vRealize Automation REST API with Curl

vRealize Autmation exposes a RESTful API to automate common tasks without having to access the GUI. Some common examples of why you would use this are:

  • Request machines as part of a Continus Integratation process
  • Integrate vRA provisioning into your build systems such as Jenkins
  • Drive vRA requests from a third party IT management portal
  • Trigger Day 2 operations from monitoring or testing systems, for example triggering a reboot of a machine.

Pre-reqs that you will need in place prior to exploring the REST API

vRealize Automation:

  • The REST API is officially supported in vCloud Automation Center 6.1 and   vRealize Automation 6.2 and all newer versions.
  • At least one IaaS catalog item to provision. NOTE: You should be able to provision this successfully from the UI prior to using the API.

User Workstation:

  • A linux or Mac with curl
  • Network access to the vRA appliance and the SSO appliance
  • A few hours of free time where you will not be interupted

API Documentation here

You should also be able to follow this lab by using the VMware Hands on Labs On-line

Lets get started, first we will need to set some environment variables to save us time. Let’s export the vRA appliance host name.

media_1423269220831.png

Note: Replace the text in red with your appliance host name

export VRA=vcac-01a.corp.local

Create variable for the HTTP Accept header, which tells the server what format you want the response to be in. Could also be application/json

media_1423269357332.png
export ACCEPT="text/xml"

Here we will authenticate by requesting a bearer token via a POST against /identity/api/tokens API, and we will store the bearer token in a variable so we can use it on future API invocations. This example passes cloudadmins credentials (rainpole tenant) with inline JSON, but you could also create variables or store this JSON in a file and use the file instead.

media_1423269882544.png

I have highlighted what you need to change for your environement:

curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data '{"username":"cloudadmin@corp.local","password":"VMware1!","tenant":"rainpole"}' https://$VRA/identity/api/tokens

Once you press enter you should see a response like this.

media_1423270064051.png

Notice in the above the “id” field is what we need to copy and paste to create our AUTH variable

Now let’s export our Authentication token to a new variable with export AUTH=”Bearer youridfromcommandabove”

media_1423271046935.png

Notice it must include Bearer and a space and be in quotes for this to work. For example:

 

export AUTH="Bearer MTQyMzI2Mjc5NTMzNzphNTM0ODg2NTI1NjY4OGVmNGFmYjp0ZW5hbnQ6cmFpbnBvbGV1c2VybmFtZTpjbG91ZGFkbWluQGNvcnAubG9jYWw6ZTYzZDJiMDkwYTMzYzM3OTg4ZDQwNWYxZWYwMTcxZjIwMzgwZGFjNTliNWE5ZGExYTVlOTk0ZWNjNmEwNzk3MjUxYWNjMDlhMTllNTZkY2JhYmRhNjE4ZGU5YmE5M2FmZjQ3Y2MwMjI0ODg2M2MxZmUzNWI3NjI2Y2Q3OTI3Yzg="

You need to change the red text to your authentication id

 

Now lets test connectivity by listing the entitled catalog items with curl –insecure -H “Accept: $ACCEPT” -H “Authorization: $AUTH” https://$VRA/catalog-service/api/consumer/entitledCatalogItems

media_1423271474694.png
curl --insecure -H "Accept: $ACCEPT" -H "Authorization: $AUTH" https://$VRA/catalog-service/api/consumer/entitledCatalogItems

Now we need to construct a JSON file for our request. You can get the fields you need by traversing the API. I have highlighted the fields you need

{
 "@type": "CatalogItemRequest",
 "catalogItemRef": {
 "id": "908259ad-555c-40fc-9ef1-24281f4ff42b"
 },
 "organization": {
 "tenantRef": "rainpole",
 "subtenantRef": "df59b474-7374-48f0-ab08-e11d8cdc2298"
 },
 "requestedFor": "cloudadmin@corp.local",
 "state": "SUBMITTED",
 "requestNumber": 0,
 "requestData": {
 "entries": [
 {
 "key": "provider-blueprintId",
 "value": {
 "type": "string",
 "value": "c2e64049-2f4f-439b-adc3-88c10cef17ea"
 }
 },
 {
 "key": "provider-provisioningGroupId",
 "value": {
 "type": "string",
 "value": "df59b474-7374-48f0-ab08-e11d8cdc2298"
 }
 },
 {
 "key": "requestedFor",
 "value": {
 "type": "string",
 "value": "cloudadmin@corp.local"
 }
 },
 {
 "key": "provider-Machine.ssh",
 "value": {
 "type": "string",
 "value": "true"
 }
 },
 {
 "key": "provider-VirtualMachine.CPU.Count",
 "value": {
 "type": "integer",
 "value": 1
 }
 },
 {
 "key": "provider-VirtualMachine.Memory.Size",
 "value": {
 "type": "integer",
 "value": 1024
 }
 },
 {
 "key": "provider-VirtualMachine.Disk0.Size",
 "value": {
 "type": "string",
 "value": "6"
 }
 },
 {
 "key": "provider-VirtualMachine.LeaseDays",
 "value": {
 "type": "integer",
 "value": 5
 }
 },
 {
 "key": "provider-__Notes",
 "value": {
 "type": "string",
 "value": "Test"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.TotalStorageSize",
 "value": {
 "type": "decimal",
 "value": 0
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.Description",
 "value": {
 "type": "string",
 "value": "Test"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.NumberOfInstances",
 "value": {
 "type": "integer",
 "value": 1
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.Reason",
 "value": {
 "type": "string",
 "value": "Test"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.AssignToUser",
 "value": {
 "type": "string",
 "value": "cloudadmin@corp.local"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.MinCost",
 "value": {
 "type": "string",
 "value": "0.9329"
 }
 },
 {
 "key": "provider-Cafe.Shim.VirtualMachine.MaxCost",
 "value": {
 "type": "string",
 "value": "0.9329"
 }
 },
 {
 "key": "description",
 "value": {
 "type": "string",
 "value": "Test"
 }
 },
 {
 "key": "reasons",
 "value": {
 "type": "string",
 "value": "Test"
 }
 }
 ]
 }
 }

Save this file and your ready to request. I saved mine as centos.json

Now let”s request with the following:

curl –insecure -H “Accept: $ACCEPT” -H “Authorization: $AUTH” https://$VRA/catalog-service/api/consumer/requests –data @/centos.json –verbose -H “Content-Type: application/json”

media_1423272332467.png

You can use the API to see the request with curl –insecure -H “Accept: $ACCEPT” -H “Authorization: $AUTH” https://$VRA/catalog-service/api/consumer/requests or access the UI.

media_1423272280600.png

Remember, sharing is caring ->Tweet about this on Twitter
Twitter
0Share on Facebook
Facebook
0Share on LinkedIn
Linkedin
Share on Google+
Google+
0Email this to someone
email

18 Replies to “vRealize Automation REST API with Curl”

  1. Thanks for the info.. Great stuff. But on the path of continuous delivery, is there a way to get a callback method run using this API? So after the VM is up and running, I would then want to move forward and deploy a number of things.

    • Hi Nick,

      Here is another guide I wrote for just that. You would need to modify the blueprint with a couple properties as well as add a script in the guest template. This is very similar to cloudinit but in vRA/vCAC we call it the Guest agent. It basically phones home to vRA/vCAC to run scripts in the guest after it boots up. You can add parameters as arguments to the script from the API when you request the VM from Jenkins. http://www.vmtocloud.com/how-to-call-vcac-vra-from-command-line-to-request-vms-and-run-scripts-in-the-guest/

      Also you may want to have a look at code stream that is much more out of the box for this. https://www.youtube.com/watch?v=2hGEoot9viU&index=1&list=PLrFo2o1FG9n7Pr4Fq-7exPvN6ThDYRcPV

      • Hi Ryan,

        Thanks for the detailed help.
        I tried your steps and works like a charm.

        However i have issues executing “https://$VRA/catalog-service/api/consumer/entitledCatalogItems” using some REST console without using curl.
        I used the same token and end points which gives exact output in curl but throws the below error using some REST console :
        Error:
        HTTP Status 401 – Authentication required

        Any pointers would be really helpful.

        Thanks,
        Durga

        • Durga,

          Did you get this resolved. I have exactly the same issue, everything works via curl but not via vRO REST interface or via a REST application (Firefox Restful plugin etc).

          Thanks

          Andy

  2. Hi there, im using postman and I authnticate well but when I try to get catalog-service/api/consumer/entitledCatalogItems i receive an empty response:

    {
    “links”: [],
    “content”: [],
    “metadata”: {
    “size”: 20,
    “totalElements”: 0,
    “totalPages”: 0,
    “number”: 1,
    “offset”: 0
    }
    }

    any ideas?

        • Ariel, i am also getting the same issue. i have no typo mistake on tenant name.
          still getting the same empty response.

          {
          “links”: [],
          “content”: [],
          “metadata”: {
          “size”: 20,
          “totalElements”: 0,
          “totalPages”: 0,
          “number”: 1,
          “offset”: 0
          }
          }

  3. How can you export the contents into a delimited csv file. For example if I only wanted “key” and “value”

  4. Where do I get the provider-blueprintId and provider-provisioningGroupId values?
    They are not returned in the body of the previous consumer/entitledCatalogItems request

  5. LOL, you guys … Time is definitely investment and time is the critical component to generating a backlist of novels or even stories. The trick is deciding whether to have patience and develop your own backlist or to just simply begin and see where it leads you. Congrats on your success, Brand and thanks for the comment

  6. how to sent the resource id collection to get the resources properties by using the rest API “/api/resources/properties”. i using the this api via postman but its throwing error not able to convert resourceid

  7. May I simply just say what a comfort to uncover an individual who actually knows what they are talking about
    on the web. You actually understand how to bring an issue to light and make it important.
    More and more people need to look at this and understand
    this side of the story. I can’t believe you are not more popular because you definitely have the gift.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.