We have an vital announcement to make – Usage Meter and Usage Report APIs at the moment are a part of the Cloud Provider Navigator and will be accessed from the Cloud Provider part on developer.vmware.com. Furthermore, there’s a new API for registering Usage Meter with a contract within the VCPP Commerce Portal. Here is how the Usage API web page appears to be like like on developer.vmware.com.
In this weblog publish, we are going to reveal the steps of registering a Usage Meter occasion, getting info and downloading utilization stories.
Before utilizing the aforementioned APIs, there are a couple of conditions that should be glad.
Prerequisites
- A refresh token generated from Cloud Partner Navigator/User Profile/API Tokens. Information will be discovered right here or scroll to the Generating an Access Token part on this weblog publish.
- An entry token generated from the Cloud Partner Navigator refresh token. Read right here or scroll to the Generating an Access Token part on this weblog publish.
Note: A generated entry token expires after half-hour so you should regenerate it every so often.
Generating an Access Token for Authentication
To execute the API requests described on this weblog publish, you will want to generate a refresh token from Cloud Partner Navigator (CPN) after which execute a POST request to the Cloud Services Portal gateway to get the entry token with which you’ll authenticate with the CPN service – Usage Insight.
The Usage Insight service is the service which is able to register your Usage Meter with a contract within the Commerce Portal and generate stories for a Usage Meter occasion.
Now let’s see how you can generate an entry token:
- Log in to Cloud Partner Navigator.
- Switch to the group for which you want to register a Usage Meter or obtain utilization stories.
- Under your username, click on My Account.
- Click on the API Tokens tab.
- In the API Tokens web page, click on GENERATE TOKEN.
- Copy the token and click on Continue.
Note: Save your refresh token someplace as you will want it repeatedly to generate an entry token in your utilization API calls.
- In your API consumer, make the next POST Request to the Cloud Partner Navigator Service Gateway to generate an entry token.
|
POST https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize |
This entry token you’ll use to authenticate with Usage Insight when sending the request for registering your Usage Meter with a contract within the Commerce Portal.
See the pattern request and response:
Sample cURL Code:
|
curl —location —request POST ‘https://console-.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize’ —header ‘Content-Type: utility/x-www-form-urlencoded’ —header ‘Accept: utility/json’ —header ‘Cookie: incap_ses_875_1285679=dI6yChlNDWmSHUSOe6AkDJeH22MAAAAAVl2Twv8diGo4dJ3dWNmwZg==; nlbi_1285679=U7QpOt23TR0lxkHi+iiRRwAAAACv7L8J9/EtUtWlx9vSOrbq’ —information–urlencode ‘refresh_token=7lz-3tDup5w1xGV54iRHyhlEIq5Malq1Ii5ZgoYuCBqq95jbwIvTBLsCxu3RsNyU’ |
Note: Replace the refresh token with your personal generated from the CPN API Token web page.
- Copy the entry token from the response. Use it when executing the API requests described on this weblog publish.
Checking if a Usage Meter occasion is registered
Before registering a Usage Meter, test if it has already been registered with Usage Insight.
Here is how you can do it:
- Execute the next GET registration request:
|
GET https://ums.vmware.com/utilization/api/v1/agent-registrations/um-uuid |
- Use the UUID of your Usage Meter.
- Use the generated entry token to authenticate to the service.
- If your registration is profitable, you’ll get the next response: Status 200 OK, additionally a contract quantity, and a website identify. See the screenshot beneath:
Sample cURL Code
|
curl —location —request GET ‘https://ums.vmware.com/usage/api/v1/agent-registrations/9273dc74-2cef-4009-abcc-69fe9ccfde8d’ —header ‘Authorization: Bearer |
Note: Replace the Usage Meter UUID with your personal. You can discover it in your Usage Meter internet utility, beneath the About tab. Use the entry token you generated for the authorization.
Registering a Usage Meter within the Commerce Portal
To register your Usage Meter with a contract within the Commerce Portal utilizing the brand new REST API, you will want to authenticate with the Usage Insight service to which to ship the registration request.
Here are the precise steps:
- Send POST request to the Usage Insight service, which is able to deal with the registration of the Usage Meter occasion with a contract within the Commerce Portal.
|
POST https://ums.vmware.com/utilization/api/v1/agent-registrations |
- In the physique of the request, you have to specify the next:
|
{ “agentId”: “88531d1c-296e-4b47-8431-c0e8182148e7”, // that is the UM UUID “connectivityMode”: “ONLINE”, //the mode during which UM will report information “contractNumber”: “1012345”, // the variety of the VCPP contract with which you’ll register your UM “label”: “um46-reg-demo”, // the identify you’ll give to your Usage Meter “meteringMode”: “PRODUCTION”, // the mode during which the info will probably be reported to the Commerce Portal “siteName”: “Site A”, // the positioning of the group with which you’ll register this UM “model”: “4.6” // The UM model Note: Do not use 4.x right here, because the request will return an error. }
|
- For the authorization with the Usage Insight service, use the generated entry token.
- Execute the request. If the Usage Meter registration is profitable, then you’ll get code 202. See an instance beneath:
If this Usage Meter has already been registered, you’ll get code 201.
- Go to the VMware Commerce portal to confirm if Usage Meter is registered with the required contract and org website.
Sample cURL code
|
curl —location —request POST ‘https://ums.vmware.com/usage/api/v1/agent-registrations’ —header ‘Content-Type: utility/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”, “model”: “4.6”
}‘ |
Note: Use your Usage Meter particulars an present the entry token you generated from the CPN refresh token.
Getting Information on All Usage Reports
Usage report API is now dully documented and is able to be applied in your group. Here are the API requests that you should use to automate your utilization report technology:
- Get info on all utilization stories for a particular month and 12 months for a company
- Download a particular utilization report by specifying its reference quantity retrieved from the get info on all utilization stories API request
- Finally, get info on all stories related by a utilization meter UUID
Get Information on All Usage Reports for a Month
To get info on all utilization stories of all Usage Meters in your CPN group for a specific month and 12 months, do the next:
- Execute GET https://ums.vmware.com/usage/api/v1/reports/2023/1 request to the Usage Insight service endpoint.
- Provide the month and 12 months for which you want to get all utilization stories for all of your registered Usage Meters.
- Authenticate to Usage Insight with the generated entry token.
- If your request is profitable, you’ll get Status 200 OK and an inventory of all utilization stories related to Usage Meter UUID. Here is an instance of the response.
Sample cURL code
|
curl —location —request GET ‘https://ums.vmware.com/usage/api/v1/reports/2023/01’ —header ‘Authorization: Bearer
|
Note: Specify a month and a 12 months for which to get info on all utilization stories of a CPN group.
Download a Specific Usage Report
To obtain a particular Usage Meter report, you should present within the parameters of your API request the reference variety of that report. To discover it, you want first to set off GET info on all utilization stories request. See the Getting Information on All Usage Reports for a Month part.
Here is how you can obtain a particular Usage Meter report:
1. Make a GET request to https://ums.vmware.com/usage/api/v1/reports and specify the next:
- In the parameters of the request enter the reference variety of the report. This worth you have to retrieve from the request defined within the Get Information on All Reports for a Month part.
- In the header of the request, you have to specify the Accept parameter to be the content material kind of the report (once more get this info from the get info on all utilization stories API request)
- Authenticate to the Usage Insight service by utilizing the generated entry code.
- The response will probably be Status 200 OK if the request is profitable, and also you additionally get the textual content of the zipped report. In this instance, the response isn’t decoded as Postman does node decode the content material of zipped recordsdata.
- Save the response. In Postman, the way in which to do it’s to click on Save Response. This manner you’ll obtain the referenced report.
Sample cURL code
|
curl —location —request GET ‘https://ums.vmware.com/usage/api/v1/reports?ref=nPrNoRBz9cjia2YSJvUPpBNQY3raKZidg7dGzdAkm%2FzNGJFpVEKmccXNchrMZA7tHJKtWuOtbwmj0rB1gXb48PMQx0iSYR%2Fl1MYB03sZa7G8A4JGppTBszl6gmVXapXFjO2g’ —header ‘Accept: textual content/tab-separated-values+gzip’ —header ‘Content-Type: utility/json’ —header ‘Authorization: Bearer |
Note: Use the reference variety of the report you want to obtain the your generated entry token.
Get Information on all Reports of a Usage Meter Instance
To get info on all utilization stories of a particular Usage Meters, do the next:
- Execute a GET request to the Usage Insight service, specifying the month and 12 months for which you want to get info and the uuid of the utilization meter with which the stories are related.
- Provide the generated entry token with which to authenticate with the Usage Insight service.
- You will get the next response: Status 200 OK and the small print of all stories associated to this Usage Meter and their reference numbers.
Note: Use the reference variety of the stories you want to obtain with the GET / https://ums.vmware.com/usage/api/v1/reports API request.
Here is an instance of the request and its response.
Sample cURL Code
|
curl —location —request GET ‘https://ums.vmware.com/usage/api/v1/reports/2023/01/9273dc74-2cef-4009-abcc-69fe9ccfde8d’ —header ‘Authorization: Bearer
|
Note: Specify a month and a 12 months for which to get info on all utilization stories related to the uuid of your utilization meter. Replace the Usage Meter UUID on this instance with your personal.
Conclusion
In a conclusion, you should use these APIs as a part of your Usage Meter reporting automation. Now with the registration of the Usage Meter occasion you possibly can absolutely automate the set up and configuration of your Usage Meter cases.
We will hold enhancing and increasing our Usage Meter-related APIs and need to hear from you about what different APIs we are able to develop to enhance your reporting expertise.
The remainder of the Usage Meter API requests will be discovered right here. Cloud Partner Navigator and Commerce Portal APIs will be discovered right here and right here.
For extra questions or queries, go away a remark beneath or ship us an electronic mail to usagemeter@vmware.com. There is a Slack channel accessible to cloud suppliers the place you may as well ask your questions.