Cloud for Sustainability API (Preview) overview
Important
Some or all of this functionality is available as part of a preview release. The content and the functionality are subject to change.
Microsoft Cloud for Sustainability provides APIs to access emissions data related to your Azure usage.
Accurate carbon accounting requires good information from partners, vendors, and suppliers. The Cloud for Sustainability APIs give you transparency on the carbon emissions generated by your usage of Azure. Microsoft’s carbon accounting extends across all three scopes of emissions with a methodology validated by Stanford University in 2018. It uses consistent and accurate carbon accounting to quantify the effect of Microsoft cloud services on customers’ environmental footprint.
Details of the API are listed in the Microsoft Cloud for Sustainability API reference. They include additional information about operations, parameters, and responses.
- Get started with Cloud for Sustainability APIs
- Sample queries
- Assign permissions
- Manage instances
- View API usage
- FAQ
Get started with Cloud for Sustainability APIs
Note
If your organization would like to gain access to the Microsoft Cloud for Sustainability API (Preview), submit this sign up form.
Get started with the APIs with the following procedures:
- Review supported Azure accounts
- Sign in and create an instance
- Configure data sources and enable the APIs
- Try the APIs
Supported Azure accounts
Microsoft Cloud for Sustainability APIs support EA Direct, MCA, and MPA accounts with direct billing relationships with Microsoft. Customers who purchase Azure from a Cloud Solution Provider (CSP) aren't supported and must work directly with their CSP to learn about their cloud emissions. Legacy accounts aren't supported.
Sign in and create an instance
After you receive access to the Microsoft Cloud for Sustainability APIs from Microsoft, sign in with your Azure Active Directory (Azure AD) credentials.
You must create an instance to access the Microsoft Cloud for Sustainability APIs. By creating the instance, you become the administrator of that instance. The administrator of the instance can add users, groups, and applications to the instance.
Configure data sources and enable the APIs
Important
To successfully enable access to your organization's data, this step must be performed by a billing account administrator with a role as billing account reader/contributor/owner on your Azure billing account. The billing account administrator may create instances or be added to instances to enable data sources and enable the API. If you don't have permissions to access your Azure billing account data, you can explore the API using demo data only.
On the Data Sources tab, toggle the connection on to connect Azure emissions data. Ensure the status is listed as Available before using the APIs. This action enables emissions data related to all enrollments or billing accounts for which you have access. If you don't have access to any emissions data, you'll proceed with demo data only.
Select the API Management tab, and then select Enable.
Enabling the API generates primary and secondary API keys for your instance to use in API requests. To regenerate the keys, select
. To copy keys, select
.
Try the APIs
On the API Management tab, select Try API. A developer portal will open in a new tab where you can explore the request and response schemas and make live requests against the Microsoft Cloud for Sustainability APIs.
To make a live request, select Try it. Enter all required fields:
- Authorization: Automatically populated authorization token
- Subscription key: Automatically populated with the API key from the API Management tab
- enrollmentId: Your enrollment ID, also known as billing account ID
- instanceId: Found in the URL of for the Microsoft Cloud for Sustainability API portal
Add all necessary query parameters. Scroll to the bottom of the side pane and select Send. The HTTP response will display at the bottom of the pane.
Important
The Microsoft Cloud for Sustainability API is currently in preview and is subject to change. Your historical emissions figures may also be updated as Microsoft makes improvements to data accuracy and completeness.
Sample queries
For a short list of OData sample queries to work with the APIs, go to OData query examples.
Assign permissions
Access to Microsoft Cloud for Sustainability APIs is restricted to users in your organization that are added to the application by an admin of an instance. A user can be a single user, group, or application. Guest accounts aren't supported. There are three types of roles that may be assigned:
- Viewer: Can view all pages within the Microsoft Cloud for Sustainability API.
- Contributor: Can interact with all pages in the Microsoft Cloud for Sustainability API portal. Can't add or remove users.
- Admin: All permissions available, including the ability to add or remove users.
To add users, groups, or apps as an admin:
- Select the Permissions tab, and then select Add Users.
- Use the Search field to find the Azure AD user, application, or group you want to add.
- Select a role assignment, and then select Save.
Manage instances
Navigate to the instance icon
to find a list of all instances, create instances, or remove instances.
View API usage
View details about your real-time API usage.
- Navigate to the API Management tab, and then select Usage.
- Select a time frame to view.
The API usage page contains three sections:
- API calls: A chart that visualizes the aggregated number of calls to the API in the selected time frame.
- Data transfer: A chart that shows the amount of data that was transferred through the API in the selected time frame.
- Operations: A table with rows for each available API operation and details about the usage of the operations.
FAQ
How does Microsoft calculate cloud carbon emissions made available by the API?
For information about Microsoft's calculation methodology, go to Microsoft Cloud for Sustainability API calculation methodology.
Where can I learn more about writing queries with OData?
To learn more about OData, go to Query options overview.
Where is the data used to produce this report stored?
The data is stored in the United States.
See also
Microsoft Cloud for Sustainability API OData query examples Microsoft Cloud for Sustainability API calculation methodology Microsoft Cloud for Sustainability API