Recently I published a blog talking about the vCloud Director 9.0 for Service Providers API.  Before I move onto other API topics, I decided to write something on consuming VMware vCloud Usage Meter 3.6 via the API and introduce a few new API interactions in this post.

This blog assumes you are familiar with vCloud Usage Meter and it’s functionality.

Why am I writing about the vCloud Usage Meter API?  While most VMware Cloud Service Providers (CSPs) work with vCloud Usage Meter through the web interface.  There may be some larger and more dynamic environments which require a CSP to interact with the vCloud Usage Meter API and I would like to bring some awareness to this.

I would also like to highlight some of the new API calls we introduced in vCloud Usage Meter 3.6.  Specifically, an API call to get a ZIP file containing a specified report, and API calls to interact with NSX Manager.

Before We Get Started

First, download and install vCloud Usage Meter 3.6 in your environment.  The download link is found here.

Download the vCloud Usage Meter Users Guide.  I will be referring to several items in this document as we go along, specifically when we cover End User Reporting API calls.  It is a good idea to familiarize yourself with the Object and Value Types in Customer Rules, you will need an understanding of these objects when we create a Customer Rule through the API.

Download the vCloud Usage Meter 3.6 API Reference.  This document contains all the API calls for vCloud Usage Meter 3.6.

The vCloud Usage Meter API is a RESTful API.  As I discussed in my first blog post you need to find a REST based API Client.  I like to use Postman. There are others that function as plug-ins to either Chrome or FireFox browsers that work well.  Postman can be downloaded here.

Ensure you have the latest VMware Cloud Provider Program Usage Guide, you will find this in Partner Central.  We will be covering End User Reporting and it is a good idea to have a solid understanding of this.

Finally, ensure you have downloaded the VMware Cloud Provider Program Program Guide from Partner Central.  We will be covering End User Reporting and this is covered in the Program Guide.

Introduction to Postman

Looking at the Postman GUI, there is a section to enter the API Request, authenticate to the API and a place to see the response.  REST based APIs are made up of a simple set of commands some examples are: GET, POST, PUT, DELETE.

vCloud Usage Meter 3.6 API

Each API call you make will have two Request Headers (I go into detail below and show you how to add these) namely:

• vCloud Usage Meter API Token Header (used for authentication).
• Content-Type Header (must be sent with every API request).

Step 1: Authenticating to the API

All vCloud Usage Meter API calls require authentication.  vCloud Usage Meter uses cURL to authenticate (this is a very common authentication method for REST APIs).  The first step is to obtain an API Authentication key from vCloud Usage Meter.

You can obtain this token in one of two ways.  Firstly, from the Usage Meter web interface.  We will go into vCloud Usage Meter web page, click Manage, then click the API tab, and click Add Admin Token and copy the token:

Secondly, you can also generate this token from the console by using the “umtoken” command once you have logged into the Usage Meter:

Once you have your token, this token is added into the Postman API Client as a header (you will ignore the authentication dropdown under the authentication tab), go to the Headers tab and add your key to this section.  The key name is always “x-usagemeter-authorization” and enter your token key in the value field.  This will ensure every API command that is sent, has this token with the header.

Like this: x-usagemeter-authorization: TOKJ1QDQO3QD1VR1MQN03U2BA1WQR2PY04T

Step 2: Adding Request Header

Once the authentication header is in place.  The next step is to add a “Content-Type” Header.  The key name is “Content-Type” and enter “application/xml” in the value field.  This will ensure every API command that is sent, has this token with the header.

Like this: Content-Type: application/xml 

Now that you are authenticated, and the required Headers are in place.  We are ready to make some API requests.

Step 3: Your First API Request – Getting a list of Customers

The first API request we will make will give us a listing of customers already in the vCloud Usage Meter.

First, we will use the drop down to select GET then you will enter our first request.  The request query will consist of the FQDN and the port of vCloud Usage Meter followed by api/customers.  Note, all these queries are case sensitive.  Like this:

https://FQDN-of-UM:8443/um/api/customers

Click the Send button.  Once you have a response, look at the XML output in the Body section.  You will receive a Status: 200 OK, this confirms you have successfully created a session to vCloud Usage Meter.  Well done!

You will see from the below screenshot next to the name field, we have VCPPCustomer1.  In this case, automatically added by vCloud Director.

If we look at the vCloud Usage Meter web interface under the Customers tab.  We see we have our VCPPCustomer1.

Step 4: Creating a Customer

Creating a customer is essential to End User Reporting, particularly when tying a customers usage to point consumed.  If you are using vCloud Director, vCloud Usage Meter automatically detects customers in vCloud Director and adds these entries automatically.

Using Postman, use the drop down to select POST (POST tells the API we are going to send information to vCloud Usage Meter).  The request query will consist of the FQDN and the port of vCloud Usage Meter followed by api/customer.  Like this:

https://FQDN-of-UM:8443/um/api/customer

Next, Click on the Body tab.  Ensure the “raw” radio button is selected.  Enter the following information, keeping the exact format (Note, the areas I have bolded are the areas you will customize for each customer added, this example is taken from API reference guide):

<customer xmlns=”http://www.vmware.com/UM”&gt;
<name>Customer Name</name>
<country>US</country>
<postalCode>90210</postalCode>
</customer>

Click the Send button, and look at the response pane.  You will receive a Status: 201 Created, this means you have successfully created a customer.

Now we look at vCloud Usage Meter and we see the customer VCPP New Customer is created.

Step 5: Getting the vCenter Server List

Several API calls require you to include the vCenter Server ID in the API call.  For that, we need to get a list of active vCenter Servers on this vCloud Usage Meter Instance.

Using Postman, use the drop down to select GET and enter the following query in the request field and click the Send button:

https://FQDN-of-UM:8443/um/api/vcServers

Look at the response pane.  We see in my example I have one active vCenter server attached, and the vCenter ID next to the <id> entry is 3.  This will display all active vCenter Servers attached to vCloud Usage Meter.  Take note of this vCenter ID – you will need this in the next step.

Step 6: Creating a Customer Rule

This is where the vCloud Usage Meter API is powerful, the ability to create a Customer rule for End User Reporting.  This is mostly applicable to customers using vCenter, as vCloud Director automatically creates both Customers and Rules.  When we create a rule, we are associating VMs with a specific Customer, and creating a hierarchy very similar to the way customers are defined in your vCenter or vCloud Director environment today.  This is where you will need to be familiar with the Object and Value Types in Customer Rules.  I have included some screenshots from the documentation detailing these out:

When we create a rule, we are associating VMs with a specific customer, and creating a hierarchy very similar to the way customers are defined in your vCenter environment today.  This is where you will need to be familiar with the Object and Value Types in Customer Rules.  I have included some screenshots from the documentation detailing these out:

Once you have reviewed the above tables.  I have included some examples of the ways customers could be defined in vCenter:

• Customers have a dedicated vCenter.
• Customers each have their own Resource Pool within vCenter.
• Customers are sorted by Folder in vCenter.

Once you have established how the vCenter hierarchy for your customers is setup, we can proceed with creating a Customer rule.

For this step, you need both the vCenter Server ID and the Customer name (both examples of how to obtain this information is included in the examples above).

Using Postman, use the drop down to select POST (because we are going to send information to vCloud Usage Meter) and enter the following query in the request field:

https://FQDN-of-UM:8443/um/api/rule

Next, Click on the Body tab.  Ensure the “raw” radio button is selected.  Here we have a number of options, we can create a Customer Rule which will pick up on every VM in the vCenter, or we can create a rule to pick up VMs in a specific folder.  Review the tables above for the values you can enter into the ObjectType and ValueType fields.

In this example, we are creating a rule to capture every VM in the vCenter Server.  Enter the following string, keeping the format (Note, the areas I have bolded are the areas you will customize for each rule added).   Then press the Send button:

<rule xmlns=”http://www.vmware.com/UM”&gt;
<vcServerId>3</vcServerId>
<customerName>Customer Name</customerName>
<objectType>vCenter Server</objectType>
<valueType>Unique ID</valueType>
</rule>

Look at the response pane.  You will receive a Status: 201 Created, this means you have successfully created a customer rule.  Refer to the documentation for further examples.

Conclusion

This wraps up this post on the vCloud Usage Meter 3.6 API.

If you have any specific questions about the vCloud Usage Meter API, feel free to leave a comment.