diff --git a/google/cloud/billing/budgets/artman_billingbudgets_v1beta1.yaml b/google/cloud/billing/budgets/artman_billingbudgets_v1beta1.yaml new file mode 100644 index 0000000000..fc786be65b --- /dev/null +++ b/google/cloud/billing/budgets/artman_billingbudgets_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: billingbudgets + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: billingbudgets.yaml + gapic_yaml: v1beta1/billingbudgets_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/billing/budgets/billingbudgets.yaml b/google/cloud/billing/budgets/billingbudgets.yaml new file mode 100644 index 0000000000..bdef1bff9a --- /dev/null +++ b/google/cloud/billing/budgets/billingbudgets.yaml @@ -0,0 +1,14 @@ +type: google.api.Service +config_version: 3 +name: billingbudgets.googleapis.com +title: Cloud Billing Budget API + +apis: +- name: google.cloud.billing.budgets.v1beta1.BudgetService + +authentication: + rules: + - selector: 'google.cloud.billing.budgets.v1beta1.BudgetService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/billing/budgets/v1beta1/billingbudgets_gapic.yaml b/google/cloud/billing/budgets/v1beta1/billingbudgets_gapic.yaml new file mode 100644 index 0000000000..7f20c8fe46 --- /dev/null +++ b/google/cloud/billing/budgets/v1beta1/billingbudgets_gapic.yaml @@ -0,0 +1,57 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 2.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.billing.budgets.v1beta1 +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.billing.budgets.v1beta1.BudgetService + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: CreateBudget + retry_codes_name: non_idempotent + retry_params_name: default + - name: UpdateBudget + retry_codes_name: idempotent + retry_params_name: default + - name: GetBudget + retry_codes_name: idempotent + retry_params_name: default + - name: ListBudgets + retry_codes_name: idempotent + retry_params_name: default + - name: DeleteBudget + retry_codes_name: idempotent + retry_params_name: default diff --git a/google/cloud/billing/budgets/v1beta1/budget_model.proto b/google/cloud/billing/budgets/v1beta1/budget_model.proto new file mode 100644 index 0000000000..0271958bc3 --- /dev/null +++ b/google/cloud/billing/budgets/v1beta1/budget_model.proto @@ -0,0 +1,174 @@ +// Copyright 2019 Google LLC. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +syntax = "proto3"; + +package google.cloud.billing.budgets.v1beta1; + +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/type/money.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/billing/budgets/v1beta1;budgets"; +option java_multiple_files = true; +option java_package = "com.google.cloud.billing.budgets.v1beta1"; + +// A budget is a plan that describes what the user expects to spend on Cloud +// projects, plus rules to execute as spend is tracked against that plan, +// e.g. alert at 90% of $100 target. +// Currently all plans are monthly budgets so the usage period(s) tracked are +// implied (calendar months of usage back-to-back). +message Budget { + option (google.api.resource) = { + type: "billingbudgets.googleapis.com/Budget" + pattern: "billingAccounts/{billing_account}/budgets/{budget}" + }; + + // Output only. Resource name of the budget. + // The resource name implies the scope of a budget. Values are of the form + // `billingAccounts/{billingAccountId}/budgets/{budgetId}`. + string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // User data for display name in UI. + // Validation: <= 60 chars. + string display_name = 2; + + // Optional. Filters that define which resources are used to compute + // the actual spend against the budget. + Filter budget_filter = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Required. Budgeted amount. + BudgetAmount amount = 4 [(google.api.field_behavior) = REQUIRED]; + + // Required. Rules that trigger alerts (notifications of thresholds + // being crossed) when spend exceeds the specified percentages of the budget. + repeated ThresholdRule threshold_rules = 5 [(google.api.field_behavior) = REQUIRED]; + + // Optional. Rules to apply to all updates to the actual spend, regardless + // of the thresholds set in `threshold_rules`. + AllUpdatesRule all_updates_rule = 6 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Etag to validate that the object is unchanged for a + // read-modify-write operation. + // An empty etag will cause an update to overwrite other changes. + string etag = 7 [(google.api.field_behavior) = OPTIONAL]; +} + +// The budgeted amount for each usage period. +message BudgetAmount { + // Specification for what amount to use as the budget. + oneof budget_amount { + // A specified amount to use as the budget. + // `currency_code` is optional. If specified, it must match the + // currency of the billing account. The `currency_code` is provided on + // output. + google.type.Money specified_amount = 1; + + // Use the last period's actual spend as the budget for the present period. + LastPeriodAmount last_period_amount = 2; + } +} + +// Describes a plan to target last period's spend. +// There are no options yet. The amount is automatically 100% of last period's +// spend. +// Future configuration will go here (e.g. configuring the percentage). +message LastPeriodAmount { + +} + +// ThresholdRule contains a definition of a threshold which triggers +// an alert (a notification of a threshold being crossed) to be sent when +// spend goes above the specified amount. +// Alerts are automatically e-mailed to the billing users who have +// access to the billing account. The thresholds here have no effect on +// notifications sent to anything configured under `Budget.all_updates_rule`. +message ThresholdRule { + // The type of basis used to determine if spend has passed the threshold. + enum Basis { + // Unspecified threshold basis. + BASIS_UNSPECIFIED = 0; + + // Use current spend as the basis for comparison against the threshold. + CURRENT_SPEND = 1; + + // Use forecasted spend for the period as the basis for comparison against + // the threshold. + FORECASTED_SPEND = 2; + } + + // Required. Send an alert when this threshold is exceeded. + // This is a 1.0-based percentage, so 0.5 = 50%. + // Validation: non-negative number. + double threshold_percent = 1 [(google.api.field_behavior) = REQUIRED]; + + // Optional. The type of basis used to determine if spend has passed the + // threshold. Behavior defaults to CURRENT_SPEND if not set. + Basis spend_basis = 2 [(google.api.field_behavior) = OPTIONAL]; +} + +// AllUpdatesRule defines notifications that are sent on every update to the +// billing account's spend, regardless of the thresholds defined using +// threshold rules. +message AllUpdatesRule { + // Required. The name of Cloud Pub/Sub topic that budget related messages are + // published to. Updates are sent at regular intervals to the topic. + // This value of the form + // `projects/{project_id}/topics/{topic_id}` can be used as IAM resource name + // and to call services defined in google/pubsub/v1/pubsub.proto. On + // creation of a budget, the topic must be owned by the user, and + // Google must be granted publishing permissions on it. + string pubsub_topic = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The schema version of the notification. + // Only "1.0" is accepted. It represents the JSON schema as defined in + // https://cloud.google.com/billing/docs/how-to/budgets#notification_format + string schema_version = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// A filter for a budget, limiting the scope of the cost to calculate. +message Filter { + // Specifies how credits should be treated when determining spend for + // threshold calculations. + enum CreditTypesTreatment { + CREDIT_TYPES_TREATMENT_UNSPECIFIED = 0; + + // All types of credit are subtracted from the gross cost to determine the + // spend for threshold calculations. + INCLUDE_ALL_CREDITS = 1; + + // All types of credit are added to the net cost to determine the spend for + // threshold calculations. + EXCLUDE_ALL_CREDITS = 2; + } + + // Optional. A set of projects of the form `projects/{project_id}`, + // specifying that usage from only this set of projects should be + // included in the budget. If omitted, the report will include all usage for + // the billing account, regardless of which project the usage occurred on. + // Only zero or one project can be specified currently. + repeated string projects = 1 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If not set, default behavior is `INCLUDE_ALL_CREDITS`. + CreditTypesTreatment credit_types_treatment = 4 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. A set of services of the form `services/{service_id}`, + // specifying that usage from only this set of services should be + // included in the budget. If omitted, the report will include usage for + // all the services. + // The service names are available through the Catalog API: + // https://cloud.google.com/billing/v1/how-tos/catalog-api. + repeated string services = 3 [(google.api.field_behavior) = OPTIONAL]; +} diff --git a/google/cloud/billing/budgets/v1beta1/budget_service.proto b/google/cloud/billing/budgets/v1beta1/budget_service.proto new file mode 100644 index 0000000000..6c7f3559bc --- /dev/null +++ b/google/cloud/billing/budgets/v1beta1/budget_service.proto @@ -0,0 +1,160 @@ +// Copyright 2019 Google LLC. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +syntax = "proto3"; + +package google.cloud.billing.budgets.v1beta1; + +import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/cloud/billing/budgets/v1beta1/budget_model.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/billing/budgets/v1beta1;budgets"; +option java_multiple_files = true; +option java_package = "com.google.cloud.billing.budgets.v1beta1"; + +// BudgetService stores Cloud Billing budgets, which define a +// budget plan and rules to execute as we track spend against that plan. +service BudgetService { + option (google.api.default_host) = "billingbudgets.googleapis.com"; + option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform"; + + // Creates a new budget if none exists. There is a limit of 1,000 budgets + // per billing account. + rpc CreateBudget(CreateBudgetRequest) returns (Budget) { + option (google.api.http) = { + post: "/v1beta1/{parent=billingAccounts/*}/budgets" + body: "*" + }; + } + + // Updates a budget and returns the updated budget. + rpc UpdateBudget(UpdateBudgetRequest) returns (Budget) { + option (google.api.http) = { + patch: "/v1beta1/{budget.name=billingAccounts/*/budgets/*}" + body: "*" + }; + } + + // Returns a budget. + rpc GetBudget(GetBudgetRequest) returns (Budget) { + option (google.api.http) = { + get: "/v1beta1/{name=billingAccounts/*/budgets/*}" + }; + } + + // Returns the budgets for a billing account. + rpc ListBudgets(ListBudgetsRequest) returns (ListBudgetsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=billingAccounts/*}/budgets" + }; + } + + // Deletes a budget. Returns successfully if already deleted. + rpc DeleteBudget(DeleteBudgetRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=billingAccounts/*/budgets/*}" + }; + } +} + +// Request for CreateBudget +message CreateBudgetRequest { + // Required. the name of the billing account to create the budget in. Values + // are of the form `billingAccounts/{billingAccountId}`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + child_type: "billingbudgets.googleapis.com/Budget" + } + ]; + + // Required. Budget to create. + Budget budget = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// Request for UpdateBudget +message UpdateBudgetRequest { + // Required. The updated budget object. + // The budget to update is specified by the budget name in the budget. + Budget budget = 1 [(google.api.field_behavior) = REQUIRED]; + + // Optional. Indicates which fields in the provided budget to update. + // Read-only fields (such as `name`) cannot be changed. If this is not + // provided, then only fields with non-default values from the request are + // updated. See + // https://developers.google.com/protocol-buffers/docs/proto3#default for more + // details about default values. + google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = OPTIONAL]; +} + +// Request for GetBudget +message GetBudgetRequest { + // Required. Name of budget to get. Values are of the form + // `billingAccounts/{billingAccountId}/budgets/{budgetId}`. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "billingbudgets.googleapis.com/Budget" + } + ]; +} + +// Request for ListBudgets +message ListBudgetsRequest { + // Required. Name of billing account to list budgets under. Values + // are of the form `billingAccounts/{billingAccountId}`. + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + child_type: "billingbudgets.googleapis.com/Budget" + } + ]; + + // Optional. The maximum number of budgets to return per page. + // The default and maximum value are 100. + int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The value returned by the last `ListBudgetsResponse` which + // indicates that this is a continuation of a prior `ListBudgets` call, + // and that the system should return the next page of data. + string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; +} + +// Response for ListBudgets +message ListBudgetsResponse { + // List of the budgets owned by the requested billing account. + repeated Budget budgets = 1; + + // If not empty, indicates that there may be more budgets that match the + // request; this value should be passed in a new `ListBudgetsRequest`. + string next_page_token = 2; +} + +// Request for DeleteBudget +message DeleteBudgetRequest { + // Required. Name of the budget to delete. Values are of the form + // `billingAccounts/{billingAccountId}/budgets/{budgetId}`. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "billingbudgets.googleapis.com/Budget" + } + ]; +}