Programming Guide VRealize. Automation 7.1 V Realize Vrealize 71

User Manual: Pdf vRealize Automation - 7.1 - Programming Guide User Guide for VMware vRealize Software, Free Instruction Manual

Open the PDF directly: View PDF PDF.
Page Count: 389 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Programming Guide
vRealize Automation 7.1
Programming Guide
VMware, Inc. 2
You can find the most up-to-date technical documentation on the VMware website at:
https://docs.vmware.com/
If you have comments about this documentation, submit your feedback to
docfeedback@vmware.com
Copyright © 2008–2016 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
Contents
vRealize Automation Programming Guide 6
1Overview of the vRealize Automation REST API 7
2REST API Authentication 10
Using HTTP Bearer Tokens 10
Configure the Duration of an HTTP Bearer Token 10
Request an HTTP Bearer Token 11
Validate an HTTP Bearer Token 14
Delete an HTTP Bearer Token 14
3REST API Use Cases 16
Create a Tenant 17
Syntax for Displaying Your Current Tenants 20
Syntax for Requesting a New Tenant 23
Syntax for Listing All Tenant Identity Stores 26
Syntax for Linking an Identity Store to the Tenant 29
Syntax for Searching LDAP or Active Directory for a User 33
Syntax for Assigning a User to a Role 35
Syntax for Displaying all Roles Assigned to a User 36
Request a Machine 38
Syntax for Listing Shared and Private Catalog Items 40
Syntax for Getting Information for a Catalog Item 43
Syntax for Getting a Template Request for a Catalog Item 47
Syntax for Requesting a Machine 51
Syntax for Viewing Details of a Machine Request 54
Approve a Machine Request 57
Syntax for Listing Work Items 58
Syntax for Getting Work Item Details 65
Syntax for Constructing a JSON File to Approve a Machine Request 69
Syntax for Approving a Submitted Machine Request 73
Syntax for Updating Cost Information 75
List Provisioned Resources 78
Syntax for Displaying Your Provisioned Resources 79
Syntax for Displaying Provisioned Resources by Resource Type 81
Syntax for Displaying All Available Resource Types 84
Syntax for Displaying Provisioned Resources by Business Groups You Manage 86
Syntax for Viewing Machine Details 93
VMware, Inc. 3
Manage Provisioned Deployments 97
Syntax for Getting Deployment Details 99
Syntax for Navigating to the Children of a Deployed Resource 103
Perform a Day 2 Action: Power Off 109
Perform a Day 2 Action: Change Lease 111
Working with Reservations 112
Create a Reservation 113
Display a List of Reservations 263
Update a Reservation 274
Delete a Reservation 283
Working with Reservation Policies 285
List Reservation Policies 285
Create a Reservation Policy 288
Display a Reservation Policy by ID 290
Update a Reservation Policy 292
Delete a Reservation Policy 294
Working with Key Pairs 296
Get a Key Pair List 296
Create a Key Pair 301
Query a Key Pair 304
Update a Key Pair 305
Delete a Key Pair 308
Working with Network Profiles 310
Get a Network Profile List 311
Create a Network Profile 327
Query a Network Profile 332
Update a Network Profile 338
Delete a Network Profile 341
Get a List of Available IP Ranges for an IPAM Provider 342
Import and Export Content 359
Syntax for Listing Supported Content Types 362
Syntax for Listing Available Content 365
Syntax for Filtering Content by Content Type 369
Syntax for Creating a Package for Export 371
Syntax for Listing Packages in the Content Service 372
Syntax for Exporting a Package 374
Syntax for Validating a Content Bundle Before Importing 375
Syntax for Importing a Package 377
Understanding Blueprint Schema 379
Manage XaaS Content with Import and Export 381
Programming Guide
VMware, Inc. 4
4Related Tools and Documentation 385
Using the vRealize Automation API Reference 385
View Reference Information for an API 386
Using vRealize CloudClient 386
Using Third Party Tools 387
5Filtering and Formatting REST API Information 389
Programming Guide
VMware, Inc. 5
vRealize Automation Programming Guide
The Programming Guide provides information about the vRealize Automation REST APIs, including how
to use the REST API services and resources, create HTTP bearer tokens for authentication and
authorization, and construct REST API service calls.
Intended Audience
This information is intended for administrators and programmers who want to configure and manage
vRealize Automation programmatically using the vRealize Automation REST API. The guide focuses on
common use cases. For related information about all available REST API services, see in vRealize
Automation API Reference at https://www.vmware.com/support/pubs/vcac-pubs.html.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For
definitions of terms as they are used in VMware technical documentation, go to
https://www.vmware.com/support/pubs/vcac-pubs.html.
VMware, Inc. 6
Overview of the
vRealize Automation REST API 1
The vRealize Automation REST API provides consumer, administrator, and provider-level access to the
service catalog with the same services that support the vRealize Automation console user interface. You
can perform vRealize Automation functions programmatically by using REST API service calls.
The vRealize Automation REST API offers the following services and functions.
Table 1‑1. vRealize Automation REST API Services
Service Description
Approval Service Retrieve, create, update, and delete approval policies, policy types, policy
instances, and policy requests.
Branding Service Change the background and text colors, company logo, company name,
product name, tenant name, and other resources in the console.
Catalog Service Retrieve global and entitled catalog items, and entitlements for a catalog
item and its service that the current user can review. A consumer can
retrieve, edit, and submit a request form for a catalog item. A provider
can retrieve, register, update, and delete catalog items. Provision and
manage systems.
Component Registry Service Access and manage all services and serves as the central view for all
service lookups.
Composition Service Allows vRealize Automation services to register application components,
which the composition service manages so that they can be used in
composite blueprints.
Content Management Service Access and manage the content controller and package controller for
export and import processes. This includes export and import for
blueprints and software.
Endpoint Configuration Service Create, read, update and delete endpoint types, endpoint categories, and
endpoints.
Event Broker Service Provide a central location and a consistent way of recording events and
querying for events.
Forms Service Used internally by the vRealize Automation system to create, read,
update and delete (perform CRUD operations on) request forms for XaaS
components.
IaaS Proxy Provider Service Run a proxy service that acts as a bridge between the service catalog
and the IaaS provider to call other services, such as the catalog service,
composition service, reservation service, and event broker service.
VMware, Inc. 7
Table 1‑1. vRealize Automation REST API Services (Continued)
Service Description
Identity Service Manage tenants, business groups, SSO and custom groups, users, and
identity stores.
IP Address Management Service Allocate and deallocate IP addresses from IP address management
(IPAM) providers.
Licensing Service Retrieve permissions and post serial keys.
Management Service (Reclamation Service) Retrieve work item forms, callbacks, and tasks. Manage endpoint details
including tenant, password, user name, and endpoint URL. Retrieve
performance metrics. Retrieve and cancel reclamation requests.
Network Service Access and manage application network and security settings for
creating and configuring NAT and routed networks; creating load
balancers; and adding and configuring security groups, security tags and
security policies for application components.
Notification Service Configure and send notifications for several types of events such as the
successful completion of a catalog request or a required approval.
Orchestration Gateway Service Provides a gateway to VMware Realize Orchestrator (vRO) for services
running on vRealize Automation. By using the gateway, consumers of the
API can access a vRO instance, and initiate workflows or script actions
without having to deal directly with the vRO APIs.
Extensibility (Plug-in) Service Retrieve, create, update, and delete a resource. Retrieve an extension.
Retrieve license notifications.
Portal Service Retrieve, create, update, and delete a portal resource.
Properties Service Manage custom properties, property groups, and property definitions.
Properties specify items that can be added to blueprints to trigger
vRealize Orchestrator actions.
Reservation Service Retrieve, create, update, and delete a reservation or reservation policy.
Software Services Triggers the execution life cycle of software components using the
software agent, registers software agents, and manages the creation,
modification and deletion of software componentsoftware component
types, software resource requests, and nodes (machines).
vRA Orchestrator Service Manage vRealize Orchestrator actions, tasks, packages, and workflows.
Browse system and plug-in inventories.
Work Item Service Retrieve, create, update, complete, cancel, and delete a work item. Also
retrieve form data, metadata, detail forms, and submission forms from
service providers.
XaaS Service Manages XaaS elements such as forms, endpoints, XaaS blueprints,
tenants, vRealize Orchestrator imports, workflows, and work items.
The advanced designer service selection on the vRealize Automation API
Reference landing page selects the documentation for the XaaS service.
Programming Guide
VMware, Inc. 8
When a service request contains a resource URL, the first part of the URL identifies the service and the
last part identifies the resource. For example, the following resource URL identifies the catalog service
and the providers resource:
https://$host/component-registry/api/services
For more information about all the vRealize Automation REST API service calls, see Using the vRealize
Automation API Reference and the vRealize Automation API Reference in your vRealize Automation
installation.
Programming Guide
VMware, Inc. 9
REST API Authentication 2
In the REST API, vRealize Automation requires HTTP bearer tokens in request headers for authentication
of consumer requests. A consumer request applies to tasks that you can perform in the
vRealize Automation console, such as requesting a machine.
To acquire an HTTP bearer token, you authenticate with an identity service that manages the
communication with the SSO server. The identity service returns an HTTP bearer token that you include
in all request headers until the token expires, or you delete it. An HTTP bearer token expires in 24 hours
by default, but you can configure the token with a different duration.
Using HTTP Bearer Tokens
You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation console. You
create a request header with the curl command or with some other utility.
You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation console. You
create a request header with the curl command or with some other utility.
You use POST, HEAD, and DELETE methods to manage HTTP bearer tokens.
Method URL Description
POST /tokens Authenticate the user with the identity service /tokens and
generate a new token.
HEAD /tokens/tokenID Validate the token tokenID.
DELETE /tokens/tokenID Delete the token tokenID.
Use the following root URL for HTTP bearer calls:
https://$vra_server/identity/api/tokens
Configure the Duration of an HTTP Bearer Token
You set the duration of HTTP bearer tokens in the /etc/vcac/security.properties file on the
vRealize Automation appliance.
VMware, Inc. 10
The effective duration or lifetime of an HTTP bearer token depends on the duration of its corresponding
SAML token, which the SSO server creates at request time. An HTTP bearer token expires when it
reaches the end of its configured duration, or at the end of the configured duration of the SAML token,
whichever comes first. For example, if the configured duration is three days for the HTTP bearer token
and two days for the SAML token, the HTTP bearer token expires in two days. A configuration setting on
the SSO server determines the duration of SAML tokens.
Prerequisites
nLog in to the vRealize Automation appliance with SSH as root. The password is the one you specified
when you deployed the appliance.
nThe /etc/vcac/security.properties file on the appliance must be editable.
Procedure
1Open the /etc/vcac/security.properties file for editing.
2Add the following lines to the file, where N is an integer specifying the duration of the token in hours.
identity.basic.token.lifetime.hours=N
#The number is in hours.
3Save and close the file.
4Log out of the vRealize Automation appliance.
The new value applies the next time someone requests an HTTP bearer token.
Request an HTTP Bearer Token
You use an HTTP bearer token to authenticate a vRealize Automation REST API consumer request .
A consumer request must specify the correct component registry service and resource. For example, the
URL to obtain an HTTP bearer token must specify the identity service and token resource.
The HTTP bearer token expires in 24 hours by default. See Configure the Duration of an HTTP Bearer
Token for information on how to set the duration.
For related information, see Syntax for Requesting an HTTP Bearer Token.
Prerequisites
nLog in to vRealize Automation using the applicable credentials. For example, to assign a user to a
role, log in as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
Programming Guide
VMware, Inc. 11
Procedure
uEnter a curl command in the following format, replacing the variables with the correct values.
The variable $vRA used in this example represents the host name.domain name of the
vRealize Automation server, for example, mycompany.mktg.mydomain.com.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
--data '{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}'
https://$vRA/identity/api/tokens
For example, enter the following command line:
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"tanteater @example.com","password":"password","tenant":"MYCOMPANY"}'
https://tanteater.eng.mycompany.com:4870/identity/api/tokens
The command returns a response header with a status code and, if your request is successful, an HTTP
bearer token.
For example, the following sample output displays based on the command input:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Thur, 16 Jul 2015 23:59:59 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 324
Date: Wed, 15 Jul 2015 13:04:50 GMT
{
"expires":"2015-16-01T13:09:45.619Z",
"id":"MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLmNvb
TplMDViNGU0NGM2ZWU0MWQ1OWEwMTNmZGExNTQwZjNlNGM3YTBlM2I5MDhlYWZjYjY1ZjhiODI2OTg4ODU3M2UwOTUwOWRk
MjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==",
"tenant":"MYCOMPANY"
}
What to do next
Include the HTTP bearer token in your REST API service calls. You can store the token in a variable such
as $AUTH and then use the variable in your requests.
Syntax for Requesting an HTTP Bearer Token
An HTTP bearer token is required by the REST client to use the vRealize Automation REST API. You can
obtain a bearer token by authenticating to the identity service.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 12
A consumer request must specify the correct component registry service and resource. For example, the
URL to obtain an HTTP bearer token must contain the identity service and token resource values.
Input Description
host host name.domain name of the vRealize Automation server, for example,
mycompany.mktg.mydomain.com.
usrname Specifies the tenant administrator user name.
passwd Specifies the tenant administrator password.
tenantURLtoken Specifies the tenant URL token determined by the system administrator when creating the
tenant, for example, support.
Output
The following information is displayed as a result of your HTTP bearer token request.
Output Description
expires Contains the ISO 8601 timestamp indicating when the token expires.
id Contains the HTTP bearer token to use in Authorization header in subsequent requests.
tenant Displays the tenant ID associated with the token.
Response Status Codes
One of the following codes are displayed as a result of your HTTP bearer token request.
Status Code Description
200 OK Your request succeeded and the resource was updated. The
response body contains the full representation of the resource.
400 BAD REQUEST The data you provided in the POST failed validation. Inspect the
response body for details.
401 UNAUTHORIZED The request could not authenticate the user or authentication
credentials required.
Example: curl Command
You can enter the following command line format to request an HTTP bearer token.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"usrname",
"password":"passwd","tenant":"tenantURLtoken"}' https://$host/identity/api/tokens
When your request succeeds, the system returns the 200 OK status code, the expiration date and time of
the token, and the HTTP bearer token. After receiving the bearer token, you can include it in your request
headers.
Programming Guide
VMware, Inc. 13
Validate an HTTP Bearer Token
You can validate an existing HTTP bearer token.
Prerequisites
nRequest an HTTP Bearer Token.
Procedure
uCreate the request to validate the HTTP bearer token, as in the following example.
HEAD
/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OTg4O
DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==
Accept: application/json
The system returns one of the following status codes.
Status Code Description
204 NO CONTENT The request succeeded.
401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must be
authenticated.
403 FORBIDDEN Your authentication credentials do not provide sufficient access to the resource.
404 NOT FOUND Could not locate the resource based on the specified URI.
405 METHOD NOT ALLOWED The HEAD method is not supported for the resource.
500 SERVER ERROR Could not create or update the resource because of an internal server error.
Delete an HTTP Bearer Token
You can delete an HTTP bearer token.
Prerequisites
nRequest an HTTP Bearer Token.
Procedure
uCreate the request to delete the HTTP bearer token, as in the following example.
DELETE
/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OTg4O
DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==
Accept: application/json
The system returns one of the following status codes.
Programming Guide
VMware, Inc. 14
Status Code Description
204 NO CONTENT The request succeeded. The resource has been deleted.
401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must be
authenticated.
403 FORBIDDEN Your authentication credentials do not provide sufficient access to the resource.
404 NOT FOUND Could not locate the resource based on the specified URI.
405 METHOD NOT ALLOWED The DELETE method is not supported for the resource.
500 SERVER ERROR Could not create or update the resource because of an internal server error.
Programming Guide
VMware, Inc. 15
REST API Use Cases 3
Available use cases provide the prerequisite, command line options and format, and sample results to
help you perform a variety of vRealize Automation functions, such as requesting a machine or creating a
reservation.
You can find information about all of the available vRealize Automation REST API calls in the vRealize
Automation API Reference zip file located in the vRealize Automation Documentation Center. The use
cases provide samples of calls that you might commonly use and descriptions of example inputs and
outputs relative to those calls.
nCreate a Tenant
You can use the REST API identity service to create a vRealize Automation tenant and perform
related functions. Perform the tasks required to create a tenant with the REST API in sequence. For
information about creating and working with tenants and roles by using thevRealize Automation
application user interface, see the Tenant Administration and IaaS Configuration documentation.
nRequest a Machine
You can use REST API catalog service commands to complete a variety of tasks related to
requesting a machine. This procedure provides sample command line syntax for machine request
tasks. Supporting information regarding available input and output parameters, command-line entry
samples, and sample JSON output samples is available in the subsequent topics that explain syntax
for the various tasks.
nApprove a Machine Request
You can use a sequence of REST API workitem service commands to approve a machine request.
nList Provisioned Resources
You can use the REST API catalog service to log in to vRealize Automation and display a full or
filtered list of your provisioned resources .
nManage Provisioned Deployments
You can use the REST API catalog service to log in to vRealize Automation and view information
about provisioned resources .
nWorking with Reservations
You can work with the REST API reservation service to perform a variety of functions, such as
creating and updating reservations.
VMware, Inc. 16
nWorking with Reservation Policies
You can use the vRealize Automation REST API to work with the reservation service to perform a
variety of functions, such as creating and updating reservation policies.
nWorking with Key Pairs
You can work with the keyValuePair data element of the REST API workitem service to list, create,
and update key pairs.
nWorking with Network Profiles
You can use the vRealize Automation IaaS proxy provider service and IPAM service REST API to
create, list, and update network profiles.
nGet a List of Available IP Ranges for an IPAM Provider
You can query a specified IPAM provider endpoint for a list of the available IP address ranges
configured on the IPAM provider device.
nImport and Export Content
You can use the REST API content management service to import and export content, such as
blueprints, between vRealize Automation systems.
Create a Tenant
You can use the REST API identity service to create a vRealize Automation tenant and perform related
functions. Perform the tasks required to create a tenant with the REST API in sequence. For information
about creating and working with tenants and roles by using thevRealize Automation application user
interface, see the Tenant Administration and IaaS Configuration documentation.
Prerequisites
nLog in to vRealize Automation as a system administrator and a tenant administrator.
nVerify that there is access to a functional LDAP, Active Directory, or Native Active Directory identity
server.
nVerify that the identity server details required for the JSON template are available.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nSyntax for Displaying Your Current Tenants
You can use the REST API identity service to list of all the vRealize Automation tenants in your
system.
nSyntax for Requesting a New Tenant
You can use the REST API identity service to submit a request for a tenant. You can specify request
parameters using JSON command line input or by calling an existing JSON file from the command
line.
Programming Guide
VMware, Inc. 17
nSyntax for Listing All Tenant Identity Stores
You can use the REST API identity service to list all available identity stores for a named
vRealize Automation tenant, such as the default tenant vsphere.local.
nSyntax for Linking an Identity Store to the Tenant
You can use the REST API identity service to link an LDAP, Active Directory, or Native Active
Directory identity store to the vRealize Automation tenant.
nSyntax for Searching LDAP or Active Directory for a User
You can use the vRealize Automation REST API identity service to search the configured LDAP
directory, Active Directory, or Native Active Directory for a user.
nSyntax for Assigning a User to a Role
You can use the REST API identity service to assign a user to a role.
nSyntax for Displaying all Roles Assigned to a User
You can use the REST API identity service to display all of the roles assigned to a user.
Procedure
1Use the identity service to display all the available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
2Submit a request for a new tenant and either call a JSON file that contains tenant request parameters
or specify those parameters using inline text. The first example uses a JSON file as input. The
second example uses inline text as input.
The first example calls the following sample newTenant.json file.
{
"@type" : "Tenant",
"id" : "development",
"urlName" : "development",
"name" : "DevelopmentTenant",
Programming Guide
VMware, Inc. 18
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
Examples Command
Example 1
Call the above newTenant.json file,
which contains parameters for the
tenant request.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/development --data
@C:\Temp\newTenant.json
Example 2
Specify the parameters for the tenant
request by using inline text.
curl --insecure -H "Accept: application/json" -H "Content-
Type: application/json"
-H "Authorization: Bearer $token"
--data
'{"@type":"Tenant","id":"development","urlName":"development","
name":
"DevelopmentTenant","description":"Tenant for all
developers","contactEmail":
"admin@mycompany.com","defaultTenant":false}'
3List all available identity stores for a named tenant, such as the default tenant vsphere.local by using
variables, instead of the full token and host name.domain name.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories
4Link an LDAP, Active Directory, or Native Active Directory identity store to the tenant by using the
identity service.
Call the following sample ldap.json.txt input file from the command line to specify necessary
parameters.
{
"alias": "example.com",
"domain": "example.mycompany.com",
"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"name": "openLDAPDemo",
"password": "password",
"type": "LDAP",
Programming Guide
VMware, Inc. 19
"url": "ldap://10.000.00.000:389",
"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"
}
Use the following command to call the example JSON text file and link an identity store to a tenant.
The command also tests that vRealize Automation can connect to the identity store successfully. If
the command finishes successfully, vRealize Automation succeeded in connecting to the identity
store.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/identity/api/tenants/development/directories/example.mycompany.com
--data @C:\Temp\ldap.json.txt
5Query the configured LDAP directory, Active Directory, or Native Active Directory for a specific user.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/$tenantId/principals/$userId
6Assign a user to a role with the REST API identity service.
Use the following command string to submit a request to assign the user tony in the domain
example.mycompany.com to the tenant administrator role. It provides empty braces for the required
JSON payload.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
"https://$host/identity/api/authorization/tenants/development/principals/
susan@example.mycompany.com/roles/CSP_TENANT_ADMIN/" --data "{}"
7Display all of the roles assigned to a user with the identity service.
Use the following command to list all the roles that are assigned to tony@example.mycompany.com.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/authorization/tenants/development/principals/
tony@example.mycompany.com/roles
What to do next
Syntax for Displaying Your Current Tenants
You can use the REST API identity service to list of all the vRealize Automation tenants in your system.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 20
Parameter Description
URL https://$host/identity/api/tenants
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 21
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
nFirst, Previous, Next, and Last refer to
corresponding pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of
the tenant objects returned in a pageable list. Each tenant object
can contain the following information:
nId:
Specifies the unique tenant identifier.
nurlName:
Specifies the name of the tenant as it appears in URLs.
nName:
Specifies the name of the tenant for display purposes.
ndescription:
Specifies the long description of the tenant.
ncontactEmail:
Specifies the primary contact email address.
nPassword:
Unused
ndefaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Programming Guide
VMware, Inc. 22
Example: curl Command
The following example command displays all available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
Format the XML output to improve its readability. For information about formatting output, see Chapter 5
Filtering and Formatting REST API Information.
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "Tenant",
"id" : "vsphere.local",
"urlName" : "vsphere.local",
"name" : "vsphere.local",
"description" : null,
"contactEmail" : null,
"password" : null,
"defaultTenant" : true
}, {
"@type" : "Tenant",
"id" : "MYCOMPANY",
"urlName" : "MYCOMPANY",
"name" : "QETenant",
"description" : "Test tenant",
"contactEmail" : null,
"password" : "defaultPwd#1",
"defaultTenant" : false
} ],
"metadata" : {
"size" : 19,
"totalElements" : 2,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}
Syntax for Requesting a New Tenant
You can use the REST API identity service to submit a request for a tenant. You can specify request
parameters using JSON command line input or by calling an existing JSON file from the command line.
Programming Guide
VMware, Inc. 23
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/identity/api/tenants/$tenantId --data @
$inputFileName.json
$token Specifies a valid HTTP bearer token with necessary credentials.
$host Specifies the host name and fully qualified domain name or IP address
of the vRealize Automation identity server.
$tenantId Specifies the ID of the tenant.
$tenantURL Specifies the URL of the tenant.
$tenantName Specifies the name of the tenant.
$description Specifies a description of the tenant.
$emailAddress Specifies the contact email address for the tenant.
JSON Input File Template
To simplify command line input, create a JSON file and call that file from the command line. To create a
JSON file, copy the following template to a new text file. To maintain formatting, use an XML editor.
Replace the italicized variables in the template with your specific values.
{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"defaultTenant" : false
}
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 24
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
nFirst, Previous, Next, and Last refer to
corresponding pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of
the tenant objects returned in a pageable list. Each tenant object
can contain the following information:
nId:
Specifies the unique tenant identifier.
nurlName:
Specifies the name of the tenant as it appears in URLs.
nName:
Specifies the name of the tenant for display purposes.
ndescription:
Specifies the long description of the tenant.
ncontactEmail:
Specifies the primary contact email address.
nPassword:
Unused
ndefaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Programming Guide
VMware, Inc. 25
Example: curl Command
Submit a request for a new tenant and either call a JSON file that contains tenant request parameters or
specify those parameters using inline text. The first example uses a JSON file as input. The second
example uses inline text as input.
The first example calls the following sample newTenant.json file.
{
"@type" : "Tenant",
"id" : "development",
"urlName" : "development",
"name" : "DevelopmentTenant",
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
Example 1: Use the following example to call the above newTenant.json file, which contains parameters
for the tenant request.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/development --data @C:\Temp\newTenant.json
Example 2: Use the following example to specify parameters for the tenant request by using inline text.
curl --insecure -H "Accept: application/json" -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
--data '{"@type":"Tenant","id":"development","urlName":"development","name":
"DevelopmentTenant","description":"Tenant for all developers","contactEmail":
"admin@mycompany.com","defaultTenant":false}'
Syntax for Listing All Tenant Identity Stores
You can use the REST API identity service to list all available identity stores for a named
vRealize Automation tenant, such as the default tenant vsphere.local.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/identity/api/tenants/$tenantId/directories
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$tenantId Specifies the ID of the tenant.
Programming Guide
VMware, Inc. 26
Output
The command output contains property names and values based on the command input parameters.
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
nFirst, Previous, Next, and Last refer to
corresponding pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of
the tenant objects returned in a pageable list. Each tenant object
can contain the following information:
nId:
Specifies the unique tenant identifier.
nurlName:
Specifies the name of the tenant as it appears in URLs.
nName:
Specifies the name of the tenant for display purposes.
ndescription:
Specifies the long description of the tenant.
ncontactEmail:
Specifies the primary contact email address.
nPassword:
Unused
ndefaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Programming Guide
VMware, Inc. 27
Example: curl Command
The following example command lists the identity stores by using variables, instead of the full token and
host name.domain name.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories
Example: JSON Output
The following JSON output is returned based on the command input.
HTTP/1.1 200 OK
Server: Apache-Beach/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Wed, 31 Dec 1969 23:59:59 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 830
Date: Sat, 01 Feb 2014 13:07:54 GMT
{"links":[],
"content":[
{"@type":"IdentityStore",
"domain":"vcac.mycompany.com",
"name":"openLDAPPromocom",
"description":null,
"alias":"promocom.com",
"type":"LDAP",
"userNameDn":"cn=promocomadmin,ou=promocom,dc=vcac,dc=mycompany,dc=com",
"password":null,
"url":"ldap://10.000.00.000:389",
"groupBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com",
"userBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com"
},
{"@type":"IdentityStore",
"domain":"example.mycompany.com",
"name":"openLDAPDemo",
"description":null,
"alias":"example.com",
"type":"LDAP",
"userNameDn":"cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com",
"password":null,
"url":"ldap://10.000.00.000:389",
"groupBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com",
"userBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com"
}],
"metadata":{
"size":20,
"totalElements":2,
"totalPages":1,
Programming Guide
VMware, Inc. 28
"number":1,
"offset":0
}
}
Syntax for Linking an Identity Store to the Tenant
You can use the REST API identity service to link an LDAP, Active Directory, or Native Active Directory
identity store to the vRealize Automation tenant.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/identity/api/tenants/$tenantId/directories/$domainName --data @
$inputFileName.json
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$tenantId Specifies the ID of the tenant.
userId Specifies the ID of the user in the form name@domain.
$domainAlias Specifies the domain alias.
$domainName Specifies the domain of the identity store.
$grpBaseSearchDn Specifies the group search base Distinguished Name.
$identityStoreName Specifies a description of the new tenant.
$password Specifies the password.
$identityStoreType Specifies the identity store type for the tenant. The following values are
supported:
nLDAP
nAD
nNATIVE_AD
$identityServerUrl Specifies the URL of the identity server.
$usrBaseSearchDn Specifies the user search base Distinguished Name.
$usrNameDn Specifies the Distinguished Name for the login user.
JSON Input File Template
Use this template to create a JSON input file. Replace the variables in the template with actual values in
the file.
{
"alias": "$domainAlias",
"domain": "$domainName",
"groupBaseSearchDn": "$grpBaseSearchDn",
Programming Guide
VMware, Inc. 29
"name": "$identityStoreName",
"password": "$password",
"type": "$identityStoreType",
"url": "$identityServerUrl",
"userBaseSearchDn": "$usrBaseSearchDn",
"userNameDn": "$usrNameDn"
}
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 30
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
nFirst, Previous, Next, and Last refer to
corresponding pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of
the tenant objects returned in a pageable list. Each tenant object
can contain the following information:
nId:
Specifies the unique tenant identifier.
nurlName:
Specifies the name of the tenant as it appears in URLs.
nName:
Specifies the name of the tenant for display purposes.
ndescription:
Specifies the long description of the tenant.
ncontactEmail:
Specifies the primary contact email address.
nPassword:
Unused
ndefaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Programming Guide
VMware, Inc. 31
Example JSON Input File
Call the following sample ldap.json.txt input file from the command line to specify necessary
parameters.
{
"alias": "example.com",
"domain": "example.mycompany.com",
"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"name": "openLDAPDemo",
"password": "password",
"type": "LDAP",
"url": "ldap://10.000.00.000:389",
"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"
}
Example: curl Command
The following example command calls the example JSON text file and links an identity store to a tenant.
The command also tests that vRealize Automation can connect to the identity store successfully. If the
command finishes successfully,vRealize Automation succeeded in connecting to the identity store.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/identity/api/tenants/development/directories/example.mycompany.com
--data @C:\Temp\ldap.json.txt
Example: JSON Output
This output indicates that an identity store is successfully linked to the specified tenant.
Request Headers
{
Content-Type = application/json
Accept = application/json
Content-Length = 413
Accept-Charset = big5, big5-hkscs, euc-jp, euc-kr, gb18030, gb2312, gbk,
ibm-thai, ibm00858, ibm01140, ibm01141, ibm01142, ibm01143, ibm01144, ibm01145,
ibm01146, ibm01147, ibm01148, ibm01149, ibm037, ibm1026, ibm1047, ibm273, ibm277,
ibm278, ibm280, ibm284, ibm285, ibm290, ibm297, ibm420, ibm424, ibm437, ibm500,
ibm775, ibm850, ibm852, ibm855, ibm857, ibm860, ibm861, ibm862, ibm863, ibm864,
ibm865, ibm866, ibm868, ibm869, ibm870, ibm871, ibm918, iso-2022-cn, iso-2022-jp,
iso-2022-jp-2, iso-2022-kr, iso-8859-1, iso-8859-13, iso-8859-15, iso-8859-2,
iso-8859-3, iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9,
jis_x0201, jis_x0212-1990, koi8-r, koi8-u, shift_jis, tis-620, us-ascii, utf-16,
utf-16be, utf-16le, utf-32, utf-32be, utf-32le, utf-8, windows-1250, windows-1251,
windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257,
windows-1258, windows-31j, x-big5-hkscs-2001, x-big5-solaris, x-compound_text,
x-euc-jp-linux, x-euc-tw, x-eucjp-open, x-ibm1006, x-ibm1025, x-ibm1046, x-ibm1097,
x-ibm1098, x-ibm1112, x-ibm1122, x-ibm1123, x-ibm1124, x-ibm1364, x-ibm1381,
Programming Guide
VMware, Inc. 32
x-ibm1383, x-ibm300, x-ibm33722, x-ibm737, x-ibm833, x-ibm834, x-ibm856, x-ibm874,
x-ibm875, x-ibm921, x-ibm922, x-ibm930, x-ibm933, x-ibm935, x-ibm937, x-ibm939,
x-ibm942, x-ibm942c, x-ibm943, x-ibm943c, x-ibm948, x-ibm949, x-ibm949c, x-ibm950,
x-ibm964, x-ibm970, x-iscii91, x-iso-2022-cn-cns, x-iso-2022-cn-gb, x-iso-8859-11,
x-jis0208, x-jisautodetect, x-johab, x-macarabic, x-maccentraleurope, x-maccroatian,
x-maccyrillic, x-macdingbat, x-macgreek, x-machebrew, x-maciceland, x-macroman,
x-macromania, x-macsymbol, x-macthai, x-macturkish, x-macukraine, x-ms932_0213,
x-ms950-hkscs, x-ms950-hkscs-xp, x-mswin-936, x-pck, x-sjis_0213, x-utf-16le-bom,
x-utf-32be-bom, x-utf-32le-bom, x-windows-50220, x-windows-50221, x-windows-874,
x-windows-949, x-windows-950, x-windows-iso2022jp
}
Response Headers
{
Date = Wed, 29 Oct 2014 22:41:57 GMT
Content-Type = application/json;charset=UTF-8
Content-Length = 0
Vary = Accept-Encoding,User-Agent
Keep-Alive = timeout=15, max=100
Connection = Keep-Alive
}
Successful
Unlinked Identity Store Error
The following output indicates that an identity store is not linked to the specified tenant. To resolve the
problem, correct the identity store and connection details in the JSON input file and rerun the command.
Command failed [Rest Error]: {Status code: 400}, {Error code: 90027} , {Error
Source: null}, {Error Msg: Cannot connect to the directory service.}, {System
Msg: 90027-Connection to directory service can’t be established}
Syntax for Searching LDAP or Active Directory for a User
You can use the vRealize Automation REST API identity service to search the configured LDAP directory,
Active Directory, or Native Active Directory for a user.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/identity/api/tenants/$tenantId/principals/$userId
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$tenantId Specifies the ID of the tenant.
$userId Specifies the ID of the user in the form name@domain.
Programming Guide
VMware, Inc. 33
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Specifies an array of link objects, each of which contains the following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested. This parameter does not
appear when you query a single profile.
nFirst, Previous, Next, and Last refer to corresponding pages of pageable lists.
nSpecifies the application or service that determines the other names.
nhref
Specifies the URL that produces the result.
@type Specifies the user name.
firstName Specifies the first name of the user.
lastName Specifies the last name of the user.
description Specifies the description of the user.
emailAddress Specifies the email address of the user.
locked Specifies the Boolean flag indicating if the user is locked out.
disabled Specifies the Boolean flag indicating if the user is disabled.
principalId Specifies the principal ID of the user in username@domain format.
tenantName Specifies the name of tenant to which user belongs.
name Specifies the first and last name concatenated.
Example: curl Command
The following example command queries the configured LDAP directory for a specific user.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/$tenantId/principals/$userId
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "User",
"firstName" : "Tony",
"lastName" : "Anteater",
"emailAddress" : "tony@example.mycompany.com",
Programming Guide
VMware, Inc. 34
"locked" : false,
"disabled" : false,
"principalId" : {
"domain" : "example.mycompany.com",
"name" : "susan"
},
"tenantName" : "MYCOMPANY1",
"name" : "Tony Anteater"
} ]
}
Syntax for Assigning a User to a Role
You can use the REST API identity service to assign a user to a role.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/identity/api/authorization/tenants/$tenantId/principals/$principalId/rol
es/roleId
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$tenantId Specifies the ID of the tenant.
$principalId Specifies the ID of the user in name@domain format.
$roleId Specifies the ID of the user role.
Example: curl Command
The following example command string submits a request to assign the user tony in the domain
example.mycompany.com to the tenant administrator role. It provides empty braces for the required
JSON payload. See Syntax for Searching LDAP or Active Directory for a User for more information about
getting the user name and domain values.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
"https://$host/identity/api/authorization/tenants/development/principals/
susan@example.mycompany.com/roles/CSP_TENANT_ADMIN/" --data "{}"
Example: JSON Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Programming Guide
VMware, Inc. 35
Syntax for Displaying all Roles Assigned to a User
You can use the REST API identity service to display all of the roles assigned to a user.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/identity/api/authorization/tenants/$tenantId/principals/$principalId/ro
les
$token Specifies a valid HTTP bearer token with necessary credentials.
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$tenantId Specifies the ID of the tenant.
principalId Specifies the ID of the user in the form name@domain.
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the role ID.
name Specifies the role name.
description Specifies the role description.
status Specifies the status of this role.
assignedPermissions Specifies the set of permissions that are implied by this role assignment.
Example: curl Command
The following example command lists all the roles that are assigned to tony@example.mycompany.com.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/authorization/tenants/development/principals/
tony@example.mycompany.com/roles
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "SystemRole",
"id" : "ABX_TENANT_ADMIN",
Programming Guide
VMware, Inc. 36
"name" : "Tenant Administrator",
"description" : "ABX Tenant Administrator",
"assignedPermissions" : [ {
"id" : "CATALOG_CONSUME_TENANT_MGMT",
"name" : "Catalog Consume Tenant Management",
"description" : "Consume services, resources and manage requests on
behalf of any user within a Tenant",
"prereqAdminPermissions" : null
}, {
"id" : "MY_TENANT_MANAGEMENT",
"name" : "My Tenant Management",
"description" : "Manage my tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "CATALOG_AUTHOR_TENANT",
"name" : "Catalog Tenant-level Author",
"description" : "Create, update and publish services, catalog items and actions shared across a
Tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "GUI_MY_TENANT_MANAGEMENT",
"name" : "My Tenant Administration User Interface",
"description" : "Access my tenant administration GUI.",
"prereqAdminPermissions" : null
}, {
"id" : "CATALOG_ENTITLE_TENANT",
"name" : "Catalog Tenant-level Entitlement Management",
"description" : "Entitle services, catalog items and actions to all users within a tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "FILE_EDIT_TENANT",
"name" : "Manage Tenant Files",
"description" : "Upload and delete files belonging to this tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "TENANT_USER_DATA_MANAGEMENT",
"name" : "Manage user data (requests, items, tasks etc) within a tenant.",
"description" : "Manage user created objects belonging to the tenant.",
"prereqAdminPermissions" : null
}, {
"id" : "TENANT_ADMIN_ROLE_ASSIGNMENT",
"name" : "Tenant Administrator Role Assignment",
"description" : "Assign the tenant administrator role to other users.",
"prereqAdminPermissions" : null
}, {
"id" : "GUI_MY_TENANT_TUG_MANAGEMENT",
"name" : "My Tenant Identity Stores, Groups and Users Administration User Interfaces",
"description" : "Access my tenant identity stores, groups and users administration GUIs.",
"prereqAdminPermissions" : null
} ]
} ],
"metadata" : {
"size" : 20,
Programming Guide
VMware, Inc. 37
"totalElements" : 1,
"totalPages" : 1,
"number" : 1,
"offset" : 0
Request a Machine
You can use REST API catalog service commands to complete a variety of tasks related to requesting a
machine. This procedure provides sample command line syntax for machine request tasks. Supporting
information regarding available input and output parameters, command-line entry samples, and sample
JSON output samples is available in the subsequent topics that explain syntax for the various tasks.
The REST API catalog service includes Hypermedia as the Engine of Application State (HATEOAS) links
that function as templates to assist users in completing common tasks that are supported by the API.
They typical scenario for using a template is for the user to submit a template request for a given context.
For example, catalog-service/api/consumer/entitledCatalogItems/ dc808d12-3786-4f7c-
b5a1-d5f997c8ad66/requests/template. Users can employ the returned template, either as is or
modified, to create an appropriate request. The user then POSTs, or PUTs, the request to the target API.
For example, catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-
b5a1-d5f997c8ad66/requests.
This procedure provides sample command line syntax for approving a machine request. Supporting
information regarding available input and output parameters, command-line entry samples, and sample
JSON output samples is available.
Prerequisites
nLog in to vRealize Automation as a consumer and current business group user.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nSyntax for Listing Shared and Private Catalog Items
You can use the REST API catalog service to retrieve a list of all shared viewable catalog items for
the current user. Shared catalog items do not belong to a specific business group. Also, this service
retrieves a list of all shared and private catalog items that can be viewed, including their business
groups.
nSyntax for Getting Information for a Catalog Item
You can use the REST API catalog service to get information about a specific catalog item if desired.
nSyntax for Getting a Template Request for a Catalog Item
You can use the REST API catalog service to request catalog items. VMware supplies a number of
templates to help you create different types of machine requests.
Programming Guide
VMware, Inc. 38
nSyntax for Requesting a Machine
You can use the REST API catalog service to submit a machine request.
nSyntax for Viewing Details of a Machine Request
You can use the vRealize Automation REST API catalog service to view the details of a machine
request.
Procedure
1List all shared catalog items in the catalog.
You can browse the API and use HATEOAS links to navigate to additional API calls that are relevant
to the current context.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/entitledCatalogItemViews
Accept: application/json
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/entitledCatalogItems
Alternatively, you can also search for a catalog item by name by substituting $catalogItemName with
$catalogItemId.
2Locate the details of a specific catalog item by name.
Note that the vRealize Automation API supports OData filtering.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/entitledCatalogItemViews?$filter=name+eq+%27$catalogItemName%27
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/entitledCatalogItems
3Get a template request for a catalog item.
This request uses a HATEOAS link for a template request for this catalog item.
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests/template
Accept: application/json
4Review and edit the template request.
The template request returned in preceding step is specific to the catalog item that corresponds to
your template request. The fields and default values are populated based on the configuration of the
underlying blueprint.
Programming Guide
VMware, Inc. 39
Review the contents of the template and edit the values if you want to change them from the default
prior to submitting the request. For example, you can specify a value for the description field or
change the values for the machine resources if the blueprint allows for a range.
5Submit the request.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests --verbose --data
@C:/Temp/requestMachine.json
{
$contentsOfTemplateFromPrecedingSections
}
6(Optional) View the details of your request.
You can perform a GET on the URI in the Location header to retrieve the updated request details.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b
Accept: application/json
The status information is particularly noteworthy in the request details. The phase field corresponds to
the status that is displayed in the Requests tab in the user interface.
Syntax for Listing Shared and Private Catalog Items
You can use the REST API catalog service to retrieve a list of all shared viewable catalog items for the
current user. Shared catalog items do not belong to a specific business group. Also, this service retrieves
a list of all shared and private catalog items that can be viewed, including their business groups.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/catalogItems
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
page number The page number. Default is 1.
limit The number of entries per page. The default is 20.
Programming Guide
VMware, Inc. 40
Parameter Description
$orderby Multiple comma-separated properties sorted in ascending or descending order. Valid OData
properties include the following:
nname - filter based on catalog item name.
nstatus - filter based on catalog item status.
nservice/id - filter based on catalog item service id.
nservice/name - filter based on catalog item service name.
norganization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
norganization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
noutputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
noutputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
ncatalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
ncatalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
nicon/id - filter based on catalog item icon ID.
$top Sets the number of returned entries from the top of the response
$skip Sets the number of entries to skip.
$filter Boolean expression for whether a particular entry should be included in the response. Valid
OData properties include the following:
nname - filter based on catalog item name.
nstatus - filter based on catalog item status.
nservice/id - filter based on catalog item service id.
nservice/name - filter based on catalog item service name.
norganization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
norganization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
noutputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
noutputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
ncatalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
ncatalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
nicon/id - filter based on catalog item icon ID.
serviceId (Optional) Query parameter to filter the returned catalog items by one specific service.
onBehalfOf (Optional) Query parameter that provides the value of the user ID when making a request on
behalf of another user.
Programming Guide
VMware, Inc. 41
Output
The command output contains property names and values based on the command input parameters.
Property Description
outputResourceTypeRef Specifies the type of the resource that results from requesting the catalog item.
catalogItemId Specifies the catalog item identifier.
name Specifies the user friendly name of the catalog item. Specifies the property type is string.
description Specifies a short description of the catalog item. Specifies the property type is string.
catalogItemTypeRef Specifies the type of the catalog item.
serviceRef Specifies the catalog service that contains the catalog item.
iconId Specifies the associated icon representing this item.
isNoteworthy Specifies if the catalog item should be highlighted to users for a period of time.
dateCreated Specifies the date that this item was created in the catalog.
lastUpdatedDate Specifies the date that this item was last updated in the catalog.
entitledOrganizations Specifies the organizations in which the catalog item can be consumed by the current user.
Example Curl Command
The following example command retrieves information about all the available shared catalog items of the
type ConsumerEntitledCatalogItemView.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-service/api/consumer/entitledCatalogItemViews
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links": [],
"content": [
{
"@type": "ConsumerEntitledCatalogItemView",
"links": [
{
"@type": "link",
"rel": "GET: Request Template",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests"
Programming Guide
VMware, Inc. 42
}
],
"entitledOrganizations": [
{
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
}
],
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"name": "Linux",
"description": "Linux blueprint for API demo",
"isNoteworthy": false,
"dateCreated": "2015-07-29T03:54:28.141Z",
"lastUpdatedDate": "2015-07-29T12:46:56.405Z",
"iconId": "cafe_default_icon_genericCatalogItem",
"catalogItemTypeRef": {
"id": "com.vmware.csp.component.cafe.composition.blueprint",
"label": "Composite Blueprint"
},
"serviceRef": {
"id": "057d4095-95f1-47da-b14b-641ac9010c97",
"label": "Infrastructure Services"
},
"outputResourceTypeRef": {
"id": "composition.resource.type.deployment",
"label": "Deployment"
}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Syntax for Getting Information for a Catalog Item
You can use the REST API catalog service to get information about a specific catalog item if desired.
REST API Catalog Service
The REST API supports OData filtering. For more information about supported OData filters, refer to the
vRealize Automation API Reference, particularly the REST API Tips page located at
https://$host/component-registry/services/docs/odata.html.
Programming Guide
VMware, Inc. 43
For specific information about catalog service filters, see the "Important Notes About catalog-service and
OData Queries" topic located at https://$host/catalog-service/api/docs/index.html.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/catalogItems
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
page number The page number. Default is 1.
limit The number of entries per page. The default is 20.
$orderby Multiple comma-separated properties sorted in ascending or descending order. Valid OData
properties include the following:
nname - filter based on catalog item name.
nstatus - filter based on catalog item status.
nservice/id - filter based on catalog item service id.
nservice/name - filter based on catalog item service name.
norganization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
norganization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
noutputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
noutputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
ncatalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
ncatalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
nicon/id - filter based on catalog item icon ID.
$top Sets the number of returned entries from the top of the response
$skip Sets the number of entries to skip.
Programming Guide
VMware, Inc. 44
Parameter Description
$filter Boolean expression for whether a particular entry should be included in the response. Valid
OData properties include the following:
nname - filter based on catalog item name.
nstatus - filter based on catalog item status.
nservice/id - filter based on catalog item service id.
nservice/name - filter based on catalog item service name.
norganization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
norganization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
noutputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
noutputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
ncatalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
ncatalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
nicon/id - filter based on catalog item icon ID.
serviceId (Optional) Query parameter to filter the returned catalog items by one specific service.
onBehalfOf (Optional) Query parameter that provides the value of the user ID when making a request on
behalf of another user.
Output
The command output contains property names and values based on the command input parameters.
Property Description
outputResourceTypeRef Specifies the type of the resource that results from requesting the catalog item.
catalogItemId Specifies the catalog item identifier.
name Specifies the user friendly name of the catalog item. Specifies the property type is string.
description Specifies a short description of the catalog item. Specifies the property type is string.
catalogItemTypeRef Specifies the type of the catalog item.
serviceRef Specifies the catalog service that contains the catalog item.
iconId Specifies the associated icon representing this item.
isNoteworthy Specifies if the catalog item should be highlighted to users for a period of time.
dateCreated Specifies the date that this item was created in the catalog.
lastUpdatedDate Specifies the date that this item was last updated in the catalog.
entitledOrganizations The list of organizations in which the current user can consume the catalog item.
Programming Guide
VMware, Inc. 45
Example Curl Command
The following example command retrieves information about all the available shared catalog items of the
type ConsumerEntitledCatalogItemView.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-service/api/consumer/entitledCatalogItemViews
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links": [],
"content": [
{
"@type": "ConsumerEntitledCatalogItemView",
"links": [
{
"@type": "link",
"rel": "GET: Request Template",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests"
}
],
"entitledOrganizations": [
{
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
}
],
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"name": "Linux",
"description": "Linux blueprint for API demo",
"isNoteworthy": false,
"dateCreated": "2015-07-29T03:54:28.141Z",
"lastUpdatedDate": "2015-07-29T12:46:56.405Z",
"iconId": "cafe_default_icon_genericCatalogItem",
"catalogItemTypeRef": {
"id": "com.vmware.csp.component.cafe.composition.blueprint",
"label": "Composite Blueprint"
},
"serviceRef": {
"id": "057d4095-95f1-47da-b14b-641ac9010c97",
"label": "Infrastructure Services"
Programming Guide
VMware, Inc. 46
},
"outputResourceTypeRef": {
"id": "composition.resource.type.deployment",
"label": "Deployment"
}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Syntax for Getting a Template Request for a Catalog Item
You can use the REST API catalog service to request catalog items. VMware supplies a number of
templates to help you create different types of machine requests.
Overview
In the entitledCatalogItemViews response, there is a link field that contains a value similar to the
following:
{
"@type":"link",
"href":"https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-
b5a1-d5f997c8ad66/requests/template",
"rel":"GET: Request Template"
}
This URL is a HATEOAS link for a template request for this catalog item. The rel field provides a
description of the link (request template) and indicates the HTTP method to use with the URI in the href
field (GET). By using these HATEOAS links, you can make follow-on API calls without having to consult
the API documentation for the URI syntax or construct the links programmatically.
Review and Edit the Template Request
The returned template request is specific to the applicable catalog item. The fields and default values are
populated based on the configuration of the underlying blueprint.
You can review the contents of the template and optionally edit the values if you want to change them
from the default prior to submitting the request. For example, you can specify a value for the description
field or change the values for the machine resources if the blueprint allows for a range.
Programming Guide
VMware, Inc. 47
Input
Use the supported input parameters to control the command output.
Parameter Description
id The UUID of the catalog item.
Output
The command output contains property names and values based on the command input parameters.
Property Description
entitledOrganizations The list of organizations in which the current user can consume the catalog item.
catalogItemId Specifies the catalog item identifier.
Example Curl Command
The following example command retrieves the catalog item with an ID of dc808d12-3786-4f7c-b5a1-
d5f997c8ad66.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalog-
service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-d5f997c8ad66/requests/template
Example: JSON Output
The following JSON output is returned based on the command input.
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogItemProvisioningRequest",
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"requestedFor": "csummers@example.com",
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"description": null,
"reasons": null,
"data": {
"Existing_Network_1": {
"componentTypeId": "com.vmware.csp.component.cafe.composition",
"componentId": null,
"classId": "Blueprint.Component.Declaration",
"typeFilter": "LinuxDemo*Existing_Network_1",
"data": {
"_cluster": 1,
"_hasChildren": false,
"description": null,
"name": "Existing Network",
"networkname": "Existing Network",
"subnetmask": "255.255.255.0"
}
},
Programming Guide
VMware, Inc. 48
"vSphere-Linux": {
"componentTypeId": "com.vmware.csp.component.cafe.composition",
"componentId": null,
"classId": "Blueprint.Component.Declaration",
"typeFilter": "LinuxDemo*vSphere-Linux",
"data": {
"Cafe.Shim.VirtualMachine.MaxCost": 0,
"Cafe.Shim.VirtualMachine.MinCost": 0,
"_cluster": 1,
"_hasChildren": false,
"action": "FullClone",
"allow_storage_policies": false,
"archive_days": 0,
"blueprint_type": "1",
"cpu": 1,
"custom_properties": [],
"daily_cost": 0,
"datacenter_location": null,
"description": null,
"disks": [
{
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Compute.Machine.MachineDisk",
"typeFilter": null,
"data": {
"capacity": 6,
"id": 0,
"initial_location": "",
"is_clone": false,
"label": "",
"storage_reservation_policy": "",
"userCreated": true,
"volumeId": 0
}
}
],
"display_location": false,
"guest_customization_specification": null,
"lease_days": 0,
"machine_actions": [
"DESTROY",
"POWER_ON",
"CONNECT_RDP_SSH",
"REPROVISION",
"POWER_CYCLE",
"EXPIRE",
"SUSPEND",
"CONNECT_REMOTE_CONSOLE",
"CONNECT_USING_VDI"
],
"machine_prefix": {
"componentId": null,
"classId": "Infrastructure.Compute.MachinePrefix",
"id": "Use group default"
Programming Guide
VMware, Inc. 49
},
"max_network_adapters": 0,
"max_per_user": 0,
"max_volumes": 60,
"memory": 4096,
"nics": [
{
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Compute.Machine.Nic",
"typeFilter": null,
"data": {
"address": "",
"assignment_type": "DHCP",
"custom_properties": null,
"id": 0,
"load_balancing": "",
"network_profile": "Existing Network"
}
}
],
"number_of_instances": 1,
"os_arch": "x86_64",
"os_distribution": null,
"os_type": "Linux",
"os_version": null,
"platform_name": "vsphere",
"platform_type": "virtual",
"property_groups": [
null
],
"provisioning_workflow": {
"componentId": null,
"classId": "Infrastructure.Compute.ProvisioningWorkflow",
"id": "CloneWorkflow"
},
"reservation_policy": {
"componentId": null,
"classId": "Infrastructure.Reservation.Policy.ComputeResource",
"id": "None"
},
"security_groups": [],
"security_tags": [],
"source_machine": null,
"source_machine_external_snapshot": null,
"source_machine_name": "cbpcentos_63_x86",
"source_machine_vmsnapshot": null,
"storage": 6
}
}
}
}
Programming Guide
VMware, Inc. 50
Syntax for Requesting a Machine
You can use the REST API catalog service to submit a machine request.
Prepare you Request
Going back to the entitledCatalogItemViews response, locate a link field that contains a value similar to
the following:
{
"@type":"link",
"href":"https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-
b5a1-d5f997c8ad66/requests",
"rel":"POST: Submit Request"
}
Use the information in this response to edit the template construct the URI to request the desired catalog
item using a POST command.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/requests/requestId
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
catalogItemId The identifier of a catalog item. Typically, this is provided by users via the REST
URI when making an entitledCatalogItem provisioning request.
requestedFor The user for whom this request is being made. Must be the fully qualified user
ID. Typically this is provided by the REST URI when making an
entitledCatalogItem provisioning request.
businessGroupId The business group identifier associated with the request. Typically this is
provided via the REST URI when making the request.
description The catalog item description.
reasons
data Context-specific properties. Obtain the consumerEntitledCatalogItem template
request to identify the properties available for a given context.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 51
Property Description
version Displays the object version number.
state Specifies the item state, such as submitted.
approvalStatus Specifies a status indicating whether this request has been approved, rejected, or is still
pending some form of approval.
waitingStatus Specifies a status indicating whether this request is waiting on any external users or services
before it is able to progress.
requestNumber Specifies a more user-friendly identifier for this request.
executionStatus Specifies the current execution status of the request.
stateName Specifies the localized state name.
phase Specifies the current phase of the request, which is more coarse grained and easier for users to
understand.
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
description Contains a brief description of this request.
reasons Specifies the business reasons entered by the requestor or owner of this request.
requestedFor Specifies the ID of the user for whom this request is logged.
requestedBy Specifies the ID of the user who actually submitted the request
organization Subtenant and/or tenant owner of this request.
requestorEntitlementId Specified the value of the requestorEntitlement setting.
preApprovalId Specifies the ID of the preApproval setting.
postApprovalId Specifies the ID of the approval generated for the post-provisioning workflow step.
dateCreated Specifies the date when this request was sent to the catalog.
lastUpdated Specifies the date when this request was last updated.
dateSubmitted Specifies the date when this request was first submitted.
dateApproved Specifies the date when this request was approved.
dateCompleted Specifies the date when this request was completed.
quote Contains a quote made by the provider defining the estimated cost(s) associated with the
request and/or any resources provisioned as a result of the request.
requestCompletion Contains additional request completion information.
requestData Contains a map of the provider-specific field-value pairs collected for this request.
retriesRemaning Specifies the number of attempts remaining to move this request from its current state to the
next state in the request workflow.
Some state transitions require calls to external services. These calls may fail due to transient
errors such as momentary network errors. In these cases, the catalog will retry the call a
number of times before failing.
This property defines the number of retries remaining for the current state transition. When it
reaches 0, the catalog will stop retrying and mark the request as failed. This property is reset to
the default number of retries for every new operation that is triggered.
requestedItemName Specifies the item name.
Programming Guide
VMware, Inc. 52
Property Description
requestedItemDescription Specifies the item description.
components Returns the list of components associated with the request. The provider supplies this list of
components after request initialization.
Example: Curl Command
To construct your request, refer to the entitledCatalogItemViews response received when you ran the
request described in Syntax for Getting a Template Request for a Catalog Item, locate a link field that
contains a value similar to the following:
{
"@type":"link",
"href":"https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-
b5a1-d5f997c8ad66/requests",
"rel":"POST: Submit Request"
}
The following example command submits a machine request using appropriately edited template content
from the entitledCatalogItemViews response.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1-
d5f997c8ad66/requests
{
$contentsOfTemplateFromPrecedingSections
}
Example: Output with Request and Response Headers
The following sample displays the request and response headers and the command output. Use the
indicated JSON text file or inline text as input.
{
Accept = application/json
Content-Type = application/json
Content-Length = 2806
}
Response Headers
{
Date = Wed, 03 Dec 2014 20:58:34 GMT
ETag = "0"
Location = https://$host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b
{
$requestObjectDetails
}
Content-Type = application/json;charset=UTF-8
Content-Length = 0
Programming Guide
VMware, Inc. 53
Vary = Accept-Encoding,User-Agent
Keep-Alive = timeout=15, max=100
Connection = Keep-Alive
}
null
Syntax for Viewing Details of a Machine Request
You can use the vRealize Automation REST API catalog service to view the details of a machine request.
Request Status
Typically, the request status information is the most important part of request details. The phase field
corresponds to the status displayed in the Requests tab in the interface. You can rerun this command
multiple times to monitor the state of a machine request.
Table 3‑1. Request Phase Status
Phase Description End State?
UNSUBMITTED Request was saved but not submitted. No
PENDING_PRE_APPROVAL Request is subject to approval - pre-provisioning approval required. No
IN_PROGRESS Request is in progress, machine is being provisioned. No
PENDING_POST_APPROVAL Request is subject to approval, post-provisioning approval
required.
No
SUCCESSFUL Request completed successfully. The machine is available under
provisioned resources on the Items tab.
Yes
FAILED Request failed. Yes
REJECTED Request approval was rejected and will not complete. Yes
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/requests/$requestId
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$requestId Specifies the request ID. See Syntax for Displaying Your Provisioned Resources to view all of
your requests and search for a request ID.
The required request ID is located at the end of the Location URL in the response header.
The request ID is located in the Location field of the response header if you submitted the
request with the –headers flag.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 54
Property Description
version Displays the object version number.
state Specifies the item state, such as submitted.
approvalStatus Specifies a status indicating whether this request has been approved, rejected, or is still
pending some form of approval.
waitingStatus Specifies a status indicating whether this request is waiting on any external users or services
before it is able to progress.
requestNumber Specifies a more user-friendly identifier for this request.
executionStatus Specifies the current execution status of the request.
stateName Specifies the localized state name.
phase Specifies the current phase of the request, which is more coarse grained and easier for users to
understand.
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
description Contains a brief description of this request.
reasons Specifies the business reasons entered by the requestor or owner of this request.
requestedFor Specifies the ID of the user for whom this request is logged.
requestedBy Specifies the ID of the user who actually submitted the request
organization Subtenant and/or tenant owner of this request.
requestorEntitlementId Specified the value of the requestorEntitlement setting.
preApprovalId Specifies the ID of the preApproval setting.
postApprovalId Specifies the ID of the approval generated for the post-provisioning workflow step.
dateCreated Specifies the date when this request was sent to the catalog.
lastUpdated Specifies the date when this request was last updated.
dateSubmitted Specifies the date when this request was first submitted.
dateApproved Specifies the date when this request was approved.
dateCompleted Specifies the date when this request was completed.
quote Contains a quote made by the provider defining the estimated cost(s) associated with the
request and/or any resources provisioned as a result of the request.
requestCompletion Contains additional request completion information.
requestData Contains a map of the provider-specific field-value pairs collected for this request.
retriesRemaning Specifies the number of attempts remaining to move this request from its current state to the
next state in the request workflow.
Some state transitions require calls to external services. These calls may fail due to transient
errors such as momentary network errors. In these cases, the catalog will retry the call a
number of times before failing.
This property defines the number of retries remaining for the current state transition. When it
reaches 0, the catalog will stop retrying and mark the request as failed. This property is reset to
the default number of retries for every new operation that is triggered.
requestedItemName Specifies the item name.
Programming Guide
VMware, Inc. 55
Property Description
requestedItemDescription Specifies the item description.
components Returns the list of components associated with the request. The provider supplies this list of
components after request initialization.
Example: curl Command
The following example command displays details of a request.
curl --insecure -H "Content-Type: application/json" -H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b
Example: JSON Output
The following sample output contains information about the catalog item request 7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b.
{
"@type": "CatalogItemRequest",
"id": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"iconId": "cafe_default_icon_genericCatalogItem",
"version": 6,
"requestNumber": 8,
"state": "SUCCESSFUL",
"description": "API test",
"reasons": null,
"requestedFor": "csummers@example.com",
"requestedBy": "csummers@example.com",
"organization": {
"tenantRef": "mycompany",
"tenantLabel": "mycompany",
"subtenantRef": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"subtenantLabel": "Demo Group"
},
"requestorEntitlementId": "1b409157-152c-43c4-b4cc-1cdef7f6adf8",
"preApprovalId": null,
"postApprovalId": null,
"dateCreated": "2015-07-29T13:50:33.689Z",
"lastUpdated": "2015-07-29T13:55:35.951Z",
"dateSubmitted": "2015-07-29T13:50:33.689Z",
"dateApproved": null,
"dateCompleted": "2015-07-29T13:55:35.949Z",
"quote": {},
"requestCompletion": {
"requestCompletionState": "SUCCESSFUL",
"completionDetails": null
},
"requestData": {
$detailsOfSubmittedRequest
},
"retriesRemaining": 3,
Programming Guide
VMware, Inc. 56
"requestedItemName": "Linux",
"requestedItemDescription": "Linux blueprint for API demo",
"stateName": "Successful",
"approvalStatus": "POST_APPROVED",
"executionStatus": "STOPPED",
"waitingStatus": "NOT_WAITING",
"phase": "SUCCESSFUL",
"catalogItemRef": {
"id": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"label": "Linux"
}
}
Approve a Machine Request
You can use a sequence of REST API workitem service commands to approve a machine request.
Prerequisites
nLog in to vRealize Automation as an approver with at least one of the following qualifications:
nYou are designated as an approver in an approval policy.
nYou belong to a group which has been designated as an approval group in an approval policy.
nYou are designated as a delegate for someone who is an approver.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nSyntax for Listing Work Items
You can use the vRealize Automation REST API workitem service to list the unique IDs of all
available work items.
nSyntax for Getting Work Item Details
You can use the vRealize Automation REST API workitem service to display the details of a pending
work item. You need these details to submit a completion request.
nSyntax for Constructing a JSON File to Approve a Machine Request
You can specify a JSON file in your vRealize Automation REST API command line input. For
example, when you enter a command to approve a machine request, you can include the name of a
JSON file that contains all the parameters required to approve the request and complete the work
item.
nSyntax for Approving a Submitted Machine Request
You can approve a work item request to complete the request by using the vRealize Automation
REST API. To construct the approval command, you add work item and work item form details to a
JSON file, and call that JSON file from the command line. Use a template to correctly format the
JSON file content.
Programming Guide
VMware, Inc. 57
nSyntax for Updating Cost Information
You can use the composition service to update and display cost information for a deployment. The
cost of a deployment is based on which blueprint you request plus details of the specific request. For
example, if the blueprint allows for a range of CPU, memory, or storage values, the cost depends on
the value requested.
Procedure
1List all available work item IDs.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/workitem-service/api/workitems
2Get details for a specific work item ID.
For example, get the details for work item 5e3e9519-78ea-4409-a52c-e4aa3bc56511.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/workitem-service/api/workitems/5e3e9519-78ea-4409-a52c-e4aa3bc56511
3Construct a JSON file that contains the work item ID information that you need to approve a machine
request.
a Copy the appropriate JSON input file template to a new file in an XML editor that maintains
formatting.
b Substitute the input variables in the template with the values you obtained for your specific work
item ID, for example 5e3e9519-78ea-4409-a52c-e4aa3bc56511.
c Save the file with a new name, for example, approve.json.
4Approve the submitted machine request by specifying the work item ID and including the JSON file as
part of the command line.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/workitem-service/api/workitems/5e3e9519-78ea-4409-
a52c-e4aa3bc56511/actions/com.mycompany.csp.core.approval.action.approve
--d @approve.json
If the command is successful, the HTTP status is 201 Created. If the command is not successful, the
HTTP status is 204 No Content.
Syntax for Listing Work Items
You can use the vRealize Automation REST API workitem service to list the unique IDs of all available
work items.
Programming Guide
VMware, Inc. 58
Inputs
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/workitem-service/api/workitems
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Specifies an array of link objects, each of which contains the following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
nFirst, Previous, Next, and Last refer to corresponding pages of pageable lists.
nSpecifies the application or service that determines the other names.
nhref
Specifies the URL that produces the result.
work itemNumber Displays a reference number for the work item.
id Specifies the unique identifier of this resource.
version Displays the object version number.
assignees Displays the list of work item assignees.
subTenantId Optionally associates the work item with a specific business group granting users with
management responsibilities over that business group permission to see the approval.
tenantId Specifies the tenant ID for the work item.
callbackEntityId Specifies the callback entity ID for the work item.
work itemType Specifies the work item type for the work item.
completedDate Specifies the date when the work item was completed.
assignedDate Specifies the date when the work item was assigned.
createdDate Specifies the created date of this instance.
assignedOrCompletedDate Specifies the date to be displayed on UI.
formUrl Specifies the URL from which the layout for this work item can be retrieved.
serviceId Specifies the service ID that generated this work item instance.
work itemRequest Specifies the corresponding work item request object.
status Specifies the status of the work item.
Programming Guide
VMware, Inc. 59
Property Description
completedBy Specifies the principal ID of user who completed the work item.
availableActions Contains a list of relevant work item actions.
Metadata Specifies the paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned.
ntotalPages: Specifies the total number of pages of data available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Example: curl Command
The following example command retrieves all the available work item IDs.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/workitem-service/api/workitems
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "WorkItem",
"id" : "1755ef1a-d6f0-4901-9ecd-d03352ae4a05",
"version" : 1,
"workItemNumber" : 1,
"assignees" : [ {
"principalId" : "tony@example.mycompany.com",
"principalType" : "USER"
} ],
"tenantId" : "MYCOMPANY",
"callbackEntityId" : "1",
"workItemType" : {
"id" : "com.mycompany.cafe.samples.travel.workItem",
"name" : "Workspace Assignment",
"pluralizedName" : "Workspace Assignments",
"description" : "Location Specific Workspace Assignment",
"serviceTypeId" : "com.mycompany.cafe.samples.travel.api",
"actions" : [ {
"id" : "com.mycompany.cafe.samples.travel.workItem.complete",
"name" : "Reserve Workspace",
"stateName" : "Completed",
"icon" : {
"id" : "baa623db-0ca0-4db7-af41-9a301bc9e152",
"name" : "Complete Action Icon",
"contentType" : "image/png",
"image" : null
Programming Guide
VMware, Inc. 60
}
}, {
"id" : "com.mycompany.cafe.samples.travel.workItem.cancel",
"name" : "Workspace Unavailable",
"stateName" : "Cancelled",
"icon" : {
"id" : "b03f994a-e1ec-4aae-8fae-e747ed680a5e",
"name" : "Cancel Action Icon",
"contentType" : "image/png",
"image" : null
}
} ],
"completeByEmail" : true,
"commentsField" : null,
"listView" : {
"columns" : [ {
"id" : "duration",
"label" : "Duration",
"description" : "The length of stay, measured in days.",
"dataType" : {
"type" : "primitive",
"typeId" : "INTEGER"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
}, {
"id" : "location",
"label" : "Destination",
"description" : "The destination to which travel is being requested.",
"dataType" : {
"type" : "ref",
"componentTypeId" : null,
"componentId" : null,
"classId" : "location",
"typeFilter" : null,
"label" : null
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
}, {
"id" : "arrivalDate",
"label" : "Arrival Date",
"description" : "The date of arrival at the destination",
Programming Guide
VMware, Inc. 61
"dataType" : {
"type" : "primitive",
"typeId" : "DATE_TIME"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
} ],
"defaultSequence" : [ "location", "arrivalDate", "duration" ]
},
"version" : 3,
"forms" : {
"workItemDetails" : {
"type" : "external",
"formId" : "travel.seating.task"
},
"workItemSubmission" : {
"type" : "external",
"formId" : "travel.seating.task"
},
"workItemNotification" : {
"type" : "external",
"formId" : "travel.itinerary.details"
}
}
},
.
.
.
"completedDate" : null,
"assignedDate" : "2014-02-20T23:55:31.600Z",
"createdDate" : "2014-02-20T23:55:31.600Z",
"assignedOrCompletedDate" : "2014-02-20T23:55:31.600Z",
"serviceId" : "2af18227-6a00-49e9-a76b-96de3ee767d2",
"workItemRequest" : {
"itemId" : "531660fd-b540-4946-9917-38c023b61c02",
"itemName" : "test travel 1",
"itemDescription" : "test travel 1",
"itemRequestor" : "tony@example.mycompany.com",
"itemCost" : 0.0,
"itemData" : {
"entries" : [ {
"key" : "requestLeaseTotal",
"value" : {
"type" : "money",
"currencyCode" : null,
"amount" : 1065.0
Programming Guide
VMware, Inc. 62
}
}, {
"key" : "approvalId",
"value" : {
"type" : "string",
"value" : "7a8b6054-1922-4f82-9266-245dffaa957c"
}
}, {
"key" : "requestClassId",
"value" : {
"type" : "string",
"value" : "request"
}
}, {
"key" : "requestedFor",
"value" : {
"type" : "string",
"value" : "tony@example.mycompany.com"
}
}, {
"key" : "requestReasons"
}, {
"key" : "requestedItemName",
"value" : {
"type" : "string",
"value" : "test travel 1"
}
}, {
"key" : "requestInstanceId",
"value" : {
"type" : "string",
"value" : "1cfe7177-74e3-4d68-a559-ea17587022ca"
}
}, {
"key" : "requestRef",
"value" : {
"type" : "string",
"value" : "15"
}
}, {
"key" : "requestedItemDescription",
"value" : {
"type" : "string",
"value" : "test travel 1"
}
}, {
"key" : "requestLeaseRate",
"value" : {
"type" : "moneyTimeRate",
"cost" : {
"type" : "money",
"currencyCode" : null,
"amount" : 213.0
},
"basis" : {
Programming Guide
VMware, Inc. 63
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 1
}
}
}, {
"key" : "requestingServiceId",
"value" : {
"type" : "string",
"value" : "f91d044a-04f9-4b96-8542-375e3e4e1dc1"
}
}, {
"key" : "policy",
"value" : {
"type" : "string",
"value" : "test travel approval policy"
}
}, {
"key" : "phase",
"value" : {
"type" : "string",
"value" : "Pre Approval"
}
}, {
"key" : "requestDescription",
"value" : {
"type" : "string",
"value" : "t"
}
}, {
"key" : "requestLease",
"value" : {
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 5
}
}, {
"key" : "requestedBy",
"value" : {
"type" : "string",
"value" : "tony@example.mycompany.com"
}
} ]
}
},
"status" : "Active",
"availableActions" : [ ]
} ],
"metadata" : {
"size" : 20,
"totalElements" : 7,
"totalPages" : 1,
"number" : 1,
Programming Guide
VMware, Inc. 64
"offset" : 0
}
}
Syntax for Getting Work Item Details
You can use the vRealize Automation REST API workitem service to display the details of a pending work
item. You need these details to submit a completion request.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/workitem-service/api/workitems/workitem_ID
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
workitem_ID Specifies the unique identifier of a work item. See Syntax for Listing Work Items.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Specifies an array of link objects, each of which contains the following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
nFirst, Previous, Next, and Last refer to corresponding pages of pageable lists.
nSpecifies the application or service that determines the other names.
nhref
Specifies the URL that produces the result.
work itemNumber Displays a reference number for the work item.
id Specifies the unique identifier of this resource.
version Displays the object version number.
assignees Displays the list of work item assignees.
subTenantId Optionally associates the work item with a specific business group granting users with
management responsibilities over that business group permission to see the approval.
tenantId Specifies the tenant ID for the work item.
callbackEntityId Specifies the callback entity ID for the work item.
work itemType Specifies the work item type for the work item.
Programming Guide
VMware, Inc. 65
Property Description
completedDate Specifies the date when the work item was completed.
assignedDate Specifies the date when the work item was assigned.
createdDate Specifies the created date of this instance.
assignedOrCompletedDate Specifies the date to be displayed on UI.
formUrl Specifies the URL from which the layout for this work item can be retrieved.
serviceId Specifies the service ID that generated this work item instance.
work itemRequest Specifies the corresponding work item request object.
status Specifies the status of the work item.
completedBy Specifies the principal ID of user who completed the work item.
availableActions Contains a list of relevant work item actions.
Metadata Specifies the paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned.
ntotalPages: Specifies the total number of pages of data available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Example: curl Command
The following example command retrieves the necessary details for the specified work item.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/workitem-service/api/workitems/5e3e9519-78ea-4409-a52c-e4aa3bc56511
Example: JSON Output
The following JSON output is returned based on the command input.
To view the contents of a JSON output file, for example workItemDetails.json, use the ! command
with more in UNIX or type in Windows.
n(UNIX) vcac-shell>! more workItemDetails.json
n(Windows) vcac-shell> ! CMD /C type workItemDetails.json
vcac-shell> ! more workItemDetails.json
{
"id" : "5e3e9519-78ea-4409-a52c-e4aa3bc56511",
"version" : 0,
"workItemNumber" : 8,
"assignees" : [ {
"principalId" : "tony@example.mycompany.com",
"principalType" : "USER"
} ],
"subTenantId" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
Programming Guide
VMware, Inc. 66
"tenantId" : "MYCOMPANY",
"callbackEntityId" : "069dc3ce-a260-4d6a-b191-683141c994c0",
"workItemType" : {
"id" : "com.mycompany.csp.core.approval.workitem.request",
"name" : "Approval",
"pluralizedName" : "Approvals",
"description" : "",
"serviceTypeId" : "com.mycompany.csp.core.cafe.approvals",
"actions" : [ {
"id" : "com.mycompany.csp.core.approval.action.approve",
"name" : "Approve",
"stateName" : "Approved",
"icon" : {
"id" : "c192b6a7-5b35-4a3b-8593-107ffcf8c3a8",
"name" : "approved.png",
"contentType" : "image/png",
"image" : null
}
}, {
"id" : "com.mycompany.csp.core.approval.action.reject",
"name" : "Reject",
"stateName" : "Rejected",
"icon" : {
"id" : "61c6da67-1164-421d-b575-10a245c89e10",
"name" : "rejected.png",
"contentType" : "image/png",
"image" : null
}
} ],
"completeByEmail" : true,
"commentsField" : "businessJustification",
"listView" : {
"columns" : [ {
"id" : "requestedItemName",
"label" : "Requested Item",
"description" : "",
"dataType" : {
"type" : "primitive",
"typeId" : "STRING"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
},
.
.
.
{
Programming Guide
VMware, Inc. 67
"id" : "requestLease",
"label" : "Lease",
"description" : "",
"dataType" : {
"type" : "primitive",
"typeId" : "TIME_SPAN"
},
"displayAdvice" : null,
"state" : {
"dependencies" : [ ],
"facets" : [ ]
},
"filterable" : false,
"sortable" : false,
"isMultiValued" : false
} ],
"defaultSequence" : [ "requestRef", "requestedItemName", "requestedFor", "requestLease",
"requestLeaseRate", "requestLeaseTotal" ]
},
"version" : 1,
"forms" : {
"workItemDetails" : {
"type" : "external",
"formId" : "approval.details"
},
"workItemSubmission" : {
"type" : "external",
"formId" : "approval.submission"
},
"workItemNotification" : {
"type" : "external",
"formId" : "approval.notification"
}
}
},
"completedDate" : null,
"assignedDate" : "2014-02-25T01:26:07.153Z",
"createdDate" : "2014-02-25T01:26:07.153Z",
"assignedOrCompletedDate" : "2014-02-25T01:26:07.153Z",
"serviceId" : "2af18227-6a00-49e9-a76b-96de3ee767d2",
"workItemRequest" : {
"itemId" : "069dc3ce-a260-4d6a-b191-683141c994c0",
"itemName" : "test-blueprint",
"itemDescription" : "",
"itemRequestor" : "fritz@example.mycompany.com",
"itemCost" : 0.0,
"itemData" : {
"entries" : [ {
"key" : "requestLeaseTotal"
}, {
"key" : "approvalId",
"value" : {
"type" : "string",
"value" : "469c11ae-ed27-4790-baf1-c6839f35d474"
}
Programming Guide
VMware, Inc. 68
}, {
"key" : "requestClassId",
"value" : {
"type" : "string",
"value" : "request"
}
}, {
"key" : "requestedFor",
"value" : {
"type" : "string",
"value" : "fritz@example.mycompany.com"
}
}, {
"key" : "requestReasons",
"value" : {
"type" : "string",
"value" : ""
}
}, {
"key" : "requestedItemName",
"value" : {
"type" : "string",
"value" : "test-blueprint"
}
.
.
.
}, {
"key" : "requestLease"
}, {
"key" : "requestedBy",
"value" : {
"type" : "string",
"value" : "fritz@example.mycompany.com"
}
} ]
}
},
"status" : "Active",
"availableActions" : [ ]
}
Syntax for Constructing a JSON File to Approve a Machine
Request
You can specify a JSON file in your vRealize Automation REST API command line input. For example,
when you enter a command to approve a machine request, you can include the name of a JSON file that
contains all the parameters required to approve the request and complete the work item.
Programming Guide
VMware, Inc. 69
Template JSON File Values
Copy the following template to start constructing a properly formatted JSON file in a text editor. Replace
the highlighted values with your obtained work item details. After you create the JSON file, you can
include it, or its contents, when you approve a submitted machine request. See Syntax for Approving a
Submitted Machine Request.
{
"formData": {
"entries": [
{
"key": "source-source-provider-Cafe.Shim.VirtualMachine.NumberOfInstances",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "source-source-provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 512
}
},
{
"key": "source-source-provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "source-businessJustification",
"value": {
"type": "string",
"value": "solves abx request"
}
},
{
"key": "source-source-provider-VirtualMachine.LeaseDays",
"value": {
"type": "integer",
"value": 0
}
}
]
},
"workItemId": "5e3e9519-78ea-4409-a52c-e4aa3bc56511",
"workItemActionId": "com.mycompany.csp.core.approval.action.approve"
}
Certain parameters are available to use in the JSON template.
Programming Guide
VMware, Inc. 70
Table 3‑2. JSON Template Value Table
JSON File Parameter Name Description of Value
workItemId Specifies the value of the corresponding work item ID obtained from the
work item list.
source-source-provider-
Cafe.Shim.VirtualMachine.NumberOfInstances value
Specifies the number of instances requested.
source-source-provider-VirtualMachine.Memory.Size Specifies the amount of memory requested in GB.
source-source-provider-VirtualMachine.CPU.Count Specifies the number of CPUs requested.
source-businessJustification Specifies the text description of reason for request.
source-source-provider-VirtualMachine.LeaseDays Specifies the number of days to lease.
workItemActionId To approve a request, include the approve statement, for example
com.mycompany.csp.core.approval.action.approve..
To reject a request, include the reject statement, for example
com.mycompany.csp.core.approval.action.reject.
Example: JSON Input File
Use the following JSON input file sample when constructing a file.
{
"@type": "CatalogItemRequest",
"catalogItemRef": {
"id": "65fbca06-a28e-46f3-bced-c6e5fb3a66f9"
},
"organization": {
"tenantRef": "MYCOMPANY",
"subtenantRef": "cccd7a7e-5283-416b-beb0-45eb4e924dcb"
},
"requestedFor": "fritz@example.mycompany.com",
"state": "SUBMITTED",
"requestNumber": 0,
"requestData": {
"entries": [{
"key": "provider-blueprintId",
"value": {
"type": "string",
"value": "e16edcf9-6a10-4bc7-98e2-a33361aeb857"
}
},
{
"key": "provider-provisioningGroupId",
"value": {
"type": "string",
"value": "cccd7a7e-5283-416b-beb0-45eb4e924dcb"
}
},
{
"key": "requestedFor",
"value": {
"type": "string",
Programming Guide
VMware, Inc. 71
"value": "fritz@example.mycompany.com"
}
},
{
"key": "provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 1024
}
},
{
"key": "provider-VirtualMachine.LeaseDays",
"value": {
"type": "integer",
"value": 30
}
},
{
"key": "provider-__Notes",
"value": {
"type": "string",
"value": "MYCOMPANY machine"
}
},
{
"key": "provider-VirtualMachine.Disk0.Size",
"value": {
"type": "string",
"value": "1"
}
},
{
"key": "provider-VirtualMachine.Disk0.Letter",
"value": {
"type": "string",
"value": "C"
}
},
{
"key": "provider-VirtualMachine.Disk0.Label",
"value": {
"type": "string",
"value": "main"
}
}]
}
}
Programming Guide
VMware, Inc. 72
Syntax for Approving a Submitted Machine Request
You can approve a work item request to complete the request by using the vRealize Automation REST
API. To construct the approval command, you add work item and work item form details to a JSON file,
and call that JSON file from the command line. Use a template to correctly format the JSON file content.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/workitem-service/api/workitems/workitem_ID
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
workitem_ID Specifies the unique identifier of a work item. See Syntax for Listing
Work Items.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Specifies an array of link objects, each of which contains the following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
nFirst, Previous, Next, and Last refer to corresponding pages of pageable lists.
nSpecifies the application or service that determines the other names.
nhref
Specifies the URL that produces the result.
work itemNumber Displays a reference number for the work item.
id Specifies the unique identifier of this resource.
version Displays the object version number.
assignees Displays the list of work item assignees.
subTenantId Optionally associates the work item with a specific business group granting users with
management responsibilities over that business group permission to see the approval.
tenantId Specifies the tenant ID for the work item.
callbackEntityId Specifies the callback entity ID for the work item.
work itemType Specifies the work item type for the work item.
completedDate Specifies the date when the work item was completed.
Programming Guide
VMware, Inc. 73
Property Description
assignedDate Specifies the date when the work item was assigned.
createdDate Specifies the created date of this instance.
assignedOrCompletedDate Specifies the date to be displayed on UI.
formUrl Specifies the URL from which the layout for this work item can be retrieved.
serviceId Specifies the service ID that generated this work item instance.
work itemRequest Specifies the corresponding work item request object.
status Specifies the status of the work item.
completedBy Specifies the principal ID of user who completed the work item.
availableActions Contains a list of relevant work item actions.
Metadata Specifies the paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned.
ntotalPages: Specifies the total number of pages of data available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Example: Example: curl Command
Approve a submitted machine request by specifying its work item ID and using a JSON file named
approve.json to pass arguments to the command line.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/workitem-service/api/workitems/5e3e9519-78ea-4409-
a52c-e4aa3bc56511/actions/com.mycompany.csp.core.approval.action.approve
--d @approve.json
Error Conditions
If the same request is submitted a second time, the following error response is received:
Command failed [Rest Error]: {Status code: 400}, {Error code: 12005} ,
{Error Source: null}, {Error Msg: Work item 5e3e9519-78ea-4409-a52c-e4aa3bc56511
is in COMPLETED state. Requested operation cannot be performed.}, {System Msg:
Work item 5e3e9519-78ea-4409-a52c-e4aa3bc56511 is in COMPLETED state. Requested
operation cannot be performed.}
Programming Guide
VMware, Inc. 74
If a user who is not authorized to approve the request submits the request, the following error response is
received:
Command failed [Rest Error]: {Status code: 400}, {Error code: 12017} ,
{Error Source: null}, {Error Msg: User fritz@example.mycompany.com not authorized to
complete work item with ID 5e3e9519-78ea-4409-a52c-e4aa3bc56511.}, {System Msg:
User fritz@example.mycompany.com not authorized to complete Work item with id
5e3e9519-78ea-4409-a52c-e4aa3bc56511.}
Syntax for Updating Cost Information
You can use the composition service to update and display cost information for a deployment. The cost of
a deployment is based on which blueprint you request plus details of the specific request. For example, if
the blueprint allows for a range of CPU, memory, or storage values, the cost depends on the value
requested.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL //$host/composition-
service/api/blueprints/$BlueprintId/costs/upfront
Method Post
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
Programming Guide
VMware, Inc. 75
Parameter Description
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP Body Specifies the blueprint ID for the blueprint for which you are
requesting cost information and other information.
nBlueprint ID: Specifies the blueprint ID.
nrequestedFor: The user for whom this request is being made.
Must be the fully qualified user ID.
nsubTenantId: Specifies the subtenant ID associated with the
blueprint
nrequestData: Specifies data that identifies the blueprint further.
nentries
nKey: The name of the machine on which the blueprint
resides.
nvalue: Specifies key-value pairs that further identify the
blueprint, such as the type of the value, the
componentType ID for the item, the classID of the
value, and where the blueprint resides. In turn, each
entry contains an array of key-value pairs that identify
the type of data used to compute the cost that is to be
displayed.
nValues: Specifies an array of type filters.
nEntries: Specifies a list of key-value pairs that
specify the values to be used in computing the cost.
For example, the cluster, CPU, and allocated
memory to use.
Output
The command output contains property names and values based on the command input parameters.
Property Description
setupFee Specifies the one time setup fee associated with the component.
totalLeasePriceInfo Specifies the minimum cost and maximum cost for the lease
period.
averageDailyPriceInfo Specifies the average daily price, which depends on the
reservation available for the component.
count Specifies the instance count of the component.
memory Specifies memory requested for this component.
additional Specifies the additional cost, if any, associated with the
component.
cpu Specifies the cpu requested for the component.
storage Specifies the storage requested for the component.
componentId Specifies the component ID, or total cost of the deployment.
Programming Guide
VMware, Inc. 76
Example: curl Command
The following sample command updates and displays the cost of a sample blueprint with one node. The
HTTP body is included as part of the command line input.
curl -- insecure -H “Content Type: application/json”
-H "Authorization: Bearer $token"
https://$host/composition-service/api/blueprints/$BlueprintId/costs/upfront"
{
"blueprintId": "myblueprintId",
"requestedFor": "fritz@coke.sqa-horizon.local",
"subTenantId": "7a961949-13c4-4f3d-9010-66db8da6c51e",
"requestData": {
"entries": [
{
"key": "vSphere_Machine_1",
"value": {
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"classId": "Blueprint.Node",
"typeFilter": "phanisimple*vSphere_Machine_1",
"values": {
"entries": [
{
"key": "_cluster",
"value": {
"type": "integer",
"value": 3
}
},
{
"key": "cpu",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "memory",
"value": {
"type": "integer",
"value": 2048
}
}
]
}
}
}
]
}
}
Programming Guide
VMware, Inc. 77
Example: JSON Output for a Blueprint Cost Update
[{"componentId":"vSphere_Machine_1",
"setupFee":"$0.00",
"totalLeasePriceInfo":{"min":50.0543225806451601,"max":50.0543225806451601,"displayString":"$50.05"},
"averageDailyPriceInfo":{"min":16.6847741935483867,"max":16.6847741935483867,"displayString":"$16.68"},
"count":3
"fieldMap":{"setup_fee":{"min":0,"max":0,"displayString":"$0.00"},
"memory":{"min":8.00,"max":8.00,"displayString":"$8.00"},
"additional":{"min":8.6847741935483867,"max":8.6847741935483867,"displayString":"$8.68"},
"cpu":{"min":0.0,"max":0.0,"displayString":"$0.00"},
"storage":{"min":0,"max":0,"displayString":"$0.00"}}},
{"componentId":"Total","setupFee":"","totalLeasePriceInfo":
{"min":50.0543225806451601,"max":50.0543225806451601,"displayString":"$50.05"},
"averageDailyPriceInfo":{"min":16.6847741935483867,"max":16.6847741935483867,"displayString":"$16.68"},
"count":3,"fieldMap":{}}]
List Provisioned Resources
You can use the REST API catalog service to log in to vRealize Automation and display a full or filtered
list of your provisioned resources .
Prerequisites
nLog in to vRealize Automation as a business group manager.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the business group subtenant ID values to specify on the command line. See Syntax for
Displaying Your Provisioned Resources.
nSyntax for Displaying Your Provisioned Resources
You can use the REST API catalog service to display a list of all the provisioned resources that you
own.
nSyntax for Displaying Provisioned Resources by Resource Type
You can use the REST API catalog service to display a list of the provisioned resources that you
own filtered by machine resource type.
nSyntax for Displaying All Available Resource Types
You can use the REST API catalog service to display all the resource types that are available on the
system.
nSyntax for Displaying Provisioned Resources by Business Groups You Manage
You can use the REST API catalog service to display all of the provisioned resources that are owned
by the business groups that you manage. You can optionally filter the list by business group name.
Programming Guide
VMware, Inc. 78
nSyntax for Viewing Machine Details
You can use the vRealize Automation REST API catalog service to display the machine details for a
provisioned machine.
Procedure
1Display a list of all the provisioned resources.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/?page=n&limit=n
2Display a list of the provisioned resources filtered by machine resource type.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/resourceTypes/Infrastructure.Machine/?page=1&limit=1
3Display all the resource types that are available on the system.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resourceTypes
4Display all of the provisioned resources that are owned by the business groups. Optionally, filter the
list by business group name.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/types/Infrastructure.Machine/?page=1&limit=2&
$orderby=dateCreated desc&$filter=((organization/subTenant/id eq 'subtenantID_group1') or
(organization/subTenant/id eq ''subtenantID_group2') … )"
5Display the machine details for a provisioned machine.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/resources/resourceID/
Syntax for Displaying Your Provisioned Resources
You can use the REST API catalog service to display a list of all the provisioned resources that you own.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 79
Parameter Description
URL https://$host/catalog-service/api/consumer/resources
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
resourceTypeRef Specifies the resource type.
name Specifies the resource name.
description Specifies the resource description.
status Specifies the resource status.
catalogItem Specifies the catalog item that defines the service this resource is based on.
requestId Specifies the request ID that provisioned this resource.
providerBinding Specifies the provider binding.
owners Species the owners of this resource.
organization Specifies the subtenant or tenant that owns this resource.
dateCreated Specifies the data and time at which the resource was created.
lastUpdated Specifies the date and time at which the resource was most recently modified.
hasLease Returns true if the resource is subject to a lease.
lease Displays the resource's current lease as start and end time stamps.
leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Specifies the sequence of available operations that can be performed on this resource.
forms Specifies the forms used to render this resource.
resourceData Displays the extended provider-defined properties of the resource.
Programming Guide
VMware, Inc. 80
Example: curl Command
The following example command displays all applicable provisioned resources.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/?page=n&limit=n
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ {
"@type" : "link",
"rel" : "next",
"href" : "https://vra152-009-067.mycompany.com/catalog-service/api/consumer/resources/?
page=2&limit=1"
} ],
"content" : [ {
"@type" : "ConsumerResource",
"id" : "c24e8c75-c201-489c-b51c-8d7009c23563",
"iconId" : "Travel_100.png",
"resourceTypeRef" : {
"id" : "com.mycompany.mystuff.samples.travel.packageType",
"label" : "Reservation"
},
"name" : "example",
"description" : "asd",
"status" : "ACTIVE",
"catalogResource" : {
"id" : "6fddafcd-bc3d-4753-8a2a-5fa3f78a5a90",
"label" : "example"
},
"requestId" : "55e7fcf3-4c77-4b11-a442-1f282333ac91",
"providerBinding" : {
"bindingId" : "1",
"providerRef" : {
"id" : "f60f5d1e-d6e9-4d98-9c48-f70a3e405346",
"label" : "travel-service"
}
},
…
}
Syntax for Displaying Provisioned Resources by Resource Type
You can use the REST API catalog service to display a list of the provisioned resources that you own
filtered by machine resource type.
Programming Guide
VMware, Inc. 81
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/resourceType
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Filter by the following resource types:
nInfrastructure.Machine
nInfrastructure.AppServic
nInfrastructure.Cloud
nInfrastructure.Physical
nInfrastructure.vApp
nInfrastructure.Virtual
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
resourceTypeRef Specifies the resource type.
name Specifies the resource name.
description Specifies the resource description.
status Specifies the resource status.
catalogItem Specifies the catalog item that defines the service this resource is based on.
requestId Specifies the request ID that provisioned this resource.
providerBinding Specifies the provider binding.
owners Species the owners of this resource.
organization Specifies the subtenant or tenant that owns this resource.
dateCreated Specifies the data and time at which the resource was created.
lastUpdated Specifies the date and time at which the resource was most recently modified.
hasLease Returns true if the resource is subject to a lease.
lease Displays the resource's current lease as start and end time stamps.
leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
Programming Guide
VMware, Inc. 82
Property Description
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Specifies the sequence of available operations that can be performed on this resource.
forms Specifies the forms used to render this resource.
resourceData Displays the extended provider-defined properties of the resource.
Example: curl Command
The following example command displays the provisioned resources by resource type.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/resourceTypes/Infrastructure.Machine/?page=1&limit=1
Example: JSON Output
In this example, the highlighted resource ID (3bfde906-81b9-44c3-8c2d-07d2c9768168) corresponds
to a provisioned machine owned by the logged-in user. The resource IDs are used in requests to retrieve
the details for the corresponding machines.
Also in this example, the subtenantRef ID (eab762cb-6e75-4379-83ef-171a71c9f00e) corresponds to
the business group of the logged-in user. If the logged-in user is also the manager of the business group,
the subtenantRef ID is used to get resources from all business groups that the user manages.
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "ConsumerResource",
"id" : "3bfde906-81b9-44c3-8c2d-07d2c9768168",
"iconId" : "cafe_default_icon_genericCatalogResource",
"resourceTypeRef" : {
"id" : "Infrastructure.Virtual",
"label" : "Virtual Machine"
},
"name" : "test2",
"description" : null,
"status" : "ACTIVE",
"catalogResource" : {
"id" : "e2f397be-72ad-4ec4-a688-c017560fa1a3",
"label" : "test-blueprint"
},
Programming Guide
VMware, Inc. 83
"requestId" : "b013d2fa-4ba4-416c-b46b-98bb8cc7b076",
"providerBinding" : {
"bindingId" : "8a4581a0-84f9-4e80-9af6-75d79633e382",
"providerRef" : {
"id" : "6918cd49-b737-467f-94bf-d14d52c78fba",
"label" : "iaas-service"
}
},
"owners" : [ {
"tenantName" : "MYCOMPANY",
"ref" : "fritz@example.mycompany.com",
"type" : "USER",
"value" : "Fritz Arbeiter"
} ],
"organization" : {
"tenantRef" : "MYCOMPANY",
"tenantLabel" : "QETenant",
"subtenantRef" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"subtenantLabel" : "MyTestAgentBusinessGroup"
},
…
}
Syntax for Displaying All Available Resource Types
You can use the REST API catalog service to display all the resource types that are available on the
system.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/resourceType
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
resourceTypeRef Specifies the resource type.
name Specifies the resource name.
description Specifies the resource description.
Programming Guide
VMware, Inc. 84
Property Description
status Specifies the resource status.
catalogItem Specifies the catalog item that defines the service this resource is based on.
requestId Specifies the request ID that provisioned this resource.
providerBinding Specifies the provider binding.
owners Species the owners of this resource.
organization Specifies the subtenant or tenant that owns this resource.
dateCreated Specifies the data and time at which the resource was created.
lastUpdated Specifies the date and time at which the resource was most recently modified.
hasLease Returns true if the resource is subject to a lease.
lease Displays the resource's current lease as start and end time stamps.
leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Specifies the sequence of available operations that can be performed on this resource.
forms Specifies the forms used to render this resource.
resourceData Displays the extended provider-defined properties of the resource.
Example: curl Command
The following example command displays all available resource types.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resourceTypes
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "ResourceType",
"id" : "Infrastructure.Machine",
"name" : "Machine",
"pluralizedName" : "Machines",
"description" : "The common parent type for all types of machines",
Programming Guide
VMware, Inc. 85
"primary" : true,
"schema" : {
"classId" : "Infrastructure.Machine.Schema",
"typeFilter" : null
},
"forms" : {
"catalogResourceInfoHidden" : true,
"details" : {
"type" : "extension",
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}
Syntax for Displaying Provisioned Resources by Business Groups
You Manage
You can use the REST API catalog service to display all of the provisioned resources that are owned by
the business groups that you manage. You can optionally filter the list by business group name.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/resources/type
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
resourceTypeRef Specifies the resource type.
name Specifies the resource name.
description Specifies the resource description.
status Specifies the resource status.
catalogItem Specifies the catalog item that defines the service this resource is based on.
requestId Specifies the request ID that provisioned this resource.
providerBinding Specifies the provider binding.
owners Species the owners of this resource.
organization Specifies the subtenant or tenant that owns this resource.
Programming Guide
VMware, Inc. 86
Property Description
dateCreated Specifies the data and time at which the resource was created.
lastUpdated Specifies the date and time at which the resource was most recently modified.
hasLease Returns true if the resource is subject to a lease.
lease Displays the resource's current lease as start and end time stamps.
leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Specifies the sequence of available operations that can be performed on this resource.
forms Specifies the forms used to render this resource.
resourceData Displays the extended provider-defined properties of the resource.
Example: curl Command
The following example command displays the provisioned resources of one or more business groups.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/types/Infrastructure.Machine/?page=1&limit=2&
$orderby=dateCreated desc&$filter=((organization/subTenant/id eq 'subtenantID_group1') or
(organization/subTenant/id eq ''subtenantID_group2') … )"
Example: JSON Output
The following JSON output is returned based on the command input.
For the following command input, the specified subtenant IDs correspond to business groups that are
managed by the logged-in user.
rest get catalog-service --u "consumer/resources/types/Infrastructure.Machine/?page=1&limit=2&
$orderby=dateCreated desc&$filter=((organization/subTenant/id eq
'eab762cb-6e75-4379-83ef-171a71c9f00e') or (organization/subTenant/id eq 'fa995528-e289-455e-a0e6-
c2da8b0e1bf9') or (organization/subTenant/id eq '699efe66-fe6e-4e34-96e8-52a34f338d20') or
(organization/subTenant/id eq '4d949784-e93e-4538-accb-6a0a464e4a4b'))"
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "ConsumerResource",
Programming Guide
VMware, Inc. 87
"id" : "3bfde906-81b9-44c3-8c2d-07d2c9768168",
"iconId" : "cafe_default_icon_genericCatalogResource",
"resourceTypeRef" : {
"id" : "Infrastructure.Virtual",
"label" : "Virtual Machine"
},
"name" : "test2",
"description" : null,
"status" : "ACTIVE",
"catalogResource" : {
"id" : "e2f397be-72ad-4ec4-a688-c017560fa1a3",
"label" : "test-blueprint"
},
"requestId" : "b013d2fa-4ba4-416c-b46b-98bb8cc7b076",
"providerBinding" : {
"bindingId" : "8a4581a0-84f9-4e80-9af6-75d79633e382",
"providerRef" : {
"id" : "6918cd49-b737-467f-94bf-d14d52c78fba",
"label" : "iaas-service"
}
},
"owners" : [ {
"tenantName" : "MYCOMPANY",
"ref" : "fritz@example.mycompany.com",
"type" : "USER",
"value" : "Fritz Arbeiter"
} ],
"organization" : {
"tenantRef" : "MYCOMPANY",
"tenantLabel" : "QETenant",
"subtenantRef" : "eab762cb-6e75-4379-83ef-171a71c9f00e",
"subtenantLabel" : "MyTestAgentBusinessGroup"
},
"dateCreated" : "2014-09-19T21:19:37.541Z",
"lastUpdated" : "2014-09-19T21:19:40.888Z",
"hasLease" : true,
"lease" : {
"start" : "2014-09-19T21:18:57.000Z"
},
"leaseForDisplay" : null,
"hasCosts" : true,
"costs" : {
"leaseRate" : {
"type" : "moneyTimeRate",
"cost" : {
"type" : "money",
"currencyCode" : "USD",
"amount" : 0.0
},
"basis" : {
"type" : "timeSpan",
"unit" : "DAYS",
"amount" : 1
}
}
Programming Guide
VMware, Inc. 88
},
"costToDate" : {
"type" : "money",
"currencyCode" : "USD",
"amount" : 0.0
},
"totalCost" : null,
"childResources" : [ ],
"operations" : [ {
"name" : "Reprovision",
"description" : "Reprovision a machine.",
"iconId" : "machineReprovision.png",
"type" : "ACTION",
"id" : "a1caee9b-d67f-41e8-a7b3-131616a0f6ac",
"extensionId" : null,
"providerTypeId" : "com.mycompany.csp.iaas.blueprint.service",
"bindingId" : "Infrastructure.Machine.Action.Reprovision",
"hasForm" : false,
"formScale" : null
} ],
"forms" : {
"catalogResourceInfoHidden" : true,
"details" : {
"type" : "extension",
"extensionId" : "csp.places.iaas.resource.details",
"extensionPointId" : null
}
},
"resourceData" : {
"entries" : [ {
"key" : "Expire",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineGroupName",
"value" : {
"type" : "string",
"value" : "MyTestAgentBusinessGroup"
}
}, {
"key" : "NETWORK_LIST",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ {
"type" : "complex",
"componentTypeId" : "com.mycompany.csp.component.iaas.proxy.provider",
"componentId" : null,
"classId" : "vra.api.model.NetworkViewModel",
"typeFilter" : null,
"values" : {
"entries" : [ {
"key" : "NETWORK_MAC_ADDRESS",
Programming Guide
VMware, Inc. 89
"value" : {
"type" : "string",
"value" : "56:52:4d:e7:46:d4"
}
}, {
"key" : "NETWORK_NAME",
"value" : {
"type" : "string",
"value" : "Test Agent-network-1"
}
} ]
}
} ]
}
}, {
"key" : "SNAPSHOT_LIST",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ ]
}
}, {
"key" : "ConnectViaRdp",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineStatus",
"value" : {
"type" : "string",
"value" : "On"
}
}, {
"key" : "PowerOff",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "DISK_VOLUMES",
"value" : {
"type" : "multiple",
"elementTypeId" : "COMPLEX",
"resources" : [ {
"type" : "complex",
"componentTypeId" : "com.mycompany.csp.component.iaas.proxy.provider",
"componentId" : null,
"classId" : "vra.api.model.DiskInputModel",
"typeFilter" : null,
"values" : {
"entries" : [ {
"key" : "DISK_CAPACITY",
"value" : {
"type" : "integer",
Programming Guide
VMware, Inc. 90
"value" : 1
}
}, {
"key" : "DISK_DRIVE",
"value" : {
"type" : "string",
"value" : "c"
}
}, {
"key" : "DISK_INPUT_ID",
"value" : {
"type" : "string",
"value" : "DISK_INPUT_ID1"
}
} ]
}
} ]
}
}, {
"key" : "MachineBlueprintName",
"value" : {
"type" : "string",
"value" : "test-blueprint"
}
}, {
"key" : "Suspend",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Reboot",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Reprovision",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineStorage",
"value" : {
"type" : "integer",
"value" : 1
}
}, {
"key" : "MachineDailyCost",
"value" : {
"type" : "decimal",
"value" : 0.0
}
}, {
Programming Guide
VMware, Inc. 91
"key" : "Destroy",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "MachineType",
"value" : {
"type" : "string",
"value" : "Virtual"
}
}, {
"key" : "InstallTools",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "Shutdown",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "ChangeLease",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "machineId",
"value" : {
"type" : "string",
"value" : "8a4581a0-84f9-4e80-9af6-75d79633e382"
}
}, {
"key" : "MachineMemory",
"value" : {
"type" : "integer",
"value" : 0
}
}, {
"key" : "MachineGuestOperatingSystem"
}, {
"key" : "MachineName",
"value" : {
"type" : "string",
"value" : "test2"
}
}, {
"key" : "MachineDestructionDate"
}, {
"key" : "MachineCPU",
"value" : {
"type" : "integer",
Programming Guide
VMware, Inc. 92
"value" : 1
}
}, {
"key" : "MachineInterfaceType",
"value" : {
"type" : "string",
"value" : "Test"
}
}, {
"key" : "MachineReservationName",
"value" : {
"type" : "string",
"value" : "Test Agent-Res-1"
}
}, {
"key" : "Reconfigure",
"value" : {
"type" : "boolean",
"value" : true
}
}, {
"key" : "EXTERNAL_REFERENCE_ID"
}, {
"key" : "MachineExpirationDate"
}, {
"key" : "Reset",
"value" : {
"type" : "boolean",
"value" : true
}
} ]
}
} ],
"metadata" : {
"size" : 2,
"totalElements" : 1,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}
Syntax for Viewing Machine Details
You can use the vRealize Automation REST API catalog service to display the machine details for a
provisioned machine.
Programming Guide
VMware, Inc. 93
Using the API to Get Deployment Details
You can use the REST API to view deployed machine details by appending /resourceViews to the
request details URI that you generated when you retrieved request details. So the syntax the GET
statement would read as follows:
http://$host/catalog-service/api/consumer/requests/$requestId/resourceViews
See Syntax for Viewing Details of a Machine Request.
In addition to general information about the provisioned deployment--such as its name, description, and
ID--the response contains additional HATEOAS links that enable you to obtain additional details and
information.
Table 3‑3. HATEOAS Link Functions as Defined by rel Field
Link Description
GET: Catalog Item URI to get the catalog item details (as described in sections 3.2.1 and
3.2.2) from which this catalog item was provisioned.
GET: Request URI to get the request details that provisioned this item.
GET:Template
{com.vmware.csp.component.cafe.composition@reso
urce.action.deployment.$actionName
URI to get a template request for a specific action that you can perform on
this resource. Typically, on a deployment the action will be Delete.
POST:
{com.vmware.csp.component.cafe.composition@reso
urce.action.deployment.$actionName
URI to which to post the request to perform an action, based on the
corresponding template.
GET: Child Resources If the deployment contains child resources (nodes specified in the
composite blueprint), this is the URI to get a list of the resourceViews for
the children of this deployment.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/resources/$resourceId
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$resourceID Specifies a resource ID. See Syntax for Displaying Your Provisioned Resources to view all of
your requests and search for a request ID.
managedOnly If true, the returned requests are from the user's managed subtenants.
page Specifies a page number.
limit Specifies the number of entries to display on a page.
Programming Guide
VMware, Inc. 94
Parameter Description
$orderby Specifies how to order multiple comma-separated properties sorted in ascending or descending
order.
$top Specifies the number of returned entries from the top of the response (total number per page in
relation to skip).
$skip Specifies the number of entries to skip.
filter Contains a Boolean expression to determine if a particular entry is included in the response.
Output
The command output contains property names and values based on the command input parameters.
Property Description
id Specifies the unique identifier of this resource.
iconId Specifies an icon for this request based on the requested object type.
resourceTypeRef Specifies the resource type.
name Specifies the resource name.
description Specifies the resource description.
status Specifies the resource status.
catalogItem Specifies the catalog item that defines the service this resource is based on.
requestId Specifies the request ID that provisioned this resource.
providerBinding Specifies the provider binding.
owners Species the owners of this resource.
organization Specifies the subtenant or tenant that owns this resource.
dateCreated Specifies the data and time at which the resource was created.
lastUpdated Specifies the date and time at which the resource was most recently modified.
hasLease Returns true if the resource is subject to a lease.
lease Displays the resource's current lease as start and end time stamps.
leaseForDisplay Specifies the resource's current lease, #getLease, with time units synchronized with #getCosts.
hasCosts Returns true if the resource is subject to per-time costs.
costs Displays an optional rate of the cost charges for the resource.
costToDate Displays an optional rate of the current cost charges for the resource.
totalCost Displays an optional rate of the cost charges for the entire lease period.
parentResourceRef Displays the parent of this resource.
childResources Displays the children of this resource.
operations Specifies the sequence of available operations that can be performed on this resource.
forms Specifies the forms used to render this resource.
resourceData Displays the extended provider-defined properties of the resource.
Programming Guide
VMware, Inc. 95
Example: curl Command
The following example command displays machine details for a provisioned machine, where the
provisioned machine ID is 7aaf9baf-aa4e-47c4-997b-edd7c7983a5b.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
http://$host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-edd7c7983a5b/resourceViews
Example: JSON Output
In the following example, the provisioned machine resourceID value specified in the command line was
7aaf9baf-aa4e-47c4-997b-edd7c7983a5b.
{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Catalog Item",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItemViews/7c8275d6-1bd6-452a-97c4-d6c053e4baa4"
},
{
"@type": "link",
"rel": "GET: Request",
"href": "https://$host/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$host/catalog-service/api/consumer/resources/c4d3db3e-e397-44ff-
a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$host/catalog-service/api/consumer/resources/c4d3db3e-e397-44ff-
a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests"
},
{
"@type": "link",
"rel": "GET: Child Resources",
"href": "https://$host/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq
%20%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27"
Programming Guide
VMware, Inc. 96
}
],
"resourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Linux-80813151",
"description": null,
"status": null,
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"catalogItemLabel": "Linux",
"requestId": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"resourceType":
"{com.vmware.csp.component.cafe.composition@resource.type.deployment.name}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:51:36.368Z",
"lastUpdated": "2015-07-29T13:55:35.963Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": null,
"hasChildren": true,
"data": {}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Manage Provisioned Deployments
You can use the REST API catalog service to log in to vRealize Automation and view information about
provisioned resources .
Prerequisites
Note The vRealize Automation REST API does not support custom resource actions template API calls.
However, you can perform custom resource actions programmatically by using the vRealize Automation
Cloud Client.
nLog in to vRealize Automation as a business group manager.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
Programming Guide
VMware, Inc. 97
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the business group subtenant ID values to specify on the command line. See Syntax for
Getting Deployment Details.
nSyntax for Getting Deployment Details
You can use the REST API catalog service to identify provisioned items from a given request.
nSyntax for Navigating to the Children of a Deployed Resource
Use the GET: Child Resources link to retrieve a list of the child nodes of a deployment, including
virtual machines, networks, and other objects you may have configured on the blueprint canvas.
nPerform a Day 2 Action: Power Off
You can use the REST API catalog service to perform a power off action. For simple actions that
require no user input, the process is straightforward.
nPerform a Day 2 Action: Change Lease
You can use the REST API catalog service to change a lease. For actions that require user input,
you may need to edit the template prior to submitting the request.
Procedure
1Display a list of all provisioned resources.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
http://
$host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b/resourceViews
The output from this command includes HATEOAS links that enable you to quickly obtain additional
information about specific deployed resources.
2Use the GET: Child Resources HATEOAS link to retrieve a list of child nodes of a deployment.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https:// $host
/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq
%20%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27
3In addition, you can use the HATEOAS links to complete day 2 actions.
nYou can use a command like the following to get the template for the resource action request and
use it to power off a machine.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template
Programming Guide
VMware, Inc. 98
Then POST the unmodified template to the corresponding URI.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer
$token"https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "02bad06d-f92b-4cf8-b964-37bb5d57be38",
"description": null,
"data": {
"description": null,
"reasons": null
}
}
nYou can modify the HATEOAS links to complete more complex day 2 actions that require user
input, such as changing a lease. Use a command like the following to get the template for the
resource action request.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template
After you edit the template as desired, you can POST it to the corresponding URI.
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Sat, 01 August 2015 23:04:50 GMT
Content-Type: application/json;charset=UTF-8
Date: Sat, 01 August 2015 13:04:50 GMT
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "b5739e30-871d-48c7-9012-f2a7cf431dc1",
"description": null,
"data": {
"provider-ExpirationDate": "2015-07-29T16:44:13.846Z"
}
}
Syntax for Getting Deployment Details
You can use the REST API catalog service to identify provisioned items from a given request.
Programming Guide
VMware, Inc. 99
Accessing Links to Provisioned Items
You can access links to provisioned items from a given request by appending /resourceViews to the
request details URI. For instance, you can edit the example request URI from as follows:
http://$host/catalog-service/api/consumer/requests/$requestId/resourceViews
In addition to the general information about the provisioned deployment returned in the response, such as
its name, description and ID, the response contains additional HATEOAS links.
Table 3‑4. HATEOAS Link Deployment Details Functions
Link Description
GET: Catalog Item URI to get the catalog item details from which this catalog item was
provisioned. See Syntax for Viewing Details of a Machine Request.
GET: Request URI to get the request details that provisioned this item.
GET:Template
{com.vmware.csp.component.cafe.composition@resour
ce.action.deployment.$actionName
URI to get a template request for a specific action that you can perform
on this resource. Typically, on a deployment, the action will be Delete.
POST:
{com.vmware.csp.component.cafe.composition@resour
ce.action.deployment.$actionName
URI to which to post the request to perform an action, based on the
corresponding template.
GET: Child Resources If the deployment contains child resources, such as nodes specified in
the composite blueprint, this is the URI to get a list of the
resourceViews for the children of this deployment.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/catalog-service/api/consumer/resources/$resourceId
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
id UUID of a request.
page Specifies a page number.
limit Specifies the number of entries to display on a page.
$orderby Specifies how to order multiple comma-separated properties sorted in ascending or descending
order.
$top Specifies the number of returned entries from the top of the response (total number per page in
relation to skip).
$skip Specifies the number of entries to skip.
filter Contains a Boolean expression to determine if a particular entry is included in the response.
Programming Guide
VMware, Inc. 100
Output
The command output contains property names and values based on the command input parameters.
Table 3‑5. Output Parameters
Property Description
resourceId The unique identifier of the resource.
iconId Specifies an icon for this request based on the requested object type.
name The user friendly name of the resource.
description An extended user friendly description of the resource.
status The status of the resource. For example, On, Off, etc.
catalogItemId The identifier of the catalog item associated with this provisioned resource.
catalogItemLabel The label of the catalog item associated with this provisioned resource.
requestId The unique identifier of the request that created this provisioned resource.
businessGroupId The unique identifier of the business group that owns this resource.
tenantId The unique identifier of the tenant that owns this resource.
owners The owner of this resource.
resourceType The type identifier of this resource. For example, Virtual Machine.
parentResourceId The unique identifier of the parent resource. Used for child resources of a multi-machine
resource.
hasChildren Returns trun if this resource has child resources. Used if this is a multi-machine resource.
dateCreated The date and time at which the resource was created.
lastUpdated The date and time at which the resource was most recently modified.
lease The current lease of the resource.
costs An optional rate card of the costs and charges levied against the resource.
costToDate An optional rate card of the existing costs and charges levied against the resource.
totalCost An optional rate card of the costs and charges levied for the entire lease period.
data The extended, provider defined properties of the resource.
Example Curl Command
This example retrieves all children of the resource with an ID of 7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b.
$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer
$token" http:// $host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997b-
edd7c7983a5b/resourceViews
Programming Guide
VMware, Inc. 101
Example: JSON Output
{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Catalog Item",
"href": "https://$host/catalog-
service/api/consumer/entitledCatalogItemViews/7c8275d6-1bd6-452a-97c4-d6c053e4baa4"
},
{
"@type": "link",
"rel": "GET: Request",
"href": "https://$host/catalog-service/api/consumer/requests/7aaf9baf-
aa4e-47c4-997b-edd7c7983a5b"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$host/catalog-service/api/consumer/resources/c4d3db3e-e397-44ff-
a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.cafe.composition@resource.action.deployment.destroy.name}",
"href": "https://$host/catalog-service/api/consumer/resources/c4d3db3e-e397-44ff-
a1c9-0ecebdba12f4/actions/416e6bb1-3357-448b-8396-e268d5f7343b/requests"
},
{
"@type": "link",
"rel": "GET: Child Resources",
"href": "https://$host/catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource%20eq
%20%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27"
}
],
"resourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Linux-80813151",
"description": null,
"status": null,
"catalogItemId": "7c8275d6-1bd6-452a-97c4-d6c053e4baa4",
"catalogItemLabel": "Linux",
"requestId": "7aaf9baf-aa4e-47c4-997b-edd7c7983a5b",
"resourceType":
"{com.vmware.csp.component.cafe.composition@resource.type.deployment.name}",
"owners": [
Programming Guide
VMware, Inc. 102
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:51:36.368Z",
"lastUpdated": "2015-07-29T13:55:35.963Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": null,
"hasChildren": true,
"data": {}
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Syntax for Navigating to the Children of a Deployed Resource
Use the GET: Child Resources link to retrieve a list of the child nodes of a deployment, including virtual
machines, networks, and other objects you may have configured on the blueprint canvas.
Using the REST API to Get Additional Deployment Information
In addition to general information about the provisioned resource, the response contains additional
HATEOAS links that enable you to obtain additional details and information about each returned child
resource.
Table 3‑6. HATEOAS Link Functions as Defined by rel Field
Link Description
GET: Parent Resource URI to get the resourceView for the parent item. See Syntax for Getting
Deployment Details.
GET:Template
{com.vmware.csp.component.cafe.composition@resour
ce.action.deployment.$actionName
URI to get a template request for a specific action that you can perform
on this resource.
POST:
{com.vmware.csp.component.cafe.composition@resour
ce.action.deployment.$actionName
URI to which to post the request to perform an action, based on the
corresponding template.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 103
Parameter Description
URL https://$host/catalog-service/api/consumer/resources/$resourceId
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$resourceID Specifies a resource ID. See Syntax for Getting Deployment Details to view all of your requests
and search for a request ID.
managedOnly If true, the returned requests are from the user's managed subtenants.
page Specifies a page number.
limit Specifies the number of entries to display on a page.
$orderby Specifies how to order multiple comma-separated properties sorted in ascending or descending
order.
$top Specifies the number of returned entries from the top of the response (total number per page in
relation to skip).
$skip Specifies the number of entries to skip.
filter Contains a Boolean expression to determine if a particular entry is included in the response.
Output
The command output contains property names and values based on the command input parameters.
Table 3‑7. Output Parameters
Property Description
resourceId The unique identifier of the resource.
iconId Specifies an icon for this request based on the requested object type.
name The user friendly name of the resource.
description An extended user friendly description of the resource.
status The status of the resource. For example, On, Off, etc.
catalogItemId The identifier of the catalog item associated with this provisioned resource.
catalogItemLabel The label of the catalog item associated with this provisioned resource.
requestId The unique identifier of the request that created this provisioned resource.
businessGroupId The unique identifier of the business group that owns this resource.
tenantId The unique identifier of the tenant that owns this resource.
owners The owner of this resource.
resourceType The type identifier of this resource. For example, Virtual Machine.
parentResourceId The unique identifier of the parent resource. Used for child resources of a multi-machine
resource.
hasChildren Returns trun if this resource has child resources. Used if this is a multi-machine resource.
dateCreated The date and time at which the resource was created.
Programming Guide
VMware, Inc. 104
Table 3‑7. Output Parameters (Continued)
Property Description
lastUpdated The date and time at which the resource was most recently modified.
lease The current lease of the resource.
costs An optional rate card of the costs and charges levied against the resource.
costToDate An optional rate card of the existing costs and charges levied against the resource.
totalCost An optional rate card of the costs and charges levied for the entire lease period.
data The extended, provider defined properties of the resource.
Example Curl Command
This example retrieves all children of the resource with an ID of c4d3db3e-e397-44ff-
a1c9-0ecebdba12f4%27.
$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer
$token" https:// $host /catalog-service/api/consumer/resourceViews?
managedOnly=false&withExtendedData=true&withOperations=true&%24filter=parentResource
%20eq%20%27c4d3db3e-e397-44ff-a1c9-0ecebdba12f4%27
Example: JSON Output
The validation output displays the validation status of each content item within the package.
{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Parent Resource",
"href": "https://$host/catalog-service/api/consumer/resourceViews/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-
b5be-b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-
b5be-b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests"
},
Programming Guide
VMware, Inc. 105
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-
b5be-b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-
b5be-b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests"
}
],
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "DEMO-002",
"description": null,
"status": "On",
"catalogItemId": null,
"catalogItemLabel": null,
"requestId": null,
"resourceType":
"{com.vmware.csp.component.iaas.proxy.provider@resource.type.registration.name.Infrastructure.Virtual}"
,
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:54:58.804Z",
"lastUpdated": "2015-07-29T13:55:01.371Z",
"lease": {
"start": "2015-07-29T13:51:33.000Z"
},
"costs": {
"leaseRate": {
"type": "moneyTimeRate",
"cost": {
"type": "money",
"currencyCode": "USD",
"amount": 0
},
"basis": {
"type": "timeSpan",
"unit": "DAYS",
"amount": 1
}
}
},
"costToDate": {
"type": "money",
"currencyCode": "USD",
"amount": 0
Programming Guide
VMware, Inc. 106
},
"totalCost": null,
"parentResourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"hasChildren": false,
"data": {
"ChangeLease": true,
"ConnectViaRdp": true,
"ConnectViaVmrc": true,
"DISK_VOLUMES": [
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.DiskInputModel",
"typeFilter": null,
"data": {
"DISK_CAPACITY": 6,
"DISK_INPUT_ID": "DISK_INPUT_ID1"
}
},
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.DiskInputModel",
"typeFilter": null,
"data": {
"DISK_CAPACITY": 6,
"DISK_INPUT_ID": "DISK_INPUT_ID2"
}
}
],
"Destroy": true,
"EXTERNAL_REFERENCE_ID": "vm-38153",
"Expire": true,
"IS_COMPONENT_MACHINE": false,
"MachineBlueprintName": "system_blueprint_vsphere",
"MachineCPU": 1,
"MachineDailyCost": 0,
"MachineDestructionDate": null,
"MachineExpirationDate": null,
"MachineGroupName": "Demo Group",
"MachineGuestOperatingSystem": null,
"MachineInterfaceDisplayName": "vSphere (vCenter)",
"MachineInterfaceType": "vSphere",
"MachineMemory": 4096,
"MachineName": "DEMO-002",
"MachineReservationName": "vCenter55",
"MachineStorage": 12,
"MachineType": "Virtual",
"NETWORK_LIST": [
{
"componentTypeId": "com.vmware.csp.component.iaas.proxy.provider",
"componentId": null,
"classId": "dynamicops.api.model.NetworkViewModel",
"typeFilter": null,
"data": {
Programming Guide
VMware, Inc. 107
"NETWORK_MAC_ADDRESS": "00:50:56:ba:6b:85",
"NETWORK_NAME": "VM Network SQA"
}
}
],
"PowerOff": true,
"Reboot": true,
"Reconfigure": true,
"Reprovision": true,
"Reset": true,
"SNAPSHOT_LIST": [],
"Shutdown": true,
"Suspend": true,
"ip_address": "10.118.194.213",
"machineId": "f3579990-a3c4-4e17-9593-1f8893636876"
}
},
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Parent Resource",
"href": "https://$host/catalog-service/api/consumer/resourceViews/c4d3db3e-
e397-44ff-a1c9-0ecebdba12f4"
},
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.network.service@resource.action.destroy.name,
[{{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrastructure.N
etwork.Network.Existing}}]}",
"href": "https://$host/catalog-service/api/consumer/resources/f735b57a-
fe6f-4108-876f-1c1055ca2cec/actions/ec5c522d-7b5b-4d0b-b9f2-1aedf01a2f0c/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.network.service@resource.action.destroy.name,
[{{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrastructure.N
etwork.Network.Existing}}]}",
"href": "https://$host/catalog-service/api/consumer/resources/f735b57a-
fe6f-4108-876f-1c1055ca2cec/actions/ec5c522d-7b5b-4d0b-b9f2-1aedf01a2f0c/requests"
}
],
"resourceId": "f735b57a-fe6f-4108-876f-1c1055ca2cec",
"iconId": "cafe_default_icon_genericCatalogItem",
"name": "Existing Network",
"description": null,
"status": null,
"catalogItemId": null,
"catalogItemLabel": null,
"requestId": null,
"resourceType":
"{com.vmware.csp.component.iaas.proxy.provider@network.network.type.registration.name.Infrastructure.Ne
Programming Guide
VMware, Inc. 108
twork.Network.Existing}",
"owners": [
"Connie Summers"
],
"businessGroupId": "c0683388-6db2-4cb5-9033-b24d15ad3766",
"tenantId": "mycompany",
"dateCreated": "2015-07-29T13:55:14.095Z",
"lastUpdated": "2015-07-29T13:55:17.315Z",
"lease": null,
"costs": null,
"costToDate": null,
"totalCost": null,
"parentResourceId": "c4d3db3e-e397-44ff-a1c9-0ecebdba12f4",
"hasChildren": false,
"data": {
"Description": " ",
"Name": "Existing Network"
}
}
],
"metadata": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Perform a Day 2 Action: Power O
You can use the REST API catalog service to perform a power off action. For simple actions that require
no user input, the process is straightforward.
This command leverages the links for the power off action from the command used in the Syntax for
Navigating to the Children of a Deployed Resource example.
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$host/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.PowerOff}",
"href": "https://$host/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests"
}
Programming Guide
VMware, Inc. 109
Procedure
1Get the template for the resource action request.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template
This example command returns a response.
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Sat, 01 August 2015 23:04:50 GMT
Content-Type: application/json;charset=UTF-8
Date: Sat, 01 August 2015 13:04:50 GMT
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "02bad06d-f92b-4cf8-b964-37bb5d57be38",
"description": null,
"data": {
"description": null,
"reasons": null
}
}
2Use a POST command to send the template without modification to the corresponding URI.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer
$token"https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "02bad06d-f92b-4cf8-b964-37bb5d57be38",
"description": null,
"data": {
"description": null,
"reasons": null
}
}
This POST command returns a response indicating success or failure, such as HTTP/1.1 201 CREATED
for success.
Programming Guide
VMware, Inc. 110
Perform a Day 2 Action: Change Lease
You can use the REST API catalog service to change a lease. For actions that require user input, you
may need to edit the template prior to submitting the request.
This command leverages the links for the change lease action from the command used in the Syntax for
Navigating to the Children of a Deployed Resource example.
{
"@type": "link",
"rel": "GET Template:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$host/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template"
},
{
"@type": "link",
"rel": "POST:
{com.vmware.csp.component.iaas.proxy.provider@resource.action.name.machine.ChangeLease}",
"href": "https://$host/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests"
},
Procedure
1Get the template for the resource action request.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$host/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests/template
This example command returns a response.
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Sat, 01 August 2015 23:04:50 GMT
Content-Type: application/json;charset=UTF-8
Date: Sat, 01 August 2015 13:04:50 GMT
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "b5739e30-871d-48c7-9012-f2a7cf431dc1",
"description": null,
"data": {
"provider-ExpirationDate": "2015-07-29T16:44:13.846Z"
}
}
Programming Guide
VMware, Inc. 111
2Edit the template as desired. The template is populated with default values. In this example, the value
of provider-ExpirationDate is set to the time at which the template was requested in UTC. Edit this
value (for example, to change the expiration to a month from now).
3Use a POST command to send the template without modification to the corresponding URI.
$curl --insecure -s
-H" Content-Type: multipart/form-data" -H "Authorization: Bearer $token"
https://$hosts/catalog-service/api/consumer/resources/dd37b7a1-829c-4773-b5be-
b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests
Accept: application/json
Content-Type: application/json
Authorization: Bearer $token
{
"type": "com.vmware.vcac.catalog.domain.request.CatalogResourceRequest",
"resourceId": "dd37b7a1-829c-4773-b5be-b229453eca4a",
"actionId": "b5739e30-871d-48c7-9012-f2a7cf431dc1",
"description": null,
"data": {
"provider-ExpirationDate": "2015-08-29T16:44:13.846Z"
}
}
This POST command returns a response indicating success or failure, such as HTTP/1.1 201 CREATED
for success.
Working with Reservations
You can work with the REST API reservation service to perform a variety of functions, such as creating
and updating reservations.
The vRealize Automation REST API reservation service supports the following reservation types:
nvSphere (except for FlexClone in vSphere)
nvCloud Air
nvCloud Director
nAmazon
nHyper-V
nKVM
nXen
The following reservation types are not supported:
nOpenStack
nPhysical reservation
The reservation service is extensible, which allows you to add new reservation types.
Programming Guide
VMware, Inc. 112
A reservation must belong to a business group, also referred to as a subtenant. A business group can
have multiple reservations on the same resources or on different resources.
Note The Reservation API now returns compute resource endpoint names within parentheses. You may
need to update any client code which contains logic that uses compute resource names to account for
this change.
Create a Reservation
You can use the vRealize Automation REST API reservation service to create a reservation.
You can use the following procedure to create a vSphere, vCloud Air, or Amazon reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the schema class ID of the reservation type to create. See Display a List of Supported
Reservation Types.
nDisplay a list of the reservation types that are supported in the vRealize Automation server. See
Display a List of Supported Reservation Types.
nObtain the permissible value field information required to create a new reservation. After you retrieve
all permissible value field information, you have the input information required to create a reservation.
See Get Resources Schema for a vSphere Reservation.
nGet the required compute resource ID. See Get a Compute Resource for the Reservation.
nFinish creating a new reservation. Obtain the reservation ID from the output URL. See Syntax for
Creating a vSphere Reservation.
nGet the reservation ID if you do not already know it. See Display a List of Reservations.
Procedure
1Display a list of supported vRealize Automation reservation types by using the reservation service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/types
Programming Guide
VMware, Inc. 113
2Display a schema definition for a reservation.
a Display a schema definition for a vSphere reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default
b Display a schema definition for an Amazon reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default
c Display a schema definition for a vCloud Air reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloudAir/default
3Get the business group ID for a vRealize Automation reservation by using the reservation service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/qe/subtenants
Programming Guide
VMware, Inc. 114
4Obtain a compute resource for the vRealize Automation reservation by using the reservation service.
Use the following command to get a compute resource for a vSphere reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default/computeResource/values -d “{}”
Example: curl Command for an Amazon EC2 reservation
Use the following command to get a compute resource for an Amazon reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default/computeResource/values -d “{}”
Use the following command to get a compute resource for a vCloud Air reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloudAir/default/computeResource/values -d “{}”
Programming Guide
VMware, Inc. 115
5Use the vRealize Automation REST API reservation service to get a resources schema for any
supported reservation type, including a vSphere, Amazon, or vCloud Air reservation.
a Display information about available resources, such as storage and network information, for a
vSphere reservation by using the reservation service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default/resourcePool/values -d “{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": " cc254a84-95b8-434a-874d-bdfef8e8ad2c "
}
}]
}
}
b Display resource schema, such as storage and network information, for an Amazon reservation
by using the data and schema service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default/securityGroups/values -d “
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
}
Programming Guide
VMware, Inc. 116
}]
}
}
”
c Display information about available resources, such as storage and network information, for a
vCloud Air reservation by using the reservation service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloudAir/default/reservationStorages/values -
d “
Programming Guide
VMware, Inc. 117
6Use the vRealize Automation REST API to create any supported reservation type, including a
vSphere, Amazon, or vCloud Air reservation.
a Create a vSphere reservation by using the vRealize Automation reservation service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d
“
{
"name": "TestCreateReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["test1@mycompany.com",
"test2@mycompany.com"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
Programming Guide
VMware, Inc. 118
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "custom-Properties-key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "custom-Properties-key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15872
}
}]
}
}
Programming Guide
VMware, Inc. 119
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 32
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
Programming Guide
VMware, Inc. 120
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "storagePriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
}
}]
}
}"
Programming Guide
VMware, Inc. 121
}]
}
}
”
b Create a vCloud Air reservation by using the vRealize Automation reservation service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d “
{
"id": "bf922450-d495-460d-9dbf-1c09b0692db2",
"name": "TestvAppReservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloudAir",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [
],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
Programming Guide
VMware, Inc. 122
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}
}
]
}
}
]
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
Programming Guide
VMware, Inc. 123
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "storageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
Programming Guide
VMware, Inc. 124
]
}
}
]
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 4096
}
}
]
}
}
}
]
}
}
“
c Create an Amazon reservation by using the vRealize Automation reservation service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d “
{
"name": "TestEC2Reservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.Amazon",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": "34d2a612-718e-4814-96c5-225f7f5615a6",
"alertPolicy": {
"enabled": false,
Programming Guide
VMware, Inc. 125
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [
],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "securityGroups",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
}
]
}
},
{
"key": "loadBalancers",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
Programming Guide
VMware, Inc. 126
"type": "entityRef",
"componentId": null,
"classId": "ElasticLoadBalancer",
"id": "3",
"label": "test1"
}
]
}
},
{
"key": "locations",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AvailabilityZone",
"id": "10",
"label": "us-east-1a"
}
]
}
},
{
"key": "keyPairs",
"value": {
"type": "string",
"value": "Per Provisioning Group"
}
}
]
}
}”
7Use the reservation ID to verify that the reservation exists. Also use the ID to get information about
the reservation in preparation for updating or deleting it.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c
Display a List of Supported Reservation Types
You can use the vRealize Automation REST API reservation service to display a list of supported
reservation types.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
Programming Guide
VMware, Inc. 127
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
uDisplay a list of supported vRealize Automation reservation types by using the reservation service.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/types
JSON Output for a vSphere Reservation
{
"links": [],
"content": [{
"@type": "ReservationType",
"createdDate": "2015-10-13T04:44:32.008Z",
"lastUpdated": "2015-10-13T04:44:32.009Z",
"version": 1,
"id": "Infrastructure.Reservation.Virtual.vSphere",
"name": "vSphere",
"description": "vSphere Reservation",
"category": "Virtual",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Reservation.Virtual.vSphere.form.new"
},
"schemaClassId": "Infrastructure.Reservation.Virtual.vSphere",
"alertTypes": [{
"createdDate": "2015-10-13T04:44:32.008Z",
"lastUpdated": "2015-10-13T04:44:32.008Z",
"version": 0,
"id": "d248eeee-238c-4e87-9e95-f263b04d113f",
"name": "storage",
"description": null,
"referenceResourceId": "storage"
},//Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Programming Guide
VMware, Inc. 128
JSON Output for a vCloud Air Reservation
{
"links": [],
"content": [{
{
"@type": "ReservationType",
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 1,
"id": "Infrastructure.Reservation.Cloud.vCloudAir",
"name": "vCloud",
"description": "vCloud Air Reservation",
"category": "Cloud",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Reservation.Cloud.vCloudAir.form.new"
},
"schemaClassId": "Infrastructure.Reservation.Cloud.vCloudAir",
"alertTypes": [
{
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.010Z",
"version": 0,
"id": "cd707ad2-d504-43e2-8002-11ee670dcf41",
"name": "storage",
"description": null,
"referenceResourceId": "storage"
},
{
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.010Z",
"version": 0,
"id": "ef96fec4-a607-4944-a0af-fbe7df862ee2",
"name": "memory",
"description": null,
"referenceResourceId": "memory"
},
{
"createdDate": "2015-11-06T10:21:06.011Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 0,
"id": "043e0815-9f02-4876-b5ce-ddbedabb8ff6",
"name": "cpu",
"description": null,
"referenceResourceId": "cpu"
},
{
"createdDate": "2015-11-06T10:21:06.011Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 0,
"id": "77e90acd-93ab-4bbe-853a-b74923dae70a",
"name": "machine",
Programming Guide
VMware, Inc. 129
"description": null,
"referenceResourceId": "machine"
}
]
}, //Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
JSON Output for an Amazon Reservation
{
"links": [],
"content": [{
{
"@type": "ReservationType",
"createdDate": "2015-10-13T04:44:32.074Z",
"lastUpdated": "2015-10-13T04:44:32.075Z",
"version": 1,
"id": "Infrastructure.Cloud.Amazon",
"name": "Amazon",
"description": "Amazon Reservation",
"category": "Cloud",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Cloud.Amazon.form.new"
},
"schemaClassId": "Infrastructure.Cloud.Amazon",
"alertTypes": [{
"createdDate": "2015-10-13T04:44:32.075Z",
"lastUpdated": "2015-10-13T04:44:32.075Z",
"version": 0,
"id": "2ef8f47c-045c-4ee4-821d-7b1543ea5f11",
"name": "machine",
"description": null,
"referenceResourceId": "machine"
}]
},//Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
Programming Guide
VMware, Inc. 130
"number": 1,
"offset": 0
}
}
Syntax for Displaying a List of Supported Reservation Types
You can use the REST API reservation service to display a list of supported vRealize Automation
reservation types.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations/types
Method Get
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Species an array of link objects, each of which contains the following parts:
rel Specifies the name of the link.
nSelf refers to the object that was returned or requested.
nFirst, Previous, Next, and Last refer to corresponding pages of pageable lists.
nSpecifies the application or service that determines the other names.
href Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of the objects returned in a pageable list.
Each object contains the following information:
@type Contains the ReservationType string.
createdDate Specifies the create date.
lastUpdated Specifies the last update date.
version Displays the object version number.
Id Specifies the unique identifier of this resource.
name Specifies the reservation type name.
description Specifies the reservation type description.
category Specifies the reservation category of Virtual, Cloud or Physical.
serviceTypeId Specifies the vRealize Automation service ID.
tenantId This contains a null value.
Programming Guide
VMware, Inc. 131
Property Description
FormReference Specifies the user interface form reference. This field is valid for user interface elements only.
ntype -- user interface form type
nformId -- user interface form ID
SchemaClassId Specifies the schema class ID of the reservation type. Each supported reservation type contains
specific fields. The supported fields are defined in the schema. For details, see the reservation service
schema definitions in the vRealize Automation API Reference in the vRealize Automation
Documentation Center.
alertTypes Contains the alert type list defined in the reservation type:
ncreatedDate -- Alert type created date
nlastUpdated -- Alert type last updated date
nversion -- Alert type version
nid -- Unique identifier of alert type
nname -- Name of alert type
ndescription -- Long description of alert type
nreferenceResourceId -- Unique identifier of reference resource
Metadata Specifies the paging-related data:
nSize:
Specifies the maximum number of rows per page.
ntotalElements:
Specifies the number of rows returned.
ntotalPages:
Specifies the total number of pages of data available.
nNumber:
Specifies the current page number.
nOffset:
Specifies the number of rows skipped.
Example: curl Command
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/types
The following command contains the example bearer token from Syntax for Requesting an HTTP Bearer
Token.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer
MTQxMTY5OTkxODQyNTpkYmZmYjkzZTgzNjdmOGU0NThjZTp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLnZtd2
FyZS5jb206NDhmNGViNzQ3ZjYxY2YxMzdhNDAxOGY2MDAwOTFlZTJiZWI4MmJmZWU5ZTQ0MTI0YWI1M2U4NGNiOTk0
OTJjZjEwNjdhMzdmZTQ5YWMyMzA2NTA5M2UyNzlhMzI2ZGYxZDhlYTgxYmNkNjM5ZTNiNjIyYmEwYTRhOWJiMGE2ZTI="
https://myVRA.eng.mycompany.com/reservation-service/api/reservations/types
Programming Guide
VMware, Inc. 132
Example: JSON Output for a vSphere Reservation
In the following response, there are 8 reservation types. For the vSphere reservation, the reservation type
ID is Infrastructure.Reservation.Virtual.vSphere, and its schema class ID is
Infrastructure.Reservation.Virtual.vSphere.
{
"links": [],
"content": [{
"@type": "ReservationType",
"createdDate": "2015-10-13T04:44:32.008Z",
"lastUpdated": "2015-10-13T04:44:32.009Z",
"version": 1,
"id": "Infrastructure.Reservation.Virtual.vSphere",
"name": "vSphere",
"description": "vSphere Reservation",
"category": "Virtual",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Reservation.Virtual.vSphere.form.new"
},
"schemaClassId": "Infrastructure.Reservation.Virtual.vSphere",
"alertTypes": [{
"createdDate": "2015-10-13T04:44:32.008Z",
"lastUpdated": "2015-10-13T04:44:32.008Z",
"version": 0,
"id": "d248eeee-238c-4e87-9e95-f263b04d113f",
"name": "storage",
"description": null,
"referenceResourceId": "storage"
},//Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Example: JSON Output for a vCloud Air Reservation
In the following response, there are 8 reservation types. For the vCloud Air reservation, the reservation
type ID is Infrastructure.Reservation.Cloud.vCloudAir and its schema class ID is
Infrastructure.Reservation.Cloud.vCloudAir.
{
"links": [],
"content": [{
{
Programming Guide
VMware, Inc. 133
"@type": "ReservationType",
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 1,
"id": "Infrastructure.Reservation.Cloud.vCloudAir",
"name": "vCloud",
"description": "vCloud Reservation",
"category": "Cloud",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Reservation.Cloud.vCloudAir.form.new"
},
"schemaClassId": "Infrastructure.Reservation.Cloud.vCloudAir",
"alertTypes": [
{
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.010Z",
"version": 0,
"id": "cd707ad2-d504-43e2-8002-11ee670dcf41",
"name": "storage",
"description": null,
"referenceResourceId": "storage"
},
{
"createdDate": "2015-11-06T10:21:06.010Z",
"lastUpdated": "2015-11-06T10:21:06.010Z",
"version": 0,
"id": "ef96fec4-a607-4944-a0af-fbe7df862ee2",
"name": "memory",
"description": null,
"referenceResourceId": "memory"
},
{
"createdDate": "2015-11-06T10:21:06.011Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 0,
"id": "043e0815-9f02-4876-b5ce-ddbedabb8ff6",
"name": "cpu",
"description": null,
"referenceResourceId": "cpu"
},
{
"createdDate": "2015-11-06T10:21:06.011Z",
"lastUpdated": "2015-11-06T10:21:06.011Z",
"version": 0,
"id": "77e90acd-93ab-4bbe-853a-b74923dae70a",
"name": "machine",
"description": null,
"referenceResourceId": "machine"
}
]
}, //Omit 7 reservation types here
],
Programming Guide
VMware, Inc. 134
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Example: JSON Output for an Amazon Reservation
In the following response, there are 8 reservation types. For the Amazon reservation, the reservation type
ID is Infrastructure.Reservation.Cloud.Amazon and its schema class ID is
Infrastructure.Reservation.Cloud.Amazon.
{
"links": [],
"content": [{
{
"@type": "ReservationType",
"createdDate": "2015-10-13T04:44:32.074Z",
"lastUpdated": "2015-10-13T04:44:32.075Z",
"version": 1,
"id": "Infrastructure.Cloud.Amazon",
"name": "Amazon",
"description": "Amazon Reservation",
"category": "Cloud",
"serviceTypeId": "com.mycompany.csp.iaas.blueprint.service",
"tenantId": null,
"formReference": {
"type": "external",
"formId": "Infrastructure.Cloud.Amazon.form.new"
},
"schemaClassId": "Infrastructure.Cloud.Amazon",
"alertTypes": [{
"createdDate": "2015-10-13T04:44:32.075Z",
"lastUpdated": "2015-10-13T04:44:32.075Z",
"version": 0,
"id": "2ef8f47c-045c-4ee4-821d-7b1543ea5f11",
"name": "machine",
"description": null,
"referenceResourceId": "machine"
}]
},//Omit 7 reservation types here
],
"metadata": {
"size": 20,
"totalElements": 8,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Programming Guide
VMware, Inc. 135
Displaying a Schema Definition for a Reservation
You can use the vRealize Automation REST API to display a schema definition for any supported
reservation type, including a vSphere, Amazon EC2, or vCloud reservation.
Display a Schema Definition for a vSphere Reservation
You can use the REST API reservation service to display a schema definition for a specific
vRealize Automation reservation type, for example a vSphere reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the schema class ID of the reservation type to create. See Display a List of Supported
Reservation Types.
Procedure
uDisplay a schema definition for a specific vRealize Automation vSphere reservation type.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default
The schema definition in this example includes 9 extension fields that are supported for the vSphere
type reservation.
{
"fields": [{
"id": "reservationNetworks",
"label": "Network",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"label": "Network"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
Programming Guide
VMware, Inc. 136
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": true
},
{
"id": "reservationVCNSTransportZone",
"label": "Transport Zone",
"description": "Transport zone of the vCNS settings",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "NetworkScopes",
"typeFilter": null,
"label": "Transport Zone"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationVCNSSecurityGroups",
"label": "Security Groups",
"description": "Security groups of the vCNS settings",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "SecurityGroups",
"typeFilter": null,
"label": "Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
Programming Guide
VMware, Inc. 137
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": true
},
{
"id": "reservationMemory",
"label": "Memory",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"label": "Memory"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "InterfaceTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
Programming Guide
VMware, Inc. 138
"customAllowed": false,
"dependencies": []
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": false
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationStorages",
"label": "Storage",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"label": "Storage"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
Programming Guide
VMware, Inc. 139
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": true
},
{
"id": "resourcePool",
"label": "Resource Pool",
"description": "The resource pool for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ResourcePools",
"typeFilter": null,
"label": "Resource Pool"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationVCNSRoutedGateways",
"label": "Routed Gateways",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationVCNSRoutedGateway",
"typeFilter": null,
"label": "Routed Gateways"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
Programming Guide
VMware, Inc. 140
},
"isMultiValued": true
}]
}
Syntax for Displaying a Schema Definition for a vSphere Reservation
You can use the REST API reservation service to display a schema definition for a specific
vRealize Automation reservation type, for example a vSphere reservation.
Overview
Each reservation contains several fields. Some fields are common to all reservation types and some are
type-specific. The list of type-specific fields is defined in a schema. Call a data and schema service to get
schema definition information. The data and schema service combines fetch data and fetch schema
REST API calls.
Table 3‑8. Fields Common To All Reservation Types
Parameter Description Parameter Type
Id Specifies the reservation ID. GUID
name Specifies the reservation name. String
reservationTypeId Specifies the reservation type, for
example
Infrastructure.Reservation.Virtual.vSpher
e or
Infrastructure.Reservation.Virtual.Amazo
n.
String
tenantId Specifies the tenant ID that contains the
reservation.
String
subTenantId Specifies the subtenant ID that contains
the reservation.
GUID
enabled Specifies whether the reservation is
enabled.
Boolean
priority Specifies the priority of the reservation
during VM provisioning.
Integer
reservationPolicyId Specifies the reservation policy ID to
bind to this reservation.
GUID
alertPolicy Specifies the alert policy of the
reservation. The detail schema of this
field refers to the alert policy.
JSON
extensionData Contains type-specific fields. The detail
schema of this field is retrieved by the
data and schema service.
JSON
The following table describes the vSphere reservation types field IDs that appear in the output schema
definitions.
Programming Guide
VMware, Inc. 141
Table 3‑9. Extension Fields Supported in vSphere Reservations
Field ID Data Type Type Class
Permissible
Value Depends on Field
reservationNetworks Complex Type reservationNetwork Yes computeResource
reservationVCNSTransportZ
one
Entity Reference NetworkScopes Yes computeResource
reservationVCNSSecurityGr
oups
Entity Reference SecurityGroups Yes computeResource
reservationMemory Complex Type reservationMemory Yes computeResource
computeResource Entity Reference ComputeResource Yes NA
machineQuota Integer N/A No NA
reservationStorages Complex Type reservationStorage Yes computeResource
resourcePool Entity Reference ResourcePools Yes computeResource
reservationVCNSRoutedGat
eways
Complex Type reservationVCNSRoutedGat
eway
Yes computeResource
Note The information in the table is subject to change. Call the data and schema service to retrieve the
latest field information.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/data-service/schema/$schemaclassid/default
Method Get
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$schemaclassid Specifies the schema class of the reservation type.
The schema class ID for a vSphere reservation is
Infrastructure.Reservation.Virtual.vSphere.
Each supported reservation type contains specific fields. The supported fields are
defined in the schema. For details, see the reservation service schema definitions in
the vRealize Automation API Reference in the vRealize Automation documentation
center.
Output
The command output contains property names and values based on the command input parameters.
Each field contains an array of data rows. Each data row represents one of the fields defined in the
schema.
Programming Guide
VMware, Inc. 142
Property Description
Id Specifies the unique identifier of this resource.
label Specifies the field label.
dataType Specifies the dataType field value:
ntype: Specifies the field value type:
nSelf refers to the object that was returned or requested.
nFirst, Previous, Next, and Last refer to corresponding pages of a pageable list.
nSpecifies the application or service that determines the other names.
ncomponentTypeid:
Specifies the type ID of the component.
ncomponent:
Specifies the unique identifier of the component.
nclassId:
Specifies the schema class of the field
This property is valid for complex and ref field types only.
nlabel:
Specifies the label of the field data type.
displayAdvice Contains display advice for the field. This property is valid for a user interface element only.
permissibleValues Optional field. If this field is a permissible value list field, define the meta info for the permissible
value by using the following options:
ntype:
Specifies if the permissible value list is dynamic or static.
ncustomAllowed:
Specifies if a custom value is allowed during user input in this field.
ndependencies:
Specifies the list of fields that the current field depends on.
Programming Guide
VMware, Inc. 143
Property Description
state Provides a structure for defining the state of a content construct, for example {@link
LayoutSection}. The element state identifies the field paths in the client data context upon
which that element state depends. For example, the callback facet result indicates that facet
evaluation must be delegated to the server of the object. This evaluation may be dependent on
data collected in the client data context. For example, for a unique machine name, the
evaluation requires the proposed name entered by the user.
dependencies Contains the set of field paths on which the server-side evaluation of the facets depends:
nfacets:
Provides a higher level view of an {@link Constraint} collection and its current values.
All rendering code should use this class to provide a common place to get the current state
of the field.
If a field is considered in need of server-side evaluation, its facets setting is callback.
If a field is considered mandatory, its facets setting is mandatory.
nisMultiValued:
Specifies if the field is a multi-value field, such as a list field.
The state provides a higher level view of an {@link Constraint} collection and its current
values. Rendering code should use this class to provide a common place to get the current
state of the field.
Example: curl Command
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default
Example: JSON Output
The schema definition in this example includes 9 extension fields that are supported for the vSphere type
reservation.
{
"fields": [{
"id": "reservationNetworks",
"label": "Network",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"label": "Network"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
Programming Guide
VMware, Inc. 144
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": true
},
{
"id": "reservationVCNSTransportZone",
"label": "Transport Zone",
"description": "Transport zone of the vCNS settings",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "NetworkScopes",
"typeFilter": null,
"label": "Transport Zone"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationVCNSSecurityGroups",
"label": "Security Groups",
"description": "Security groups of the vCNS settings",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "SecurityGroups",
"typeFilter": null,
"label": "Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
Programming Guide
VMware, Inc. 145
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": true
},
{
"id": "reservationMemory",
"label": "Memory",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"label": "Memory"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "InterfaceTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
Programming Guide
VMware, Inc. 146
"type": "dynamic",
"customAllowed": false,
"dependencies": []
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": false
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationStorages",
"label": "Storage",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"label": "Storage"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": [{
"type": "mandatory",
Programming Guide
VMware, Inc. 147
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}]
},
"isMultiValued": true
},
{
"id": "resourcePool",
"label": "Resource Pool",
"description": "The resource pool for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ResourcePools",
"typeFilter": null,
"label": "Resource Pool"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
},
"isMultiValued": false
},
{
"id": "reservationVCNSRoutedGateways",
"label": "Routed Gateways",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationVCNSRoutedGateway",
"typeFilter": null,
"label": "Routed Gateways"
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": ["computeResource"]
},
"state": {
"dependencies": [],
"facets": []
Programming Guide
VMware, Inc. 148
},
"isMultiValued": true
}]
}
Display a Schema Definition for an Amazon Reservation
You can use the REST API reservation service to display a schema definition for a specific
vRealize Automation reservation type, for example an Amazon reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the schema class ID of the reservation type to create. See Display a List of Supported
Reservation Types.
Procedure
uDisplay a schema definition for an Amazon reservation type.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default
The schema definition in this example includes 9 extension fields.
{
"fields": [
{
"id": "securityGroups",
"label": "Security groups",
"description": "The security groups",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AmazonSecurityGroup",
"typeFilter": null,
"label": "Amazon Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
Programming Guide
VMware, Inc. 149
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
},
{
"type": "mandatory",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "locations",
"label": "Locations",
"description": "The locations",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AvailabilityZone",
"typeFilter": null,
"label": "Availability Zone"
},
Programming Guide
VMware, Inc. 150
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
},
{
"type": "mandatory",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "loadBalancers",
"label": "Load balancers",
"description": "The load balancers",
"dataType": {
"type": "ref",
Programming Guide
VMware, Inc. 151
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ElasticLoadBalancer",
"typeFilter": null,
"label": "Elastic Load Balancer"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"locations",
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "specificKeyPairs",
"label": "Specific key pair",
"description": "The specific key pair",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "KeyPair",
"typeFilter": null,
"label": "Key Pair"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
Programming Guide
VMware, Inc. 152
"customAllowed": false,
"dependencies": [
"computeResource",
"keyPairs"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "and",
"subClauses": [
{
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "keyPairs"
}
},
{
"type": "expression",
"operator": {
"type": "equals"
},
"leftOperand": {
"type": "constant",
"value": {
"type": "string",
"value": "Specific Key Pair"
}
},
"rightOperand": {
"type": "path",
"path": "keyPairs"
}
}
]
}
},
{
"type": "mandatory",
"value": {
"type": "and",
"subClauses": [
{
"type": "expression",
"operator": {
"type": "isDefined"
Programming Guide
VMware, Inc. 153
},
"leftOperand": {
"type": "path",
"path": "keyPairs"
}
},
{
"type": "expression",
"operator": {
"type": "equals"
},
"leftOperand": {
"type": "constant",
"value": {
"type": "string",
"value": "Specific Key Pair"
}
},
"rightOperand": {
"type": "path",
"path": "keyPairs"
}
}
]
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "ReservationTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
Programming Guide
VMware, Inc. 154
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "VPC",
"label": "VPC",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Cloud.Amazon.VPC",
"typeFilter": null,
"label": "VPC",
"schema": {
"fields": [
{
"id": "VPCSubnets",
"label": "Subnets",
"description": "The subnets.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Subnet",
"typeFilter": null,
"label": "Subnet"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "minCardinality",
"value": {
"type": "constant",
Programming Guide
VMware, Inc. 155
"value": {
"type": "integer",
"value": 1
}
}
},
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "VPCSecurityGroups",
"label": "Security groups",
"description": "The security groups",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AmazonSecurityGroup",
"typeFilter": null,
"label": "Amazon Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "minCardinality",
"value": {
"type": "constant",
"value": {
"type": "integer",
"value": 1
}
}
},
Programming Guide
VMware, Inc. 156
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "VPCName",
"label": "VPC Name",
"description": "The virtual private cloud.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "VirtualPrivateCloud",
"typeFilter": null,
"label": "Virtual Private Cloud"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "VPCLoadBalancers",
"label": "Load balancers",
"description": "The load balancers.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ElasticLoadBalancer",
Programming Guide
VMware, Inc. 157
"typeFilter": null,
"label": "Elastic Load Balancer"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"VPCSubnets"
]
},
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": true
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "or",
"subClauses": [
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "locations"
}
}
},
Programming Guide
VMware, Inc. 158
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "securityGroups"
}
}
}
]
}
},
{
"type": "mandatory",
"value": {
"type": "or",
"subClauses": [
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "locations"
}
}
},
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "securityGroups"
}
}
}
]
}
}
]
},
"isMultiValued": true
},
{
Programming Guide
VMware, Inc. 159
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
},
{
"id": "keyPairs",
"label": "Key pair",
"description": "The key pair",
"dataType": {
"type": "primitive",
"typeId": "STRING"
},
"displayAdvice": null,
"permissibleValues": {
"type": "static",
"customAllowed": false,
"values": [
{
"underlyingValue": {
"type": "string",
"value": "Not Specified"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Per Provisioning Group"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Per Machine"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
Programming Guide
VMware, Inc. 160
"value": "Specific Key Pair"
},
"label": null
}
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
}
]
Syntax for Displaying a Schema Definition for an Amazon Reservation
You can use the REST API reservation service to display a schema definition for a specific
vRealize Automation reservation type, for example an Amazon reservation.
Overview
Each reservation contains several fields. Some fields are common to all reservation types and some are
type-specific. The list of type-specific fields is defined in a schema. Call a data and schema service to get
schema definition information. The data and schema service combines fetch data and fetch schema
REST API calls.
Table 3‑10. Fields Common To All Reservation Types
Parameter Description Parameter Type
Id Specifies the reservation ID. GUID
name Specifies the reservation name. String
reservationTypeId Specifies the reservation type, for
example
Infrastructure.Reservation.Virtual.vSpher
e or
Infrastructure.Reservation.Virtual.Amazo
n.
String
tenantId Specifies the tenant ID that contains the
reservation.
String
Programming Guide
VMware, Inc. 161
Table 3‑10. Fields Common To All Reservation Types (Continued)
Parameter Description Parameter Type
subTenantId Specifies the subtenant ID that contains
the reservation.
GUID
enabled Specifies whether the reservation is
enabled.
Boolean
priority Specifies the priority of the reservation
during VM provisioning.
Integer
reservationPolicyId Specifies the reservation policy ID to
bind to this reservation.
GUID
alertPolicy Specifies the alert policy of the
reservation. The detail schema of this
field refers to the alert policy.
JSON
extensionData Contains type-specific fields. The detail
schema of this field is retrieved by the
data and schema service.
JSON
The following table describes the Amazon EC2 reservation types field IDs that appear in the output
schema definitions.
Table 3‑11. Extension Fields Supported in Amazon Reservations
Field ID Data Type Type Class
Permissible
Value Depends on Field
securityGroups Entity Reference AmazonSecurityGroup Yes computeResource
locations Entity Reference AvailabilityZone Yes computeResource
loadBalancers Entity Reference ElasticLoadBalancer Yes computeResource and
locations
specificKeyPairs Entity Reference KeyPair Yes computeResource
and keyPairs
computeResource Entity Reference ComputeResource Yes NA
VPC Complex Type Infrastructure.Reservation.Cl
oud.Amazon.VPC
Yes computeResource
machineQuota Integer NA No NA
keyPairs String ResourcePools Yes computeResource
Note The information in the table is subject to change. Call the data and schema service to retrieve the
latest field information.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 162
Parameter Description
URL https://$host/reservation-service/api/data-service/schema/$schemaclassid/default
Method Get
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$schemaclassid Specifies the schema class of the reservation type.
The schema class ID for an Amazon reservation is
Infrastructure.Reservation.Cloud.Amazon.
Each supported reservation type contains specific fields. The supported fields are
defined in the schema. For details, see the reservation service schema definitions in
the vRealize Automation API Reference in vRealize Automation documentation.
Output
The command output contains property names and values based on the command input parameters.
Each field contains an array of data rows. Each data row represents one of the fields defined in the
schema.
Property Description
Id Specifies the unique identifier of this resource.
label Specifies the field label.
dataType Specifies the dataType field value:
ntype: Specifies the field value type:
nSelf refers to the object that was returned or requested.
nFirst, Previous, Next, and Last refer to corresponding pages of a pageable list.
nSpecifies the application or service that determines the other names.
ncomponentTypeid:
Specifies the type ID of the component.
ncomponent:
Specifies the unique identifier of the component.
nclassId:
Specifies the schema class of the field
This property is valid for complex and ref field types only.
nlabel:
Specifies the label of the field data type.
displayAdvice Contains display advice for the field. This property is valid for a user interface element only.
Programming Guide
VMware, Inc. 163
Property Description
permissibleValues Optional field. If this field is a permissible value list field, define the meta info for the permissible
value by using the following options:
ntype:
Specifies if the permissible value list is dynamic or static.
ncustomAllowed:
Specifies if a custom value is allowed during user input in this field.
ndependencies:
Specifies the list of fields that the current field depends on.
state Provides a structure for defining the state of a content construct, for example {@link
LayoutSection}. The element state identifies the field paths in the client data context upon
which that element state depends. For example, the callback facet result indicates that facet
evaluation must be delegated to the server of the object. This evaluation may be dependent on
data collected in the client data context. For example, for a unique machine name, the
evaluation requires the proposed name entered by the user.
dependencies Contains the set of field paths on which the server-side evaluation of the facets depends:
nfacets:
Provides a higher level view of an {@link Constraint} collection and its current values.
All rendering code should use this class to provide a common place to get the current state
of the field.
If a field is considered in need of server-side evaluation, its facets setting is callback.
If a field is considered mandatory, its facets setting is mandatory.
nisMultiValued:
Specifies if the field is a multi-value field, such as a list field.
The state provides a higher level view of an {@link Constraint} collection and its current
values. Rendering code should use this class to provide a common place to get the current
state of the field.
Example: curl Command
The following example command retrieves schema definition information for an Amazon type reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default
Example: JSON Output
The following JSON output is returned based on the command input.
Programming Guide
VMware, Inc. 164
The schema definition in this example includes 8 extension fields that are supported for the Amazon EC2
type reservation.
{
"fields": [
{
"id": "securityGroups",
"label": "Security groups",
"description": "The security groups",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AmazonSecurityGroup",
"typeFilter": null,
"label": "Amazon Security Group"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
},
{
"type": "mandatory",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
Programming Guide
VMware, Inc. 165
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "locations",
"label": "Locations",
"description": "The locations",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AvailabilityZone",
"typeFilter": null,
"label": "Availability Zone"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
},
{
"type": "mandatory",
Programming Guide
VMware, Inc. 166
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "loadBalancers",
"label": "Load balancers",
"description": "The load balancers",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ElasticLoadBalancer",
"typeFilter": null,
"label": "Elastic Load Balancer"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"locations",
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
Programming Guide
VMware, Inc. 167
"path": "VPC"
}
}
}
}
]
},
"isMultiValued": true
},
{
"id": "specificKeyPairs",
"label": "Specific key pair",
"description": "The specific key pair",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "KeyPair",
"typeFilter": null,
"label": "Key Pair"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource",
"keyPairs"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "and",
"subClauses": [
{
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "keyPairs"
}
},
{
"type": "expression",
"operator": {
"type": "equals"
},
Programming Guide
VMware, Inc. 168
"leftOperand": {
"type": "constant",
"value": {
"type": "string",
"value": "Specific Key Pair"
}
},
"rightOperand": {
"type": "path",
"path": "keyPairs"
}
}
]
}
},
{
"type": "mandatory",
"value": {
"type": "and",
"subClauses": [
{
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "keyPairs"
}
},
{
"type": "expression",
"operator": {
"type": "equals"
},
"leftOperand": {
"type": "constant",
"value": {
"type": "string",
"value": "Specific Key Pair"
}
},
"rightOperand": {
"type": "path",
"path": "keyPairs"
}
}
]
}
}
]
},
"isMultiValued": false
},
{
Programming Guide
VMware, Inc. 169
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "ReservationTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "VPC",
"label": "VPC",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Cloud.Amazon.VPC",
"typeFilter": null,
"label": "VPC",
"schema": {
"fields": [
{
"id": "VPCSubnets",
"label": "Subnets",
"description": "The subnets.",
"dataType": {
Programming Guide
VMware, Inc. 170
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Subnet",
"typeFilter": null,
"label": "Subnet"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "minCardinality",
"value": {
"type": "constant",
"value": {
"type": "integer",
"value": 1
}
}
},
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "VPCSecurityGroups",
"label": "Security groups",
"description": "The security groups",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "AmazonSecurityGroup",
"typeFilter": null,
"label": "Amazon Security Group"
Programming Guide
VMware, Inc. 171
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "minCardinality",
"value": {
"type": "constant",
"value": {
"type": "integer",
"value": 1
}
}
},
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "VPCName",
"label": "VPC Name",
"description": "The virtual private cloud.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "VirtualPrivateCloud",
"typeFilter": null,
"label": "Virtual Private Cloud"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
Programming Guide
VMware, Inc. 172
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "VPCLoadBalancers",
"label": "Load balancers",
"description": "The load balancers.",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ElasticLoadBalancer",
"typeFilter": null,
"label": "Elastic Load Balancer"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"VPCSubnets"
]
},
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": true
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
Programming Guide
VMware, Inc. 173
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "visible",
"value": {
"type": "or",
"subClauses": [
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "locations"
}
}
},
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "securityGroups"
}
}
}
]
}
},
{
"type": "mandatory",
"value": {
"type": "or",
"subClauses": [
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "locations"
Programming Guide
VMware, Inc. 174
}
}
},
{
"type": "not",
"subClause": {
"type": "expression",
"operator": {
"type": "isDefined"
},
"leftOperand": {
"type": "path",
"path": "securityGroups"
}
}
}
]
}
}
]
},
"isMultiValued": true
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
},
{
"id": "keyPairs",
"label": "Key pair",
"description": "The key pair",
"dataType": {
"type": "primitive",
"typeId": "STRING"
},
"displayAdvice": null,
"permissibleValues": {
"type": "static",
"customAllowed": false,
"values": [
Programming Guide
VMware, Inc. 175
{
"underlyingValue": {
"type": "string",
"value": "Not Specified"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Per Provisioning Group"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Per Machine"
},
"label": null
},
{
"underlyingValue": {
"type": "string",
"value": "Specific Key Pair"
},
"label": null
}
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
}
]
Display a Schema Definition for a vCloud Air Reservation
You can use the vRealize Automation REST API reservation service to display a schema definition for a
specific reservation type, for example a vCloud Air reservation.
Programming Guide
VMware, Inc. 176
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the schema class ID of the reservation type to create. See Display a List of Supported
Reservation Types.
Procedure
uDisplay a schema definition for a specific vCloud Air reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloudAir/default
The schema definition in this example includes 6 extension fields that are supported for the
vCloud Air type reservation.
{
"fields": [
{
"id": "reservationNetworks",
"label": "Network",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"label": "Network",
"schema": {
"fields": [
{
"id": "networkPath",
"label": "Network Path",
"description": "Network path of the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Network",
"typeFilter": null,
"label": "Network"
},
"displayAdvice": null,
"state": {
"dependencies": [
Programming Guide
VMware, Inc. 177
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "networkProfile",
"label": "Network Profile",
"description": "The Network Profile",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "NetworkProfile",
"typeFilter": null,
"label": "Network Profile"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
Programming Guide
VMware, Inc. 178
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "allocationModel",
"label": "Allocation Model",
"description": "The allocation model for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "reservationMemory",
"label": "Memory",
"dataType": {
"type": "complex",
Programming Guide
VMware, Inc. 179
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"label": "Memory",
"schema": {
"fields": [
{
"id": "computeResourceMemoryTotalSizeMB",
"label": "Physical Memory (MB)",
"description": "The physical capacity (MB) for the memory",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "memoryReservedSizeMb",
"label": "Memory Reservation (MB)",
"description": "The reserved capacity (MB) for the memory",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
}
]
Programming Guide
VMware, Inc. 180
}
},
"displayAdvice": "DATA_TABLE",
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "ReservationTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "machineQuota",
"label": "Machine Quota",
Programming Guide
VMware, Inc. 181
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
},
{
"id": "reservationStorages",
"label": "Storage",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"label": "Storage",
"schema": {
"fields": [
{
"id": "storagePath",
"label": "Storage Path",
"description": "The storage path of the storage",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Storage",
"typeFilter": null,
"label": "Storage Path"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
Programming Guide
VMware, Inc. 182
}
]
},
"isMultiValued": false
},
{
"id": "storageReservationPriority",
"label": "Priority",
"description": "The reservation priority for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResourceStorageTotalSizeGB",
"label": "Total (GB)",
"description": "The total physical capacity (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
Programming Guide
VMware, Inc. 183
}
}
]
},
"isMultiValued": false
},
{
"id": "storageReservedSizeGB",
"label": "This reservation reserved (GB)",
"description": "The reserved capacity size (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
},
{
"id": "storageEnabled",
"label": "Enabled",
"description": "Whether the storage is enabled to reserve",
"dataType": {
"type": "primitive",
"typeId": "BOOLEAN"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResourceStorageFreeSizeGB",
Programming Guide
VMware, Inc. 184
"label": "Free (GB)",
"description": "The free capacity (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
Programming Guide
VMware, Inc. 185
"isMultiValued": true
}
]
}
Syntax for Displaying a Schema Definition for a vCloud Air Reservation
You can use the REST API reservation service to display a schema definition for a specific
vRealize Automation reservation type, for example a vCloud Air reservation.
Overview
SomevRealize Automation reservation fields are common to all reservation types and some are type-
specific. The list of type-specific fields is defined in a schema. You can call a data and schema service to
get schema definition information. The data and schema service combines fetch data and fetch schema
REST API calls.
Table 3‑12. Fields Common To All Reservation Types
Parameter Description Parameter Type
Id Specifies the reservation ID. GUID
name Specifies the reservation name. String
reservationTypeId Specifies the reservation type, for
example
Infrastructure.Reservation.Virtual.vSpher
e or
Infrastructure.Reservation.Virtual.Amazo
n.
String
tenantId Specifies the tenant ID that contains the
reservation.
String
subTenantId Specifies the subtenant ID that contains
the reservation.
GUID
enabled Specifies whether the reservation is
enabled.
Boolean
priority Specifies the priority of the reservation
during VM provisioning.
Integer
reservationPolicyId Specifies the reservation policy ID to
bind to this reservation.
GUID
alertPolicy Specifies the alert policy of the
reservation. The detail schema of this
field refers to the alert policy.
JSON
extensionData Contains type-specific fields. The detail
schema of this field is retrieved by the
data and schema service.
JSON
The following table describes the vCloud Air reservation types field IDs that appear in the output schema
definitions.
Programming Guide
VMware, Inc. 186
Table 3‑13. Extension Fields Supported in vCloud Reservations
Field ID Data Type Type Class
Permissible
Value Depends on Field
reservationNetworks Complex Type Infrastructure.Reservation.N
etwork
Yes computeResource
allocationModel Integer NA No NA
reservationMemory Complex Type Infrastructure.Reservation.M
emory
No NA
computeResource Entity Reference ComputeResource Yes NA
machineQuota Integer NA No NA
reservationStorages Complex Type Infrastructure.Reservation.St
orage
Yes computeResource
Note The information in the table is subject to change. Call the data and schema service to retrieve the
latest field information.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/data-service/schema/$schemaclassid/default
Method Get
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$schemaclassid Specifies the schema class of the reservation type.
The schema class ID for a vCloud Air reservation is
Infrastructure.Reservation.Cloud.vCloudAir.
Each supported reservation type contains specific fields. The supported fields are
defined in the schema. For details, see the reservation service schema definitions in
the vRealize Automation API Reference in vRealize Automation documentation.
Output
The command output contains property names and values based on the command input parameters.
Each field contains an array of data rows. Each data row represents one of the fields defined in the
schema.
Property Description
Id Specifies the unique identifier of this resource.
label Specifies the field label.
Programming Guide
VMware, Inc. 187
Property Description
dataType Specifies the dataType field value:
ntype: Specifies the field value type:
nSelf refers to the object that was returned or requested.
nFirst, Previous, Next, and Last refer to corresponding pages of a pageable list.
nSpecifies the application or service that determines the other names.
ncomponentTypeid:
Specifies the type ID of the component.
ncomponent:
Specifies the unique identifier of the component.
nclassId:
Specifies the schema class of the field
This property is valid for complex and ref field types only.
nlabel:
Specifies the label of the field data type.
displayAdvice Contains display advice for the field. This property is valid for a user interface element only.
permissibleValues Optional field. If this field is a permissible value list field, define the meta info for the permissible
value by using the following options:
ntype:
Specifies if the permissible value list is dynamic or static.
ncustomAllowed:
Specifies if a custom value is allowed during user input in this field.
ndependencies:
Specifies the list of fields that the current field depends on.
state Provides a structure for defining the state of a content construct, for example {@link
LayoutSection}. The element state identifies the field paths in the client data context upon
which that element state depends. For example, the callback facet result indicates that facet
evaluation must be delegated to the server of the object. This evaluation may be dependent on
data collected in the client data context. For example, for a unique machine name, the
evaluation requires the proposed name entered by the user.
dependencies Contains the set of field paths on which the server-side evaluation of the facets depends:
nfacets:
Provides a higher level view of an {@link Constraint} collection and its current values.
All rendering code should use this class to provide a common place to get the current state
of the field.
If a field is considered in need of server-side evaluation, its facets setting is callback.
If a field is considered mandatory, its facets setting is mandatory.
nisMultiValued:
Specifies if the field is a multi-value field, such as a list field.
The state provides a higher level view of an {@link Constraint} collection and its current
values. Rendering code should use this class to provide a common place to get the current
state of the field.
Programming Guide
VMware, Inc. 188
Example: curl Command
The following example command retrieves schema definition information for a vCloud Air reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloudAir/default
Example: JSON Output
The schema definition in this example includes 6 extension fields that are supported for the vCloud Air
type reservation.
{
"fields": [
{
"id": "reservationNetworks",
"label": "Network",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"label": "Network",
"schema": {
"fields": [
{
"id": "networkPath",
"label": "Network Path",
"description": "Network path of the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Network",
"typeFilter": null,
"label": "Network"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
Programming Guide
VMware, Inc. 189
}
}
]
},
"isMultiValued": false
},
{
"id": "networkProfile",
"label": "Network Profile",
"description": "The Network Profile",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "NetworkProfile",
"typeFilter": null,
"label": "Network Profile"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
Programming Guide
VMware, Inc. 190
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
},
{
"id": "allocationModel",
"label": "Allocation Model",
"description": "The allocation model for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "reservationMemory",
"label": "Memory",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"label": "Memory",
"schema": {
"fields": [
{
"id": "computeResourceMemoryTotalSizeMB",
"label": "Physical Memory (MB)",
"description": "The physical capacity (MB) for the memory",
Programming Guide
VMware, Inc. 191
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "memoryReservedSizeMb",
"label": "Memory Reservation (MB)",
"description": "The reserved capacity (MB) for the memory",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"state": {
"dependencies": [
],
"facets": [
]
},
Programming Guide
VMware, Inc. 192
"isMultiValued": false
},
{
"id": "computeResource",
"label": "Compute Resource",
"description": "The compute resource for the reservation",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "ComputeResource",
"typeFilter": "ReservationTypeId",
"label": "Compute Resource"
},
"displayAdvice": null,
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "machineQuota",
"label": "Machine Quota",
"description": "The machine quota for the reservation",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
Programming Guide
VMware, Inc. 193
]
},
"isMultiValued": false
},
{
"id": "reservationStorages",
"label": "Storage",
"dataType": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"label": "Storage",
"schema": {
"fields": [
{
"id": "storagePath",
"label": "Storage Path",
"description": "The storage path of the storage",
"dataType": {
"type": "ref",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Storage",
"typeFilter": null,
"label": "Storage Path"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "storageReservationPriority",
"label": "Priority",
"description": "The reservation priority for the storage",
"dataType": {
"type": "primitive",
Programming Guide
VMware, Inc. 194
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResourceStorageTotalSizeGB",
"label": "Total (GB)",
"description": "The total physical capacity (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "storageReservedSizeGB",
"label": "This reservation reserved (GB)",
"description": "The reserved capacity size (GB) for the storage",
"dataType": {
Programming Guide
VMware, Inc. 195
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
]
},
"isMultiValued": false
},
{
"id": "storageEnabled",
"label": "Enabled",
"description": "Whether the storage is enabled to reserve",
"dataType": {
"type": "primitive",
"typeId": "BOOLEAN"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
},
{
"id": "computeResourceStorageFreeSizeGB",
"label": "Free (GB)",
"description": "The free capacity (GB) for the storage",
"dataType": {
"type": "primitive",
"typeId": "INTEGER"
},
"displayAdvice": null,
"state": {
"dependencies": [
],
Programming Guide
VMware, Inc. 196
"facets": [
{
"type": "readOnly",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": false
}
]
}
},
"displayAdvice": "DATA_TABLE",
"permissibleValues": {
"type": "dynamic",
"customAllowed": false,
"dependencies": [
"computeResource"
]
},
"state": {
"dependencies": [
],
"facets": [
{
"type": "mandatory",
"value": {
"type": "constantClause",
"value": {
"type": "boolean",
"value": true
}
}
}
]
},
"isMultiValued": true
}
]
}
Get the Business Group ID for a Reservation
You can use REST API reservation service to get the business group ID for a vRealize Automation
reservation. The business group is also referred to as the subtenant in the API. When you create a
reservation, you must supply the business group ID, also referred to as the subtenant ID, in the REST
command line. Use this procedure to obtain the subTenantId value.
Programming Guide
VMware, Inc. 197
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
uGet business group ID for a vRealize Automation reservation with the reservation service.
insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/qe/subtenants
The following JSON output is returned based on the command input.
{
"links": [],
"content": [{
"@type": "Subtenant",
"id": "7d7dbb19-d2dc-44a3-9fc2-7435552c8a05",
"name": "Development",
"description": " Development ",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": "user1@mycompany.com"
}
}]
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "ade5b8d3-decf-405e-bd0b-297f976ef721",
"name": "Finance",
"description": "Finance",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": " user1@mycompany.com "
}
}]
},
"tenant": "qe"
Programming Guide
VMware, Inc. 198
},
{
"@type": "Subtenant",
"id": "ef58f604-528d-4441-a219-4725bead629b",
"name": "Test Sub Tenant",
"description": "VMPS",
"subtenantRoles": null,
"extensionData": {
"entries": []
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "92926c91-37de-4647-9aee-70b8d557ce8d",
"name": "Quality Engineering",
"description": "created by demo content",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": " user1@mycompany.com "
}
}]
},
"tenant": "qe"
}],
"metadata": {
"size": 20,
"totalElements": 4,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Syntax for Getting the Business Group ID for a Reservation
You can use the REST API identity service to get the business group ID for a vRealize Automation
reservation. The business group is also referred to as the subtenant in the API. When you create a
reservation, you must supply the business group ID, also referred to as the subtenant ID, in the REST
command line. Use this procedure to obtain the subTenantId value.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/identity/api/tenants/$tenantId/subtenants
Method Get
Programming Guide
VMware, Inc. 199
Parameter Description
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$tenantId Specifies the ID of the tenant.
Use to indicate the tenant ID to be queried. Each subtenant, or business group, must
belong to a tenant.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Species an array of link objects, each of which contains the following parts:
rel Specifies the name of the link.
nSelf refers to the object that was returned or requested.
nFirst, Previous, Next, and Last refer to corresponding pages of pageable lists.
nSpecifies the application or service determines the other names.
href Specifies the URL which produces the result.
Content Specifies an array of data rows, each of which represents one of the tenant objects returned in a
pageable list. Each tenant object contains the following information:
@type Constants the ReservationType string.
Id Specifies the unique reservation type identifier.
name Specifies the reservation type name.
description Specifies the reservation type description.
subtenantRoles Specifies the business group roles.
extensionData Specifies the extension data of the business group.
For example, the email address of the vRealize Automation business group manager is
user1@mycompany.com.
Metadata Specifies the paging-related data.
Size Specifies the maximum number of rows per page.
totalElements Specifies the number of rows returned.
totalPages Specifies the total number of pages of data available.
Number Specifies the current page number.
Offset Specifies the number of rows skipped.
Programming Guide
VMware, Inc. 200
Example: curl Command
The following example command retrieves all available business group, or subtenant, IDs.
insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/qe/subtenants
Example: JSON Output
In this example, all available business group, or subtenant, IDs are displayed. For related information
about the subtenant ID ef58f604-528d-4441-a219-4725bead629b, see Create a Reservation.
The following JSON output is returned based on the command input.
{
"links": [],
"content": [{
"@type": "Subtenant",
"id": "7d7dbb19-d2dc-44a3-9fc2-7435552c8a05",
"name": "Development",
"description": " Development ",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": "user1@mycompany.com"
}
}]
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "ade5b8d3-decf-405e-bd0b-297f976ef721",
"name": "Finance",
"description": "Finance",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": " user1@mycompany.com "
}
}]
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "ef58f604-528d-4441-a219-4725bead629b",
Programming Guide
VMware, Inc. 201
"name": "Test Sub Tenant",
"description": "VMPS",
"subtenantRoles": null,
"extensionData": {
"entries": []
},
"tenant": "qe"
},
{
"@type": "Subtenant",
"id": "92926c91-37de-4647-9aee-70b8d557ce8d",
"name": "Quality Engineering",
"description": "created by demo content",
"subtenantRoles": null,
"extensionData": {
"entries": [{
"key": "iaas-manager-emails",
"value": {
"type": "string",
"value": " user1@mycompany.com "
}
}]
},
"tenant": "qe"
}],
"metadata": {
"size": 20,
"totalElements": 4,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Get a Compute Resource for the Reservation
You can use the REST API reservation service to obtain compute resources for vRealize Automation
reservations.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
When you create a reservation, you must provide compute resource information that corresponds to the
computeResource parameter.
Programming Guide
VMware, Inc. 202
For example, for a vSphere, Amazon EC2, or vCloud reservation type schema definition, the following
permissibleValues field in the compute resource output indicates if the compute resource is available
and if it has any dependencies.
“permissibleValues": {"type": "dynamic","customAllowed": false, "dependencies": []}
Procedure
uUse the following command to get a compute resource.
Command to get a compute resource for vSphere reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default/computeResource/values -d “{}”
Command to get a compute resource for an Amazon EC2 reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default/computeResource/values -d “{}”
Example: curl Command for a vCloud reservation
Command to get a compute resource for a vCloud reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloud/default/computeResource/values -d “{}”
The following JSON output is returned based on the command input.
JSON Output for a vSphere Reservation
{
"values": [{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
},
"label": "VC51-Cluster"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
Programming Guide
VMware, Inc. 203
"id": "a4349488-9a56-4906-83a5-7d8b33c9d435",
"label": "NSX61-RC-ManagementCluster"
},
"label": "NSX61-RC-ManagementCluster"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "40b151ce-e409-4d2a-8dae-bb456139a660",
"label": "NSX61-RC-ComputeClusterB"
},
"label": "NSX61-RC-ComputeClusterB"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
},
"label": "NSX61-RC-ComputeClusterA"
}]
}
JSON output for an Amazon EC2 Reservation
{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "fdfa4b95-9476-4c18-81c5-1c0e5cb1131f",
"label": "EC2 841 Endpoint-us-west-1"
},
"label": "EC2 841 Endpoint-us-west-1"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "4e362590-b634-4269-9da4-548260148fa3",
"label": "EC2 841 Endpoint-us-west-2"
},
"label": "EC2 841 Endpoint-us-west-2"
},
{
"underlyingValue": {
"type": "entityRef",
Programming Guide
VMware, Inc. 204
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
},
"label": "EC2 841 Endpoint-us-east-1"
}
]
}
JSON output for a vCloud Reservation
{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
},
"label": "Engineering Allocation VDC"
}
]
}
Syntax for Getting a Compute Resource for a Reservation
You can use the REST API reservation service to obtain a compute resource for a vRealize Automation
reservation.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/data-
service/schema/$schemaclassid/default/$fieldid/values
Method Post
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Programming Guide
VMware, Inc. 205
Parameter Description
$schemaclassid Specifies the schema class ID.
For a vSphere reservation, specify
Infrastructure.Reservation.Virtual.vSphere as the
$schemaclassid value.
For an Amazon EC2 reservation, specify
Infrastructure.Reservation.Cloud.Amazon as the the
$schemaclassid value.
For a vCloud reservation, specify
Infrastructure.Reservation.Cloud.vCloud as the the
$schemaclassid value.
$fieldId From the schema definition, specifies the schemaclassid of the compute
resource field, which is is computeResource.
Enter computeResource for the $fieldId value.
HTTP body Because the dependencies entry for this permissible value field is an
empty string, provide an empty JSON string "{}" in the HTTP body.
Output
The command output contains property names and values based on the command input parameters.
The values section contains an array of data rows, each of which represents one of the compute
resource objects, returned in a pageable list. Each compute resource object contains the following
information.
Property Description
underlyingValue Contains a JSON string representing one permissible value of field.
ntype
Specifies one of the following permissible value data types.
nentityRef - Indicates that the object references a vRealize Automation entity.
ncomplexRef - Indicates that the object is a user-defined complex structure, for example struct
in C or Pojo in Java.
nprimary - Indicates the entity type such as string, integer, and so on.
ncomponentId
Specifies the component ID.
nclassId
Specifies the schema class ID of the current data type.
nId
Specifies the unique compute resource identifier.
label Contains the compute resource label. This value matches the underlyingValue.label.
Programming Guide
VMware, Inc. 206
Example: curl Command for a vSphere reservation
The following command retrieves a compute resource for a vSphere reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default/computeResource/values -d “{}”
Example: curl Command for an Amazon EC2 reservation
The following command retrieves a compute resource for an Amazon EC2 reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default/computeResource/values -d “{}”
Example: curl Command for a vCloud reservation
The following command retrieves a compute resource for a vCloud reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloud/default/computeResource/values -d “{}”
Example: JSON Output for a vSphere Reservation
In this example, there are 4 available compute resources that you can use to create a vSphere
reservation, for example cc254a84-95b8-434a-874d-bdfef8e8ad2c. Save a copy of the
underlyingValue section of the compute resource that you want to an XML editor and use the section
content later to create a reservation request.
The following JSON output is returned based on the command input.
{
"values": [{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
},
"label": "VC51-Cluster"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
Programming Guide
VMware, Inc. 207
"id": "a4349488-9a56-4906-83a5-7d8b33c9d435",
"label": "NSX61-RC-ManagementCluster"
},
"label": "NSX61-RC-ManagementCluster"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "40b151ce-e409-4d2a-8dae-bb456139a660",
"label": "NSX61-RC-ComputeClusterB"
},
"label": "NSX61-RC-ComputeClusterB"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
},
"label": "NSX61-RC-ComputeClusterA"
}]
}
Example: JSON Output for an Amazon Reservation
In this example, there are 3 available compute resources that you can use to create an Amazon EC2
reservation. Save a copy of the underlyingValue section of the compute resource that you want to an
XML editor and use the section content later to create a reservation request.
{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "fdfa4b95-9476-4c18-81c5-1c0e5cb1131f",
"label": "EC2 841 Endpoint-us-west-1"
},
"label": "EC2 841 Endpoint-us-west-1"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "4e362590-b634-4269-9da4-548260148fa3",
"label": "EC2 841 Endpoint-us-west-2"
},
"label": "EC2 841 Endpoint-us-west-2"
Programming Guide
VMware, Inc. 208
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
},
"label": "EC2 841 Endpoint-us-east-1"
}
]
}
Example: Output for a vCloud Reservation
In this example, there is 1 available compute resource that you can use to create a vCloud reservation.
Save a copy of the underlyingValue section of the compute resource that you want to an XML editor
and use the section content later to create a reservation request.
{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
},
"label": "Engineering Allocation VDC"
}
]
}
Getting a Resources Schema by Reservation Type
You can use the vRealize Automation REST API to get a resources schema for any supported reservation
type, including a vSphere, Amazon EC2, or vCloud reservation.
Get Resources Schema for a vSphere Reservation
You can use the REST API reservation service to display information about available resources, such as
storage and network information, for a vSphere reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nGet the required compute resource ID. See Get a Compute Resource for the Reservation.
Programming Guide
VMware, Inc. 209
Procedure
uDisplay information about available resources.
The following example command queries resource pool information for the compute resource
cc254a84-95b8-434a-874d-bdfef8e8ad2c.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default/resourcePool/values -d “{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": " cc254a84-95b8-434a-874d-bdfef8e8ad2c "
}
}]
}
}”
The following JSON output is returned based on the command input.
{
"values": [{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": " 4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": " CoreDev"
},
"label": " CoreDev"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "1186b5cc-cdef-4afb-8653-0ad41a36c194",
"label": "Documentation"
},
"label": "Documentation"
},
//Omit other resource pool list
]
}
Programming Guide
VMware, Inc. 210
Syntax for Getting Resources Schema for a vSphere Reservation
You can use the REST API reservation service to display information about available resources for a
vSphere reservation, such as storage and network information.
Overview
This example illustrates how to get a permissible value list for the resourcePool field. You can use the
generated output as input for creating or updating a vSphere reservation.
Table 3‑14. Extension Fields Supported in vSphere Reservations
Field ID Data Type Type Class
Permissible
Value Depends on Field
reservationNetworks Complex Type reservationNetwork Yes computeResource
reservationVCNSTransportZ
one
Entity Reference NetworkScopes Yes computeResource
reservationVCNSSecurityGr
oups
Entity Reference SecurityGroups Yes computeResource
reservationMemory Complex Type reservationMemory Yes computeResource
computeResource Entity Reference ComputeResource Yes NA
machineQuota Integer N/A No NA
reservationStorages Complex Type reservationStorage Yes computeResource
resourcePool Entity Reference ResourcePools Yes computeResource
reservationVCNSRoutedGat
eways
Complex Type reservationVCNSRoutedGat
eway
Yes computeResource
Note The information in the table is subject to change. Call the data and schema service to retrieve the
latest field information.
For related information, see Syntax for Displaying a Schema Definition for a vSphere Reservation.
Input
Use the supported input parameters to control the command output.
Input Description
URL https://$host/reservation-service/api/data-
service/schema/$schemaclassid/default/$fieldid/values
Method Post
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Programming Guide
VMware, Inc. 211
Input Description
$schemaclassid Specifies the schema class ID.
This example illustrates how to use the resourcePool field of a vSphere reservation type as
an example. The schema class ID of a vSphere reservation is
Infrastructure.Reservation.Virtual.vSphere. For this example, the input value for
$schemaclassid is Infrastructure.Reservation.Virtual.vSphere.
$fieldId Specifies the field ID of the resource.
For example, the field ID for the resource pool is resourcePool. For this example, the input
value for $fieldId is resourcePool.
HTTP body Contains information about dependencies.
Because the dependency of this permissible value field is computeResource, you must
provide a dependency definition in the HTTP body.
Output
The command output contains property names and values based on the command input parameters.
Property Description
values An array of data rows, each of which represents one of the resource pool objects returned in a
pageable list. Each resource pool object contains an underlyingValue and label entry.
underlyingValue JSON string representing one permissible value for a field:
ntype -- data type of entityRef, complexRef, or primary
ncomponent ID -- componentID
nclassId -- schema class ID of current data type
nid -- unique resource pool ID
nlabel -- resource pool label
label Specifies the resource pool label. This value matches the underlyingValue value.
Example: curl Command
The following example command returns vSphere reservation storage information.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Virtual.vSphere/default/resourcePool/values -d “{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": " cc254a84-95b8-434a-874d-bdfef8e8ad2c "
Programming Guide
VMware, Inc. 212
}
}]
}
}”
Example: JSON Output
The following JSON output is returned based on the command input.
In the following example output, the CoreDev resource pool is shown. Copy the output underlyingValue
section into an XML editor and use it as input to create or update a reservation. Note that other REST
calls can be used such as reservationNetworks and reservationStorages to get other resources for
the reservation.
{
"values": [{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": " 4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": " CoreDev"
},
"label": " CoreDev"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "1186b5cc-cdef-4afb-8653-0ad41a36c194",
"label": "Documentation"
},
"label": "Documentation"
},
//Omit other resource pool list
]
}
Get Resources Schema for an Amazon Reservation
You can use the vRealize Automation REST API reservation service to display resource schema, such as
storage and network information, for an Amazon reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nGet the required compute resource ID. See Get a Compute Resource for the Reservation.
Programming Guide
VMware, Inc. 213
Procedure
uUse the reservation service to display resource schema information for an Amazon reservation.
The following example command displays storage and network information for the compute resource
with an ID of 9d1a3b5a-7162-4a5a-85b7-ec1b2824f554.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default/securityGroups/values -d “
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
}
}]
}
}
”
The following JSON output is returned based on the command input.
{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "9",
"label": "test1"
},
"label": "test1"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
},
"label": "default"
}
]
}
Programming Guide
VMware, Inc. 214
Syntax for Getting Resources Schema for an Amazon Reservation
You can use the REST API reservation service data and schema service to display resource schema
information, such as storage and network data, for an Amazon reservation.
Overview
This example illustrates how to get a permissible value list for the securityGroups field. You can use the
generated output as input for creating or updating an Amazon reservation.
Table 3‑15. Extension Fields Supported in Amazon Reservations
Field ID Data Type Type Class
Permissible
Value Depends on Field
securityGroups Entity Reference AmazonSecurityGroup Yes computeResource
locations Entity Reference AvailabilityZone Yes computeResource
loadBalancers Entity Reference ElasticLoadBalancer Yes computeResource and
locations
specificKeyPairs Entity Reference KeyPair Yes computeResource
and keyPairs
computeResource Entity Reference ComputeResource Yes NA
VPC Complex Type Infrastructure.Reservation.Cl
oud.Amazon.VPC
Yes computeResource
machineQuota Integer NA No NA
keyPairs String ResourcePools Yes computeResource
Note The information in the table is subject to change. Call the data and schema service to retrieve the
latest field information.
For related information, see Syntax for Displaying a Schema Definition for an Amazon Reservation.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/data-
service/schema/$schemaclassid/default/$fieldid/values
Method Post
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Programming Guide
VMware, Inc. 215
Parameter Description
$schemaclassid Specifies the schema class ID.
This example illustrates how to use the securityGroups field of an
Amazon reservation type as an example. The schema class ID of an
Amazon reservation is Infrastructure.Reservation.Cloud.Amazon.
For this example, the input value for $schemaclassid is
Infrastructure.Reservation.Cloud.Amazon.
$fieldId Specifies the field ID of the resource.
For example, the field ID for the resource pool is securityGroups. For
this example, the input value for $fieldId is securityGroups.
HTTP body Contains information about dependencies.
Because the dependency of this permissible value field is
computeResource, you must provide a dependency definition in the HTTP
body.
Output
The command output contains property names and values based on the command input parameters.
Property Description
values An array of data rows, each of which represents one of the security group objects returned in a
pageable list. Each security group object contains an underlyingValue and label entry.
underlyingValue JSON string representing one permissible value for a field:
ntype -- data type of entityRef, complexRef, or primary
ncomponent ID -- componentID
nclassId -- schema class ID of current data type
nid -- unique security group ID
nlabel -- security group label
label Specifies the security groups label. This value matches the underlyingValue value.
Example: curl Command
The following example command displays resource schema security group information.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.Amazon/default/securityGroups/values -d “
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
}
Programming Guide
VMware, Inc. 216
}]
}
}
”
Example: JSON Output
The following JSON output is returned based on the command input.
Copy the output from an underlyingValue section into an XML editor and use it as input to create or
update a reservation.
{
"values": [
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "9",
"label": "test1"
},
"label": "test1"
},
{
"underlyingValue": {
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
},
"label": "default"
}
]
}
Get Resources Schema for a vCloud Air Reservation
You can use the REST API reservation service to display information about available resources, such as
storage and network information, for a vCloud Air reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nGet the required compute resource ID. See Get a Compute Resource for the Reservation.
Programming Guide
VMware, Inc. 217
Procedure
uUse the reservation service to display information about available resources.
The following example command displays storage and network information.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloudAir/default/reservationStorages/values -d “
The following JSON output is returned based on the command input.
{
"values": [
{
"underlyingValue": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "f4df029b-d475-4f85-ab42-05bddde3f667",
"label": "Low Performance Storage"
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 954
}
}
]
}
},
"label": "Low Performance Storage"
},
{
"underlyingValue": {
Programming Guide
VMware, Inc. 218
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
},
"label": "High Performance Storage"
}
]
}
Syntax for Getting Resources Schema for a vCloud Air Reservation
You can use the vRealize Automation REST API reservation service to display information about
available resources, such as storage and network information, for a vCloud Air reservation.
Overview
This example illustrates how to get a permissible value list for the reservationStorages field. Use the
generated output as input for creating or updating a vCloud Air reservation.
Programming Guide
VMware, Inc. 219
Table 3‑16. Extension Fields Supported in vCloud Reservations
Field ID Data Type Type Class
Permissible
Value Depends on Field
reservationNetworks Complex Type Infrastructure.Reservation.N
etwork
Yes computeResource
allocationModel Integer NA No NA
reservationMemory Complex Type Infrastructure.Reservation.M
emory
No NA
computeResource Entity Reference ComputeResource Yes NA
machineQuota Integer NA No NA
reservationStorages Complex Type Infrastructure.Reservation.St
orage
Yes computeResource
Note The information in the table is subject to change. Call the data and schema service to retrieve the
latest field information.
For related information, see Syntax for Displaying a Schema Definition for a vCloud Air Reservation.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/data-
service/schema/$schemaclassid/default/$fieldid/values
Method Post
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$schemaclassid Specifies the schema class ID.
This example illustrates how to use the reservationStorages field of a reservation
type as an example. The schema class ID of a vCloud Air reservation is
Infrastructure.Reservation.Cloud.vCloudAir. For this example, the input
value for $schemaclassid is Infrastructure.Reservation.Cloud.vCloudAir.
$fieldId Specifies the field ID of the resource.
For example, the field ID for the reservation storage is reservationStorages. For
this example, the input value for $fieldId is reservationStorages.
HTTP body Contains information about dependencies.
Because the dependency of the permissible value field reservationStorages is
computeResource, you must include a dependency definition in the HTTP body.
text Empty
Programming Guide
VMware, Inc. 220
Parameter Description
dependencyValues JSON string that defines the dependency values
entries key -- Specifies the field ID of dependent field. For this example, enter
computeResource.
value -- Specifies the value of the dependent field. For this example, copy and paste
the vCloud HTTP response obtained by using the Get Compute Resource task. See
Syntax for Getting Resources Schema for a vCloud Air Reservation.
Output
The command output contains property names and values based on the command input parameters.
Property Description
values An array of data rows, each of which represents one of the reservation storage objects returned
in a pageable list. Each reservation storage object contains an underlyingValue and label
entry.
underlyingValue JSON string representing one permissible value for a field:
ntype -- data type of entityRef, complexRef, or primary
ncomponent ID -- componentID
nclassId -- schema class ID of current data type
nid -- unique reservation storage ID
nlabel --reservation storage label
label Specifies the reservation storage label. This value matches the underlyingValue value.
Example: curl Command
The following example command returns vCloud Air reservation storage information.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/data-
service/schema/Infrastructure.Reservation.Cloud.vCloudAir/default/reservationStorages/values -d “
Example: JSON Output
The following JSON output is returned based on the command input.
Copy the output from an underlyingValue section into an XML editor and use it as input to create or
update a reservation.
{
"values": [
{
"underlyingValue": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
Programming Guide
VMware, Inc. 221
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "f4df029b-d475-4f85-ab42-05bddde3f667",
"label": "Low Performance Storage"
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 954
}
}
]
}
},
"label": "Low Performance Storage"
},
{
"underlyingValue": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
Programming Guide
VMware, Inc. 222
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
},
"label": "High Performance Storage"
}
]
}
Creating a Reservation By Type
You can use the vRealize Automation REST API to create any supported reservation type, including a
vSphere, Amazon EC2, or vCloud reservation.
Create a vSphere Reservation
You can use the vRealize Automation REST API reservation service to create a vSphere reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nDisplay a list of the reservation types that are supported in the vRealize Automation server. See
Display a List of Supported Reservation Types.
nObtain the permissible value field information required to create a new reservation. After you retrieve
all permissible value field information, you have the input information required to create a reservation.
See Get Resources Schema for a vSphere Reservation.
For the full list of tasks that you can perform before you create a reservation, see Create a Reservation.
Procedure
uCreate a vSphere reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d
“
{
Programming Guide
VMware, Inc. 223
"name": "TestCreateReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["test1@mycompany.com",
"test2@mycompany.com"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
Programming Guide
VMware, Inc. 224
}
}]
}
}]
}
},
{
"key": "custom-Properties-key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "custom-Properties-key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15872
}
}]
}
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
}
Programming Guide
VMware, Inc. 225
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 32
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
Programming Guide
VMware, Inc. 226
"value": 120
}
},
{
"key": "storagePriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
”
The command output is a URL that includes the new reservation ID, for example
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-
efd590fea15c.
Syntax for Creating a vSphere Reservation
You can use the REST API reservation service to create a vSphere reservation.
Input
Use the supported input parameters to control the command output.
Input Description
URL https://$host/reservation-service/api/reservations
Method Post
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
Programming Guide
VMware, Inc. 227
Input Description
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP body The HTTP body describes the reservation to create and calls the REST
API used to create the reservation.
Compose the HTTP body using one of the following methods:
nCopy the HTTP body from the JSON output from this example and
edit the applicable field values to compose the HTTP body input for
the command line.
nUse the API commands in Syntax for Verifying a Reservation and
Getting Reservation Details, remove the appropriate ID field from the
HTTP response, and edit the field values to compose the HTTP body
input for the command line.
Output
The output URL contains the new reservation ID.
Property Description
status When the reservation is successfully created, the HTTP response status is
201 created.
Header.Location The HTTP response contains a Location attribute that is formatted as
https://$host /reservation-service/api/reservations/$reservationId.
$reservationId Specifies the new reservation ID.
Example: curl Command
The following sample command creates a vSphere reservation. The HTTP body is included as part of the
command line input.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d
“
{
"name": "TestCreateReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["test1@mycompany.com",
"test2@mycompany.com"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
Programming Guide
VMware, Inc. 228
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "custom-Properties-key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "custom-Properties-key2",
"value": {
Programming Guide
VMware, Inc. 229
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15872
}
}]
}
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "cc254a84-95b8-434a-874d-bdfef8e8ad2c",
"label": "NSX61-RC-ComputeClusterA"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
Programming Guide
VMware, Inc. 230
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 32
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "storagePriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
Programming Guide
VMware, Inc. 231
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
”
Example: JSON Output
The following sample location URL is displayed, including the new vSphere reservation ID.
Location:
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c
Copy the output response into an XML editor for use in a future procedure, such as updating or deleting
the reservation.
Create a vCloud Air Reservation
You can use the vRealize Automation REST API reservation service to create a vCloud Air reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nDisplay a list of the reservation types that are supported in the vRealize Automation server. See
Display a List of Supported Reservation Types.
nObtain the permissible value field information required to create a new reservation. After you retrieve
all permissible value field information, you have the input information required to create a reservation.
See Get Resources Schema for a vSphere Reservation.
For the full list of tasks that you can perform before you create a reservation, see Create a Reservation.
Procedure
uCreate a vCloud Air reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d “
{
"name": "TestvAppReservation",
Programming Guide
VMware, Inc. 232
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloudAir",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [
],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
Programming Guide
VMware, Inc. 233
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}
}
]
}
}
]
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
Programming Guide
VMware, Inc. 234
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "storagePriority",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
}
]
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
Programming Guide
VMware, Inc. 235
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 4096
}
}
]
}
}
}
]
}
}
“
The output is a location URL, including the new vCloud Air reservation ID.
Location:
https://$host/reservation-service/api/reservations/3289b039-2a11-4ab4-a0bc-b583e4c6d085
Syntax for Creating a vCloud Air Reservation
You can use the REST API reservation service to create a vCloud Air reservation.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations
Method Post
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
Programming Guide
VMware, Inc. 236
Parameter Description
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP body The HTTP body describes the reservation to create and calls the REST
API used to create the reservation.
Compose the HTTP body using one of the following methods:
nCopy the HTTP body from the JSON output from this example and
edit the applicable field values to compose the HTTP body input for
the command line.
nUpdate the formatted reservation information to specify the new
information:
nremove the appropriate ID field from the HTTP response
nedit the field values to compose the HTTP body input for the
command line
For information, see Syntax for Verifying a Reservation and Getting
Reservation Details.
Output
The output URL contains the new reservation ID.
Property Description
status When the reservation is successfully created, the HTTP response status is
201 created.
Header.Location The HTTP response contains a Location attribute that is formatted as
https://$host /reservation-service/api/reservations/$reservationId.
$reservationId Specifies the new reservation ID.
Example: curl Command
The following sample command creates a vCloud Air reservation. The HTTP body is included as part of
the command line input.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d “
{
"name": "TestvAppReservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloudAir",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [
Programming Guide
VMware, Inc. 237
],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
Programming Guide
VMware, Inc. 238
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}
}
]
}
}
]
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
Programming Guide
VMware, Inc. 239
},
{
"key": "storageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
}
]
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},
{
"key": "memoryReservedSizeMb",
"value": {
Programming Guide
VMware, Inc. 240
"type": "integer",
"value": 4096
}
}
]
}
}
}
]
}
}
“
Example: JSON Output
The output response displays the location URL, including the new vCloud reservation ID.
Location: https://$host/reservation-service/api/reservations/3289b039-2a11-4ab4-a0bc-b583e4c6d085
Copy the output response into an XML editor for use in a future procedure, such as updating or deleting
the reservation.
Create an Amazon Reservation
You can use the vRealize Automation REST API reservation service to create an Amazon reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nDisplay a list of the reservation types that are supported in the vRealize Automation server. See
Display a List of Supported Reservation Types.
nObtain the permissible value field information required to create a new reservation. After you retrieve
all permissible value field information, you have the input information required to create a reservation.
See Get Resources Schema for a vSphere Reservation.
For the full list of tasks that you can perform before you create a reservation, see Create a Reservation.
Procedure
uCreate an Amazon reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d “
{
"name": "TestEC2Reservation",
Programming Guide
VMware, Inc. 241
"reservationTypeId": "Infrastructure.Reservation.Cloud.Amazon",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": "34d2a612-718e-4814-96c5-225f7f5615a6",
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [
],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "securityGroups",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
}
]
}
Programming Guide
VMware, Inc. 242
},
{
"key": "loadBalancers",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "ElasticLoadBalancer",
"id": "3",
"label": "test1"
}
]
}
},
{
"key": "locations",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AvailabilityZone",
"id": "10",
"label": "us-east-1a"
}
]
}
},
{
"key": "keyPairs",
"value": {
"type": "string",
"value": "Per Provisioning Group"
}
}
]
}
}”
The output is a sample location URL, including the new Amazon reservation ID.
Location: https://$host/reservation-service/api/reservations/3289b039-2a11-4ab4-a0bc-b583e4c6d085
Syntax for Creating an Amazon Reservation
You can use the REST API reservation service to create an Amazon reservation.
Programming Guide
VMware, Inc. 243
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations
Method Post
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP body The HTTP body describes the reservation to create and calls the REST
API used to create the reservation.
Compose the HTTP body using one of the following methods:
nCopy the HTTP body from the JSON output from this example and
edit the applicable field values to compose the HTTP body input for
the command line.
nUse the API commands in Syntax for Verifying a Reservation and
Getting Reservation Details, remove the appropriate ID field from the
HTTP response, and edit the field values to compose the HTTP body
input for the command line.
Output
The output URL contains the new reservation ID.
Property Description
status When the reservation is successfully created, the HTTP response status is
201 created.
Header.Location The HTTP response contains a Location attribute that is formatted as
https://$host /reservation-service/api/reservations/$reservationId.
$reservationId Specifies the new reservation ID.
Example: curl Command
The following example command creates an Amazon reservation. The HTTP body is included as part of
the command line input.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d “
{
"name": "TestEC2Reservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.Amazon",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": "34d2a612-718e-4814-96c5-225f7f5615a6",
"alertPolicy": {
Programming Guide
VMware, Inc. 244
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [
],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554",
"label": "EC2 841 Endpoint-us-east-1"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "securityGroups",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AmazonSecurityGroup",
"id": "10",
"label": "default"
}
]
}
},
{
"key": "loadBalancers",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
Programming Guide
VMware, Inc. 245
{
"type": "entityRef",
"componentId": null,
"classId": "ElasticLoadBalancer",
"id": "3",
"label": "test1"
}
]
}
},
{
"key": "locations",
"value": {
"type": "multiple",
"elementTypeId": "ENTITY_REFERENCE",
"items": [
{
"type": "entityRef",
"componentId": null,
"classId": "AvailabilityZone",
"id": "10",
"label": "us-east-1a"
}
]
}
},
{
"key": "keyPairs",
"value": {
"type": "string",
"value": "Per Provisioning Group"
}
}
]
}
}”
Example: JSON Output
The following sample location URL is displayed, including the new Amazon reservation ID.
Location: https://$host/reservation-service/api/reservations/3289b039-2a11-4ab4-a0bc-b583e4c6d085
Copy the output response into an XML editor for use in a future procedure, such as updating or deleting
the reservation.
Verify a Reservation and Get Reservation Details
After you create a vRealize Automation reservation, you can use the REST API reservation service along
with reservation ID to verify that the reservation exists. You can also use the ID to get information about
the reservation in preparation for updating or deleting it.
Programming Guide
VMware, Inc. 246
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nFinish creating a new reservation. Obtain the reservation ID from the output URL. See Syntax for
Creating a vSphere Reservation.
nGet the reservation ID if you do not already know it. See Display a List of Reservations.
Procedure
uUse the reservation service to verify that a reservation exists by using the verification ID.
The following example command verifies the existence of a reservation with an ID of
94d74105-831a-4598-8f42-efd590fea15c and returns reservation details.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c
The following JSON output is returned based on the command input.
{
"id": "94d74105-831a-4598-8f42-efd590fea15c ",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["user1@mycompany.com",
"user2@mycompany.com"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
Programming Guide
VMware, Inc. 247
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "ETEDoNotDelete2014-10-13 13:10:56"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
Programming Guide
VMware, Inc. 248
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
Programming Guide
VMware, Inc. 249
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
Programming Guide
VMware, Inc. 250
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
Example Output for a vCloud Reservation
{
"id": "bf922450-d495-460d-9dbf-1c09b0692db2",
"name": "TestvAppReservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloud",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [
],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
Programming Guide
VMware, Inc. 251
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
Programming Guide
VMware, Inc. 252
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}
}
]
}
}
]
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "storageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
Programming Guide
VMware, Inc. 253
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
"value": 691
}
}
]
}
}
]
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 4096
}
}
]
}
}
Programming Guide
VMware, Inc. 254
}
]
}
}
Syntax for Verifying a Reservation and Getting Reservation Details
After you create a vRealize Automation reservation, you can use the REST API reservation service and
the reservation ID to verify that the reservation exists. You can also use the ID to get information about
the reservation in preparation for updating or deleting it.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations/$reservationId
This is the URL that is generated when you create a reservation using the
REST API. See Syntax for Creating a vSphere Reservation.
Method Get
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$reservationId Specifies the unique identifier of the reservation to verify. Obtain the value
from the output generated when you created the reservation. See Create a
Reservation.
Output
The command output contains property names and values based on the command input parameters.
Property Description
status The HTTP response status is 201 created to indicate that the reservation exists.
Header.Location The HTTP response should contain a location attribute, format as https://$host /reservation-
service/api/reservations/$reservationId.
$reservationId The HTTP response should contain a location attribute, formatted as https://$host /reservation-
service/api/reservations/$reservationId.
Example: curl Command
In the following example, the reservation ID of 94d74105-831a-4598-8f42-efd590fea15c is the value you
obtained when you created the reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c
Programming Guide
VMware, Inc. 255
Example: JSON Output for a vSphere Reservation
The following JSON output is returned based on the command input.
Copy the output response into an XML editor for future step usage.
{
"id": "94d74105-831a-4598-8f42-efd590fea15c ",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["user1@mycompany.com",
"user2@mycompany.com"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
Programming Guide
VMware, Inc. 256
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "ETEDoNotDelete2014-10-13 13:10:56"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
Programming Guide
VMware, Inc. 257
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
Programming Guide
VMware, Inc. 258
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
Programming Guide
VMware, Inc. 259
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
Example: Example Output for a vCloud Reservation
{
"id": "bf922450-d495-460d-9dbf-1c09b0692db2",
"name": "TestvAppReservation",
"reservationTypeId": "Infrastructure.Reservation.Cloud.vCloud",
"tenantId": "qe",
"subTenantId": "a5d056be-3aa2-4fdd-ba1e-a3805f26f0e0",
"enabled": true,
"priority": 1,
"reservationPolicyId": null,
"alertPolicy": {
"enabled": false,
"frequencyReminder": 0,
"emailBgMgr": true,
"recipients": [
],
"alerts": [
{
"alertPercentLevel": 80,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 80,
"referenceResourceId": "machine",
"id": "machine"
}
]
},
"extensionData": {
"entries": [
Programming Guide
VMware, Inc. 260
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "c527a0f5-b1ae-4b61-8145-ad9d5c434dc7",
"label": "Engineering Allocation VDC"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "allocationModel",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Network",
"typeFilter": null,
"values": {
"entries": [
{
"key": "networkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "42c5063c-5422-448f-aac7-22ebe941ac8e",
"label": "VM Network SQA"
}
}
]
}
}
]
}
},
{
Programming Guide
VMware, Inc. 261
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [
{
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Storage",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceStorageTotalSizeGB",
"value": {
"type": "integer",
"value": 1000
}
},
{
"key": "storagePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Storage",
"id": "e655aa78-e5fb-4722-9e8a-0cd4139248cf",
"label": "High Performance Storage"
}
},
{
"key": "storageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "storageReservedSizeGB",
"value": {
"type": "integer",
"value": 100
}
},
{
"key": "storageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "computeResourceStorageFreeSizeGB",
"value": {
"type": "integer",
Programming Guide
VMware, Inc. 262
"value": 691
}
}
]
}
}
]
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.vmware.csp.iaas.blueprint.service",
"componentId": null,
"classId": "Infrastructure.Reservation.Memory",
"typeFilter": null,
"values": {
"entries": [
{
"key": "computeResourceMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 13312
}
},
{
"key": "memoryReservedSizeMb",
"value": {
"type": "integer",
"value": 4096
}
}
]
}
}
}
]
}
}
Display a List of Reservations
You can use the vRealize Automation REST API reservation service to obtain and display a list of existing
reservations to obtain the required reservation ID value in preparation for updating or deleting a
reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
Programming Guide
VMware, Inc. 263
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
uDisplay a list of existing vRealize Automation reservations.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations
The following sample output lists two vSphere reservations, named MyTestReservation1 and
MyTestReservation2 .
{
"links": [],
"content": [{
"id": "94d74105-831a-4598-8f42-efd590fea15c ",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["user1@mycompany.com",
"user2@mycompany.com"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
Programming Guide
VMware, Inc. 264
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "ETEDoNotDelete2014-10-13 13:10:56"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
Programming Guide
VMware, Inc. 265
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
Programming Guide
VMware, Inc. 266
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
Programming Guide
VMware, Inc. 267
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}],
"metadata": {
"size": 0,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Syntax for Displaying a List of Reservations
You can use the REST API reservation service to display a list of existing vRealize Automation
reservations. You can use this list to obtain the required reservation ID value in preparation for updating
or deleting a reservation.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations
Method Get
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 268
Property Description
Links Species an array of link objects, each of which contains the following parts:
rel Specifies the name of the link.
nSelf refers to the object which was returned or requested.
nFirst, Previous, Next, and Last refer to corresponding pages of pageable lists.
nSpecifies the application or service that determines the other names.
href Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of the tenant objects returned in a
pageable list.
Metadata Specifies the paging-related data.
Size Specifies the maximum number of rows per page.
totalElements Specifies the number of rows returned.
totalPages Specifies the total number of pages of data available.
Number Specifies the current page number.
Offset Specifies the number of rows skipped.
Example: curl Command
The following example command displays a list of reservations.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations
Example: JSON Output
The following sample output lists two vSphere reservations, named MyTestReservation1 and
MyTestReservation2. For related information, see Syntax for Verifying a Reservation and Getting
Reservation Details.
You can use the id value for each reservation to update or delete them. For related information, see
Syntax for Updating a Reservation or Syntax for Deleting a Reservation.
{
"links": [],
"content": [{
"id": "94d74105-831a-4598-8f42-efd590fea15c ",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
Programming Guide
VMware, Inc. 269
"emailBgMgr": false,
"recipients": ["user1@mycompany.com",
"user2@mycompany.com"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
Programming Guide
VMware, Inc. 270
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "ETEDoNotDelete2014-10-13 13:10:56"
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
Programming Guide
VMware, Inc. 271
}
}]
}
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
Programming Guide
VMware, Inc. 272
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}],
"metadata": {
"size": 0,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Programming Guide
VMware, Inc. 273
Update a Reservation
You can use the REST API reservation service to update an existing vRealize Automation reservation.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the reservation ID of the reservation that you want to update. This information is required API
command input. See Syntax for Displaying a List of Reservations.
nObtain the reservation field information for the reservation that you want to update. For example, if
you want to change from one compute resource to another, you must obtain the new compute
resource ID and its associated JSON section output. This information is required API command input.
See Syntax for Getting a Compute Resource for a Reservation.
Procedure
uUse the reservation service to update an existing reservation.
The following example command updates a reservation with an ID of 94d74105-831a-4598-8f42-
efd590fea15c.
curl –X PUT--insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c –d
“
{
"id": "94d74105-831a-4598-8f42-efd590fea15c",
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["user1@mycompany.com",
"user2@mycompany.com"],
"alerts": [{
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
Programming Guide
VMware, Inc. 274
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "TestNetworkProfile"
}
},
{
"key": "reservationNetworkPath",
Programming Guide
VMware, Inc. 275
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
}
},
{
"key": "key1",
Programming Guide
VMware, Inc. 276
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
"type": "boolean",
"value": true
}
},
Programming Guide
VMware, Inc. 277
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
”
The following output is returned based on the command input.
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Syntax for Updating a Reservation
You can use the vRealize Automation REST API reservation service to update an existing reservation.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 278
Parameter Description
URL https://$host/reservation-service/api/reservations/$reservationId
Method Put
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$reservationId Specifies the unique identifier of the reservation to update. For information
about how to obtain the reservation ID, see Syntax for Displaying a List of
Reservations.
HTTP body Contains the JSON information for the reservation, including the updated
data for the parameters that you want to update.
Most of this JSON string information is obtained by displaying the existing
details of the $reservationId. See Syntax for Verifying a Reservation and
Getting Reservation Details. The rest of the JSON string information is
obtained by using an API command to get the ID of the parameter you
want to update.
For example, to update the reservation to use a different compute
resource than the one currently specified, replace the computeResource
value of the exiting reservation with a new computeResource value in the
command's HTTP input.
Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Example: curl Command
The following example command updates the reservation with an ID of 94d74105-831a-4598-8f42-
efd590fea15c to use compute resource ID 047e00f5-5424-4ed2-a751-4a334aeaff54.
curl –X PUT--insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c –d
“
{
"name": "TestReservation",
"reservationTypeId": "Infrastructure.Reservation.Virtual.vSphere",
"tenantId": "qe",
"subTenantId": "ef58f604-528d-4441-a219-4725bead629b",
"enabled": true,
"priority": 3,
"reservationPolicyId": "b71c3a5f-087a-4d9e-9a56-fab785a3d128",
"alertPolicy": {
"enabled": true,
"frequencyReminder": 20,
"emailBgMgr": false,
"recipients": ["user1@mycompany.com",
"user2@mycompany.com"],
"alerts": [{
Programming Guide
VMware, Inc. 279
"alertPercentLevel": 10,
"referenceResourceId": "storage",
"id": "storage"
},
{
"alertPercentLevel": 20,
"referenceResourceId": "memory",
"id": "memory"
},
{
"alertPercentLevel": 30,
"referenceResourceId": "cpu",
"id": "cpu"
},
{
"alertPercentLevel": 40,
"referenceResourceId": "machine",
"id": "machine"
}]
},
"extensionData": {
"entries": [{
"key": "key4",
"value": {
"type": "string",
"value": "custom-property-value4"
}
},
{
"key": "key3",
"value": {
"type": "string",
"value": "custom-property-value3"
}
},
{
"key": "reservationNetworks",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationNetwork",
"typeFilter": null,
"values": {
"entries": [{
"key": "reservationNetworkProfile",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "NetworkProfile",
"id": "ed5d1503-08ac-42ca-804d-9167834a63a5",
"label": "TestNetworkProfile"
Programming Guide
VMware, Inc. 280
}
},
{
"key": "reservationNetworkPath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "Network",
"id": "44cb65d5-b321-43dd-a2ab-8ecf387bff8f",
"label": "VM Network SQA"
}
}]
}
}]
}
},
{
"key": "key0",
"value": {
"type": "string",
"value": "custom-property-value0"
}
},
{
"key": "key2",
"value": {
"type": "string",
"value": "custom-property-value2"
}
},
{
"key": "reservationMemory",
"value": {
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationMemory",
"typeFilter": null,
"values": {
"entries": [{
"key": "hostMemoryTotalSizeMB",
"value": {
"type": "integer",
"value": 57187
}
},
{
"key": "reservationMemoryReservedSizeMb",
"value": {
"type": "integer",
"value": 15888
}
}]
}
Programming Guide
VMware, Inc. 281
}
},
{
"key": "key1",
"value": {
"type": "string",
"value": "custom-property-value-Updated"
}
},
{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "047e00f5-5424-4ed2-a751-4a334aeaff54",
"label": "VC51-Cluster"
}
},
{
"key": "machineQuota",
"value": {
"type": "integer",
"value": 2
}
},
{
"key": "reservationStorages",
"value": {
"type": "multiple",
"elementTypeId": "COMPLEX",
"items": [{
"type": "complex",
"componentTypeId": "com.mycompany.csp.iaas.blueprint.service",
"componentId": null,
"classId": "reservationStorage",
"typeFilter": null,
"values": {
"entries": [{
"key": "storageTotalSizeGB",
"value": {
"type": "integer",
"value": 394
}
},
{
"key": "reservationStorageReservedSizeGB",
"value": {
"type": "integer",
"value": 31
}
},
{
"key": "reservationStorageEnabled",
"value": {
Programming Guide
VMware, Inc. 282
"type": "boolean",
"value": true
}
},
{
"key": "reservationStoragePath",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "StoragePath",
"id": "f48a527b-30a6-4d54-8829-f549bc195b69",
"label": "VNXe:qe-vnxe-nfs-1"
}
},
{
"key": "storageFreeSizeGB",
"value": {
"type": "integer",
"value": 120
}
},
{
"key": "reservationStorageReservationPriority",
"value": {
"type": "integer",
"value": 1
}
}]
}
}]
}
},
{
"key": "resourcePool",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ResourcePools",
"id": "4e51fabc-19e8-4e79-b413-d52309b3bb62",
"label": "CoreDev"
}
}]
}
}
”
Example: JSON Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Delete a Reservation
You can use the vRealize Automation REST API reservation service to delete an existing reservation.
Programming Guide
VMware, Inc. 283
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the reservation ID of the reservation that you want to delete. This information is required API
command input. See Syntax for Displaying a List of Reservations.
Procedure
uUse the reservation service to delete the existing reservation.
The following example command deletes a reservation with the ID of 94d74105-831a-4598-8f42-
efd590fea15c.
curl –X “Delete” --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c
The following output is returned based on the command input.
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Syntax for Deleting a Reservation
You can use the vRealize Automation REST API reservation service to delete an existing reservation.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations/$reservationId
Method Delete
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$reservationId Specifies the unique identifier of the reservation to delete. For information
about how to obtain the reservation ID, see Syntax for Displaying a List of
Reservations.
Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Programming Guide
VMware, Inc. 284
Example: curl Command
The following example command deletes a reservation with an ID of 94d74105-831a-4598-8f42-
efd590fea15c.
curl –X “Delete” --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/94d74105-831a-4598-8f42-efd590fea15c
Example: JSON Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Working with Reservation Policies
You can use the vRealize Automation REST API to work with the reservation service to perform a variety
of functions, such as creating and updating reservation policies.
While many functions are stand-alone, some functions rely on the output of others. For example, to delete
a reservation ID, you must first obtain the ID of the reservation to delete.
List Reservation Policies
You can use the REST API reservation service to list existing reservation policies. Use this information to
obtain a reservation policy ID in preparation for updating or deleting the reservation policy.
For information about available command input and output parameters, see Syntax for Listing
Reservation Policies.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Programming Guide
VMware, Inc. 285
Procedure
uRun the following example command to list all available reservation policies.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies
The following example output lists two reservation policies, named reservationPolicyTest and
reservationPolicyTest2. You can use the ID value for each reservation policy to update or delete
them. See Syntax for Updating a Reservation Policyand Syntax for Deleting a Reservation Policy
Syntax.
{
"links": [],
"content": [{
"@type": "ReservationPolicy",
"id": "8adafb54-4c85-4478-86f0-b6ae80ab5ca4",
"name": "reservationPolicyTest",
"description": "reservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
},
{
"@type": "reservationPolicy",
"id": "fdd9854b-012e-41d7-ad17-fc73d4395714",
"name": "reservationPolicyTest2",
"description": "reservationPolicyDescTest2",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.Storage"
}],
"metadata": {
"size": 0,
"totalElements": 2,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Syntax for Listing Reservation Policies
You can use the vRealize Automation REST API to list existing reservation policies. Use this information
to obtain a reservation policy ID in preparation for updating or deleting the reservation policy.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations/policies
Method Get
Programming Guide
VMware, Inc. 286
Parameter Description
$host Specifies the host name and fully qualified domain name or IP address of
the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Specifies an array of link objects, each of which contains the following parts:
nrel
Specifies the name of the link.
nSelf refers to the object which was returned or requested.
nFirst, Previous, Next, and Last refer to corresponding pages of pageable lists.
nSpecifies the application or service that determines the other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of the tenant objects returned in a
pageable list. Each tenant object contains the following information:
n@type. Contains the ReservationPolicy string.
nid. Specifies the unique reservation policy ID.
nname. Specifies the reservation policy name.
ndescription. Specifies the reservation policy description.
reservationPolicyTypeId Specifies the type of reservation policy. Supported vRealize Automation reservation policy types are
Reservation.Policy.ComputeResource and Reservation.Policy.Storage.
Metadata Specifies the paging-related data:
nSize. Specifies the maximum number of rows per page.
ntotalElements. Specifies the number of rows returned.
ntotalPages. Specifies the total number of pages of data available.
nNumber. Specifies the current page number.
nOffset. Specifies the number of rows skipped.
Example: curl Command
List all available reservation policies.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies
Programming Guide
VMware, Inc. 287
Example: JSON Output
The following example output lists two reservation policies, named reservationPolicyTest and
reservationPolicyTest2. Use the id value for each reservation policy to update or delete them. See
Syntax for Updating a Reservation Policyand Syntax for Deleting a Reservation Policy Syntax.
{
"links": [],
"content": [{
"@type": "ReservationPolicy",
"id": "8adafb54-4c85-4478-86f0-b6ae80ab5ca4",
"name": "reservationPolicyTest",
"description": "reservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
},
{
"@type": "reservationPolicy",
"id": "fdd9854b-012e-41d7-ad17-fc73d4395714",
"name": "reservationPolicyTest2",
"description": "reservationPolicyDescTest2",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.Storage"
}],
"metadata": {
"size": 0,
"totalElements": 2,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Create a Reservation Policy
You can use the REST API reservation service to create a reservation policy.
For information about available command input and output parameters, see Syntax for Creating a
Reservation Policy.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nList existing reservation policies to create the sample output required for creating a new reservation
policy. See List Reservation Policies.
Programming Guide
VMware, Inc. 288
Procedure
uUse the reservation service to create a reservation policy as shown in the following sample
command.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies -d “
{
"name": "ABXReservationPolicyTest",
"description": "ABXReservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}
“
The command output contains the new reservation policy ID, for example
5fd2de36-659f-4beb-97af-77d683feb697.
Location:
https://$host/reservation-service/api/reservations/policies/5fd2de36-659f-4beb-97af-77d683feb697
Syntax for Creating a Reservation Policy
You can use the REST API reservation service to create a reservation policy.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations/policies
Method Post
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP body Describes the reservation policy to create.
n$name - reservation policy name
n$description - reservation policy description
$reservationPolicyTypeId Specifies the reservation policy type ID. The supported reservation policy
types are Reservation.Policy.ComputeResource and
Reservation.Policy.Storage.
Output
The command output contains property names and values based on the command input parameters.
The output URL contains the new reservation policy ID.
Programming Guide
VMware, Inc. 289
Property Description
status When the reservation policy is successfully created, the HTTP response
status is 201 created.
Header.Location The HTTP response contains a Location attribute that is format as
https://$host /reservation-
service/api/reservations/policies/$reservationPolicyId.
$reservationPolicyId Specifies the new reservation policy ID. Obtain this ID by listing your available
reservation policies.
Example: curl Command
The following example command uses the reservation service to create a new reservation policy.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies -d “
{
"name": "ABXReservationPolicyTest",
"description": "ABXReservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}
“
Example: JSON Output
The following example output contains the HTTP body and a location URL. The output URL contains the
new reservation policy ID, for example 5fd2de36-659f-4beb-97af-77d683feb697.
Location:
https://$host/reservation-service/api/reservations/policies/5fd2de36-659f-4beb-97af-77d683feb697
Copy the location URL from this output to an editor for future use, for example for updating or deleting the
reservation policy.
Display a Reservation Policy by ID
You can use the REST API reservation service with a reservation policy ID to display information about a
specific reservation policy.
For information about available command input and output parameters, see Syntax for Displaying a
Reservation Policy by ID.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
Programming Guide
VMware, Inc. 290
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the reservation policy ID of the reservation policy to query. See Syntax for Listing Reservation
Policies.
Procedure
uDisplay information about the reservation policy ID.
The following example displays information about reservation policy 8adafb54-4c85-4478-86f0-
b6ae80ab5ca4.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies/8adafb54-4c85-4478-86f0-b6ae80ab5ca4
The following sample output is generated.
{
"id": "8adafb54-4c85-4478-86f0-b6ae80ab5ca4",
"name": "reservationPolicyTest",
"description": "reservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}
Use the command output to make updates to the reservation policy. See Syntax for Updating a
Reservation Policy.
Syntax for Displaying a Reservation Policy by ID
You can use the REST API reservation service with a reservation policy ID to display information about a
specific reservation policy.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations/policies/$id
Method Get
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Example: Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 291
Parameter Description
$id Specifies the reservation policy ID.
$name Specifies the reservation policy name.
$description Specifies the reservation policy description.
$reservationPolicyTypeId Specifies the reservation policy type ID.
Example: Example: curl Command
The following example command retrieves information for the reservation policy with an ID of
8adafb54-4c85-4478-86f0-b6ae80ab5ca4.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies/8adafb54-4c85-4478-86f0-b6ae80ab5ca4
Example: Example: JSON Output
The following sample output displays information for the specified reservation policy ID
8adafb54-4c85-4478-86f0-b6ae80ab5ca4.
{
"id": "8adafb54-4c85-4478-86f0-b6ae80ab5ca4",
"name": "reservationPolicyTest",
"description": "reservationPolicyDescTest",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}
Update a Reservation Policy
You can use the REST API reservation service to update a vRealize Automation reservation policy.
For information about available command input and output parameters, see Syntax for Updating a
Reservation Policy.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nGet the required reservation policy ID. See Syntax for Listing Reservation Policies.
nQuery the reservation policy and copy the response output to an XML editor for use as the basis of
your command input for this task. See Syntax for Displaying a Reservation Policy by ID.
Programming Guide
VMware, Inc. 292
Procedure
1Query the reservation policy and copy the response output to an editor.
2Change the following information to use as the basis of the command input for this task.
nReservation policy name
nReservation policy description
nReservation policy type ID
3Update the name and description values for the reservation policy ID.
The following example syntax updates the information for reservation policy ID
94d74105-831a-4598-8f42-efd590fea15c.
curl –X PUT --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies/94d74105-831a-4598-8f42-efd590fea15c -
d “
{
"id": "94d74105-831a-4598-8f42-efd590fea15c",
"name": "ReservationPolicyTestRename",
"description": "ReservationPolicyDescTestRename",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}
“
If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.
Syntax for Updating a Reservation Policy
You can use the vRealize Automation REST API reservation service to update a reservation policy.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations/policies/$id
Method Put
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
Programming Guide
VMware, Inc. 293
Parameter Description
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP body Describes the reservation policy to update.
To obtain the value, query the reservation policy and copy the response
output to an editor for use as the basis of your command input. See Syntax for
Displaying a Reservation Policy by ID.
n$id - reservation policy ID
n$name - reservation policy name
n$description - reservation policy description
n$reservationPolicyTypeId - reservation policy type ID
The supported reservation policy types are
Reservation.Policy.ComputeResource and Reservation.Policy.Storage.
Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Example: curl Command
The following example command updates the name and description values for the reservation policy with
an ID of 94d74105-831a-4598-8f42-efd590fea15c.
curl –X PUT --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies/94d74105-831a-4598-8f42-efd590fea15c -d “
{
"id": "94d74105-831a-4598-8f42-efd590fea15c",
"name": "ReservationPolicyTestRename",
"description": "ReservationPolicyDescTestRename",
"reservationPolicyTypeId": "Infrastructure.Reservation.Policy.ComputeResource"
}
“
Example: JSON Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Delete a Reservation Policy
You can use the REST API reservation service to delete a vRealize Automation reservation policy.
For information about available command input and output parameters, see Syntax for Deleting a
Reservation Policy Syntax.
Prerequisites
nLog in to vRealize Automation as a fabric group administrator.
Programming Guide
VMware, Inc. 294
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nGet the required reservation policy ID. See Syntax for Listing Reservation Policies.
Procedure
uDelete the reservation policy ID.
The following example syntax updates the information for reservation policy
ID8adafb54-4c85-4478-86f0-b6ae80ab5ca4.
curl –X “Delete” --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies/8adafb54-4c85-4478-86f0-b6ae80ab5ca4
If the command is successful, the HTTP response body is empty except for a 204 No Content
status statement.
Syntax for Deleting a Reservation Policy Syntax
You can use the REST API reservation service to delete a vRealize Automation reservation policy.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/reservation-service/api/reservations/policies/$id
Method Delete
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$id Specifies the reservation policy ID. To obtain the reservation policy ID to
delete, see Syntax for Listing Reservation Policies.
Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Programming Guide
VMware, Inc. 295
Example: Example: curl Command
The following example command deletes a reservation policy with an ID of 8adafb54-4c85-4478-86f0-
b6ae80ab5ca4.
curl –X “Delete” --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations/policies/8adafb54-4c85-4478-86f0-b6ae80ab5ca4
Example: Example: JSON Output
If the command is successful, the HTTP response body is empty except for a 204 No Content status
statement.
Working with Key Pairs
You can work with the keyValuePair data element of the REST API workitem service to list, create, and
update key pairs.
For information about using the vRealize Automation application user interface to work with key pairs, see
the IaaS Configuration documentation.
Get a Key Pair List
You can use the vRealize Automation REST API to get a list of valid key pairs.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
uUse the following sample command to list all available reservation policies.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs
The following JSON output is returned based on your command input.
{
"links": [
],
"content": [
{
Programming Guide
VMware, Inc. 296
"@type": "KeyPair",
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey": ""
},
{
"@type": "KeyPair",
"id": 27,
"name": "EC2KeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9UplO
+YKnAcqUSyXB6PQ3I/NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/h
KsXKbNSJz
+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/0SNr2yCz
sZcqbVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ17jyQD
+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBi
CzjvyBqof21y6dhGCd1q48Dkd72QCj6gGV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g
+giB9j4VQOMvC/uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4
XrmRt3P09FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S
+XyzvFDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR
+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXH
BNlrp0L7bAMggpmystGIkBNkSRhcDAFflNoS/MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/rQSSolcBfVhbejVp
bktJo4YKB7dzSDcJTSw99Uve
+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/17WCu7mQ
XMevlIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/kT
+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/dzW6ONeJygjIlpgfwSLwr8JA4GanN1R
WGeqRNjfOOGgdufIvDqmBB/klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm
+DltRM1Nw3o9WAJjQJ5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/dJQyibZAg1yDqyI3sIL3
CeGr7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz
+p5JrIb192STI/PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ
+ZaYfxCc1UKO1AYBGS9ARz5OtYQU64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s
+N61TPQ9HZuof/c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/zGgR9yTOeADIXHWsF4lQyai9Mn
mEaclHVWmK+LiVZSAfk6auEm
+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wfSIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK
+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1TyJaKIFhhqs6bA6/PH
+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/SpOZ5MPnNjRo
+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/PClR46vQ/3Iyv5pUG
Pno
+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1XpetxvG9d7L1lU/sg
CVmEhdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
},//Omit 18 more key pairs
],
"metadata": {
"size": 0,
"totalElements": 20,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
What to do next
Programming Guide
VMware, Inc. 297
Syntax for Getting a Key Pair List
You can use the vRealize Automation REST API to get a list of valid key pairs.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/iaas-proxy-provider/api/keyPairs
Method Get
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 298
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a single
profile.
nFirst, Previous, Next, and Last refer to corresponding
pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of the
tenant objects returned in a pageable list. Each tenant object can
contain the following information:
n@type:
Contains the KeyPair string.
n$id:
Specifies the unique identifier of the key pair.
n$name:
Specifies the name of the key pair.
n$computeresourceId:
Specifies the compute resource ID that is binded to the key pair.
n$secretKey:
Specifies the secret key for the key pair.
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Example: curl Command
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs
Programming Guide
VMware, Inc. 299
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links": [
],
"content": [
{
"@type": "KeyPair",
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey": ""
},
{
"@type": "KeyPair",
"id": 27,
"name": "EC2KeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9UplO
+YKnAcqUSyXB6PQ3I/NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/hKsXK
bNSJz
+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/0SNr2yCzsZcq
bVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ17jyQD
+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBiCzjv
yBqof21y6dhGCd1q48Dkd72QCj6gGV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g
+giB9j4VQOMvC/uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4XrmR
t3P09FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S
+XyzvFDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR
+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXHBNlr
p0L7bAMggpmystGIkBNkSRhcDAFflNoS/MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/rQSSolcBfVhbejVpbktJo4YK
B7dzSDcJTSw99Uve
+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/17WCu7mQXMev
lIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/kT
+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/dzW6ONeJygjIlpgfwSLwr8JA4GanN1RWGeq
RNjfOOGgdufIvDqmBB/klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm
+DltRM1Nw3o9WAJjQJ5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/dJQyibZAg1yDqyI3sIL3CeGr
7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz
+p5JrIb192STI/PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ
+ZaYfxCc1UKO1AYBGS9ARz5OtYQU64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s
+N61TPQ9HZuof/c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/zGgR9yTOeADIXHWsF4lQyai9MnmEac
lHVWmK+LiVZSAfk6auEm+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wfSIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK
+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1TyJaKIFhhqs6bA6/PH
+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/SpOZ5MPnNjRo
+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/PClR46vQ/3Iyv5pUGPno
+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1XpetxvG9d7L1lU/sgCVmE
hdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
},//Omit 18 more key pairs
],
"metadata": {
"size": 0,
"totalElements": 20,
Programming Guide
VMware, Inc. 300
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Create a Key Pair
You can use the vRealize Automation REST API to create a key pair.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nGet the required compute resource ID. See Get a Compute Resource for the Reservation.
Procedure
1Obtain the compute resource ID of the target key pair that you want to create.
2Use the following sample command to create a key pair.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs -d
“
{
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9UplO
+YKnAcqUSyXB6PQ3I/NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/h
KsXKbNSJz
+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/0SNr2yCz
sZcqbVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ17jyQD
+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBi
CzjvyBqof21y6dhGCd1q48Dkd72QCj6gGV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g
+giB9j4VQOMvC/uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4
XrmRt3P09FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S
+XyzvFDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR
+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXH
BNlrp0L7bAMggpmystGIkBNkSRhcDAFflNoS/MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/rQSSolcBfVhbejVp
bktJo4YKB7dzSDcJTSw99Uve
+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/17WCu7mQ
XMevlIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/kT
+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/dzW6ONeJygjIlpgfwSLwr8JA4GanN1R
WGeqRNjfOOGgdufIvDqmBB/klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm
+DltRM1Nw3o9WAJjQJ5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/dJQyibZAg1yDqyI3sIL3
Programming Guide
VMware, Inc. 301
CeGr7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz
+p5JrIb192STI/PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ
+ZaYfxCc1UKO1AYBGS9ARz5OtYQU64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s
+N61TPQ9HZuof/c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/zGgR9yTOeADIXHWsF4lQyai9Mn
mEaclHVWmK+LiVZSAfk6auEm
+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wfSIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK
+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1TyJaKIFhhqs6bA6/PH
+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/SpOZ5MPnNjRo
+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/PClR46vQ/3Iyv5pUG
Pno
+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1XpetxvG9d7L1lU/sg
CVmEhdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
}
“
Syntax for Creating a Key Pair
You can use the vRealize Automation REST API to create a key pair.
Input
Use the supported input parameters to control the command output.
Input Description
URL https://$host/iaas-proxy-provider/api/keyPairs
Method Post
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP Body Contains the HTTP body of the target key pair.
n$id:
Specifies the unique identifier of the key pair.
n$name:
Specifies the name of the key pair.
n$computeResourceId:
Specifies the compute resource ID that is binded to the key
pair.
n$secretKey:
Specifies the secret key for the key pair.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 302
Parameter Description
status If the command is successful, the HTTP status is 201 Created.
Header.Location The http response should contain a Location attribute that is
formatted as https://$host/iaas-proxy-
provider/api/keyPairs/$keypairID.
$keypairID Specifies the unique identifier of the new key pair.
Example: curl Command
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs -d
“
{
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9UplO
+YKnAcqUSyXB6PQ3I/NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/hKsXK
bNSJz
+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/0SNr2yCzsZcq
bVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ17jyQD
+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBiCzjv
yBqof21y6dhGCd1q48Dkd72QCj6gGV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g
+giB9j4VQOMvC/uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4XrmR
t3P09FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S
+XyzvFDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR
+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXHBNlr
p0L7bAMggpmystGIkBNkSRhcDAFflNoS/MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/rQSSolcBfVhbejVpbktJo4YK
B7dzSDcJTSw99Uve
+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/17WCu7mQXMev
lIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/kT
+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/dzW6ONeJygjIlpgfwSLwr8JA4GanN1RWGeq
RNjfOOGgdufIvDqmBB/klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm
+DltRM1Nw3o9WAJjQJ5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/dJQyibZAg1yDqyI3sIL3CeGr
7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz
+p5JrIb192STI/PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ
+ZaYfxCc1UKO1AYBGS9ARz5OtYQU64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s
+N61TPQ9HZuof/c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/zGgR9yTOeADIXHWsF4lQyai9MnmEac
lHVWmK+LiVZSAfk6auEm+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wfSIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK
+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1TyJaKIFhhqs6bA6/PH
+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/SpOZ5MPnNjRo
+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/PClR46vQ/3Iyv5pUGPno
+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1XpetxvG9d7L1lU/sgCVmE
hdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
}
“
Programming Guide
VMware, Inc. 303
Example: JSON Output
The output returns an empty HTTP response body and the host information and key pair ID in the header
statement.
Location:
https://vcac148-084-241.eng.mycompany.com/iaas-proxy-provider/api/keyPairs/56
Copy the location URL into a text editor for future use.
Query a Key Pair
You can use the REST API to query a key pair that is available for the vRealize Automation tenant
administrator.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
uUse the following sample command to query a key pair.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs/26
The following JSON output is returned based on the command input.
{
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey": ""
}
Syntax for Querying a Key Pair
You can use the REST API to query a key pair that is available for the vRealize Automation tenant
administrator.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 304
Parameters Description
URL https://$host/iaas-proxy-provider/api/keyPairs/$ids
Method Get
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$id: Specifies the unique identifier of the key pair.
Output
The command output contains property names and values based on the command input parameters.
Parameters Description
$id: Specifies the unique identifier of the key pair.
$name: Specifies the name of the key pair.
$computeResourceId: Specifies the compute resource ID that is binded to the key pair.
$secretKey: Specifies the secret key for the key pair.
Example: curl Command
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs/26
Example: JSON Output
The following JSON output is returned based on the command input.
{
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey": ""
}
Update a Key Pair
You can use the vRealize Automation REST API to update an existing key pair.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
Programming Guide
VMware, Inc. 305
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
uUse the following sample command to update a key pair.
curl –X PUT --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs/26 -d “
{
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9UplO
+YKnAcqUSyXB6PQ3I/NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/h
KsXKbNSJz
+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/0SNr2yCz
sZcqbVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ17jyQD
+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBi
CzjvyBqof21y6dhGCd1q48Dkd72QCj6gGV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g
+giB9j4VQOMvC/uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4
XrmRt3P09FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S
+XyzvFDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR
+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXH
BNlrp0L7bAMggpmystGIkBNkSRhcDAFflNoS/MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/rQSSolcBfVhbejVp
bktJo4YKB7dzSDcJTSw99Uve
+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/17WCu7mQ
XMevlIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/kT
+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/dzW6ONeJygjIlpgfwSLwr8JA4GanN1R
WGeqRNjfOOGgdufIvDqmBB/klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm
+DltRM1Nw3o9WAJjQJ5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/dJQyibZAg1yDqyI3sIL3
CeGr7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz
+p5JrIb192STI/PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ
+ZaYfxCc1UKO1AYBGS9ARz5OtYQU64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s
+N61TPQ9HZuof/c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/zGgR9yTOeADIXHWsF4lQyai9Mn
mEaclHVWmK+LiVZSAfk6auEm
+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wfSIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK
+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1TyJaKIFhhqs6bA6/PH
+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/SpOZ5MPnNjRo
+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/PClR46vQ/3Iyv5pUG
Pno
+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1XpetxvG9d7L1lU/sg
CVmEhdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
}
“
The output contains an empty HTTP response body and the following status code.
204 No Content
Programming Guide
VMware, Inc. 306
Syntax for Updating a Key Pair
You can update an existing key pair by using the vRealize Automation REST API.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/iaas-proxy-provider/api/keyPairs/$id
Method Put
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP Body Contains the HTTP body that describes the key pair to update
and what to update in the identified key pair.
n$id:
Specifies the unique identifier of the key pair.
n$name:
Specifies the name of the key pair.
n$computeResourceId:
Specifies the compute resource ID that is binded to the key
pair.
n$secretKey:
Specifies the secret key for the key pair.
Output
The command output contains a status statement.
Parameter Description
status If the command is not successful, the HTTP status is 204 No
Content.
Example: curl Command
curl –X PUT --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs/26 -d “
{
"id": 26,
"name": "TestKeyPair",
"computeResourceId": "ca4dcca0-85ce-49dd-8371-4ce7c8e2d5e6",
"secretKey":
"jmfhkPFLe1xF4LsgxyYDlBH65IjiKsNH3xgeUhNt6AyIcSA2eZsxH9FNFcDst1cRLQUmLYLUCN6ZlrVtD3C5CYAOEE9UplO
+YKnAcqUSyXB6PQ3I/NuebdtGrx38fkTJsEpRqxLppWPJpVlHYRO2O7GhhWnE6F3bPwwg3dWwymqWHxBZlCcuEcztovbhN8r7/hKsXK
bNSJz
Programming Guide
VMware, Inc. 307
+J8DVhPB7PPdHJJ4E/6a9IXkNQs/T0NknCOyc0YcFVpgrc3PMGabi8vd/7v0nEtDARyA8WwAGgtedHGtBo2gciY1Bu/0SNr2yCzsZcq
bVeg4ufkjlv0G1Ed1FfGHMh5kuVC7alk2aSI5YkWnS4d9YJYi7diYmc7GmrVW0XWNz4kEMdQBkK+CvMxiZ17jyQD
+V4NuM4ydNPJJMqpvoAHtLrAmp/hXhInuf8j/l0mbawWSvUDUA3s4ZE55cFp546MJIrVCRyoMoKfxuHquIPdANRAVs7qo9DGxBiCzjv
yBqof21y6dhGCd1q48Dkd72QCj6gGV84lHZ/zXWcz4+aKFRVolNqSZEtZ/9wzdjqYdn/ySl0S5GE2rG/xRsh6g
+giB9j4VQOMvC/uvhkYUo3WfTgxi8SeipFIVcbvkkOI0ubPU1xnWdDErjji6UwEtmjajHuiA93GtiWIdeCvyKQWmo9jkkLUmQe4XrmR
t3P09FWm8Quwe5Hw6czK0dIODwcHE0Azl0TqLKl1wA39uhGrHoXNypFiOMmRbo1YnfIW23ggEnxRACY1jUZkTewhSbVY4S
+XyzvFDcTRpSjWpRUOozYuMSsDnRzCJZQXhg4IYvwTvG+uEUu4+YR
+WCrgC6Tk60i3cLSuHnV5k00AWXWwvnPnwYRFxxyzhcSDx4jyyCaysmBo9NHGwNkJU1F94SY5Vp6O0E9EJuViMohF1gc18Q6SXHBNlr
p0L7bAMggpmystGIkBNkSRhcDAFflNoS/MTEW0uJoDfe6DczAt9B0YGtHdy3AH/U4ADOPkz5xlQ4EL/rQSSolcBfVhbejVpbktJo4YK
B7dzSDcJTSw99Uve
+BQjhigVcfxDXme3MrXPO4BeCU891DLaTJyeYYADyGUKZfKFC6iCO9SQfynwK6iE2eYKLpIMcf/C8+rLJVXcy7gkjT/17WCu7mQXMev
lIJlaApyytN1eCJcVDsr4N5LURZofnPArromhLy3JWiEJ4dtq+17KPiMff34e/kT
+i0ns73Wdy1oblZAi5kwBFMgBjAMex5fGNR1q/wtY1beWaxVw1J5RViaXeXSKO5mttE/dzW6ONeJygjIlpgfwSLwr8JA4GanN1RWGeq
RNjfOOGgdufIvDqmBB/klnuGTVgMVWc0caQMzFq07UcXlMsgNOROHBfkzelWB+v0kXHsQ4eSeYVhjnT3CPURr5UMZ8YQ7fm
+DltRM1Nw3o9WAJjQJ5xyT2kxou4PHBzoq6JouwrCluig7GQ06lVu2C3nNpyfGKsmFyOlHMaVuRYX9/dJQyibZAg1yDqyI3sIL3CeGr
7ynhOTEEQiAOWqgIUyDvrvc2Ma4RjjI4b3eFfBMkLWqTqs33+/5QktQz
+p5JrIb192STI/PwHY51MfkbDErpeNFY479P7yKlZGbB8WVBfFpJCoVTQoZNio1ZhA7nA+rkqNbM4mcHQ
+ZaYfxCc1UKO1AYBGS9ARz5OtYQU64Ei7tpWUbsYDXIA9Ss4VRASHvA7M3s
+N61TPQ9HZuof/c6TbzOWE0ojtxEyO3sDsBWumm13/61+JT3k0rIdmV25aVvxrUv1S3JLI/o/zGgR9yTOeADIXHWsF4lQyai9MnmEac
lHVWmK+LiVZSAfk6auEm+13a24+UM9Mg6ninfzeIq0cjdT3OUweXgDnK0BMGX0wfSIYIrpRrDr9QdVoHGtdqZvJ62F8aITjO8urIK
+bXZzwgFQ2JE4SYxojNHPYwBjadFm0A2eVPtOivMYYYr8FCUYtfbjjIS1TyJaKIFhhqs6bA6/PH
+NvBmbozpDkH9wg3mQ1SOP5iSMAMue6fx+b/SpOZ5MPnNjRo
+VXG3qFl936AB4F1F2ObD27GyjibeYmhQkITtp/yGYCZ68PhCun0/eiEjmXiOUx/5jYGOUEZ1Ddojhc5M/PClR46vQ/3Iyv5pUGPno
+wkn34lk6s2PO2axrXvQqTwoiYC3f2p1gp0qYidIzKa2KHrUCOF4hnjQ3v3z93ORMCK3wN5uQ3xMFOd7+1XpetxvG9d7L1lU/sgCVmE
hdOSnhLC5Jeq70MVwixPocnJR4nyotPE=="
}
“
Example: JSON Output
The output contains an empty HTTP response body and the following status code.
204 No Content
Delete a Key Pair
You can use the vRealize Automation REST API to delete a key pair.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Programming Guide
VMware, Inc. 308
Procedure
uUse the following sample command to delete a key pair.
curl –X “Delete” --insecure -H "Accept:application/json"
-H "Authorization: Bearere $token"
https://$host/iaas-proxy-provider/api/keyPairs/26
The output contains an empty HTTP response body and the following status code.
204 No Content
Syntax for Deleting a Key Pair
You can use the vRealize Automation REST API to delete a key pair.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Input
Use the supported input parameters to control the command output.
Input Description
URL https://$host/iaas-proxy-provider/api/keyPairs/$id
Method Delete
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary
credentials.
$id: Specifies the unique identifier of the key pair.
Output
The command output contains a status statement.
Parameter Description
status If the command is not successful, the HTTP status is 204 No
Content.
Programming Guide
VMware, Inc. 309
Example: curl Command
The following example command deletes a key pair.
curl –X “Delete” --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/keyPairs/26
Example: JSON Output
The output contains an empty HTTP response body and the following status code.
204 No Content
Working with Network Profiles
You can use the vRealize Automation IaaS proxy provider service and IPAM service REST API to create,
list, and update network profiles.
You can access the following types of network profile by using the same programming calls. Different
types of network profiles contain different fields.
Programming Guide
VMware, Inc. 310
Network Profile
Type Description
External All network profiles use the elements in the object definition for external network. The network definition
specifies the network address configuration for the network. The external network definition can specify:
nExisting network addresses configured on the vSphere server. They are the external part of the NAT and
routed networks types. An external network profile can define a range of static IP addresses available on
the external network.
nAn endpoint that allows access to IP ranges obtained from the supplied VMware internal IPAM provider or
an external IPAM provider solution that you have imported and registered in vRealize Orchestrator, such
as Infoblox IPAM, and existing network address ranges configured by the IPAM provider software.
nAn endpoint that allows access to IP ranges obtained from the supplied VMware internal IPAM provider or
an external IPAM provider solution that you have imported and registered in vRealize Orchestrator, such
as Infoblox IPAM, and existing network address ranges configured by the IPAM provider software.
An external network profile with a static IP range is a prerequisite for NAT and routed networks.
When you specify a NAT network profile or a Routed network profile, the base object definition for the external
network profile is used and additional definitions for the NAT or Routed network profiles are required to
complete the profile.
NAT An external network that uses network address translation (NAT) to enable one set of IP addresses for external
communication and another set for internal communications. With one-to-one NAT networks, every virtual
machine is assigned an external IP address from the external network profile and an internal IP address from
the NAT network profile. With one-to-many NAT networks, all machines share a single IP address from the
external network profile for external communication.
A NAT network profile defines local and external networks that use a translation table for mutual
communication.
Routed A routed network represents a routable IP space divided across subnets that are linked together using
Distributed Logical Router (DLR). Every new routed network has the next available subnet assigned to it and is
associated with other routed networks that use the same network profile. The virtual machines that are
provisioned with routed networks that have the same routed network profile can communicate with each other
and the external network.
A routed network profile defines a routable space and available subnets.
For more information about Distributed Logical Router, see NSX Administration Guide.
Get a Network Profile List
You can use the vRealize Automation REST API to get a list of current network profiles.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Programming Guide
VMware, Inc. 311
Procedure
uUse the following sample command to list all available network profiles.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/ iaas-proxy-provider/api/network/profiles
The following JSON output is returned based on the command input.
{
"links": [
],
"content": [
{
"@type": "NATNetworkProfile",
"id": "599541aa-ffb0-4a37-9483-4353f3fc6be3",
"name": "NATTest",
"description": "",
"createdDate": "2014-11-11T02:29:09.000Z",
"lastModifiedDate": "2014-11-11T02:29:09.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "9f7d8025-bd4c-4560-9b41-9ce455ee49ae",
"name": "range",
"description": "",
"beginIPv4Address": "10.118.190.110",
"endIPv4Address": "10.118.190.115",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z",
"definedAddresses": [
{
"id": "6e7dc8c3-dc64-4ebd-a282-05852010310f",
"name": null,
"description": null,
"IPv4Address": "10.118.190.111",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "f6802100-1d7e-4f31-bdeb-1b27f7e77766",
"name": null,
"description": null,
"IPv4Address": "10.118.190.115",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
Programming Guide
VMware, Inc. 312
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "f6deba8c-fbf4-4ea0-9d9c-325e9db2f13e",
"name": null,
"description": null,
"IPv4Address": "10.118.190.114",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "9d5a9d25-26d7-4ce3-93a2-61242a88c5b2",
"name": null,
"description": null,
"IPv4Address": "10.118.190.110",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "2b616f1a-dc35-4caa-8ee7-6494ca50db57",
"name": null,
"description": null,
"IPv4Address": "10.118.190.113",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "9dd5d265-ec23-42be-9bdb-734c11b1e315",
"name": null,
"description": null,
"IPv4Address": "10.118.190.112",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
]
}
],
"profileType": "NAT",
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.118.190.230",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
Programming Guide
VMware, Inc. 313
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": "",
"dhcpStartIPAddress": null,
"dhcpEndIPAddress": null,
"leaseTimeInSeconds": 0
},
{
"@type": "PrivateNetworkProfile",
"id": "594e4016-b067-4d19-aa81-63502675f925",
"name": "privateTest",
"description": "",
"createdDate": "2014-11-11T02:26:44.000Z",
"lastModifiedDate": "2014-11-11T02:26:44.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "8827193e-f1c3-493e-8bcd-1b153f2a5e74",
"name": "range",
"description": "",
"beginIPv4Address": "10.118.190.110",
"endIPv4Address": "10.118.190.112",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z",
"definedAddresses": [
{
"id": "262a4273-1e75-4c23-8fb8-088473521b19",
"name": null,
"description": null,
"IPv4Address": "10.118.190.111",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
},
{
"id": "7eebd0ad-0dde-4fa1-aad3-750498214caf",
"name": null,
"description": null,
"IPv4Address": "10.118.190.110",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
},
{
"id": "37ca8368-5d19-4d23-a6b8-7b233bb2320d",
"name": null,
"description": null,
"IPv4Address": "10.118.190.112",
"IPSortValue": 0,
Programming Guide
VMware, Inc. 314
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
},
]
}
],
"profileType": "PRIVATE",
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.118.190.230",
"dhcpStartIPAddress": null,
"dhcpEndIPAddress": null,
"leaseTimeInSeconds": 0
},
{
"@type": "RoutedNetworkProfile",
"id": "a3dbfc76-7eab-4c1f-8f59-8fcc0b50ec6c",
"name": "routedTest",
"description": "",
"createdDate": "2014-11-11T02:31:11.000Z",
"lastModifiedDate": "2014-11-11T02:31:11.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "4d9b291a-841f-4f62-b03e-83781133024c",
"name": "Range 1",
"description": "",
"beginIPv4Address": "10.118.183.1",
"endIPv4Address": "10.118.183.254",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:30:34.000Z",
"lastModifiedDate": "2014-11-11T02:30:34.000Z",
"definedAddresses": [
]
}
],
"profileType": "ROUTED",
"subnetMask": "255.255.254.0",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": "",
"baseIP": "10.118.183.1"
},
{
"@type": "ExternalNetworkProfile",
"id": "68b6a183-fc8a-4592-af23-92f8d410ee32",
"name": "externalTest",
"description": "",
"createdDate": "2014-11-11T02:24:07.000Z",
"lastModifiedDate": "2014-11-11T02:24:07.000Z",
Programming Guide
VMware, Inc. 315
"isHidden": false,
"definedRanges": [
{
"id": "3a85a049-522f-4b64-8f60-6e7b252ad204",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.200",
"endIPv4Address": "10.110.183.201",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z",
"definedAddresses": [
{
"id": "f229ea1a-18de-4dae-ae7b-0cec7feaa99b",
"name": null,
"description": null,
"IPv4Address": "10.110.183.201",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
{
"id": "cd39e786-6490-4c95-8cf7-d6e3b6a0ba67",
"name": null,
"description": null,
"IPv4Address": "10.110.183.200",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
]
},
{
"id": "67acdc6f-d0b9-4f47-a74b-ea58ff9ce074",
"name": "range2",
"description": "",
"beginIPv4Address": "10.110.183.180",
"endIPv4Address": "10.110.183.183",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z",
"definedAddresses": [
{
"id": "37b5c7d1-b82f-4961-a7cc-0117d3610ed7",
"name": null,
"description": null,
"IPv4Address": "10.110.183.182",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
Programming Guide
VMware, Inc. 316
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
"id": "43d8bae4-7b78-40d2-a9ef-350d28901c24",
"name": null,
"description": null,
"IPv4Address": "10.110.183.180",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
{
"id": "c270ce8e-a418-4d02-89db-3b84f6816a75",
"name": null,
"description": null,
"IPv4Address": "10.110.183.181",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
{
"id": "684bbe43-29ce-4113-92c7-43921c943099",
"name": null,
"description": null,
"IPv4Address": "10.110.183.183",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
]
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
],
"metadata": {
"size": 0,
"totalElements": 4,
"totalPages": 1,
Programming Guide
VMware, Inc. 317
"number": 1,
"offset": 0
}
}
Syntax for Getting a Network Profile List
You can use the vRealize Automation IaaS proxy provider REST API to get a list of current network
profiles.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/iaas-proxy-provider/api/network/profiles
Method Get
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 318
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a single
profile.
nFirst, Previous, Next, and Last refer to corresponding
pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of the
tenant objects returned in a pageable list. Each tenant object can
contain the following information:
n@type:
Specifies one of the following network profile type values:
nExternalNetworkProfile
nNATNetworkProfile
nPrivateNetworkProfile
nRoutedNetworkProfile
n$id:
Specifies the unique network profile identifier.
n$name:
Specifies the network profile name.
ncreatedDate:
Specifies the date and time that the network profile was created.
nlastModifiedDate:
Specifies the date and time that the network profile was last
modified.
nisHidden:
Specifies if the network profile is hidden from the
vRealize Automation user interface.
ndefinedRanges:
Specifies the IP range array that is defined for the network
profile.
nprofileType:
Specifies the network profile type as one of the following types:
nEXTERNAL
nNAT
nROUTED
nIPAMEndpointId:
Programming Guide
VMware, Inc. 319
Parameter Description
If you are creating or querying an external network profile that
uses extrernal, IPAM , specifies the endpoint ID for the external
IPAM provider. If you are creating a network profile and the
profile does not use external IPAM, code null for this value.
nsubnetMask:
Specifies the subnet mask.
ngatewayAddress:
Specifies the IP address of the network gateway.
nprimaryDnsAddress:
Specifies the IP address of the primary DNS server. This
parameter is only available for external, NAT, and routed
network profiles.
nsecondaryDnsAddress:
Specifies the IP address of a secondary DNS server. This
parameter is only available for external, NAT, and routed
network profiles.
ndnsSuffix:
Specifies the DNS suffix. This parameter is only available for
external, NAT, and routed network profiles.
ndnsSearchSuffix:
Specifies the DNS search suffix. This parameter is only
available for external, NAT, and routed network profiles.
nprimaryWinsAddress:
Specifies the IP address of the primary Wins server. This
parameter is only available for external, NAT, and routed
network profiles.
nsecondaryWinsAddress:
Specifies the IP address of secondary Wins server. This
parameter is only available for external, NAT, and routed
network profiles.
ndhcpStartIPAddress:
Specifies the start IP address of the DHCP server. This
parameter is only supported by NAT and private network
profiles.
ndhcpEndIPAddress:
Specifies the end IP address of the DHCP server. This
parameter is only supported by NAT and private network
profiles.
nleaseTimeInSeconds:
Specifies the lease time for the DHCP server. This parameter is
only supported by NAT and private network profiles.
Programming Guide
VMware, Inc. 320
Parameter Description
nbaseIP:
Specifies the base IP address. This parameter is only supported
by routed network profiles.
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Example: curl Command
The following example command returns a list of network profiles.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/ iaas-proxy-provider/api/network/profiles
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links": [
],
"content": [
{
"@type": "NATNetworkProfile",
"id": "599541aa-ffb0-4a37-9483-4353f3fc6be3",
"name": "NATTest",
"description": "",
"createdDate": "2014-11-11T02:29:09.000Z",
"lastModifiedDate": "2014-11-11T02:29:09.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "9f7d8025-bd4c-4560-9b41-9ce455ee49ae",
"name": "range",
"description": "",
"beginIPv4Address": "10.118.190.110",
"endIPv4Address": "10.118.190.115",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z",
"definedAddresses": [
{
"id": "6e7dc8c3-dc64-4ebd-a282-05852010310f",
Programming Guide
VMware, Inc. 321
"name": null,
"description": null,
"IPv4Address": "10.118.190.111",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "f6802100-1d7e-4f31-bdeb-1b27f7e77766",
"name": null,
"description": null,
"IPv4Address": "10.118.190.115",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "f6deba8c-fbf4-4ea0-9d9c-325e9db2f13e",
"name": null,
"description": null,
"IPv4Address": "10.118.190.114",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "9d5a9d25-26d7-4ce3-93a2-61242a88c5b2",
"name": null,
"description": null,
"IPv4Address": "10.118.190.110",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "2b616f1a-dc35-4caa-8ee7-6494ca50db57",
"name": null,
"description": null,
"IPv4Address": "10.118.190.113",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
{
"id": "9dd5d265-ec23-42be-9bdb-734c11b1e315",
Programming Guide
VMware, Inc. 322
"name": null,
"description": null,
"IPv4Address": "10.118.190.112",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:29:05.000Z",
"lastModifiedDate": "2014-11-11T02:29:05.000Z"
},
]
}
],
"profileType": "NAT",
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.118.190.230",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": "",
"dhcpStartIPAddress": null,
"dhcpEndIPAddress": null,
"leaseTimeInSeconds": 0
},
{
"@type": "PrivateNetworkProfile",
"id": "594e4016-b067-4d19-aa81-63502675f925",
"name": "privateTest",
"description": "",
"createdDate": "2014-11-11T02:26:44.000Z",
"lastModifiedDate": "2014-11-11T02:26:44.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "8827193e-f1c3-493e-8bcd-1b153f2a5e74",
"name": "range",
"description": "",
"beginIPv4Address": "10.118.190.110",
"endIPv4Address": "10.118.190.112",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z",
"definedAddresses": [
{
"id": "262a4273-1e75-4c23-8fb8-088473521b19",
"name": null,
"description": null,
"IPv4Address": "10.118.190.111",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
Programming Guide
VMware, Inc. 323
},
{
"id": "7eebd0ad-0dde-4fa1-aad3-750498214caf",
"name": null,
"description": null,
"IPv4Address": "10.118.190.110",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
},
{
"id": "37ca8368-5d19-4d23-a6b8-7b233bb2320d",
"name": null,
"description": null,
"IPv4Address": "10.118.190.112",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:25:57.000Z",
"lastModifiedDate": "2014-11-11T02:25:57.000Z"
},
]
}
],
"profileType": "PRIVATE",
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.118.190.230",
"dhcpStartIPAddress": null,
"dhcpEndIPAddress": null,
"leaseTimeInSeconds": 0
},
{
"@type": "RoutedNetworkProfile",
"id": "a3dbfc76-7eab-4c1f-8f59-8fcc0b50ec6c",
"name": "routedTest",
"description": "",
"createdDate": "2014-11-11T02:31:11.000Z",
"lastModifiedDate": "2014-11-11T02:31:11.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "4d9b291a-841f-4f62-b03e-83781133024c",
"name": "Range 1",
"description": "",
"beginIPv4Address": "10.118.183.1",
"endIPv4Address": "10.118.183.254",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:30:34.000Z",
"lastModifiedDate": "2014-11-11T02:30:34.000Z",
"definedAddresses": [
]
}
Programming Guide
VMware, Inc. 324
],
"profileType": "ROUTED",
"subnetMask": "255.255.254.0",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": "",
"baseIP": "10.118.183.1"
},
{
"@type": "ExternalNetworkProfile",
"id": "68b6a183-fc8a-4592-af23-92f8d410ee32",
"name": "externalTest",
"description": "",
"createdDate": "2014-11-11T02:24:07.000Z",
"lastModifiedDate": "2014-11-11T02:24:07.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "3a85a049-522f-4b64-8f60-6e7b252ad204",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.200",
"endIPv4Address": "10.110.183.201",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z",
"definedAddresses": [
{
"id": "f229ea1a-18de-4dae-ae7b-0cec7feaa99b",
"name": null,
"description": null,
"IPv4Address": "10.110.183.201",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
{
"id": "cd39e786-6490-4c95-8cf7-d6e3b6a0ba67",
"name": null,
"description": null,
"IPv4Address": "10.110.183.200",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
]
},
{
Programming Guide
VMware, Inc. 325
"id": "67acdc6f-d0b9-4f47-a74b-ea58ff9ce074",
"name": "range2",
"description": "",
"beginIPv4Address": "10.110.183.180",
"endIPv4Address": "10.110.183.183",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z",
"definedAddresses": [
{
"id": "37b5c7d1-b82f-4961-a7cc-0117d3610ed7",
"name": null,
"description": null,
"IPv4Address": "10.110.183.182",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
"id": "43d8bae4-7b78-40d2-a9ef-350d28901c24",
"name": null,
"description": null,
"IPv4Address": "10.110.183.180",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
{
"id": "c270ce8e-a418-4d02-89db-3b84f6816a75",
"name": null,
"description": null,
"IPv4Address": "10.110.183.181",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
{
"id": "684bbe43-29ce-4113-92c7-43921c943099",
"name": null,
"description": null,
"IPv4Address": "10.110.183.183",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:24:04.000Z",
"lastModifiedDate": "2014-11-11T02:24:04.000Z"
},
]
}
Programming Guide
VMware, Inc. 326
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
],
"metadata": {
"size": 0,
"totalElements": 4,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Create a Network Profile
You can use the vRealize Automation IaaS proxy provider REST API to create an external, NAT, or routed
network profile.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nIf you are using an external IPAM provider solution, verify that you have access to an endpoint for the
IPAM provider solution software.
nIf you are creating an network profile using external IPAM and are specifying definedRanges or
definedAddresses as part of the profile that you are creating, make sure that you know what
address ranges and TCP/IP addresses are actually configured on the external IPAM provider's
device.
Programming Guide
VMware, Inc. 327
Procedure
uUse the following sample command to create a network profile. You can create an external, NAT, or
routed network profile. The code in the sample command creates an external network profile without
IPAM.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/$networkProfileID -d “
{
"@type": "ExternalNetworkProfile",
"name": "externalTestCreate",
"description": "",
"isHidden": false,
"definedRanges": [
{
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.221",
"endIPv4Address": "10.110.183.240",
"state": "UNALLOCATED"
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
“
The JSON output consists of a location URL, which points to the newly created network profile. The
output contains an empty HTTP response body and the following or similar header statement. Copy
the location URL into a text editor for future use.
Location:
https://vcac148-084-241.eng.mycompany.com/iaas-proxy-provider/api/network/profiles/263b80f5-
d34f-47f2-b0b1-5a3db991c2e9
Syntax for Creating an External Network Profile Without IPAM
You can use the vRealize Automation REST API to create an external, NAT, private, or routed network
profile.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 328
Input Description
URL https://$host/iaas-proxy-provider/api/network/profiles
Method Post
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP Body The HTTP body describes the network profile to create.
Sample HTTP body field values are presented in the JSON
Output section of the Syntax for Getting a Network Profile List
topic. Format your HTTP body using this content as reference.
Output
The command output contains property names and values based on the command input parameters.
Property Description
status If the command is successful, the HTTP status is 201 Created.
Header.Location The HTTP response should contain a Location attribute that is formatted as
https://$host/iaas-proxy-
provider/api/network/profiles/$networkProfileID.
$networkProfileID Specifies the unique identifier of the new network profile.
Example: curl Command
The following example command creates an external network profile without IPAM.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/$networkProfileID -d “
{
"@type": "ExternalNetworkProfile",
"name": "externalTestCreate",
"description": "",
"isHidden": false,
"definedRanges": [
{
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.221",
"endIPv4Address": "10.110.183.240",
"state": "UNALLOCATED"
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
Programming Guide
VMware, Inc. 329
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
“
Example: JSON Output
The JSON output consists of a location URL, which points to the newly created network profile. The
output contains an empty HTTP response body and the following or similar header statement. Copy the
location URL into a text editor for future use.
Location:
https://vcac148-084-241.eng.mycompany.com/iaas-proxy-provider/api/network/profiles/263b80f5-d34f-47f2-
b0b1-5a3db991c2e9
Copy the location URL into a text editor for future use.
Syntax for Creating an External Network Profile Using External IPAM
You can use the vRealize Automation REST API to create a external network profile using external IPAM.
Input
Use the supported input parameters to control the command output.
Input Description
URL https://$host/iaas-proxy-provider/api/network/profiles
Method Post
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
Programming Guide
VMware, Inc. 330
Input Description
$token Specifies a valid HTTP bearer token with necessary credentials.
HTTP Body The HTTP body specifies the information for creating an external
IPAM profile.
nprofileType
Specify EXTERNAL for this paramter.
nid
Specifies null.
nname
Specifies the name of the profile.
nIPAMEndpointId
Specifies the endpoint ID for an external IPAM provider.
naddressSpaceExternalId
Must specify the value that is chosen in the
vRealize Automation UI for Address Space.
ndescription
Optionally, can specify a description for the profile. If you do
not provide a description, code "null" for this parameter.
ndefinedRanges
Specifies parameters that set up defined address ranges:
nexternalId
nname
ndescription
nstate
Specify "UNALLOCATED" for this value.
nbeginIPv4Address
Specify "null" for this parameter.
nendIPv4Address
Specify "null" for this parameter.
Output
The command output contains property names and values based on the command input parameters.
Property Description
status The http response should contain a Location attribute that is formatted as
https://$host/iaas-proxy-provider/api/keyPairs/$keypairID.
Header.Location The HTTP response should contain a Location attribute that is formatted as
https://$host/iaas-proxy-
provider/api/network/profiles/$networkProfileID.
$networkProfileID Specifies the unique identifier of the new network profile.
Programming Guide
VMware, Inc. 331
Example: curl Command
The following example command creates an external IPAM profile.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/$networkProfileID -d “
{
"profileType" : "EXTERNAL",
"id" : null,
"@type" : "ExternalNetworkProfile",
"name" : "External IPAM",
"IPAMEndpointId" : "c20f305c-07a5-4ba7-88ac-35da7b9713e0",
"addressSpaceExternalId" : "address-space-4",
"description" : null,
"definedRanges" : [{
"externalId" : "network-1",
"name" : "192.168.1.0/24",
"description" : "Created by vRO package stub workflow",
"state" : "UNALLOCATED",
"beginIPv4Address" : null,
"endIPv4Address" : null
}
]
}
Example: JSON Output
The output contains an empty HTTP response body and the location and network profile ID in the header
statement.
Location:
https://vcac148-084-241.eng.mycompany.com/iaas-proxy-provider/api/network/profiles/263b80f5-d34f-47f2-
b0b1-5a3db991c2e9
Copy the location URL into a text editor for future use.
Query a Network Profile
You can use the REST API to query and display an external, NAT, private, or routed network profile. For
example, you can query an external network profile and use it as the basis for creating a different type of
network profile.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Programming Guide
VMware, Inc. 332
nObtain the network profile ID to query. See Get a Network Profile List.
Procedure
uUse the following command to query the existing network profile ID 68b6a183-fc8a-4592-
af23-92f8d410ee32.
Note The output shown in the following example, shows profile for one address range. A network
profile can also contain multiple ranges.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/ iaas-proxy-provider/api/network/profiles/68b6a183-fc8a-4592-af23-92f8d410ee32
The following JSON output is returned based on the command input.
{
"@type": "ExternalNetworkProfile",
"id": "68b6a183-fc8a-4592-af23-92f8d410ee32",
"name": "externalTest",
"description": "",
"createdDate": "2014-11-11T02:24:07.000Z",
"lastModifiedDate": "2014-11-11T02:24:07.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "3a85a049-522f-4b64-8f60-6e7b252ad204",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.200",
"endIPv4Address": "10.110.183.201",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z",
"definedAddresses": [
{
"id": "f229ea1a-18de-4dae-ae7b-0cec7feaa99b",
"name": null,
"description": null,
"IPv4Address": "10.110.183.201",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
{
"id": "cd39e786-6490-4c95-8cf7-d6e3b6a0ba67",
"name": null,
"description": null,
"IPv4Address": "10.110.183.200",
"IPSortValue": 0,
"state": "UNALLOCATED",
Programming Guide
VMware, Inc. 333
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
Syntax for Querying a Network Profile
You can use the vRealize Automation REST API to query and display an external, NAT,or routed network
profile. For example, you can query an external network profile and use it as the basis for creating a
different type of network profile.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/iaas-proxy-provider/api/network/profiles/$id
Method Get
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$id: Specifies the unique network profile identifier.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 334
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This property does not exist when you query for a single
profile.
nFirst, Previous, Next, and Last refer to corresponding
pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of the
objects returned in a pageable list. Each object contains the
following information:
n@type:
Specifies one of the following network profile type values:
nExternalNetworkProfile
nNATNetworkProfile
nRoutedNetworkProfile
n$id:
Specifies the unique network profile identifier.
n$name:
Specifies the network profile name.
ncreatedDate:
Specifies the date and time that the network profile was created.
nlastModifiedDate:
Specifies the date and time that the network profile was last
modified.
nisHidden:
Specifies if the network profile is hidden from the
vRealize Automation user interface.
ndefinedRanges:
Specifies the IP range array that is defined for the network
profile.
nprofileType:
Specifies the network profile type as one of the following types:
nEXTERNAL
nNAT
Programming Guide
VMware, Inc. 335
Parameter Description
nROUTED
nIPAMEndpointId
If you are querying an external network profile that uses external
IPAM, shows the endpoint ID for the external IPAM provider.
nsubnetMask:
Specifies the subnet mask.
ngatewayAddress:
Specifies the IP address of the network gateway.
nprimaryDnsAddress:
Specifies the IP address of the primary DNS server. This
parameter is only available for external, NAT, and routed
network profiles.
nsecondaryDnsAddress:
Specifies the IP address of a secondary DNS server. This
parameter is only available for external, NAT, and routed
network profiles.
ndnsSuffix:
Specifies the DNS suffix. This parameter is only available for
external, NAT, and routed network profiles.
ndnsSearchSuffix:
Specifies the DNS search suffix. This parameter is only
available for external, NAT, and routed network profiles.
nprimaryWinsAddress:
Specifies the IP address of the primary Wins server. This
parameter is only available for external, NAT, and routed
network profiles.
nsecondaryWinsAddress:
Specifies the IP address of secondary Wins server. This
parameter is only available for external, NAT, and routed
network profiles.
ndhcpStartIPAddress:
Specifies the start IP address of the DHCP server. This
parameter is only supported by NAT network profiles.
ndhcpEndIPAddress:
Specifies the end IP address of the DHCP server. This
parameter is only supported by NAT network profiles.
nleaseTimeInSeconds:
Specifies the lease time for the DHCP server. This parameter is
only supported by NAT network profiles.
nbaseIP:
Specifies the base IP address. This parameter is only supported
by routed network profiles.
Metadata Specifies the following paging-related data:
Programming Guide
VMware, Inc. 336
Parameter Description
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Example: curl Command
The following example command queries the existing network profile ID 68b6a183-fc8a-4592-
af23-92f8d410ee32.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/ iaas-proxy-provider/api/network/profiles/68b6a183-fc8a-4592-af23-92f8d410ee32
Example: JSON Output
The following JSON output is returned based on the command input.
{
"@type": "ExternalNetworkProfile",
"id": "68b6a183-fc8a-4592-af23-92f8d410ee32",
"name": "externalTest",
"description": "",
"createdDate": "2014-11-11T02:24:07.000Z",
"lastModifiedDate": "2014-11-11T02:24:07.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "3a85a049-522f-4b64-8f60-6e7b252ad204",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.200",
"endIPv4Address": "10.110.183.201",
"state": "UNALLOCATED",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z",
"definedAddresses": [
{
"id": "f229ea1a-18de-4dae-ae7b-0cec7feaa99b",
"name": null,
"description": null,
"IPv4Address": "10.110.183.201",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
Programming Guide
VMware, Inc. 337
{
"id": "cd39e786-6490-4c95-8cf7-d6e3b6a0ba67",
"name": null,
"description": null,
"IPv4Address": "10.110.183.200",
"IPSortValue": 0,
"state": "UNALLOCATED",
"hostName": "",
"createdDate": "2014-11-11T02:23:38.000Z",
"lastModifiedDate": "2014-11-11T02:23:38.000Z"
},
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
Update a Network Profile
You can use the vRealize Automation REST API to update an existing network profile.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the network profile ID to query. See Get a Network Profile List.
Procedure
uUpdate the network profile.
The following example command updates the network profile 263b80f5-d34f-47f2-
b0b1-5a3db991c2e9.
curl –X PUT --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/network/profiles/263b80f5-d34f-47f2-b0b1-5a3db991c2e9 -d “
{
"@type": "ExternalNetworkProfile",
"id": "263b80f5-d34f-47f2-b0b1-5a3db991c2e9",
Programming Guide
VMware, Inc. 338
"name": "externalTestEdit",
"description": "",
"createdDate": "2014-11-16T09:11:55.000Z",
"lastModifiedDate": "2014-11-16T09:11:55.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "ce266d4c-5fbb-47a9-a391-c77444c20b09",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.239",
"endIPv4Address": "10.110.183.240",
"state": "UNALLOCATED",
"createdDate": "2014-11-16T09:11:55.000Z",
"lastModifiedDate": "2014-11-16T09:11:55.000Z",
"definedAddresses": [
]
}
],
"profileType": "EXTERNAL",
"IPAMEndpointId": null,
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
“
The output contains an empty HTTP response body and the following status code.
204 No Content
Syntax for Updating a Network Profile
You can use the vRealize Automation IaaS proxy provider service REST API to update an existing
network profile.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/iaas-proxy-provider/api/network/profiles/$id
Method Put
Programming Guide
VMware, Inc. 339
Parameter Description
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains a status statement.
Parameter Description
status If the command is not successful, the HTTP status is 204 No
Content.
Example: curl Command
The following example command updates the network profile with an ID of 263b80f5-d34f-47f2-
b0b1-5a3db991c2e9.
curl –X PUT --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/iaas-proxy-provider/api/network/profiles/263b80f5-d34f-47f2-b0b1-5a3db991c2e9 -d “
{
"@type": "ExternalNetworkProfile",
"id": "263b80f5-d34f-47f2-b0b1-5a3db991c2e9",
"name": "externalTestEdit",
"description": "",
"createdDate": "2014-11-16T09:11:55.000Z",
"lastModifiedDate": "2014-11-16T09:11:55.000Z",
"isHidden": false,
"definedRanges": [
{
"id": "ce266d4c-5fbb-47a9-a391-c77444c20b09",
"name": "range",
"description": "",
"beginIPv4Address": "10.110.183.239",
"endIPv4Address": "10.110.183.240",
"state": "UNALLOCATED",
"createdDate": "2014-11-16T09:11:55.000Z",
"lastModifiedDate": "2014-11-16T09:11:55.000Z",
"definedAddresses": [
]
}
],
"profileType": "EXTERNAL",
"subnetMask": "255.255.255.0",
"gatewayAddress": "10.110.183.253",
"primaryDnsAddress": "10.110.182.45",
"secondaryDnsAddress": "",
"dnsSuffix": "mycompany.com",
"dnsSearchSuffix": "",
Programming Guide
VMware, Inc. 340
"primaryWinsAddress": "10.0.0.1",
"secondaryWinsAddress": ""
}
“
Example: JSON Output
The output contains an empty HTTP response body and the following status code.
204 No Content
Delete a Network Profile
You can use the vRealize Automation REST API network service to delete an existing network profile.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the network profile ID to delete. See Get a Network Profile List.
Procedure
uDelete the network profile.
The following example command deletes the network profile 263b80f5-d34f-47f2-
b0b1-5a3db991c2e9.
curl –X “Delete” --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/network/profiles/263b80f5-d34f-47f2-b0b1-5a3db991c2e9
The output contains an empty HTTP response body and the following status code.
204 No Content
Syntax for Deleting a Network Profile
You can use the vRealize Automation REST API to delete an existing network profile.
Input
Use the supported input parameters to control the command output.
Programming Guide
VMware, Inc. 341
Parameter Description
URL https://$host/iaas-proxy-provider/api/network/profiles/$id
Method Delete
$host Specifies the host name and fully qualified domain name or IP
address of the vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$id: Specifies the unique network profile identifier.
Output
The command output contains a status statement.
Parameter Description
status If the command is not successful, the HTTP status is 204 No
Content.
Example: curl Command
The following example command deletes a network profile with an ID of 263b80f5-d34f-47f2-
b0b1-5a3db991c2e9.
curl –X “Delete” --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/network/profiles/263b80f5-d34f-47f2-b0b1-5a3db991c2e9
Example: JSON Output
The output contains an empty HTTP response body and the following status code.
204 No Content
Get a List of Available IP Ranges for an IPAM Provider
You can query a specified IPAM provider endpoint for a list of the available IP address ranges configured
on the IPAM provider device.
Prerequisites
nLog in to vRealize Automation as a tenant administrator.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
nObtain the endpoint ID for the external IPAM provider device you want to query.
Programming Guide
VMware, Inc. 342
Procedure
uUse the following command to query an IPAM endpoint for a list of configured IP address ranges.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/ ipam-service/api/providers/<ENDPOINT_ID>/ip-ranges
where ENDPOINT_ID is the endpoint ID of the external IPAM service provider.
The following JSON output is returned based on the command input.
{
"links": [],
"content": [
{
"@type": "IPRange",
"id": null,
"name": "192.168.0.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 0"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.0.0",
"subnetPrefixLength": 24,
"externalId": "network-0",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
Programming Guide
VMware, Inc. 343
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.1.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 1"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.1.0",
"subnetPrefixLength": 24,
"externalId": "network-1",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.2.0/24",
Programming Guide
VMware, Inc. 344
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 2"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.2.0",
"subnetPrefixLength": 24,
"externalId": "network-2",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.3.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 3"
}
},
Programming Guide
VMware, Inc. 345
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.3.0",
"subnetPrefixLength": 24,
"externalId": "network-3",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.4.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 4"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
Programming Guide
VMware, Inc. 346
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.4.0",
"subnetPrefixLength": 24,
"externalId": "network-4",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.5.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 5"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.5.0",
"subnetPrefixLength": 24,
"externalId": "network-5",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
Programming Guide
VMware, Inc. 347
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.6.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 6"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.6.0",
"subnetPrefixLength": 24,
"externalId": "network-6",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
Programming Guide
VMware, Inc. 348
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.7.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 7"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.7.0",
"subnetPrefixLength": 24,
"externalId": "network-7",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.8.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
Programming Guide
VMware, Inc. 349
"value": {
"type": "string",
"value": "Building 8"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.8.0",
"subnetPrefixLength": 24,
"externalId": "network-8",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.9.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 9"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
Programming Guide
VMware, Inc. 350
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.9.0",
"subnetPrefixLength": 24,
"externalId": "network-9",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.10.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 10"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.10.0",
Programming Guide
VMware, Inc. 351
"subnetPrefixLength": 24,
"externalId": "network-10",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.11.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 11"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.11.0",
"subnetPrefixLength": 24,
"externalId": "network-11",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
Programming Guide
VMware, Inc. 352
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.12.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 12"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.12.0",
"subnetPrefixLength": 24,
"externalId": "network-12",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.13.0/24",
Programming Guide
VMware, Inc. 353
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 13"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.13.0",
"subnetPrefixLength": 24,
"externalId": "network-13",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.14.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 14"
}
},
Programming Guide
VMware, Inc. 354
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.14.0",
"subnetPrefixLength": 24,
"externalId": "network-14",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.15.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 15"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
Programming Guide
VMware, Inc. 355
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.15.0",
"subnetPrefixLength": 24,
"externalId": "network-15",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.16.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 16"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.16.0",
"subnetPrefixLength": 24,
"externalId": "network-16",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
Programming Guide
VMware, Inc. 356
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.17.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 17"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.17.0",
"subnetPrefixLength": 24,
"externalId": "network-17",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
Programming Guide
VMware, Inc. 357
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.18.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
"value": {
"type": "string",
"value": "Building 18"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Santa Clara"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.18.0",
"subnetPrefixLength": 24,
"externalId": "network-18",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
},
{
"@type": "IPRange",
"id": null,
"name": "192.168.19.0/24",
"description": "Created by vRO package stub workflow",
"extensionData": {
"entries": [
{
"key": "Building",
Programming Guide
VMware, Inc. 358
"value": {
"type": "string",
"value": "Building 19"
}
},
{
"key": "City",
"value": {
"type": "string",
"value": "Boston"
}
}
]
},
"providerEndpointId": "C20F305C-07A5-4BA7-88AC-35DA7B9713E0",
"providerEndpointURI": null,
"start": null,
"end": null,
"ipVersion": "IPv4",
"gateway": "192.168.19.0",
"subnetPrefixLength": 24,
"externalId": "network-19",
"dnsInfo": {
"@type": "DNSInfo",
"id": null,
"name": null,
"description": null,
"dnsSuffix": "sqa.local",
"primaryDNS": "",
"secondaryDNS": "",
"dnsSearchSuffixes": "search.sqa.local,search2.sqa.local",
"preferredWINS": "",
"alternateWINS": ""
},
"addressSpaceId": "default"
}
],
"metadata": {
"size": 0,
"totalElements": 20,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Import and Export Content
You can use the REST API content management service to import and export content, such as blueprints,
between vRealize Automation systems.
Programming Guide
VMware, Inc. 359
vRealize Automation customers often experiment with system artifacts such as catalog items, XaaS
services, resource actions, and IaaS blueprints in their development or staging environments. When
appropriate, users need to move these artifacts to their production environments.
Note You cannot import/export approval policies or entitlements. Also, you cannot import or export any
content that is in a draft state.
The examples herein are shown as Curl commands for consistency with other similar examples, though
the REST API content management service provides a convenient mechanism for moving such artifacts
between systems using the CloudClient interface. With CloudClient, there is no need to set heading
values, including the Authorization header. The $host//$servicename/api is eliminated from the URL
and the service name becomes a separate parameter. For example, consumer/entitled
CatalogItems/{id}/request/template. See Using vRealize CloudClient.
Some parameters on the API request are common to all content management service import and export
commands. These parameters are listed below.
Parameter Description
$host The host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token A valid HTTP bearer token that includes necessary credentials.
Note When exporting content, values of secure strings and encrypted properties are excluded by
default. You can add the --secure false parameter to commands to export these properties as plain
text with your content. Secure strings and encrypted properties are typically used as property holders for
passwords.
The following examples illustrate the types of requests that you might use in typical import export
situations.
Prerequisites
nLog in to vRealize Automation with an appropriate role. For example: Software Architect, Application
Architect, Infrastructure Architecture or some combination of these depending on the need.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that there is a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Programming Guide
VMware, Inc. 360
Procedure
1(Optional) Use the REST API content service to display a list of supported vRealize Automation
content types. Typically, this step is required only if you are not familiar with the content on your
system or if you need to verify the content.
A content type describes the content that you can import or export using the content management
service.
$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/provider/contenttypes
2Display a list of available content in vRealize Automation.
Content includes published artifacts such as blueprints, software, properties etc.
$curl --insecure -s -H"Content-Type: application/json" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/contents
3If applicable, you can also apply filtering by content type.
This example sets the contentTypeId to composite-blueprint.
$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/contents?
%24filter=contentTypeId+eq+%27composite-blueprint%27
4Create a package that contains the desired content.
The following command creates a package named Demo Package with a content ID of
9b348c29-88ff-4fa8-b93e-f80bc7c3e723.
$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/packages-d'{"name" : "Demo
Package", "description" : "Package for demo purposes", "contents" :
[ "9b348c29-88ff-4fa8-b93e-f80bc7c3e723" ]}'
5(Optional) List the packages within the content service. Use this step if you need to confirm the
contents of the package you created.
$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/packages
6Export the specified package as a .zip file.
The example specifies the Accept header as application/zip and the output file as package.zip.
$curl --insecure -s -H "Accept: application/zip"-H "Authorization: Bearer $token"
https://$host/content-management-
service/api/packages/54f627bb-2277-48af-9fa0-7d7366b498f3-o package.zip
Programming Guide
VMware, Inc. 361
7Validate the package prior to importing it.
The example uses the 'DukesBankApp.zip' which is out-of-box content provided on the
vRealize Automation virtual appliance. You can copy the file from /usr/lib/vcac/tools/initial-
config/sample-oob-content/DukesBankApp.zip using WinSCP (Windows) or scp (Mac).
$curl --insecure -s -H "Content-Type: multipart/form-data"-H "Authorization:
Bearer $token" https://$host/content-management-service/api/packages/validate-F"
file=@DukesBankApp.zip"
The validation output shows the status of each content item within the package.
8Import the package.
This example imports the DukesBankApp.zip package.
$curl --insecure -s -H "Content-Type: multipart/form-data"-H "Authorization:
Bearer $token" https://$host/content-management-service/api/packages-F"
file=@DukesBankApp.zip"
Syntax for Listing Supported Content Types
You can use the REST API content management service to display a list of supported content types.
Supported Content Types
A content type describes content that you can import or export using the content management service.
Content types contain metadata about the content provider and the content itself, such as type
information or service type ID. Usually the content provider supplies this information.
The REST API supports import and export of the following registered content types:
ncomposite-blueprint - the content type corresponding to the composite blueprint
nsoftware-component - the content type corresponding to the software component
nproperty-group - the content type corresponding to the property groups
nproperty-definition - the content type corresponding to the property definitions
Everything as a Service (XaaS) content types:
nXaaS-blueprint
nXaaS-resource-action
nXaaS-resource-type
nXaaS-resource-mapping
Input
Use the supported input parameters with your query URL to control command output. .
Programming Guide
VMware, Inc. 362
Name Description Type
page Page Number. Default is 1. Query
limit Number of entries per page. Default is 20. Query
$orderby Multiple comma-separated properties sorted in ascending or
descending order.
Query
$top The number of returned entries from the top of the response (total
number per page in relation to skip).
Query
$skip The number of entries to skip. Query
$filter Boolean expression for whether a particular entry should be
included in the response.
Query
Output
The command output contains property names and values based on the command input parameters.
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
nFirst, Previous, Next, and Last refer to
corresponding pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content nid: The unique identifier for the content. This is also used as
a folder name to group similar content artifacts.
nname: The name of a given content type provided in
localized message key form.
ndescription: Additional information describing the content
type.
nclassId: The class identifier associated with a content type.
nserviceTypeId: The service ID for the given content type.
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Programming Guide
VMware, Inc. 363
Example Curl Command
The following example command returns a list of supported content types.
$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/provider/contenttypes
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links": [
],
"content": [
{
"@type": "ContentType",
"id": "property-group",
"name": "Property Group",
"description": "Content type corresponding to the property groups.",
"classId": "PropertyGroup",
"serviceTypeId": "com.vmware.csp.core.properties.service"
},
{
"@type": "ContentType",
"id": "property-definition",
"name": "Property Definition",
"description": "Content type corresponding to the property definitions.",
"classId": "PropertyDefinition",
"serviceTypeId": "com.vmware.csp.core.properties.service"
},
{
"@type": "ContentType",
"id": "composite-blueprint",
"name": "Composite Blueprint Content Type",
"description": "The content type corresponding to the composite blueprint",
"classId": "Composite.Blueprint",
"serviceTypeId": "com.vmware.csp.component.cafe.composition"
},
{
"@type": "ContentType",
"id": "asd-blueprint",
"name": "{com.vmware.csp.core.designer.service@service.blueprint.content.type.name}",
"description":
"{com.vmware.csp.core.designer.service@service.blueprint.content.type.description}",
"classId": "asdServiceBlueprint",
"serviceTypeId": "com.vmware.csp.core.designer.service"
},
{
"@type": "ContentType",
"id": "asd-resource-action",
"name": "{com.vmware.csp.core.designer.service@resource.action.content.type.name}",
"description": "{com.vmware.csp.core.designer.service@resource.action.content.type.description}",
"classId": "asdResourceAction",
Programming Guide
VMware, Inc. 364
"serviceTypeId": "com.vmware.csp.core.designer.service"
},
{
"@type": "ContentType",
"id": "asd-resource-type",
"name": "{com.vmware.csp.core.designer.service@resource.type.content.type.name}",
"description": "{com.vmware.csp.core.designer.service@resource.type.content.type.description}",
"classId": "asdResourceType",
"serviceTypeId": "com.vmware.csp.core.designer.service"
},
{
"@type": "ContentType",
"id": "asd-resource-mapping",
"name": "{com.vmware.csp.core.designer.service@resource.mapping.content.type.name}",
"description":
"{com.vmware.csp.core.designer.service@resource.mapping.content.type.description}",
"classId": "asdResourceMapping",
"serviceTypeId": "com.vmware.csp.core.designer.service"
},
{
"@type": "ContentType",
"id": "software-component",
"name": "Software Component Content Type",
"description":
"{com.vmware.csp.component.software.service@software.component.content.type.description}",
"classId": "softwareComponentType",
"serviceTypeId": "com.vmware.csp.component.software.service"
}
],
"metadata": {
"size": 20,
"totalElements": 9,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Syntax for Listing Available Content
You can use the REST API content management service to list the content that is available for export on
your vRealize Automation deployment.
Listing Available Content
Content is some artifact, entity or information that provides value to a user in a specific context. Content
can be represented in a file in different formats, such as XML, JSON, or a package of files.
Input
Use the supported input parameters with your query URL to control command output.
Programming Guide
VMware, Inc. 365
Name Description Type
page Page Number. Default is 1. Query
limit Number of entries per page. Default is 20. Query
$orderby Multiple comma-separated properties sorted in ascending or
descending order.
Query
$top The number of returned entries from the top of the response (total
number per page in relation to skip).
Query
$skip The number of entries to skip. Query
$filter Boolean expression for whether a particular entry should be
included in the response.
Query
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 366
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
nFirst, Previous, Next, and Last refer to
corresponding pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content Specifies an array of data rows, each of which represents one of
the objects returned in a pageable list.
nid: Specifies the unique identifier for the content. This is also
used as a folder name to group similar content artifacts.
ncontentId: The human readable immutable user or provider
supplied content ID.
nname: Specifies the name of a given content type provided
in localized message key form.
ndescription: Specifies additional information describing the
package.
ncontentTypeId: Identifies the nature of the content.
nmimeType: Identifies the mime type.
ntenantId: The ID of the tenant associated with the package.
Used to enforce ownership.
nsubtenantId: (Optional) The ID of the sub tenant or business
group associated with the package.
ndependencies: Represents the dependencies of the content
unit in the form of content IDs.
ncreatedDate: The creation date of the content.
nlastUpdated: The date on which the content was last
updated.
nversion: The version identifier of the content.
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Programming Guide
VMware, Inc. 367
Example Curl Command
$curl --insecure -s -H "Content-Type: application/json"-H "Authorization: Bearer
$token" https://$host/content-management-service/api/contents
Example: JSON Output
{
"links": [],
"content": [
{
"@type": "Content",
"id": "6ba58cb4-257d-4833-b2dc-f090f92f86be",
"contentId": "3482e3a7-c6c2-4372-b8e1-0db517b93406",
"name": "Echo String",
"description": null,
"contentTypeId": "asd-blueprint",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T19:14:54.899Z",
"lastUpdated": "2015-08-18T19:14:54.899Z",
"version": 0
},
{
"@type": "Content",
"id": "079cc912-b870-4f56-a1c3-91905526b09d",
"contentId": "NicksBP",
"name": "Nick's BP",
"description": "Nick's BP",
"contentTypeId": "composite-blueprint",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T20:14:57.299Z",
"lastUpdated": "2015-08-18T20:14:57.299Z",
"version": 0
},
{
"@type": "Content",
"id": "9795e97f-7025-44f9-9a57-f59242a7775d",
"contentId": "de81f329-cb72-4099-b831-309db708833b",
"name": "TestMapping",
"description": null,
"contentTypeId": "asd-resource-mapping",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T20:53:25.062Z",
"lastUpdated": "2015-08-18T20:53:25.062Z",
Programming Guide
VMware, Inc. 368
"version": 0
},
{
"@type": "Content",
"id": "3922fda1-b5fd-4c51-997d-5f803ec6fb6e",
"contentId": "e8ae6093-18a9-4ec9-a415-1ef850f243f9",
"name": "CustomRes",
"description": null,
"contentTypeId": "asd-resource-type",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T20:56:11.052Z",
"lastUpdated": "2015-08-18T20:56:11.052Z",
"version": 0
},
{
"@type": "Content",
"id": "4754ad69-a6a7-447f-96de-2ed6fa260f7c",
"contentId": "Software.Apache_LB",
"name": "Apache_LB",
"description": "Apache 2.2 The Apache HTTP Server is an open-source HTTP server for modern
operating systems including UNIX, Microsoft Windows, Mac OS/X and Netware. The goal of this project is
to provide a secure, efficient and extensible server that provides HTTP services observing the current
HTTP standards. Apache has been the most popular web server on the Internet since April of 1996.",
"contentTypeId": "software-component",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-18T21:31:43.094Z",
"lastUpdated": "2015-08-18T21:31:44.133Z",
"version": 1
},
{
Syntax for Filtering Content by Content Type
You can use the REST API content management service to filter a list of returned content type items.
Input
Output
The command output contains property names and values based on the command input parameters.
Example Curl Command
$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/contents?
%24filter=contentTypeId+eq+%27composite-blueprint%27
Programming Guide
VMware, Inc. 369
Example: JSON Output
In this example the returned IDs correspond to composite blueprints that meet the filtering criteria.
{
"links": [],
"content": [
{
"@type": "Content",
"id": "9b348c29-88ff-4fa8-b93e-f80bc7c3e723",
"contentId": "vSphere",
"name": "vSphere",
"description": "vSphere",
"contentTypeId": "composite-blueprint",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [],
"createdDate": "2015-08-04T14:46:54.201Z",
"lastUpdated": "2015-08-04T16:59:30.488Z",
"version": 1
},
{
"@type": "Content",
"id": "968ae331-1ef2-44f8-bdc5-dfc2be78ca2f",
"contentId": "Amazon",
"name": "Amazon",
"description": "Amazon",
"contentTypeId": "composite-blueprint",
"mimeType": null,
"tenantId": "qe",
"subtenantId": null,
"dependencies": [
"9e2005c3-c56e-48d0-801c-be36851f2b08"
],
"createdDate": "2015-08-04T20:47:20.308Z",
"lastUpdated": "2015-08-04T20:47:20.308Z",
"version": 0
}
],
"metadata": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Programming Guide
VMware, Inc. 370
Syntax for Creating a Package for Export
You can use the REST API content management service to create a package that contains content for
export use.
Creating a Package with Content
nFor import or export purposes you must create a package to contain the desired content.
nThe package is a logical unit that enables you to piece together different content elements.
nYou can add multiple content IDs to the package.
A package represents an entity that you can export or import via the content management service. A set
of references to the content instances can be bundled together as a package.
Input
Parameter Description
createdDate The package creation date.
lastUpdated The date when the package was last updated.
version The package version identifier.
tenantId The ID of the tenant associated with the package. Used to
enforce ownership.
subTenantId (Optional) The ID of the sub tenant or business group
associated with the package
id Specifies the unique identifier for the content. This is also used
as a folder name to group similar content artifacts.
name Specifies the name of a given content type provided in localized
message key form.
description Specifies additional information describing the package.
contents Collection of references that form the contents of the package.
Output
The command output contains property names and values based on the command input parameters.
Parameter Description
createdDate The package creation date.
lastUpdated The date when the package was last updated.
version The package version identifier.
tenantId The ID of the tenant associated with the package. Used to
enforce ownership.
subTenantId (Optional) The ID of the sub tenant or business group
associated with the package
Programming Guide
VMware, Inc. 371
Parameter Description
id Specifies the unique identifier for the content. This is also used
as a folder name to group similar content artifacts.
name Specifies the name of a given content type provided in localized
message key form.
description Specifies additional information describing the package.
contents Collection of references that form the contents of the package.
Example Curl Command
The following command creates a package named "Demo Package" with a content ID of
9b348c29-88ff-4fa8-b93e-f80bc7c3e723.
$curl --insecure -s -H "Content-Type: application/json" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/packages-d'{"name" : "Demo
Package", "description" : "Package for demo purposes", "contents" :
[ "9b348c29-88ff-4fa8-b93e-f80bc7c3e723" ]}'
Example: JSON Output
The JSON output is a URL for the created package.
Syntax for Listing Packages in the Content Service
You can use the REST API content management service to list the packages within the content service.
Input
You must provide the appropriate request parameters to list packages within the content service.
Name Description Type
page Page Number. Default is 1. Query
limit Number of entries per page. Default is 20. Query
$orderby Multiple comma-separated properties sorted in ascending or
descending order.
Query
$top The number of returned entries from the top of the response (total
number per page in relation to skip).
Query
$skip The number of entries to skip. Query
$filter Boolean expression for whether a particular entry should be
included in the response.
Query
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 372
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
nrel
Specifies the name of the link.
nSelf refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
nFirst, Previous, Next, and Last refer to
corresponding pages of pageable lists.
nSpecifies the application or service that determines the
other names.
nhref
Specifies the URL that produces the result.
Content ncreatedDate: The creation date of the content.
nlastUpdated: The date on which the content was last
updated.
nversion: The version identifier of the content.
nid: Specifies the unique identifier for the content. This is also
used as a folder name to group similar content artifacts.
ncontentId: The human readable immutable user or provider
supplied content ID.
nname: Specifies the name of a given content type provided
in localized message key form.
ndescription: Specifies additional information describing the
package.
ncontentTypeId: The unique identifier of the contentType.
nmimeType: The mime type file identifier.
ntenantId: The ID of the tenant associated with the package.
Used to enforce ownership.
nsubtenantId: (Optional) The ID of the sub tenant or business
group associated with the package.
ndependencies: These represent the content unit
dependencies in the form of content IDs.
Metadata Specifies the following paging-related data:
nSize: Specifies the maximum number of rows per page.
ntotalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
ntotalPages: Specifies the total number of pages of data
available.
nNumber: Specifies the current page number.
nOffset: Specifies the number of rows skipped.
Example Curl Command
$curl --insecure -s -H"Content-Type: application/json"-H"Authorization: Bearer
$token"https://$host/content-management-service/api/packages
Programming Guide
VMware, Inc. 373
Example: JSON Output
The following example lists all packages within the content service.
{
"links": [
],
"content": [
{
"@type": "Package",
"createdDate": "2015-08-04T22:22:53.490Z",
"lastUpdated": "2015-08-04T22:22:53.490Z",
"version": 0,
"id": "54f627bb-2277-48af-9fa0-7d7366b498f3",
"name": "Demo Package",
"description": "Package for demo purposes",
"contents": [
"9b348c29-88ff-4fa8-b93e-f80bc7c3e723"
],
"tenantId": "qe",
"subTenantId": null
}
],
"metadata": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Syntax for Exporting a Package
You can use the REST API content management service to export a package containing content as a .zip
file.
Input
The query URL for the export command must specify the ID of the package to export.
Table 3‑17. Export Query URL Parameters
Name Description Type
id The identifier of the package Path
secureValueFormat The format in which secure values should be sent. This
parameter is optional and defaults to "BLANKOUT".
Query
Output
The output of this command is a .zip file.
Programming Guide
VMware, Inc. 374
Example Curl Command
$curl --insecure -s -H "Accept: application/zip" -H "Authorization: Bearer $token"
https://$host/content-management-
service/api/packages/54f627bb-2277-48af-9fa0-7d7366b498f3-o package.zip
Example: Example: JSON Output
The export command returns a message that indicates whether or not the package was exported. A
successful export produces a package.zip exported to the specified location. The returned message is
'200 - Successes' with the Package or 404 - 'Not Found' if it does not find a package with
provided ID.
Syntax for Validating a Content Bundle Before Importing
You can use the REST API content management service to validate a content bundle before importing to
a critical system. VMware recommends that you validate all packages before importing them to any
system.
Input
You can use optional request parameters with your query URL to customize the returned content.
Table 3‑18. Package Validation Parameters
Name Description Type
file The name of the package file to be validated query
resolution mode The resolution mode to be used for performing validation when the
same entity exists in the system. Valid values are SKIP,
OVERWRITE. SKIP will not update the existing entity with the new
content while OVERWRITE will update the old entity with the new
data. In case the resolution mode is not explicitly provided the
default mode OVERWRITE will be used for conflict resolution.
query
Output
The package validation response body contains the following parameters.
Programming Guide
VMware, Inc. 375
Table 3‑19. Import and Export Response Body Parameters
Parameter Description
contentImportStatus Over all status of the import/validation operation, one failure in import/validation result
guarantees failed status. Values are as follows:
nSuccess - Denotes the successful import or validation status at a particular component or
package level.
nFailed - Denotes an import or validation failure at a particular component package level.
nWarning - Denotes a scenario that warrants a system level warning. Alerts the user about a
possible error condition that the proposed action may create.
contentImportResults Set of collected content import/validation results populated by the provider. The Content import
operation result collection is the set of content that passed or failed. If failed the errors are
populated in ContentImportError. Properties are as follows:
ncontentId - (string) Unique content ID within the file system.
ncontentName - (anyType) Name of the content being imported.
ncontentTypeId - (string) The ID for the content type being exported. This matches the folder
structure in the exported zip.
ncontentImportStatus - Track the failed or succeeded status of an entity.
nmessages - Information returned by the provider.
ncontentImportErrors - Set of errors returned by the provider.
Example Curl Command
This example uses the 'DukesBankApp.zip' - which is out-of-the-box content provided on the
vRealize Automation virtual appliance. You can copy the file from /usr/lib/vcac/tools/initial-
config/sample-oob-content/DukesBankApp.zip using WinSCP (Windows) or scp (Mac).
$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/packages/validate -F
"file=@DukesBankApp.zip"
Example: JSON Output
The validation output displays the validation status of each content item within the bundle.
{
"contentImportStatus": "SUCCESS",
"contentImportResults": [
{
"contentId": "Apache_LB",
"contentName": "Apache_LB",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "MySql",
"contentName": "MySql",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
Programming Guide
VMware, Inc. 376
},
{
"contentId": "JBossAppServer",
"contentName": "JBossAppServer",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "Dukes-Bank-DB-setup",
"contentName": "Dukes-Bank-DB-setup",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "Dukes_Bank_App",
"contentName": "Dukes_Bank_App",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "DukesBankApplication",
"contentName": "DukesBankApplication",
"contentTypeId": "composite-blueprint",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
}
]
}
Syntax for Importing a Package
You can use the REST API content management service to import a package containing content as a .zip
file.
Import a Package
To verify success of a package import, use vRealize Automation to view the imported items on the target
system.
Output
The command output contains property names and values based on the command input parameters.
Programming Guide
VMware, Inc. 377
Table 3‑20. Import and Export Response Body Parameters
Parameter Description
contentImportStatus Over all status of the import/validation operation, one failure in import/validation result
guarantees failed status. Values are as follows:
nSuccess - Denotes the successful import or validation status at a particular component or
package level.
nFailed - Denotes an import or validation failure at a particular component package level.
nWarning - Denotes a scenario that warrants a system level warning. Alerts the user about a
possible error condition that the proposed action may create.
contentImportResults Set of collected content import/validation results populated by the provider. The Content import
operation result collection is the set of content that passed or failed. If failed the errors are
populated in ContentImportError. Properties are as follows:
ncontentId - (string) Unique content ID within the file system.
ncontentName - (anyType) Name of the content being imported.
ncontentTypeId - (string) The ID for the content type being exported. This matches the folder
structure in the exported zip.
ncontentImportStatus - Track the failed or succeeded status of an entity.
nmessages - Information returned by the provider.
ncontentImportErrors - Set of errors returned by the provider.
Example Curl Command
$curl --insecure -s -H "Content-Type: multipart/form-data" -H "Authorization: Bearer
$token" https://$host/content-management-service/api/packages -F
"file=@DukesBankApp.zip"
Example: JSON Output
{
"contentImportStatus": "SUCCESS",
"contentImportResults": [
{
"contentId": "Apache_LB",
"contentName": "Apache_LB",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "MySql",
"contentName": "MySql",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "JBossAppServer",
"contentName": "JBossAppServer",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
Programming Guide
VMware, Inc. 378
"contentImportErrors": null
},
{
"contentId": "Dukes-Bank-DB-setup",
"contentName": "Dukes-Bank-DB-setup",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "Dukes_Bank_App",
"contentName": "Dukes_Bank_App",
"contentTypeId": "software-component",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
},
{
"contentId": "DukesBankApplication",
"contentName": "DukesBankApplication",
"contentTypeId": "composite-blueprint",
"contentImportStatus": "SUCCESS",
"contentImportErrors": null
}
]
}
Understanding Blueprint Schema
Users who wish to edit blueprints when exporting them to a deployment may need to understand the
blueprint schema.
Simple Blueprint Structure
The following is an example of a simple blueprint. Note that this example includes line number that are
referenced later in this topic.
1 id: Blueprint.CentOSAndApache
2. name: CentOSAndApache
3. status: PUBLISHED
4. components:
5. web:
6. type: Infrastructure.CatalogItem.Machine.Virtual.vSphere
7. data:
8. cpu: 1
9. memory:
10. min: 512
11. max: 8192
12. os_type: Linux
13. os_distribution: rhel
14. action: LinkedClone
15. archive_days: 1
16. provisioning_workflow: {id: CloneWorkflow}
17. lease_days: 3
Programming Guide
VMware, Inc. 379
18. source_machine_name: cbp_centos_63_x86
19. cost_center: sales
20. _cluster: 2
21. apache:
22. type: Software.Apache
23. data:
24. host: '${_resource~web}'
25. http_port: 8080
Each of these lines plays an important role in the blueprint structure.
nLines 1 - 4 represent possible top level blueprint fields that provide identifying information. The only
other possible field is description. The semantics of these fields is straightforward, but you can
refer to java.classBlueprintDocument for more information.
nLine 4 represents the blueprint components. Each key under components is the ID of the component
that must be unique under the current blueprint.
nLines 5 - 19 correspond to the Web component. The following appear under any component data:
nThe key type is mandatory and must refer to the component type on which the current
component is based.
nThe key dependsOn is optional and contains the list of component IDs current component
depends on. Component dependencies are extracted automatically based on property binding
expressions. In most cases, you do not need to explicitly specify component dependencies.
nThe key data defines the component configuration and appears under all component data.
nKey is the name of the property or field of that component. This can be a property defined in
the corresponding component type.
Property or field option Example
A property defined in the corresponding component type cpu
A reserved property _cluster
Custom property cost_center
nThe value of the field can be directly defined as in cpu: 2, or you can defines its constraints,
as done for the memory field in the example.
nLine 16 shows how to specify and entity reference field. The available sub-keys are id and label.
nLine 24 depicts several things.
n${<field_path>} provides a way to express the value of a field to come from another field.
n_resource is a reserved field ID that captures the output of entire blueprint. Output from each
component is exposed under the same key as component ID. So in this case, host value is set to
the output of the web component thus saying the apache component needs to be hosted on
machine provisioned from the web component.
nWhenever a property binding refers to output of some other component, it creates an implicit
dependency between components.
Programming Guide
VMware, Inc. 380
Available Constraints
To define constraints in any blueprint field. create a new hierarchy or level in YAML, and use any of the
keys below to define constraints and their values.
Table 3‑21. Blueprint Constraints
ID or Key Corresponding CAFE Constraint Description
default com.vmware.vcac.platform.content.facets.DefaultValueBehav
ior
Specifies the value for a field.
fixed com.vmware.vcac.platform.content.facets.FixedValueConstrai
nt
Specifies the value for a field that cannot
be overridden at request or reuse time.
mandatory com.vmware.vcac.platform.content.facets.MandatoryConstrai
nt
Indicates that the field is mandatory.
min com.vmware.vcac.platform.content.facets.MinValueConstraint Indicates the minimum value for a numeric
field.
max com.vmware.vcac.platform.content.facets.MaxValueConstrain
t
Indicates the maximum value for a
numeric field.
minLength com.vmware.vcac.platform.content.facets.MinLengthConstrai
nt
Indicates the minimum length for a string
field.
maxLength com.vmware.vcac.platform.content.facets.MaxLengthConstra
int
Indicates the maximum length for a string
field.
minCardinality com.vmware.vcac.platform.content.facets.MinLengthConstrai
nt
Indicates the minimum cardinality for an
array field.
maxCardinality com.vmware.vcac.platform.content.facets.MaxCardinalityCon
straint
Indicates the maximum cardinality for an
array field.
increment com.vmware.vcac.platform.content.facets.IncrementBehavior Indicates the step or increment for a
numeric field.
regex com.vmware.vcac.platform.content.facets.RegexpConstraint Indicates the valid regex for a string field.
secured com.vmware.vcac.platform.content.facets.EncryptedBehavior Indicates whether the field is to be treated
securely.
valid_values com.vmware.vcac.platform.content.fields.PermissibleValueLis
t
Defines the valid values for a field.
Manage XaaS Content with Import and Export
You can use the content management service to import and export everything as a service (XaaS)
content.
XaaS is integrated with the API content management service, and all commands that work with other
content types also work with XaaS content. Though the XaaS functionality is being deprecated in the
vRealize Automation 7.0 release, it is still available for users to migrate XaaS content into
vRealize Automation 7.0.
Programming Guide
VMware, Inc. 381
Prerequisites
nLog in to vRealize Automation with an appropriate role. For example: Software Architect, Application
Architect, Infrastructure Architecture or some combination of these depending on the need.
nVerify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
nVerify that there is a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
1Use the following command to import a 6.2.x package into vRealize Automation 7.0.
curl --insecure -X POST -H"Authorization: Bearer $token"-H"Content-Type:
multipart/form-data"-F"file=@XaaSContent.zip"-F"prefix=prefix_"-
F"prefixOnlyConflicting=true"' https://$host/advanced-designer-
service/api/content/bundles'
2Use the following command to export an XaaS package as a .zip file.
curl -X PUT -H"Authorization: Bearer $token"-H"Content-Type: application/json"-
d'{"jsonAccepted" : true, "tenantId" : "qe", "data" : [] }''
https://$host/advanced-designer-service/api/content/bundles/filters'
Export XaaS Content
You can use the REST API content management service to export a package containing content as a .zip
file.
Input
Table 3‑22. XaaS Import Input Parameters
Name Parameter
tenantId Identifies the tenant associated with the export package.
data Information about the export package. Includes the following:
nentityType
nid
jsonAccepted Valid values are true or false.
Output
Example Curl Command
The following command exports a package containing content as a .zip file at the specified location.
curl -X PUT -H "Authorization: Bearer $token"-H"Content-Type: application/json"-
d'{"jsonAccepted" : true, "tenantId" : "qe", "data" : [] }'' https://$host/advanced-
designer-service/api/content/bundles/filters'
Programming Guide
VMware, Inc. 382
Example: JSON Output
The output of a successful export command is a .zip file at the specified location.
Import XaaS Content
You can use the content management service to import an XaaS content bundle.
Input
Table 3‑23. XaaS Import Input Parameters
Name Parameter
file Identifies the .zip file that is the content bundle to import.
prefix The prefix to use with imported objects. Ensures avoidance of a duplicate name failure.
prefixOnlyConflicting Set to true to rename or prefix conflicting objects.
Output
The command output contains property names and values based on the command input parameters.
Table 3‑24. Import and Export Response Body Parameters
Parameter Description
importStatus Over all status of the import/validation operation, one failure in import/validation result
guarantees failed status. Values are as follows:
nSuccessful - Denotes the successful import or validation status at a particular component or
package level.
nPartial - Denotes a scenario that warrants a system level warning. Alerts the user about a
possible error condition that the proposed action may create.
nFailed - Denotes an import or validation failure at a particular component package level.
data Set of collected content import/validation results populated by the provider. The Content import
operation result collection is the set of content that passed or failed:
nentityType - (string) The ID for the entity being imported.
nentitytId - (string) Unique content ID within the file system.
nmessageKey - (string)
nlogLevel - The logging level to use for any errors that occur.
nmessage - Information returned by the provider.
nentityName - (anyType) Name of the entity being imported.
Example Curl Command
The following command imports a file called XaaSContent.zip.
curl --insecure -X POST -H"Authorization: Bearer $token"-H"Content-Type:
multipart/form-data"-F"file=@XaaSContent.zip"-F"prefix=prefix_"-
F"prefixOnlyConflicting=true"' https://$host/advanced-designer-
service/api/content/bundles'
Programming Guide
VMware, Inc. 383
Example: JSON Output
The output of the command is a message indicating the status and details of the import operation.
{
"importStatus" : "SUCCESSFUL",
"data" : [ {
"logLevel" : "INFO",
"entityType" : "com.vmware.vcac.designer.service.domain.ServiceBlueprint",
"entityId" : "4740aa54-61e6-47d7-945f-0bb50ff153c8",
"entityName" : "XaaSBlueprint",
"messageKey" : "import.blueprint.success",
"message" : "Success"
} ]
}
Programming Guide
VMware, Inc. 384
Related Tools and
Documentation 4
In addition to the provided use case code snippets, you can expand your options for working with the
vRealize Automation REST API by using related tools and documentation.
You can use the vRealize CloudClient to simplify your interaction with the vRealize Automation REST
API. You can also use third party tools such as Chrome Developer Tools or Firebug to further expand your
vRealize Automation REST API programming options.
For a complete list and description of available vRealize Automation REST API service calls and their
usage, see the Swagger documentation for the product.
This chapter includes the following topics:
nUsing the vRealize Automation API Reference
nView Reference Information for an API
nUsing vRealize CloudClient
nUsing Third Party Tools
Using the vRealize Automation API Reference
The vRealize Automation API Reference describes all the available vRealize Automation REST API
services calls that you can use to configure and manage vRealize Automation programmatically.
To use the vRealize Automation REST API service reference documentation effectively, you must know
which service and resource to use. See Chapter 1 Overview of the vRealize Automation REST API for a
complete list of services and their descriptions. If you need more information, click one of the linked
service topics for a detailed description of the service and a list of the tasks that you can perform with it.
While the Programming Guide contains frequently used use cases, it does not document all the available
service calls and tasks. For a complete description of all the available vRealize Automation REST API
services, see the vRealize Automation API Reference, which contains a menu that lists the
vRealize Automation services and allows you to select documentation for each service. The vRealize
Automation API Reference is available at the following locations:
nIn your running vRealize Automation installation at the following URL:
https://$host/component-registry/services/docs
The $host denotes the host name of the machine where vRealize Automation is installed.
VMware, Inc. 385
nAs a zip file on the Product Documentation and Related Information page of the vRealize Automation
Information Center.
nIn the Developer Resources section of the vRealize Automation Information Center.
For information about requesting a bearer token, and about available pagination, sorting, and filtering
options for any given command, see the Tips option on the vRealize Automation API landing page for the
selected service API.
View Reference Information for an API
Using the vRealize Automation API Reference, you can view reference information for the REST APIs in
each vRealize Automation service, including parameter values, return codes, and implementaton notes.
You can choose the category for a specified REST API and view reference information about the APIs
included in the category.
Procedure
1From the pull-down menu on the vRealize Automation API Reference start page, select a service.
The Swagger documentation page for the service appears. The bottom of the page lists the API
categories included in the service.
2Scroll down to the bottom of the web page and select a category.
The HTTP operations in the category appear.
3Click an operation to view the reference information.
Reference information for the selected API appears.
4To display a list of the operations for a category , click List Operations next to a category name.
5To show the complete reference information for all of the operations in a category, click Expand
Operations next to a category name.
Detailed reference information for all of the operations in the category appears.
6To toggle on or off the display of reference information for the operations in a category, click
Show/Hide.
Using vRealize CloudClient
vRealize CloudClient is a separate command-line utility that provides a unified interface for working with
the vRealize Automation APIs.
For information about vRealize CloudClient, see the VMware Developer site at
https://developercenter.vmware.com/tool/cloudclient.
Programming Guide
VMware, Inc. 386
Using Third Party Tools
You can use third party tools such as Chrome Developer Tools or Firebug to reveal the data that you can
then use to construct a vRealize Automation REST API service call.
You can adapt these steps to perform a different action, such as adding a tenant.
Prerequisites
This example shows how you might use the Chrome Developer Tools to perform a catalog service query.
This option is not available for all vRealize Automation functions.
nOpen a Chrome browser session and log in to the vRealize Automation console as a business group
user with access to catalog items.
nOpen a command prompt or a shell and log in to the vRealize Automation command line interface.
Procedure
1Click the Catalog tab in the vRealize Automation console.
2Click the catalog Item you want to request.
3Enter the request information for the catalog item, but do not submit your changes.
4Press the Ctrl-Shift-I keys simultaneously to open the Chrome Developer Tools. For example:
a Click the Network tab.
b Click Record Network Log.
c Click Submit in the console.
5Verify that the network logs in the Chrome Developer Tools contain the relevant data. For example:
a Locate a makeRequest POST in the network recordings.
b Click makeRequest POST to view its details.
c Scroll to view the Form Data url and postData sections.
The url section shows the vRealize Automation service and URI for you to use. This example uses
the catalog-service, under the uri consumer/requests.
The postData section shows the JSON data passed in the HTTP POST call. You can insert the
JSON data in a JSON file, for example request.json, and submit it with the POST method in the
command line.
Note Click Clear to purge the network logs if they become too large to navigate easily.
Programming Guide
VMware, Inc. 387
6Enter the following call in the vRealize Automation shell, where the request.json text file contains
the JSON data from the postData section.
rest post --headers --service catalog-service --uri consumer/requests --data request.json
This call makes the same request that was submitted by using the console.
Programming Guide
VMware, Inc. 388
Filtering and Formatting REST
API Information 5
You can filter and format your vRealize Automation REST API command line and command line output.
You can use filters in your command line to limit JSON output to specific conditions. For example, you can
use a filter in a catalog item request to display only catalog items that contain a specific catalog ID. Or
you can use the requestID resource call to format the output of a command that displays request status.
You can also use an Odata equivalent to format that same information For details, see Syntax for Getting
Information for a Catalog Item.
Note You must URL encode all filter parameters when using Curl commands.
You can also reduce command line errors by using a JSON formatter to validate the JSON data and
present it in an easy-to-read format.
You can use command line options or JSON formatting tools, such as Open Data Protocol (OData), to
control the JSON results of your vRealize Automation REST API commands.
To simplify your JSON output, consider using command line options or a to filter out unnecessary data
and display only the information that you are interested in, such as the following information categories:
nPublished catalog items
nRequest status
nProvisioned machine identifiers
For information about requesting a bearer token, and about available pagination, sorting, and filtering
options for any given command, see the Tips option on the vRealize Automation API landing page for the
selected service API.
VMware, Inc. 389

Navigation menu