VMware vRealize Automation - 7.3 Programming Guide
Programming Guide
vRealize Automation 7.3
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–2017 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc. 2
Contents
vRealize Automation Programming Guide 7
Updated Information 8
Overview of the vRealize Automation REST API 9
1
REST API Services 9
Using the vRealize Automation REST API 11
About the API Use Cases 12
REST API Authentication 13
2
About HTTP Bearer Tokens 13
Configure the Duration of an HTTP Bearer Token 14
Request an HTTP Bearer Token 14
Syntax for Requesting an HTTP Bearer Token 16
Validate an HTTP Bearer Token 17
Delete an HTTP Bearer Token 18
Creating a Tenant 20
3
Prerequisites for Creating a Tenant 20
Create a Tenant With Parameters Inline 20
Create a Tenant With a JSON File 23
Identity Service Examples for Creating a Tenant 25
Syntax for Displaying Your Current Tenants 26
Syntax for Requesting a New Tenant 28
Syntax for Listing All Tenant Identity Stores 31
Syntax for Linking an Identity Store to the Tenant 33
Syntax for Searching LDAP or Active Directory for a User 37
Syntax for Assigning a User to a Role 38
Syntax for Displaying all Roles Assigned to a User 39
VMware, Inc.
Requesting a Machine 42
4
Request a Machine 42
Catalog Service Examples for Requesting a Machine 44
Syntax for Listing Shared and Private Catalog Items 44
Syntax for Getting Information for a Catalog Item 48
Syntax for Getting a Template Request for a Catalog Item 52
Syntax for Requesting a Machine 55
Syntax for Viewing Details of a Machine Request 59
3
Programming Guide
Approving a Machine Request 63
5
Approve a Machine Request 63
Work Item Service Examples for Approving a Machine Request 64
Syntax for Listing Work Items 65
Syntax for Getting Work Item Details 71
Syntax for Constructing a JSON File to Approve a Machine Request 76
Syntax for Approving a Submitted Machine Request 79
Syntax for Updating Price Information 81
Listing Provisioned Resources 85
6
Prerequisites for Listing Provisioned Resources 85
Display Your Provisioned Resources Example 85
Display Provisioned Resources by Resource Type Example 89
Display All Available Resource Types Example 92
Display Provisioned Resources by Business Groups You Manage Example 94
View Machine Details Example 103
Managing Provisioned Deployments 107
7
Manage Provisioned Deployments 107
Power Off 108
Change Lease 109
Catalog Service Examples for Managing Provisioned Deployments 111
Syntax for Getting Deployment Details 111
Syntax for Navigating to the Children of a Deployed Resource 115
Working with Reservations 122
8
Prerequisites for Working With Reservations 123
Create a Reservation 123
Display a List of Supported Reservation Types 124
Displaying a Schema Definition for a Reservation 127
Get the Business Group ID for a Reservation 153
Get a Compute Resource for the Reservation 155
Getting a Resources Schema by Reservation Type 158
Creating a Reservation By Type 162
Verify a Reservation and Get Reservation Details 173
Display a List of Reservations 181
Update a Reservation 186
Delete a Reservation 191
Service Examples for Working with Reservations 191
Syntax for Displaying a List of Reservations 193
Syntax for Displaying a Schema Definition for a vSphere Reservation 199
VMware, Inc. 4
Programming Guide
Syntax for Displaying a Schema Definition for an Amazon Reservation 206
Syntax for Displaying a Schema Definition for a vCloud Air Reservation 221
Syntax for Getting the Business Group ID for a Reservation 233
Syntax for Getting a Compute Resource for a Reservation 236
Syntax for Getting Resources Schema for a vSphere Reservation 240
Syntax for Getting Resources Schema for an Amazon Reservation 242
Syntax for Getting Resources Schema for a vCloud Air Reservation 245
Syntax for Creating a vSphere Reservation 249
Syntax for Creating an Amazon Reservation 254
Syntax for Creating a vCloud Air Reservation 257
Syntax for Verifying a Reservation and Getting Reservation Details 262
Syntax for Displaying a List of Supported Reservation Types 270
Syntax for Updating a Reservation 275
Syntax for Deleting a Reservation 280
Working with Reservation Policies 282
9
Prerequisites for Working with Reservation Policies 282
List Reservation Policies Example 282
Create a Reservation Policy Example 284
Display a Reservation Policy by ID Example 286
Update a Reservation Policy Example 287
Deleting a Reservation Policy Example 288
Working with Key Pairs 290
10
Prerequisites for Working with Key Pairs 290
Get a Key Pair List Example 290
Create a Key Pair Example 293
Query a Key Pair Example 296
Update a Key Pair Example 298
Delete a Key Pair Example 299
Working with Network Profiles 301
11
Prerequisites for Working With Network Profiles 303
Get a Network Profile List Example 303
Create an External Network Profile Without IPAM Example 312
Create an External Network Profile Using External IPAM Example 314
Query a Network Profile Example 317
Update a Network Profile Example 321
Delete a Network Profile Example 322
Getting a List of Available IP Ranges 324
12
Get a List of Available IP Ranges for an IPAM Provider 324
VMware, Inc. 5
Programming Guide
Importing and Exporting Content 342
13
Understanding Blueprint Schema 343
Prerequisites for Importing and Exporting Content 345
List Supported Content Types Example 345
List Available Content Example 349
Filter Content by Content Type Example 354
Create a Package for Export Example 355
List Packages in the Content Service Example 356
Export a Package Example 360
Validate a Content Bundle Before Importing example 360
Import a Package Example 363
Export XaaS Content Example 364
Import XaaS Content Example 365
Related Tools and Documentation 367
14
Viewing API Reference Information 367
Using vRealize CloudClient 368
Using Third Party Tools 368
Filtering and Formatting REST API Information 370
15
VMware, Inc. 6
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 the vRealize
Automation API Reference at https://code.vmware.com/apis/vrealize-automation.
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.
7
Updated Information
This Programming Guide is updated with each release of the product or when necessary.
This table provides the update history of the Programming Guide.
Revision Description
002448-01
002448-00 Initial release.
n
Removed Day 2 action terminology from Chapter 7 Managing Provisioned Deployments.
n
Clarified procedure in Viewing API Reference Information.
VMware, Inc. 8
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.
This chapter includes the following topics:
n
REST API Services
n
Using the vRealize Automation REST API
n
About the API Use Cases
REST API Services
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.
VMware, Inc. 9
Programming Guide
Table 1‑1. vRealize Automation REST API Services (Continued)
Service Description
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.
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.
Placement Service Provides vRealize Automation with recommendations for the placement
of deployments. With cluster health information from an external service
such as vRealize Operations Manager, the service can recommend
reservations to use for the provisioning of blueprint components.
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 component, software 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.
VMware, Inc. 10
Programming Guide
Table 1‑1. vRealize Automation REST API Services (Continued)
Service Description
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.
Using the vRealize Automation REST API
To make vRealize Automation REST API service calls, you can use a browser application or an HTTP
client program to send requests and review responses.
REST Client Programs
Any client application that can send HTTPS requests is an appropriate tool for developing REST
applications with the vRealize Automation API. The following open-source programs are commonly used:
n
cURL. http://curl.haxx.se
n
Postman application. http://www.getpostman.com
About the API Reference
The vRealize Automation API Reference lists all REST API service calls. It is provided as a Swagger
document and is available in either of the following ways.
n
If vRealize Automation is installed, documentation is available with the product.
n
A list of general services
https://$vRA/component-registry/services/docs
n
A list of installation and configuration services
https://$vRA:5480/config/
$vRA denotes an instance of vRealize Automation.
n
If vRealize Automation is not installed, documentation is available from the APIs section for the
vRealize Automation API at VMware{code} or, https://code.vmware.com/apis/vrealize-automation.
For information about using the vRealize Automation API Reference, see Viewing API Reference
Information.
VMware, Inc. 11
Programming Guide
About the API Use Cases
While the vRealize Automation API Reference contains a menu that lists all REST API service calls, it
does not document use cases. The Programming Guide provides frequently used use cases including
sample requests and responses.
The following REST API 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. Each includes service examples that provide syntax for the calls
referenced in the use case.
n
Chapter 3 Creating a Tenant
n
Chapter 4 Requesting a Machine
n
Chapter 5 Approving a Machine Request
n
Chapter 6 Listing Provisioned Resources
n
Chapter 7 Managing Provisioned Deployments
n
Chapter 8 Working with Reservations
n
Chapter 9 Working with Reservation Policies
n
Chapter 10 Working with Key Pairs
n
Chapter 11 Working with Network Profiles
n
Chapter 12 Getting a List of Available IP Ranges
n
Chapter 13 Importing and Exporting Content
curl is used for example requests. Request headers required by the API are included in example requests
that are not fragments of a larger example. The variable $vRA represents the appliance name.domain
name of the vRealize Automation server in all URLs.
Most example responses show only those elements and attributes that are relevant to the operation being
discussed. Ellipses (...) indicate omitted content within response bodies.
Postman collections are not used in the API examples, but are available from the Code Samples section
for the vRealize Automation API at VMware{code} or, https://code.vmware.com/apis/vrealize-automation.
VMware, Inc. 12
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.
This chapter includes the following topics:
n
About HTTP Bearer Tokens
n
Configure the Duration of an HTTP Bearer Token
n
Request an HTTP Bearer Token
n
Validate an HTTP Bearer Token
n
Delete an HTTP Bearer Token
About 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 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 token calls:
https://$vRA/identity/api/tokens
The variable $vRA represents the appliance name.domain name of the vRealize Automation server
such as, vra-appliance-name.company.com.
VMware, Inc.
13
Programming Guide
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.
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 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 details regarding input, output, and response codes, see Syntax for Requesting an HTTP Bearer
Token.
VMware, Inc. 14
Programming Guide
Prerequisites
n
Secure a channel between the web browser and the vRealize Automation server. Open a browser
and enter the URL such as:
https://vra-appliance-name.company.com
The system warns that your connection is not private. Click through to confirm the security exception
and establish an SSL handshake.
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 appliance name and fully qualified domain name of the vRealize Automation instance
are available.
Procedure
1 Enter the command to request the HTTP bearer token.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"vra-user@company.com","password":"vra-user-password","tenant":"company.com"}'
https://$vRA/identity/api/tokens
In this example, $vRA is an instance of vRealize Automation. The --insecure flag is included so that
the request will return a response even if the traffic is not secured with a trusted certificate.
2 Examine the response.
A successful request returns an HTTP bearer token that you include in subsequent API requests.
3 For convenience, store the token in a variable.
export token="EXAMPLE-TOKEN-TEXT"
Example: Token Request and Response
The following sample displays output based on the example request.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"vra-user@company.com","password":"vra-user-password","tenant":"company.com"}'
https://$vRA/identity/api/tokens
{"expires":"2017-04-14T04:46:43.000Z","id":"MTQ5Mj ... M2RmMA==","tenant":"company.com"}
The id is the bearer token to store for future use.
export token="MTQ5Mj ... M2RmMA=="
VMware, Inc. 15
Programming Guide
If the credentials supplied in the Authorization header are invalid, the response includes status code 401
as in the following output.
<!DOCTYPE html><html><head><title>Error report</title></head><body><h1>HTTP Status 401 -
Authentication required</h1></body></html>
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
obtain a bearer token by authenticating to the identity service.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/identity/api/tokens
$vRA appliance name.domain name of the vRealize Automation server.
usrname Tenant administrator user name.
passwd Tenant administrator password.
tenantURLtoken Tenant URL token determined by the system administrator when creating the tenant such
as, support.
Output
The following information is displayed as a result of your HTTP bearer token request.
Parameter 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.
VMware, Inc. 16
Programming Guide
Example: curl Command to Request HTTP Bearer Token
The following example command requests an HTTP bearer token.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}' https://$vRA/identity/api/tokens
When your request succeeds, the system returns the expiration date and time of the token, and the HTTP
bearer token.
Validate an HTTP Bearer Token
You can validate an existing HTTP bearer token.
Prerequisites
n
Request an HTTP Bearer Token.
Procedure
1 Enter the command to validate the HTTP bearer token.
curl --insecure -I -H "Accept: application/json" -H "Authorization: Bearer $token" -H "Cache-
Control: no-cache" "https://$vRA/identity/api/tokens/$token"
2 Examine the response.
A successful request returns status code 204.
Example: Validate Token Request and Response
The following sample displays output based on the example request.
curl --insecure -I -H "Accept: application/json" -H "Authorization: Bearer $token" -H "Cache-Control:
no-cache" "https://$vRA/identity/api/tokens/$token"
HTTP/1.1 204
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Date: Thu, 13 Apr 2017 21:56:02 GMT
X-Frame-Options: SAMEORIGIN
The server returns one of the following status codes.
VMware, Inc. 17
Programming Guide
Table 2‑1. Status Codes for Validate a Bearer Token
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
1 Enter the command to delete the HTTP bearer token, as in the following example.
curl --insecure -X DELETE -H "Accept: application/json" -H "Authorization: Bearer $token" -H
"Cache-Control: no-cache" "https://$vRA/identity/api/tokens/$token"
2 Examine the response.
A successful request returns status code 204.
Example: Delete Token Request and Response
The following sample displays output based on the example request.
curl --insecure -X DELETE -H "Accept: application/json" -H "Authorization: Bearer $token" -H "Cache-
Control: no-cache" "https://$vRA/identity/api/tokens/$token"
204 NO CONTENT
The server returns one of the following status codes.
Table 2‑2. Status Codes for Delete a Bearer Token
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.
VMware, Inc. 18
Programming Guide
Table 2‑2. Status Codes for Delete a Bearer Token (Continued)
Status Code Description
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. 19
Creating a Tenant 3
You use the identity service to create a tenant.
The identity service is comprised of two components: authentication and authorization. The authentication
component manages tenants, groups, users, and identity stores. Creating a tenant is an authentication
example.
Two use cases show how to create a tenant, either with parameters inline or with input values in a JSON
file. After creating a tenant, you can use other service examples to perform additional authentication and
authorization functions.
For general information about creating and working with tenants, see Configuring vRealize Automation in
the vRealize Automation information center.
This chapter includes the following topics:
n
Prerequisites for Creating a Tenant
n
Create a Tenant With Parameters Inline
n
Create a Tenant With a JSON File
n
Identity Service Examples for Creating a Tenant
Prerequisites for Creating a Tenant
Satisfy the following conditions before performing any tasks for this use case.
n
Log in to vRealize Automation as a system administrator and a tenant administrator.
n
Verify that the appliance 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.
Create a Tenant With Parameters Inline
To create a tenant with parameters inline, you first display all available tenants then request a new tenant
with input parameters specified inline.
VMware, Inc.
20
Programming Guide
Prerequisites
In addition to the Prerequisites for Creating a Tenant, verify that you have parameter values for the new
tenant.
Procedure
1 Use the identity service to display all the available tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
For details regarding input and output of this sample, see Syntax for Displaying Your Current Tenants.
2 Examine the response to verify that the tenant you plan to create is not listed.
See the output of the request to display all tenants Example: Create a Tenant With Parameters Inline.
3 Submit a request for a new tenant with parameters inline.
curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type: application/json" -H
"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
'{"@type":"Tenant","id":"rainpole","urlName":"rainpole","name":"rainpoleTenant","description":"New
Custom Tenant","contactEmail":"admin@vmware.com","defaultTenant":false}'
For details regarding input and output of this sample, see Syntax for Requesting a New Tenant
4 Use the identity service to display all the available tenants again.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
5 Examine the response to verify that the tenant you requested is listed.
See the output of the request to verify the new tenant is created Example: Create a Tenant With
Parameters Inline.
Example: Create a Tenant With Parameters Inline
The following sample output for Step 1 lists three tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
{
"links":[],
"content"[
{"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",
"defaultTenant":true},
VMware, Inc. 21
Programming Guide
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...}
],
"metadata":{"size":20,"totalElements":3,"totalPages":1,"number":1,"offset":0}
}
The following sample output for Step 3 shows that the tenant named rainpole has been created.
curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type: application/json" -H
"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
'{"@type":"Tenant","id":"rainpole","urlName":"rainpole","name":"rainpoleTenant","description":"New
Custom Tenant","contactEmail":"admin@vmware.com","defaultTenant":false}'
{
"id":"rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"admin@vmware.com",
"defaultTenant":false
}
The following sample output for Step 4 lists four tenants including rainpole.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
{
"links":[],
"content":[
{"@type":"Tenant",
"id":"vsphere.local",
...},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...},
{"@type":"Tenant",
"id":"rainpole",
...}
],
"metadata":{"size":20,"totalElements":4,"totalPages":1,"number":1,"offset":0}
}
VMware, Inc. 22
Programming Guide
Create a Tenant With a JSON File
To create a tenant with a JSON file, you first display all available tenants then request a new tenant with
input parameters. The input parameters are specified in a separate JSON file that you call from the
request.
Prerequisites
In addition to the Prerequisites for Creating a Tenant, verify that you have parameter values for the new
tenant required for the JSON file input.
Procedure
1 Use the identity service to display all the available tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
For details regarding input and output of this sample, see Syntax for Displaying Your Current Tenants.
2 Examine the response to verify that the tenant you plan to create is not listed.
See the output of the request to display all tenants Example: Create a Tenant With a JSON File.
3 Create a JSON file for the new tenant request to call.
The newTenant.json file contains information about the new tenant.
{
"@type":"Tenant",
"id":"rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"admin@vmware.com",
"defaultTenant":false
}
4 Submit a request for a new tenant that calls the JSON file.
curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type:application/json" -H
"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
@C:/Temp/newTenant.json
For details regarding input and output of this sample, see Syntax for Requesting a New Tenant
5 Use the identity service to display all the available tenants again.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
VMware, Inc. 23
Programming Guide
6 Examine the response to verify that the tenant you requested is listed.
See the output of the request to verify the new tenant is created Example: Create a Tenant With a
JSON File.
Example: Create a Tenant With a JSON File
The following sample output for Step 1 lists three tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
{
"links":[],
"content"[
{"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",
"defaultTenant":true},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...}
],
"metadata":{"size":20,"totalElements":3,"totalPages":1,"number":1,"offset":0}
}
The following sample output for Step 4, shows that the tenant named rainpole has been created.
curl -X PUT --insecure -H "Accept:application/json" -H "Content-Type:application/json" -H
"Authorization: Bearer $token" https://$vRA/identity/api/tenants/rainpole --data
@C:/Temp/newTenant.json
{
"id": "rainpole",
"urlName":"rainpole",
"name":"rainpoleTenant",
"description":"New Custom Tenant",
"contactEmail":"admin@vmware.com",
"password":"",
"defaultTenant":false
}
The following sample output for Step 5 lists four tenants including rainpole.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
{
"links":[],
VMware, Inc. 24
Programming Guide
"content":[
{"@type":"Tenant",
"id":"vsphere.local",
...},
{"@type":"Tenant",
"id":"qe",
...},
{"@type":"Tenant",
"id":"management",
...},
{"@type":"Tenant",
"id":"rainpole",
...}
],
"metadata":{"size":20,"totalElements":4,"totalPages":1,"number":1,"offset":0}
}
Identity Service Examples for Creating a Tenant
Syntax for each service example lists input parameters, output parameters, and curl commands.
n
Syntax for Displaying Your Current Tenants
GET /api/tenants lists all the vRealize Automation tenants in your system.
n
Syntax for Requesting a New Tenant
PUT /api/tenants/{tenantId} submits a request to create or update a tenant. You can specify
request parameters using JSON command line input or by calling an existing JSON file from the
command line.
n
Syntax for Listing All Tenant Identity Stores
GET /api/tenants/{tenantId}/directories lists 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
PUT /api/tenants/{tenantId}/directories/{id} links 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
GET /api/tenants/{tenantId}/principals/{userId} searches the configured LDAP directory,
Active Directory, or Native Active Directory for a user.
n
Syntax for Assigning a User to a Role
PUT /api/authorization/tenants/{tenantId}/principals/{principalId}/scopes/{scope
Id}/roles/{scopeRoleId} assigns a user to a role.
n
Syntax for Displaying all Roles Assigned to a User
GET /api/authorization/tenants/{tenantId}/principals/{principalId}/roles displays
all of the roles assigned to a user.
VMware, Inc. 25
Programming Guide
Syntax for Displaying Your Current Tenants
GET /api/tenants lists all the vRealize Automation tenants in your system.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/identity/api/tenants
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation 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. 26
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
Specifies the application or service that determines the other names.
n
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: Specifies the name of the tenant as it appears in URLs.
n
Name: Specifies the name of the tenant for display purposes.
n
description: Specifies the long description of the tenant.
n
contactEmail: Specifies the primary contact email address.
n
Password: Unused
n
defaultTenant: Is set to True if the corresponding tenant is the default tenant (vsphere.local).
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.
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 to Display Current Tenants
The following example command displays all available tenants.
curl --insecure -H "Accept:application/json" -H "Authorization: Bearer $token"
https://$vRA/identity/api/tenants
The response in JSON lists the current tenants. Format the output to improve its readability. For
information about formatting output, see Chapter 15 Filtering and Formatting REST API Information.
{
"links":[],
"content"[
{
"@type":"Tenant",
"id":"vsphere.local",
"urlName":"vsphere.local",
VMware, Inc. 27
Programming Guide
"name":"vsphere.local",
"description":null,
"contactEmail":null,
"password":"",
"defaultTenant":true
},
{
"@type":"Tenant",
"id":"qe",
"urlName":"qe",
"name":"QETenant",
"description":"Precreated test tenant",
"contactEmail":null,
"password":"",
"defaultTenant":false
}
{
"@type":"Tenant",
"id":"management",
"urlName":"management",
"name":"Management-ITTenant",
"description":"Precreated test tenant",
"contactEmail":null,
"password":"",
"defaultTenant":false
}
],
"metadata":{
"size":20,
"totalElements":3,
"totalPages":1,
"number":1,
"offset":0
}
}
Syntax for Requesting a New Tenant
PUT /api/tenants/{tenantId} submits a request to create or update a tenant. You can specify
request parameters using JSON command line input or by calling an existing JSON file from the
command line.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$vRA/identity/api/tenants/$tenantId --data @$inputFileName.json
$vRA Specifies the appliance name and fully qualified domain name, or IP address of the
vRealize Automation server.
$token Specifies a valid HTTP bearer token with necessary credentials.
VMware, Inc. 28
Programming Guide
Parameter Description
$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.
$password Optional password for the new tenant. If blank, no password is required.
JSON Input File Template
To simplify command line input, you can call a JSON file with input parameters from the command line.
You create the JSON file using a text editor, replacing italicized variables in the following template with
your specific values.
{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"password": "$password",
"defaultTenant" : false
}
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 29
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
Specifies the application or service that determines the other names.
n
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: Specifies the name of the tenant as it appears in URLs.
n
Name: Specifies the name of the tenant for display purposes.
n
description: Specifies the long description of the tenant.
n
contactEmail: Specifies the primary contact email address.
n
Password: Unused
n
defaultTenant: Is set to True if the corresponding tenant is the default tenant
(vsphere.local).
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.
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 to Request a New Tenant With JSON File
The following sample newTenant.json file contains parameters for the tenant request.
{
"@type" : "Tenant",
"id" : "rainpole",
"urlName" : "rainpole",
"name" : "rainpoleTenant",
"description" : "New Custom Tenant",
"contactEmail" : null,
"password": "",
"defaultTenant" : true
}
VMware, Inc. 30
Loading...