Skip to content

Commit

Permalink
docs: Formatting change from HTML to markdown; Additional clarifications
Browse files Browse the repository at this point in the history 
PiperOrigin-RevId: 427761663
  • Loading branch information
Google APIs authored and Copybara-Service committed Feb 10, 2022
1 parent 14fe023 commit 46c5d65
Show file tree
Hide file tree
Showing 2 changed files with 88 additions and 76 deletions.
157 changes: 85 additions & 72 deletions google/cloud/billing/budgets/v1beta1/budget_model.proto
View file
@@ -1,4 +1,4 @@
// Copyright 2021 Google LLC
// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -46,21 +46,23 @@ message Budget {
// Validation: <= 60 chars.
string display_name = 2;

// Optional. Filters that define which resources are used to compute the
// actual spend against the budget amount, such as projects, services, and the
// budget's time period, as well as other filters.
// Optional. Filters that define which resources are used to compute the actual spend
// against the budget amount, such as projects, services, and the budget's
// time period, as well as other filters.
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 for `pubsubTopic` notifications.
//
// Required if using email notifications.
repeated ThresholdRule threshold_rules = 5 [(google.api.field_behavior) = OPTIONAL];

// Optional. Rules to apply to notifications sent based on budget spend and
// thresholds.
// Optional. Rules to apply to notifications sent based on budget spend and thresholds.
AllUpdatesRule all_updates_rule = 6 [(google.api.field_behavior) = OPTIONAL];

// Optional. Etag to validate that the object is unchanged for a
Expand All @@ -82,31 +84,45 @@ message BudgetAmount {

// Use the last period's actual spend as the budget for the present period.
// LastPeriodAmount can only be set when the budget's time period is a
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period].
// It cannot be set in combination with
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]. It cannot be set in combination with
// [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
LastPeriodAmount last_period_amount = 2;
}
}

// Describes a budget amount targeted to the last
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]
// Describes a budget amount targeted to the last [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]
// spend. At this time, the amount is automatically 100% of the last calendar
// period's spend; that is, there are no other options yet.
// Future configuration options will be described here (for example, configuring
// a percentage of last period's spend).
// LastPeriodAmount cannot be set for a budget configured with
// a
// [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
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`.
// a [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
message LastPeriodAmount {

}

// ThresholdRule contains the definition of a threshold. Threshold rules define
// the triggering events used to generate a budget notification email. When a
// threshold is crossed (spend exceeds the specified percentages of the
// budget), budget alert emails are sent to the email recipients you specify
// in the
// [NotificationsRule](#notificationsrule).
//
// Threshold rules also affect the fields included in the
// [JSON data
// object](https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification_format)
// sent to a Pub/Sub topic.
//
// Threshold rules are _required_ if using email notifications.
//
// Threshold rules are _optional_ if only setting a
// [`pubsubTopic` NotificationsRule](#NotificationsRule),
// unless you want your JSON data object to include data about the thresholds
// you set.
//
// For more information, see
// [set budget threshold rules and
// actions](https://cloud.google.com/billing/docs/how-to/budgets#budget-actions).
message ThresholdRule {
// The type of basis used to determine if spend has passed the threshold.
enum Basis {
Expand All @@ -119,8 +135,7 @@ message ThresholdRule {
// Use forecasted spend for the period as the basis for comparison against
// the threshold.
// FORECASTED_SPEND can only be set when the budget's time period is a
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period].
// It cannot be set in combination with
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]. It cannot be set in combination with
// [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
FORECASTED_SPEND = 2;
}
Expand All @@ -138,10 +153,10 @@ message ThresholdRule {
// AllUpdatesRule defines notifications that are sent based on budget spend
// and thresholds.
message AllUpdatesRule {
// 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
// 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-programmatic-notifications
// for more details.
// Caller is expected to have
Expand All @@ -151,31 +166,26 @@ message AllUpdatesRule {
// for more details on Pub/Sub roles and permissions.
string pubsub_topic = 1 [(google.api.field_behavior) = OPTIONAL];

// Optional. Required when
// [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic]
// is set. The schema version of the notification sent to
// [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic].
// Only "1.0" is accepted. It represents the JSON schema as defined in
// Optional. Required when [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic] is set. The schema version of
// the notification sent to [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.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
// 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];
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.
Expand Down Expand Up @@ -210,21 +220,18 @@ message Filter {
// Only zero or one project can be specified currently.
repeated string projects = 1 [(google.api.field_behavior) = OPTIONAL];

// Optional. If
// [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
// is INCLUDE_SPECIFIED_CREDITS, this is a list of credit types to be
// subtracted from gross cost to determine the spend for threshold
// calculations. See [a list of acceptable credit type
// Optional. If [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment] is INCLUDE_SPECIFIED_CREDITS, this is
// a list of credit types to be subtracted from gross cost to determine the
// spend for threshold calculations. See
// [a list of acceptable credit type
// values](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
//
// If
// [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
// is **not** INCLUDE_SPECIFIED_CREDITS, this field must be empty.
// If [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment] is **not** INCLUDE_SPECIFIED_CREDITS,
// this field must be empty.
repeated string credit_types = 7 [(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];
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
Expand All @@ -234,24 +241,28 @@ message Filter {
// 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,
// 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 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<string, google.protobuf.ListValue> labels = 6
[(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. If omitted, the
// report will include all labeled and unlabeled usage.
//
// An object containing a single `"key": value` pair. Example: `{ "name":
// "wrench" }`.
//
// _Currently, multiple entries or multiple values per entry are not
// allowed._
map<string, google.protobuf.ListValue> labels = 6 [(google.api.field_behavior) = OPTIONAL];

// Multiple options to choose the budget's time period, specifying that only
// usage that occurs during this time period should be included in the budget.
// If not set, the `usage_period` defaults to CalendarPeriod.MONTH.
// If not set, the <code>usage_period</code> defaults to CalendarPeriod.MONTH.
oneof usage_period {
// Optional. Specifies to track usage for recurring calendar period.
// For example, assume that CalendarPeriod.QUARTER is set. The budget will
Expand All @@ -261,8 +272,8 @@ message Filter {
// so on.
CalendarPeriod calendar_period = 8 [(google.api.field_behavior) = OPTIONAL];

// Optional. Specifies to track usage from any start date (required) to any
// end date (optional). This time period is static, it does not recur.
// Optional. Specifies to track usage from any start date (required) to any end date
// (optional). This time period is static, it does not recur.
CustomPeriod custom_period = 9 [(google.api.field_behavior) = OPTIONAL];
}
}
Expand All @@ -272,9 +283,9 @@ message CustomPeriod {
// Required. The start date must be after January 1, 2017.
google.type.Date start_date = 1 [(google.api.field_behavior) = REQUIRED];

// Optional. The end date of the time period. Budgets with elapsed end date
// won't be processed. If unset, specifies to track all usage incurred since
// the start_date.
// Optional. The end date of the time period. Budgets with elapsed end date won't be
// processed. If unset, specifies to track all usage
// incurred since the start_date.
google.type.Date end_date = 2 [(google.api.field_behavior) = OPTIONAL];
}

Expand All @@ -283,6 +294,8 @@ message CustomPeriod {
// `CalendarPeriod`". All calendar times begin at 12 AM US and Canadian
// Pacific Time (UTC-8).
enum CalendarPeriod {
// Calendar period is unset. This is the default if the budget is for a
// custom time period (CustomPeriod).
CALENDAR_PERIOD_UNSPECIFIED = 0;

// A month. Month starts on the first day of each month, such as January 1,
Expand Down
7 changes: 3 additions & 4 deletions google/cloud/billing/budgets/v1beta1/budget_service.proto
View file
@@ -1,4 +1,4 @@
// Copyright 2021 Google LLC
// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -37,7 +37,7 @@ service BudgetService {
"https://www.googleapis.com/auth/cloud-platform";

// Creates a new budget. See
// <a href="https://cloud.google.com/billing/quotas">Quotas and limits</a>
// [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) = {
Expand Down Expand Up @@ -117,8 +117,7 @@ message UpdateBudgetRequest {
// 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];
google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request for GetBudget
Expand Down

0 comments on commit 46c5d65

Please sign in to comment.