VRealize Operations Manager API Programming Guide VRealize 6.5 65

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 32

vRealize Operations Manager API
Programming Guide
vRealize Operations Manager 6.5
This document supports the version of each product listed and
supports all subsequent versions until the document is
replaced by a new edition. To check for more recent editions of
this document, see http://www.vmware.com/support/pubs.
EN-002458-00
vRealize Operations Manager API Programming Guide
2 VMware, Inc.
You can find the most up-to-date technical documentation on the VMware Web site at:
hp://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2017 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
Contents
1About This Programming Guide 5
2Understanding the vRealize Operations Manager API 7
How the vRealize Operations Manager API Works 7
Client Workow Overview 8
Using the API with VMware vRealize Operations Manager 12
3Geing Started with the
API 13
Acquire an Authentication Token 13
Find the Adapter Type and Object Type 14
Generate a List of All Metrics for the Object 16
4Conguring an Adapter
Instance 19
Summary of Conguring an Adapter Instance Requests 19
Identify the Solution and Its Adapters 20
Identify the Object Types Required for the Adapter 21
Create the Adapter Instance 23
Provide Proof of Certicate Validity 26
Start Monitoring the New Adapter Instance 30
Index 31
VMware, Inc. 3
vRealize Operations Manager API Programming Guide
4 VMware, Inc.
About This Programming Guide 1
The vRealize® Operations Manager™ API Programming Guide provides information about the
VMware vRealize Operations Manager REST APIs, including how to use the REST API resources,
authenticate, and construct REST API calls.
Intended Audience
This information is intended for administrators and programmers who want to congure and manage
vRealize Operations Manager programmatically using the vRealize Operations Manager REST API. The
guide focuses on common use cases.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For denitions
of terms as they are used in VMware technical documentation, go to
hp://www.vmware.com/support/pubs.
VMware, Inc. 5
vRealize Operations Manager API Programming Guide
6 VMware, Inc.
Understanding the
vRealize Operations Manager API 2
Developers can use the API to build interactive clients of vRealize Operations Manager. The API follows the
REST style and is available to all licensed users.
vRealize Operations Manager clients communicate with the server over HTTP, exchanging representations
of vRealize Operations Manager objects. These representations take the form of JSON or XML elements. You
use HTTP GET requests to retrieve the current representation of an object, HTTP POST and PUT requests to
create or modify an object, and HTTP DELETE requests to delete an object.
This chapter includes the following topics:
n“How the vRealize Operations Manager API Works,” on page 7
n“Client Workow Overview,” on page 8
n“Using the API with VMware vRealize Operations Manager,” on page 12
How the vRealize Operations Manager API Works
You use a Web browser to communicate with the vRealize Operations Manager analytics engine, either
through the product user interface or through API calls.
Figure 2‑1. vRealize Operations Manager Simplified Architecture
The adapter instance collects data from objects in your monitored environment. The
vRealize Operations Manager analytics engine processes the data and displays the complete model in the
graphical interface.
VMware, Inc. 7
Why Use the API
The API is most useful when there is a need to automate a well-dened workow, such as repeating the
same tasks to congure access control for new vRealize Operations Manager users. The API is also useful
when performing queries on the vRealize Operations Manager data repository, such as retrieving data for
particular assets in your virtual environment. In addition, you can use the API to extract all data from the
vRealize Operations Manager data repository and load it into a separate analytics system.
vRealize Operations Manager Terminology
The XML syntax you use to describe the objects for an adapter corresponds to the API code syntax but
diers from what you nd in the user interface. The following terms appear in the user interface. Included
with the description of each term is the corresponding XML syntax used in an API call.
Adapter types Denes the adapter used to discover particular object types. For example, the vCenter adapter discovers
objects connected to vSphere datacenters. The EMC adapter discovers EMC storage system objects.
XML syntax: adapterkinds.
Object types The class of entities that represent objects or information sources. Objects report data to the
vRealize Operations Manager analytics engine. Virtual machines, datastores, and host systems are
examples of object types dened in a vCenter adapter model.
XML syntax: resourcekinds.
Client Workflow Overview
vRealize Operations Manager API clients implement a REST workow, making HTTP requests to the server
and retrieving the information they need from the server’s responses.
About REST
REST, an acronym for Representational State Transfer, describes an architectural style characteristic of
programs that use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects
between a client and a server. In the vRealize Operations Manager API, these representations are JSON or
XML documents.
In a REST workow, representations of objects are passed back and forth between a client and a server with
the explicit assumption that neither party need know anything about an object other than what is presented
in a single request or response. The URLs at which these documents are available often persist beyond the
lifetime of the request or response that includes them.
REST API Workflows
Application programs wrien to use a REST API use HTTP requests that are often executed by a script or
other higher-level language to make remote procedure calls that create, retrieve, update, or delete objects
that the API denes . In the vRealize Operations Manager REST API, these objects are dened by a
collection of XML schemas. The operations themselves are HTTP requests, and so are generic to all HTTP
clients.
To write a REST API client application, you must understand only the HTTP protocol, and the semantics of
JSON or XML, the transfer format that the vRealize Operations Manager API uses. To use the API eectively
in such a client, you must become familiar with the following concepts.
nThe set of objects that the API supports, and what they represent.
nHow the API represents these objects.
vRealize Operations Manager API Programming Guide
8 VMware, Inc.
nHow a client refers to an object on which it wants to operate.
The API reference includes a complete list of API requests. See “About the Schema Reference,” on page 12.
vRealize Operations Manager API REST Requests
To retrieve object representations, clients make HTTP requests to object references.
Security
The HTTP link between an API client and server is established using SSL. API clients congure either basic
authentication or token-based authentication to communicate with the server. If token-based authentication
is used, the API client must complete a login request to receive an authentication token that is included in all
subsequent requests .
Figure 2‑2. Scenario: Provide user credentials to obtain details about alert with ID 123
With basic authentication, you must pass valid user credentials with every API request. To prevent user
credentials from being passed as clear text, the vRealize Operations Manager API server supports HTTPS
communication only . The following example presents a basic authentication scenario using curl.
1 You obtain valid user credentials for your vRealize Operations Manager instance, such as user name
example_user, password simple_pass.
2 If you want to obtain information about a resource with ID 00000000-0000-0000-2222-000000000002, you
run the curl command:
curl --user example_user:simple_pass https://RESTendpoint.example.com/suite-
api/api/resources/00000000-0000-0000-2222-000000000002
3 The API server extracts credentials from the HTTP header authorization and checks the user
credentials. If the credentials are valid, it performs a read operation and returns the requested
information about the resource.
With token-based authentication, you POST a login request to the vRealize Operations Manager API server,
supplying valid user credentials to obtain an authentication token. The following example presents a token-
based authentication scenario.
1 You obtain valid user credentials for your vRealize Operations Manager instance.
Chapter 2 Understanding the vRealize Operations Manager API
VMware, Inc. 9
2 POST a request to the REST endpoint for authentication.
POST https://RESTendpoint.example.com/api/token/acquire
The request body includes the user name, password, and authentication source.
3 In the response body, the endpoint returns the token, expiry date and time.
4 For further communication, you include the token object in the Authorization header with the format :
Authorization: vRealizeOpsToken <vROps_token>
Alternatively, if you acquired the token from an SSO source, the Authorization header is of the format:
Authorization: SSO2Token <SSO_SAML_TOKEN>
5 You can invalidate the token before the expiration date and time by sending a POST request to the
logout endpoint.
POST https://RESTendpoint.example.com/api/token/release
Request Headers
The following HTTP headers are typically included in API requests:
Accept-Language To specify the language desired in responses, use the Accept-Language request header. Message
strings in ErrorType responses are localized. To request a response with message strings localized to
French, use the following header:
Accept-Language: fr-FR
Authorization All requests to create an API session must include an Authorization header of the form prescribed
by the identity provider that your organization uses
Content-Type Requests that include a body must include an appropriate HTTP Content-Type header.
nFor a request body in XML, the header must include Content-Type: application/xml
nFor a request body in JSON, the header must include Content-Type: application/json
Accept To specify the desired response format , include the Accept request header.
nFor a response in XML, the header must include Accept: application/xml
nFor a response in JSON, the header must include Accept: application/json
Request Bodies in XML
For a request body wrien in XML, vRealize Operations Manager uses a validating XML parser that
requires elements in a request body to agree with the schema in order and number . Request bodies are
rejected as invalid unless they meet the following criteria:
nXML namespace aributes must be supplied for all namespaces represented by elements in the request.
nIf multiple namespaces are represented in the request, XML namespace aributes must include an
identifying prex, and that prex must be used with all elements from that namespace.
nAll required elements must appear in request bodies. All elements that appear in request bodies must
appear in the order that the schema establishes, and with content that conforms to the type constraint
that the schema species.
vRealize Operations Manager API REST Responses
All responses include an HTTP status code and, unless the status code is 204 (No Content), an Accept
header. Response content depends on the request. Some responses include a document body, some include
only a URL, and some are empty.
HTTP Response Codes
An API client can expect a subset of HTTP status codes in a response.
vRealize Operations Manager API Programming Guide
10 VMware, Inc.
Table 2‑1. HTTP Status Codes that the API Returns
Status Code Status Description
200 OK The request is valid and was completed. The response
includes a document body.
201 Created The request is valid. The requested object was created and
can be found at the URL specied in the Location header.
202 Accepted The request is valid and a task was created to handle it.
This response is usually accompanied by a TaskStatus
element .
204 No Content The request is valid and was completed. The response does
not include a body.
400 Bad Request The request body is malformed, incomplete, or otherwise
invalid.
401 Unauthorized Login failed or authentication token has expired.
403 Forbidden The user is not authenticated or does not have adequate
privileges to access one or more objects specied in the
request.
404 Not Found The object specied in the request could not be found.
405 Method Not Allowed The HTTP method specied in the request is not supported
for this object.
406 Not Acceptable The resource identied by the request is not capable of
generating a response of the type specied in the request's
Accept header.
415 Unsupported Media Type The resource identied by the request does not support a
request of the specied Content-Type and HTTP method.
422 Not Found Usually indicates a malformed request URL or request
body.
429 Too Many Requests A client has sent too many requests or multiple clients are
sending too many simultaneous requests and the server is
unable to process them due to rate limits.
To work around the problem, try sending the request again
later.
500 Internal Server Error The request was received but could not be completed
because of an internal error on the server.
503 Service Unavailable The server is currently unable to handle the request due to
a temporary condition such as resource exhaustion or
server maintenance.
504 Gateway Timeout The server, while acting as a gateway or proxy, did not
receive a timely response from the upstream server
specied by the request URL.
Chapter 2 Understanding the vRealize Operations Manager API
VMware, Inc. 11
Using the API with VMware vRealize Operations Manager
VMware vRealize Operations Manager 6.0 and later versions support the vRealize Operations Manager
REST API. You can use a browser or an HTTP client program to send requests and receive responses.
REST Client Programs
Any client application that can send HTTPS requests is an appropriate tool for developing REST
applications with the VMware vRealize Operations Manager API. REST client plug-ins are available for
most browsers and many IDEs. The following open-source programs are commonly used:
ncURL. hp://curl.haxx.se
nPostman application. hp://www.getpostman.com
In addition, VMware provides language-specic client bindings for the
VMware vRealize Operations Manager API. See “About the Schema Reference,” on page 12.
About the Schema Reference
The VMware vRealize Operations Manager REST API documentation includes reference material for all
elements, types, queries, and operations in the VMware vRealize Operations Manager API. It also includes
the schema denition les.
The reference is available in HTML format and is installed with your VMware vRealize Operations Manager
instance. For example, if the URL of your VMware vRealize Operations Manager instance is
https://vrealize.example.com, the API reference is available from: https://vrealize.example.com/suite-
api/docs/rest/index.html.
Language-specic client bindings are available from:
https://vrealize.example.com/suite-api/
About the VMware vRealize Operations Manager API Examples
All examples include HTTP requests and responses. These examples show the workow and content
associated with operations such as creating and querying for information about objects in your monitored
environment.
Example request bodies are in JSON. Request headers required by the
VMware vRealize Operations Manager API are included in example requests that are not fragments of a
larger example.
Most example responses show only those elements and aributes that are relevant to the operation being
discussed. Ellipses (...) indicate omied content within response bodies.
vRealize Operations Manager API Programming Guide
12 VMware, Inc.
Getting Started with the API 3
API clients and vRealize Operations Manager servers communicate over HTTPS, exchanging XML
representations of API objects.
This simple example of a REST API workow shows how to obtain a list of all metrics for a virtual machine
object type that is included in the model denition of the VMware vCenter® adapter. Using the API, you can
obtain the complete list of available metrics for any object type.
This chapter includes the following topics:
n“Acquire an Authentication Token,” on page 13
n“Find the Adapter Type and Object Type,” on page 14
n“Generate a List of All Metrics for the Object,” on page 16
Acquire an Authentication Token
vRealize Operations Manager requires API requests to be authenticated The rst step in this workow is to
obtain an authentication token.
To obtain an authentication token, the login request supplies the user credentials in a form that Basic HTTP
authentication requires. In this example, the user is logging in to a vRealize Operations Manager instance
with URL https://vrealize.example.com/.
Note This example uses token-based authentication. The vRealize Operations Manager API also supports
basic authentication. For more information regarding authentication mechanisms, see “Security,” on page 9
Prerequisites
nSecure a channel between the web browser and the vRealize Operations Manager server. Open a
browser and enter the URL of a vRealize Operations Manager instance such as:
https://vrealize.example.com
The system warns that your connection is not private. Click through to conrm the security exception
and establish an SSL handshake.
nVerify that you can access the APIs. Enter the URL of your vRealize Operations Manager instance with
suite-api/docs/rest/index.html added to the end, such as:
https://vrealize.example.com/suite-api/docs/rest/index.html
nVerify that you have the login credentials for a user of your vRealize Operations Manager instance.
VMware, Inc. 13
Procedure
1 POST a request to the login URL to acquire a token.
POST https://vrealize.example.com/suite-api/api/auth/token/acquire
See “Example: Login Request and Response,” on page 14.
2 Examine the response.
A successful request returns an ops authorization token, which you must included in subsequent API
requests.
Example: Login Request and Response
This example shows a request and response for a user with login username: vRealize-user and password:
vRealize-dummy-password.
Request header:
POST https://vrealize.example.com/suite-api/api/auth/token/acquire
Content-Type: application/json
Accept: application/json
Request body in JSON format:
{
"username" : "vRealize-user",
"password" : "vRealize-dummy-password"
}
Response in JSON:
200 OK
{
"token": "8f868cca-27cc-43d6-a838-c5467e73ec45::77cea9b2-1e87-490e-b626-e878beeaa23b",
"validity": 1470421325035,
"expiresAt": "Friday, August 5, 2016 6:22:05 PM UTC",
"roles": []
}
The response code indicates whether the request succeeded, or how it failed.
nIf the request is successful, the server return HTTP response code 200 (OK) and re-usable ops
authorization token that expires after six hours. This token must be included in each subsequent API
request.
nIf the authorization header is missing for the request, the server returns HTTP response code 403.
nIf the credentials supplied in the Authorization header are invalid, the server returns HTTP response
code 401.
Find the Adapter Type and Object Type
Your vRealize Operations Manager instance includes multiple adapter types. To nd the adapter type for
the vCenter adapter, you make a GET request to retrieve a list of all adapter types. The API response
includes all the object types that the adapter monitors.
Prerequisites
Verify that you are logged in to the vRealize Operations Manager instance.
vRealize Operations Manager API Programming Guide
14 VMware, Inc.
Procedure
1 Make a GET request for all adapter types.
GET https://vrealize.example.com/suite-api/api/adapterkinds
2 Examine the response to nd the vCenter adapter and list of monitored object types.
See the response portion of “Example: Determine the Adapter Type and Object Types for the vCenter
Adapter,” on page 15.
Example: Determine the Adapter Type and Object Types for the vCenter Adapter
This example nds the adapter type for the vCenter adapter and all the object types included in the adapter
model denition.
Request header:
GET https://vRealize.example.com/suite-api/api/adapterkinds
Content-Type: application/json
Authorization: vRealizeOpsToken <vROps_token>
Accept: application/json
Where vROps_token is the token that you obtained from the response in “Example: Login Request and
Response,” on page 14.
Snippet of the response in JSON for the vCenter Adapter:
200 OK
{
"key": "VMWARE",
"name": "vCenter Adapter",
"description": "Provides the connection information and credentials required...",
"adapterKindType": "GENERAL",
"describeVersion": 573,
"identifiers": [],
"resourceKinds": [
"ClusterComputeResource",
"ComputeResource",
"CustomDatacenter",
"Datacenter",
"Datastore",
"StoragePod",
"DatastoreFolder",
"VM Entity Status",
"Folder",
"HostFolder",
"HostSystem",
"NetworkFolder",
"ResourcePool",
"VMwareAdapter Instance",
"VirtualMachine",
"VMFolder",
"DistributedVirtualPortgroup",
"VmwareDistributedVirtualSwitch",
"vSphere World"
],
...
}
Chapter 3 Getting Started with the API
VMware, Inc. 15
For the vCenter adapter, the adapter-kind key is VMWARE. The resourceKinds are the object types that the
vCenter adapter monitors. For virtual machine object type, the resourceKinds is VirtualMachine.
Generate a List of All Metrics for the Object
To generate a complete list of metrics for any virtual machine dened in the vCenter adapter model, you
make a GET request to the URL with the adapter type and the object type.
Prerequisites
Verify that the following requirements are met:
nYou are logged in to the vRealize Operations Manager instance.
nYou know the adapter-kind value for the vCenter adapter and the resourceKinds value for the virtual
machine. See “Example: Determine the Adapter Type and Object Types for the vCenter Adapter,” on
page 15
Procedure
1 Make a GET request to obtain the metadata for metrics.
GET https://vrealize.example.com/suite-
api/api/adapterkinds/VMWARE/resourcekinds/VirtualMachine/statkeys
2 Compare the metrics listed in the response to metrics displayed in the user interface. See
“Example: Virtual Machine Metrics from the API and in the User Interface,” on page 16
Example: Virtual Machine Metrics from the API and in the User Interface
This example shows how the virtual machine metrics listed in the XML response compare to the metrics
displayed in the vRealize Operations Manager user interface.
Request:
GET https://vrealize.example.com/suite-
api/api/adapterkinds/VMWARE/resourcekinds/VirtualMachine/statkeys
Content-Type: application/json
Authorization: vRealizeOpsToken <vROps_token>
Accept: application/json
Where:
nVMWARE is the adapterKindKey.
nVirtualMachine is the resourceKindKey.
nvROps_token is the token that you obtained from the response in “Example: Login Request and
Response,” on page 14.
Snippet of the response in JSON:
200 OK
{
"key": "mem-consumed|waste",
"name": "Memory (Consumed)|Waste",
"description": "Waste",
"defaultMonitored": true,
"rollupType": "AVG",
"instanceType": "INSTANCED",
"unit": "%",
"monitoring": false,
"property": false
vRealize Operations Manager API Programming Guide
16 VMware, Inc.
},
{
"key": "mem-consumed|workload",
"name": "Memory (Consumed)|Workload",
"description": "Workload",
"defaultMonitored": true,
"rollupType": "AVG",
"instanceType": "INSTANCED",
"unit": "%",
"monitoring": false,
"property": false
}
Every resource-kind-attribute in the response is a metric with metadata for a virtual machine object. The
name corresponds to text displayed in the vRealize Operations Manager user interface. In this example, the
snippet lists metrics for:
nMemory (Consumed), Waste
nMemory (Consumed), Workload
To compare metrics in the response with metrics in the user interface, log in to the
vRealize Operations Manager instance running on vrealize.example.com and navigate to the metrics for a
virtual machine. The following example shows where you nd metrics for Memory (Consumed), Workload.
The example shows how to retrieve metrics for the virtual machine object type. To retrieve metrics for other
object types, replace VirtualMachine in the GET request with other resourceKinds.
Chapter 3 Getting Started with the API
VMware, Inc. 17
vRealize Operations Manager API Programming Guide
18 VMware, Inc.
Configuring an Adapter Instance 4
After installing a solution that includes a management pack with an adapter, you must congure an adapter
instance to collect data from the objects in the adapter model denition. You can use the
vRealize Operations Manager API to congure an adapter instance.
This use case example shows how to congure an adapter instance for a vSphere Solution and includes:
nsummary of operations with request, request body, and response for each
nspecic procedure for each operation
This chapter includes the following topics:
n“Summary of Conguring an Adapter Instance Requests,” on page 19
n“Identify the Solution and Its Adapters,” on page 20
n“Identify the Object Types Required for the Adapter,” on page 21
n“Create the Adapter Instance,” on page 23
n“Provide Proof of Certicate Validity,” on page 26
n“Start Monitoring the New Adapter Instance,” on page 30
Summary of Configuring an Adapter Instance Requests
You make sequential API requests to congure an adapter instance. Responses from earlier requests yield
information required for a subsequent requests.
Table 4‑1. Summary of Requests
Operation Request Request Body Response
Get all solutions registered
with the product and
identify the adapter types
GET <API-URL>/suite-
api/api/solutions
None adapterkindkeys
Get all the object types for a
particular adapter type.
GET <API-URL>/suite-
api/api/adapterkinds/{key
}/resourcekinds
None resourceIdentifierTypes
Create an adapter instance
object
POST <API-URL>/suite-
api/api/adapters
Values for
resourceIdentifiers
and credential
adapterid
VMware, Inc. 19
Table 4‑1. Summary of Requests (Continued)
Operation Request Request Body Response
Patch an adapter instance to
acknowledge the presented
certicate
PATCH <API-URL>/suite-
api/api/adapters
API response of POST
<API-URL>/suite-
api/api/adapters
API response of POST <API-
URL>/suite-api/api/adapters
without adapter-
cerfiticates
Start adapter monitoring PUT <API-URL>/suite-
api/api/adapters/{adapterid
}/monitoringstate/start
None 200 OK
Identify the Solution and Its Adapters
Your vRealize Operations Manager instance may have several solutions installed. To nd the vSphere
solution and its adapter types, you make a GET request to retrieve a list of all solutions. The response
includes all the adapters included with the solution.
For this example use case, the API-URL for the vRealize Operations Manager instance is
vrealize.example.com.
Prerequisites
Verify that you can log in to the API URL for a vRealize Operations Manager instance. See “Acquire an
Authentication Token,” on page 13.
Procedure
1 Make a GET request to list all the solutions.
GET https://vrealize.example.com/suite-api/api/solutions
2 Examine the response to nd the vSphere solution and its adapter types.
See the response portion of “Example: Adapter Types for the vSphere Solution,” on page 20.
Example: Adapter Types for the vSphere Solution
This example lists all the installed solutions and the adapter types for each.
Request header:
GET https://vrealize.example.com/suite-api/api/solutions
The response in JSON:
200 OK
{
"solution":
{
"id": "MPforLogInsight",
"name": "VMware vRealize Operations Management Pack for Log Insight",
"version": "6.0.3171089",
"description": "VMware vRealize Operations Management Pack for Log Insight... ",
"vendor": "VMware Inc.",
"adapterKindKeys": [
"LogInsightAdapter"
]
},
{
"id": "ep-ops-os-and-availability",
vRealize Operations Manager API Programming Guide
20 VMware, Inc.
"name": "Operating Systems / Remote Service Monitoring",
"version": "1.0.4071095",
"description": "The End Point Operations Management Solution for Operating... ",
"vendor": "VMware Inc.",
"adapterKindKeys": [
"ep-ops-os-and-availability-kind"
]
},
{
"id": "VMware vSphere",
"name": "VMware vSphere",
"version": "6.0.7496664",
"description": "Manages vSphere objects such as Clusters, Hosts...",
"vendor": "VMware Inc.",
"adapterKindKeys": [
"VMWARE",
"PythonRemediationVcenterAdapter"
]
}
]
}
The response shows three solutions installed:
nManagement Pack for Log Insight solution
nEnd Point Operations solution
nvSphere solution
The vSphere solution has two adapter types:
nVMWARE
nPythonRemediationVcenterAdapter
For the vCenter adapter, the adapter type is VMWARE.
Identify the Object Types Required for the Adapter
After you determine that you want to create an instance of the vCenter adapter, you must identify the
required object types for that adapter. You make a GET request to retrieve a list of all object types for the
vCenter adapter.
Prerequisites
Verify that you know the adapter type for the vCenter adapter.
Procedure
1 Make a GET request to list all the object types for the vCenter adapter.
GET https://vrealize.example.com/suite-api/api/adapterkinds/VMWARE/resourcekinds
2 Examine the response to identify the required object types..
See the response portion of “Example: Object Types Required for the vCenter Adapter,” on page 21.
Example: Object Types Required for the vCenter Adapter
This example nds all the object types for the vCenter adapter.
Chapter 4 Configuring an Adapter Instance
VMware, Inc. 21
Request header:
GET https://vrealize.example.com/suite-api/api/adapterkinds/VMWARE/resourcekinds
Snippet of the response in JSON:
200 OK
{
"key": "VMwareAdapter Instance",
"name": "vCenter Server",
"adapterKind": "VMWARE",
"resourceKindType": "ADAPTER_INSTANCE",
"resourceKindSubType": "NONE",
"resourceIdentifierTypes": [
{
"name": "AUTODISCOVERY",
"dataType": "STRING",
"isPartOfUniqueness": false
},
{
"name": "DISABLE_COMPUTATION_BASED_ON_CONSUMERS",
"dataType": "STRING",
"isPartOfUniqueness": false
},
{
"name": "DV_PORT_GROUP_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
{
"name": "DVS_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
{
"name": "PROCESSCHANGEEVENTS",
"dataType": "STRING",
"isPartOfUniqueness": false
},
{
"name": "VCURL",
"dataType": "STRING",
"isPartOfUniqueness": true
},
...
{
"name": "VM_LIMIT",
"dataType": "INTEGER",
"isPartOfUniqueness": false
}
],
...
}
vRealize Operations Manager API Programming Guide
22 VMware, Inc.
This snippet shows the Resource Kind with the aribute "resourceKindType": "ADAPTER_INSTANCE". Any
object type that has the resource identier "isPartOfUniqueness":true requires a value for that object type
with the API request to create the adapter instance.
An adapter instance of the vCenter adapter requires a value for VCURL or the URL of the vCenter.
Create the Adapter Instance
After you identify the object types required for the adapter, you provide parameter values for the object
types to create an adapter instance. Your POST request includes a request body with the required
parameters.
To create an adapter instance, the VCURL seing is mandatory.
Prerequisites
Verify that you have an IP address and credentials for a vCenter.
Procedure
1 Make a POST request to create the adapter instance.
POST https://vrealize.example.com/suite-api/api/adapters
2 Examine the response to nd the name for the vSphere Solution and its adapter types.
See the response portion of “Example: Adapter Instance,” on page 23.
Example: Adapter Instance
This example creates the adapter instance for a vCenter with the following parameters:
nDisplay Name: VC Adapter Instance
nDescription: A vCenter Adapter Instance for VC 12.345.678.9
nvCenter Server IP address: hps://12.345.678.9
nCredential name: VC-Credential-1
nUser Name: administrator@vsphere.local
nPassword: VC-dummy-passwd
AUTODISCOVERY and PROCESSCHANGEEVENTS are optional, but are included to show additional examples of
resource identiers in the request body and in the response.
Request header:
POST https://vrealize.example.com/suite-api/api/adapters
Request body in JSON format:
{
"name" : "VC Adapter Instance",
"description" : "A vCenter Adapter Instance for VC 12.345.678.9",
"collectorId" : "1",
"adapterKindKey" : "VMWARE",
"resourceIdentifiers" : [
{
"name" : "AUTODISCOVERY",
"value" : "true"
},
{
"name" : "PROCESSCHANGEEVENTS",
Chapter 4 Configuring an Adapter Instance
VMware, Inc. 23
"value" : "true"
},
{
"name" : "VCURL",
"value" : "https://12.345.678.9"
}
],
"credential" : {
"id" : null,
"name" : "VC-Credential-1",
"adapterKindKey" : "VMWARE",
"credentialKindKey" : "PRINCIPALCREDENTIAL",
"fields" : [
{
"name" : "USER",
"value" : "administrator@vsphere.local"
},
{
"name" : "PASSWORD",
"value" : "VC-dummy-passwd"
}
],
},
}
Snippet of the response in JSON:
201 Created
{
"resourceKey": {
"name": "VC Adapter Instance",
"adapterKindKey": "VMWARE",
"resourceKindKey": "VMwareAdapter Instance",
"resourceIdentifiers": [
{
"identifierType": {
"name": "AUTODISCOVERY",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": "true"
},
{
"identifierType": {
"name": "DISABLE_COMPUTATION_BASED_ON_CONSUMERS",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "DV_PORT_GROUP_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
vRealize Operations Manager API Programming Guide
24 VMware, Inc.
"value": ""
},
{
"identifierType": {
"name": "DVS_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "PROCESSCHANGEEVENTS",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": "true"
},
{
"identifierType": {
"name": "VCURL",
"dataType": "STRING",
"isPartOfUniqueness": true
},
"value": "https://12.345.678.9"
},
{
"identifierType": {
"name": "VM_FOLDER_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "VM_LIMIT",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
}
]
},
"description": "A vCenter Adapter Instance for VC 12.345.678.9",
"collectorId": 1,
"collectorGroupId": "909c2fbf-2c2c-4957-9a75-21bf2a887d31",
"credentialInstanceId": "65081a8d-d462-43b2-b4e0-596eaf3d497e",
"monitoringInterval": 5,
"adapter-certificates": [
{
"thumbprint": "2520fb4351bc91ee7b82ef7cc54a8d88fa893da9",
"certificateDetails": "[
Version: V3 Subject: C=US, CN=12.345.678.9
Signature Algorithm: SHA256withRSA, OID = 1.2.840.113549.1.1.11
Chapter 4 Configuring an Adapter Instance
VMware, Inc. 25
Key: Sun RSA public key, 2048 bits modulus: ...
Validity: [From: Wed Jul 15 19:26:51 UTC 2015, To: Tue Jul 08 11:26:30 UTC 2025]
Issuer: O=W12R2UINanduVC, C=US, DC=local, DC=vsphere, CN=CA ...
...
]"
}
],
...
"id": "a97bd204-e3e5-404b-a219-e2b20cf158d2"
}
The API creates a new adapter with an internally generated UUID that uniquely identies the object. The
API response includes the certicates that vCenter 12.345.678.9 presents. The value of the adapter instance
ID is used to start monitoring and collecting data.
Provide Proof of Certificate Validity
Before vRealize Operations Manager can connect to the vCenter and start collecting data, it needs to verify
that data sources discovered by the adapter instance are presenting valid certicates. Your PATCH request
provides the proof that the certicates are valid by including a request body that is the response from the
POST request used to create the adapter.
Prerequisites
Verify that you have the response from the POST request used to create the adapter. See the response in
“Example: Adapter Instance,” on page 23.
Procedure
uMake a PATCH request to notify the system that the user has accepted the certicate presented by the
vCenter.
PATCH https://vrealize.example.com/suite-api/api/adapters
Example: Certificate Validation
In this example, the request body for the PATCH request is the same as the response from the POST request
used to create the adapter instance.
Request header:
PATCH https://vrealize.example.com/suite-api/api/adapters
Request body in JSON format:
{
"resourceKey": {
"name": "VC Adapter Instance",
"adapterKindKey": "VMWARE",
"resourceKindKey": "VMwareAdapter Instance",
"resourceIdentifiers": [
{
"identifierType": {
"name": "AUTODISCOVERY",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": "true"
},
{
vRealize Operations Manager API Programming Guide
26 VMware, Inc.
"identifierType": {
"name": "DISABLE_COMPUTATION_BASED_ON_CONSUMERS",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "DV_PORT_GROUP_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "DVS_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "PROCESSCHANGEEVENTS",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": "true"
},
{
"identifierType": {
"name": "VCURL",
"dataType": "STRING",
"isPartOfUniqueness": true
},
"value": "https://12.345.678.9"
},
{
"identifierType": {
"name": "VM_FOLDER_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "VM_LIMIT",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
}
Chapter 4 Configuring an Adapter Instance
VMware, Inc. 27
]
},
"description": "A vCenter Adapter Instance for VC 12.345.678.9",
"collectorId": 1,
"collectorGroupId": "909c2fbf-2c2c-4957-9a75-21bf2a887d31",
"credentialInstanceId": "65081a8d-d462-43b2-b4e0-596eaf3d497e",
"monitoringInterval": 5,
"adapter-certificates": [
{
"thumbprint": "2520fb4351bc91ee7b82ef7cc54a8d88fa893da9",
"certificateDetails": "[
Version: V3 Subject: C=US, CN=12.345.678.9
Signature Algorithm: SHA256withRSA, OID = 1.2.840.113549.1.1.11
Key: Sun RSA public key, 2048 bits modulus: ...
Validity: [From: Wed Jul 15 19:26:51 UTC 2015, To: Tue Jul 08 11:26:30 UTC 2025]
Issuer: O=W12R2UINanduVC, C=US, DC=local, DC=vsphere, CN=CA ...
...
]"
}
],
...
"id": "a97bd204-e3e5-404b-a219-e2b20cf158d2"
}
Response in JSON:
{
"resourceKey": {
"name": "VC Adapter Instance",
"adapterKindKey": "VMWARE",
"resourceKindKey": "VMwareAdapter Instance",
"resourceIdentifiers": [
{
"identifierType": {
"name": "AUTODISCOVERY",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": "true"
},
{
"identifierType": {
"name": "DISABLE_COMPUTATION_BASED_ON_CONSUMERS",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "DV_PORT_GROUP_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
vRealize Operations Manager API Programming Guide
28 VMware, Inc.
{
"identifierType": {
"name": "DVS_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "PROCESSCHANGEEVENTS",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": "true"
},
{
"identifierType": {
"name": "VCURL",
"dataType": "STRING",
"isPartOfUniqueness": true
},
"value": "https://12.345.678.9"
},
{
"identifierType": {
"name": "VM_FOLDER_DISABLED",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
},
{
"identifierType": {
"name": "VM_LIMIT",
"dataType": "STRING",
"isPartOfUniqueness": false
},
"value": ""
}
]
},
"description": "A vCenter Adapter Instance for VC 12.345.678.9",
"collectorId": 1,
"collectorGroupId": "909c2fbf-2c2c-4957-9a75-21bf2a887d31",
"credentialInstanceId": "65081a8d-d462-43b2-b4e0-596eaf3d497e",
"monitoringInterval": 5,
...
"id": "a97bd204-e3e5-404b-a219-e2b20cf158d2"
}
The response is same as the request body without the adapter-certificates section.
Chapter 4 Configuring an Adapter Instance
VMware, Inc. 29
Start Monitoring the New Adapter Instance
After the creating the adapter instance and conguring vRealize Operations Manager to recognize a valid
certicate, start monitoring and collecting data. Your PUT request provides the UUID of the adapter
instance used to discover new objects.
Prerequisites
Verify that you have the UUID of the newly created adapter instance. See the response in
“Example: Adapter Instance,” on page 23.
Procedure
uMake a PUT request to start monitoring with the new adapter instance.
PUT https://vrealize.example.com/suite-api/api/adapters/<adapter_UUID>/monitoringstate/start
Example: Discover Objects and Collect Data
This example starts the adapter monitoring process using the adapter instance ID from the PUT request that
created the adapter instance.
Request header:
PUT https://vrealize.example.com/suite-api/api/adapters/a97bd204-e3e5-404b-a219-
e2b20cf158d2/monitoringstate/start
vRealize Operations Manager API Programming Guide
30 VMware, Inc.
Index
A
adapter for solution, identify 20
adapter instance, create 23
adapter types, find 14
API syntax 7
authentication
basic 9
token-based 9
authentication token, acquire 13
C
certificate signature, acknowledge 26
configuring adapter instance, summary of
requests 19
G
glossary 5
I
intended audience 5
M
metrics for the object, list all 16
O
object types, find 14
object types, identify 21
overview 7
R
request bodies 9
request headers 9
responses, about 10
REST client programs 12
S
schema reference 12
security, authentication 9
solution, identify 20
start monitoring 30
W
workflow 8
workflow, example of 13
VMware, Inc. 31
vRealize Operations Manager API Programming Guide
32 VMware, Inc.

Navigation menu