Skip to content

Commit 24f0828

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Added support for configurable budget time period.
fix: Updated some documentation links. PiperOrigin-RevId: 368871882
1 parent b1c23ed commit 24f0828

2 files changed

Lines changed: 93 additions & 23 deletions

File tree

‎google/cloud/billing/budgets/v1beta1/BUILD.bazel‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# This file was automatically generated by BuildFileGenerator
2-
# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel
2+
# https://github.com/googleapis/rules_gapic/tree/master/bazel
33

44
# Most of the manual changes to this file will be overwritten.
55
# It's **only** allowed to change the following rule attribute values:
@@ -29,6 +29,7 @@ proto_library(
2929
"//google/api:client_proto",
3030
"//google/api:field_behavior_proto",
3131
"//google/api:resource_proto",
32+
"//google/type:date_proto",
3233
"//google/type:money_proto",
3334
"@com_google_protobuf//:empty_proto",
3435
"@com_google_protobuf//:field_mask_proto",
@@ -82,6 +83,7 @@ java_gapic_library(
8283
java_gapic_test(
8384
name = "budgets_java_gapic_test_suite",
8485
test_classes = [
86+
"com.google.cloud.billing.budgets.v1beta1.BudgetServiceClientTest",
8587
],
8688
runtime_deps = [":budgets_java_gapic_test"],
8789
)
@@ -115,6 +117,7 @@ go_proto_library(
115117
protos = [":budgets_proto"],
116118
deps = [
117119
"//google/api:annotations_go_proto",
120+
"//google/type:date_go_proto",
118121
"//google/type:money_go_proto",
119122
],
120123
)
@@ -124,6 +127,7 @@ go_gapic_library(
124127
srcs = [":budgets_proto_with_info"],
125128
grpc_service_config = "billingbudgets_grpc_service_config.json",
126129
importpath = "cloud.google.com/go/billing/budgets/apiv1beta1;budgets",
130+
metadata = True,
127131
service_yaml = "billingbudgets.yaml",
128132
deps = [
129133
":budgets_go_proto",
@@ -142,6 +146,7 @@ go_gapic_assembly_pkg(
142146
name = "gapi-cloud-billing-budgets-v1beta1-go",
143147
deps = [
144148
":budgets_go_gapic",
149+
":budgets_go_gapic_srcjar-metadata.srcjar",
145150
":budgets_go_gapic_srcjar-test.srcjar",
146151
":budgets_go_proto",
147152
],
@@ -267,11 +272,11 @@ ruby_cloud_gapic_library(
267272
name = "budgets_ruby_gapic",
268273
srcs = [":budgets_proto_with_info"],
269274
extra_protoc_parameters = [
270-
"ruby-cloud-gem-name=google-cloud-billing-budgets-v1beta1",
271-
"ruby-cloud-env-prefix=BILLING_BUDGETS",
272-
"ruby-cloud-product-url=https://cloud.google.com/billing/docs/how-to/budget-api-overview",
273275
"ruby-cloud-api-id=billingbudgets.googleapis.com",
274276
"ruby-cloud-api-shortname=billingbudgets",
277+
"ruby-cloud-env-prefix=BILLING_BUDGETS",
278+
"ruby-cloud-gem-name=google-cloud-billing-budgets-v1beta1",
279+
"ruby-cloud-product-url=https://cloud.google.com/billing/docs/how-to/budget-api-overview",
275280
],
276281
grpc_service_config = "billingbudgets_grpc_service_config.json",
277282
ruby_cloud_description = "Provides methods to view, create, and manage Cloud Billing budgets programmatically at scale.",

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

Lines changed: 84 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ package google.cloud.billing.budgets.v1beta1;
1919
import "google/api/field_behavior.proto";
2020
import "google/api/resource.proto";
2121
import "google/protobuf/struct.proto";
22+
import "google/type/date.proto";
2223
import "google/type/money.proto";
2324

2425
option go_package = "google.golang.org/genproto/googleapis/cloud/billing/budgets/v1beta1;budgets";
@@ -28,8 +29,8 @@ option java_package = "com.google.cloud.billing.budgets.v1beta1";
2829
// A budget is a plan that describes what you expect to spend on Cloud
2930
// projects, plus the rules to execute as spend is tracked against that plan,
3031
// (for example, send an alert when 90% of the target spend is met).
31-
// Currently all plans are monthly budgets so the usage period(s) tracked are
32-
// implied (calendar months of usage back-to-back).
32+
// The budget time period is configurable, with options such as month (default),
33+
// quarter, year, or custom time period.
3334
message Budget {
3435
option (google.api.resource) = {
3536
type: "billingbudgets.googleapis.com/Budget"
@@ -45,8 +46,9 @@ message Budget {
4546
// Validation: <= 60 chars.
4647
string display_name = 2;
4748

48-
// Optional. Filters that define which resources are used to compute
49-
// the actual spend against the budget.
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.
5052
Filter budget_filter = 3 [(google.api.field_behavior) = OPTIONAL];
5153

5254
// Required. Budgeted amount.
@@ -74,20 +76,28 @@ message BudgetAmount {
7476
// A specified amount to use as the budget.
7577
// `currency_code` is optional. If specified when creating a budget, it must
7678
// match the currency of the billing account. If specified when updating a
77-
// budget, it must match the existing budget currency_code.
79+
// budget, it must match the currency_code of the existing budget.
7880
// The `currency_code` is provided on output.
7981
google.type.Money specified_amount = 1;
8082

8183
// Use the last period's actual spend as the budget for the present period.
84+
// 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.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
8288
LastPeriodAmount last_period_amount = 2;
8389
}
8490
}
8591

86-
// Describes a budget amount targeted to last period's spend.
87-
// At this time, the amount is automatically 100% of last period's spend;
88-
// that is, there are no other options yet.
89-
// Future configuration will be described here (for example, configuring a
90-
// percentage of last period's spend).
92+
// Describes a budget amount targeted to the last
93+
// [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]
94+
// spend. At this time, the amount is automatically 100% of the last calendar
95+
// period's spend; that is, there are no other options yet.
96+
// Future configuration options will be described here (for example, configuring
97+
// a percentage of last period's spend).
98+
// LastPeriodAmount cannot be set for a budget configured with
99+
// a
100+
// [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
91101
message LastPeriodAmount {}
92102

93103
// ThresholdRule contains a definition of a threshold which triggers
@@ -108,6 +118,10 @@ message ThresholdRule {
108118

109119
// Use forecasted spend for the period as the basis for comparison against
110120
// the threshold.
121+
// 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
124+
// [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
111125
FORECASTED_SPEND = 2;
112126
}
113127

@@ -128,12 +142,12 @@ message AllUpdatesRule {
128142
// be published, in the form `projects/{project_id}/topics/{topic_id}`.
129143
// Updates are sent at regular intervals to the topic. The topic needs to be
130144
// created before the budget is created; see
131-
// https://cloud.google.com/billing/docs/how-to/budgets#manage-notifications
145+
// https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications
132146
// for more details.
133147
// Caller is expected to have
134148
// `pubsub.topics.setIamPolicy` permission on the topic when it's set for a
135149
// budget, otherwise, the API call will fail with PERMISSION_DENIED. See
136-
// https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications
150+
// https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#permissions_required_for_this_task
137151
// for more details on Pub/Sub roles and permissions.
138152
string pubsub_topic = 1 [(google.api.field_behavior) = OPTIONAL];
139153

@@ -166,8 +180,11 @@ message AllUpdatesRule {
166180

167181
// A filter for a budget, limiting the scope of the cost to calculate.
168182
message Filter {
169-
// Specifies how credits should be treated when determining spend for
170-
// threshold calculations.
183+
// Specifies how credits are applied when determining the spend for
184+
// threshold calculations. Budgets track the total cost minus any applicable
185+
// selected credits.
186+
// [See the documentation for a list of credit
187+
// types](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
171188
enum CreditTypesTreatment {
172189
CREDIT_TYPES_TREATMENT_UNSPECIFIED = 0;
173190

@@ -179,7 +196,9 @@ message Filter {
179196
// threshold calculations.
180197
EXCLUDE_ALL_CREDITS = 2;
181198

182-
// Credit types specified in the credit_types field are subtracted from the
199+
// [Credit
200+
// types](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type)
201+
// specified in the credit_types field are subtracted from the
183202
// gross cost to determine the spend for threshold calculations.
184203
INCLUDE_SPECIFIED_CREDITS = 3;
185204
}
@@ -195,13 +214,12 @@ message Filter {
195214
// [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
196215
// is INCLUDE_SPECIFIED_CREDITS, this is a list of credit types to be
197216
// subtracted from gross cost to determine the spend for threshold
198-
// calculations.
217+
// calculations. See [a list of acceptable credit type
218+
// values](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
199219
//
200220
// If
201221
// [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
202-
// is **not** INCLUDE_SPECIFIED_CREDITS, this field must be empty. See [a list
203-
// of acceptable credit type
204-
// values](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
222+
// is **not** INCLUDE_SPECIFIED_CREDITS, this field must be empty.
205223
repeated string credit_types = 7 [(google.api.field_behavior) = OPTIONAL];
206224

207225
// Optional. If not set, default behavior is `INCLUDE_ALL_CREDITS`.
@@ -230,4 +248,51 @@ message Filter {
230248
// the report will include all labeled and unlabeled usage.
231249
map<string, google.protobuf.ListValue> labels = 6
232250
[(google.api.field_behavior) = OPTIONAL];
251+
252+
// Multiple options to choose the budget's time period, specifying that only
253+
// usage that occurs during this time period should be included in the budget.
254+
// If not set, the `usage_period` defaults to CalendarPeriod.MONTH.
255+
oneof usage_period {
256+
// Optional. Specifies to track usage for recurring calendar period.
257+
// For example, assume that CalendarPeriod.QUARTER is set. The budget will
258+
// track usage from April 1 to June 30, when the current calendar month is
259+
// April, May, June. After that, it will track usage from July 1 to
260+
// September 30 when the current calendar month is July, August, September,
261+
// so on.
262+
CalendarPeriod calendar_period = 8 [(google.api.field_behavior) = OPTIONAL];
263+
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.
266+
CustomPeriod custom_period = 9 [(google.api.field_behavior) = OPTIONAL];
267+
}
268+
}
269+
270+
// All date times begin at 12 AM US and Canadian Pacific Time (UTC-8).
271+
message CustomPeriod {
272+
// Required. The start date must be after January 1, 2017.
273+
google.type.Date start_date = 1 [(google.api.field_behavior) = REQUIRED];
274+
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.
278+
google.type.Date end_date = 2 [(google.api.field_behavior) = OPTIONAL];
279+
}
280+
281+
// A `CalendarPeriod` represents the abstract concept of a time period that
282+
// has a canonical start. Grammatically, "the start of the current
283+
// `CalendarPeriod`". All calendar times begin at 12 AM US and Canadian
284+
// Pacific Time (UTC-8).
285+
enum CalendarPeriod {
286+
CALENDAR_PERIOD_UNSPECIFIED = 0;
287+
288+
// A month. Month starts on the first day of each month, such as January 1,
289+
// February 1, March 1, and so on.
290+
MONTH = 1;
291+
292+
// A quarter. Quarters start on dates January 1, April 1, July 1, and October
293+
// 1 of each year.
294+
QUARTER = 2;
295+
296+
// A year. Year starts on January 1.
297+
YEAR = 3;
233298
}

0 commit comments

Comments
 (0)