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 
.
Page Count: 389
| Download | |
| Open PDF In Browser | View PDF |
Programming Guide
vRealize Automation 7.1
Programming Guide
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
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
Copyright © 2008–2016 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc.
2
Contents
vRealize Automation Programming Guide
6
1 Overview of the vRealize Automation REST API 7
2 REST API Authentication 10
Using HTTP Bearer Tokens
10
Configure the Duration of an HTTP Bearer Token
Request an HTTP Bearer Token
11
Validate an HTTP Bearer Token
14
Delete an HTTP Bearer Token
10
14
3 REST API Use Cases 16
Create a Tenant
17
Syntax for Displaying Your Current Tenants
Syntax for Requesting a New Tenant
20
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
Syntax for Assigning a User to a Role
35
Syntax for Displaying all Roles Assigned to a User
Request a Machine
33
36
38
Syntax for Listing Shared and Private Catalog Items
Syntax for Getting Information for a Catalog Item
40
43
Syntax for Getting a Template Request for a Catalog Item
Syntax for Requesting a Machine
51
Syntax for Viewing Details of a Machine Request
Approve a Machine Request
47
54
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
Syntax for Approving a Submitted Machine Request
Syntax for Updating Cost Information
List Provisioned Resources
69
73
75
78
Syntax for Displaying Your Provisioned Resources
79
Syntax for Displaying Provisioned Resources by Resource Type
Syntax for Displaying All Available Resource Types
81
84
Syntax for Displaying Provisioned Resources by Business Groups You Manage
Syntax for Viewing Machine Details
VMware, Inc.
86
93
3
Programming Guide
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
Working with Reservations
Create a Reservation
112
113
Display a List of Reservations
Update a Reservation
Delete a Reservation
263
274
283
Working with Reservation Policies
List Reservation Policies
285
285
Create a Reservation Policy
288
Display a Reservation Policy by ID
Update a Reservation Policy
Get a Key Pair List
296
301
Query a Key Pair
304
Delete a Key Pair
294
296
Create a Key Pair
Update a Key Pair
290
292
Delete a Reservation Policy
Working with Key Pairs
111
305
308
Working with Network Profiles
Get a Network Profile List
310
311
Create a Network Profile
327
Query a Network Profile
332
Update a Network Profile
Delete a Network Profile
338
341
Get a List of Available IP Ranges for an IPAM Provider
Import and Export Content
342
359
Syntax for Listing Supported Content Types
Syntax for Listing Available Content
362
365
Syntax for Filtering Content by Content Type
Syntax for Creating a Package for Export
369
371
Syntax for Listing Packages in the Content Service
Syntax for Exporting a Package
372
374
Syntax for Validating a Content Bundle Before Importing
Syntax for Importing a Package
Understanding Blueprint Schema
377
379
Manage XaaS Content with Import and Export
VMware, Inc.
375
381
4
Programming Guide
4 Related Tools and Documentation 385
Using the vRealize Automation API Reference
View Reference Information for an API
Using vRealize CloudClient
Using Third Party Tools
385
386
386
387
5 Filtering and Formatting REST API Information 389
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
Programming Guide
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.
VMware, Inc.
8
Programming Guide
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.
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
Programming Guide
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
n
Log in to the vRealize Automation appliance with SSH as root. The password is the one you specified
when you deployed the appliance.
n
The /etc/vcac/security.properties file on the appliance must be editable.
Procedure
1
Open the /etc/vcac/security.properties file for editing.
2
Add 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.
3
Save and close the file.
4
Log 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
n
Log in to vRealize Automation using the applicable credentials. For example, to assign a user to a
role, log in as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc.
11
Programming Guide
Procedure
u
Enter 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.
VMware, Inc.
12
Programming Guide
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.
VMware, Inc.
13
Programming Guide
Validate an HTTP Bearer Token
You can validate an existing HTTP bearer token.
Prerequisites
n
Request an HTTP Bearer Token.
Procedure
u
Create 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
n
Request an HTTP Bearer Token.
Procedure
u
Create 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.
VMware, Inc.
14
Programming Guide
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.
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.
n
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.
n
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.
n
Approve a Machine Request
You can use a sequence of REST API workitem service commands to approve a machine request.
n
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 .
n
Manage Provisioned Deployments
You can use the REST API catalog service to log in to vRealize Automation and view information
about provisioned resources .
n
Working 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
Programming Guide
n
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.
n
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.
n
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.
n
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.
n
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.
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
n
Log in to vRealize Automation as a system administrator and a tenant administrator.
n
Verify that there is access to a functional LDAP, Active Directory, or Native Active Directory identity
server.
n
Verify that the identity server details required for the JSON template are available.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
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.
n
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.
VMware, Inc.
17
Programming Guide
n
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.
n
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.
n
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.
n
Syntax for Assigning a User to a Role
You can use the REST API identity service to assign a user to a role.
n
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.
Procedure
1
Use the identity service to display all the available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
2
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",
VMware, Inc.
18
Programming Guide
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
Examples
Example 1
Call the above newTenant.json file,
which contains parameters for the
tenant request.
Example 2
Specify the parameters for the tenant
request by using inline text.
3
Command
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/development --data
@C:\Temp\newTenant.json
curl --insecure -H "Accept: application/json" -H "ContentType: 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}'
List 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
4
Link 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",
VMware, Inc.
19
Programming Guide
"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
5
Query 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
6
Assign 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 "{}"
7
Display 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.
VMware, Inc.
20
Programming Guide
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.
VMware, Inc.
21
Programming Guide
Parameter
Description
Links
Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
n
Specifies 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. Each tenant object
can contain the following information:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
n
Name:
Specifies the name of the tenant as it appears in URLs.
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
n
Password:
Specifies the primary contact email address.
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata
VMware, Inc.
Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
22
Programming Guide
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.
VMware, Inc.
23
Programming Guide
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.
VMware, Inc.
24
Programming Guide
Parameter
Description
Links
Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
n
Specifies 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. Each tenant object
can contain the following information:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
n
Name:
Specifies the name of the tenant as it appears in URLs.
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
n
Password:
Specifies the primary contact email address.
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata
VMware, Inc.
Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
25
Programming Guide
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.
VMware, Inc.
26
Programming Guide
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:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
n
Specifies 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. Each tenant object
can contain the following information:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
n
Name:
Specifies the name of the tenant as it appears in URLs.
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
n
Password:
Specifies the primary contact email address.
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata
VMware, Inc.
Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
27
Programming Guide
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,
VMware, Inc.
28
Programming Guide
"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:
n
LDAP
n
AD
n
NATIVE_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",
VMware, Inc.
29
Programming Guide
"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.
VMware, Inc.
30
Programming Guide
Parameter
Description
Links
Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
n
Specifies 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. Each tenant object
can contain the following information:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
n
Name:
Specifies the name of the tenant as it appears in URLs.
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
n
Password:
Specifies the primary contact email address.
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata
VMware, Inc.
Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
31
Programming Guide
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
Accept
Content-Length
Accept-Charset
ibm-thai, ibm00858,
= application/json
= application/json
= 413
= big5, big5-hkscs, euc-jp, euc-kr, gb18030, gb2312, gbk,
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,
VMware, Inc.
32
Programming Guide
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.
VMware, Inc.
33
Programming Guide
Output
The command output contains property names and values based on the command input parameters.
Property
Links
Description
Specifies an array of link objects, each of which contains the following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested. This parameter does not
appear when you query a single profile.
n
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service that determines the other names.
href
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",
VMware, Inc.
34
Programming Guide
"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.
VMware, Inc.
35
Programming Guide
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",
VMware, Inc.
36
Programming Guide
"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,
VMware, Inc.
37
Programming Guide
"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-4f7cb5a1-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-4f7cb5a1-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
n
Log in to vRealize Automation as a consumer and current business group user.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
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.
n
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.
n
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.
VMware, Inc.
38
Programming Guide
n
Syntax for Requesting a Machine
You can use the REST API catalog service to submit a machine request.
n
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.
Procedure
1
List 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/catalogservice/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.
2
Locate 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/catalogservice/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
3
Get 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-b5a1d5f997c8ad66/requests/template
Accept: application/json
4
Review 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.
VMware, Inc.
39
Programming Guide
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.
5
Submit the request.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/catalog-service/api/consumer/entitledCatalogItems/dc808d12-3786-4f7c-b5a1d5f997c8ad66/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/7aaf9bafaa4e-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.
VMware, Inc.
40
Programming Guide
Parameter
Description
$orderby
Multiple comma-separated properties sorted in ascending or descending order. Valid OData
properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n
icon/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:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n
icon/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.
VMware, Inc.
41
Programming Guide
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/catalogservice/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$host/catalogservice/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests"
VMware, Inc.
42
Programming Guide
}
],
"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.
VMware, Inc.
43
Programming Guide
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:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n
icon/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.
VMware, Inc.
44
Programming Guide
Parameter
Description
$filter
Boolean expression for whether a particular entry should be included in the response. Valid
OData properties include the following:
n
name - filter based on catalog item name.
n
status - filter based on catalog item status.
n
service/id - filter based on catalog item service id.
n
service/name - filter based on catalog item service name.
n
organization/subTenant/id - filter based on catalog item business group ID, which you can
find in the catalogItem payload under organization > subtenantRef
n
organization/subTenant/name - filter based on catalog item business group name, which
you can find in catalogItem payload under organization >subtenantLabel
n
outputResourceType/id - filter based on catalog item output resource type ID, for example :
Infrastructure.Virtual
n
outputResourceType/name - Filter based on catalog item output resource type name, for
example: "VirtualMavhine".
n
catalogItemType/id - filter based on catalog item type ID, for example:
"Infrastructure.Virtual".
n
catalogItemType/name - filter based on catalog item type name, for example:
"VirtualMachine".
n
icon/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.
VMware, Inc.
45
Programming Guide
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/catalogservice/api/consumer/entitledCatalogItems/7c8275d6-1bd6-452a-97c4-d6c053e4baa4/requests/template"
},
{
"@type": "link",
"rel": "POST: Submit Request",
"href": "https://$host/catalogservice/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"
VMware, Inc.
46
Programming Guide
},
"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-4f7cb5a1-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.
VMware, Inc.
47
Programming Guide
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-b5a1d5f997c8ad66.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token” https://$host/catalogservice/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"
}
},
VMware, Inc.
48
Programming Guide
"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"
VMware, Inc.
49
Programming Guide
},
"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
}
}
}
}
VMware, Inc.
50
Programming Guide
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-4f7cb5a1-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.
VMware, Inc.
51
Programming Guide
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
VMware, Inc.
Specifies the item name.
52
Programming Guide
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-4f7cb5a1-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-b5a1d5f997c8ad66/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
VMware, Inc.
53
Programming Guide
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.
VMware, Inc.
54
Programming Guide
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
VMware, Inc.
Specifies the item name.
55
Programming Guide
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 7aaf9bafaa4e-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,
VMware, Inc.
56
Programming Guide
"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
n
Log in to vRealize Automation as an approver with at least one of the following qualifications:
n
You are designated as an approver in an approval policy.
n
You belong to a group which has been designated as an approval group in an approval policy.
n
You are designated as a delegate for someone who is an approver.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
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.
n
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.
n
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.
n
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.
VMware, Inc.
57
Programming Guide
n
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.
Procedure
1
List all available work item IDs.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/workitem-service/api/workitems
2
Get 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
3
4
Construct 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.
Approve 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-4409a52c-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.
VMware, Inc.
58
Programming Guide
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
Links
Description
Specifies an array of link objects, each of which contains the following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
n
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service that determines the other names.
href
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.
VMware, Inc.
59
Programming Guide
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:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned.
n
totalPages: Specifies the total number of pages of data available.
n
Number: Specifies the current page number.
n
Offset: 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
VMware, Inc.
60
Programming Guide
}
}, {
"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",
VMware, Inc.
61
Programming Guide
"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
VMware, Inc.
62
Programming Guide
}
}, {
"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" : {
VMware, Inc.
63
Programming Guide
"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,
VMware, Inc.
64
Programming Guide
"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:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
n
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service that determines the other names.
href
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.
VMware, Inc.
65
Programming Guide
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:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned.
n
totalPages: Specifies the total number of pages of data available.
n
Number: Specifies the current page number.
n
Offset: 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",
VMware, Inc.
66
Programming Guide
"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
},
.
.
.
{
VMware, Inc.
67
Programming Guide
"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"
}
VMware, Inc.
68
Programming Guide
}, {
"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.
VMware, Inc.
69
Programming Guide
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.
VMware, Inc.
70
Programming Guide
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-providerCafe.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",
VMware, Inc.
71
Programming Guide
"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"
}
}]
}
}
VMware, Inc.
72
Programming Guide
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
Links
Description
Specifies an array of link objects, each of which contains the following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested. This property does not exist
when you query for a single profile.
n
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service that determines the other names.
href
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.
VMware, Inc.
73
Programming Guide
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:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned.
n
totalPages: Specifies the total number of pages of data available.
n
Number: Specifies the current page number.
n
Offset: 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-4409a52c-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.}
VMware, Inc.
74
Programming Guide
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/compositionservice/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.
VMware, Inc.
75
Programming Guide
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.
n
Blueprint ID: Specifies the blueprint ID.
n
requestedFor: The user for whom this request is being made.
Must be the fully qualified user ID.
n
subTenantId: Specifies the subtenant ID associated with the
blueprint
n
requestData: Specifies data that identifies the blueprint further.
n
entries
n
Key: The name of the machine on which the blueprint
resides.
n
value: 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.
n
Values: Specifies an array of type filters.
n
Entries: 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.
VMware, Inc.
76
Programming Guide
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
}
}
]
}
}
}
]
}
}
VMware, Inc.
77
Programming Guide
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
n
Log in to vRealize Automation as a business group manager.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the business group subtenant ID values to specify on the command line. See Syntax for
Displaying Your Provisioned Resources.
n
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.
n
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.
n
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.
n
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.
VMware, Inc.
78
Programming Guide
n
Syntax for Viewing Machine Details
You can use the vRealize Automation REST API catalog service to display the machine details for a
provisioned machine.
Procedure
1
Display 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
2
Display 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
3
Display 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
4
Display 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') … )"
5
Display 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.
VMware, Inc.
79
Programming Guide
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.
VMware, Inc.
80
Programming Guide
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.
VMware, Inc.
81
Programming Guide
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:
n
Infrastructure.Machine
n
Infrastructure.AppServic
n
Infrastructure.Cloud
n
Infrastructure.Physical
n
Infrastructure.vApp
n
Infrastructure.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.
VMware, Inc.
82
Programming Guide
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"
},
VMware, Inc.
83
Programming Guide
"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.
VMware, Inc.
84
Programming Guide
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",
VMware, Inc.
85
Programming Guide
"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.
VMware, Inc.
86
Programming Guide
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-a0e6c2da8b0e1bf9') 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",
VMware, Inc.
87
Programming Guide
"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
}
}
VMware, Inc.
88
Programming Guide
},
"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",
VMware, Inc.
89
Programming Guide
"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",
VMware, Inc.
90
Programming Guide
"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
}
}, {
VMware, Inc.
91
Programming Guide
"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",
VMware, Inc.
92
Programming Guide
"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.
VMware, Inc.
93
Programming Guide
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
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.
{com.vmware.csp.component.cafe.composition@reso
urce.action.deployment.$actionName
POST:
{com.vmware.csp.component.cafe.composition@reso
urce.action.deployment.$actionName
GET: Child Resources
URI to which to post the request to perform an action, based on the
corresponding template.
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.
VMware, Inc.
94
Programming Guide
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.
VMware, Inc.
95
Programming Guide
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/catalogservice/api/consumer/entitledCatalogItemViews/7c8275d6-1bd6-452a-97c4-d6c053e4baa4"
},
{
"@type": "link",
"rel": "GET: Request",
"href": "https://$host/catalog-service/api/consumer/requests/7aaf9bafaa4e-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-44ffa1c9-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-44ffa1c9-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"
VMware, Inc.
96
Programming Guide
}
],
"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.
n
Log in to vRealize Automation as a business group manager.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc.
97
Programming Guide
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the business group subtenant ID values to specify on the command line. See Syntax for
Getting Deployment Details.
n
Syntax for Getting Deployment Details
You can use the REST API catalog service to identify provisioned items from a given request.
n
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.
n
Perform 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.
n
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.
Procedure
1
Display 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-997bedd7c7983a5b/resourceViews
The output from this command includes HATEOAS links that enable you to quickly obtain additional
information about specific deployed resources.
2
Use 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
3
In addition, you can use the HATEOAS links to complete day 2 actions.
n
You 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-b5beb229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests/template
VMware, Inc.
98
Programming Guide
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-b5beb229453eca4a/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
}
}
n
You 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-b5beb229453eca4a/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.
VMware, Inc.
99
Programming Guide
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
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.
{com.vmware.csp.component.cafe.composition@resour
ce.action.deployment.$actionName
POST:
{com.vmware.csp.component.cafe.composition@resour
ce.action.deployment.$actionName
GET: Child Resources
URI to which to post the request to perform an action, based on the
corresponding template.
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.
VMware, Inc.
100
Programming Guide
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-997bedd7c7983a5b.
$curl --insecure -s -H" Content-Type: multipart/form-data" -H "Authorization: Bearer
$token" http:// $host/catalog-service/api/consumer/requests/7aaf9baf-aa4e-47c4-997bedd7c7983a5b/resourceViews
VMware, Inc.
101
Programming Guide
Example: JSON Output
{
"links": [],
"content": [
{
"@type": "CatalogResourceView",
"links": [
{
"@type": "link",
"rel": "GET: Catalog Item",
"href": "https://$host/catalogservice/api/consumer/entitledCatalogItemViews/7c8275d6-1bd6-452a-97c4-d6c053e4baa4"
},
{
"@type": "link",
"rel": "GET: Request",
"href": "https://$host/catalog-service/api/consumer/requests/7aaf9bafaa4e-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-44ffa1c9-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-44ffa1c9-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": [
VMware, Inc.
102
Programming Guide
"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
POST:
{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.
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.
VMware, Inc.
103
Programming Guide
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.
VMware, Inc.
104
Programming Guide
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-44ffa1c9-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/c4d3db3ee397-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-4773b5be-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-4773b5be-b229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests"
},
VMware, Inc.
105
Programming Guide
{
"@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-4773b5be-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-4773b5be-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
VMware, Inc.
106
Programming Guide
},
"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": {
VMware, Inc.
107
Programming Guide
"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/c4d3db3ee397-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/f735b57afe6f-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/f735b57afe6f-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
VMware, Inc.
108
Programming Guide
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 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.
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-b5beb229453eca4a/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-b5beb229453eca4a/actions/02bad06d-f92b-4cf8-b964-37bb5d57be38/requests"
}
VMware, Inc.
109
Programming Guide
Procedure
1
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-b5beb229453eca4a/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
}
}
2
Use 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-b5beb229453eca4a/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.
VMware, Inc.
110
Programming Guide
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-b5beb229453eca4a/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-b5beb229453eca4a/actions/b5739e30-871d-48c7-9012-f2a7cf431dc1/requests"
},
Procedure
1
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-b5beb229453eca4a/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"
}
}
VMware, Inc.
111
Programming Guide
2
Edit 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).
3
Use 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-b5beb229453eca4a/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:
n
vSphere (except for FlexClone in vSphere)
n
vCloud Air
n
vCloud Director
n
Amazon
n
Hyper-V
n
KVM
n
Xen
The following reservation types are not supported:
n
OpenStack
n
Physical reservation
The reservation service is extensible, which allows you to add new reservation types.
VMware, Inc.
112
Programming Guide
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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the schema class ID of the reservation type to create. See Display a List of Supported
Reservation Types.
n
Display a list of the reservation types that are supported in the vRealize Automation server. See
Display a List of Supported Reservation Types.
n
Obtain 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.
n
Get the required compute resource ID. See Get a Compute Resource for the Reservation.
n
Finish creating a new reservation. Obtain the reservation ID from the output URL. See Syntax for
Creating a vSphere Reservation.
n
Get the reservation ID if you do not already know it. See Display a List of Reservations.
Procedure
1
Display 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
VMware, Inc.
113
Programming Guide
2
Display 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/dataservice/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/dataservice/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/dataservice/schema/Infrastructure.Reservation.Cloud.vCloudAir/default
3
Get 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
VMware, Inc.
114
Programming Guide
4
Obtain 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/dataservice/schema/Infrastructure.Reservation.Virtual.vSphere/default/computeResource/values
Example: curl Command for an Amazon EC2 reservation
-d “{}”
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/dataservice/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/dataservice/schema/Infrastructure.Reservation.Cloud.vCloudAir/default/computeResource/values
VMware, Inc.
-d “{}”
115
Programming Guide
5
Use 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/dataservice/schema/Infrastructure.Reservation.Virtual.vSphere/default/resourcePool/values
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": " cc254a84-95b8-434a-874d-bdfef8e8ad2c "
}
}]
}
}
b
-d “{
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/dataservice/schema/Infrastructure.Reservation.Cloud.Amazon/default/securityGroups/values
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
-d “
}
VMware, Inc.
116
Programming Guide
}]
}
}
”
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/dataservice/schema/Infrastructure.Reservation.Cloud.vCloudAir/default/reservationStorages/values
d “
VMware, Inc.
-
117
Programming Guide
6
Use 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",
VMware, Inc.
118
Programming Guide
"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
}
}]
}
}
VMware, Inc.
119
Programming Guide
},
{
"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",
VMware, Inc.
120
Programming Guide
"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"
}
}]
}
}"
VMware, Inc.
121
Programming Guide
}]
}
}
”
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": {
VMware, Inc.
122
Programming Guide
"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",
VMware, Inc.
123
Programming Guide
"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
}
}
VMware, Inc.
124
Programming Guide
]
}
}
]
}
},
{
"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,
VMware, Inc.
125
Programming Guide
"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": [
{
VMware, Inc.
126
Programming Guide
"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"
}
}
]
}
}”
7
Use 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
n
Log in to vRealize Automation as a fabric group administrator.
VMware, Inc.
127
Programming Guide
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
u
Display 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
}
}
VMware, Inc.
128
Programming Guide
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",
VMware, Inc.
129
Programming Guide
"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,
VMware, Inc.
130
Programming Guide
"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.
n
href
Content
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service that determines the other names.
Specifies the URL that produces the result.
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.
VMware, Inc.
131
Programming Guide
Property
FormReference
SchemaClassId
alertTypes
Description
Specifies the user interface form reference. This field is valid for user interface elements only.
n
type -- user interface form type
n
formId -- user interface form ID
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.
Contains the alert type list defined in the reservation type:
n
Metadata
createdDate -- Alert type created date
n
lastUpdated -- Alert type last updated date
n
version -- Alert type version
n
id -- Unique identifier of alert type
n
name -- Name of alert type
n
description -- Long description of alert type
n
referenceResourceId -- Unique identifier of reference resource
Specifies the paging-related data:
n
Size:
n
totalElements:
Specifies the maximum number of rows per page.
Specifies the number of rows returned.
n
totalPages:
Specifies the total number of pages of data available.
n
Number:
n
Offset:
Specifies the current page number.
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
VMware, Inc.
132
Programming Guide
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": [{
{
VMware, Inc.
133
Programming Guide
"@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
],
VMware, Inc.
134
Programming Guide
"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
}
}
VMware, Inc.
135
Programming Guide
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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the schema class ID of the reservation type to create. See Display a List of Supported
Reservation Types.
Procedure
u
Display 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/dataservice/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"]
},
VMware, Inc.
136
Programming Guide
"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,
VMware, Inc.
137
Programming Guide
"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",
VMware, Inc.
138
Programming Guide
"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": {
VMware, Inc.
139
Programming Guide
"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": []
VMware, Inc.
140
Programming Guide
},
"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.
VMware, Inc.
141
Programming Guide
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.
VMware, Inc.
142
Programming Guide
Property
Description
Id
Specifies the unique identifier of this resource.
label
Specifies the field label.
dataType
Specifies the dataType field value:
n
type: Specifies the field value type:
n
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to corresponding pages of a pageable list.
n
Specifies the application or service that determines the other names.
n
componentTypeid:
n
component:
Specifies the type ID of the component.
Specifies the unique identifier of the component.
n
classId:
Specifies the schema class of the field
This property is valid for complex and ref field types only.
n
label:
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:
n
type:
n
customAllowed:
n
dependencies:
Specifies if the permissible value list is dynamic or static.
Specifies if a custom value is allowed during user input in this field.
Specifies the list of fields that the current field depends on.
VMware, Inc.
143
Programming Guide
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:
n
facets:
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.
n
isMultiValued:
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/dataservice/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"]
VMware, Inc.
144
Programming Guide
},
"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",
VMware, Inc.
145
Programming Guide
"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": {
VMware, Inc.
146
Programming Guide
"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",
VMware, Inc.
147
Programming Guide
"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": []
VMware, Inc.
148
Programming Guide
},
"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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the schema class ID of the reservation type to create. See Display a List of Supported
Reservation Types.
Procedure
u
Display a schema definition for an Amazon reservation type.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/dataservice/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"
VMware, Inc.
149
Programming Guide
]
},
"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"
},
VMware, Inc.
150
Programming Guide
"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",
VMware, Inc.
151
Programming Guide
"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",
VMware, Inc.
152
Programming Guide
"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"
VMware, Inc.
153
Programming Guide
},
"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": [
VMware, Inc.
154
Programming Guide
{
"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",
VMware, Inc.
155
Programming Guide
"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
}
}
},
VMware, Inc.
156
Programming Guide
{
"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",
VMware, Inc.
157
Programming Guide
"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"
}
}
},
VMware, Inc.
158
Programming Guide
{
"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
},
{
VMware, Inc.
159
Programming Guide
"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",
VMware, Inc.
160
Programming Guide
"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
VMware, Inc.
161
Programming Guide
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.
VMware, Inc.
162
Programming Guide
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:
n
n
type: Specifies the field value type:
n
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to corresponding pages of a pageable list.
n
Specifies the application or service that determines the other names.
componentTypeid:
Specifies the type ID of the component.
n
component:
Specifies the unique identifier of the component.
n
classId:
Specifies the schema class of the field
This property is valid for complex and ref field types only.
n
label:
Specifies the label of the field data type.
displayAdvice
VMware, Inc.
Contains display advice for the field. This property is valid for a user interface element only.
163
Programming Guide
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:
n
type:
n
customAllowed:
n
dependencies:
Specifies if the permissible value list is dynamic or static.
Specifies if a custom value is allowed during user input in this field.
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:
n
facets:
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.
n
isMultiValued:
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/dataservice/schema/Infrastructure.Reservation.Cloud.Amazon/default
Example: JSON Output
The following JSON output is returned based on the command input.
VMware, Inc.
164
Programming Guide
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"
VMware, Inc.
165
Programming Guide
},
"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",
VMware, Inc.
166
Programming Guide
"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",
VMware, Inc.
167
Programming Guide
"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"
},
VMware, Inc.
168
Programming Guide
"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
},
{
VMware, Inc.
169
Programming Guide
"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": {
VMware, Inc.
170
Programming Guide
"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"
VMware, Inc.
171
Programming Guide
},
"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": [
],
VMware, Inc.
172
Programming Guide
"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"
]
VMware, Inc.
173
Programming Guide
},
"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"
VMware, Inc.
174
Programming Guide
}
}
},
{
"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": [
VMware, Inc.
175
Programming Guide
{
"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.
VMware, Inc.
176
Programming Guide
Prerequisites
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the schema class ID of the reservation type to create. See Display a List of Supported
Reservation Types.
Procedure
u
Display a schema definition for a specific vCloud Air reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/dataservice/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": [
VMware, Inc.
177
Programming Guide
],
"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": [
VMware, Inc.
178
Programming Guide
"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",
VMware, Inc.
179
Programming Guide
"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
}
]
VMware, Inc.
180
Programming Guide
}
},
"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",
VMware, Inc.
181
Programming Guide
"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
}
}
VMware, Inc.
182
Programming Guide
}
]
},
"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
}
VMware, Inc.
183
Programming Guide
}
}
]
},
"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",
VMware, Inc.
184
Programming Guide
"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
}
}
}
]
},
VMware, Inc.
185
Programming Guide
"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 typespecific. 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.
VMware, Inc.
186
Programming Guide
Table 3‑13. Extension Fields Supported in vCloud Reservations
Permissible
Value
Depends on Field
Infrastructure.Reservation.N
etwork
Yes
computeResource
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
Field ID
Data Type
Type Class
reservationNetworks
Complex Type
allocationModel
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.
VMware, Inc.
187
Programming Guide
Property
Description
dataType
Specifies the dataType field value:
n
type: Specifies the field value type:
n
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to corresponding pages of a pageable list.
n
Specifies the application or service that determines the other names.
n
componentTypeid:
n
component:
Specifies the type ID of the component.
Specifies the unique identifier of the component.
n
classId:
Specifies the schema class of the field
This property is valid for complex and ref field types only.
n
label:
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:
n
type:
Specifies if the permissible value list is dynamic or static.
n
customAllowed:
Specifies if a custom value is allowed during user input in this field.
n
dependencies:
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:
n
facets:
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.
n
isMultiValued:
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.
VMware, Inc.
188
Programming Guide
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/dataservice/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
}
VMware, Inc.
189
Programming Guide
}
}
]
},
"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": {
VMware, Inc.
190
Programming Guide
"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",
VMware, Inc.
191
Programming Guide
"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": [
]
},
VMware, Inc.
192
Programming Guide
"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": [
VMware, Inc.
193
Programming Guide
]
},
"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",
VMware, Inc.
194
Programming Guide
"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": {
VMware, Inc.
195
Programming Guide
"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": [
],
VMware, Inc.
196
Programming Guide
"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.
VMware, Inc.
197
Programming Guide
Prerequisites
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
u
Get 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"
VMware, Inc.
198
Programming Guide
},
{
"@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
VMware, Inc.
199
Programming Guide
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.
n
href
Content
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service determines the other names.
Specifies the URL which produces the result.
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.
VMware, Inc.
200
Programming Guide
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",
VMware, Inc.
201
Programming Guide
"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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify 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.
VMware, Inc.
202
Programming Guide
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
u
Use 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/dataservice/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/dataservice/schema/Infrastructure.Reservation.Cloud.Amazon/default/computeResource/values
Example: curl Command for a vCloud reservation
-d “{}”
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/dataservice/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",
VMware, Inc.
203
Programming Guide
"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",
VMware, Inc.
204
Programming Guide
"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/dataservice/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.
VMware, Inc.
205
Programming Guide
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.
From the schema definition, specifies the schemaclassid of the compute
$fieldId
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.
n
type
Specifies one of the following permissible value data types.
n
entityRef - Indicates that the object references a vRealize Automation entity.
n
complexRef - Indicates that the object is a user-defined complex structure, for example struct
in C or Pojo in Java.
n
n
primary - Indicates the entity type such as string, integer, and so on.
componentId
Specifies the component ID.
n
classId
Specifies the schema class ID of the current data type.
n
Id
Specifies the unique compute resource identifier.
label
VMware, Inc.
Contains the compute resource label. This value matches the underlyingValue.label.
206
Programming Guide
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/dataservice/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/dataservice/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/dataservice/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",
VMware, Inc.
207
Programming Guide
"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"
VMware, Inc.
208
Programming Guide
},
{
"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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Get the required compute resource ID. See Get a Compute Resource for the Reservation.
VMware, Inc.
209
Programming Guide
Procedure
u
Display 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/dataservice/schema/Infrastructure.Reservation.Virtual.vSphere/default/resourcePool/values
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": " cc254a84-95b8-434a-874d-bdfef8e8ad2c "
}
}]
}
}”
-d “{
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
]
}
VMware, Inc.
210
Programming Guide
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/dataservice/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.
VMware, Inc.
211
Programming Guide
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
label
JSON string representing one permissible value for a field:
n
type -- data type of entityRef, complexRef, or primary
n
component ID -- componentID
n
classId -- schema class ID of current data type
n
id -- unique resource pool ID
n
label -- resource pool 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/dataservice/schema/Infrastructure.Reservation.Virtual.vSphere/default/resourcePool/values
"text": "",
-d “{
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": " cc254a84-95b8-434a-874d-bdfef8e8ad2c "
VMware, Inc.
212
Programming Guide
}
}]
}
}”
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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Get the required compute resource ID. See Get a Compute Resource for the Reservation.
VMware, Inc.
213
Programming Guide
Procedure
u
Use 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/dataservice/schema/Infrastructure.Reservation.Cloud.Amazon/default/securityGroups/values
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
}
}]
}
}
”
-d “
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"
}
]
}
VMware, Inc.
214
Programming Guide
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/dataservice/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.
VMware, Inc.
215
Programming Guide
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
label
JSON string representing one permissible value for a field:
n
type -- data type of entityRef, complexRef, or primary
n
component ID -- componentID
n
classId -- schema class ID of current data type
n
id -- unique security group ID
n
label -- security group 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/dataservice/schema/Infrastructure.Reservation.Cloud.Amazon/default/securityGroups/values
{
"text": "",
"dependencyValues": {
"entries": [{
"key": "computeResource",
"value": {
"type": "entityRef",
"componentId": null,
"classId": "ComputeResource",
"id": "9d1a3b5a-7162-4a5a-85b7-ec1b2824f554"
}
VMware, Inc.
-d “
216
Programming Guide
}]
}
}
”
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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Get the required compute resource ID. See Get a Compute Resource for the Reservation.
VMware, Inc.
217
Programming Guide
Procedure
u
Use 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/dataservice/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": {
VMware, Inc.
218
Programming Guide
"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.
VMware, Inc.
219
Programming Guide
Table 3‑16. Extension Fields Supported in vCloud Reservations
Permissible
Value
Depends on Field
Infrastructure.Reservation.N
etwork
Yes
computeResource
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
Field ID
Data Type
Type Class
reservationNetworks
Complex Type
allocationModel
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/dataservice/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
VMware, Inc.
Empty
220
Programming Guide
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
label
JSON string representing one permissible value for a field:
n
type -- data type of entityRef, complexRef, or primary
n
component ID -- componentID
n
classId -- schema class ID of current data type
n
id -- unique reservation storage ID
n
label --reservation storage 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/dataservice/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,
VMware, Inc.
221
Programming Guide
"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"
VMware, Inc.
222
Programming Guide
}
},
{
"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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Display a list of the reservation types that are supported in the vRealize Automation server. See
Display a List of Supported Reservation Types.
n
Obtain 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
u
Create a vSphere reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d
“
{
VMware, Inc.
223
Programming Guide
"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"
VMware, Inc.
224
Programming Guide
}
}]
}
}]
}
},
{
"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"
}
VMware, Inc.
225
Programming Guide
},
{
"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",
VMware, Inc.
226
Programming Guide
"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-8f42efd590fea15c.
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.
VMware, Inc.
227
Programming Guide
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:
n
Copy 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.
n
Use 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",
VMware, Inc.
228
Programming Guide
"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": {
VMware, Inc.
229
Programming Guide
"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",
VMware, Inc.
230
Programming Guide
"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",
VMware, Inc.
231
Programming Guide
"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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Display a list of the reservation types that are supported in the vRealize Automation server. See
Display a List of Supported Reservation Types.
n
Obtain 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
u
Create a vCloud Air reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d “
{
"name": "TestvAppReservation",
VMware, Inc.
232
Programming Guide
"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
}
},
VMware, Inc.
233
Programming Guide
{
"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",
VMware, Inc.
234
Programming Guide
"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,
VMware, Inc.
235
Programming Guide
"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.
VMware, Inc.
236
Programming Guide
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:
n
Copy 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.
n
Update the formatted reservation information to specify the new
information:
n
remove the appropriate ID field from the HTTP response
n
edit 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": [
VMware, Inc.
237
Programming Guide
],
"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",
VMware, Inc.
238
Programming Guide
"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"
}
VMware, Inc.
239
Programming Guide
},
{
"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": {
VMware, Inc.
240
Programming Guide
"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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Display a list of the reservation types that are supported in the vRealize Automation server. See
Display a List of Supported Reservation Types.
n
Obtain 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
u
Create an Amazon reservation.
curl --insecure -H "Accept:application/json"
-H "Authorization: Bearer $token"
https://$host/reservation-service/api/reservations -d “
{
"name": "TestEC2Reservation",
VMware, Inc.
241
Programming Guide
"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"
}
]
}
VMware, Inc.
242
Programming Guide
},
{
"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.
VMware, Inc.
243
Programming Guide
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:
n
Copy 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.
n
Use 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": {
VMware, Inc.
244
Programming Guide
"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": [
VMware, Inc.
245
Programming Guide
{
"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.
VMware, Inc.
246
Programming Guide
Prerequisites
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Finish creating a new reservation. Obtain the reservation ID from the output URL. See Syntax for
Creating a vSphere Reservation.
n
Get the reservation ID if you do not already know it. See Display a List of Reservations.
Procedure
u
Use 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,
VMware, Inc.
247
Programming Guide
"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"
}
VMware, Inc.
248
Programming Guide
}]
}
}]
}
},
{
"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": {
VMware, Inc.
249
Programming Guide
"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"
VMware, Inc.
250
Programming Guide
}
},
{
"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"
},
VMware, Inc.
251
Programming Guide
{
"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,
VMware, Inc.
252
Programming Guide
"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
}
VMware, Inc.
253
Programming Guide
},
{
"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
}
}
]
}
}
VMware, Inc.
254
Programming Guide
}
]
}
}
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 /reservationservice/api/reservations/$reservationId.
$reservationId
The HTTP response should contain a location attribute, formatted as https://$host /reservationservice/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
VMware, Inc.
255
Programming Guide
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"
VMware, Inc.
256
Programming Guide
}
},
{
"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": {
VMware, Inc.
257
Programming Guide
"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",
VMware, Inc.
258
Programming Guide
"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",
VMware, Inc.
259
Programming Guide
"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": [
VMware, Inc.
260
Programming Guide
{
"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"
}
}
]
}
}
]
}
},
{
VMware, Inc.
261
Programming Guide
"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",
VMware, Inc.
262
Programming Guide
"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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc.
263
Programming Guide
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
u
Display 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": [{
VMware, Inc.
264
Programming Guide
"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"
}
VMware, Inc.
265
Programming Guide
},
{
"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",
VMware, Inc.
266
Programming Guide
"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",
VMware, Inc.
267
Programming Guide
"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.
VMware, Inc.
268
Programming Guide
Property
Description
Links
Species an array of link objects, each of which contains the following parts:
rel
href
Specifies the name of the link.
n
Self refers to the object which was returned or requested.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service that determines the other names.
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,
VMware, Inc.
269
Programming Guide
"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",
VMware, Inc.
270
Programming Guide
"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
VMware, Inc.
271
Programming Guide
}
}]
}
}
},
{
"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
}
},
VMware, Inc.
272
Programming Guide
{
"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
}
}
VMware, Inc.
273
Programming Guide
Update a Reservation
You can use the REST API reservation service to update an existing vRealize Automation reservation.
Prerequisites
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain 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.
n
Obtain 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
u
Use the reservation service to update an existing reservation.
The following example command updates a reservation with an ID of 94d74105-831a-4598-8f42efd590fea15c.
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"
},
VMware, Inc.
274
Programming Guide
{
"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",
VMware, Inc.
275
Programming Guide
"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",
VMware, Inc.
276
Programming Guide
"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
}
},
VMware, Inc.
277
Programming Guide
{
"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.
VMware, Inc.
278
Programming Guide
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-8f42efd590fea15c 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": [{
VMware, Inc.
279
Programming Guide
"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"
VMware, Inc.
280
Programming Guide
}
},
{
"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
}
}]
}
VMware, Inc.
281
Programming Guide
}
},
{
"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": {
VMware, Inc.
282
Programming Guide
"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.
VMware, Inc.
283
Programming Guide
Prerequisites
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain 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
u
Use the reservation service to delete the existing reservation.
The following example command deletes a reservation with the ID of 94d74105-831a-4598-8f42efd590fea15c.
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.
VMware, Inc.
284
Programming Guide
Example: curl Command
The following example command deletes a reservation with an ID of 94d74105-831a-4598-8f42efd590fea15c.
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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
VMware, Inc.
285
Programming Guide
Procedure
u
Run 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
VMware, Inc.
286
Programming Guide
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:
n
rel
Specifies the name of the link.
n
n
Self refers to the object which was returned or requested.
n
First, Previous, Next, and Last refer to corresponding pages of pageable lists.
n
Specifies the application or service that determines the other names.
href
Specifies the URL that produces the result.
Content
reservationPolicyTypeId
Metadata
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.
n
id. Specifies the unique reservation policy ID.
n
name. Specifies the reservation policy name.
n
description. Specifies the reservation policy description.
Specifies the type of reservation policy. Supported vRealize Automation reservation policy types are
Reservation.Policy.ComputeResource and Reservation.Policy.Storage.
Specifies the paging-related data:
n
Size. Specifies the maximum number of rows per page.
n
totalElements. Specifies the number of rows returned.
n
totalPages. Specifies the total number of pages of data available.
n
Number. Specifies the current page number.
n
Offset. 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
VMware, Inc.
287
Programming Guide
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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
List existing reservation policies to create the sample output required for creating a new reservation
policy. See List Reservation Policies.
VMware, Inc.
288
Programming Guide
Procedure
u
Use 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.
$reservationPolicyTypeId
n
$name - reservation policy name
n
$description - reservation policy description
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.
VMware, Inc.
289
Programming Guide
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 /reservationservice/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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc.
290
Programming Guide
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the reservation policy ID of the reservation policy to query. See Syntax for Listing Reservation
Policies.
Procedure
u
Display information about the reservation policy ID.
The following example displays information about reservation policy 8adafb54-4c85-4478-86f0b6ae80ab5ca4.
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.
VMware, Inc.
291
Programming Guide
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
n
Log in to vRealize Automation as a fabric group administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Get the required reservation policy ID. See Syntax for Listing Reservation Policies.
n
Query 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.
VMware, Inc.
292
Programming Guide
Procedure
1
Query the reservation policy and copy the response output to an editor.
2
Change the following information to use as the basis of the command input for this task.
3
n
Reservation policy name
n
Reservation policy description
n
Reservation policy type ID
Update 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.
VMware, Inc.
293
Programming Guide
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
n
Log in to vRealize Automation as a fabric group administrator.
VMware, Inc.
294
Programming Guide
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Get the required reservation policy ID. See Syntax for Listing Reservation Policies.
Procedure
u
Delete 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.
VMware, Inc.
295
Programming Guide
Example: Example: curl Command
The following example command deletes a reservation policy with an ID of 8adafb54-4c85-4478-86f0b6ae80ab5ca4.
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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
u
Use 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": [
{
VMware, Inc.
296
Programming Guide
"@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
VMware, Inc.
297
Programming Guide
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.
VMware, Inc.
298
Programming Guide
Parameter
Description
Links
Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a single
profile.
n
First, Previous, Next, and Last refer to corresponding
pages of pageable lists.
n
n
Specifies 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. Each tenant object can
contain the following information:
n
@type:
n
$id:
Contains the KeyPair string.
Specifies the unique identifier of the key pair.
n
$name:
n
$computeresourceId:
Specifies the name of the key pair.
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:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: 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
VMware, Inc.
299
Programming Guide
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,
VMware, Inc.
300
Programming Guide
"totalPages": 1,
"number": 1,
"offset": 0
}
}
Create a Key Pair
You can use the vRealize Automation REST API to create a key pair.
Prerequisites
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Get the required compute resource ID. See Get a Compute Resource for the Reservation.
Procedure
1
Obtain the compute resource ID of the target key pair that you want to create.
2
Use 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
VMware, Inc.
301
Programming Guide
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:
n
$computeResourceId:
Specifies the name of the key pair.
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.
VMware, Inc.
302
Programming Guide
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-proxyprovider/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=="
}
“
VMware, Inc.
303
Programming Guide
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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
u
Use 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.
VMware, Inc.
304
Programming Guide
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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc.
305
Programming Guide
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
u
Use 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
VMware, Inc.
306
Programming Guide
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:
n
$computeResourceId:
Specifies the name of the key pair.
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
VMware, Inc.
307
Programming Guide
+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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
VMware, Inc.
308
Programming Guide
Procedure
u
Use 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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify 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.
VMware, Inc.
309
Programming Guide
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.
VMware, Inc.
310
Programming Guide
Network Profile
Type
External
Description
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:
n
Existing 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.
n
An 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.
n
An 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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
VMware, Inc.
311
Programming Guide
Procedure
u
Use 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",
VMware, Inc.
312
Programming Guide
"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": "",
VMware, Inc.
313
Programming Guide
"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,
VMware, Inc.
314
Programming Guide
"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",
VMware, Inc.
315
Programming Guide
"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",
VMware, Inc.
316
Programming Guide
"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,
VMware, Inc.
317
Programming Guide
"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.
VMware, Inc.
318
Programming Guide
Parameter
Description
Links
Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a single
profile.
n
First, Previous, Next, and Last refer to corresponding
pages of pageable lists.
n
n
Specifies 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. Each tenant object can
contain the following information:
n
@type:
Specifies one of the following network profile type values:
n
ExternalNetworkProfile
n
NATNetworkProfile
n
PrivateNetworkProfile
n
RoutedNetworkProfile
n
$id:
n
$name:
Specifies the unique network profile identifier.
Specifies the network profile name.
n
createdDate:
Specifies the date and time that the network profile was created.
n
lastModifiedDate:
Specifies the date and time that the network profile was last
modified.
n
isHidden:
Specifies if the network profile is hidden from the
vRealize Automation user interface.
n
definedRanges:
Specifies the IP range array that is defined for the network
profile.
n
profileType:
Specifies the network profile type as one of the following types:
n
n
VMware, Inc.
EXTERNAL
n
NAT
n
ROUTED
IPAMEndpointId:
319
Programming Guide
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.
n
subnetMask:
n
gatewayAddress:
Specifies the subnet mask.
Specifies the IP address of the network gateway.
n
primaryDnsAddress:
Specifies the IP address of the primary DNS server. This
parameter is only available for external, NAT, and routed
network profiles.
n
secondaryDnsAddress:
Specifies the IP address of a secondary DNS server. This
parameter is only available for external, NAT, and routed
network profiles.
n
dnsSuffix:
Specifies the DNS suffix. This parameter is only available for
external, NAT, and routed network profiles.
n
dnsSearchSuffix:
Specifies the DNS search suffix. This parameter is only
available for external, NAT, and routed network profiles.
n
primaryWinsAddress:
Specifies the IP address of the primary Wins server. This
parameter is only available for external, NAT, and routed
network profiles.
n
secondaryWinsAddress:
Specifies the IP address of secondary Wins server. This
parameter is only available for external, NAT, and routed
network profiles.
n
dhcpStartIPAddress:
Specifies the start IP address of the DHCP server. This
parameter is only supported by NAT and private network
profiles.
n
dhcpEndIPAddress:
Specifies the end IP address of the DHCP server. This
parameter is only supported by NAT and private network
profiles.
n
leaseTimeInSeconds:
Specifies the lease time for the DHCP server. This parameter is
only supported by NAT and private network profiles.
VMware, Inc.
320
Programming Guide
Parameter
Description
n
baseIP:
Specifies the base IP address. This parameter is only supported
by routed network profiles.
Metadata
Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: 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",
VMware, Inc.
321
Programming Guide
"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",
VMware, Inc.
322
Programming Guide
"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"
VMware, Inc.
323
Programming Guide
},
{
"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": [
]
}
VMware, Inc.
324
Programming Guide
],
"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"
},
]
},
{
VMware, Inc.
325
Programming Guide
"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"
},
]
}
VMware, Inc.
326
Programming Guide
],
"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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
If you are using an external IPAM provider solution, verify that you have access to an endpoint for the
IPAM provider solution software.
n
If 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.
VMware, Inc.
327
Programming Guide
Procedure
u
Use 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/263b80f5d34f-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.
VMware, Inc.
328
Programming Guide
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-proxyprovider/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": "",
VMware, Inc.
329
Programming Guide
"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-47f2b0b1-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.
VMware, Inc.
330
Programming Guide
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.
n
profileType
Specify EXTERNAL for this paramter.
n
id
Specifies null.
n
name
Specifies the name of the profile.
n
IPAMEndpointId
Specifies the endpoint ID for an external IPAM provider.
n
addressSpaceExternalId
Must specify the value that is chosen in the
vRealize Automation UI for Address Space.
n
description
Optionally, can specify a description for the profile. If you do
not provide a description, code "null" for this parameter.
n
definedRanges
Specifies parameters that set up defined address ranges:
n
externalId
n
name
n
description
n
state
n
beginIPv4Address
Specify "UNALLOCATED" for this value.
Specify "null" for this parameter.
n
endIPv4Address
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-proxyprovider/api/network/profiles/$networkProfileID.
$networkProfileID
VMware, Inc.
Specifies the unique identifier of the new network profile.
331
Programming Guide
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-47f2b0b1-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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
VMware, Inc.
332
Programming Guide
n
Obtain the network profile ID to query. See Get a Network Profile List.
Procedure
u
Use the following command to query the existing network profile ID 68b6a183-fc8a-4592af23-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",
VMware, Inc.
333
Programming Guide
"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.
VMware, Inc.
334
Programming Guide
Parameter
Description
Links
Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This property does not exist when you query for a single
profile.
n
First, Previous, Next, and Last refer to corresponding
pages of pageable lists.
n
n
Specifies 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:
n
@type:
Specifies one of the following network profile type values:
n
n
ExternalNetworkProfile
n
NATNetworkProfile
n
RoutedNetworkProfile
$id:
Specifies the unique network profile identifier.
n
$name:
Specifies the network profile name.
n
createdDate:
Specifies the date and time that the network profile was created.
n
lastModifiedDate:
Specifies the date and time that the network profile was last
modified.
n
isHidden:
Specifies if the network profile is hidden from the
vRealize Automation user interface.
n
definedRanges:
Specifies the IP range array that is defined for the network
profile.
n
profileType:
Specifies the network profile type as one of the following types:
VMware, Inc.
n
EXTERNAL
n
NAT
335
Programming Guide
Parameter
Description
n
n
ROUTED
IPAMEndpointId
If you are querying an external network profile that uses external
IPAM, shows the endpoint ID for the external IPAM provider.
n
subnetMask:
n
gatewayAddress:
Specifies the subnet mask.
Specifies the IP address of the network gateway.
n
primaryDnsAddress:
Specifies the IP address of the primary DNS server. This
parameter is only available for external, NAT, and routed
network profiles.
n
secondaryDnsAddress:
Specifies the IP address of a secondary DNS server. This
parameter is only available for external, NAT, and routed
network profiles.
n
dnsSuffix:
Specifies the DNS suffix. This parameter is only available for
external, NAT, and routed network profiles.
n
dnsSearchSuffix:
Specifies the DNS search suffix. This parameter is only
available for external, NAT, and routed network profiles.
n
primaryWinsAddress:
Specifies the IP address of the primary Wins server. This
parameter is only available for external, NAT, and routed
network profiles.
n
secondaryWinsAddress:
Specifies the IP address of secondary Wins server. This
parameter is only available for external, NAT, and routed
network profiles.
n
dhcpStartIPAddress:
Specifies the start IP address of the DHCP server. This
parameter is only supported by NAT network profiles.
n
dhcpEndIPAddress:
Specifies the end IP address of the DHCP server. This
parameter is only supported by NAT network profiles.
n
leaseTimeInSeconds:
Specifies the lease time for the DHCP server. This parameter is
only supported by NAT network profiles.
n
baseIP:
Specifies the base IP address. This parameter is only supported
by routed network profiles.
Metadata
VMware, Inc.
Specifies the following paging-related data:
336
Programming Guide
Parameter
Description
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
Example: curl Command
The following example command queries the existing network profile ID 68b6a183-fc8a-4592af23-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"
},
VMware, Inc.
337
Programming Guide
{
"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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the network profile ID to query. See Get a Network Profile List.
Procedure
u
Update the network profile.
The following example command updates the network profile 263b80f5-d34f-47f2b0b1-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",
VMware, Inc.
338
Programming Guide
"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
VMware, Inc.
339
Programming Guide
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-47f2b0b1-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": "",
VMware, Inc.
340
Programming Guide
"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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the network profile ID to delete. See Get a Network Profile List.
Procedure
u
Delete the network profile.
The following example command deletes the network profile 263b80f5-d34f-47f2b0b1-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.
VMware, Inc.
341
Programming Guide
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-47f2b0b1-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
n
Log in to vRealize Automation as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
n
Obtain the endpoint ID for the external IPAM provider device you want to query.
VMware, Inc.
342
Programming Guide
Procedure
u
Use 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//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": "",
VMware, Inc.
343
Programming Guide
"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",
VMware, Inc.
344
Programming Guide
"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"
}
},
VMware, Inc.
345
Programming Guide
{
"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",
VMware, Inc.
346
Programming Guide
"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,
VMware, Inc.
347
Programming Guide
"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"
VMware, Inc.
348
Programming Guide
},
{
"@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",
VMware, Inc.
349
Programming Guide
"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"
VMware, Inc.
350
Programming Guide
}
}
]
},
"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",
VMware, Inc.
351
Programming Guide
"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": "",
VMware, Inc.
352
Programming Guide
"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",
VMware, Inc.
353
Programming Guide
"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"
}
},
VMware, Inc.
354
Programming Guide
{
"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",
VMware, Inc.
355
Programming Guide
"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,
VMware, Inc.
356
Programming Guide
"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"
VMware, Inc.
357
Programming Guide
},
{
"@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",
VMware, Inc.
358
Programming Guide
"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.
VMware, Inc.
359
Programming Guide
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
n
Log 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.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that there is a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
VMware, Inc.
360
Programming Guide
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
2
Display 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
3
If 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
4
Create 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
6
Export 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-managementservice/api/packages/54f627bb-2277-48af-9fa0-7d7366b498f3-o package.zip
VMware, Inc.
361
Programming Guide
7
Validate 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/initialconfig/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.
8
Import 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:
n
composite-blueprint - the content type corresponding to the composite blueprint
n
software-component - the content type corresponding to the software component
n
property-group - the content type corresponding to the property groups
n
property-definition - the content type corresponding to the property definitions
Everything as a Service (XaaS) content types:
n
XaaS-blueprint
n
XaaS-resource-action
n
XaaS-resource-type
n
XaaS-resource-mapping
Input
Use the supported input parameters with your query URL to control command output. .
VMware, Inc.
362
Programming Guide
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:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
n
Specifies the application or service that determines the
other names.
href
Specifies the URL that produces the result.
Content
n
id: The unique identifier for the content. This is also used as
n
name: The name of a given content type provided in
localized message key form.
n
description: Additional information describing the content
a folder name to group similar content artifacts.
type.
Metadata
VMware, Inc.
n
classId: The class identifier associated with a content type.
n
serviceTypeId: The service ID for the given content type.
Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
363
Programming Guide
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",
VMware, Inc.
364
Programming Guide
"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.
VMware, Inc.
365
Programming Guide
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.
VMware, Inc.
366
Programming Guide
Parameter
Description
Links
Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
n
Specifies the application or service that determines the
other names.
href
Specifies the URL that produces the result.
Content
Metadata
VMware, Inc.
Specifies an array of data rows, each of which represents one of
the objects returned in a pageable list.
n
id: Specifies the unique identifier for the content. This is also
used as a folder name to group similar content artifacts.
n
contentId: The human readable immutable user or provider
supplied content ID.
n
name: Specifies the name of a given content type provided
in localized message key form.
n
description: Specifies additional information describing the
package.
n
contentTypeId: Identifies the nature of the content.
n
mimeType: Identifies the mime type.
n
tenantId: The ID of the tenant associated with the package.
Used to enforce ownership.
n
subtenantId: (Optional) The ID of the sub tenant or business
group associated with the package.
n
dependencies: Represents the dependencies of the content
unit in the form of content IDs.
n
createdDate: The creation date of the content.
n
lastUpdated: The date on which the content was last
updated.
n
version: The version identifier of the content.
Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
367
Programming Guide
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",
VMware, Inc.
368
Programming Guide
"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
VMware, Inc.
369
Programming Guide
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
}
}
VMware, Inc.
370
Programming Guide
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
n
For import or export purposes you must create a package to contain the desired content.
n
The package is a logical unit that enables you to piece together different content elements.
n
You 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
VMware, Inc.
371
Programming Guide
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.
VMware, Inc.
372
Programming Guide
Parameter
Description
Links
Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
This parameter does not appear when you query a
single profile.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
n
Specifies the application or service that determines the
other names.
href
Specifies the URL that produces the result.
Content
Metadata
n
createdDate: The creation date of the content.
n
lastUpdated: The date on which the content was last
updated.
n
version: The version identifier of the content.
n
id: Specifies the unique identifier for the content. This is also
used as a folder name to group similar content artifacts.
n
contentId: The human readable immutable user or provider
supplied content ID.
n
name: Specifies the name of a given content type provided
in localized message key form.
n
description: Specifies additional information describing the
package.
n
contentTypeId: The unique identifier of the contentType.
n
mimeType: The mime type file identifier.
n
tenantId: The ID of the tenant associated with the package.
Used to enforce ownership.
n
subtenantId: (Optional) The ID of the sub tenant or business
group associated with the package.
n
dependencies: These represent the content unit
dependencies in the form of content IDs.
Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned. This
parameter is not output when you query for a single profile.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: 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
VMware, Inc.
373
Programming Guide
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.
VMware, Inc.
374
Programming Guide
Example Curl Command
$curl --insecure -s -H "Accept: application/zip" -H "Authorization: Bearer $token"
https://$host/content-managementservice/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.
VMware, Inc.
375
Programming Guide
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:
n
contentImportResults
Success - Denotes the successful import or validation status at a particular component or
package level.
n
Failed - Denotes an import or validation failure at a particular component package level.
n
Warning - Denotes a scenario that warrants a system level warning. Alerts the user about a
possible error condition that the proposed action may create.
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:
n
contentId - (string) Unique content ID within the file system.
n
contentName - (anyType) Name of the content being imported.
n
contentTypeId - (string) The ID for the content type being exported. This matches the folder
structure in the exported zip.
n
contentImportStatus - Track the failed or succeeded status of an entity.
n
messages - Information returned by the provider.
n
contentImportErrors - 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/initialconfig/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
VMware, Inc.
376
Programming Guide
},
{
"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.
VMware, Inc.
377
Programming Guide
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:
n
contentImportResults
Success - Denotes the successful import or validation status at a particular component or
package level.
n
Failed - Denotes an import or validation failure at a particular component package level.
n
Warning - Denotes a scenario that warrants a system level warning. Alerts the user about a
possible error condition that the proposed action may create.
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:
n
contentId - (string) Unique content ID within the file system.
n
contentName - (anyType) Name of the content being imported.
n
contentTypeId - (string) The ID for the content type being exported. This matches the folder
structure in the exported zip.
n
contentImportStatus - Track the failed or succeeded status of an entity.
n
messages - Information returned by the provider.
n
contentImportErrors - 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",
VMware, Inc.
378
Programming Guide
"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
2.
3.
4.
5.
id: Blueprint.CentOSAndApache
name: CentOSAndApache
status: PUBLISHED
components:
web:
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
VMware, Inc.
type: Infrastructure.CatalogItem.Machine.Virtual.vSphere
data:
cpu: 1
memory:
min: 512
max: 8192
os_type: Linux
os_distribution: rhel
action: LinkedClone
archive_days: 1
provisioning_workflow: {id: CloneWorkflow}
lease_days: 3
379
Programming Guide
18.
19.
20.
21.
22.
23.
24.
25.
source_machine_name: cbp_centos_63_x86
cost_center: sales
_cluster: 2
apache:
type: Software.Apache
data:
host: '${_resource~web}'
http_port: 8080
Each of these lines plays an important role in the blueprint structure.
n
Lines 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.
n
Line 4 represents the blueprint components. Each key under components is the ID of the component
that must be unique under the current blueprint.
n
Lines 5 - 19 correspond to the Web component. The following appear under any component data:
n
The key type is mandatory and must refer to the component type on which the current
component is based.
n
The 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.
n
The key data defines the component configuration and appears under all component data.
n
n
Key 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
The 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.
n
Line 16 shows how to specify and entity reference field. The available sub-keys are id and label.
n
Line 24 depicts several things.
n
${} 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.
n
Whenever a property binding refers to output of some other component, it creates an implicit
dependency between components.
VMware, Inc.
380
Programming Guide
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.
VMware, Inc.
381
Programming Guide
Prerequisites
n
Log 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.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
Verify that there is a valid HTTP bearer token that matches your login credentials. See Chapter 2
REST API Authentication.
Procedure
1
Use 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-designerservice/api/content/bundles'
2
Use 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:
jsonAccepted
n
entityType
n
id
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/advanceddesigner-service/api/content/bundles/filters'
VMware, Inc.
382
Programming Guide
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:
data
n
Successful - Denotes the successful import or validation status at a particular component or
package level.
n
Partial - Denotes a scenario that warrants a system level warning. Alerts the user about a
possible error condition that the proposed action may create.
n
Failed - Denotes an import or validation failure at a particular component package level.
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:
n
entityType - (string) The ID for the entity being imported.
n
entitytId - (string) Unique content ID within the file system.
n
messageKey - (string)
n
logLevel - The logging level to use for any errors that occur.
n
message - Information returned by the provider.
n
entityName - (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-designerservice/api/content/bundles'
VMware, Inc.
383
Programming Guide
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"
} ]
}
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:
n
Using the vRealize Automation API Reference
n
View Reference Information for an API
n
Using vRealize CloudClient
n
Using 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:
n
In 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
Programming Guide
n
As a zip file on the Product Documentation and Related Information page of the vRealize Automation
Information Center.
n
In 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
1
From 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.
2
Scroll down to the bottom of the web page and select a category.
The HTTP operations in the category appear.
3
Click an operation to view the reference information.
Reference information for the selected API appears.
4
To display a list of the operations for a category , click List Operations next to a category name.
5
To 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.
6
To 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.
VMware, Inc.
386
Programming Guide
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.
n
Open a Chrome browser session and log in to the vRealize Automation console as a business group
user with access to catalog items.
n
Open a command prompt or a shell and log in to the vRealize Automation command line interface.
Procedure
1
Click the Catalog tab in the vRealize Automation console.
2
Click the catalog Item you want to request.
3
Enter the request information for the catalog item, but do not submit your changes.
4
Press the Ctrl-Shift-I keys simultaneously to open the Chrome Developer Tools. For example:
5
a
Click the Network tab.
b
Click Record Network Log.
c
Click Submit in the console.
Verify 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.
VMware, Inc.
387
Programming Guide
6
Enter 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.
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:
n
Published catalog items
n
Request status
n
Provisioned 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
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Author : VMware, Inc. Create Date : 2018:02:09 12:44:35-08:00 Modify Date : 2018:02:09 12:44:35-08:00 Creator : AH XSL Formatter V6.3 MR1 for Windows (x64) : 6.3.2.23978 (2016/03/18 11:26JST) Producer : Antenna House PDF Output Library 6.3.762 (Windows (x64)) Title : Programming Guide - vRealize. Automation 7.1 Trapped : False Page Count : 389 Page Mode : UseOutlines Page Layout : SinglePage Language : ENEXIF Metadata provided by EXIF.tools