In today’s fast-paced IT landscape, virtualization is a cornerstone of modern infrastructure, and VMware’s vSphere continues to lead the way. To manage these dynamic environments efficiently, VMware provides powerful APIs that enable administrators and developers to automate tasks, gather crucial data, and optimize operations. Among these APIs, the Virtual Infrastructure (VI JSON) JSON API has gained significant attention for its simplicity and ease of use in managing virtual environments.
In this post, we’ll walk through how to use VMware’s PropertyCollector and ContainerView APIs with JSON. These APIs help retrieve and manage data from your VMware environment in a structured way. We’ll cover the necessary steps to establish a session, create a container view, and retrieve properties using these powerful tools.
Steps Overview:
- Create a session and obtain a token
- Create a container view
- Use
RetrievePropertiesExto collect data - Use
ContinueRetrievePropertiesExto get more results (if needed) - Optionally, cancel the process with
CancelRetrievePropertiesEx
Let’s go step by step.
1. Create a Session and Obtain a Token
Before accessing any data, you need to authenticate with the API by creating a session and obtaining a token. This token will be used to authenticate all subsequent API calls.
API Endpoint:POST https://{{ip}}/api/session
Request:
- Body: Empty
- Authentication: Basic (username and password)
If successful, you’ll receive a 201 Created status and a token in the response body. This token should be included in the headers of all further API requests, using the key vmware-api-session-id.
For more details, refer to the Create Session | vSphere Automation API Documentation.
2. Create a Container View using VI JSON
A container view is a list of managed objects (VMs, hosts, etc.) within a specific folder or inventory. This is useful for working with large VMware environments where you want to target specific objects or types of objects.
API Endpoint:POST https://{{ip}}/sdk/vim25/8.0.2.0/ViewManager/ViewManager/CreateContainerView
Request Body:
json
Copy code
{
"container": {
"_typeName": "ManagedObjectReference",
"type": "Folder",
"value": "group-d1"
},
"recursive": true
}
- Container: A reference to an instance of a Folder, Datacenter, ComputeResource, ResourcePool, or HostSystem object. (
group-d1in this case, The root folder of the inventory). - Recursive: Set to true to include objects from sub-containers.
The response will include a ManagedObjectReference of type ContainerView, which will be used in the next step.
For more details, refer to the View Manager | VI JSON API.
3. Retrieve Properties Using RetrievePropertiesEx via VI JSON
Now that we have a container view, we can retrieve the properties of the managed objects within it. This could include hosts, virtual machines, and other inventory objects.
API Endpoint:POST https://{{ip}}/sdk/vim25/8.0.2.0/PropertyCollector/propertyCollector/RetrievePropertiesEx
Request Body:
json
Copy code
{
"specSet": [
{
"_typeName": "PropertyFilterSpec",
“propSet”: [
{
"type": "HostSystem",
"all": false,
"pathSet": ["name", "runtime"]
},
{
"type": "VirtualMachine",
"all": false,
"pathSet": ["name"]
}
],
“objectSet”: [
{
"obj": {
"type": "ContainerView",
"value": "session[529f6215-1d11-789a-6c28-ec498e7bb647]529e4d9b-9c4e-f02c-f356-e514612ad14b"
},
“selectSet”: [
{
"name": "TraversalSpec",
"path": "view",
"type": "ContainerView"
}
]
}
]
}
],
"options": {
"maxObjects": 1
}
}
- PropertyFilterSpec: Specifies the properties we want to retrieve. In this example, we’re retrieving the
nameandruntimeofHostSystemobjects, and just thenameofVirtualMachineobjects. - ContainerView: The view created in step 2, specifying the range of objects we’re interested in.
- MaxObjects: Limits the number of results returned at once.
The response contains a RetrieveResult, including the properties of the managed objects and a token for further results.
4. Continue Retrieving Properties Using ContinueRetrievePropertiesEx
If the response from RetrievePropertiesEx includes a token, this means there are more results to fetch. Use the token to get the next batch of data.
API Endpoint:POST https://{{ip}}/sdk/vim25/8.0.2.0/PropertyCollector/propertyCollector/ContinueRetrievePropertiesEx
Request Body:
json
Copy code
{
"token": "0"
}
The response will be similar to that of RetrievePropertiesEx, with another token if there are more results. Repeat this process until the token is no longer provided, indicating all data has been retrieved.
5. Cancel Retrieval with CancelRetrievePropertiesEx using VI JSON
If you no longer need the data or want to stop the process before retrieving all the results, use CancelRetrievePropertiesEx.
API Endpoint:POST https://{{ip}}/sdk/vim25/8.0.2.0/PropertyCollector/propertyCollector/CancelRetrievePropertiesEx
Request Body:
json
Copy code
{
"token": "1"
}
This will terminate the data retrieval process.
Conclusion
The PropertyCollector and ContainerView APIs offer a flexible and efficient way to retrieve data from your VMware environment. Nowadays they are even better because of the VI JSON protocol introduced with vSphere 8.0 Update1. By following the above steps, you can create a session, generate a container view, and collect object properties, all while managing large datasets using tokens for pagination.
For further details on the API methods used here, check the official documentation:
