From dec8fd8ea5dc464496606189ba4b8949188639c8 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 13 Nov 2019 10:20:57 -0800 Subject: [PATCH] Updating Cloud Billing Budget API documentation for clarity. PiperOrigin-RevId: 280225437 --- .../budgets/v1beta1/billingbudgets.yaml | 6 ++++ .../budgets/v1beta1/budget_model.proto | 28 +++++++++++-------- .../budgets/v1beta1/budget_service.proto | 9 +++--- 3 files changed, 28 insertions(+), 15 deletions(-) diff --git a/google/cloud/billing/budgets/v1beta1/billingbudgets.yaml b/google/cloud/billing/budgets/v1beta1/billingbudgets.yaml index bdef1bff..01ae424d 100644 --- a/google/cloud/billing/budgets/v1beta1/billingbudgets.yaml +++ b/google/cloud/billing/budgets/v1beta1/billingbudgets.yaml @@ -6,6 +6,12 @@ title: Cloud Billing Budget API apis: - name: google.cloud.billing.budgets.v1beta1.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.v1beta1.BudgetService.*' diff --git a/google/cloud/billing/budgets/v1beta1/budget_model.proto b/google/cloud/billing/budgets/v1beta1/budget_model.proto index e7d5ca2b..89e96bea 100644 --- a/google/cloud/billing/budgets/v1beta1/budget_model.proto +++ b/google/cloud/billing/budgets/v1beta1/budget_model.proto @@ -25,9 +25,9 @@ option go_package = "google.golang.org/genproto/googleapis/cloud/billing/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. +// 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 { @@ -81,10 +81,11 @@ message BudgetAmount { } } -// 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). +// 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 { } @@ -92,9 +93,10 @@ 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`. +// 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 { @@ -125,7 +127,11 @@ message ThresholdRule { message AllUpdatesRule { // Required. The name of the Cloud 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. Caller is expected to have + // 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/pubsub/docs/access-control for more details on diff --git a/google/cloud/billing/budgets/v1beta1/budget_service.proto b/google/cloud/billing/budgets/v1beta1/budget_service.proto index 6c7f3559..d5e0f4bc 100644 --- a/google/cloud/billing/budgets/v1beta1/budget_service.proto +++ b/google/cloud/billing/budgets/v1beta1/budget_service.proto @@ -35,8 +35,9 @@ 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. + // Creates a new budget. See + // Quotas and limits + // for more information on the limits of the number of budgets you can create. rpc CreateBudget(CreateBudgetRequest) returns (Budget) { option (google.api.http) = { post: "/v1beta1/{parent=billingAccounts/*}/budgets" @@ -59,7 +60,7 @@ service BudgetService { }; } - // Returns the budgets for a billing account. + // Returns a list of budgets for a billing account. rpc ListBudgets(ListBudgetsRequest) returns (ListBudgetsResponse) { option (google.api.http) = { get: "/v1beta1/{parent=billingAccounts/*}/budgets" @@ -76,7 +77,7 @@ service BudgetService { // Request for CreateBudget message CreateBudgetRequest { - // Required. the name of the billing account to create the budget in. Values + // 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,