feat: Add resource_ancestors field to support filtering by folders & organizations (#11360)

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Anthonios Partheniou <partheniou@google.com>

Author: gcf-owl-bot[bot]

packages/google-cloud-billing-budgets/google/cloud/billing/budgets/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "1.10.0" # {x-release-please-version}
+__version__ = "0.1.0" # {x-release-please-version}

packages/google-cloud-billing-budgets/google/cloud/billing/budgets_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "1.10.0" # {x-release-please-version}
+__version__ = "0.1.0" # {x-release-please-version}

packages/google-cloud-billing-budgets/google/cloud/billing/budgets_v1/types/budget_model.py

@@ -45,7 +45,9 @@ class CalendarPeriod(proto.Enum):
 
  Values:
  CALENDAR_PERIOD_UNSPECIFIED (0):
- No description available.
+ Calendar period is unset. This is the default
+ if the budget is for a custom time period
+ (CustomPeriod).
  MONTH (1):
  A month. Month starts on the first day of
  each month, such as January 1, February 1, March
@@ -87,17 +89,20 @@ class Budget(proto.Message):
  amount (google.cloud.billing.budgets_v1.types.BudgetAmount):
  Required. Budgeted amount.
  threshold_rules (MutableSequence[google.cloud.billing.budgets_v1.types.ThresholdRule]):
- Optional. Rules that trigger alerts
- (notifications of thresholds being crossed) when
- spend exceeds the specified percentages of the
- budget.
+ Optional. Rules that trigger alerts (notifications of
+ thresholds being crossed) when spend exceeds the specified
+ percentages of the budget.
+
+ Optional for ``pubsubTopic`` notifications.
+
+ Required if using email notifications.
  notifications_rule (google.cloud.billing.budgets_v1.types.NotificationsRule):
  Optional. Rules to apply to notifications
  sent based on budget spend and thresholds.
  etag (str):
  Optional. Etag to validate that the object is
  unchanged for a read-modify-write operation.
- An empty etag will cause an update to overwrite
+ An empty etag causes an update to overwrite
  other changes.
  """
 
@@ -185,22 +190,32 @@ class LastPeriodAmount(proto.Message):
  [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
+ LastPeriodAmount cannot be set for a budget configured with a
  [Filter.custom_period][google.cloud.billing.budgets.v1.Filter.custom_period].
 
  """
 
 
 class ThresholdRule(proto.Message):
- r"""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``.
+ r"""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>`__.
 
  Attributes:
  threshold_percent (float):
@@ -252,18 +267,36 @@ class NotificationsRule(proto.Message):
 
  Attributes:
  pubsub_topic (str):
- Optional. The name of the Pub/Sub topic where budget related
- messages will be published, in the form
+ Optional. The name of the Pub/Sub topic where budget-related
+ messages are 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#manage-notifications
- for more details. Caller is expected to have
- ``pubsub.topics.setIamPolicy`` permission on the topic when
- it's set for a budget, otherwise, the API call will fail
- with PERMISSION_DENIED. See
- https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications
- for more details on Pub/Sub roles and permissions.
+ sent to the topic at regular intervals; the timing of the
+ updates is not dependent on the `threshold
+ rules <#thresholdrule>`__ you've set.
+
+ Note that if you want your `Pub/Sub JSON
+ object <https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification_format>`__
+ to contain data for ``alertThresholdExceeded``, you need at
+ least one `alert threshold rule <#thresholdrule>`__. When
+ you set threshold rules, you must also enable at least one
+ of the email notification options, either using the default
+ IAM recipients or Cloud Monitoring email notification
+ channels.
+
+ To use Pub/Sub topics with budgets, you must do the
+ following:
+
+ 1. Create the Pub/Sub topic before connecting it to your
+ budget. For guidance, see `Manage programmatic budget
+ alert
+ notifications <https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications>`__.
+
+ 2. Grant the API caller the ``pubsub.topics.setIamPolicy``
+ permission on the Pub/Sub topic. If not set, the API call
+ fails with PERMISSION_DENIED. For additional details on
+ Pub/Sub roles and permissions, see `Permissions required
+ for this
+ task <https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#permissions_required_for_this_task>`__.
  schema_version (str):
  Optional. Required when
  [NotificationsRule.pubsub_topic][google.cloud.billing.budgets.v1.NotificationsRule.pubsub_topic]
@@ -273,15 +306,29 @@ class NotificationsRule(proto.Message):
  defined in
  https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification_format.
  monitoring_notification_channels (MutableSequence[str]):
- 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. Email targets to send notifications to when a
+ threshold is exceeded. This is in addition to the
+ ``DefaultIamRecipients`` who receive alert emails based on
+ their billing account IAM role. The value is the full REST
+ resource name of a Cloud Monitoring email 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.
+ A maximum of 5 email notifications are allowed.
+
+ To customize budget alert email recipients with monitoring
+ notification channels, you *must create the monitoring
+ notification channels before you link them to a budget*. For
+ guidance on setting up notification channels to use with
+ budgets, see `Customize budget alert email
+ recipients <https://cloud.google.com/billing/docs/how-to/budgets-notification-recipients>`__.
+
+ For Cloud Billing budget alerts, you *must use email
+ notification channels*. The other types of notification
+ channels are *not* supported, such as Slack, SMS, or
+ PagerDuty. If you want to `send budget notifications to
+ Slack <https://cloud.google.com/billing/docs/how-to/notify#send_notifications_to_slack>`__,
+ use a pubsubTopic and configure `programmatic
+ notifications <https://cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications>`__.
  disable_default_iam_recipients (bool):
  Optional. When set to true, disables default
  notifications sent when a threshold is exceeded.
@@ -324,9 +371,16 @@ class Filter(proto.Message):
  Optional. A set of projects of the form
  ``projects/{project}``, specifying that usage from only this
  set of projects should be included in the budget. If
- omitted, the report will include all usage for the billing
+ omitted, the report includes all usage for the billing
  account, regardless of which project the usage occurred on.
- Only zero or one project can be specified currently.
+ resource_ancestors (MutableSequence[str]):
+ Optional. A set of folder and organization names of the form
+ ``folders/{folderId}`` or
+ ``organizations/{organizationId}``, specifying that usage
+ from only this set of folders and organizations should be
+ included in the budget. If omitted, the report includes all
+ usage for all organizations, regardless of which
+ organization the usage occurred on.
  credit_types (MutableSequence[str]):
  Optional. If
  [Filter.credit_types_treatment][google.cloud.billing.budgets.v1.Filter.credit_types_treatment]
@@ -347,32 +401,35 @@ class Filter(proto.Message):
  Optional. A set of services of the form
  ``services/{service_id}``, specifying that usage from only
  this set of services should be included in the budget. If
- omitted, the report will include usage for all the services.
- The service names are available through the Catalog API:
+ omitted, the report includes usage for all the services. The
+ service names are available through the Catalog API:
  https://cloud.google.com/billing/v1/how-tos/catalog-api.
  subaccounts (MutableSequence[str]):
  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
- the field is omitted, the report will include usage from the
- parent account and all subaccounts, if they exist.
+ account, usage from the parent account is included. If the
+ field is omitted, the report includes usage from the parent
+ account and all subaccounts, if they exist.
  labels (MutableMapping[str, google.protobuf.struct_pb2.ListValue]):
- 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.
+ 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 includes 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.*
  calendar_period (google.cloud.billing.budgets_v1.types.CalendarPeriod):
  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
+ tracks usage from April 1 to June 30, when the
+ current calendar month is April, May, June.
+ After that, it tracks usage from July 1 to
  September 30 when the current calendar month is
  July, August, September, so on.
 
@@ -420,6 +477,10 @@ class CreditTypesTreatment(proto.Enum):
  proto.STRING,
  number=1,
  )
+ resource_ancestors: MutableSequence[str] = proto.RepeatedField(
+ proto.STRING,
+ number=2,
+ )
  credit_types: MutableSequence[str] = proto.RepeatedField(
  proto.STRING,
  number=7,

packages/google-cloud-billing-budgets/google/cloud/billing/budgets_v1beta1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "1.10.0" # {x-release-please-version}
+__version__ = "0.1.0" # {x-release-please-version}

packages/google-cloud-billing-budgets/google/cloud/billing/budgets_v1beta1/types/budget_model.py

@@ -343,7 +343,14 @@ class Filter(proto.Message):
  set of projects should be included in the budget. If
  omitted, the report will include all usage for the billing
  account, regardless of which project the usage occurred on.
- Only zero or one project can be specified currently.
+ resource_ancestors (MutableSequence[str]):
+ Optional. A set of folder and organization names of the form
+ ``folders/{folderId}`` or
+ ``organizations/{organizationId}``, specifying that usage
+ from only this set of folders and organizations should be
+ included in the budget. If omitted, the report includes all
+ usage for all organizations, regardless of which
+ organization the usage occurred on.
  credit_types (MutableSequence[str]):
  Optional. If
  [Filter.credit_types_treatment][google.cloud.billing.budgets.v1beta1.Filter.credit_types_treatment]
@@ -440,6 +447,10 @@ class CreditTypesTreatment(proto.Enum):
  proto.STRING,
  number=1,
  )
+ resource_ancestors: MutableSequence[str] = proto.RepeatedField(
+ proto.STRING,
+ number=2,
+ )
  credit_types: MutableSequence[str] = proto.RepeatedField(
  proto.STRING,
  number=7,

packages/google-cloud-billing-budgets/samples/generated_samples/billingbudgets_v1_generated_budget_service_create_budget_async.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+# 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.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Generated code. DO NOT EDIT!
+#
+# Snippet for CreateBudget
+# NOTE: This snippet has been automatically generated for illustrative purposes only.
+# It may require modifications to work in your environment.
+
+# To install the latest published package dependency, execute the following:
+# python3 -m pip install google-cloud-billing-budgets
+
+
+# [START billingbudgets_v1_generated_BudgetService_CreateBudget_async]
+# This snippet has been automatically generated and should be regarded as a
+# code template only.
+# It will require modifications to work:
+# - It may require correct/in-range values for request initialization.
+# - It may require specifying regional endpoints when creating the service
+# client as shown in:
+# https://googleapis.dev/python/google-api-core/latest/client_options.html
+from google.cloud.billing import budgets_v1
+
+
+async def sample_create_budget():
+ # Create a client
+ client = budgets_v1.BudgetServiceAsyncClient()
+
+ # Initialize request argument(s)
+ request = budgets_v1.CreateBudgetRequest(
+ parent="parent_value",
+ )
+
+ # Make the request
+ response = await client.create_budget(request=request)
+
+ # Handle the response
+ print(response)
+
+# [END billingbudgets_v1_generated_BudgetService_CreateBudget_async]

packages/google-cloud-billing-budgets/samples/generated_samples/billingbudgets_v1_generated_budget_service_create_budget_sync.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+# 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.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Generated code. DO NOT EDIT!
+#
+# Snippet for CreateBudget
+# NOTE: This snippet has been automatically generated for illustrative purposes only.
+# It may require modifications to work in your environment.
+
+# To install the latest published package dependency, execute the following:
+# python3 -m pip install google-cloud-billing-budgets
+
+
+# [START billingbudgets_v1_generated_BudgetService_CreateBudget_sync]
+# This snippet has been automatically generated and should be regarded as a
+# code template only.
+# It will require modifications to work:
+# - It may require correct/in-range values for request initialization.
+# - It may require specifying regional endpoints when creating the service
+# client as shown in:
+# https://googleapis.dev/python/google-api-core/latest/client_options.html
+from google.cloud.billing import budgets_v1
+
+
+def sample_create_budget():
+ # Create a client
+ client = budgets_v1.BudgetServiceClient()
+
+ # Initialize request argument(s)
+ request = budgets_v1.CreateBudgetRequest(
+ parent="parent_value",
+ )
+
+ # Make the request
+ response = client.create_budget(request=request)
+
+ # Handle the response
+ print(response)
+
+# [END billingbudgets_v1_generated_BudgetService_CreateBudget_sync]