Introduction

Inventory reports come to fit into the missing part of the vSphere Client, either web or windows based, to export certain Virtual Machine properties in a portable manner. The RESTful API offers the /v2/inventory resource allowing two main actions: create a submission to generate a report with specific properties or a default set and to download the report in CSV and JSON format. Also, a copy of the generated report will be stored in your personal space available in https://vskey-stor.eis.utoronto.ca under the inventory directory.

The following table shows a brief description and HTTP methods allowed to submit and download an inventory report of your VMs.

On this page:

Resource	URI	Description
Inventory Request	/inventory	Generate and download VM inventory files in CSV or JSON format.
Inventory Download	/inventory/<request_id>	Download generated inventory file in CSV or JSON format
Inventory Properties	/inventory/options	Available inventory options

TK stores the Cloud API Token generated as a result of the following POST request to the /auth/request-token resource:

curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username>

For example, extracting the token with the jq command:

TK=$(curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username> | jq -r '.token')

Create

Creating an inventory report requires a POST request to /inventory and only one attribute: properties, which will store a list of supported properties in JSON format:

{"properties": ["uuid", "name", "cpu", "folder"]}  # only 4 properties in report

The following table describe the only attribute of this resource:

Attribute	Description	Type	Options	Default
properties	Elements to be included in report	array	Listed in Inventory#Properties section	All listed in Inventory#Properties section
		string	List of elements using ";" as separator	All listed in Inventory#Properties section
format	Report format. Currently supporting CSV (default) and JSON.	string	csv or json	csv

HTTPie

http POST "https://vss-api.eis.utoronto.ca/v2/inventory" "Authorization: Bearer $TK" properties:='["cpu", "folder"]'
http POST "https://vss-api.eis.utoronto.ca/v2/inventory" "Authorization: Bearer $TK" properties='cpu;folder'

CURL

curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/inventory -d '{"properties": ["cpu", "folder"]}'
curl -H "Content-Type: application/json" -H "Authorization: Bearer $TK" -X POST "https://vss-api.eis.utoronto.ca/v2/inventory -d '{"properties": "cpu;folder"}'

Submitting an empty properties attribute will generate a full report (including all supported properties).

Response

A request has been submitted as well as a task. Both elements can be got from the Response Body and Headers as show below:

Response Headers

HTTP/1.1 202 ACCEPTED
Allow: POST, OPTIONS
Connection: keep-alive
Content-Length: 410
Content-Type: application/json
Date: Sun, 01 May 2016 03:17:13 GMT
Location: https://vss-api.eis.utoronto.ca/v2/request/task/6cdd8400-8ba2-4995-9f1e-7e9207f74cb9
Server: nginx
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7199
X-RateLimit-Reset: 1462075200

Response Body

{
    "data": {
        "_links": {
            "request": "https://vss-api.eis.utoronto.ca/v2/request/inventory/3", 
            "task": "https://vss-api.eis.utoronto.ca/v2/request/task/6cdd8400-8ba2-4995-9f1e-7e9207f74cb9"
        }, 
        "message": "New VM Inventory Request has been accepted for processing", 
        "name": "Accepted", 
        "status": 202
    }, 
    "meta": {
        "time": "0.35453s", 
        "user": "jm"
    }
}

Request

The request object stores the resulting inventory report CSV filename if generated, this is in the name attribute, but also an URL to access the file is generated in the object _links, file. That particular URL will make available the file via the API, however if you prefer going to VSKEY-STOR be sure transferred attribute is true, then 7e32f6df-3749-48ce-bd19-2e80397d0d24.csv will be available under https://vskey-stor.eis.utoronto.ca/inventory/7e32f6df-3749-48ce-bd19-2e80397d0d24.csv.

Inventory Request

{
    "_link": {
        "request": "https://vss-ws.eis.utoronto.ca/v2/request/inventory/", 
        "self": "https://vss-ws.eis.utoronto.ca/v2/request/inventory/3"
    }, 
    "data": {
        "_links": {
            "file": "https://vss-ws.eis.utoronto.ca/v2/inventory/3", 
            "task": "https://vss-ws.eis.utoronto.ca/v2/request/task/722f9c58-0e49-42b6-bd47-bfa689ab64b6"
        }, 
        "created_on": "2016-04-30 23:40:55 EDT", 
        "hits": 1, 
        "id": 3, 
        "message": {
            "errors": [], 
            "warnings": [
                "Inventory Report has been created 7e32f6df-3749-48ce-bd19-2e80397d0d24.csv"
            ]
        }, 
        "name": "7e32f6df-3749-48ce-bd19-2e80397d0d24.csv", 
        "properties": {
            "data": [
                "uuid", 
                "name", 
                "cPU", 
                "folder"
            ]
        }, 
        "run_time": 0.0, 
        "status": "Processed", 
        "task_id": "722f9c58-0e49-42b6-bd47-bfa689ab64b6", 
        "transferred": true, 
        "updated_on": "2016-04-30 23:41:33 EDT", 
        "user": {
            "_links": {
                "self": "https://vss-ws.eis.utoronto.ca/v2/user"
            }, 
            "id": 1, 
            "username": "jm"
        }
    }, 
    "meta": {
        "count": 13, 
        "time": "0.00995s", 
        "user": "jm"
    }
}

Properties

Id	Name	Description
uuid	VM Uuid	Universal Unique Identifier.
name	VM Name	Virtual Machine human readable name.
isTemplate	Template status	Whether a VM is template.
osId	Operating System Identifier	OS configured in Virtual Machine settings.
guestOsId	Guest Operating System Identifier	OS running in the Virtual Machine.
ipAddress	IP Address	Main ip address if any.
hostNmae	Host Name	Main hostname if any.
cpu	CPU	Number of CPUs.
memory	Memory	Memory size in GB.
diskTotalSize	Hard Disks Total Size	Sum of Virtual Disks Capacity in GB.
diskCount	Hard Disks Count	Number of virtual Disks.
disks	Hard Disks	Summary of virtual disks.
cdBacking	CD/DVD Backing	CD/DVD unit with backing. Including ISO path, client or none.
folder	Folder	Logical folder. This property also adds folderMoId which is the folder managed object Id
haGroup	HA Group settings	HA Group tag settings.
networkIds	Network IDs	NIC and Mac Addresses
nicCount	NIC Count	Number of virtual NICs
nics	NICs	Summary of NICs.
hardwareVersion	Hardware Version	VMX virtual hardware version
status	Status	Connected, disconnected
state	State	Virtual Machine Power State
domain	Fault Domain	Cluster Fault domain. This property also adds domainMoId which is the fault domain managed object Id
provisionedSpace	Provisioned Space	Total size allocated to the VM in GB.
usedSpace	Used Space	Real space used by the VM in GB.
uncommittedSpace	Uncommitted Space	Space allocated but not used in GB.
vmtVersion	VMware Tools Version Status	Whether VMware Tools is up to date or outdated
vmtRunning	VMware Tools Running Status	Running, not running, not installed
snapshot	Snapshot	Summary of snapshots
requested	Requested	Timestamp when VM was requested
inform	Inform	Informational contacts
client	Client	Client name
admin	Admin	Virtual Machine main administrator
service	VSS Service	VSS Service
clientNotes	ClientNotes	Custom client notes

Download

As mentioned before, a HTTP GET request to /v2/inventory/<request_id> must be made to download the generated file or going to https://vskey-stor.eis.utoronto.ca/inventory/<file_name>. The following section exemplifies how to download an already generated file from the API:

HTTPie

http GET "https://vss-api.eis.utoronto.ca/v2/inventory/3" "Authorization: Bearer $TK"

CURL

curl -H "Authorization: Bearer $TK" -X GET "https://vss-api.eis.utoronto.ca/v2/inventory/3

Response

Headers

HTTP/1.1 200 OK
Allow: HEAD, OPTIONS, GET
Connection: keep-alive
Content-Disposition: attachment; filename=7e32f6df-3749-48ce-bd19-2e80397d0d24.csv
Content-Length: 2278
Content-Type: text/csv
Date: Sun, 01 May 2016 03:53:02 GMT
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7184
X-RateLimit-Reset: 1462075200

Body

"Uuid","Name","CPU","Folder"
"50121c29-33af-22a8-6195-607527229087","1603P-docker-node1","4","VSS > Sandbox > jm > Swarm"
"5012dae7-925b-b97a-97b8-4a40e5663147","Ubuntu_64b-14.10","1","Public > Templates"
"5012f4f0-443b-9cc4-1256-3d78093e7d30","Ubuntu_64b-14.04","1","Public > Templates"