vCloud API Programming Guide vCloud Director 5.5 This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.
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–2013 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 17 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 Deploy the vApp 31 Get Information Abo
vCloud API Programming Guide 5 Deploying and Operating vApps 89 Summary of vCloud API vApp and Virtual Machine Operations Requests 91 Create a vApp From a Template 93 Create a vApp From an OVF Package 97 Compose a vApp From Existing Virtual Machines 101 Recompose a vApp to Add or Remove Virtual Machines 103 Clone a vApp 106 Capture a vApp as a Template 108 Update vApp Access Controls 110 Provide User Input Requested by a Virtual Machine 111 Attach or Detach an Independent Disk 112 Creating and Using vApp
Contents 10 Configuring and Using Blocking Tasks and Notifications 307 Configure Notifications and AMQP Settings 308 Retrieve or Update Blocking Task Settings 318 Monitor Blocking Tasks 324 Take Action on a Blocking Task 325 Extend The Timeout Expiration of an Active Task 327 11 vCloud Director Extension Services 329 Summary of vCloud API Extension Services Framework Requests 330 Register an Extension Service 332 Adding or Removing Service Links 336 Service-Specific Tasks and Events 339 Authorization Fra
vCloud API Programming Guide 6 VMware, Inc.
vCloud API Programming Guide This edition of the vCloud API Programming Guide provides information about version 5.5 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 n as a local repository for content published by another cloud or any Web site that hosts a VMware Content Subscription Protocol (VCSP) endpoint. An organization administrator or catalog owner controls catalog sharing. Organization administrators in organizations that have permission to publish catalogs control publication and subscription options for catalogs in their organization.
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) 14 rel Attribute Value Action or Relationship Description Implied HTTP Verb down References an object contained by this object. GET 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.
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 fail Fail this blocking task. POST firstPage Reference to the first page of a paginated response. GET 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.
vCloud API Programming Guide Table 1‑1. Link Relationships and HTTP Request Types (Continued) 16 rel Attribute Value Action or Relationship Description Implied HTTP Verb repair Repair this host or network. POST resourcePoolVmList List the virtual machines using this resource pool. GET resume Resume this blocking task. POST rights List the service-specific rights created by this extension service. GET rights:cleanup Remove service-specific rights no longer used by any extension service.
Chapter 1 About the VMware vCloud API Client Workflow Overview vCloud API clients implement a RESTful workflow, making HTTP requests to the server and retrieving the information they need from the server’s responses. About RESTful Workflows REST, an acronym for Representational State Transfer, describes an architectural style characteristic of programs that use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects between a client and a server.
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 Valid values for the HTTP Accept header in this release are: version=5.5 The request is from a vCloud API version 5.5 client. version=5.1 The request is from a vCloud API version 5.1 client. version=1.5 The request is from a vCloud API version 1.5 client. In general, client requests can access objects defined by any version of the vCloud API that is less than or equal to the version specified in the Accept header.
vCloud API Programming Guide n If multiple namespaces are represented in the request, XML namespace attributes must include an identifying prefix, and that prefix must be used with all elements from that namespace. n All required elements must appear in request bodies. All elements that appear in request bodies must appear in the order that the schema establishes, and with content that conforms to the type constraint that the schema specifies.
Chapter 1 About the VMware vCloud API Table 1‑3. HTTP Status Codes that the vCloud API Returns (Continued) Status Code Status Description 406 Not Acceptable The resource identified by the request is not capable of generating a response of the type specified in the request's Accept header. 409 Conflict The object state is not compatible with the requested operation.
vCloud API Programming Guide About the Schema Reference The vCloud API Schema Reference includes reference material for all elements, types, queries, and operations in the vCloud API. It also includes the schema definition files. The schema reference is available in HTML format in the vCloud Director documentation center. About the vCloud API Examples The vCloud API Programming Guide includes many examples of HTTP requests and responses.
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 Undeploy, Power Off, and Delete the vApp on page 38 After you undeploy a vApp and power it off, you can use an HTTP DELETE request to delete the vApp object.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow Integrated 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.
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 name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"> ... ... PAGE 32vCloud API Programming Guide 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. 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 name="Linux FTP server" deploy="true" powerOn="true" 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 status="running" operation="Creating Virtual Application Linux FTP server(7)" ... > Get Information About a vApp When you instantiate a vApp template, the server returns the URL of the resulting vApp.
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 n Verify that your browser has an installed copy of the vmware-vmrc plug-in. This plug-in is installed by your browser whenever you use the vCloud Director Web Console to access the console of a running virtual machine. After this plug-in is installed, you can find it in the folder where your browser stores plug-ins. Procedure 1 Retrieve the screen ticket. POST a request to the acquireTicket link of the Vm. Request: POST https://vcloud.example.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow 2 Undeploy the vApp, and specify that it should also be powered off. Make a POST request to the vApp action/undeploy link, which has the following form: In the request body, specify that the undeployment include powering off the vApp. See “Example: Undeploy, Power Off, and Delete a vApp,” on page 39. 3 Retrieve the XML representation of the vApp again.
vCloud API Programming Guide Request: DELETE https://vcloud.example.com/api/vApp/vapp-7 Response: 202 Accepted ... 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.
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 ... ... 5.5 https://vcloud.example.com/api/sessions ... ... NOTE You can use the URL in the SchemaLocation element with a GET request to retreive the file in which that complex type is defined. For example: GET http://vcloud.example.
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 name="System" href="https://vcloud.example.com/api/org/99" /> PAGE 47
Chapter 3 Exploring a Cloud Prerequisites NOTE This procedure assumes that you are logging in with credentials managed by a SAML identity provider. Users whose credentials are managed by the vCloud Director integrated identity provider must follow a different login workflow. n Verify that you know the login URL.
vCloud API Programming Guide 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. See “Retrieve or Update System Settings,” on page 239. A Session object can be deleted by its owner or an administrator.
Chapter 3 Exploring a Cloud rel="entityResolver" type="application/vnd.vmware.vcloud.entity+xml" href="https://vcloud.example.com/api/entity/" /> Because this user has limited rights, the response includes only a few link types: org A link to the user's organization. See “Retrieve a List of Organizations Accessible to You,” on page 49. queryList A link to the set of typed queries you can run. See Chapter 9, “Using the Query Service,” on page 289. entity A link to the entity resolver.
vCloud API Programming Guide The request returns an OrgList element similar to the one shown here. Additional Org elements are returned only when a system administrator makes the request. Response: 200 OK Content-Type: application/vnd.vmware.vcloud.orgList+xml ... PAGE 51Chapter 3 Exploring a Cloud 3 Retrieve the VCloud element by making a GET request to the href value of the Link described in Step 2. See “Example: Retrieve an Administrative View of a Cloud,” on page 51 Example: Retrieve an Administrative View of a Cloud Request: GET https://vcloud.example.com/api/admin Response: 200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml ... PAGE 52vCloud API Programming Guide type="application/vnd.vmware.admin.right+xml name="vApp_Deploy" href="https://vcloud.example.com/api/admin/right/3" /> ... PAGE 53Chapter 3 Exploring a Cloud 2 Examine the contents of the Session element to locate the link to the VMWExtension object. This link has the following form: 3 Retrieve the list of organizations by making a GET request to the href value of the Link described in Step 2.
vCloud API Programming Guide rel="down" type="application/vnd.vmware.admin.extensionServices+xml" href="https://vcloud.example.com/api/admin/extension/service" /> 54 VMware, Inc.
Provisioning an Organization 4 The vCloud API provides several ways for you to make vApp templates, vApps, media images, and independent disks available to users in a vCloud Director organization. The vCloud API allows you to upload and download OVF packages and ISO-format media images.
vCloud API Programming Guide n “Capturing and Importing vApps,” on page 75 n “Managing Catalog Items,” on page 76 n “Creating and Using Independent Disks,” on page 80 n “View or Change the Owner of an Object,” on page 83 n “Controlling Access to vApps and Catalogs,” on page 84 Summary of vCloud API Provisioning Requests Provisioning requests add vApp templates and media to a a catalog. You can also use provisioning requests to copy, move, rename, download, and delete these objects.
Chapter 4 Provisioning an Organization Table 4‑1. Summary of Provisioning Requests (Continued) Operation Request Request Body Response Move a catalog item. [NEW] POST APIURL/catalogItem/id/ action/move CopyOrMoveCatalogItemP arams Task Copy a catalog item. [NEW] POST APIURL/catalogItem/id/ action/copy CopyOrMoveCatalogItemP arams Task Synchronize a catalog with its remote source. [NEW] POST API-URL/catalog/id/ action/sync None Task Synchronize a catalog item with its remote source.
vCloud API Programming Guide Table 4‑1. Summary of Provisioning Requests (Continued) Operation Request Request Body Response Retrieve properties of an independent disk. GET API-URL/disk/id None Disk Update an independent disk in a VDC. POST API-URL/disk/id Disk Disk Retrieve a list of all virtual machines attached to an independent disk. GET APIURL/disk/id/attachedVms None Vms Delete an independent disk.
Chapter 4 Provisioning an Organization 7 If the OVF package includes a manifest file, the entire upload is validated against the contents of the manifest file. Both monolithic and ranged, or chunked, PUT requests are supported. After starting an upload, a client can make periodic requests to assess its progress. After all of the files are uploaded (and validated if a manifest is present), the server processes them and updates the vApp template.
vCloud API Programming Guide Initiating the OVF Upload To initiate the OVF upload, a client makes a POST request to an action/upload link in the target catalog. The type of this link is application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml. The request body is an UploadVAppTemplateParams element.
Chapter 4 Provisioning an Organization Example: Initiating the Upload This example assumes an OVF package that has no manifest. Request: POST https://vcloud.example.com/api/catalog/32/action/upload Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml ... PAGE 62vCloud API Programming Guide Retrieving the Upload URL for the OVF Descriptor After the vApp template and corresponding catalog item have been created, you must retrieve the template to get the upload URL for the OVF descriptor. Procedure 1 Examine the CatalogItem returned by the upload request to find the reference to the new vApp template. The reference is the value of the href attribute of the Entity element, as shown here. PAGE 63Chapter 4 Provisioning an Organization bytesTransferred="0"> ... ... ... The response body includes the following attributes: n An ovfDescriptorUploaded attribute with a value of false, indicating that the OVF descriptor file is not uploaded.
vCloud API Programming Guide 2 Verify that the request succeeded. A response of the following form indicates that the request was valid and is being processed: 200 OK Example: Uploading the OVF Descriptor Request: PUT https://vcloud.example.com/transfer/.../descriptor.ovf Content-Type text/xml ... ...
Chapter 4 Provisioning an Organization id="urn:vcloud:vapptemplate:111" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml"> ... Ubuntu vApp Template PAGE 66vCloud API Programming Guide Uploading Referenced Files You can use a PUT request to upload each file that the vApp template references. Prerequisites n Verify that you uploaded the OVF descriptor. See “Uploading the OVF Descriptor,” on page 63. n Retrieve the upload URLs for all files in the package. See “Retrieving Additional Upload URLs,” on page 64. Procedure 1 Find the upload:default URL for the file you want to upload. 2 Use the upload:default URL to construct a PUT request for the file.
Chapter 4 Provisioning an Organization 2 Compare the values of the size and the bytesTransferred attributes of each File element. When these two values are equal, the file transfer is complete. After all the files are uploaded, the response includes final values for the bytesTransferred attribute of each File, and a Task that tracks the events leading up to resolution of the template with the uploaded files, as shown in “Example: Monitoring the Progress of an Upload,” on page 67.
vCloud API Programming Guide 2 Make a PUT request that specifies a Content-Range and Content-Length and includes the serialized contents of the range. For Content-Range, specify the value of the File element's bytesTransferred attribute for the low end of the range and the value of its size attribute for the high end of the range. For Content-Length, subtract the value of the File element's bytesTransferred attribute from the value of its size attribute.
Chapter 4 Provisioning an Organization 1 Enable a vApp or vApp Template for Download on page 69 Before you can download a vApp or vApp template, an administrator or privileged user must explicitly enable the object for download. 2 Download the OVF Descriptor of a vApp or vApp Template on page 70 To download the OVF descriptor, make a GET request to the download:default URL in the downloadenabled VApp or VAppTemplate element.
vCloud API Programming Guide Response: 200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... ... ...
Chapter 4 Provisioning an Organization Download a Referenced File After you download the OVF descriptor of a vApp or vApp template, you can examine the contents of the descriptor to discover download URLs for .vmdk and other files in the package. The OVF descriptor includes an href value for each file that the descriptor references.
vCloud API Programming Guide Upload a Media Image Uploading an ISO-format media image to a catalog creates a Media object and a corresponding CatalogItem object. vCloud Director supports using the vCloud API to upload media images to a catalog. NOTE Media images in formats other than ISO can be uploaded, but are given an imageType of other in the catalog. The workflow for uploading media images is similar to the one shown in “Upload an OVF Package to Create a vApp Template,” on page 58.
Chapter 4 Provisioning an Organization Request: POST https://vcloud.example.com/api/catalog/32/action/upload Content-Type: application/vnd.vmware.vcloud.media+xml ... ISO database image Response: 201 Created Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... PAGE 74vCloud API Programming Guide ... PUT the media file contents to the upload:default link in the response. The procedure is the same as the one shown in “Uploading Referenced Files,” on page 66. The upload URL remains valid while a transfer session is in progress, and for a maximum of 60 minutes of transfer session idle time. A system administrator can change this default value.
Chapter 4 Provisioning an Organization Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... The Task in the response tracks the creation of the downloadable image. When the task completes, retrieve the Media element again. GET https://vcloud.example.com/api/media/254 The Media object now includes a download URL for the media file. ... PAGE 76vCloud API Programming Guide Managing Catalog Items Catalog items are references to vApp templates and media files. If you have the appropriate rights, you can copy, move, rename, or delete catalog items in your organization's catalogs. You cannot modify catalog items in catalogs that have an external subscription. After you add vApp templates or media files to a catalog, you might need to modify the CatalogItem objects that represent them.
Chapter 4 Provisioning an Organization 4 Examine the Catalog element to find the copy and move links it contains. These links have the following form: PAGE 78
vCloud API Programming Guide Change the Name or Description of a Catalog Item Every CatalogItem object includes a rel="edit" link that you can use to modify the name or description of the catalog item. Prerequisites n Verify that you are logged in as a user with the Catalog Author role, as an organization administrator of the organization that owns the catalog, or as a system administrator. n Verify that the target catalog does not have an external subscription.
Chapter 4 Provisioning an Organization Remove an Item from a Catalog An organization administrator or a user with adequate permissions can remove a CatalogItem by making a DELETE request to its rel="remove" link. Removing a CatalogItem also removes the referenced vApp template or media image from the catalog's storage.
vCloud API Programming Guide 3 Examine the Catalog and CatalogItem element to find the sync links that they contain. In catalogs, these links have the following form: In catalog items, these links have the following form: 4 Synchronize the catalog or catalog item. Make a POST request to the appropriate action/sync link.
Chapter 4 Provisioning an Organization The owner of a disk is initially the user who created it. To change the owner, see “View or Change the Owner of an Object,” on page 83. Procedure 1 Choose an organization VDC to contain the disk. 2 Create a DiskCreateParams element. You must specify the size (in Megabytes) and name of the independent disk. See the request portion of “Example: Create an Independent Disk,” on page 81.
vCloud API Programming Guide href="https://vcloud.example.com/api/vdc/44" /> PAGE 83
Chapter 4 Provisioning an Organization There are also two queries that you can use to return a list of virtual machines, the disks connected to them, and the VDC that contains them: vmDiskRelation Lists this information for Vm and Disk objects that you own. AdminvmDiskRelation Lists this information for all Vm and Disk objects in a cloud (system administrators only). Prerequisites Verify that you are logged in to the vCloud API as a system administrator or the object owner.
vCloud API Programming Guide 2 Modify the Owner element to specify a different User. The user must be a member of the organization that contains the object. NOTE You cannot modify the Owner of a Media or VAppTemplate object. 3 To change the owner, make a PUT request to the Owner element's rel="edit" URL and supply an Owner element in the request body. The User element in the Owner element references the new owner. See “Example: Change the Owner of a vApp,” on page 84.
Chapter 4 Provisioning an Organization Access Control for vApps An administrator or vApp owner can control access to a vApp. Each VApp element includes two types of access control links: n Links where rel="down". Use this kind of link to retrieve the access control settings for the vApp identified in the href value. n Links where rel="controlAccess".
vCloud API Programming Guide Granting Access to All Members of an Organization To specify access controls that apply to all members of an organization, an organization administrator can set IsSharedToEveryone to true and specify an access level in the EveryoneAccessLevel element. The following ControlAccessParams element grants read access to all members of the organization. PAGE 87Chapter 4 Provisioning an Organization Access Rights to vCloud Director Objects Each access level supported by vCloud Director grants one or more users a specific set of rights to an object. vCloud Director access levels are similar to roles in that they give a name to a set of rights. When you apply an access control to an object, you grant one or more users in your organization a set of rights to the object. Access rights are additive.
vCloud API Programming Guide Table 4‑2. Access Levels and the Rights They Grant (Continued) FullControl 88 vApp: Sharing X vApp: Use Console X Change ReadOnly X X 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 “Update vApp Access Controls,” on page 110 n “Provide User Input Requested by a Virtual Machine,” on page 111 n “Attach or Detach an Independent Disk,” on page 112 n “Creating and Using vApp Snapshots,” on page 114 n “Operate a vApp,” on page 115 n “Configuring vApps and Virtual Machines,” on page 116 Summary of vCloud API vApp and Virtual Machine Operations Requests These vCloud API operations requests create, manage, operate, and delete vApps and the
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 Get a Screen Thumbnail for a Virtual Machine GET Vm-URL/screen None Returns a screen thumbnail (Content-type: image/png) if one is available. Otherwise returns null (ContentLength: 0). Get a Screen Ticket for a Virtual Machine POST VmURL/screen/action/acquire Ticket None ScreenTicket Attach an independent disk to a virtual machine.
vCloud API Programming Guide n One or more EulaSection elements that specify licensing terms or other conditions that you must accept before creating the vApp. The InstantiateVAppTemplateParams element can include an AllEULAsAccepted element whose value indicates whether you accept all EULA terms included in the template. If a vApp template includes any ovf:EulaSection elements, AllEULAsAccepted must be set to a value of true. Otherwise, instantiation fails. n A LeaseSettingsSection.
Chapter 5 Deploying and Operating vApps 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 96vCloud API Programming Guide Procedure 1 Examine the OVF descriptor of the template to determine the values that you can include in a SourcedVmInstantiationParams element. See “Example: Modify Virtual Machine Hardware During vApp Template Instantiation,” on page 96 for guidelines. 2 Include the SourcedVmInstantiationParams element in an InstantiateVAppTemplateParams element. See “Example: Modify Virtual Machine Hardware During vApp Template Instantiation,” on page 96.
Chapter 5 Deploying and Operating vApps bridged Lease Settings 172800 2013-04-11T08:08:16.
vCloud API Programming Guide n You know the URL of the target VDC that will receive the upload. Retrieve the XML representation of your organization to see a list of the VDCs that it contains. Review the contents of the Envelope element in the descriptor file of your OVF package. Several properties in this file have implications for the InstantiateOvfParams request body you must construct to initiate the upload. Procedure 1 Retrieve the XML representation of the target VDC.
Chapter 5 Deploying and Operating vApps Example: Create a vApp From an OVF Package This request includes a NetworkMapping element that maps a network name found in the uploaded OVF descriptor to the name of a network available in the target VDC. Request: POST https://vcloud.example.com/api/vdc/5/action/instantiateOvf Content-Type: application/vnd.vmware.vcloud.instantiateOvfParams+xml ... PAGE 100vCloud API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... PAGE 101Chapter 5 Deploying and Operating vApps Compose a vApp From Existing Virtual Machines With the vCloud API composeVApp operation, you can build a vApp from existing virtual machines, including virtual machines contained by vApps and vApp templates to which you have access. Every VDC includes a link to a composeVApp operation, which creates a new vApp in it. To compose a vApp, POST a composeVApp request to this link.
vCloud API Programming Guide Example: Compose a vApp This request specifies two vAppTemplate items and one Vm item. The Vm item requires InstantiationParams that modify its NetworkConnectionSection to specify the vApp network created for this vApp. The vAppTemplate items inherit this setting from the base InstantiationParams element that appears before the first SourcedItem is specified. NOTE Virtual machines specified in Source elements must be powered off or this operation will fail.
Chapter 5 Deploying and Operating vApps true The response is a sparsely populated VApp element in the target VDC.
vCloud API Programming Guide Procedure 1 Find the recomposeVApp link in the target vApp. The XML representation of a vApp contains a recomposeVapp link, which has the following form: 2 Create a RecomposeVappParams element that specifies the details of the recomposition. See “Example: Recompose a vApp,” on page 104.
Chapter 5 Deploying and Operating vApps Request: POST https://vcloud.example.com/api/vApp/vapp-33/action/recomposeVApp Content-Type: application/vnd.vmware.vcloud.recomposeVAppParams+xml ... PAGE 106vCloud API Programming Guide Clone a vApp You can make a copy of a vApp by cloning it. If the vApp is deployed when you clone it, the clone procedure also clones the memory state of the virtual machines in the vApp. The cloneVApp request makes a copy of the vApp referenced in the Source element of the CloneVappParams request body. The request specifies a new name and, optionally, a new description for the copy.
Chapter 5 Deploying and Operating vApps Request: POST https://vcloud.example.com/api/vdc/12/action/cloneVApp Content-Type: application/vnd.vmware.vcloud.cloneVAppParams+xml ... PAGE 108vCloud API Programming Guide status="running" operation="Copying Virtual Application cloned (103)" ... > ... Capture a vApp as a Template You can capture a vApp to create a vApp template in a catalog. Instantiating the resulting template recreates the vApp from which it was captured. The captureVApp request creates a template based on the vApp referenced in the Source element of the CaptureVAppParams request body.
Chapter 5 Deploying and Operating vApps Example: Capture a vApp This request captures the vApp created in “Example: Compose a vApp,” on page 102. Because the request does not specify a TargetCatalogItem, a new catalog item is created for the new template. Request: POST https://vcloud.example.com/api/catalog/5/action/captureVApp Content-Type: application/vnd.vmware.vcloud.captureVAppParams+xml ... PAGE 110vCloud API Programming Guide Update vApp Access Controls A system or organization administrator can use the controlAccess links in a VApp element to grant or restrict access to the vApp. A vApp initially grants full access to its owner and no access to other users. The vCloud API access control mechanism enables an administrator to retrieve or update vApp access controls to add or remove rights for all users, or for individual users.
Chapter 5 Deploying and Operating vApps Response: 200 OK Content-Type: application/vnd.vmware.vcloud.controlAccess+xml ... false ...
vCloud API Programming Guide msg.parallel.file.open:Parallel port output file "/vmfs/volumes/d6162a46-58e50cab/linuxftp/vm-mgi.log" already exists.
Chapter 5 Deploying and Operating vApps n Verify that the VDC contains an independent disk. If the VDC does not contain independent disks, you can create one. See “Create or Update an Independent Disk,” on page 80. Procedure 1 Retrieve a reference to the independent disk to attach to a virtual machine. The independent disk and the virtual machine must be contained by the same VDC. You can retrieve references to independent disks in a VDC in the following ways: n Use the query service.
vCloud API Programming Guide 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.
Chapter 5 Deploying and Operating vApps 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.
vCloud API Programming Guide 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.
Chapter 5 Deploying and Operating vApps Configuring a vApp You can include the following sections in the InstantiationParams you supply 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.
vCloud API Programming Guide 4 Update the section by making a PUT request to the section’s edit link, a Link element in the section where rel="edit", and supplying the modified section in the request body. 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.
Chapter 5 Deploying and Operating vApps type="application/vnd.vmware.vcloud.leaseSettingsSection+xml" href="https://vcloud.example.com/api/vApp/vapp-7/leaseSettingsSection/" /> ... ... ...
vCloud API Programming Guide Table 5‑2.
Chapter 5 Deploying and Operating vApps status="8" name="ubuntu10-x86" href="https://vcloud.example.com/api/vApp/vm-4"> ... ... PAGE 122vCloud API Programming Guide rel="edit" type="application/vnd.vmware.vcloud.operatingSystemSection+xml" href="https://vcloud.example.com/api/vApp/vm-4/operatingSystemSection/" /> ... PAGE 123Chapter 5 Deploying and Operating vApps Table 5‑3.
vCloud API Programming Guide Table 5‑3.
Chapter 5 Deploying and Operating vApps Table 5‑4. vCloud API Custom Attributes for OVF and RASD Elements (Continued) Element Name rasd:HostResource RASD Resource Type 17 (Hard disks) Attribute Name Attribute Type Description busSubType xs:string Hard disk controller type. One of: n buslogic n lsilogic n lsilogicsas n VirtualSCSI n vmware.sata.ahci See “Retrieve or Modify the Hard Disk Configuration of a Virtual Machine,” on page 143 for valid combinations of busType and busSubType.
vCloud API Programming Guide Example: Update Multiple Sections of a Virtual Machine This example uses the reconfigureVm operation to accomplish the updates shown in “Example: Update a NetworkConnectionSection,” on page 135 and “Example: Modify the Guest Customization Section of a Virtual Machine,” on page 138 in a single operation. Request: POST https://vcloud.example.com/api/vApp/vm-4/action/reconfigureVm Content-Type: application/vnd.vmware.vcloud.vm+xml ...
Chapter 5 Deploying and Operating vApps Win2K3 ... Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Retrieve or Update a Modifiable Section You can make a GET request to the URL of any modifiable section to retrieve it for modification.
vCloud API Programming Guide Response: 200 OK Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml ... Configuration parameters for logical networks PAGE 129Chapter 5 Deploying and Operating vApps 2 Modify the returned NetworkConfigSection 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.
vCloud API Programming Guide 10.147.56.1 10.147.56.1 PAGE 131Chapter 5 Deploying and Operating vApps 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.
vCloud API Programming Guide 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.
Chapter 5 Deploying and Operating vApps 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.
vCloud API Programming Guide 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.
Chapter 5 Deploying and Operating vApps 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.
vCloud API Programming Guide 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 an administrator or vApp Author. 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.
Chapter 5 Deploying and Operating vApps Request: PUT https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/cpu Content-type: application/vnd.vmware.vcloud.rasdItem+xml ... - PAGE 138
vCloud API Programming Guide 2 Modify the retrieved section. 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 5 Deploying and Operating vApps ... operation="Updating Virtual Application Win2K3 (12)" ...> ... 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.
vCloud API Programming Guide The modified section replaces the contents of the original section, subject to the rules listed in Step 2. 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 ...
Chapter 5 Deploying and Operating vApps After the vApp is powered on, a virtual machine can retrieve the ovf:Environment document in the following ways: n It can use the default OVF iso transport type. This makes the environment document available as a file named ovf-env.xml on an ISO image that is mounted on the first available CD-ROM device on the virtual machine. You can use any convenient mechanism to read this file. [root@example-vm-RHEL ~] cat /media/cdrom/ovf-env.xml
vCloud API Programming Guide Retrieve or Modify Groups of Related Sections in a Virtual Machine The vCloud API provides links that you can use to retrieve or update groups of sections that define related hardware items such as disks, media devices, and network cards in a Vm element. As shown in “Example: Configuration Links in a Vm Element,” on page 120, Link elements for disks, media devices, and network cards are grouped at the end of the VirtualHardwareSection.
Chapter 5 Deploying and Operating vApps rel="edit" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="https://vcloud.example.
vCloud API Programming Guide Procedure 1 Retrieve the hard disk configuration from the virtual machine. Make a GET request to the virtual machine's virtualHardwareSection/disks link. GET https://vcloud.example.
Chapter 5 Deploying and Operating vApps xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cimschema/2/CIM_ResourceAllocationSettingData" type="application/vnd.vmware.vcloud.
vCloud API Programming Guide Update the Storage Profile for a Virtual Machine You can update a Vm to revalidate the storage profile it uses or specify a different storage profile. Revalidation of a virtual machine's current storage profile is required whenever the datastore that supports the virtual machine changes. Every Vm element includes a StorageProfile element. The value of the href attribute of that element is a reference to the virtual machine's storage profile.
Chapter 5 Deploying and Operating vApps type="application/vnd.vmware.vcloud.vdcStorageProfile+xml" name="Gold" href="https://vcloud.example.com/api/vdcStorageProfile/3" /> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... VMware, Inc.
vCloud API Programming Guide 148 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 150 Operation Request Request Body Response Retrieve an administrative view of an organization. GET APIURL/admin/org/id None AdminOrg Create an organization. POST API-URL/admin/orgs AdminOrg AdminOrg Enable an organization. POST APIURL/admin/org/id/action/e nable None 204 No Content Disable an organization. POST APIURL/admin/org/id/action/d isable 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 Retrieve the admin view of a provider VDC. GET APIURL/admin/providervdc/id None ProviderVdc 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.
vCloud API Programming Guide Table 6‑1. Summary of Administrative Requests (Continued) Operation Request Request Body Response Retrieve a list of tasks owned by organization id. GET API-URL/tasksList/id None TasksList Retrieve a task. GET API-URL/task/id None Task Cancel a task. POST APIURL/task/id/action/cancel None 204 No Content Administrator Credentials and Privileges An administrator's privileges are scoped by the organization to which the administrator authenticates.
Chapter 6 Creating and Managing Organizations Organization Administration System administrators create organizations and organization administrators, and establish certain organization policies. Organization administrators populate their organization with users and groups, assign roles, and can update most organization policies and properties. A cloud can contain one or more organizations. Each organization is a unit of administration for a collection of users, groups, and computing resources.
vCloud API Programming Guide Request: POST https://vcloud.example.com/api/admin/orgs Content-Type: application/vnd.vmware.admin.organization+xml ... PAGE 155Chapter 6 Creating and Managing Organizations rel="add" type="application/vnd.vmware.admin.catalog+xml" href="https://vcloud.example.com/api/admin/org/26/catalogs" /> PAGE 156
vCloud API Programming Guide PAGE 157
Chapter 6 Creating and Managing Organizations Retrieve or Update Organization Settings Organization settings define organization policies such as default lease settings for vApps and how incorrect login attempts are handled. They also configure how the organization uses services such as email and LDAP, and define the organization's federated identity provider if it uses one.
vCloud API Programming Guide Procedure 1 Retrieve the list of organization settings elements. Use a request like this one: GET https://vcloud.example.com/api/admin/org/26/settings The response is an OrgSettings element. 2 Examine the OrgSettings element to find the links to the sections to view or modify. Each section is represented in the OrgSettings element with a link where rel="down". You can use that link to retrieve the section. The retrieved section includes a link where rel="edit".
Chapter 6 Creating and Managing Organizations 100 false 0 The response contains information extracted from the request, and includes a rel="edit" link and other attributes that the server creates. Response: 200 OK Content-Type: application/vnd.vmware.admin.organizationGeneralSettings+xml ... PAGE 160vCloud API Programming Guide 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 49. Procedure n To enable an organization, POST a request to its action/enable link.
Chapter 6 Creating and Managing Organizations 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.
vCloud API Programming Guide 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. When you use this allocation model, any Limit values you specify for Memory and CPU are ignored when you create a vApp and returned as 0 when you retrieve a vApp.
Chapter 6 Creating and Managing Organizations PAGE 164vCloud API Programming Guide PAGE 165
Chapter 6 Creating and Managing Organizations type="application/vnd.vmware.admin.vdc+xml" href="https://vcloud.example.com/api/admin/vdc/44" ... > PAGE 166vCloud API Programming Guide href="https://vcloud.example.com/api/admin/vdc/44/vdcStorageProfiles" /> ... ... ... Update Organization VDC Storage Profiles A system administrator can update the storage profiles that are available in an organization VDC.
Chapter 6 Creating and Managing Organizations 3 Create an UpdateVdcStorageProfiles request body that specifies the details of the update. To add a storage profile: a Select a storage profile from the Provider VDC referenced in the ProviderVdcReference element of the VDC you are updating. The storage profile must not be listed in the VdcStorageProfiles element of the VDC you are updating. b Include an AddStorageProfile element in the UpdateVdcStorageProfiles request body.
vCloud API Programming Guide id="urn:vcloud:providervdcstorageprofile:128" href="https://vcloud.example.com/api/admin/pvdcStorageProfile/128" /> ... Using information, you can construct the AddStorageProfile element in the request body. Request: POST https://vcloud.example.com/api/admin/vdc/44/vdcStorageProfiles Content-Type: application/vnd.vmware.admin.updateVdcStorageProfiles+xml ...
Chapter 6 Creating and Managing Organizations d POST a request to its action/disable link to disable the VDC. After the VDC is disabled, its representation includes a rel="remove" link. e Make a DELETE request to the VDC's rel="remove" link. The server takes the requested action and returns an HTTP status of 204 No Content. Network Administration A newly created organization VDC has no networks in it.
vCloud API Programming Guide The configuration of a vApp network, contained in the NetworkConfig element of the InstantiateVAppTemplateParams request body, includes the following information n A name for the network, specified in the networkName attribute of the NetworkConfig element. The instantiation parameters must create a vApp network whose name matches the value of the network attribute of the NetworkConnection of each Vm element in the template.
Chapter 6 Creating and Managing Organizations n An isolated organization VDC network does not require an Edge Gateway or external network, but does require the containing VDC to be associated with a network pool. After a system administrator has created an organization VDC with a network pool, organization administrators or system administrators can create isolated organization VDC networks in that VDC. n Most types of organization VDC networks do not provide any network services.
vCloud API Programming Guide For an example of adding services to an Edge Gateway, see “Configure Edge Gateway Services,” on page 177. For more information about any of these services, see the vShield Administration Guide. External Networks and Network Pools External networks and network pools are vSphere resources backed by vSphere portgroup, VLAN, or DVswitch objects.
Chapter 6 Creating and Managing Organizations 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.
vCloud API Programming Guide For information about additional elements that an EdgeGateway can contain, see “Example: Create an Edge Gateway,” on page 174 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.
Chapter 6 Creating and Managing Organizations Request: POST https://vcloud.example.com/api/admin/vdc/44/edgeGateways Content-Type: application/vnd.vmware.admin.edgeGateway+xml ... PAGE 176vCloud API Programming Guide href="https://vcloud.example.com/api/admin/edgeGateway/2000" /> PAGE 177
Chapter 6 Creating and Managing Organizations 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.
vCloud API Programming Guide 5 POST the modified EdgeGatewayServiceConfiguration element to the URL in the value of the href attribute of the configureServices link described in Step 2. 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.
Chapter 6 Creating and Managing Organizations 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.
vCloud API Programming Guide 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.
Chapter 6 Creating and Managing Organizations 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 178. 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.
vCloud API Programming Guide SNAT true 192.168.0.10-192.168.0.255 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 178.
Chapter 6 Creating and Managing Organizations false vnic3 routed2 internal 172.168.0.1 255.255.255.0 172.168.0.
vCloud API Programming Guide 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 131. 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.
Chapter 6 Creating and Managing Organizations n A VirtualServer element that defines the Interface, an internal or external interface defined by the containing EdgeGateway, on which requests are accepted. 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.
vCloud API Programming Guide 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 178.
Chapter 6 Creating and Managing Organizations 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.
vCloud API Programming Guide 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 169. 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.example.
Chapter 6 Creating and Managing Organizations 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.
vCloud API Programming Guide 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.
Chapter 6 Creating and Managing Organizations Bridged to the public Internet ...
vCloud API Programming Guide 3 Create an OrgVdcNetwork element. a Specify a value of natRouted in the FenceMode element of the network Configuration. You can specify additional Configuration parameters, as noted in the schema reference. b Specify the href of the Edge Gateway you chose in Step 1 in the EdgeGateway element. See the request portion of “Example: Create an Organization VDC Network With a Routed Connection,” on page 192.
Chapter 6 Creating and Managing Organizations true Response: 201 Created Content-Type: application/vnd.vmware.vcloud.orgVdcNetwork+xml ... PAGE 194vCloud API Programming Guide name="theEdge" href="https://vcloud.example.com/api/admin/edgeGateway/2000" /> true
NOTE When the Task completes, the new network is represented in the EdgeGateway by a GatewayInterface whose InterfaceType is Internal. Unlike the Uplink interface that you create when you create an EdgeGateway, an internal interface cannot be created explicitly. It is created only as a side-effect of creating a routed organization VDC network.
Chapter 6 Creating and Managing Organizations false 192.168.0.1 255.255.255.0 10.147.115.1 example.com 192.168.0.100 192.168.0.
vCloud API Programming Guide href="https://vcloud.example.com/api/admin/network/60/allocatedAddresses/" /> Isolated Organization Vdc Network ... false 3600 7200 192.168.0.
Chapter 6 Creating and Managing Organizations 3 Make a POST request to the href value of the link described in Step 2. The request does not have a request body. The response is a task. 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 172. POST https://vcloud.example.
vCloud API Programming Guide items that hold local copies of that content. Synchronization keeps a catalog up to date with its external subscription. A catalog owner can synchronize individual catalog items or entire catalogs at any time. A system administrator can also schedule background synchronization for catalogs, so that all externally subscribed catalogs in the system are synchronized on a common schedule.
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 Response: 201 Created Content-Type: application/vnd.vmware.admin.catalog+xml ... PAGE 201Chapter 6 Creating and Managing Organizations Create a Catalog For External Publication An organization administrator in an organization that has permission to publish externally can create a catalog whose contents, catalog items created locally, are made available to external consumers on a subscription basis. Organizations that are permitted to publish externally can enable any of their catalogs for external publication.
vCloud API Programming Guide Request: POST https://vcloud.example.com/api/admin/org/26/catalogs Content-Type: application/vnd.vmware.admin.catalog+xml ... PAGE 203Chapter 6 Creating and Managing Organizations true false
When the task completes, the PublishExternalCatalogParams includes a URL at which external consumers can connect to the catalog. ... true true https://vcloud2.example.
vCloud API Programming Guide Example: Create a Catalog With an External Subscription This request creates a catalog with a subscription to the VCSP URL https://vcloud2.example.com/vcsp/catalog/5. Because the LocalCopy element in ExternalCatalogSubscriptionParams has a value of false, files that comprise a vApp template or media image that a catalog item references are not downloaded until a user requests them.
Chapter 6 Creating and Managing Organizations operation="Creating Catalog SubscribedExternally (34)" ... Example Catalog With External Subscription false 2013-06-18T10:00:03.012-07:00 1 true https://vcloud2.example.
vCloud API Programming Guide NOTE If you are a system administrator, you must filter the response to show only those storage profiles in the organization where you are creating the catalog. 2 Create an AdminCatalog element that includes a CatalogStorageProfiles element.
Chapter 6 Creating and Managing Organizations Update Catalog Access Controls If you are an administrator or catalog owner, you can use the controlAccess links in your organization to grant or restrict access to a catalog.
vCloud API Programming Guide false FullControl PAGE 209Chapter 6 Creating and Managing Organizations 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.publishCatalogParams+xml, as this example shows: PAGE 210
vCloud API Programming Guide NOTE The controlAccess links for catalogs are not returned in the AdminOrg response when you retrieve the organization in the admin view. 3 Create a ControlAccessParams element that contains an AccessSettings element that specifies the organizations with which to share the catalog.
Chapter 6 Creating and Managing Organizations Publish an Existing Catalog Externally An organization administrator in an organization that has permission to publish externally can update an existing catalog to make its contents available to external consumers on a subscription basis. Organizations that are permitted to publish externally can enable any of their local catalogs for external publication.
vCloud API Programming Guide xmlns="http://www.vmware.com/vcloud/v1.5"> true Password>Pa55w0rd Response: 204 No Content Content Subscription Endpoint Specification This document specifies the requirements for creating an endpoint that is compatible with a client using version 1 of the VMware Content Subscription Protocol (VCSP).
Chapter 6 Creating and Managing Organizations Endpoint Descriptor The endpoint descriptor is a file whose contents define the catalog available at the endpoint. The contents, which must be expressed in JavaScript Object Notation (media type application/json) as defined by RFC4627, define a JSON object, and must specify values for the following key names. vcspVersion An integer that specifies the version of the VCSP protocol to which this endpoint conforms.
vCloud API Programming Guide "generateIds" : true } "metadata" : [ { "type" : "STRING", "domain" : "GENERAL", "key" : "key1", "value" : "value1", "visibility" : "READWRITE" }, { "type" : "STRING", "domain" : "SYSTEM", "key" : "key2", "value" : "value2", "visibility" : "READONLY" } ] } Endpoint Index The endpoint index is a file whose contents define the set of items available in the catalog.
Chapter 6 Creating and Managing Organizations files properties An array of file objects that includes all the files that represent the item. Each file object is represented as an array with three elements: etag An integer representing the version of the file. The value of this key must be the same for each file in the array. When any file in this array gets updated, you must increment the value of the etag key for all files in the array. name The name of the file.
vCloud API Programming Guide }, { "name" : "descriptor.mf", "hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/descriptor.mf" ] }, { "etag" : "37" "name" : "vm-d5349476-aae2-4b65-bc9a-28effdc213fb-disk-0.vmdk", "hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/vm-d5349476-aae2-4b65bc9a-28effdc213fb-disk-0.vmdk" ] } ], "properties" : { }, "selfHref" : "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/item.
Chapter 6 Creating and Managing Organizations Metadata The endpoint descriptor and endpoint index allow you to include object metadata that is used to create vCloud Director object metadata when endpoint contents are synchronized by a subscribed catalog. For more information about the design and operation of vCloud Director object metadata, see Chapter 8, “Working With Object Metadata,” on page 281. metadata An array of object metadata.
vCloud API Programming Guide files properties An array of file objects that includes all the files that represent the item. Each file object is represented as an array with two elements: name The name of the file. hrefs An array of pathnames to the file. Must contain a single pathname to the file from the root of the endpoint, written as a URL fragment. An array of additional properties of the item. Must be empty. The following example shows a typical item descriptor for an OVF package.
Chapter 6 Creating and Managing Organizations An operation that has encountered an error could return the following response. { "status" : "failed", "message" : "File Generation failed" } Authentication An endpoint can require authentication. VCSP clients always present the user name vcsp when logging in. The endpoint can specify any password for this user, but must accept the user name vcsp. The user name and password are encoded as specified for Basic HTTP authentication.
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 223. 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 153. 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 226vCloud 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 222, 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‑6. Rights Associated With vApp Templates and Media (Continued) Admin Catalog Author vApp Author vApp User vApp Template or Media: View X X X X vApp Template: Checkout (Add to My Cloud) X X X X Catalog Author vApp Author vApp User X Console Access Only Rights Associated with vApps Table 6‑7.
vCloud API Programming Guide Table 6‑8.
Chapter 6 Creating and Managing Organizations Create a Role An organization administrator can create a role by aggregating a set of rights in a Role element and POSTing it to the organization's add URL for roles. Prerequisites Verify that you are logged in to the vCloud API as an organization administrator or system administrator. Procedure 1 Create a Role element that defines the role with a name and a set of rights.
vCloud API Programming Guide name="vApp: Create / Reconfigure" href="https://vcloud.example.com/api/admin/right/2dc8abec-2e0d-3789-a5f9ce0453160b53" /> PAGE 233Chapter 6 Creating and Managing Organizations xmlns="http://www.vmware.com/vcloud/v1.5" href="https://vcloud.example.com/api/admin/role/102" ...> Create and manage vApps ... VMware, Inc.
vCloud API Programming Guide 234 VMware, Inc.
Managing 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 well-known 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 Prepare an ESXi host. POST APIURL/admin/extension/hos t/id/action/prepare PrepareHostParams Task Unprepare an ESXi host. POST APIURL/admin/extension/hos t/id/action/unprepare None Task Enable an ESXi host. POST APIURL/admin/extension/hos t/id/action/enable None Task Disable an ESXi host.
vCloud API Programming Guide Table 7‑1. Summary of vSphere Platform Extension Requests (Continued) 238 Operation Request Request Body Response Create a network pool. POST APIURL/admin/extension/net workPools VMWNetworkPool VMWNetworkPool 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.
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/exitM aintenanceMode 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 License System license serial number and related settings. BrandingSettings Customize the branding of the vCloud Director Web Console and some of the links that appear on the vCloud Director Home login screen. BlockingTaskSettings Control the behavior of blocking tasks and enable blocking for specific operations. PasswordPolicySettings Specify default policies to be followed when a user in any organization enters an incorrect password.
Chapter 7 Managing and Monitoring a Cloud Procedure 1 Retrieve the XML representation of the vSphere platform extensions. Use a request like this one. GET https://vcloud.example.com/api/admin/extension 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 242
vCloud API Programming Guide xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5" xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"> ...
Chapter 7 Managing and Monitoring a Cloud Example: Resources on a vCenter Server Request: GET https://vcloud.example.com/api/admin/extension/vimServer/9 Response: 200 OK ... ...
vCloud API Programming Guide Retrieve a List of Resource Pools from a vCenter Server You can retrieve the list of resource pools available on a vCenter server registered to a cloud. To retrieve the list, you make a GET request to the server's resourcePoolList link. The ResourcePoolList of a VimServer element contains an entry for every available resource pool on the server. Resource pools that a provider VDC is already using are not listed, because they are considered unavailable.
Chapter 7 Managing and Monitoring a Cloud datastore-172 DATASTORE PAGE 246vCloud API Programming Guide 3 GET the URL in the value of this link's href attribute to retrieve the list of network resources. See “Example: Retrieve a List of Available Portgroups and Switches from a vCenter Server,” on page 246. If the list is empty, all network resources on the server are already in use. Example: Retrieve a List of Available Portgroups and Switches from a vCenter Server Request: GET https://vcloud.example.
Chapter 7 Managing and Monitoring a Cloud Procedure 1 Retrieve the XML representation of your cloud. Use a request like this one: GET https://vcloud.example.com/api/admin/extension 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 248vCloud 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 a vCenter server registered to your cloud. 2 Examine the response, a VimServer element, to locate the vmsList link. This link has the following form: PAGE 249Chapter 7 Managing and Monitoring a Cloud href="https://vcloud.example.com/api/admin/extension/vimServer/9" /> vm-44 VIRTUAL_MACHINE 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.
vCloud API Programming Guide 3 GET the URL in the value of this link's href attribute to retrieve the list of storage profiles. See “Example: Retrieve a List of Storage Profiles from a vCenter Server,” on page 250. 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 name="Bronze"> ... 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 4 POST the VMWProviderVdc element you created in Step 3 to the URL described in Step 2. See the request portion of “Example: Create a Provider VDC,” on page 252. 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.
Chapter 7 Managing and Monitoring a Cloud Response: 201 Created Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml ... PAGE 254vCloud API Programming Guide MB 0 0 0 0 PAGE 255Chapter 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.
vCloud API Programming Guide rel="up" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="https://vcloud.example.com/api/admin/extension/providervdc/35" /> PAGE 257Chapter 7 Managing and Monitoring a Cloud 2 Locate the updateResourcePools link in the VMWProviderVdc. Every VMWProviderVdc element includes an action link like this one to the Provider VDC's updateResourcePools action. 3 Retrieve the resource pool list from the Provider VDC.
vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... This request removes one of the two resource pools (a secondary resource pool) shown in “Retrieve a Provider VDC Resource Pool Set,” on page 255. The response is a task. Request: POST https://vcloud.example.com/api/admin/extension/providervdc/35/action/updateResourcePools Content-Type: application/vnd.vmware.admin.resourcePoolSetUpdateParams+xml ...
Chapter 7 Managing and Monitoring a Cloud 2 Examine the VMWProviderVdc element to find the storageProfiles link and the vmext:VimServer element. The storageProfiles link has the following form: 3 Create an UpdateProviderVdcStorageProfiles request body that specifies the details of the update.
vCloud API Programming Guide xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5" xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"> Bronze Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Merge Provider VDCs You can merge two Provider VDCs by specifying a target Provider VDC and a contributor Provider VDC to merge with it.
Chapter 7 Managing and Monitoring a Cloud Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.
vCloud API Programming Guide 5 POST the VMWExternalNetwork element you created in Step 4 to the URL described in Step 2. See the request portion of “Example: Create an External Network,” on page 262. 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.
Chapter 7 Managing and Monitoring a Cloud name="example-extnet" id="urn:vcloud:network:85" type="application/vnd.vmware.admin.vmwexternalnet+xml" href="https://vcloud.example.com/api/admin/extension/externalnet/85"... > PAGE 264vCloud API Programming Guide Create a Network Pool Network pools provide support for isolated and routed networks in organization VDCs. Although every Provider VDC includes a VXLAN network pool that can support most networking use cases, a system administrator can create other types of network pools if they are needed. A network pool object represents a collection of vSphere network resources that are contained by a Provider VDC and available to the organization VDCs backed by that Provider VDC.
Chapter 7 Managing and Monitoring a Cloud Procedure 1 Retrieve the XML representation of the vSphere platform extensions. Use a request like this one. GET https://vcloud.example.com/api/admin/extension 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 266
vCloud API Programming Guide The query response includes the values you'll need for the VimServerRef and MoRef elements. The VimObjectType for a DV Switch is always DV_SWITCH. Request: POST https://vcloud.example.com/api/admin/extension/networkPools Content-Type: application/vnd.vmware.admin.networkPool+xml ... PAGE 267Chapter 7 Managing and Monitoring a Cloud status="running" ... 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.
vCloud API Programming Guide xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="vmext:FencePoolType" name="example-isolation-pool" type="application/vnd.vmware.admin.networkPool+xml"> Example Isolation-backed network pool 5 0 PAGE 269Chapter 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 264.
vCloud API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.admin.networkPool+xml ... PAGE 271Chapter 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 272vCloud 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 274vCloud API Programming Guide Prerequisites Verify that you are logged in to the vCloud API as a system administrator or the object owner. Procedure 1 Retrieve the Vm element. Make a GET request to the URL in the value of the href attribute of the Vm. 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.
Chapter 7 Managing and Monitoring a Cloud Truststore and Keytab Maintenance You can use the vCloud API to upload and manage SSL certificates, keystores, and Kerberos keytabs for your organization's LDAP service. The OrgLdapSettings element includes links that you can use to manage the organization's LDAP truststore and keystore by uploading new certificates and keytabs. PAGE 276
vCloud API Programming Guide href="https://vcloud.example.com/api/admin/extension/settings/ldapSettings/action/resetLdapKeySto re" /> PAGE 277Chapter 7 Managing and Monitoring a Cloud The response contains an uploadLocation parameter whose value is a URL to which you can upload the certificate. Response:
vCloud API Programming Guide n n HOST n NETWORK n RESOURCE_POOL n STORAGE_PROFILE (available from vCenter 5.1 and later) n VIRTUAL_MACHINE vimObjMoref is the vSphere managed object reference of the object, as returned by the vCloud API. For an example request URL, see the request portion of “Example: Retrieve the vSphere URL of a Resource Pool,” on page 278.
Chapter 7 Managing and Monitoring a Cloud Response: https://10.147.22.134:8443/vsphere-client/#extensionId=vsphere.core.sp.summary;... Use the URL that the vmext:URL element contains to access the object with the vSphere Web Client. The URL is truncated in this example.
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 282 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="add" link that you can use to add metadata and a rel="up" link that references the containing object, as shown in this example. PAGE 285Chapter 8 Working With Object Metadata visibility="PRIVATE">SYSTEM LOS bronze
The response is a Task. Response: ...
vCloud API Programming Guide xsi:type="MetadataStringValue"> http://internal.example.com/orgs/Finance PAGE 287Chapter 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 288 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 href="https://vcloud.example.com/api/query?type=organization&format=records" /> ...
vCloud API Programming Guide storedVMQuota="0" 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 293Chapter 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 type="application/vnd.vmware.vcloud.query.references+xml" 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 295
Chapter 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 name="catalog" 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 297
Chapter 9 Using the Query Service organizationName="Engineering" 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 298vCloud 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 299Chapter 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 Filter Expressions For queries that do not examine object metadata, you can filter results using string matching or numeric comparison operations. A filter comprises one or more subexpressions drawn from the following set of operators. 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.
Chapter 9 Using the Query Service n The type of the value must be specified, using one of the following keywords. Table 9‑4.
vCloud API Programming Guide Encoding Filter Expressions When you are comparing a key with a literal value that includes characters that might be subject to interpretation when used in a URL (often termed unsafe characters), the value must be encoded as described in RFC3986 (pct-encoded).
Chapter 9 Using the Query Service Add a Metadata Filter to a Query All packaged queries and most typed queries return object metadata if it exists for an object in the result set. You can add metadata-specific filter criteria to a query. To query an object's metadata, add a metadata field specifier to the query. This specifier follows the fields parameter and consists of the string metadata: followed by the name of a metadata key. Procedure 1 Create the filter expression.
vCloud API Programming Guide visibility="PRIVATE">SYSTEM expiry 2012-05-01T00:00:00.000-04:00 rank 1 PAGE 305Chapter 9 Using the Query Service expiry 2012-06-01T00:00:00.
vCloud API Programming Guide 306 VMware, Inc.
Configuring 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 See “Notification Message Format,” on page 312. AMQP client programs can connect to the broker and specify components of the AMQP routing key to indicate their interest in messages based on content. For example, a client can use the routing key to request the broker to send it all messages from a specific organization, or all messages that indicate a failed task. See “Routing Key Format,” on page 312.
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" ... > PAGE 311Chapter 10 Configuring and Using Blocking Tasks and Notifications Procedure 1 Examine the SystemSettings element to locate the link that you can use to retrieve the system's AmqpSettings element. This link has a rel attribute value of down and a type attribute value of application/vnd.vmware.admin.amqpSettings+xml as shown here: PAGE 312
vCloud API Programming Guide xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" type="application/vnd.vmware.admin.amqpSettingsTest+xml" href="https://vcloud.example.com/api/admin/extension/settings/amqp/action/test" ... > PAGE 313Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10‑1. Notification Headers (Continued) Header Value notification.entityUUID The object identifier of the object on which an operation, an event of type com/vmware/vcloud/event/, triggered the notification. notification.orgUUID The object identifier of the organization that owns the affected object. notification.userUUID The object identifier of the user who made the request. notification.
vCloud API Programming Guide An XML Notification contains an entityResolver URL and EntityLink elements that provide more information about the entity, org, and user components of the routing key. Attributes of those elements show the name, type, and id of each component.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10‑2. User, Group, Role, and Session Events (Continued) Type (com/vmware/vcloud/event/) Description role/modify An existing role was modified. role/delete A role was deleted. Organization, Network, Catalog, and VDC Events Table 10‑3. Organization, Network, Catalog, and VDC Events Type (com/vmware/vcloud/event/) Description org/create An organization was created. org/modify An organization was modified.
vCloud API Programming Guide Table 10‑4. vApp, vApp Template, Vm, and Media Events (Continued) 316 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.
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 vm/undeploy_request A request to undeploy a virtual machine was blocked pending administrative action. vm/undeploy A virtual machine was undeployed. vm/consolidate_request A request to consolidate a virtual machine was blocked pending administrative action. vm/consolidate A virtual machine was consolidated.
vCloud API Programming Guide Table 10‑5. Other System Events (Continued) Type (com/vmware/vcloud/event/) Description task/fail A task has failed. blockingtask/create A task was blocked and a notification created. blockingtask/resume A blocking task was resumed. blockingtask/abort A blocking task was aborted. 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.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Example: Update Blocking Task Settings This request modifies the blocking task settings for a cloud to set the time-out period to 24 hours and adds media upload as an operation that creates a blocking task. See “Task Operations,” on page 320 for a list of operation names. Request: PUT https://vcloud.example.com/api/admin/extension/settings/blockingTask Content-Type: application/vnd.vmware.admin.blockingTaskSettings+xml ...
vCloud API Programming Guide Task Operations Requests that you can configure as blocking tasks are represented by task operation names. To configure a request type as a blocking task, place the operation name in an Operation element and add that element to the cloud's BlockingTaskOperations element. See “Retrieve or Update Blocking Task Settings,” on page 318. NOTE These operation names also appear in the operationName attribute of the Task element that tracks the operation. Table 10‑6.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10‑7. Blocking Task Operations for VDC Tasks (Continued) Operation Name Description vdcCopyMedia Copy a media object. vdcCopyTemplate Copy a vApp template. vdcCopyVapp Clone a vApp. vdcCreateDisk Create an independent disk. vdcCreateVdc Create an organization VDC. vdcDeleteDisk Delete an independent disk. vdcDeleteMedia Delete a media object. vdcDeleteTemplate Delete a vApp template. vdcDeleteVapp Delete a vApp.
vCloud API Programming Guide Table 10‑8. Blocking Task Operations for Network Tasks (Continued) Operation Name Description networkUpdateNetwork Modify one or more properties of a network object. networkUpdateNetworkPool Modify one or more properties of a VlanPoolType network pool object. networkUpdateVlanPool Modify one or more properties of any network pool object. Table 10‑9. Blocking Task Operations for Edge Gateway Tasks Operation Name Description edgeGatewayUpdate Update an Edge Gateway.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10‑11. Blocking Task Operations for Resource Creation Tasks Operation Name Description rclCreateProviderVdc Create a provider VDC. rclDeleteProviderVdc Delete a provider VDC. rclDisableHost Disable a host. rclEnableHost Enable a host. rclEnableVxlanForProviderVdc Enable a VXLAN pool associated with a new Provider VDC. rclMergePvdc Merge Provider VDCs.
vCloud API Programming Guide Monitor Blocking Tasks A system administrator can retrieve a list of all pending and active blocking tasks. Links in the returned BlockingTask element allow the administrator to take action on the request. In addition to being subject to programmatic action by an AMQP client (see “Notification Message Format,” on page 312), blocking tasks can be monitored and managed by a system administrator using the vCloud API.
Chapter 10 Configuring and Using Blocking Tasks and Notifications type="application/vnd.vmware.admin.blockingTask+xml" name="vdcUploadMedia" href="https://vcloud.example.com/api/admin/extension/blockingTask/12" /> Take Action on a Blocking Task The BlockingTask element includes links that you can use to take action on a blocking task. A BlockingTask element is primarily a collection of Link elements that allow you to take action on the task.
vCloud API Programming Guide Action Request fail POST a BlockingTaskOperationParams element to the Link where rel="fail" updateProgress POST a BlockingTaskUpdateProgressParams element to the Link where rel="updateProgress" Example: Handling a Blocking Task This request shows how to retrieve a blocking task without using an AMQP client. #unique_177_Connect_42_EXAMPLE_B07B54418FAF480980ED867A833E22CC shows how to retrieve the same task using information in the AMQP message. Request: GET https://vcloud.
Chapter 10 Configuring and Using Blocking Tasks and Notifications href="https://vcloud.example.com/api/admin/org/97" /> PAGE 328vCloud API Programming Guide Request: POST https://vcloud.example.com/api/admin/extension/blockingTask/34/action/updateProgress Content-Type: application/vnd.vmware.admin.blockingTaskUpdateProgressOperationParams+xml ... Giving you ten more minutes...
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 333.
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 href="https://vcloud.example.com/api/admin/extension/service/45/apifilters" /> PAGE 336vCloud 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 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 333: GET https://vcloud.example.com/api/admin/extension/service/45 2 Examine the response to find the Link for adding service links. This Link has the following form: PAGE 338vCloud 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 service. This request retrieves the XML representation of the service created in “Example: Register an Extension Service,” on page 333: GET https://vcloud.example.com/api/admin/extension/service/45 2 Examine the response to find the Link for listing service links.
Chapter 11 vCloud Director Extension Services resourceType="application/vnd.vmware.vcloud.vApp+xml" rel="backup" 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.
vCloud API Programming Guide Create or Update a Service-Specific Task When a user requests an asynchronous operation from an extension service, the service can create a task object and add it to an organization's tasks list. Every vCloud Director organization has a tasks list and accepts requests to add a task to the list. When a client requests an asynchronous operation from a service, the service starts to process the request and also POSTs a Task element to the organization's tasksList URL.
Chapter 11 vCloud Director Extension Services type="application/vnd.vmware.vcloud.task+xml" operation="Backup in progress for virtual machine with id 7b91b053-2b..." operationName="backupInProgress" name="task"> PAGE 342vCloud API Programming Guide 4 POST the Event element to the organization's events URL. Example: Add an Event to an Organization's Event Stream Request: POST https://vcloud.example.com/api/admin/org/26/events Content-Type: application/vnd.vmware.admin.event+xml ... PAGE 343Chapter 11 vCloud Director Extension Services Resource Classes and Actions A service uses the following constructs to define the objects, operations, and permissions that constitute its authorization model. Resource Classes Set of rules for creating references to service-specific objects. Like other object references in the vCloud API, resource classes are a Link element that specifies the MIME type of the resource and includes an href,URL, that can be used to retrieve the resource.
vCloud API Programming Guide 2 Examine the response to find the Link for adding resource classes. This Link has the following form: 3 Construct a ResourceClass element. See the request portion of “Example: Create an Extension Service Resource Class,” on page 344 for information about the contents of this element.
Chapter 11 vCloud Director Extension Services rel="up" type="application/vnd.vmware.admin.service+xml" href="https://vcloud.example.com/api/admin/extension/service/45" /> PAGE 346vCloud API Programming Guide Request: POST https://vcloud.example.com/api/admin/extension/service/45/resourceclassactions Content-type:application/vnd.vmware.admin.resourceClassAction+xml PAGE 347Chapter 11 vCloud Director Extension Services n any resource defined by the service that created the ACL rule Rights for specific entity types are specified in the following container elements: ServiceResourceAccess This specification is optional. OrganizationAccess Access for the organizations. This specification is required. PrincipalAccess Access control for users, or for any role that includes a specified right. This specification is required.
vCloud API Programming Guide 4 POST the ResourceClassAction element to the URL described in Step 2. Example: Define an ACL Rule for a Resource Class Action This example adds an ACL rule to the resource class action created in “Example: Define an Action for a Resource Class,” on page 345. The rule specifies that all members of a specific organization who have a role that includes a specific right can execute the action. Request: POST https://vcloud.example.
Chapter 11 vCloud Director Extension Services rel="remove" href="https://vcloud.example.com/api/admin/extension/service/resourceclassaction/268" /> ... Create a Service-Specific Right A service can create rights that apply to its operations. You can add these rights to existing roles or new roles. In the vCloud API, a right is simply a name that a service attaches to a privilege. When a service specifies an ACL rule for a resource class action, the rule can reference a right.
vCloud API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.admin.right+xml ...
Chapter 11 vCloud Director Extension Services 3 Create a BundleUploadParams element that specifies the size of the bundle and the service namespace of the service. 4 POST the BundleUploadParams element to the localizationbundles URL of your service. Example: Upload a Localization Bundle This example uploads a localization bundle for the service created in “Example: Register an Extension Service,” on page 333.
vCloud API Programming Guide Whenever a localizable attribute appears in a log message, vCloud Director takes the following steps to find text to display: 1 If the service has a localization bundle, open the file in that bundle whose name corresponds to the current client locale and display the value as it appears in the file.
Chapter 11 vCloud Director Extension Services Example: Example Message File Content The following lines are appropriate in the en_US message file for a service that meets the following conditions: n Its Namespace is registered as org.example.vcd.backup. n It defined a Task whose operationName attribute can have a value of backupInProgress. n It defined an Event whose type attribute can have a value of backupComplete. org.example.vcd.
vCloud API Programming Guide Create an API Filter for an Extension Service When you register an extension service with vCloud Director, you specify one or more API filters, which are URL patterns or MIME content types that the vCloud Director REST service should treat as extension requests. You cannot update the API filter for a registered service, but you can replace it with a new one.
Chapter 11 vCloud Director Extension Services Response: 201 Created Content-Type: application/vnd.vmware.admin.resourceClass+xml ... (/api/org/.*/backups)|(/api/vApp/vapp-.*/backups)| (/api/vApp/vapp-.*/action/backup)|(/api/backup/.*) | (/api/vApp/vapp-.*/action/recoverBackup) Create or Update an Extension Service API Definition You can define an API for an extension service when you register the service.
vCloud API Programming Guide Example: Create an Extension Service API Definition This request defines an API for a backup service. The definition includes two FileDescriptor elements that reference files available on the vendor's public Website. The entrypoint for requests to the service is the vCloud Director API login URL. Request: POST https://vcloud.example.com/api/admin/extension/service/45/apidefinitions Content-type:application/vnd.vmware.admin.apiDefinition+xml
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.
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 362).
vCloud API Programming Guide Table 12‑4. status Attribute Values for VAppTemplate, VApp, Vm, and Media Objects (Continued) Num eric Valu e String Value Description 10 MIXED 11 vAppTem plate vApp Vm Media Children do not all have the same status. YES YES No No DESCRIPTOR_PEN DING Upload initiated, OVF descriptor pending. YES No No No 12 COPYING_CONTE NTS Upload initiated, copying contents. YES No No No 13 DISK_CONTENTS_ PENDING Upload initiated , disk contents pending.
Chapter 12 XML Representations in the vCloud API Procedure 1 Retrieve the current Session object to get the entityResolver URL. Use a request like this one: GET https://vcloud.example.com/api/session The response is a Session element like the one shown in “Example: Create a Login Session Using the Integrated Identity Provider,” on page 45. The Session element contains the entityResolver URL in the href of the Link element in this excerpt. ...
vCloud API Programming Guide 364 VMware, Inc.
Index A access control 84 access rights 87 administrative tasks, about 149 administrator, system 152 AMQP about 307 certificate and truststore 275 AMQP settings to test 310 to configure 308 API client, to develop 21 attributes custom 124 name 360 status 360 B blocking task, to configure 307 blocking task requests, to monitor 324 blocking task settings, to configure 318 browsing 41 C catalog change owner 83 controlling access to 84 for external publication 201 removing items 79 storage profile for 205 sub
vCloud API Programming Guide resource classes 343 REST APIs for 353 to register 330, 332 to retrieve list of 330 to unregister 330 URL patterns for 354 external network to retrieve or update 235 to create 261 F firewall service and syslog 196 in Edge Gateway 179 in vApp network 131 G group to create, update, or remove 149 to import 223 to import from SAML 225 groups, to administer 219 H host to update or repair 235 to enable or disable 235 I id attribute, and entity resolver 362 independent disk about
Index object identifiers 12 object references, about 12 organization retrieve or update settings 157 system 152 to create, update, or remove 149 to retrieve administrative view of 149 to administer 153 to create 153 to enable or disable 149, 160 to remove 160 organization VDC network about 169 direct 188 isolated 194 routed 191 to administer 169 to configure static routes 182 to create 187 to create, update, or remove 149 organizations federation of 157 to list 41, 49 OVF, to instantiate 97 OVF descriptor
vCloud API Programming Guide to retrieve list from vCenter 249 to refresh list of 249 system settings, to retrieve or update 239 T task blocking 325 service-specific 340 to cancel 149 to retrieve 149 update progress 327 task list, to retrieve 149 task operations 320 timezone, in dateTime values 357 truststore, to upload 275 U user list of rights granted 149 to import from SAML 225 to retrieve 149 to update or remove 149 to create 149, 220 to import 222 users, to administer 219 V vApp access control for
Index to create, update, or remove 149 to add or remove storage profiles 166 to administer 160 to create 161 to enable or disable 149, 168 to find 26 to remove 168 to retrieve 41 virtual hardware, vmx versions supported by Provider VDC 251 virtual machine available for import 247 CPU configuration 136 disks 142 guest customization for 137 hard disk configuration 143 importing 271 importing from vCenter 270 network cards 142 question from 111 to update NetworkConnectionSection 134 to update storage profile
vCloud API Programming Guide 370 VMware, Inc.
