From cc0c4e7790fc57b3e720dfdd97b71ff85c85c911 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Mon, 5 Oct 2020 12:29:56 -0700 Subject: [PATCH] feat: add v1 Cloud Billing Budgets API PiperOrigin-RevId: 335474297 --- google/cloud/billing/budgets/v1/BUILD.bazel | 178 +++++++++++++++ .../billing/budgets/v1/billingbudgets.yaml | 21 ++ .../billingbudgets_grpc_service_config.json | 44 ++++ .../billing/budgets/v1/budget_model.proto | 209 ++++++++++++++++++ .../billing/budgets/v1/budget_service.proto | 182 +++++++++++++++ 5 files changed, 634 insertions(+) create mode 100644 google/cloud/billing/budgets/v1/BUILD.bazel create mode 100644 google/cloud/billing/budgets/v1/billingbudgets.yaml create mode 100644 google/cloud/billing/budgets/v1/billingbudgets_grpc_service_config.json create mode 100644 google/cloud/billing/budgets/v1/budget_model.proto create mode 100644 google/cloud/billing/budgets/v1/budget_service.proto diff --git a/google/cloud/billing/budgets/v1/BUILD.bazel b/google/cloud/billing/budgets/v1/BUILD.bazel new file mode 100644 index 00000000..ed2c1a68 --- /dev/null +++ b/google/cloud/billing/budgets/v1/BUILD.bazel @@ -0,0 +1,178 @@ +# This file was automatically generated by BuildFileGenerator + +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@rules_proto//proto:defs.bzl", "proto_library") + +proto_library( + name = "budgets_proto", + srcs = [ + "budget_model.proto", + "budget_service.proto", + ], + deps = [ + "//google/api:annotations_proto", + "//google/api:client_proto", + "//google/api:field_behavior_proto", + "//google/api:resource_proto", + "//google/type:money_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:struct_proto", + ], +) + +############################################################################## +# Java +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "java_grpc_library", + "java_proto_library", +) + +java_proto_library( + name = "budgets_java_proto", + deps = [":budgets_proto"], +) + +java_grpc_library( + name = "budgets_java_grpc", + srcs = [":budgets_proto"], + deps = [":budgets_java_proto"], +) + +############################################################################## +# Go +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "go_proto_library", +) + +go_proto_library( + name = "budgets_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/billing/budgets/v1", + protos = [":budgets_proto"], + deps = [ + "//google/api:annotations_go_proto", + "//google/type:money_go_proto", + ], +) + +############################################################################## +# Python +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "moved_proto_library", + "py_grpc_library", + "py_proto_library", +) + +moved_proto_library( + name = "budgets_moved_proto", + srcs = [":budgets_proto"], + deps = [ + "//google/api:annotations_proto", + "//google/api:client_proto", + "//google/api:field_behavior_proto", + "//google/api:resource_proto", + "//google/type:money_proto", + "@com_google_protobuf//:empty_proto", + "@com_google_protobuf//:field_mask_proto", + "@com_google_protobuf//:struct_proto", + ], +) + +py_proto_library( + name = "budgets_py_proto", + plugin = "@protoc_docs_plugin//:docs_plugin", + deps = [":budgets_moved_proto"], +) + +py_grpc_library( + name = "budgets_py_grpc", + srcs = [":budgets_moved_proto"], + deps = [":budgets_py_proto"], +) + +############################################################################## +# PHP +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "php_grpc_library", + "php_proto_library", +) + +php_proto_library( + name = "budgets_php_proto", + deps = [":budgets_proto"], +) + +php_grpc_library( + name = "budgets_php_grpc", + srcs = [":budgets_proto"], + deps = [":budgets_php_proto"], +) + +############################################################################## +# Node.js +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "nodejs_gapic_assembly_pkg", + "nodejs_gapic_library", +) + + +############################################################################## +# Ruby +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "ruby_grpc_library", + "ruby_proto_library", +) + +ruby_proto_library( + name = "budgets_ruby_proto", + deps = [":budgets_proto"], +) + +ruby_grpc_library( + name = "budgets_ruby_grpc", + srcs = [":budgets_proto"], + deps = [":budgets_ruby_proto"], +) + +############################################################################## +# C# +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "csharp_grpc_library", + "csharp_proto_library", +) + +csharp_proto_library( + name = "budgets_csharp_proto", + deps = [":budgets_proto"], +) + +csharp_grpc_library( + name = "budgets_csharp_grpc", + srcs = [":budgets_proto"], + deps = [":budgets_csharp_proto"], +) + +############################################################################## +# C++ +############################################################################## +# Put your C++ code here diff --git a/google/cloud/billing/budgets/v1/billingbudgets.yaml b/google/cloud/billing/budgets/v1/billingbudgets.yaml new file mode 100644 index 00000000..ab4a0776 --- /dev/null +++ b/google/cloud/billing/budgets/v1/billingbudgets.yaml @@ -0,0 +1,21 @@ +type: google.api.Service +config_version: 3 +name: billingbudgets.googleapis.com +title: Cloud Billing Budget API + +apis: +- name: google.cloud.billing.budgets.v1.BudgetService + +documentation: + summary: |- + The Cloud Billing Budget API stores Cloud Billing budgets, which define a + budget plan and the rules to execute as spend is tracked against that + plan. + +authentication: + rules: + - selector: 'google.cloud.billing.budgets.v1.BudgetService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-billing, + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/billing/budgets/v1/billingbudgets_grpc_service_config.json b/google/cloud/billing/budgets/v1/billingbudgets_grpc_service_config.json new file mode 100644 index 00000000..27b57fe4 --- /dev/null +++ b/google/cloud/billing/budgets/v1/billingbudgets_grpc_service_config.json @@ -0,0 +1,44 @@ +{ + "methodConfig": [ + { + "name": [ + { + "service": "google.cloud.billing.budgets.v1.BudgetService", + "method": "CreateBudget" + } + ], + "timeout": "60s" + }, + { + "name": [ + { + "service": "google.cloud.billing.budgets.v1.BudgetService", + "method": "UpdateBudget" + }, + { + "service": "google.cloud.billing.budgets.v1.BudgetService", + "method": "GetBudget" + }, + { + "service": "google.cloud.billing.budgets.v1.BudgetService", + "method": "ListBudgets" + }, + { + "service": "google.cloud.billing.budgets.v1.BudgetService", + "method": "DeleteBudget" + } + ], + "timeout": "60s", + "retryPolicy": { + "maxAttempts": 5, + "initialBackoff": "0.100s", + "maxBackoff": "60s", + "backoffMultiplier": 1.3, + "retryableStatusCodes": [ + "DEADLINE_EXCEEDED", + "UNAVAILABLE" + ] + } + } + ] +} diff --git a/google/cloud/billing/budgets/v1/budget_model.proto b/google/cloud/billing/budgets/v1/budget_model.proto new file mode 100644 index 00000000..693538c1 --- /dev/null +++ b/google/cloud/billing/budgets/v1/budget_model.proto @@ -0,0 +1,209 @@ +// Copyright 2020 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.v1; + +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/protobuf/struct.proto"; +import "google/type/money.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/billing/budgets/v1;budgets"; +option java_multiple_files = true; +option java_outer_classname = "BudgetModelProto"; +option java_package = "com.google.cloud.billing.budgets.v1"; + +// A budget is a plan that describes what you expect to spend on Cloud +// projects, plus the rules to execute as spend is tracked against that plan, +// (for example, send an alert when 90% of the target spend is met). +// 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. The name must be less than or equal to 60 + // characters. + 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]; + + // Optional. 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) = OPTIONAL]; + + // Optional. Rules to apply to notifications sent based on budget spend and thresholds. + NotificationsRule notifications_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 budget amount targeted to last period's spend. +// At this time, the amount is automatically 100% of last period's spend; +// that is, there are no other options yet. +// Future configuration will be described here (for example, configuring a +// percentage of last period's spend). +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 users with the Billing Account +// Administrator role or the Billing Account User role. +// 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]; +} + +// NotificationsRule defines notifications that are sent based on budget spend +// and thresholds. +message NotificationsRule { + // Optional. The name of the Pub/Sub topic where budget related messages will be + // published, in the form `projects/{project_id}/topics/{topic_id}`. Updates + // are sent at regular intervals to the topic. + // The topic needs to be created before the budget is created; see + // https://cloud.google.com/billing/docs/how-to/budgets#manage-notifications + // for more details. + // Caller is expected to have + // `pubsub.topics.setIamPolicy` permission on the topic when it's set for a + // budget, otherwise, the API call will fail with PERMISSION_DENIED. See + // https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications + // for more details on Pub/Sub roles and permissions. + string pubsub_topic = 1 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The schema version of the notification sent to `pubsub_topic`. + // Only "1.0" is accepted. It represents the JSON schema as defined in + // https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification_format + string schema_version = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Targets to send notifications to when a threshold is exceeded. This is in + // addition to default recipients who have billing account IAM roles. + // The value is the full REST resource name of a monitoring notification + // channel with the form + // `projects/{project_id}/notificationChannels/{channel_id}`. A maximum of 5 + // channels are allowed. See + // https://cloud.google.com/billing/docs/how-to/budgets-notification-recipients + // for more details. + repeated string monitoring_notification_channels = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. When set to true, disables default notifications sent when a threshold is + // exceeded. Default notifications are sent to those with Billing Account + // Administrator and Billing Account User IAM roles for the target account. + bool disable_default_iam_recipients = 4 [(google.api.field_behavior) = OPTIONAL]; +} + +// 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 { + // This is an invalid value. + 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}`, + // 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]; + + // Optional. A set of subaccounts of the form `billingAccounts/{account_id}`, specifying + // that usage from only this set of subaccounts should be included in the + // budget. If a subaccount is set to the name of the parent account, + // usage from the parent account will be included. If the field is omitted, + // the report will include usage from the parent account and all subaccounts, + // if they exist. + repeated string subaccounts = 5 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. A single label and value pair specifying that usage from only this set of + // labeled resources should be included in the budget. Currently, multiple + // entries or multiple values per entry are not allowed. If omitted, the + // report will include all labeled and unlabeled usage. + map labels = 6 [(google.api.field_behavior) = OPTIONAL]; +} diff --git a/google/cloud/billing/budgets/v1/budget_service.proto b/google/cloud/billing/budgets/v1/budget_service.proto new file mode 100644 index 00000000..bb2be219 --- /dev/null +++ b/google/cloud/billing/budgets/v1/budget_service.proto @@ -0,0 +1,182 @@ +// Copyright 2020 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.v1; + +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/v1/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/v1;budgets"; +option java_multiple_files = true; +option java_outer_classname = "BudgetServiceProto"; +option java_package = "com.google.cloud.billing.budgets.v1"; + +// 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-billing," + "https://www.googleapis.com/auth/cloud-platform"; + + // Creates a new budget. See + // [Quotas and limits](https://cloud.google.com/billing/quotas) + // for more information on the limits of the number of budgets you can create. + rpc CreateBudget(CreateBudgetRequest) returns (Budget) { + option (google.api.http) = { + post: "/v1/{parent=billingAccounts/*}/budgets" + body: "budget" + }; + option (google.api.method_signature) = "parent,budget"; + } + + // Updates a budget and returns the updated budget. + // + // WARNING: There are some fields exposed on the Google Cloud Console that + // aren't available on this API. Budget fields that are not exposed in + // this API will not be changed by this method. + rpc UpdateBudget(UpdateBudgetRequest) returns (Budget) { + option (google.api.http) = { + patch: "/v1/{budget.name=billingAccounts/*/budgets/*}" + body: "budget" + }; + option (google.api.method_signature) = "budget,update_mask"; + } + + // Returns a budget. + // + // WARNING: There are some fields exposed on the Google Cloud Console that + // aren't available on this API. When reading from the API, you will not + // see these fields in the return value, though they may have been set + // in the Cloud Console. + rpc GetBudget(GetBudgetRequest) returns (Budget) { + option (google.api.http) = { + get: "/v1/{name=billingAccounts/*/budgets/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Returns a list of budgets for a billing account. + // + // WARNING: There are some fields exposed on the Google Cloud Console that + // aren't available on this API. When reading from the API, you will not + // see these fields in the return value, though they may have been set + // in the Cloud Console. + rpc ListBudgets(ListBudgetsRequest) returns (ListBudgetsResponse) { + option (google.api.http) = { + get: "/v1/{parent=billingAccounts/*}/budgets" + }; + option (google.api.method_signature) = "parent"; + } + + // Deletes a budget. Returns successfully if already deleted. + rpc DeleteBudget(DeleteBudgetRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1/{name=billingAccounts/*/budgets/*}" + }; + option (google.api.method_signature) = "name"; + } +} + +// 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" + } + ]; +}