feat: Added support for configurable budget time period.

Google APIs · copybara-github · commit dd6ba75f1ef4 · 2021-04-16T10:32:14.000-07:00
fix: Updated some documentation links.

PiperOrigin-RevId: 368871890
diff --git a/google/cloud/billing/budgets/v1/BUILD.bazel b/google/cloud/billing/budgets/v1/BUILD.bazel
@@ -1,5 +1,5 @@
 # This file was automatically generated by BuildFileGenerator
-# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel
+# https://github.com/googleapis/rules_gapic/tree/master/bazel
 
 # Most of the manual changes to this file will be overwritten.
 # It's **only** allowed to change the following rule attribute values:
@@ -30,17 +30,17 @@ load(
     "java_proto_library",
     "nodejs_gapic_assembly_pkg",
     "nodejs_gapic_library",
-    php_gapic_assembly_pkg = "php_gapic_assembly_pkg2",
-    php_gapic_library = "php_gapic_library2",
-    php_grpc_library = "php_grpc_library2",
-    php_proto_library = "php_proto_library2",
     "proto_library_with_info",
     "py_gapic_assembly_pkg",
     "py_gapic_library",
+    "ruby_cloud_gapic_library",
     "ruby_gapic_assembly_pkg",
-    "ruby_gapic_library",
     "ruby_grpc_library",
     "ruby_proto_library",
+    php_gapic_assembly_pkg = "php_gapic_assembly_pkg2",
+    php_gapic_library = "php_gapic_library2",
+    php_grpc_library = "php_grpc_library2",
+    php_proto_library = "php_proto_library2",
 )
 
 # This is an API workspace, having public visibility by default makes perfect sense.
@@ -57,6 +57,7 @@ proto_library(
         "//google/api:client_proto",
         "//google/api:field_behavior_proto",
         "//google/api:resource_proto",
+        "//google/type:date_proto",
         "//google/type:money_proto",
         "@com_google_protobuf//:empty_proto",
         "@com_google_protobuf//:field_mask_proto",
@@ -98,6 +99,7 @@ java_gapic_library(
 java_gapic_test(
     name = "budgets_java_gapic_test_suite",
     test_classes = [
+        "com.google.cloud.billing.budgets.v1.BudgetServiceClientTest",
     ],
     runtime_deps = [":budgets_java_gapic_test"],
 )
@@ -120,6 +122,7 @@ go_proto_library(
     protos = [":budgets_proto"],
     deps = [
         "//google/api:annotations_go_proto",
+        "//google/type:date_go_proto",
         "//google/type:money_go_proto",
     ],
 )
@@ -129,6 +132,7 @@ go_gapic_library(
     srcs = [":budgets_proto_with_info"],
     grpc_service_config = "billingbudgets_grpc_service_config.json",
     importpath = "cloud.google.com/go/billing/budgets/apiv1;budgets",
+    metadata = True,
     service_yaml = "billingbudgets.yaml",
     deps = [
         ":budgets_go_proto",
@@ -147,6 +151,7 @@ go_gapic_assembly_pkg(
     name = "gapi-cloud-billing-budgets-v1-go",
     deps = [
         ":budgets_go_gapic",
+        ":budgets_go_gapic_srcjar-metadata.srcjar",
         ":budgets_go_gapic_srcjar-test.srcjar",
         ":budgets_go_proto",
     ],
@@ -181,6 +186,7 @@ php_gapic_library(
     name = "budgets_php_gapic",
     srcs = [":budgets_proto_with_info"],
     grpc_service_config = "billingbudgets_grpc_service_config.json",
+    service_yaml = "billingbudgets.yaml",
     deps = [
         ":budgets_php_grpc",
         ":budgets_php_proto",
@@ -227,13 +233,11 @@ ruby_grpc_library(
     deps = [":budgets_ruby_proto"],
 )
 
-ruby_gapic_library(
+ruby_cloud_gapic_library(
     name = "budgets_ruby_gapic",
-    src = ":budgets_proto_with_info",
-    gapic_yaml = "billingbudget_gapic.yaml",
+    srcs = [":budgets_proto_with_info"],
+    extra_protoc_parameters = ["ruby-cloud-gem-name=google-cloud-billing-budgets-v1"],
     grpc_service_config = "billingbudgets_grpc_service_config.json",
-    package = "google.cloud.billing.budgets.v1",
-    service_yaml = "billingbudgets.yaml",
     deps = [
         ":budgets_ruby_grpc",
         ":budgets_ruby_proto",
diff --git a/google/cloud/billing/budgets/v1/budget_model.proto b/google/cloud/billing/budgets/v1/budget_model.proto
@@ -19,6 +19,7 @@ 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/date.proto";
 import "google/type/money.proto";
 
 option go_package = "google.golang.org/genproto/googleapis/cloud/billing/budgets/v1;budgets";
@@ -29,8 +30,8 @@ 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).
+// The budget time period is configurable, with options such as month (default),
+// quarter, year, or custom time period.
 message Budget {
   option (google.api.resource) = {
     type: "billingbudgets.googleapis.com/Budget"
@@ -46,8 +47,9 @@ message Budget {
   // characters.
   string display_name = 2;
 
-  // Optional. Filters that define which resources are used to compute
-  // the actual spend against the budget.
+  // 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.
@@ -81,15 +83,23 @@ message BudgetAmount {
     google.type.Money specified_amount = 1;
 
     // 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.v1.Filter.calendar_period].
+    // It cannot be set in combination with
+    // [Filter.custom_period][google.cloud.billing.budgets.v1.Filter.custom_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).
+// Describes a budget amount targeted to the last
+// [Filter.calendar_period][google.cloud.billing.budgets.v1.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.v1.Filter.custom_period].
 message LastPeriodAmount {}
 
 // ThresholdRule contains a definition of a threshold which triggers
@@ -110,6 +120,10 @@ 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.v1.Filter.calendar_period].
+    // It cannot be set in combination with
+    // [Filter.custom_period][google.cloud.billing.budgets.v1.Filter.custom_period].
     FORECASTED_SPEND = 2;
   }
 
@@ -168,10 +182,12 @@ message NotificationsRule {
 
 // 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.
+  // Specifies how credits are applied when determining the spend for
+  // threshold calculations. Budgets track the total cost minus any applicable
+  // selected credits.
+  // [See the documentation for a list of credit
+  // types](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
   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
@@ -182,7 +198,9 @@ message Filter {
     // threshold calculations.
     EXCLUDE_ALL_CREDITS = 2;
 
-    // Credit types specified in the credit_types field are subtracted from the
+    // [Credit
+    // types](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type)
+    // specified in the credit_types field are subtracted from the
     // gross cost to determine the spend for threshold calculations.
     INCLUDE_SPECIFIED_CREDITS = 3;
   }
@@ -198,13 +216,12 @@ message Filter {
   // [Filter.credit_types_treatment][google.cloud.billing.budgets.v1.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.
+  // 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.v1.Filter.credit_types_treatment]
-  // is **not** INCLUDE_SPECIFIED_CREDITS, this field must be empty. See [a list
-  // of acceptable credit type
-  // values](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
+  // 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`.
@@ -233,4 +250,51 @@ message Filter {
   // the report will include all labeled and unlabeled usage.
   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.
+  oneof usage_period {
+    // Optional. Specifies to track usage for recurring calendar period.
+    // For example, assume that CalendarPeriod.QUARTER is set. The budget will
+    // track usage from April 1 to June 30, when the current calendar month is
+    // April, May, June. After that, it will track usage from July 1 to
+    // September 30 when the current calendar month is July, August, September,
+    // 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.
+    CustomPeriod custom_period = 9 [(google.api.field_behavior) = OPTIONAL];
+  }
+}
+
+// All date times begin at 12 AM US and Canadian Pacific Time (UTC-8).
+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.
+  google.type.Date end_date = 2 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// A `CalendarPeriod` represents the abstract concept of a time period that
+// has a canonical start. Grammatically, "the start of the current
+// `CalendarPeriod`". All calendar times begin at 12 AM US and Canadian
+// Pacific Time (UTC-8).
+enum CalendarPeriod {
+  CALENDAR_PERIOD_UNSPECIFIED = 0;
+
+  // A month. Month starts on the first day of each month, such as January 1,
+  // February 1, March 1, and so on.
+  MONTH = 1;
+
+  // A quarter. Quarters start on dates January 1, April 1, July 1, and October
+  // 1 of each year.
+  QUARTER = 2;
+
+  // A year. Year starts on January 1.
+  YEAR = 3;
 }
