We have an important announcement to make – Usage Meter and Usage Report APIs are now part of the Cloud Provider Navigator and can be accessed from the Cloud Provider section on developer.vmware.com. Furthermore, there is a new API for registering a Usage Meter with a contract in the VCPP Commerce Portal. Here is what the Usage API page looks like on developer.vmware.com.
In this blog post, we will demonstrate the steps of registering a Usage Meter instance, getting information, and downloading usage reports.
Before using the aforementioned APIs, there are a few prerequisites that need to be satisfied.
Prerequisites
- A generated refresh token from Cloud Partner Navigator/User Profile/API Tokens. Information can be found here or scroll to the Generating an Access Token section in this blog post.
- A generated access token from the Cloud Partner Navigator refresh token. Read here or scroll to the Generating an Access Token section in this blog post.
Note: A generated access token expires after 30 minutes so you need to regenerate it once in a while.
Generating an Access Token for Authentication
To execute the API requests described in this blog post, you will need to generate a refresh token from Cloud Partner Navigator (CPN) and then execute a POST request to the Cloud Services Portal gateway to get the access token with which you will authenticate with the CPN service – Usage Insight.
The Usage Insight service is the service that will register your Usage Meter with a contract in the Commerce Portal and generate reports for a Usage Meter instance.
Now let’s see how to generate an access token:
- Log in to Cloud Partner Navigator.
- Switch to the organization for which you wish to register a Usage Meter or download usage reports.
- Under your username, click My Account.
- Click on the API Tokens tab.
- On the API Tokens page, click GENERATE TOKEN.
- Copy the token and click Continue.
Note: Save your refresh token somewhere as you will need it repeatedly to generate an access token for your usage API calls.
- In your API client, make the following POST Request to the Cloud Partner Navigator Service Gateway to generate an access token.
|
1 |
POST https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize |
This access token you will use to authenticate with Usage Insight when sending the request for registering your Usage Meter with a contract in the Commerce Portal.
See the sample request and response:
Sample cURL Code:
|
1 2 3 4 5 |
curl --location --request POST 'https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Accept: application/json' \ --header 'Cookie: incap_ses_875_1285679=dI6yChlNDWmSHUSOe6AkDJeH22MAAAAAVl2Twv8diGo4dJ3dWNmwZg==; nlbi_1285679=U7QpOt23TR0lxkHi+iiRRwAAAACv7L8J9/EtUtWlx9vSOrbq' \ --data-urlencode 'refresh_token=7lz-3tDup5w1xGV54iRHyhlEIq5Malq1Ii5ZgoYuCBqq95jbwIvTBLsCxu3RsNyU' |
Note: Replace the refresh token with your own generated from the CPN API Token page.
- Copy the access token from the response. Use it when executing the API requests described in this blog post.
Checking if a Usage Meter instance is registered
Before registering a Usage Meter, check if it has already been registered with Usage Insight.
Here is how to do it:
- Execute the following GET registration request:
|
1 |
GET https://ums.cloud.vmware.com/usage/api/v1/agent-registrations/um-uuid |
- Use the UUID of your Usage Meter.
- Use the generated access token to authenticate to the service.
- If your registration is successful, you will get the following response: Status 200 OK, also a contract number, and a site name. See the screenshot below:
Sample cURL Code
|
1 2 |
curl --location --request GET 'https://ums.cloud.vmware.com/usage/api/v1/agent-registrations/9273dc74-2cef-4009-abcc-69fe9ccfde8d' \ --header 'Authorization: Bearer |
Note: Replace the Usage Meter UUID with your own. You can find it in your Usage Meter web application, under the About tab. Use the access token you generated for the authorization.
Registering a Usage Meter in the Commerce Portal
To register your Usage Meter with a contract in the Commerce Portal using the new REST API, you will need to authenticate with the Usage Insight service to which to send the registration request.
Here are the exact steps:
- Send a POST request to the Usage Insight service, which will handle the registration of the Usage Meter instance with a contract in the Commerce Portal.
|
1 |
POST https://ums.cloud.vmware.com/usage/api/v1/agent-registrations |
- In the body of the request, you must specify the following:
|
1 2 3 4 5 6 7 8 9 10 |
{ "agentId": "88531d1c-296e-4b47-8431-c0e8182148e7", // this is the UM UUID "connectivityMode": "ONLINE", //the mode in which UM will report data "contractNumber": "1012345", // the number of the VCPP contract with which you will register your UM "label": "um46-reg-demo", // the name you will give to your Usage Meter "meteringMode": "PRODUCTION", // the mode in which the data will be reported to the Commerce Portal "siteName": "Site A", // the site of the organization with which you will register this UM "version": "4.6" // The UM version Note: Do not use 4.x here, as the request will return an error. } |
- For authorization with the Usage Insight service, use the generated access token.
- Execute the request. If the Usage Meter registration is successful, then you will get code 202. See an example below:
If this Usage Meter has already been registered, you will get code 201.
- Go to the VMware Commerce portal to verify if the Usage Meter is registered with the specified contract and org site.
Sample cURL code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
curl --location --request POST 'https://ums.cloud.vmware.com/usage/api/v1/agent-registrations' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer \ --data-raw '{ "agentId": "88531d1c-296e-4b47-8431-c0e8182148e7", "connectivityMode": "ONLINE", "contractNumber": "1012345", "label": "um46-reg-demo", "meteringMode": "PRODUCTION", "siteName": "Site A", "version": "4.6" }' |
Note: Use your Usage Meter details and provide the access token you generated from the CPN refresh token.
Getting Information on All Usage Reports
Usage report API is now fully documented and is ready to be implemented in your organization. Here are the API requests that you can use to automate your usage report generation:
- Get information on all usage reports for a specific month and year for an organization
- Download a specific usage report by specifying its reference number retrieved from the get information on all usage reports API request
- Finally, get information on all reports associated with a usage meter UUID
Get Information on All Usage Reports for a Month
To get information on all usage reports of all Usage Meters in your CPN organization for a particular month and year, do the following:
- Execute GET https://ums.cloud.vmware.com/usage/api/v1/reports/2023/1 request to the Usage Insight service endpoint.
- Provide the month and year for which you wish to get all usage reports for all your registered Usage Meters.
- Authenticate to Usage Insight with the generated access token.
- If your request is successful, you will get Status 200 OK and a list of all usage reports associated with Usage Meter UUID. Here is an example of the response.
Sample cURL code
|
1 2 3 |
curl --location --request GET 'https://ums.cloud.vmware.com/usage/api/v1/reports/2023/01' \ --header 'Authorization: Bearer |
Note: Specify a month and a year for which to get information on all usage reports of a CPN organization.
Download a Specific Usage Report
To download a specific Usage Meter report, you need to provide in the parameters of your API request the reference number of that report. To find it, you need first to trigger GET information on all usage reports request. See the Getting Information on All Usage Reports for a Month section.
Here is how to download a specific Usage Meter report:
1. Make a GET request to https://ums.cloud.vmware.com/usage/api/v1/reports and specify the following:
- In the parameters of the request enter the reference number of the report. This value you must retrieve from the request explained in the Get Information on All Reports for a Month section.
- In the header of the request, you must specify the Accept parameter to be the content type of the report (again get this information from the get information on all usage reports API request)
- Authenticate with the Usage Insight service by using the generated access code.
- The response will be Status 200 OK if the request is successful, and you also get the text of the zipped report. In this example, the response is not decoded as Postman does node decode the content of zipped files.
- Save the response. In Postman, the way to do it is to click Save Response. This way you will download the referenced report.
Sample cURL code
|
1 2 3 4 |
curl --location --request GET 'https://ums.cloud.vmware.com/usage/api/v1/reports?ref=nPrNoRBz9cjia2YSJvUPpBNQY3raKZidg7dGzdAkm%2FzNGJFpVEKmccXNchrMZA7tHJKtWuOtbwmj0rB1gXb48PMQx0iSYR%2Fl1MYB03sZa7G8A4JGppTBszl6gmVXapXFjO2g' \ --header 'Accept: text/tab-separated-values+gzip' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer |
Note: Use the reference number of the report you wish to download.
Get Information on all Reports of a Usage Meter Instance
To get information on all usage reports of specific Usage Meters, do the following:
- Execute a GET request to the Usage Insight service, specifying the month and year for which you wish to get information and the uuid of the usage meter with which the reports are associated.
- Provide the generated access token with which to authenticate with the Usage Insight service.
- You will get the following response: Status 200 OK and the details of all reports related to this Usage Meter and their reference numbers.
Note: Use the reference number of the reports you wish to download with the GET / https://ums.cloud.vmware.com/usage/api/v1/reports API request.
Here is an example of the request and its response.
Sample cURL Code
|
1 2 3 |
curl --location --request GET 'https://ums.cloud.vmware.com/usage/api/v1/reports/2023/01/9273dc74-2cef-4009-abcc-69fe9ccfde8d' \ --header 'Authorization: Bearer |
Note: Specify a month and a year for which to get information on all usage reports associated with the uuid of your usage meter. Replace the Usage Meter UUID in this example with your own.
Conclusion
In a conclusion, you can use those APIs as part of your Usage Meter reporting automation. Now with the registration of the Usage Meter instance, you can fully automate the installation and configuration of your Usage Meter instances.
We will keep enhancing and expanding our Usage Meter-related APIs and want to hear from you about what other APIs we can develop to improve your reporting experience.
The rest of the Usage Meter API requests can be found here. Cloud Partner Navigator and Commerce Portal APIs can be found here and here.
For more questions or queries, leave a comment below or send us an email at [email protected]. There is a Slack channel available to cloud providers where you can also ask your questions.
