Skip to content

Commit 46c5d65

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
docs: Formatting change from HTML to markdown; Additional clarifications
PiperOrigin-RevId: 427761663
1 parent 14fe023 commit 46c5d65

2 files changed

Lines changed: 88 additions & 76 deletions

File tree

‎google/cloud/billing/budgets/v1beta1/budget_model.proto‎

Lines changed: 85 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -46,21 +46,23 @@ message Budget {
4646
// Validation: <= 60 chars.
4747
string display_name = 2;
4848

49-
// Optional. Filters that define which resources are used to compute the
50-
// actual spend against the budget amount, such as projects, services, and the
51-
// budget's time period, as well as other filters.
49+
// Optional. Filters that define which resources are used to compute the actual spend
50+
// against the budget amount, such as projects, services, and the budget's
51+
// time period, as well as other filters.
5252
Filter budget_filter = 3 [(google.api.field_behavior) = OPTIONAL];
5353

5454
// Required. Budgeted amount.
5555
BudgetAmount amount = 4 [(google.api.field_behavior) = REQUIRED];
5656

5757
// Optional. Rules that trigger alerts (notifications of thresholds
5858
// being crossed) when spend exceeds the specified percentages of the budget.
59-
repeated ThresholdRule threshold_rules = 5
60-
[(google.api.field_behavior) = OPTIONAL];
59+
//
60+
// Optional for `pubsubTopic` notifications.
61+
//
62+
// Required if using email notifications.
63+
repeated ThresholdRule threshold_rules = 5 [(google.api.field_behavior) = OPTIONAL];
6164

62-
// Optional. Rules to apply to notifications sent based on budget spend and
63-
// thresholds.
65+
// Optional. Rules to apply to notifications sent based on budget spend and thresholds.
6466
AllUpdatesRule all_updates_rule = 6 [(google.api.field_behavior) = OPTIONAL];
6567

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

8385
// Use the last period's actual spend as the budget for the present period.
8486
// LastPeriodAmount can only be set when the budget's time period is a
85-
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period].
86-
// It cannot be set in combination with
87+
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]. It cannot be set in combination with
8788
// [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
8889
LastPeriodAmount last_period_amount = 2;
8990
}
9091
}
9192

92-
// Describes a budget amount targeted to the last
93-
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]
93+
// Describes a budget amount targeted to the last [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]
9494
// spend. At this time, the amount is automatically 100% of the last calendar
9595
// period's spend; that is, there are no other options yet.
9696
// Future configuration options will be described here (for example, configuring
9797
// a percentage of last period's spend).
9898
// LastPeriodAmount cannot be set for a budget configured with
99-
// a
100-
// [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
101-
message LastPeriodAmount {}
102-
103-
// ThresholdRule contains a definition of a threshold which triggers
104-
// an alert (a notification of a threshold being crossed) to be sent when
105-
// spend goes above the specified amount.
106-
// Alerts are automatically e-mailed to users with the Billing Account
107-
// Administrator role or the Billing Account User role.
108-
// The thresholds here have no effect on notifications sent to anything
109-
// configured under `Budget.all_updates_rule`.
99+
// a [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
100+
message LastPeriodAmount {
101+
102+
}
103+
104+
// ThresholdRule contains the definition of a threshold. Threshold rules define
105+
// the triggering events used to generate a budget notification email. When a
106+
// threshold is crossed (spend exceeds the specified percentages of the
107+
// budget), budget alert emails are sent to the email recipients you specify
108+
// in the
109+
// [NotificationsRule](#notificationsrule).
110+
//
111+
// Threshold rules also affect the fields included in the
112+
// [JSON data
113+
// object](https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification_format)
114+
// sent to a Pub/Sub topic.
115+
//
116+
// Threshold rules are _required_ if using email notifications.
117+
//
118+
// Threshold rules are _optional_ if only setting a
119+
// [`pubsubTopic` NotificationsRule](#NotificationsRule),
120+
// unless you want your JSON data object to include data about the thresholds
121+
// you set.
122+
//
123+
// For more information, see
124+
// [set budget threshold rules and
125+
// actions](https://cloud.google.com/billing/docs/how-to/budgets#budget-actions).
110126
message ThresholdRule {
111127
// The type of basis used to determine if spend has passed the threshold.
112128
enum Basis {
@@ -119,8 +135,7 @@ message ThresholdRule {
119135
// Use forecasted spend for the period as the basis for comparison against
120136
// the threshold.
121137
// FORECASTED_SPEND can only be set when the budget's time period is a
122-
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period].
123-
// It cannot be set in combination with
138+
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]. It cannot be set in combination with
124139
// [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
125140
FORECASTED_SPEND = 2;
126141
}
@@ -138,10 +153,10 @@ message ThresholdRule {
138153
// AllUpdatesRule defines notifications that are sent based on budget spend
139154
// and thresholds.
140155
message AllUpdatesRule {
141-
// Optional. The name of the Pub/Sub topic where budget related messages will
142-
// be published, in the form `projects/{project_id}/topics/{topic_id}`.
143-
// Updates are sent at regular intervals to the topic. The topic needs to be
144-
// created before the budget is created; see
156+
// Optional. The name of the Pub/Sub topic where budget related messages will be
157+
// published, in the form `projects/{project_id}/topics/{topic_id}`. Updates
158+
// are sent at regular intervals to the topic.
159+
// The topic needs to be created before the budget is created; see
145160
// https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications
146161
// for more details.
147162
// Caller is expected to have
@@ -151,31 +166,26 @@ message AllUpdatesRule {
151166
// for more details on Pub/Sub roles and permissions.
152167
string pubsub_topic = 1 [(google.api.field_behavior) = OPTIONAL];
153168

154-
// Optional. Required when
155-
// [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic]
156-
// is set. The schema version of the notification sent to
157-
// [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic].
158-
// Only "1.0" is accepted. It represents the JSON schema as defined in
169+
// Optional. Required when [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic] is set. The schema version of
170+
// the notification sent to [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic]. Only "1.0" is
171+
// accepted. It represents the JSON schema as defined in
159172
// https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification_format.
160173
string schema_version = 2 [(google.api.field_behavior) = OPTIONAL];
161174

162-
// Optional. Targets to send notifications to when a threshold is exceeded.
163-
// This is in addition to default recipients who have billing account IAM
164-
// roles. The value is the full REST resource name of a monitoring
165-
// notification channel with the form
175+
// Optional. Targets to send notifications to when a threshold is exceeded. This is in
176+
// addition to default recipients who have billing account IAM roles.
177+
// The value is the full REST resource name of a monitoring notification
178+
// channel with the form
166179
// `projects/{project_id}/notificationChannels/{channel_id}`. A maximum of 5
167180
// channels are allowed. See
168181
// https://cloud.google.com/billing/docs/how-to/budgets-notification-recipients
169182
// for more details.
170-
repeated string monitoring_notification_channels = 3
171-
[(google.api.field_behavior) = OPTIONAL];
172-
173-
// Optional. When set to true, disables default notifications sent when a
174-
// threshold is exceeded. Default notifications are sent to those with Billing
175-
// Account Administrator and Billing Account User IAM roles for the target
176-
// account.
177-
bool disable_default_iam_recipients = 4
178-
[(google.api.field_behavior) = OPTIONAL];
183+
repeated string monitoring_notification_channels = 3 [(google.api.field_behavior) = OPTIONAL];
184+
185+
// Optional. When set to true, disables default notifications sent when a threshold is
186+
// exceeded. Default notifications are sent to those with Billing Account
187+
// Administrator and Billing Account User IAM roles for the target account.
188+
bool disable_default_iam_recipients = 4 [(google.api.field_behavior) = OPTIONAL];
179189
}
180190

181191
// A filter for a budget, limiting the scope of the cost to calculate.
@@ -210,21 +220,18 @@ message Filter {
210220
// Only zero or one project can be specified currently.
211221
repeated string projects = 1 [(google.api.field_behavior) = OPTIONAL];
212222

213-
// Optional. If
214-
// [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
215-
// is INCLUDE_SPECIFIED_CREDITS, this is a list of credit types to be
216-
// subtracted from gross cost to determine the spend for threshold
217-
// calculations. See [a list of acceptable credit type
223+
// Optional. If [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment] is INCLUDE_SPECIFIED_CREDITS, this is
224+
// a list of credit types to be subtracted from gross cost to determine the
225+
// spend for threshold calculations. See
226+
// [a list of acceptable credit type
218227
// values](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
219228
//
220-
// If
221-
// [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
222-
// is **not** INCLUDE_SPECIFIED_CREDITS, this field must be empty.
229+
// If [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment] is **not** INCLUDE_SPECIFIED_CREDITS,
230+
// this field must be empty.
223231
repeated string credit_types = 7 [(google.api.field_behavior) = OPTIONAL];
224232

225233
// Optional. If not set, default behavior is `INCLUDE_ALL_CREDITS`.
226-
CreditTypesTreatment credit_types_treatment = 4
227-
[(google.api.field_behavior) = OPTIONAL];
234+
CreditTypesTreatment credit_types_treatment = 4 [(google.api.field_behavior) = OPTIONAL];
228235

229236
// Optional. A set of services of the form `services/{service_id}`,
230237
// specifying that usage from only this set of services should be
@@ -234,24 +241,28 @@ message Filter {
234241
// https://cloud.google.com/billing/v1/how-tos/catalog-api.
235242
repeated string services = 3 [(google.api.field_behavior) = OPTIONAL];
236243

237-
// Optional. A set of subaccounts of the form `billingAccounts/{account_id}`,
238-
// specifying that usage from only this set of subaccounts should be included
239-
// in the budget. If a subaccount is set to the name of the parent account,
244+
// Optional. A set of subaccounts of the form `billingAccounts/{account_id}`, specifying
245+
// that usage from only this set of subaccounts should be included in the
246+
// budget. If a subaccount is set to the name of the parent account,
240247
// usage from the parent account will be included. If omitted, the
241248
// report will include usage from the parent account and all
242249
// subaccounts, if they exist.
243250
repeated string subaccounts = 5 [(google.api.field_behavior) = OPTIONAL];
244251

245-
// Optional. A single label and value pair specifying that usage from only
246-
// this set of labeled resources should be included in the budget. Currently,
247-
// multiple entries or multiple values per entry are not allowed. If omitted,
248-
// the report will include all labeled and unlabeled usage.
249-
map<string, google.protobuf.ListValue> labels = 6
250-
[(google.api.field_behavior) = OPTIONAL];
252+
// Optional. A single label and value pair specifying that usage from only this set of
253+
// labeled resources should be included in the budget. If omitted, the
254+
// report will include all labeled and unlabeled usage.
255+
//
256+
// An object containing a single `"key": value` pair. Example: `{ "name":
257+
// "wrench" }`.
258+
//
259+
// _Currently, multiple entries or multiple values per entry are not
260+
// allowed._
261+
map<string, google.protobuf.ListValue> labels = 6 [(google.api.field_behavior) = OPTIONAL];
251262

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

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

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

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

288301
// A month. Month starts on the first day of each month, such as January 1,

‎google/cloud/billing/budgets/v1beta1/budget_service.proto‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2021 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -37,7 +37,7 @@ service BudgetService {
3737
"https://www.googleapis.com/auth/cloud-platform";
3838

3939
// Creates a new budget. See
40-
// <a href="https://cloud.google.com/billing/quotas">Quotas and limits</a>
40+
// [Quotas and limits](https://cloud.google.com/billing/quotas)
4141
// for more information on the limits of the number of budgets you can create.
4242
rpc CreateBudget(CreateBudgetRequest) returns (Budget) {
4343
option (google.api.http) = {
@@ -117,8 +117,7 @@ message UpdateBudgetRequest {
117117
// updated. See
118118
// https://developers.google.com/protocol-buffers/docs/proto3#default for more
119119
// details about default values.
120-
google.protobuf.FieldMask update_mask = 2
121-
[(google.api.field_behavior) = OPTIONAL];
120+
google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = OPTIONAL];
122121
}
123122

124123
// Request for GetBudget

0 commit comments

Comments
 (0)