This guide provides all required setup steps to start using the Cloud Billing Budget API.
Before you begin
You should do the following before reading this guide:
About the Cloud Console
The Google Cloud Console (visit documentation, open console) is a web UI used to provision, configure, manage, and monitor systems that use Google Cloud products. You use the Cloud Console to set up and manage Google Cloud and Cloud Billing resources.
1. Select or Create a project
To use services provided by Google Cloud, you must create a project. A project organizes all your Google Cloud resources. A project consists of a set of collaborators, enabled APIs (and other resources), monitoring tools, billing information, and authentication and access controls. You can create one project, or you can create multiple projects and use them to organize your Google Cloud resources in a resource hierarchy. For more information on projects, see the Resource Manager documentation.
Recommendation: We recommend that you configure a separate, single Google Cloud project to contain all of your billing administration needs, including the Cloud Billing Budget API. Your billing administration Google Cloud project can also be used for things like Cloud Billing Account API access, Cloud Billing exported data, Pub/Sub channels for programmatic budget notifications, and so on.
In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
2. Enable billing
You need to make sure that billing is enabled on the project you are using for calling the Cloud Billing Budget API. If you followed the recommendation in the project section, this is your billing administration Google Cloud project.
A Cloud Billing Account is used to define who pays for a given set of Google Cloud resources. Resources, such as enabled APIs, are organized in projects. A Cloud Billing Account can be linked to one or more projects. Project usage is charged to the linked billing account. In most cases, you configure billing when you create a project. For more information, see the Billing documentation.
You set up Cloud Billing budgets to monitor a Cloud Billing Account. The Cloud Billing Account you are monitoring can be the same Cloud Billing Account that is linked to the project you use to call the Cloud Billing Budget API. Note that the Cloud Billing Budget API is free to use for Google Cloud customers. If you choose to configure programmatic budget notifications, you will be charged the standard Pub/Sub prices.
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
3. Enable the API
You must enable the Cloud Billing Budget API in the project you are using to call the Cloud Billing Budget API. If you followed the recommendation in the project section, this is your billing administration Google Cloud project.
For more information on enabling APIs, see the Service Usage documentation.Enable the Cloud Billing Budget API.
4. Set up authentication
If you plan to use the Cloud Billing Budget API, you need to set up authentication. Any client application that uses the API must be authenticated and granted access to the requested resources. This section describes important authentication concepts and provides steps for setting it up. For more information, see the GCP authentication overview.
About service accounts
There are multiple options for authentication, but we recommend that you use service accounts for authentication and access control. A service account provides credentials for applications, as opposed to end-users.
Service accounts are owned by projects, and you can create many service accounts for a project. For more information, see Service accounts.
When an identity (the service account) calls an API, Google Cloud requires the identity to have the appropriate permissions. You grant permissions by granting roles to a service account. For more information, see the Identity and Access Management (IAM) documentation.
To use all of the Cloud Billing Budget API methods, you will need to add the service account as a member to each Cloud Billing Account where you want to use the Cloud Billing Budget API to programmatically manage budgets, and assign the appropriate roles to the service account.
If you plan to configure a Pub/Sub topic for programmatic budget notifications, you also need to add the service account as a member of the project where your Pub/Sub topic resides, and assign the IAM Security Admin role to the service account. This role is needed so that the service account has permission to grant the Pub/Sub Publisher role on the topic to allow Cloud Billing to publish messages to it.
For more information on roles specific to Cloud Billing APIs, see the Cloud Billing APIs access control document.
About service account keys
Service accounts are associated with one or more public/private key pairs. When you create a new key pair, you download the private key. Your private key is used to generate credentials when calling the API. You are responsible for security of the private key and other management operations, such as key rotation.
A. Create a service account and download the private key file
The service account needs to be created in the same project where you registered the Cloud Billing Budget API. If you followed the recommendation in the project section, this is your billing administration Google Cloud project.
First, create the service account:
In the Cloud Console, go to the Create service account page.Go to Create service account
- Select a project.
Enter a service account name to display in the Cloud Console.
The Cloud Console generates a service account ID based on this name. Edit the ID if necessary. You cannot change the ID later.
- Optional: Enter a description of the service account.
Do not close your browser window. You will use it in the next procedure.
Then create a service account key:
- In the Cloud Console, click the email address for the service account that you created.
- Click Keys.
- Click Add key, then Create new key.
- Click Create. A JSON key file is downloaded to your computer.
- Click Close.
B. Grant your service account permissions to use the Cloud Billing Budget API
Grant Cloud Billing and IAM roles to your service account to assign the permissions needed to use all of the Cloud Billing Budget API methods for all budgets in your Cloud Billing Account.
- Find your service account email address inside the json file you just
downloaded, with the key
client_email. The email will look like
- In the Cloud Console, navigate to the Billing account management
follow these instructions to update billing permissions
for the service account.
- For each billing account where you want to manage budgets using the API, you need to add the service account email as a member.
- Add the Billing Account Administrator role to the service account member.
- Optional: If you plan to configure your budgets to use
programmatic notifications, you also need to assign IAM
permissions to the project where your
Pub/Sub topic resides (this might be your billing
administration Google Cloud project, if you followed the
recommendation in the
- Open the console navigation menu ( ) and click IAM & admin > IAM.
- On the IAM Permissions tab, confirm you are viewing the permissions for the project where your Pub/Sub topic resides. You will see a headline on the page similar to this: Permissions for project "My Cloud Billing Admin Project".
- Add the service account email as a member of the project, and assign
the IAM Security Admin role to the service
- Click ADD.
- In the New members field, enter the service account email address.
- In the Select a role drop-down, scroll down to (or filter by) IAM, and select the Security Admin role.
C. Use the service account key file in your environment
Provide authentication credentials to your application code by
setting the environment variable
Replace [PATH] with the file path of the JSON file that contains your
service account key. This variable only applies to your current shell session,
so if you open a new session, set the variable again.
Linux or macOS
With command prompt:
5. Install and initialize the Cloud SDK
If you plan to use the Cloud Billing Budget API,
you need to install and initialize the Cloud SDK.
Cloud SDK is a set of tools that you can use
to manage resources and applications hosted on Google Cloud.
This includes the
command line tool.
The following link provides instructions:
6. Test the SDK and authentication
If you have set up authentication in previous steps,
you can use the
gcloud tool to test your authentication environment.
Execute the following command to verify that
no error occurs and that credentials are returned:
gcloud auth application-default print-access-token
That command is used by all Cloud Billing Budget API command line REST samples to authenticate API calls.
7. Install the Cloud Billing Budget API client library
The Cloud Billing Budget API is built on HTTP and JSON, so any standard HTTP client can send requests to it and parse the responses.
You have three options for calling the API:
Google supported client libraries (recommended)
Client libraries provide better language integration, improved security, and support for making calls that require user authorization. The Google supported client libraries are available for several popular languages, and these are the recommended option.