VRealize Operations Manager APl Programming Guide 11ocT2018 vRealize Operations Manager 7.0 VmWare
vRealize Operations Manager API Programming Guide 11 OCT 2018 vRealize Operations Manager 7.0
vRealize Operations Manager API Programming Guide ou can find the most up-to-date technical documentation on the VMware website at https://docs.vmware.com If you have comments about this docu submit your feedback to docfeedh VMware Inc 3401 Hillview Palo Alto, CA 94304 ww. vmware. com Copyright. 2018 VMware, Inc. All rights reserved. Copyright and trademark information re. Inc
vRealize Operations Manager API Programming Guide VMware, Inc. 2 You can find the most up-to-date technical documentation on the VMware website at: https://docs.vmware.com/ If you have comments about this documentation, submit your feedback to docfeedback@vmware.com Copyright © 2018 VMware, Inc. All rights reserved. Copyright and trademark information. VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com
Contents About This Programming Guide 4 2 Understanding the vRealize Operations Manager API 5 How the vRealize Operations Manager API Works 5 Client Workflow Overview 6 Using the API with VMware vRealize Operations Manager 1 3 Getting Started with the API 12 Acquire an Authentication Token 12 Find the Adapter Type and Object Type 14 Generate a List of All Metrics for the object 15 4 Configuring an Adapter Instance 18 Summary of Configuring an Adapter Instance Requests 18 Identify the Solution and Its Adapters 19 Identify the Object Types Required for the Adapter 2 Create the Adapter Instance 22 Provide Proof of Certificate Validity 26 Start Monitoring the New Adapter Instance 30
Contents 1 About This Programming Guide 4 2 Understanding the vRealize Operations Manager API 5 How the vRealize Operations Manager API Works 5 Client Workflow Overview 6 Using the API with VMware vRealize Operations Manager 10 3 Getting Started with the API 12 Acquire an Authentication Token 12 Find the Adapter Type and Object Type 14 Generate a List of All Metrics for the Object 15 4 Configuring an Adapter Instance 18 Summary of Configuring an Adapter Instance Requests 18 Identify the Solution and Its Adapters 19 Identify the Object Types Required for the Adapter 21 Create the Adapter Instance 22 Provide Proof of Certificate Validity 26 Start Monitoring the New Adapter Instance 30 VMware, Inc. 3
About This Programming Guide The vRealize Operations Manager TM AP/ 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 configure and manage vRealize Operations Manager programmatically using the vRealize Operations Manager REST APL.The guide focuses on common use cases
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 configure and manage vRealize Operations Manager programmatically using the vRealize Operations Manager REST API. The guide focuses on common use cases. VMware, Inc. 4
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 epresentations 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 How the vRealize Operations Manager API Works Client Workflow Overview Using the API with VMware vRealize Operations Manager 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 Inventory Product User Interface REST AP rEalize Operations Manager Analytics Engine
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 n Client Workflow Overview n Using the API with VMware vRealize Operations Manager 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 VMware, Inc. 5
vRealize Operations Manager API Programming Guide 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 Why Use the APl The API is most useful when there is a need to automate a well-defined workflow, such as repeating the same tasks to configure 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 rEalize Operations Manager Terminology The XML syntax you use to describe the objects for an adapter corresponds to the aPl code syntax but differs from what you find 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 Defines 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 ML syntax: adapterkinds Object types The class of entities that represent objects or information sources. Objects report data to the ealize Operations Manager analytics engine. Virtual machines, datastores, and host systems are examples of object types defined in a vCenter adapter mode XML syntax: resourcekinds Client Workflow Overview vreaLize Operations Manager Api clients implement a Rest workflow 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 programsthatusetheHypertextTransferProtocol(http)toexchangeserializedrepresentationsof bjects between a client and a server. In the vRealize Operations Manager APl, these representations are json or xMl documents In a REST workflow, 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
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. Why Use the API The API is most useful when there is a need to automate a well-defined workflow, such as repeating the same tasks to configure 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 differs from what you find 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 Defines 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 defined in a vCenter adapter model. XML syntax: resourcekinds. Client Workflow Overview vRealize Operations Manager API clients implement a REST workflow, 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 workflow, 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. vRealize Operations Manager API Programming Guide VMware, Inc. 6
vRealize Operations Manager API Programming Guide REST API Workflows Application programs written to use a rEst Apl 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 bjects that the API defines In the vRealize Operations Manager REST API, these objects are defined by a collection of Xml schemas The operations themselves are Http requests and so are generic to 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 effectively in such a client, you must become familiar with the following concepts The set of objects that the API supports, and what they represent How the API represents these objects How 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 rEalize 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 configure 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 REST API REST API AuthN Alert Client Service Backend GET lapi/alerts/123 Extract Auth Header User x with valid session getAlertDetails(123) 200 OK Alert Data
REST API Workflows Application programs written 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 defines . In the vRealize Operations Manager REST API, these objects are defined 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 effectively in such a client, you must become familiar with the following concepts. n The set of objects that the API supports, and what they represent. n How the API represents these objects. n How 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. 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 configure 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 vRealize Operations Manager API Programming Guide VMware, Inc. 7
vRealize Operations Manager API Programming Guide 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-userexample_user:simple_passhttps://restendPoinT.examplecom/suite- api/api/ resources/0e000060600-0600-2222-6600000002 3Theapiserverextractscredentialsfromthehttpheaderauthorizationandcheckstheuser 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 token-based authentication scenario You obtain valid user credentials for your vRealize Operations Manager instance 2 POST a request to the REST endpoint for authentication Posthttps://restenDpoiNt.examplecom/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 Alternatively, if you acquired the token from an SSo source, the Authorization header is of the format Authorization SSo2Token 5 You can invalidate the token before the expiration date and time by sending a POST request to the out Posthttps://resteNdpoiNt.examplecom/api/token/release Request Headers The following Http headers are typically included in Api requests
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/suiteapi/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. 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 Alternatively, if you acquired the token from an SSO source, the Authorization header is of the format: Authorization: SSO2Token 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: vRealize Operations Manager API Programming Guide VMware, Inc. 8
vRealize Operations Manager API Programming Guide Accept-Language To specify the language desired in responses, use the Accept-Language request header Message strings in Error Type responses are localized To request a response with message strings localized to French, use the following header: ccept-Language: fr-FR Authorization All requests to create an API session must include an Authorization header of the fom prescribed by the identity provider that your organization uses Content-type Requests that include a body must include an appropriate Http Content-type header For a request body in XML, the header must include Content-Type: application/xmL s For 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 For a response in XML, the header must include Accept: application/xml s For a response in JSON the header must include Accept: application/json Request Bodies in XML For a request body written 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 XML namespace attributes must be supplied for all namespaces represented by elements in the request If multiple namespaces are represented in the request, XML namespace attributes must include an dentifying prefix, and that prefix must be used with all elements from that namespace All 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 specifies 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 Apl client can expect a subset of Http status codes in a response Table2-1.httpStatusCodesthattheaplreturns Status Code Status Descriptic 260K 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 specified in the Location header. 02 Accepted The request is valid and a task was created to handle it. This response is usually accompanied by a TaskStatus element
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. n For a request body in XML, the header must include Content-Type: application/xml n For 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. n For a response in XML, the header must include Accept: application/xml n For a response in JSON, the header must include Accept: application/json Request Bodies in XML For a request body written 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: n XML namespace attributes must be supplied for all namespaces represented by elements in the request. n If multiple namespaces are represented in the request, XML namespace attributes must include an identifying prefix, and that prefix must be used with all elements from that namespace. n All 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 specifies. 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. 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 specified 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 . vRealize Operations Manager API Programming Guide VMware, Inc. 9
vRealize Operations Manager API Programming Guide Table 2-1. Http Status Codes that the apl reTurns(continued) Status Code Status Descripti 204 No Content The request is valid and was completed. The response does not include a bod 400 Bad Request The request body is malformed, incomplete, or otherwise 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 specified in the equest 404 Not Found The object specified in the request could not be found. 405 Method Not Allowed The Http method specified in the request is not supported for 406 Not Acceptable The resource identified by the request is not capable of generating a response of the type specified in the requests Accept header. 415 Unsupported Media Type The resource identified by the request does not support a request of the specified 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 500 Internal Server Error The request was received but could not be completed because 503 Service Unavailable The server is currently unable to handle the request due to a temporary condition such as resource exhaustion or server 504 Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the request URL. Using the APi with VMware vRealize operations manager VMware vRealize Operations Manager 6.0 and later versions support the vRealize Operations Manager Rest Apl. You can use a browser or an Http client program to send requests and receive responses REST Client pr。 grams Any client application that can send HT TPS requests is an appropriate tool for developing REST applications with the VMware vRealize Operations Manager APl. REST client plug-ins are available for most browsers and many IDES. The following open-source programs are commonly used CurL.http://curl.haxx.se
Table 2‑1. HTTP Status Codes that the API Returns (Continued) Status Code Status Description 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 specified in the request. 404 Not Found The object specified in the request could not be found. 405 Method Not Allowed The HTTP method specified in the request is not supported for this object. 406 Not Acceptable The resource identified by the request is not capable of generating a response of the type specified in the request's Accept header. 415 Unsupported Media Type The resource identified by the request does not support a request of the specified 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 specified by the request URL. 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: n cURL. http://curl.haxx.se vRealize Operations Manager API Programming Guide VMware, Inc. 10
