budget_model.proto 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298
  1. // Copyright 2021 Google LLC
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. syntax = "proto3";
  15. package google.cloud.billing.budgets.v1beta1;
  16. import "google/api/field_behavior.proto";
  17. import "google/api/resource.proto";
  18. import "google/protobuf/struct.proto";
  19. import "google/type/date.proto";
  20. import "google/type/money.proto";
  21. option go_package = "google.golang.org/genproto/googleapis/cloud/billing/budgets/v1beta1;budgets";
  22. option java_multiple_files = true;
  23. option java_package = "com.google.cloud.billing.budgets.v1beta1";
  24. // A budget is a plan that describes what you expect to spend on Cloud
  25. // projects, plus the rules to execute as spend is tracked against that plan,
  26. // (for example, send an alert when 90% of the target spend is met).
  27. // The budget time period is configurable, with options such as month (default),
  28. // quarter, year, or custom time period.
  29. message Budget {
  30. option (google.api.resource) = {
  31. type: "billingbudgets.googleapis.com/Budget"
  32. pattern: "billingAccounts/{billing_account}/budgets/{budget}"
  33. };
  34. // Output only. Resource name of the budget.
  35. // The resource name implies the scope of a budget. Values are of the form
  36. // `billingAccounts/{billingAccountId}/budgets/{budgetId}`.
  37. string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  38. // User data for display name in UI.
  39. // Validation: <= 60 chars.
  40. string display_name = 2;
  41. // Optional. Filters that define which resources are used to compute the
  42. // actual spend against the budget amount, such as projects, services, and the
  43. // budget's time period, as well as other filters.
  44. Filter budget_filter = 3 [(google.api.field_behavior) = OPTIONAL];
  45. // Required. Budgeted amount.
  46. BudgetAmount amount = 4 [(google.api.field_behavior) = REQUIRED];
  47. // Optional. Rules that trigger alerts (notifications of thresholds
  48. // being crossed) when spend exceeds the specified percentages of the budget.
  49. repeated ThresholdRule threshold_rules = 5
  50. [(google.api.field_behavior) = OPTIONAL];
  51. // Optional. Rules to apply to notifications sent based on budget spend and
  52. // thresholds.
  53. AllUpdatesRule all_updates_rule = 6 [(google.api.field_behavior) = OPTIONAL];
  54. // Optional. Etag to validate that the object is unchanged for a
  55. // read-modify-write operation.
  56. // An empty etag will cause an update to overwrite other changes.
  57. string etag = 7 [(google.api.field_behavior) = OPTIONAL];
  58. }
  59. // The budgeted amount for each usage period.
  60. message BudgetAmount {
  61. // Specification for what amount to use as the budget.
  62. oneof budget_amount {
  63. // A specified amount to use as the budget.
  64. // `currency_code` is optional. If specified when creating a budget, it must
  65. // match the currency of the billing account. If specified when updating a
  66. // budget, it must match the currency_code of the existing budget.
  67. // The `currency_code` is provided on output.
  68. google.type.Money specified_amount = 1;
  69. // Use the last period's actual spend as the budget for the present period.
  70. // LastPeriodAmount can only be set when the budget's time period is a
  71. // [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period].
  72. // It cannot be set in combination with
  73. // [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
  74. LastPeriodAmount last_period_amount = 2;
  75. }
  76. }
  77. // Describes a budget amount targeted to the last
  78. // [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period]
  79. // spend. At this time, the amount is automatically 100% of the last calendar
  80. // period's spend; that is, there are no other options yet.
  81. // Future configuration options will be described here (for example, configuring
  82. // a percentage of last period's spend).
  83. // LastPeriodAmount cannot be set for a budget configured with
  84. // a
  85. // [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
  86. message LastPeriodAmount {}
  87. // ThresholdRule contains a definition of a threshold which triggers
  88. // an alert (a notification of a threshold being crossed) to be sent when
  89. // spend goes above the specified amount.
  90. // Alerts are automatically e-mailed to users with the Billing Account
  91. // Administrator role or the Billing Account User role.
  92. // The thresholds here have no effect on notifications sent to anything
  93. // configured under `Budget.all_updates_rule`.
  94. message ThresholdRule {
  95. // The type of basis used to determine if spend has passed the threshold.
  96. enum Basis {
  97. // Unspecified threshold basis.
  98. BASIS_UNSPECIFIED = 0;
  99. // Use current spend as the basis for comparison against the threshold.
  100. CURRENT_SPEND = 1;
  101. // Use forecasted spend for the period as the basis for comparison against
  102. // the threshold.
  103. // FORECASTED_SPEND can only be set when the budget's time period is a
  104. // [Filter.calendar_period][google.cloud.billing.budgets.v1beta1.Filter.calendar_period].
  105. // It cannot be set in combination with
  106. // [Filter.custom_period][google.cloud.billing.budgets.v1beta1.Filter.custom_period].
  107. FORECASTED_SPEND = 2;
  108. }
  109. // Required. Send an alert when this threshold is exceeded.
  110. // This is a 1.0-based percentage, so 0.5 = 50%.
  111. // Validation: non-negative number.
  112. double threshold_percent = 1 [(google.api.field_behavior) = REQUIRED];
  113. // Optional. The type of basis used to determine if spend has passed the
  114. // threshold. Behavior defaults to CURRENT_SPEND if not set.
  115. Basis spend_basis = 2 [(google.api.field_behavior) = OPTIONAL];
  116. }
  117. // AllUpdatesRule defines notifications that are sent based on budget spend
  118. // and thresholds.
  119. message AllUpdatesRule {
  120. // Optional. The name of the Pub/Sub topic where budget related messages will
  121. // be published, in the form `projects/{project_id}/topics/{topic_id}`.
  122. // Updates are sent at regular intervals to the topic. The topic needs to be
  123. // created before the budget is created; see
  124. // https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications
  125. // for more details.
  126. // Caller is expected to have
  127. // `pubsub.topics.setIamPolicy` permission on the topic when it's set for a
  128. // budget, otherwise, the API call will fail with PERMISSION_DENIED. See
  129. // https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#permissions_required_for_this_task
  130. // for more details on Pub/Sub roles and permissions.
  131. string pubsub_topic = 1 [(google.api.field_behavior) = OPTIONAL];
  132. // Optional. Required when
  133. // [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic]
  134. // is set. The schema version of the notification sent to
  135. // [AllUpdatesRule.pubsub_topic][google.cloud.billing.budgets.v1beta1.AllUpdatesRule.pubsub_topic].
  136. // Only "1.0" is accepted. It represents the JSON schema as defined in
  137. // https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification_format.
  138. string schema_version = 2 [(google.api.field_behavior) = OPTIONAL];
  139. // Optional. Targets to send notifications to when a threshold is exceeded.
  140. // This is in addition to default recipients who have billing account IAM
  141. // roles. The value is the full REST resource name of a monitoring
  142. // notification channel with the form
  143. // `projects/{project_id}/notificationChannels/{channel_id}`. A maximum of 5
  144. // channels are allowed. See
  145. // https://cloud.google.com/billing/docs/how-to/budgets-notification-recipients
  146. // for more details.
  147. repeated string monitoring_notification_channels = 3
  148. [(google.api.field_behavior) = OPTIONAL];
  149. // Optional. When set to true, disables default notifications sent when a
  150. // threshold is exceeded. Default notifications are sent to those with Billing
  151. // Account Administrator and Billing Account User IAM roles for the target
  152. // account.
  153. bool disable_default_iam_recipients = 4
  154. [(google.api.field_behavior) = OPTIONAL];
  155. }
  156. // A filter for a budget, limiting the scope of the cost to calculate.
  157. message Filter {
  158. // Specifies how credits are applied when determining the spend for
  159. // threshold calculations. Budgets track the total cost minus any applicable
  160. // selected credits.
  161. // [See the documentation for a list of credit
  162. // types](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
  163. enum CreditTypesTreatment {
  164. CREDIT_TYPES_TREATMENT_UNSPECIFIED = 0;
  165. // All types of credit are subtracted from the gross cost to determine the
  166. // spend for threshold calculations.
  167. INCLUDE_ALL_CREDITS = 1;
  168. // All types of credit are added to the net cost to determine the spend for
  169. // threshold calculations.
  170. EXCLUDE_ALL_CREDITS = 2;
  171. // [Credit
  172. // types](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type)
  173. // specified in the credit_types field are subtracted from the
  174. // gross cost to determine the spend for threshold calculations.
  175. INCLUDE_SPECIFIED_CREDITS = 3;
  176. }
  177. // Optional. A set of projects of the form `projects/{project}`,
  178. // specifying that usage from only this set of projects should be
  179. // included in the budget. If omitted, the report will include all usage for
  180. // the billing account, regardless of which project the usage occurred on.
  181. // Only zero or one project can be specified currently.
  182. repeated string projects = 1 [(google.api.field_behavior) = OPTIONAL];
  183. // Optional. If
  184. // [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
  185. // is INCLUDE_SPECIFIED_CREDITS, this is a list of credit types to be
  186. // subtracted from gross cost to determine the spend for threshold
  187. // calculations. See [a list of acceptable credit type
  188. // values](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#credits-type).
  189. //
  190. // If
  191. // [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
  192. // is **not** INCLUDE_SPECIFIED_CREDITS, this field must be empty.
  193. repeated string credit_types = 7 [(google.api.field_behavior) = OPTIONAL];
  194. // Optional. If not set, default behavior is `INCLUDE_ALL_CREDITS`.
  195. CreditTypesTreatment credit_types_treatment = 4
  196. [(google.api.field_behavior) = OPTIONAL];
  197. // Optional. A set of services of the form `services/{service_id}`,
  198. // specifying that usage from only this set of services should be
  199. // included in the budget. If omitted, the report will include usage for
  200. // all the services.
  201. // The service names are available through the Catalog API:
  202. // https://cloud.google.com/billing/v1/how-tos/catalog-api.
  203. repeated string services = 3 [(google.api.field_behavior) = OPTIONAL];
  204. // Optional. A set of subaccounts of the form `billingAccounts/{account_id}`,
  205. // specifying that usage from only this set of subaccounts should be included
  206. // in the budget. If a subaccount is set to the name of the parent account,
  207. // usage from the parent account will be included. If omitted, the
  208. // report will include usage from the parent account and all
  209. // subaccounts, if they exist.
  210. repeated string subaccounts = 5 [(google.api.field_behavior) = OPTIONAL];
  211. // Optional. A single label and value pair specifying that usage from only
  212. // this set of labeled resources should be included in the budget. Currently,
  213. // multiple entries or multiple values per entry are not allowed. If omitted,
  214. // the report will include all labeled and unlabeled usage.
  215. map<string, google.protobuf.ListValue> labels = 6
  216. [(google.api.field_behavior) = OPTIONAL];
  217. // Multiple options to choose the budget's time period, specifying that only
  218. // usage that occurs during this time period should be included in the budget.
  219. // If not set, the `usage_period` defaults to CalendarPeriod.MONTH.
  220. oneof usage_period {
  221. // Optional. Specifies to track usage for recurring calendar period.
  222. // For example, assume that CalendarPeriod.QUARTER is set. The budget will
  223. // track usage from April 1 to June 30, when the current calendar month is
  224. // April, May, June. After that, it will track usage from July 1 to
  225. // September 30 when the current calendar month is July, August, September,
  226. // so on.
  227. CalendarPeriod calendar_period = 8 [(google.api.field_behavior) = OPTIONAL];
  228. // Optional. Specifies to track usage from any start date (required) to any
  229. // end date (optional). This time period is static, it does not recur.
  230. CustomPeriod custom_period = 9 [(google.api.field_behavior) = OPTIONAL];
  231. }
  232. }
  233. // All date times begin at 12 AM US and Canadian Pacific Time (UTC-8).
  234. message CustomPeriod {
  235. // Required. The start date must be after January 1, 2017.
  236. google.type.Date start_date = 1 [(google.api.field_behavior) = REQUIRED];
  237. // Optional. The end date of the time period. Budgets with elapsed end date
  238. // won't be processed. If unset, specifies to track all usage incurred since
  239. // the start_date.
  240. google.type.Date end_date = 2 [(google.api.field_behavior) = OPTIONAL];
  241. }
  242. // A `CalendarPeriod` represents the abstract concept of a time period that
  243. // has a canonical start. Grammatically, "the start of the current
  244. // `CalendarPeriod`". All calendar times begin at 12 AM US and Canadian
  245. // Pacific Time (UTC-8).
  246. enum CalendarPeriod {
  247. CALENDAR_PERIOD_UNSPECIFIED = 0;
  248. // A month. Month starts on the first day of each month, such as January 1,
  249. // February 1, March 1, and so on.
  250. MONTH = 1;
  251. // A quarter. Quarters start on dates January 1, April 1, July 1, and October
  252. // 1 of each year.
  253. QUARTER = 2;
  254. // A year. Year starts on January 1.
  255. YEAR = 3;
  256. }