vCloud API Programming Guide vCloud Director 5.1 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.
vCloud API Programming Guide You can find the most up-to-date technical documentation on the VMware Web site at: http://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 © 2009–2012 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws.
Contents vCloud API Programming Guide 7 1 About the VMware vCloud API 9 Object Taxonomy 10 Objects, References, and Representations 12 Links and Link Relations 12 Client Workflow Overview 16 Using the vCloud API with vCloud Director 21 About the vCloud API Examples 22 2 Hello vCloud: A Simplified RESTful Workflow 23 Logging In 24 Find a Catalog and a vDC 26 Retrieve the Contents of a Catalog 27 Retrieve a Catalog Item 28 Retrieve Deployment Information From the vDC 30 Deploy the vApp 31 Get Information
vCloud API Programming Guide 5 Deploying and Operating vApps 81 Summary of vCloud API vApp and Virtual Machine Operations Requests 83 Create a vApp From a Template 85 Compose a vApp From Existing Virtual Machines 87 Recompose a vApp to Add or Remove Virtual Machines 90 Provide User Input Requested by a Virtual Machine 92 Attach or Detach an Independent Disk 93 Creating and Using vApp Snapshots 95 Operate a vApp 96 Configuring vApps and Virtual Machines 97 6 Creating and Managing Organizations 129 Summary
Contents Monitor Blocking Tasks 276 Take Action on a Blocking Task 277 Extend The Timeout Expiration of an Active Task 279 11 vCloud Director Extension Services 281 Summary of vCloud API Extensibility Requests 282 Register an Extension Service 284 Adding or Removing Service Links 288 Service-Specific Tasks and Events 291 Authorization Framework for Extension Service Operations 294 Localization Framework for Extension Services 302 REST APIs for Extension Services 302 12 XML Representations in the vCloud
vCloud API Programming Guide 6 VMware, Inc.
vCloud API Programming Guide This edition of the vCloud API Programming Guide provides information about version 5.1 of the vCloud API. VMware provides many different APIs and SDKs for applications and goals. This guide provides information about the vCloud API for developers who are interested in creating RESTful clients of VMware vCloud Director. Revision History The vCloud API Programming Guide is revised with each release of the product or when necessary.
vCloud API Programming Guide 8 VMware, Inc.
About the VMware vCloud API 1 The VMware vCloud API provides support for developers who are building interactive clients of VMware vCloud Director using a RESTful application development style. vCloud API clients and vCloud Director servers communicate over HTTP, exchanging representations of vCloud objects. These representations take the form of XML elements.
vCloud API Programming Guide Object Taxonomy The vCloud API defines a set of objects common to cloud computing environments. An understanding of these objects, their properties, and their relationships is essential to using the vCloud API. Figure 1-1.
Chapter 1 About the VMware vCloud API Organization vDCs An organization virtual datacenter (organization vDC) is a deployment environment for virtual systems owned by the containing organization, and an allocation mechanism for resources such as networks, storage, CPU, and memory. In an organization vDC, computing resources are fully virtualized, and can be allocated based on demand, service level requirements, or a combination of the two.
vCloud API Programming Guide Objects, References, and Representations The vCloud API represents objects as XML documents in which object properties are encoded as elements and attributes with typed values and an explicit object hierarchy defined by an XML schema. XML representations of first-class vCloud API objects, such as the objects in Figure 1-1, include these attributes. id The object identifier, expressed in URN format.
Chapter 1 About the VMware vCloud API Attribute values in a Link element supply the following information: rel Defines the relationship of the link to the object that contains it. A relationship can be the name of an operation on the object, a reference to a contained or containing object, or a reference to an alternate representation of the object. The relationship value implies the HTTP verb to use when you use the link's href value as a request URL.
vCloud API Programming Guide Table 1-1. Link Relationships and HTTP Request Types (Continued) rel Attribute Value Action or Relationship Description Implied HTTP Verb down:aclRules Retrieve the ACL rules for this resource class action. GET down:apidefinitions Retrieve the API definitions for this extension service. GET down:apiDefinitions Retrieve the API definitions for this extension service. GET down:apiFilters Retrieve the API filters for this extension service.
Chapter 1 About the VMware vCloud API Table 1-1. Link Relationships and HTTP Request Types (Continued) rel Attribute Value Action or Relationship Description Implied HTTP Verb installVmwareTools Install VMware Tools on this virtual machine. POST keystore:reset Removes the keystore used by this service. POST keystore:update Updates the keystore used by this service. POST keytab:reset Removes the keytab used by this service. POST keytab:update Updates the keytab used by this service.
vCloud API Programming Guide Table 1-1. Link Relationships and HTTP Request Types (Continued) rel Attribute Value Action or Relationship Description Implied HTTP Verb rights:cleanup Remove service-specific rights no longer used by any extension service. POST screen:acquireTicket Retrieve a screen ticket for this virtual machine. GET screen:thumbnail Retrieve a thumbnail view of the screen of this virtual machine.
Chapter 1 About the VMware vCloud API If a URL of such an object is known to a client, the client can use an HTTP GET request to retrieve the representation of the object. In the vCloud API, this representation is an XML document. In a RESTful workflow, representations of object state are passed back and forth between a client and a service with the explicit assumption that neither party need know anything about an object other than what is presented in a single request or response.
vCloud API Programming Guide vCloud API REST Requests To retrieve object representations, clients make HTTP requests to object references. The server supplies these references as href attribute values in responses to GET requests. Every cloud has a well-known URL from which an unauthenticated user can retrieve a SupportedVersions document, which lists each version of the of vCloud API that the server supports.
Chapter 1 About the VMware vCloud API Requests that specify API version 5.1 cannot access objects that do not exist in the vCloud API version 5.1 namespace. Accept-Encoding By default, vCloud Director returns response content as uncompressed XML. Compressing the response can improve performance, especially when the response is large and network bandwidth is a factor. (Requests cannot be compressed.
vCloud API Programming Guide vCloud API REST Responses All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content-Type header. Response content depends on the request. Some responses include a document body, some include only a URL, and some are empty. Response Content Response content depends on the requested operation. The response to a GET request is typically the complete representation of an existing object.
Chapter 1 About the VMware vCloud API Using the vCloud API with vCloud Director VMware vCloud Director 5.1 supports version 5.1 of the vCloud API. You can use a browser or other HTTP client program to send requests and receive responses. The vCloud Director REST API Reference documentation includes HTML reference material for all XML elements and complex types defined by the vCloud API. It also includes example XML representations. See “About the Schema Reference,” on page 21.
vCloud API Programming Guide About the vCloud API Examples The vCloud API Programming Guide includes many examples of HTTP requests and responses. These examples show the workflow and content associated with operations such as browsing, provisioning, and managing your cloud and its contents, and operating virtual systems. Example requests generally conform to the rules listed in “Request Bodies,” on page 19.
Hello vCloud: A Simplified RESTful Workflow 2 vCloud API clients and vCloud Director servers communicate over HTTPS, exchanging XML representations of vCloud API objects. This simplified example of a RESTful workflow includes requests that discover and deploy a particular vApp, in this case, an FTP server with a connection to the public Internet.
vCloud API Programming Guide 8 Displaying the Virtual Machine Console on page 37 After a vApp is powered on, you can retrieve a screen ticket from one of its virtual machines. You use that ticket with the VMRC browser plug-in to gain access to the console of the virtual machine. 9 Delete the vApp on page 38 To delete the vApp, undeploy it and power it off, then use an HTTP DELETE request to delete the vApp object.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow Identity Provider,” on page 45. Otherwise, the list typically includes a link of type application/vnd.vmware.vcloud.orgList+xml, as shown in the response portion of “Example: Login Request and Response,” on page 25. You can use this link to find out more about your organization and the objects it contains. For more information about the other links in the Session element, see “Create a Login Session Using the Integrated Identity Provider,” on page 44.
vCloud API Programming Guide The response code indicates whether the request succeeded, or how it failed. n If the request is successful, the server returns HTTP response code 200 (OK) and headers that include an authorization header of the following form: x-vcloud-authorization: token This header must be included in each subsequent vCloud API request. n If the authentication header is missing, the server returns HTTP response code 403.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow Request: GET https://vcloud.example.com/api/org/5 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... PAGE 28vCloud API Programming Guide 2 Examine the response to find the links to the organization's catalogs. These links have the following form: 3 Retrieve the contents of the catalog. Use a GET request of the form shown in the request portion of “Example: Retrieve the Contents of a Catalog,” on page 28.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow Prerequisites Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud. Procedure 1 Retrieve the representation of a catalog in your organization. Use a request like this one: GET https://vcloud.example.com/api/catalog/32 2 Examine the response to find the CatalogItem elements that the catalog contains.
vCloud API Programming Guide href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> Retrieve Deployment Information From the vDC To deploy your template as a vApp, you must specify an organization vDC to deploy it in and an organization vDC network to connect it to. Instantiation, deployment, and operation of a vApp all take place in the context of an organization vDC.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"> ... ... PAGE 32vCloud API Programming Guide The server takes the requested action and returns a VApp element. The element has a status attribute value of 0, meaning it is unresolved because it is still being constructed. It also contains a Task element that tracks the progress of the request. See the response portion of “Example: Deploying a vApp,” on page 32.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> Example FTP Server Configuration parameters for logical networks PAGE 34vCloud API Programming Guide ... > Get Information About a vApp When you instantiate a vApp template, the server returns the URL of the resulting vApp. You can use this URL with a GET request to retrieve information that you can use to connect to the vApp, modify its configuration, and operate it.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow Response: 200 OK Content-Type: application/vnd.vmware.vcloud.vApp+xml ... ... PAGE 36vCloud API Programming Guide href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" /> Configuration parameters for vAppNetwork ... PAGE 37Chapter 2 Hello vCloud: A Simplified RESTful Workflow href="https://vcloud.example.com/api/vApp/vm-4/screen/action/acquireTicket" /> ... ... ... ...
vCloud API Programming Guide Procedure 1 Retrieve the screen ticket. POST a request to the acquireTicket link of the Vm. Request: POST https://vcloud.example.com/api/vApp/vm-4/screen/action/acquireTicket Response: 200 OK Content-Type: application/vnd.vmware.vcloud.screenTicket+xml ... PAGE 39Chapter 2 Hello vCloud: A Simplified RESTful Workflow 3 Retrieve the XML representation of the vApp again. Now that it has been powered off and undeployed, the vApp includes a rel="remove" link of the following form: 4 Remove the vApp. Make a DELETE request to the vApp's rel="remove" link, as shown in the request portion of “Example: Undeploy, Power Off, and Delete a vApp,” on page 39.
vCloud API Programming Guide Log Out To log out and terminate a vCloud API session, delete the Session you created when you logged in. The logout request, like all other authenticated requests, must include the authorization header, as shown in “Example: Logging Out,” on page 40. Prerequisites Verify that you are logged in. Procedure u Make a DELETE request specifying the href of the current Session object. Example: Logging Out This example deletes the current user's Session, which logs the user out.
Exploring a Cloud 3 You can use HTTP GET requests to browse containers such as organizations, catalogs, and vDCs in a cloud. Responses to these requests include metadata about the container itself and references to the objects it contains. These references are provided in Link elements, which have href attributes whose values the client can use in requests to get more information about the objects themselves.
vCloud API Programming Guide Table 3-1.
Chapter 3 Exploring a Cloud Retrieve the Login URL and List of Supported API Versions Every cloud has a login URL that a client can obtain by making an unauthenticated GET request to the vCloud Director api/versions URL. The response to this request also lists vCloud API versions that the server supports. Procedure 1 Make an API version request to vCloud Director to obtain the login URL for the REST API. See the request portion of “Example: Versions Request and Response,” on page 43.
vCloud API Programming Guide https://vcloud.example.com/api/sessions application/vnd.vmware.vcloud.catalog+xml CatalogType http://vcloud.example.com/api/v1.5/schema/master.xsd ... ...
Chapter 3 Exploring a Cloud The Session element returned from a successful login contains one or more URLs from which you can begin browsing. The list of URLs in the Session object is based on the role and privileges of the authenticated user. A Session object expires after a configurable interval of client inactivity. To change the length of this client inactivity timeout, a system administrator can change the value of SessionTimeoutMinutes in the system's GeneralSettings.
vCloud API Programming Guide This response includes the following link types: orgList A link to the list of organizations that you can access. See “Retrieve a List of Organizations Accessible to You,” on page 48. vcloud A link to administrative objects and operations.
Chapter 3 Exploring a Cloud Table 3-2. Authorization Header Attributes and Values Attribute Name Attribute Value token The compressed, encoded identity assertion from your SAML identity provider. org The name of your vCloud Director organization. See “Example: Create a Login Session Using a SAML Identity Provider,” on page 47. 5 Examine the response. The response code indicates whether the request succeeded, or how it failed.
vCloud API Programming Guide PAGE 49
Chapter 3 Exploring a Cloud 2 Examine the contents of the Session element to locate the link to the organization list. This link has the following form: 3 Retrieve the list of organizations by making a GET request to the href value of the Link. See “Example: Retrieve an Organization List,” on page 49. Example: Retrieve an Organization List Request: GET https://vcloud.example.
vCloud API Programming Guide Prerequisites Use the credentials of an organization administrator or system administrator to create a login session. See “Create a Login Session Using the Integrated Identity Provider,” on page 44. Procedure 1 Retrieve the XML representation of your Session object. Use a request like this one: GET https://vcloud.example.com/api/session 2 Examine the contents of the Session element to locate the link to the VCloud object.
Chapter 3 Exploring a Cloud href="https://vcloud.example.com/api/admin/org/1"/> ... ...
vCloud API Programming Guide Retrieve a List of vSphere Platform Operations and Objects for a Cloud A successful login by a system administrator returns a Session element that contains a link that you can use to retrieve a VMWExtension element. Every vCloud Director installation depends on vSphere platform resources such as vCenter, ESX/ESXi, and vShield Manager.
Chapter 3 Exploring a Cloud rel="down" type="application/vnd.vmware.admin.vmwExternalNetworkReferences+xml" href="https://vcloud.example.com/api/admin/extension/externalNetworkReferences" /> PAGE 54vCloud API Programming Guide 54 VMware, Inc.
Provisioning an Organization 4 The vCloud API provides several ways for you to make vApp templates, vApps, media images, and idependent disks available to users in an organization. The vCloud API allows you to upload and download OVF packages, and upload media images. Operations are characterized as uploads when they transfer content from the local host to a remote host, and as downloads when the local host requests the transfer of content from a remote host.
vCloud API Programming Guide Summary of vCloud API Provisioning Requests Provisioning requests add vApp templates and media to a vDC and a catalog. You can also use provisioning requests to copy, move, rename, and delete these objects. n API-URL is a URL of the form https://vcloud.example.com/api. n id is a unique identifier in the form of a UUID, as defined by RFC 4122. IMPORTANT Request URLs are always available in Link elements contained by the representation of the object on which they operate.
Chapter 4 Provisioning an Organization Table 4-1. Summary of Provisioning Requests (Continued) Operation Request Request Body Response Remove an item from a catalog. DELETE API-URL/ catalog/id/catalogItem/id None 204 No content Control access to catalogs. POST APIURL/catalog/ id/action/controlAccess ControlAccessParams ControlAccessParams Retrieve the owner of a media object. GET APIURL/media/id/owner None Owner Retrieve the owner of a vApp template.
vCloud API Programming Guide Upload Workflow The upload workflow for OVF packages uses a combination of vCloud API requests and standard HTTP file transfer requests. 1 The client uses a POST request that specifies a name and description for the template, and a transfer format for the data. 2 The server returns an unresolved VAppTemplate element with (status="0") that includes an upload URL for the OVF descriptor. 3 The client uses an HTTP PUT request to upload the descriptor to the upload URL.
Chapter 4 Provisioning an Organization 4 Uploading Referenced Files on page 63 You can use a PUT request to upload each file that the vApp template references. Initiating the OVF Upload To initiate the OVF upload, a client makes a POST request to the uploadVAppTemplate URL of the target vDC. The request body is an UploadVAppTemplateParams element.
vCloud API Programming Guide Request: POST https://vcloud.example.com/api/vdc/5/action/uploadVAppTemplate Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml ... Ubuntu vApp Template Response: 201 Created Content-Type: application/vnd.vmware.vcloud.
Chapter 4 Provisioning an Organization The response body includes the following attributes: n An href attribute whose value is a link to the new VAppTemplate object. n An ovfDescriptorUploaded attribute with a value of false, indicating that the OVF descriptor file is not uploaded. n A status attribute with a value of 0, indicating that the file references in the descriptor are not uploaded. (A VAppTemplate with a status of 0 is said to be unresolved.
vCloud API Programming Guide Retrieving the Upload URLs After an OVF descriptor is uploaded, the server validates it and, if it is valid, updates the corresponding template with upload URLs for each of the files referenced in the descriptor. You must retrieve the template to see these URLs. Procedure 1 Retrieve the VAppTemplate to verify that the OVF descriptor is uploaded. Use the URL returned in the response to your uploadVAppTemplate request.
Chapter 4 Provisioning an Organization href="https://vcloud.example.com/transfer/.../manifest.mf"/> ... In this example, which omits most of the additional elements shown in “Example: Initiating the Upload,” on page 59, the ovfDescriptorUploaded attribute has a value of true and the status attribute has a value of 0.
vCloud API Programming Guide After all the files are uploaded, the vApp template is complete, and has a status attribute value of 8. If the upload included a manifest file, the server checks each file in the upload to verify that its checksum matches the one stated in the manifest. If a checksum does not match, the template’s status attribute is set to -1 and the template contains a Task element whose Error element indicates the reason for the failure.
Chapter 4 Provisioning an Organization ... name="Ubuntu Template" id="urn:vcloud:vapptemplate:268" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ... > ... ... ...
vCloud API Programming Guide Request: PUT https://vcloud.example.com/transfer/.../disk0.vmdk Content-Range: bytes 500000000-1950489087/1950489088 Content-Length: 1450489088 ...serialized contents of specified range... EOF Response: 200 OK Download a vApp Template as OVF You can download a vApp template as an OVF package. After you find the template by browsing a catalog, you can request that the template be enabled for download.
Chapter 4 Provisioning an Organization Procedure 1 Retrieve the template to find its action/enableDownload link. Every vApp template includes a link of the following form, where id is the id of the template: 2 Enable the template for download. Make a POST request to the template's action/enableDownload URL. Request: POST https://vcloud.example.
vCloud API Programming Guide Download the OVF Descriptor To download the OVF descriptor, you make a GET request to the download:default URL in the downloadenabled VappTemplate. Prerequisites n Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud. n Verify that you have a vApp template that is enabled for download. See “Enable the vApp Template for Download,” on page 66.
Chapter 4 Provisioning an Organization Procedure 1 For each File element in the References element of the descriptor, construct a download URL. a Start with the URL that you used to download the descriptor. This URL is the href value of the download:default link that the template contains. b 2 Replace the final component of that URL with the value of the href attribute of the File element. Use the constructed URLs to download each file. See “Example: Downloading a Referenced File,” on page 69.
vCloud API Programming Guide Procedure 1 Find the add link for media in the target vDC. This link has the following form: 2 POST a media request to the server. The request body is a Media element that includes information about the virtual media item to upload. See the request portion of “Example: Upload a Media Image,” on page 70.
Chapter 4 Provisioning an Organization rel="remove" href="https://vcloud.example.com/api/media/254" /> ISO database image
vCloud API Programming Guide Copy or Move a vApp The cloneVApp request makes a copy of the vApp referenced in the Source element of the request body. The request specifies a new name and, optionally, a new description for the copy. The request can optionally include an IsSourceDelete element whose value specifies whether to delete the source vApp after the copy is complete.
Chapter 4 Provisioning an Organization Add an Item to a Catalog A catalog can contain references to vApp templates and media images from any vDC in an organization. A vApp template or media image can be listed in at most one catalog. Prerequisites Verify that you are logged in as a user with the Catalog Author role, as an organization administrator, or as a system administrator. Procedure 1 Retrieve the XML representation of your organization and look for links to the catalogs and vDCs it contains.
vCloud API Programming Guide 4 Examine the response to locate the Link element that contains the URL for adding items to the catalog. This element has a rel attribute value of add and a type attribute value of application/vnd.vmware.admin.catalogItem+xml, as this example shows: PAGE 75
Chapter 4 Provisioning an Organization xmlns="http://www.vmware.com/vcloud/v1.5" name="Ubuntu Template with vsftpd" id="urn:vcloud:catalogitem:221" href="https://vcloud.example.com/api/catalogItem/221" ... > PAGE 76
vCloud API Programming Guide Create or Update an Independent Disk To create an independent disk in an organization vDC, POST a DiskCreateParams element to the vDC's disk link. To create an independent disk, you must specify its name and size. You can optionally include a description and specify a storage profile to be used by the disk. After you have created the disk, you can modify its name, description, and storage profile. The owner of a disk is initially the user who created it.
Chapter 4 Provisioning an Organization status="0" name="500GB-SCSI" id="urn:vcloud:disk:128" type="application/vnd.vmware.vcloud.disk+xml" href="https://vcloud.example.com/api/disk/128" ... > PAGE 78
vCloud API Programming Guide Remove an Independent Disk To remove an independent disk, verify that no powered-on virtual machines are attached to it, then use a DELETE request to delete it. A Disk element includes a link of the following form, which you can GET to return a list of virtual machines to which the disk is attached. PAGE 79
Chapter 4 Provisioning an Organization View or Change the Owner of an Object You can view the owner of a VApp, VAppTemplate, Disk, or Media object by making a GET request to the object's owner link. If you have adequate rights, you can change the owner of a Disk or VApp object, but not that of a VAppTemplate or Media object. An administrator can view or change the owner of any object. The initial owner of a VApp, VAppTemplate, Catalog, Disk, or Media object is the user who created it.
vCloud API Programming Guide 80 VMware, Inc.
Deploying and Operating vApps 5 The vCloud API supports programmatic access to a range of self-service datacenter operations that allow users to create, configure, deploy, and operate vApps. The initial configuration of a vApp is established in the OVF package on which its source template is based. In the vCloud API, vApp templates are based on OVF 1.0.
vCloud API Programming Guide n An undeployed vApp, created when a vApp template is instantiated without also being deployed, or a deployed vApp is undeployed. n A deployed vApp, ready to be powered on and operated. Instantiation can include deployment, poweron, or both. Figure 5-1.
Chapter 5 Deploying and Operating vApps n “Operate a vApp,” on page 96 n “Configuring vApps and Virtual Machines,” on page 97 Summary of vCloud API vApp and Virtual Machine Operations Requests These vCloud API operations requests create, manage, operate, and delete vApps and the virtual machines that they contain. n API-URL is a URL of the form https://vcloud.example.com/api. n id is a unique identifier in the form of a UUID, as defined by RFC 4122.
vCloud API Programming Guide Table 5-1.
Chapter 5 Deploying and Operating vApps Table 5-1. Summary of vApp and Virtual Machine Operations Requests (Continued) Operation Request Request Body Response Revert all virtual machines in a vApp to their current snapshots. [NEW] POST APIURL/vApp/vapp-id/ action/revertToCurrentSna pshot None Task Retrieve information about vApp snapshots. [NEW] GET API-URL/vApp/vappid/snapshotSection None SnapshotSection Validate the storage profile compliance of a virtual machine.
vCloud API Programming Guide 2 Examine the template to determine the set of instantiation parameters that the request must include. 3 Create an InstantiateVAppTemplateParams element. See “Example: Instantiate a vApp Template,” on page 86 for guidelines. 4 Make a POST request to the action/instantiateVAppTemplate URL of the vDC. Supply the InstantiateVAppTemplateParams element as the request body. The server takes the requested action and returns a VApp element.
Chapter 5 Deploying and Operating vApps true The response is a sparsely populated VApp element, as shown in the response portion of “Example: Deploying a vApp,” on page 32.
vCloud API Programming Guide Procedure 1 Find the composeVApp link in the target vDC. The XML representation of the vDC contains a composeVapp link, which has the following form: 2 Create a ComposeVappParams element that specifies the details of the composition. 3 POST the ComposeVappParams element to the composeVapp link of the target vDC.
Chapter 5 Deploying and Operating vApps xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="https://vcloud.example.
vCloud API Programming Guide Recompose a vApp to Add or Remove Virtual Machines The vCloud API supports recomposition of a vApp to add or remove virtual machines. To recompose a vApp, make a recomposeVApp request, supplying a RecomposeVAppParams element as the request body. The RecomposeVAppParams element allows an arbitrary number of DeleteItem elements, but is otherwise identical to ComposeVAppParams.
Chapter 5 Deploying and Operating vApps name="CRM-CRM" href="https://vcloud.example.com/api/vApp/vm-44" ...> ... ... ... The request removes one of the virtual machines from the vApp and creates a StartupSection that specifies a startup order for the remaining virtual machines. Request: POST https://vcloud.example.com/api/vApp/vapp-33/action/recomposeVApp Content-Type: application/vnd.
vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... NOTE Virtual machines specified in Source elements must be powered off or this operation will fail. You can use a query like this one to return a list of references to powered-off virtual machines that you have access to. https://vcloud.example.
Chapter 5 Deploying and Operating vApps Response: 200 OK Content-type: application/vnd.vmware.vcloud.vmPendingQuestion+xml ... msg.parallel.file.open:Parallel port output file "/vmfs/volumes/d6162a46-58e50cab/linuxftp/vm-mgi.log" already exists.
vCloud API Programming Guide You can POST a DiskAttachOrDetachParams element to one of these URLs to attach or detach an independent disk. Prerequisites n Verify that you are logged in to the vCloud API as a system administrator or the object owner. n Verify that the vDC contains an independent disk.
Chapter 5 Deploying and Operating vApps operationName="vappAttachDisk" ... /> ... Creating and Using vApp Snapshots You can take a snapshot of all the virtual machines in a vApp. After the snapshots are taken, you can revert all virtual machines in the vApp to the most recent snapshot, or remove all snapshots. You can take a snapshot of a vApp whether or not it is powered on. The createSnapshot operation always creates a snapshot for each virtual machine in the vApp.
vCloud API Programming Guide Response: ... After the snapshot is created, you can revert the vApp to the state captured in the snapshot. POST https://vcloud.example.com/api/vApp/vapp-33/action/revertToCurrentSnapshot You can also remove all snapshots. POST https://vcloud.example.com/api/vApp/vapp-33/action/removeAllSnapshots Neither of these requests has a request body. Both return a Task.
Chapter 5 Deploying and Operating vApps Configuring vApps and Virtual Machines You specify configuration details for vApps and the virtual machines they contain in ovf:SectionType elements contained in a VApp or Vm element. You can include most of these sections in the InstantiationParams that you supply when you instantiate a vApp template. You can also retrieve, modify, and update these sections to reconfigure a deployed vApp.
vCloud API Programming Guide Configuring a vApp You can include the following sections in the InstantiationParams associated with an instantiateVAppTemplate, composeVApp, or recomposeVApp request. You can also modify them in a deployed vApp. LeaseSettingsSection Defines the terms of storage and deployment leases for the vApp. If this section is omitted, the vApp inherits the default lease settings of the containing organization.
Chapter 5 Deploying and Operating vApps Modified sections must contain all required elements, even if you are not changing their values. Because optional elements revert to default values if they are omitted or empty, it is a best practice to include optional elements in updates. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes might be read-only. See the schema reference for details.
vCloud API Programming Guide ... ... ... PAGE 101
Chapter 5 Deploying and Operating vApps Table 5-2. Summary of vApp Reconfiguration Requests (Continued) Operation Request Request Body Response Retrieve vApp NetworkConfigSection GET API-URL/vApp/vappid/ networkConfigSection/ None NetworkConfigSection Update vApp NetworkConfigSection PUT API-URL/vApp/vappid/ networkConfigSection/ NetworkConfigSection Task Retrieve the Configuration Links for a Virtual Machine A virtual machine is represented by a Vm element.
vCloud API Programming Guide ... ... PAGE 103Chapter 5 Deploying and Operating vApps ... Specifies the available VM network connections 0 0 10.147.122.
vCloud API Programming Guide Table 5-3.
Chapter 5 Deploying and Operating vApps Table 5-3. Summary of Vm Reconfiguration Requests (Continued) Operation Request Request Body Response Update network card items in the VirtualHardwareSection of a virtual machine PUT API-URL/vApp/vm-id/ virtualHardwareSection/ networkCards RasdItemsList Task Update the name, Description, and any or all of VirtualHardwareSection, OperatingSystemSection, NetworkConnectionSectio n, GuestCustomizationSecti on of a virtual machine.
vCloud API Programming Guide Table 5-4. vCloud API Custom Attributes for OVF and RASD Elements (Continued) Element Name RASD Resource Type Attribute Name Attribute Type Description rasd:HostResource 17 (Hard disks) busSubType xs:string read-only ovf:OperatingSystemSec tion N/A osType xs:string Internal VMware identifier for the guest operating system. See https://www.vmware.com/suppor t/developer/vcsdk/visdk41pubs/ApiReference/vim .vm.GuestOsDescriptor.GuestOsIde ntifier.
Chapter 5 Deploying and Operating vApps Request: POST https://vcloud.example.com/api/vApp/vm-4/action/reconfigureVm Content-Type: application/vnd.vmware.vcloud.vm+xml ... ... Firewall allows access to this address.
vCloud API Programming Guide Retrieve or Update a Modifiable Section You can make a GET request to the URL of any modifiable section to retrieve it for modification. After you modify the section, you can make a PUT request to its edit link to update the section with your modifications. Prerequisites Verify that you are logged in to the vCloud API as a system administrator or the object owner. Procedure 1 Retrieve the section to modify. Make a GET request to the URL in the section's href attribute value.
Chapter 5 Deploying and Operating vApps true 10.147.56.253 255.255.255.0 10.147.115.1 10.147.115.2 example.com 10.147.56.1 10.147.56.255 PAGE 110vCloud API Programming Guide Example: Update a NetworkConfigSection This example modifies the NetworkConfigSection that was retrieved in “Example: Retrieve a NetworkConfigSection,” on page 108. The modifications change the FenceMode value to natRouted and add a Features element that defines several network features that are useful to an FTP server that must be reachable from the public Internet, but only at the FTP and SSH ports.
Chapter 5 Deploying and Operating vApps natRouted true true FTP Rule allow true 21 10.147.115.
vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... IMPORTANT Whenever you modify a vApp network, as we do in this example, you must be sure that the modifications are consistent with the network connection requirements of the virtual machines in the vApp. The vApp in this example contains a single virtual machine.
Chapter 5 Deploying and Operating vApps Firewall Service A FirewallService element defines firewall rules that, when matched, block or allow incoming or outgoing traffic on the vApp network. A firewall rule in a vApp network can specify the destination as a combination of address and port, or as a specific virtual NIC in a Vm This FirewallService allows TCP traffic to ports 21 and 22.
vCloud API Programming Guide 3963994b-5a0a-48fe-b9ae-7f9a2d8e8e5b 0 assigned Any Any false NAT Service A NatService element defines network address translation services to virtual machines on the network. This simple NatService defines a single rule that implements an IP translation stratagy for a single Vm.
Chapter 5 Deploying and Operating vApps n The Configuration of the vApp network in vApp2 has a RouterInfo element whose ExternalIp value is 192.168.0.101. n Both vApp networks have the same ParentNetwork, an organization vDC network whose network specification in CIDR notation is 192.168.0.0/24. You can enable static routing between these two vApp networks by inserting a StaticRoutingService element in the Features of each vApp network Configuration.
vCloud API Programming Guide 2 Modify the returned NetworkConnectionSection as needed. Modified sections must contain all required elements, even if you are not changing their values. Because optional elements revert to default values if they are omitted or empty, it is a best practice to include optional elements in updates. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes might be read-only.
Chapter 5 Deploying and Operating vApps Retrieve or Modify the CPU Configuration of a Virtual Machine The CPU configuration of a virtual machine is represented by an Item in its VirtualHardwareSection element. Prerequisites Verify that you are logged in to the vCloud API as a system administrator or the object owner. Procedure 1 Retrieve the CPU section to modify. Make a GET request to the URL in the section's href attribute value: GET https://vcloud.example.
vCloud API Programming Guide 3 2 0 Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ...
Chapter 5 Deploying and Operating vApps Example: Modify the Guest Customization Section of a Virtual Machine This request specifies guest customization values, including the information required to join the virtual machine to a Windows domain. NOTE If you include a CustomizationScript, it cannot exceed 49,000 characters. Request: PUT https://vcloud.example.com/api/vApp/vm-12/guestCustomizationSection/ Content-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml ...
vCloud API Programming Guide Retrieve or Modify ProductSection Elements ProductSection elements allow you to pass runtime information to vApps and virtual machines. The key=value pairs in this section are made available in the OVF Environment of a powered-on vApp or virtual machine. A vApp or virtual machine can get runtime information from its ovf:Environment element. This read-only element is populated with information from a ProductSection element when the vApp or virtual machine is powered on.
Chapter 5 Deploying and Operating vApps Example: Update a ProductSection in a vApp This request creates or updates a ProductSectionList that contains a single ProductSection. The ProductSection sets three properties. The response is a Task. Request: PUT https://vcloud.example.com/api/vApp/vapp-123/productSections Content-Type: application/vnd.vmware.vcloud.productSections+xml ... PAGE 122vCloud API Programming Guide ... n If the virtual machine has VMware Tools installed, it can use the vmtoolsd program, as shown here. [root@example-vm-RHEL ~] /usr/sbin/vmtoolsd --cmd 'info-get guestinfo.ovfEnv' ...
Chapter 5 Deploying and Operating vApps Procedure 1 Retrieve the RasdItemsList from a Vm. Make a GET request to the URL in the link where type="application/vnd.vmware.vcloud.rasdItemsList +xml" and rel="down". See “Example: Retrieve the Hard Disks and Controllers in a Virtual Machine,” on page 123. 2 Modify the items in the retrieved list. Modified sections must contain all required elements, even if you are not changing their values.
vCloud API Programming Guide vcloud:capacity="1024" vcloud:busSubType="lsilogic" vcloud:busType="6"> 2000 2 17 - 1 Hard disk Hard disk 2 PAGE 125
Chapter 5 Deploying and Operating vApps 3 Update the section with your modifications. Find the Link element in the section where rel="edit". Make a PUT request to the URL in that link's href attribute value, and supply the modified section as the request body. The response to this request is a Task element that tracks the update operation. When the task is complete, the section is updated. The modified section replaces the contents of the original section.
vCloud API Programming Guide vcloud:capacity="2048" vcloud:busSubType="lsilogic" vcloud:busType="6"> 2001 2 17 - 0 IDE Controller IDE Controller 0 3 5
The response is a task.
Chapter 5 Deploying and Operating vApps 2 Modify the retrieved Vm to change the StorageProfile reference. Modified sections must contain all required elements, even if you are not changing their values. Because optional elements revert to default values if they are omitted or empty, it is a best practice to include optional elements in updates. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes might be read-only.
vCloud API Programming Guide 128 VMware, Inc.
Creating and Managing Organizations 6 The VMware vCloud API supports objects and operations that an organization or a system administrator can use to automate tasks associated with creating and managing organizations and their vDCs, networks, catalogs, and users. A successful login by an organization or system administrator returns a Session element, which contains a link that enables the administrator to retrieve a VCloud element.
vCloud API Programming Guide Table 6-1. Summary of Administrative Requests 130 Operation Request Request Body Response Retrieve an administrative view of an organization. GET API-URL/admin/org/id None AdminOrg Create an organization. POST API-URL/admin/orgs AdminOrg AdminOrg Enable an organization. POST APIURL/admin/org/ id/action/enable None 204 No Content Disable an organization. POST APIURL/admin/org/ id/action/disable None 204 No Content Update an organization.
Chapter 6 Creating and Managing Organizations Table 6-1. Summary of Administrative Requests (Continued) Operation Request Request Body Response List the organization vDCs supported by a provider vDC. GET APIURL/admin/providervdc/ id/vdcReferences None VdcReferences Create an organization vDC. POST APIURL/admin/org/id/vdcs AdminVdc AdminVdc Enable an organization vDC. POST APIURL/admin/vdc/ id/action/enable None 204 No Content Disable an organization vDC.
vCloud API Programming Guide Administrator Credentials and Privileges An administrator's privileges are scoped by the organization to which the administrator authenticates. The vCloud API defines two levels of administrative privilege: n Organization administrators, who have administrative privileges in a specific organization. n System administrators, who have superuser privileges throughout the system.
Chapter 6 Creating and Managing Organizations Create an Organization To create an organization, a system administrator POSTs an AdminOrg element to the cloud’s add URL for orgs. Prerequisites Verify that you are logged in to the vCloud API as a system administrator. Procedure 1 Retrieve the XML representation of the cloud. Use a request like this one. GET https://vcloud.example.com/api/admin 2 Examine the response to locate the Link element that contains the URL for adding organizations to the cloud.
vCloud API Programming Guide true 0 0 false 0 SYSTEM true true
Chapter 6 Creating and Managing Organizations type="application/vnd.vmware.admin.vdc+xml" href="https://vcloud.example.com/api/admin/org/26/vdcs" /> PAGE 136
vCloud API Programming Guide rel="edit" type="application/vnd.vmware.admin.orgSettings+xml" href="https://vcloud.example.com/api/admin/org/26/settings" /> PAGE 137Chapter 6 Creating and Managing Organizations OrgLdapSettings Defines whether this organization is connected to an LDAP service, and whether it uses the service defined in the system LdapSettings or a custom LDAP service defined here. OrgEmailSettings Defines whether this organization uses the email service defined in the system EmailSettings or a custom email service defined here. OrgPasswordPolicySettin Specifies policies to be followed when a user in this organization enters an incorrect password.
vCloud API Programming Guide 4 Modify the retrieved settings element. Modified sections must contain all required elements, even if you are not changing their values. Because optional elements revert to default values if they are omitted or empty, it is a best practice to include optional elements in updates. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes might be read-only. See the schema reference for details.
Chapter 6 Creating and Managing Organizations Enable, Disable, or Remove an Organization An AdminOrg element includes action links that a system administrator can use to enable, disable, or remove the organization. Prerequisites n Verify that you are logged in to the vCloud API as a system administrator. n Retrieve the XML representation of the organization. See “Retrieve a List of Organizations Accessible to You,” on page 48.
vCloud API Programming Guide Add a vDC to an Organization A system administrator can allocate resources from a provider vDC to a vDC in an organization by POSTing a CreateVdcParams element to an organization’s add URL for vDCs. Prerequisites Verify that you are logged in to the vCloud API as a system administrator. Retrieve the list of network pools. Several types of organization vDC networks require the vDC to include a network pool, which you can specify when you create or update the vDC.
Chapter 6 Creating and Managing Organizations 4 Create a CreateVdcParams request body. a Include an AllocationModel element that specifies how compute resources are allocated by this vDC. Choose one of the following values for AllocationModel: AllocationVApp Pay as you go. Resources are committed to the organization vDC only when vApps are created in it.
vCloud API Programming Guide MHz 2048 2048 MB 2048 2048 0 100 true MB 20480 true PAGE 143Chapter 6 Creating and Managing Organizations Example vDC ...
vCloud API Programming Guide resgroup-949 RESOURCE_POOL PAGE 145
Chapter 6 Creating and Managing Organizations MB 20480 false ... Update Organization vDC Storage Profiles A system administrator can update the storage profiles that are available in an organization vDC. You can add new storage profiles and remove unused storage profiles.
vCloud API Programming Guide To remove a storage profile: a Examine the VdcStorageProfiles element and find the profile to remove. b Verify that it is not the default storage profile for the vDC, and that no virtual machines are using it. You can use the adminVm query and filter on the storageProfileName attribute to list all storage profiles that are in use. c 4 Create an UpdateVdcStorageProfiles element that contains a DeleteStorageProfile element for each storage profile to remove.
Chapter 6 Creating and Managing Organizations Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Enable, Disable, or Remove a vDC A system administrator can use the enable, disable, and remove links in an AdminVdc body to enable, disable, or remove the vDC.
vCloud API Programming Guide About vCloud Director Networks There are three categories of vCloud Director networks: external networks, organization vDC networks, and vApp networks. Additional infrastructure objects such as Edge Gateways and network pools are required by most categories of networks. You must be a system administrator to create an external network, a directly connected organization vDC network, a network pool, or an Edge Gateway.
Chapter 6 Creating and Managing Organizations n The Features element defines features of the vApp network, and can include the following services: DhcpService Provides DHCP services to virtual machines on the network. FirewallService Specifies firewall rules that, when matched, block or allow incoming or outgoing network traffic. NatService Provides network address translation services to virtual machines on the network. StaticRoutingService Specifies static routes to other networks.
vCloud API Programming Guide Table 6-2. Types of Organization vDC Networks and Their Requirements Organization vDC Network Connection Description Requirements Direct connection to an external network. Provides direct layer 2 connectivity to machines and networks outside of the organization vDC. Machines outside of this organization vDC can connect directly to machines within the organization vDC. The cloud must contain an external network. Routed connection to an external network.
Chapter 6 Creating and Managing Organizations Create an Edge Gateway An Edge Gateway is a virtual router for organization vDC networks. You can configure it to provide network services such as DHCP, firewall, NAT, static routing, VPN, and load balancing. You can create an Edge Gateway in either a compact or a full configuration. The full configuration provides increased capacity and performance. The compact configuration requires less memory and fewer compute resources.
vCloud API Programming Guide 2 Choose an external network to use for the Edge Gateway's initial uplink interface. This external network must be one of the networks listed in the AvailableNetworks element of the Provider vDC that backs the organization vDC in which you are creating the Edge Gateway. Follow these steps to find a suitable external network. a Retrieve the XML representation of the organization vDC in which you are creating the Edge Gateway. Use a request like this one: GET https://vcloud.
Chapter 6 Creating and Managing Organizations For information about additional elements that an EdgeGateway can contain, see “Example: Create an Edge Gateway,” on page 153 and the schema reference. 4 POST the EdgeGateway element to the URL for adding Edge Gateways to the organization vDC. The server takes the requested action and returns an XML representation of the partially-created object.
vCloud API Programming Guide Request: POST https://vcloud.example.com/api/admin/vdc/44/edgeGateways Content-Type: application/vnd.vmware.admin.edgeGateway+xml ... PAGE 155Chapter 6 Creating and Managing Organizations type="application/vnd.vmware.admin.edgeGateway+xml" href="https://vcloud.example.com/api/admin/edgeGateway/2000" /> PAGE 156
vCloud API Programming Guide false false
Configure Edge Gateway Services An organization administrator or system administrator can configure NAT, firewall, and similar services on an existing Edge Gateway by updating its EdgeGatewayServiceConfiguration.
Chapter 6 Creating and Managing Organizations The server takes the requested action and returns a Task element that tracks the progress of the request. When the task completes successfully, the EdgeGatewayServiceConfiguration element you POSTed replaces the one you copied in Step 3. Example: Configure Services on an Edge Gateway This example replaces the default firewall service on the Edge Gateway created in “Create an Edge Gateway,” on page 151.
vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... Firewall Service Configurations The default FirewallService in an EdgeGatewayServiceConfiguration is enabled and configured to block all incoming traffic. You can modify that FirewallService to allow incoming traffic, block outgoing traffic, or both.
Chapter 6 Creating and Managing Organizations Table 6-3. SourceIp and DestinationIp Values Value Result Any Matches any IP address Internal Matches any IP address originating on an organization vDC network connected to this EdgeGateway. When used in a vApp network, matches any IP address assigned to a virtual machine in the vApp. External Matches any IP address originating on an external network connected to this EdgeGateway.
vCloud API Programming Guide External false You can see this fragment in the context of an Edge Gateway configuration in “Example: Configure Services on an Edge Gateway,” on page 157. NAT Service Configurations An Edge Gateway configuration can define a NAT (Network Address Translation) service that translates source or destination IP addresses and port numbers.
Chapter 6 Creating and Managing Organizations SNAT true 192.168.0.10 10.147.115.155 any To add this service to an Edge Gateway, include it in an EdgeGatewayServiceConfiguration. See “Example: Configure Services on an Edge Gateway,” on page 157.
vCloud API Programming Guide false vnic3 routed2 internal 172.168.0.1 255.255.255.0 172.168.0.
Chapter 6 Creating and Managing Organizations Static Routes Between vApp Networks For an example of a static routing service in a vApp network, see “Network Services in vApp Networks,” on page 112. Load Balancer Service Configurations An Edge Gateway can provide load-balancing services that allow you to distribute incoming requests to a specific external IP address across multiple internal IP addresses. Several load-balancing algorithms are supported.
vCloud API Programming Guide n A VirtualServer element that defines the Interface, an internal or external interface defined by the containing EdgeGateway, on which requests are accepted. NOTE The network referenced in the Interface element must be configured with an IP sub-allocation. NOTE Each Member of a load balancer Pool can contain its own ServicePort element. If this element is present in a Member, its contents override the ServicePort element of the Pool.
Chapter 6 Creating and Managing Organizations true HTTPS_pool To add this service to an Edge Gateway, include it in an EdgeGatewayServiceConfiguration. See “Example: Configure Services on an Edge Gateway,” on page 157.
vCloud API Programming Guide Gateway DHCP Service Configurations An Edge Gateway configuration can define a DHCP service that assigns IP addresses to clients on organization vDC networks. You can configure multiple address pools, each of which defines a range of IP addresses that are reserved for a specific network. DHCP services for organization vDC networks are provided by the Edge Gateway to which those network connect. An EdgeGateway can contain an more GatewayDhcpService element.
Chapter 6 Creating and Managing Organizations For more information about the types of networks you can create and the resources on which they depend, see “About vCloud Director Networks,” on page 148. Prerequisites Verify that you are logged in to the vCloud API as an organization administrator or system administrator. Procedure 1 Retrieve the XML representation of the organization vDC to which you want to add the network. This request retrieves the admin view of an organization vDC. GET https://vcloud.
vCloud API Programming Guide Procedure 1 Choose the external network to which this organization vDC network will connect. This external network must be one of the ones listed in the AvailableNetworks element of the Provider vDC that backs the organization vDC in which you are creating the new network. Follow these steps to find a suitable external network. a Retrieve the XML representation of the organization vDC in which you are creating the new network. Use a request like this one: GET https://vcloud.
Chapter 6 Creating and Managing Organizations The server takes the requested action and returns an XML representation of the partially-created object. This representation includes an href attribute, properties specified in the creation request, and an embedded Task element that tracks the creation of the object. When the task completes, the object has been created, and you can use the value of the href attribute with a GET request to retrieve the XML representation of the object.
vCloud API Programming Guide type="application/vnd.vmware.vcloud.allocatedNetworkAddress+xml" href="https://vcloud.example.com/api/admin/network/54/allocatedAddresses/" /> Bridged to the public Internet ...
Chapter 6 Creating and Managing Organizations 4 POST the OrgVdcNetwork element you created in Step 2 to the URL for adding networks to the organization vDC. See the request portion of “Example: Create an Organization vDC Network With a Routed Connection,” on page 171 The server takes the requested action and returns an XML representation of the partially-created object.
vCloud API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.vcloud.orgVdcNetwork+xml ... PAGE 173Chapter 6 Creating and Managing Organizations Create an Isolated Organization vDC Network An isolated organization vDC network provides an isolated, private network that machines in the organization vDC can connect to. This network provides no connectivity to machines outside this organization vDC. Machines outside of this organization vDC have no connectivity to machines within the organization.
vCloud API Programming Guide isolated false 3600 7200 192.168.0.2 192.168.0.99 Response: 201 Created Content-Type: application/vnd.vmware.vcloud.orgVdcNetwork+xml ... PAGE 175Chapter 6 Creating and Managing Organizations false 3600 7200 192.168.0.2 192.168.0.
vCloud API Programming Guide Example: Synchronize Syslog Server Settings for an Edge Gateway This request synchronizes the syslog server settings for the Edge Gateway created in “Create an Edge Gateway,” on page 151. POST https://vcloud.example.com/api/admin/edgeGateway/2000/action/syncSyslogServerSettings Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Catalog Administration A newly created organization has no catalogs in it.
Chapter 6 Creating and Managing Organizations 2 Examine the response to locate the Link element that contains the URL for adding catalogs to the organization. This element has a rel attribute value of add and a type attribute value of application/vnd.vmware.admin.catalog+xml, as shown here: 3 Create an AdminCatalog element.
vCloud API Programming Guide rel="up" type="application/vnd.vmware.admin.organization+xml" href="https://vcloud.example.com/api/admin/org/26" /> PAGE 179
Chapter 6 Creating and Managing Organizations Procedure 1 Retrieve the XML representation of the catalog to publish. Use a request like this one, where id is the identifier of the catalog: GET https://vcloud.example.com/api/admin/catalog/id 2 Examine the response to locate the Link element that contains the URL for publishing the catalog. This element has a rel attribute value of publish and a type attribute value of application/vnd.vmware.admin.
vCloud API Programming Guide About Identity Providers In vCloud Director, an identity provider is a service that accepts credentials such as a user name and password and authenticates the user as a member of a group or organization. vCloud Director recognizes two kinds of identity providers: Integrated The integrated identity provider is a service provided by vCloud Director. It can authenticate users who are created locally or imported from LDAP.
Chapter 6 Creating and Managing Organizations The response is a User element, most of which does not appear in the example. The response includes a link that an administrator can use to edit user properties, and additional elements, such as IsDefaultCached and StoredVmQuota, whose values are inherited from the organization. n The Password element, which must not be empty when you create a User, is never returned. n The ProviderType, which was not specified in the request, defaults to INTEGRATED.
vCloud API Programming Guide Import a User from an LDAP Database If an organization defines an LDAP service to use, an organization or system administrator can import user accounts from that service. Importing a group from LDAP imports all the users in the group. See “Import a Group from an LDAP Database,” on page 183. You can also import users individually. Prerequisites n Verify that you are logged in to the vCloud API as an organization administrator or system administrator.
Chapter 6 Creating and Managing Organizations Response: 201 Created Content-Type: application/vnd.vmware.admin.user+xml ... Imported User Full Name user@example.
vCloud API Programming Guide Example: Import a Group from an LDAP Database This example imports a group to the organization created in “Example: Create an Organization,” on page 133. The response is a Group element, most of which does not appear in the example. The response includes a link that an administrator can use to edit group metadata such as name and description, and a UsersList element that includes a UserReference element for each user in the group.
Chapter 6 Creating and Managing Organizations PAGE 186vCloud API Programming Guide Example: Import a User from a SAML Identity Provider This example is identical to the one shown in “Example: Import a User from an LDAP Database,” on page 182, but includes a ProviderType element that specifies the source as the organization's SAML identity provider. It also omits the IsExternal element, which is required when importing from LDAP but is ignored when importing from SAML. Request: POST https://vcloud.example.
Chapter 6 Creating and Managing Organizations Working With Roles and Rights A role associates a role name with a set of rights. A newly created organization includes a set of predefined roles and rights inherited from the containing cloud. An organization administrator can add new roles or modify predefined roles. vCloud Director uses roles, and their associated rights, to determine whether a user or group is authorized to perform an operation.
vCloud API Programming Guide Table 6-4.
Chapter 6 Creating and Managing Organizations Table 6-4.
vCloud API Programming Guide Procedure 1 Create a Role element that defines the role with a name and a set of rights. To get the RightReference objects you will need to populate the Role, retrieve the administrative view of the cloud, using a request like this one: GET https://vcloud.example.com/api/admin 2 POST the Role element to the organization's add URL for roles. See the request portion of “Example: Create a Role,” on page 190.
Chapter 6 Creating and Managing Organizations rel="remove" href="https://vcloud.example.com/api/admin/role/102"/> Create and manage vApps ... Controlling Access to vApps and Catalogs An organization administrator can use controlAccess links to control access to vApps and catalogs. Catalogs and vApps include two types of access control links: n Links where rel="down". PAGE 192
vCloud API Programming Guide FullControl PAGE 193Managing and Monitoring a Cloud 7 The VMware vCloud API includes extensions that support operations on the vSphere platform, which provides resources to vCloud Director. A system administrator can use these extensions to retrieve or update the configuration of a cloud, add or remove vSphere resources, and import vApps and media from vCenter. Only the system administrator can perform vSphere platform operations.
vCloud API Programming Guide n id is a unique identifier in the form of a UUID, as defined by RFC 4122. IMPORTANT Request URLs are always available in Link elements contained by the representation of the object on which they operate. URL forms shown here are for reference purposes only. Although URLs have a wellknown syntax and a well-understood interpretation, a client should treat vCloud API request URLs as opaque strings.
Chapter 7 Managing and Monitoring a Cloud Table 7-1. Summary of vSphere Platform Extension Requests (Continued) Operation Request Request Body Response Unprepare a host. POST APIURL/admin/extension/hos t/id/action/unprepare None Task Enable a host. POST APIURL/admin/extension/hos t/id/action/enable None Task Disable a host. POST APIURL/admin/extension/hos t/id/action/disable None Task Repair a host. POST APIURL/admin/extension/hos t/id/action/repair None 204 No Content Upgrade a host.
vCloud API Programming Guide Table 7-1. Summary of vSphere Platform Extension Requests (Continued) 196 Operation Request Request Body Response Retrieve a network pool. GET APIURL/admin/extension/net workPool/id None VMWNetworkPool Update a network pool. PUT APIURL/admin/extension/net workPool/id VMWNetworkPool VMWNetworkPool Delete a network pool. DELETE APIURL/admin/extension/net workPool/id None Task Import a virtual machine from vCenter as a vApp.
Chapter 7 Managing and Monitoring a Cloud Table 7-1. Summary of vSphere Platform Extension Requests (Continued) Operation Request Request Body Response Remove a vApp from maintenance mode. POST APIURL/vApp/ id/action/exitMaintenance Mode None 204 No Content Relocate a virtual machine in a vApp template to a different datastore. [DEPRECATED] POST APIURL/vAppTemplate/vmid/action/relocate RelocateParams Task Relocate a virtual machine to a different datastore.
vCloud API Programming Guide EmailSettings Define configuration and connection parameters for the system default email service, and specifies properties of email alerts that the system sends. License System license serial number and related settings. BrandingSettings Allow you to customize the branding of the vCloud Director client UI and some of the links that appear on the vCloud Director Home login screen.
Chapter 7 Managing and Monitoring a Cloud 2 Examine the response to locate the Link element that contains the URL for adding vCenter servers to the cloud. This element has a rel attribute value of add and a type attribute value of application/vnd.vmware.admin.registerVimServerParams+xml, as shown here: PAGE 200
vCloud API Programming Guide Finding Available vCenter Resources Many of the operations required to import virtual machines or create Provider vDCs, external networks, and network pools require you to identify vCenter resources and obtain references to them. You use these references to make the vCenter resources available in the cloud.
Chapter 7 Managing and Monitoring a Cloud Response: 200 OK ... ... PAGE 202vCloud API Programming Guide Prerequisites n Verify that you are logged in to the vCloud API as a system administrator. n Retrieve the XML representation of a vCenter server registered to your cloud. See “Finding Available vCenter Resources,” on page 200. Procedure 1 Examine the VimServer element to locate its resourcePoolList link. The link has the following form: PAGE 203Chapter 7 Managing and Monitoring a Cloud DATASTORE resgroup-230 RESOURCE_POOL PAGE 204vCloud API Programming Guide Response: 200 OK Content-Type: application/vnd.vmware.admin.vimservernetworks+xml ... PAGE 205Chapter 7 Managing and Monitoring a Cloud 2 Examine the response, a VMWExtension element, to locate the links to lists of external networks and network pools. These links have the following form: PAGE 206vCloud API Programming Guide 2 Examine the response, a VimServer element, to locate the vmsList link. This link has the following form: 3 Retrieve the list of virtual machines. See the request portion of “Example: Retrieve a List of Virtual Machines from a vCenter Server,” on page 206.
Chapter 7 Managing and Monitoring a Cloud Retrieve a List of Storage Profiles from a vCenter Server You can retrieve the list of storage profiles that have been defined on a vCenter server registered to a cloud. To retrieve the list, you make a GET request to the server's storageProfiles link. Storage profiles are named configurations of vCenter storage. When you create a Provider vDC, you must specify the name of at least one storage profile to provide storage capacity for that Provider vDC.
vCloud API Programming Guide Example: Retrieve a List of Storage Profiles from a vCenter Server Request: GET https://vcloud.example.com/api/admin/extension/vimServer/9/storageProfiles This response shows that the specified vCenter server contains three storage profiles, named Gold, Silver, and Bronze.
Chapter 7 Managing and Monitoring a Cloud Create a Provider vDC A Provider vDC is a collection of compute, memory, and storage resources from one vCenter. A Provider vDC provides resources to organization vDCs. A Provider vDC is represented as a VMWProviderVdc element in the extension view and a ProviderVdc element in the admin view.
vCloud API Programming Guide The server creates and enables the Provider vDC and returns a VMWProviderVdc element that includes information derived from the contents you POSTed, along with a set of Link elements that you can use to access, remove, disable, or modify the Provider vDC. n The new Provider vDC becomes a member of the ProviderVdcReferences element of the VCloud. n The resource pool you selected is removed from the resource pool list of the vCenter server.
Chapter 7 Managing and Monitoring a Cloud xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" status="0" name="PvDC-Example" id="urn:vcloud:providervdc:35" type="application/vnd.vmware.admin.vmwprovidervdc+xml" ... > PAGE 212vCloud API Programming Guide PAGE 213Chapter 7 Managing and Monitoring a Cloud Retrieve a Provider vDC Resource Pool Set The VMWProviderVdcResourcePoolSet of a Provider vDC contains information about all of the Provider vDC's resource pools. Getting this information is usually a prerequisite to adding or removing a resource pool. Each reference in a VMWProviderVdcResourcePoolSet lists the vCenter server that provides the resource pool and indicates whether the resource pool is primary.
vCloud API Programming Guide href="https://vcloud.example.com/api/admin/extension/resourcePool/64/action/migrateVms" /> PAGE 215Chapter 7 Managing and Monitoring a Cloud 3 Retrieve the resource pool list from the Provider vDC. The VMWProviderVdcResourcePoolSet contains references to the Provider vDC's existing resource pools and the vCenter server that hosts them. 4 Update the resource pool set. To add resource pools: a Choose another resource pool from the same vCenter server. b Create an UpdateResourcePoolSetParams element that contains an AddItem element for each resource pool to add.
vCloud API Programming Guide Request: POST https://vcloud.example.com/api/admin/extension/providervdc/35/action/updateResourcePools Content-Type: application/vnd.vmware.admin.resourcePoolSetUpdateParams+xml ... PAGE 217Chapter 7 Managing and Monitoring a Cloud 3 Create an UpdateProviderVdcStorageProfiles request body that specifies the details of the update. To add a storage profile: a Choose another storage profile from the vCenter server referenced in the vmext:VimServer element you located in Step 2. b Create an UpdateProviderVdcStorageProfiles element that contains an AddStorageProfile element for each storage profile to add.
vCloud API Programming Guide Merge Provider vDCs You can merge one or more Provider vDCs with an existing Provider vDC. The merged Provider vDC contains the union of all resources from the contributing Provider vDCs In earlier releases of vCloud Director, a Provider vDC could be backed by no more than one resource pool. This release removes that limitation, and allows you to merge existing Provider vDCs to create a single Provider vDC that is backed by multiple resource pools.
Chapter 7 Managing and Monitoring a Cloud type="application/vnd.vmware.admin.vmwprovidervdc+xml" name="PvDC-VC005" href="https://vcloud.example.com/api/admin/extension/providervdc/45" /> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Create an External Network An external network is a reference to a portgroup on a vCenter server attached to vCloud Director.
vCloud API Programming Guide The server creates the external network and returns a VMWExternalNetwork element that includes the contents you POSTed, along with a set of Link elements that you can use to access, remove, disable, or modify it. A reference to the new external network is added to the VMWExternalNetworkReferences element of the VCloud. The portgroup you specified is removed from the VimObjectRefList of the vCenter server.
Chapter 7 Managing and Monitoring a Cloud PAGE 222vCloud API Programming Guide Create a Network Pool Network pools referenced by organization vDCs provide support for isolated and routed vApp networks and organization vDC networks. To create a network pool, a system administrator must specify backing network resources on a vCenter server registered to the cloud. A network pool object represents a collection of vSphere network resources that are contained by a Provider vDC and available to be associated with organization vDCs backed by that Provider vDC.
Chapter 7 Managing and Monitoring a Cloud 2 Examine the response to locate the Link element that contains the URL for adding network pools to your cloud. This element has a rel attribute value of add and a type attribute value of application/vnd.vmware.admin.networkPool+xml, as shown here: PAGE 224
vCloud API Programming Guide Request: POST https://vcloud.example.com/api/admin/extension/networkPools Content-Type: application/vnd.vmware.admin.networkPool+xml ... PAGE 225Chapter 7 Managing and Monitoring a Cloud operation="Creating Network Pool 67" ... ...
Create an Isolation-Backed Network Pool To create an isolation-backed network pool, create a VMWNetworkPool element whose type attribute has the value FencePoolType, and POST the element to your cloud's add link for networkPools. An isolation-backed network pool is backed by one or more vCenter isolated networks, and provides traffic isolation from other hosts.
vCloud API Programming Guide name="example-isolation-pool" type="application/vnd.vmware.admin.networkPool+xml"> Example Isolation-backed network pool 5 0 PAGE 227Chapter 7 Managing and Monitoring a Cloud Create a Portgroup-Backed Network Pool To create a portgroup-backed network pool, you create a VMWNetworkPool element whose type attribute has the value PortGroupPoolType, and POST the element to your cloud's add link for networkPools. Prerequisites n Verify that you are logged in to the vCloud API as a system administrator. n Verify that you know your cloud's add URL for networkPools. See “Create a Network Pool,” on page 222.
vCloud API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.admin.networkPool+xml ... PAGE 229Chapter 7 Managing and Monitoring a Cloud Procedure 1 Choose whether to import the virtual machine as a vApp or vApp template. The VimServer element that represents the vCenter server from which you import the virtual machine contains two links that import virtual machines. One has the following form, and imports the virtual machine as a vApp. PAGE 230vCloud API Programming Guide vm-43 Response: 201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... ... ...
Chapter 7 Managing and Monitoring a Cloud Request: POST https://vcloud.example.com/api/admin/extension/vimServer/9/importVmAsVappTemplate Content-type: application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml ... vm-43 PAGE 232vCloud API Programming Guide When a virtual machine is deployed in a vDC that supports fast provisioning, its disks can become part of a tree structure that includes parent and child disks. Disk tree structure and total storage consumption remain the same regardless of the order in which virtual machines are relocated The folder structure in the target datastore might change depending on the order in which virtual machines are relocated.
Chapter 7 Managing and Monitoring a Cloud datastore-191 DATASTORE ... ... 4 Construct a RelocateParams element that specifies the destination datastore for the Vm. See “Example: Relocate a Virtual Machine,” on page 233.
vCloud API Programming Guide type="application/vnd.vmware.admin.keystoreUpdateParams+xml" href="https://vcloud.example.com/api/admin/org/26/settings/ldap/action/updateLdapKeyStore" /> PAGE 235
Chapter 7 Managing and Monitoring a Cloud Table 7-3. Truststore, Certificate, and Keytab Upload Limits Upload Type Maximum Size in Megabytes vCenter truststore 10 LDAP certificate 2 LDAP keystore 2 LDAP SSPI keytab 2 AMQP certificate 2 AMQP truststore 10 Prerequisites Verify that you are logged in to the vCloud API as a system administrator. Procedure 1 Create the request body that the request requires. For details on these request bodies, see the schema reference.
vCloud API Programming Guide To upload the certificate, make a PUT request to the uploadLocation URL and supply the certificate in the request body. Request: PUT https://vcloud.example.com/transfer/53bc1/ldapCertificate Content-length: 2048 ...serialized contents of certificate...
Chapter 7 Managing and Monitoring a Cloud Prerequisites Verify that you are logged in to the vCloud API as a system administrator. Verify that the vSphere Web Client URL is enabled for all vCenter servers from which you want to retrieve the vSphere URL of an object. You can manage this feature on the General tab of the vSphere Properties page of the vCloud Director Web console.
vCloud API Programming Guide Table 7-4.
Working With Object Metadata 8 The vCloud API provides a general-purpose facility for associating user-defined metadata with an object. A system administrator or the owner of an object can use the metadata link in the object's representation to access object metadata. The representations of most first-class objects in the vCloud API include a link to a Metadata element, which contains up to 1024 name=value pairs that the owner of an object can create, retrieve, update, and delete.
vCloud API Programming Guide Foo ... See “Access Control for vCloud API Object Metadata,” on page 240 for more information about the Domain element. The type of a Value is expressed in the xsi:type attribute of the containing TypedValue element. Values have various restrictions, based on their type. Table 8-1. Metadata TypedValue Types Type Name Restrictions on Value Size of Value MetadataStringValue UTF-8 character set.
Chapter 8 Working With Object Metadata vCloud API Object Metadata Limits The following limits apply to vCloud API object metadata: Metadata key size The contents of a Key element in a MetadataEntry cannot exceed 256 UTF-8 characters. Metadata size The size of all Metadata for an object, computed as the sum of all Key and TypedValue UTF-8 strings in all MetadataEntry elements in the GENERAL domain, cannot exceed 128 KB. An additional 16KB of MetadataEntry content can be created in the SYSTEM domain.
vCloud API Programming Guide 2 Retrieve the Metadata element. If the object has no metadata, the element contains only a rel="edit" link that you can use when modifying the element and a rel="up" link that references the containing object, as shown in this example. PAGE 243Chapter 8 Working With Object Metadata visibility="PRIVATE">SYSTEM LOS bronze
The response is a Task. Response: ...
vCloud API Programming Guide http://internal.example.com/orgs/Finance PAGE 245Chapter 8 Working With Object Metadata 2 Retrieve or update the value. Make a request to the URL in the value of the href attribute of the MetadataEntry that contains the Key. n To retrieve the value, make a GET request to URL in the value of the href attribute of the MetadataEntry. The response is a MetadataValue element. n To update the value, make a PUT request to the URL in the edit link described in Step 1, and supply a MetadataValue element as the request body. See .
vCloud API Programming Guide 246 VMware, Inc.
Using the Query Service 9 You can use the vCloud API query service to query the vCloud Director database for information about objects in the cloud. The query service provides the following kinds of queries: n Typed queries, which require you to construct a query URL that specifies a query type and optional parameters. n Packaged queries, which have well-known URLs and can accept many of the same parameters used with typed queries.
vCloud API Programming Guide Typed Queries Typed queries require you to construct a request URL that specifies an object type and optional parameters. Use this URL with a GET request to return query results. Query Syntax Typed queries have the following syntax: API-URL/query?type=name[¶m][¶m ... ][&filter] n API-URL is a URL of the form https://vcloud.example.com/api. n name is the name of a query type. Type names are case-sensitive. n param is an optional query parameter.
Chapter 9 Using the Query Service ...
vCloud API Programming Guide numStoredVMs="0" numDeployedVMs="0" name="administrator" ldapUser="false" fullName="The Admin" enabled="true" deployedVMQuotaRank="-1" deployedVMQuota="0" href="https://vcloud.example.com/api/admin/user/24" /> PAGE 251Chapter 9 Using the Query Service type="application/vnd.vmware.admin.user+xml" name="zorro" href="https://vcloud.example.com/api/admin/user/58" /> Example: Query With Parameters This query retrieves a list of all users in your organization and returns a response in the records format. The query includes a sortAsc=name parameter, so the result set is sorted by object name. GET https://vcloud.example.
vCloud API Programming Guide href="https://vcloud.example.com/api/query? type=adminUser&page=1&pageSize=25&format=references&filter=ldapUser==true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... > PAGE 253Chapter 9 Using the Query Service Each query type returns its result set as an XML document in which objects are represented as elements and object properties are represented as attributes, pairing the name of the property with its value at the time the request was made. By default, result sets are returned in the records format, which shows all database records for each object.
vCloud API Programming Guide type="application/vnd.vmware.vcloud.query.records+xml" href="https://vcloud.example.com/api/catalogs/query?page=1&pageSize=25&format=records" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... > PAGE 255
Chapter 9 Using the Query Service numberOfTemplates="8" numberOfMedia="1" name="catalog1" isShared="true" isPublished="true" description="" createdOn="2011-03-22T16:14:06.360-07:00" href="https://vcloud.example.com/api/catalog/91" /> Packaged query using references format. GET https://vcloud.example.com/api/catalogs/query?format=references Response: PAGE 256vCloud API Programming Guide Packaged query with sorting and filtering. This query adds parameters and a filter expression to produce a list of catalogs that contain one or more vApp templates. The query sorts the result set in ascending order by number of vApp templates: GET https://vcloud.example.com/api/catalogs/query? format=records&sortAsc=numberOfTemplates&filter=numberOfTemplates!=0 Response: PAGE 257Chapter 9 Using the Query Service description="" createdOn="2011-03-21T14:28:09.273-07:00" href="https://vcloud.example.com/api/catalog/150" />
Query Parameters Query parameters specify result set properties such as pagination, sort order, and filter criteria. Query Parameters Typed queries must include a type parameter, which specifies the type of query to run. Packaged queries cannot specify a type parameter. All other parameters are optional.
vCloud API Programming Guide Table 9-3. Query Filter Expressions Operator Example Operation == attribute==value Matches. The example evaluates to true if attribute has a value that matches value in a case-sensitive comparison. NOTE Asterisk (*) characters that appear anywhere in value are treated as wildcards that match any character string. When value includes wildcards, the comparison with attribute becomes case-insensitive. != attribute!=value Does not match.
Chapter 9 Using the Query Service For queries that examine object metadata, you can filter query results using numeric comparison operations when a metadata value has type NUMBER or DATETIME. Because object metadata types are dynamic, filter expressions for metadata queries require additional parameters that define the attribute part of the expression as metadata, and specify the type of the value part of the expression. Table 9-5.
vCloud API Programming Guide Attribute Names and Values Several parameters and all filter expressions require you to specify an attribute name. Use the schema reference to find the attribute names included in a particular result set. For most queries, the name of the element that holds a result is derived form the name and format of the query. For example, the result of an adminGroup query in records format is an AdminGroupRecord element.
Chapter 9 Using the Query Service storedVMQuota="0" numberOfVdcs="5" ... href="https://vcloud.example.com/api/org/70" numberOfRunningVMs="3"> SYSTEM expiry 2012-05-01T00:00:00.
vCloud API Programming Guide Request: GET https://vcloud.example.com/api/query? type=organization&format=records&fields=metadata:rank,metadata@SYSTEM:expiry" &filter="metadata@SYSTEM:expiry=lt=DATETIME:2012-05-01T00:00:00.000-04:00 Response: PAGE 263Configuring and Using Blocking Tasks and Notifications 10 vCloud Director allows a system administrator to configure many operations as blocking tasks, which are suspended until a system administrator acts on them or a preconfigured timer expires. Blocking tasks also generate AMQP messages that you can use to automate the handling of the underlying user request. A system administrator can also enable nonblocking AMQP notifications of all system events.
vCloud API Programming Guide Processing Messages from Blocking Tasks Messages from blocking tasks are also sent to the configured message broker, and clients can use the routing key to indicate their interest in these messages. See “Subscribing to Notifications,” on page 263. Messages from blocking tasks contain additional information about the task itself. Clients that process these messages can use the vCloud API to authenticate to the system and act on the blocked task.
Chapter 10 Configuring and Using Blocking Tasks and Notifications 3 Enable or disable notifications. a Retrieve the NotificationsSettings element. Make a GET request to the href value of the application/vnd.vmware.admin.notificationsSettings +xml link. b Modify the value of the EnableNotifications element to enable or disable notifications. c Update the modified element with the new contents. PUT the modified element to the href value of its rel="edit" link. 4 Review or modify system AMQP settings.
vCloud API Programming Guide type="application/vnd.vmware.admin.amqpSettings+xml" href="https://vcloud.example.com/api/admin/extension/settings/amqp" ... > 5672 guest amq.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Request: POST https://vcloud.example.com/api/admin/extension/settings/amqp/action/test Content-Type: application/vnd.vmware.admin.amqpSettings+xml ... PAGE 268vCloud API Programming Guide Routing key components include: operationSuccess A Boolean value denoting whether the operation that triggered the notification succeeded or failed. entity The object identifier of the object on which an operation, an event of type com/vmware/vcloud/event/, triggered the notification. For more information about object identifiers, see “Objects, References, and Representations,” on page 12. org The object identifier of the organization that owns the affected object.
Chapter 10 Configuring and Using Blocking Tasks and Notifications name="vdcComposeVapp" id="urn:vcloud:blockingTask:25" /> 2011-06-18T14:33:2
vCloud API Programming Guide Table 10-2. User, Group, Role, and Session Events (Continued) Type (com/vmware/vcloud/event/) Description user/delete A local user was removed from the organization. group/import A group was imported from LDAP. group/remove A group was removed from an organization. role/create A new role was created. role/modify An existing role was modified. role/delete A role was deleted. Table 10-3.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10-4. vApp, vApp Template, Vm, and Media Events (Continued) Type (com/vmware/vcloud/event/) Description vappTemplate/create_request A request to create a vApp template was blocked pending administrative action. vappTemplate/import_request A request to import a vApp template was blocked pending administrative action. vappTemplate/modify_request A request to modify a vApp template was blocked pending administrative action.
vCloud API Programming Guide Table 10-4. vApp, vApp Template, Vm, and Media Events (Continued) Type (com/vmware/vcloud/event/) Description vm/consolidate_request A request to consolidate a virtual machine was blocked pending administrative action. vm/consolidate A virtual machine was consolidated. vm/relocate_request A request to relocate a virtual machine was blocked pending administrative action. vm/relocate A virtual machine was relocated.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10-5. Other System Events (Continued) Type (com/vmware/vcloud/event/) Description blockingtask/fail A blocking task was failed. datastore/modify One or more properties of a datastore object were modified. datastore/delete A datastore object was deleted. Retrieve or Update Blocking Task Settings Timeout settings, default actions, and related messages for blocking tasks are properties of a cloud.
vCloud API Programming Guide Request: PUT https://vcloud.example.com/api/admin/extension/settings/blockingTask Content-Type: application/vnd.vmware.admin.blockingTaskSettings+xml ... PAGE 275Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10-6. Media Operation Name Description vdcCopyMedia Copy a media object. vdcDeleteMedia Delete a media object. vdcUploadMedia Upload media. vdcUpdateMedia Modify one or more properties of a media object. Table 10-7. Network Operation Name Description networkCreateNetworkPool Create a network pool. networkCreateExternalNetwork Create an external network. networkDelete Delete a network.
vCloud API Programming Guide Table 10-9. vApp Template Operation Name Description vdcCopyTemplate Copy a vApp template. vdcDeleteTemplate Delete a vApp template. vdcEnableDownload Enable a vApp template for download as OVF. vdcUpdateTemplate Modify one or more properties of a vApp template. vdcUploadOvfContents Upload an OVF package to create a vApp template. Table 10-10. vDC Operation Name Description rclCreateProviderVdc Create a provider vDC. rclDeleteProviderVdc Delete a provider vDC.
Chapter 10 Configuring and Using Blocking Tasks and Notifications 3 Use one of the action links in the BlockingTask to take action on the task. See the response portion of “Example: Handling a Blocking Task,” on page 278. Example: Retrieve a List of Blocking Tasks Request: GET https://vcloud.example.com/api/admin/extension/blockingTasks/ Response: 200 OK Content-Type: application/vnd.vmware.admin.blockingTaskList+xml ... PAGE 278vCloud API Programming Guide fail End the task, setting the status of any transient objects that it created to ERROR. Task status is set to ERROR. updateProgress Reset the timeout value and timeout action for an active task. Use this action to keep the task alive when it might become subject to a timeout action. Prerequisites Verify that you are logged in to the vCloud API as a system administrator. Procedure 1 Retrieve the list of active blocking tasks. See “Monitor Blocking Tasks,” on page 276.
Chapter 10 Configuring and Using Blocking Tasks and Notifications rel="resume" type="application/vnd.vmware.admin.blockingTaskOperationParams+xml" href="https://vcloud.example.com/api/admin/extension/blockingTask/25/action/resume" /> PAGE 280vCloud API Programming Guide Procedure 1 Retrieve the list of active blocking tasks. See “Monitor Blocking Tasks,” on page 276. If you are using an AMQP client to handle task extension requests, skip this step. Each blocking task creates its own AMQP message, which contains a reference to the BlockingTask mentioned in Step 1. 2 Retrieve an individual BlockingTask. See the request portion of “Example: Handling a Blocking Task,” on page 278. 3 Provide a new timeout value, relative to now, for the task.
vCloud Director Extension Services 11 vCloud Director and the vCloud API include a framework for integration of extension services that a vCloud API client can access as though they were native services. In addition to service-specific objects or operations they provide, extension services can implement new operations for existing API objects. A vCloud Director extension service is a program that presents a REST interface to vCloud API clients.
vCloud API Programming Guide Service APIs An extension service can define its own request and response body elements if it needs to. API schema files can be specified as part of service registration or can be added later. Schema files can reside at any location that is reachable by the extension service.
Chapter 11 vCloud Director Extension Services Table 11-1. Summary of vCloud API Extensibility Requests Operation Request Request Body Response Register an extension service with vCloud Director POST APIURL/admin/extension/serv ice Service Service Retrieve a list of registered extension services. GET APIURL/admin/extension/serv ice None ExtensionServices Update a registered extension service. PUT APIURL/admin/extension/serv ice/id Service Service Delete a registered extension service.
vCloud API Programming Guide Table 11-1. Summary of vCloud API Extensibility Requests (Continued) Operation Request Request Body Response Create API definitions for a registered extension service. POST APIURL/admin/extension/serv ice/id/definitions ApiDefinition ApiDefinition Create file descriptors for a registered extension service.
Chapter 11 vCloud Director Extension Services 2 Examine the response to find the Link for adding extension services. This URL is present in the VMWExtension element, and has the following form. 3 Construct a Service element. See the request portion of “Example: Register an Extension Service,” on page 285.
vCloud API Programming Guide application/vnd.example.vcd-backup.backupList+xml down application/vnd.example.vcd-backup.vApp+xml {baseUri}vApp/vapp-{resourceId}/action/backup application/vnd.example.vcd-backup.createBackupParams +xml backup application/vnd.example.
Chapter 11 vCloud Director Extension Services type="application/vnd.vmware.vcloud.query.records+xml" href="https://vcloud.example.com/api/admin/extension/service/45/apifilters" /> PAGE 288vCloud API Programming Guide Adding or Removing Service Links A service can add its own Link elements to the representations of vCloud API objects. You can create these service links when you register a service. You can also add or remove the links after you register the service. You can create multiple service links as part of registering a service. After you register a service, you can add or remove individual links.
Chapter 11 vCloud Director Extension Services 2 Examine the response to find the Link for adding service links. This Link has the following form: 3 Create a ServiceLink element that specifies the properties of the new link. 4 POST the ServiceLink element to the URL described in Step 2 See “Example: Add a Service Link,” on page 289.
vCloud API Programming Guide Procedure 1 Retrieve the XML representation of the service. This request retrieves the XML representation of the service created in “Example: Register an Extension Service,” on page 285: GET https://vcloud.example.com/api/admin/extension/service/45 2 Examine the response to find the Link for listing service links. This Link has the following form: PAGE 291Chapter 11 vCloud Director Extension Services mimeType="application/vnd.vmware.vcloud.createBackupParams+xml" linkHref="{baseUri}vApp/vapp-{resourceId}/action/backup" href="https://vcloud.example.com/api/admin/extension/service/link/f62e..." /> NOTE Link id values are truncated in this example. Using this information, find the ServiceLinkRecord that represents the service link you want to delete, and make a DELETE request to that URL. DELETE https://vcloud.example.
vCloud API Programming Guide Prerequisites Verify that you are logged in to the vCloud API as a system administrator. Procedure 1 Retrieve the XML representation of the organization in which you want to create the Task. Use a request like this one: GET https://vcloud.example.com/api/admin/org/26 2 Examine the response to locate the Link element that contains the URL for adding tasks to the organization's tasks list.
Chapter 11 vCloud Director Extension Services operationName="jobCustom" operation="External processing" > ... Create a Service-Specific Event An extension service can request that vCloud Director add an event message to the event stream of an organization. The system always creates an event message when a service posts a Task to an organization's tasks list. To create additional event messages, a service can POST an Event element to an organization's events URL.
vCloud API Programming Guide Authorization Framework for Extension Service Operations All requests to extension services must be authenticated through the vCloud API. Extension services can participate in vCloud API REST authorization by controlling access to their objects and operations through new or existing rights and roles. An extension service that does not enable the use of vCloud Director REST authorization implicitly grants permission for all users to perform all operations that the service uses.
Chapter 11 vCloud Director Extension Services Create an Extension Service Resource Class To configure your extension service to provide access control for the objects it creates, define a resource class for each of its object types. A ResourceClass element contains the information needed to construct a URL that a client can use to access the resource in a specific context. It must contain the following child elements: MimeType The MIME content type of all instances of the resource class.
vCloud API Programming Guide as shown in the response. Request: POST https://vcloud.example.com/api/admin/extension/service/45/resourceclasses Content-type:application/vnd.vmware.admin.resourceClass+xml application/vnd.vmware.vcloud.
Chapter 11 vCloud Director Extension Services Define an Action for a Resource Class After you define a resource class, you can specify the actions that are permitted on resources of that class. A ResourceClassAction object defines an HTTP method that is allowed on a specific UrlPattern. Prerequisites Verify that you are logged in to the vCloud API as a system administrator. Procedure 1 Retrieve the XML representation of the service. Use a request like this one: GET https://vcloud.example.
vCloud API Programming Guide xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" name="Read backups" id="urn:vcloud:resourceClassAction:268" type="application/vnd.vmware.admin.resourceClassAction+xml" href="https://vcloud.example.com/api/admin/extension/service/resourceclassaction/268" ... > PAGE 299Chapter 11 vCloud Director Extension Services Table 11-2. ACL Rules (Continued) Container Element PrincipalAccess Access Comments Entity The action is authorized for members of the organization referenced in the Entity element in this container. Shared The action is authorized for all users Entity The action is authorized for the User referenced in the Entity element in this container, or for any role that includes the Right referenced in the Entity element in this container.
vCloud API Programming Guide Shared Entity Entity PAGE 301Chapter 11 vCloud Director Extension Services 2 Examine the response to find the Link for adding or listing service-specific rights This Link has the following form: 3 Construct a Right element. For information about the contents of this element, see the request portion of “Example: Create a ServiceSpecific Right,” on page 301.
vCloud API Programming Guide Localization Framework for Extension Services Extension service developers can provide localized service-specific messages by creating and uploading a localization bundle. An extension service localization bundle is a file in zip format that contains one or more properties files. Each properties file consists of an arbitrary number of key=value pairs, where the key is the name of a service-specific task operation or event, and the value is the localized message.
Chapter 11 vCloud Director Extension Services 3 Construct an ApiFilter element. This ApiFilter overwrites any existing ApiFilter defined by the service. See the request portion of “Example: Create an API Filter for an Extension Service,” on page 303 for information about the contents of this element. 4 POST the ApiFilter element to the URL described in Step 2.
vCloud API Programming Guide Procedure 1 Retrieve the XML representation of the service. Use a request like this one: GET https://vcloud.example.com/api/admin/extension/service/45 2 Examine the response to find the Link for adding API definitions. This Link has the following form: 3 Construct an ApiDefinition element.
Chapter 11 vCloud Director Extension Services href="http://example.com/vcdBackup/schema/v5.1/devices.xsd" /> Response: 201 Created Content-type:application/vnd.vmware.admin.apiDefinition+xml ... ... VMware, Inc.
vCloud API Programming Guide 306 VMware, Inc.
XML Representations in the vCloud API 12 The vCloud API represents objects in a cloud as XML documents in which object properties are contained in elements and attributes that have typed values and an explicit object hierarchy defined by an XML schema. Schema reference information is available as a download.
vCloud API Programming Guide Table 12-1.
Chapter 12 XML Representations in the vCloud API A client might encounter a VCloudExtension element in any response. If the element declares required=”true” and the client does not know how to interpret the contents of the element, the client can ignore it, but it must include the VCloudExtension in any request to modify the element that contains it.
vCloud API Programming Guide The examples omit XML namespace identifiers from most responses. The following fragment shows how some of them appear in a typical response body. ...> ...
Chapter 12 XML Representations in the vCloud API Object Identifier, Type, and Reference These attributes are common to all object representations. id The object identifier, expressed in URN format. The value of the id attribute uniquely identifies the object, persists for the life of the object, and is never reused. The id attribute value is intended to provide a context-free identifier that can be used with the vCloud API entityResolver (see “Retrieve an Object as an Entity,” on page 312).
vCloud API Programming Guide Retrieve an Object as an Entity You can use the vCloud API entity resolver with an object's id attribute value to retrieve a context-free reference to the object. Every first-class object that the vCloud API defines includes an id attribute whose value is the object identifier expressed in URN format. The value of the id attribute uniquely identifies the object, persists for the life of the object, and is never reused.
Chapter 12 XML Representations in the vCloud API VMware, Inc.
vCloud API Programming Guide 314 VMware, Inc.
Index A administrative tasks, about 129 administrator, system 132 AMQP about 263 certificate and truststore 233 AMQP settings to configure 264 to test 266 API client, to develop 21 attributes custom 105 name 310 status 310 B blocking task, to configure 263 blocking task requests, to monitor 276 blocking task settings, to configure 273 browsing 41 C catalog adding items 73 change owner 79 controlling access to 191 removing items 75 to administer 176 to change owner 129 to create 129, 176 to delete 129 to
vCloud API Programming Guide H N host to enable or disable 193 to update or repair 193 NAT service in Edge Gateway 160 in vApp network 112 network list IP addresses allocated to 41 to create, update, or remove 129 to reset 129 to retrieve 41 network pool and organization vDC network 148 isolation-backed 225 list of 204 portgroup-backed 227 to create 222 to retrieve or update 193 VLAN-backed 223 VxlanPoolType 209, 222, 225 network services in Edge Gateway 156 in vApp network 112 list of 148 networks abou
Index organizations federation of 136 to list 41, 48 OVF descriptor, to download 68 OVF environment 120 OVF package manifest file 59, 63 to upload or download 55 uploading 57 OVF specification 81 OVF upload initiating 59 to monitor progress of 64 using ranged PUTs 65 P ProductSection element, to retrieve or update 83 Provider vDC resource pool set 213 to add or remove storage profiles 216 to create 209 to merge 193, 218 to retrieve or update 193 Q queries packaged 252 typed 248 query service about 247 an
vCloud API Programming Guide V vApp add virtual machines 90 capturing 72 changing owner 79 composing 87 configuration links in 99 controlling access to 191 datacenter operations 81 importing 72 importing from vCenter 228 list of power operations 83 maintenance mode 97 recompose 90 remove virtual machines 90 to change name or description 83 to change owner 129 to compose or recompose 83 to configure 97 to delete 38 to deploy or undeploy 83 to enter or exit maintenance mode 193 to import from vCenter as temp
Index to view or modify network connection 103 to view or modify operating system properties 103 to view or modify virtual disks 103 Vm configuration links in 101 list of power operations 83 pending question 83 to reboot or reset 83 to retrieve 41 vmdk file, to download from template 68 VMware Tools to install 83 to retrieve installed version 83 vSphere operations 52 retrieve object URL 236 vSphere client, to generate URL for use by 193 vSphere object, retrieve URL to access directly 193 vSphere object map
vCloud API Programming Guide 320 VMware, Inc.
