vCloud API Programming Guide vCloud API 1.0 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, 2011 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws.
Contents About This Book 11 1 Introducing the VMware vCloud API 13 vCloud Object Taxonomy 13 vCloud Organizations 13 Objects, References, and Representations 15 Links and Link Relations 15 vCloud Client Workflow Overview 17 Requests 17 Responses 18 Configuring the vCloud API URL 19 Related Publications 19 About the Examples 19 2 Hello vCloud: A Structured REST Workflow Example 21 Logging In and Getting an Organization List Browsing an Organization 22 Finding a vApp Template 23 Getting Information About
vCloud API Programming Guide Restrictions on Uploaded Content 43 Initiate the Upload 43 Including a Manifest 45 Uploading the Files 45 View the OVF Descriptor of a vApp Template 47 Download a vApp Template as OVF 47 Enable a vApp Template for Download 48 Disable a vApp Template for Download 49 Upload a Media Image 50 Copying and Moving 50 Copy or Move a Media Image 51 Copy or Move a vApp Template 51 Copy or Move a vApp 52 Changing a Name or Description 53 Change the Name or Description of a vAppTemplate 53
Contents Get a Screen Ticket for a Virtual Machine 87 Provide User Input Requested by a Virtual Machine 87 Control Access to vApps 89 Retrieve a Task 89 6 Administrative Operations 91 Summary of Administrative Requests 91 Administrator Credentials and Privileges 93 Administrative Objects and URLs 93 Get an Administrative View of a Cloud 93 Organization Administration 94 Create an Organization 95 Get an Administrative View of an Organization 96 List All Tasks Owned by an Organization 97 Modify an Organizat
vCloud API Programming Guide 7 VMware vSphere Platform Operations 117 Summary of vSphere Platform Operations Requests 117 List vSphere Platform Operations and Objects for a vCloud 119 List Provider vDCs in a vCloud 120 List External Networks in a vCloud 120 List Network Pools in a vCloud 120 List vCenter Servers Registered to a vCloud 120 Get Information About a vCenter Server 120 List Available Resource Pools on a vCenter Server 121 Modify vCenter Server Settings 122 Register a vCenter Server and vShield
Contents Link 147 API Versioning 147 SupportedVersions 148 VersionInfo 148 Extensibility 148 VCloudExtension 149 9 User API Reference 151 OrgList 151 Org 151 Vdc 152 StorageCapacity 153 ComputeCapacity 153 AvailableNetworks 153 ResourceEntities 154 ResourceEntity 154 OrgNetwork 154 Configuration 155 Catalog 160 CatalogItems 160 CatalogItem 160 Media 161 VAppTemplate 161 Children 162 VApp 162 Vm 163 Section 163 LeaseSettingsSection 164 StartupSection 164 CustomizationSection 164 NetworkConfigSection 165 Ne
vCloud API Programming Guide CloneVAppParams 176 MediaInsertOrEjectParams 177 VmPendingQuestion 177 VmQuestionAnswer 177 ControlAccessParams 177 AccessSettings 178 11 Administrative API Reference 179 VCloud 179 OrganizationReferences ProviderVdcReferences RightReferences 180 RoleReferences 180 Networks 180 ExternalNetwork 180 AdminOrg 180 Settings 181 Users 185 Groups 185 Catalogs 185 Catalog 186 Vdcs 186 ProviderVdc 186 ComputeCapacity 187 StorageCapacity 188 NetworkPoolReferences NetworkPoolReference Vd
Contents VMWExternalNetwork 199 VlanRange 199 VMWHostReferences 199 Host 199 Request Parameters 200 PrepareHostParams 200 RegisterVimServerParams 200 ImportVmAsVAppParams 201 ImportVmAsVAppTemplateParams 201 A OVF and the vCloud API 203 About OVF 203 About OVF Packages 204 About OVA Files 204 How the vCloud API Uses OVF 204 Virtual Machines 204 Virtual Disk Files 205 Networks 205 B An Introduction to REST for vCloud API Users 207 How REST Works 207 Using the vCloud REST API 207 RESTful Workflow Patterns
vCloud API Programming Guide 10 VMware, Inc.
About This Book The vCloud API Programming Guide provides information about version 1.0 of the vCloud API. VMware provides many different APIs and SDKs for various applications and goals. This book provides information about the vCloud API for developers that are interested in creating RESTful clients of VMware Cloud Director. To view the current version of this book as well as all VMware API and SDK documentation, go to http://www.vmware.com/support/pubs/sdk_pubs.html.
vCloud API Programming Guide Technical Support and Education Resources The following sections describe the technical support resources available to you. To access the current versions of other VMware books, go to http://www.vmware.com/support/pubs. Online and Telephone Support To use online support to submit technical support requests, view your product and contract information, and register your products, go to http://www.vmware.com/support.
1 Introducing the VMware vCloud API 1 The VMware vCloud API provides support for developers who are building interactive clients of VMware Cloud Director using a RESTful application development style. vCloud API clients and servers communicate over HTTP, exchanging representations of vCloud objects. These representations take the form of XML elements.
vCloud API Programming Guide Figure 1-1. vCloud Object Taxonomy Organization vDC1 Catalog 3 vApp template vApp Catalogitem em Catalog 2 em em Catalogitem em Catalog 1 em em Catalogitem Catalogitem Catalogitem Catalogitem Media Media vDC2 vApp template vApp Media Media Network Network users groups TasksList vCloud Virtual Datacenters A vCloud virtual datacenter (vDC) is an allocation mechanism for resources such as networks, storage, CPU, and memory.
Chapter 1 Introducing the VMware vCloud API Virtual Systems and Media Images in a vCloud Virtual systems and media images are stored in a vDC and can be included in a catalog. Media images are stored in their native representation (ISO or floppy). Virtual systems are stored as templates, using an open standard format (OVF 1.0).
vCloud API Programming Guide Table 1-1.
Chapter 1 Introducing the VMware vCloud API Links provide a way for the server to inform a client about object relationships and the operations that objects support. For example, a container such as an organization or catalog can return links to the objects it contains, and a virtual system (a vApp or Vm) can contain action links that enable operations such as power state changes or virtual device reconfiguration.
vCloud API Programming Guide All required elements must appear in request bodies. All elements that appear in request bodies must appear in the order established by the schema, and with content that conforms to the type constraint specified in the schema. See “Schema Validation” on page 142. Authentication HTTP communications between a vCloud client and server are typically secured with SSL.
Chapter 1 Introducing the VMware vCloud API Table 1-2. HTTP Status Codes Returned by the vCloud API (Continued) Status Code Status Description 401 Unauthorized An authorization header was expected but not found. 403 Forbidden The requesting user does not have adequate privileges to access one or more objects specified in the request. 404 Not Found One or more objects specified in the request could not be found in the specified container.
vCloud API Programming Guide 20 VMware, Inc.
2 Hello vCloud: A Structured REST Workflow Example 2 This chapter presents a simple example of a structured REST workflow for discovering and deploying a particular vApp (in this case, an FTP server with a connection to the public Internet).
vCloud API Programming Guide The response includes an authentication token supplied in the x-vcloud-authorization header, and a list of the organizations to which the authenticated user has access. Each Org has a URL (in its href attribute value) that the client can use to get more information about objects that the organization contains. For more information about authentication, see “Authentication” on page 18.
Chapter 2 Hello vCloud: A Structured REST Workflow Example Finding a vApp Template The client can use the catalog URL shown in Example 2‐2 as the target of a GET request that returns the contents of the catalog, as shown in Example 2‐3. Example 2-3. Finding a vApp Template in a Catalog Request: GET http://vcloud.example.com/api/v1.0/catalog/32 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.catalog+xml ... PAGE 24vCloud API Programming Guide Getting Information About a vDC Instantiation, deployment, and operation of a vApp all take place in the context of a vDC. The XML representation of a vDC object defines that context in detail. For this exercise, you need only two pieces of information from the vDC: The URL that a client can use to request an instantiateVAppTemplate operation in the vDC A list of networks to which the vApp can connect. Example 2‐5 shows this subset of vDC contents.
Chapter 2 Hello vCloud: A Structured REST Workflow Example Creation parameters for a vApp network. A vApp network defines how the vApp connects to an organization network available in the target vDC. For more information, see “About vApp Networks” on page 62. The instantiateVAppTemplate request in Example 2‐6 supplies these parameters in the following places: The name is supplied in the name attribute of the InstantiateVAppTemplateParams request.
vCloud API Programming Guide PAGE 27Chapter 2 Hello vCloud: A Structured REST Workflow Example Because the deployment request specified powerOn="true", the vApp is powered on and ready for use when the task completes. The client can wait for a suitable interval and check the task status (see “Retrieve a Task” on page 89), or simply begin requesting operations on the powered‐on vApp and checking the task status if those requests fail. See “Deploying and Controlling vApps and Virtual Machines” on page 80.
vCloud API Programming Guide PAGE 29Chapter 2 Hello vCloud: A Structured REST Workflow Example 10.147.122.134 true 00:50:56:01:01:49 ... ... ...
vCloud API Programming Guide Use the Ticket with vmware-vmrc The vmware-vmrc plug‐in is installed by your browser whenever you use the Cloud Director Web Console to access the console of a running virtual machine. After this plug‐in has been installed, you can find it in the folder that your browser uses for plug‐ins. NOTE The version of vmware-vmrc included with Cloud Director cannot be used to access virtual machines in vCenter.
Chapter 2 Hello vCloud: A Structured REST Workflow Example Moving on to Additional Use Cases This “Hello” exercise, while simplified, demonstrates a pattern common to many vCloud API use cases: browsing to discover a template, instantiating the template, then deploying and operating the vApp described in the template.
vCloud API Programming Guide 32 VMware, Inc.
3 3 Browsing A vCloud API client can use HTTP GET requests to browse containers such as organizations, catalogs, and vDCs. 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 Discovering the Contents of an Organization, Catalog, or vDC The vCloud API defines three principal containers: organizations, catalogs, and vDCs. A client can use an HTTP GET request to discover the contents of any of them. List the Organizations in a vCloud The response to a login request includes a list of the organizations to which the authenticated user has access.
Chapter 3 Browsing PAGE 36
vCloud API Programming Guide This response body includes: A Link element that references the organization that contains this catalog: A Link element that you can use to add an item to the catalog: Several CatalogItem elements.
Chapter 3 Browsing List the Contents of a vDC The response in Example 3‐1 also contains several Vdc elements, each of which represents a vDC object. Example 3‐4 shows a request to browse one of those vDCs and shows a subset of the response. Example 3-4. List the Contents of a vDC Request: GET http://vcloud.example.com/api/v1.0/vdc/5 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.vdc+xml ... PAGE 38vCloud API Programming Guide ... PAGE 39Chapter 3 Browsing Example 3-5. Get Information About a Media Image Request: GET http://vcloud.example.com/api/v1.0/media/254 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.media+xml ... PAGE 40vCloud API Programming Guide Get Information About a vApp or Virtual Machine Catalogs cannot contain references to vApps or the virtual machines (Vm objects) that they contain. A client can discover the URL of a vApp by browsing in a vDC for a ResourceEntity element that references it. After client has the template’s URL, it can use it as the target of a GET request, as shown in Example 2‐8 on page 39 to retrieve the vApp representation and the Vm elements it contains.
4 4 Provisioning The vCloud API supports upload and download of OVF packages, and upload of media images. Transfer operations are characterized as uploads when the operation transfers content from the local host to a remote one, and as downloads when the local host requests the transfer of content from a remote host. Uploads are typically initiated by a POST request, and downloads by a GET request.
vCloud API Programming Guide Table 4-1.
Chapter 4 Provisioning Both monolithic and ranged (chunked) PUTs are supported. After starting an upload, a client can make periodic requests to determine its progress. After all the files are uploaded (and validated if a manifest is present), the server processes the uploads. When processing is complete, the server sets the value of the template’s status attribute to 8, indicating that the template is ready for use.
vCloud API Programming Guide The response body includes the following attributes: An href attribute whose value is a link to the newly created vApp template object. An ovfDescriptorUploaded attribute with a value of false, indicating that the OVF descriptor file has not yet been uploaded A status attribute with a value of 0, indicating that the file references in the descriptor have not yet been uploaded. (A VAppTemplate with a status of 0 is said to be unresolved.
Chapter 4 Provisioning In this example, the ovfDescriptorUploaded attribute has a value of true and the status attribute has a value of 0. If the descriptor fails validation, the status is set to ‐1, and the template contains a Task element whose Error element indicates the reason for the failure.
vCloud API Programming Guide Example 4-6. Uploading File Data Request: PUT http://vcloud.example.com/transfer/.../disk0.vmdk Content-length: 1950489088 ...serialized contents of file disk0.vmdk... EOF Response: 200 OK To monitor the progress of an upload, a client can use an HTTP GET request specifying the VAppTemplate URL that was returned in the upload map. The response is the same upload map.
Chapter 4 Provisioning Response: 200 OK View the OVF Descriptor of a vApp Template The representation of a resolved vApp template includes a link to its OVF descriptor. A GET request specifying the URL in the href value of this Link returns the descriptor, as shown in Example 4‐9. Only resolved VAppTemplate elements include this link.
vCloud API Programming Guide Enable a vApp Template for Download A vApp template must be explicitly enabled for download by an administrator or privileged user. Example 4‐10 shows such a request. The response is a Task element. The time required for the task to complete is determined by the number and size of the files comprising the template. Example 4-10. Enable a vApp Template for Download Request: POST http://vcloud.example.com/api/v1.
Chapter 4 Provisioning ... In this example, the descriptor references only one file: PAGE 50vCloud API Programming Guide After the disableDownload request completes, the template’s files are removed from the transfer server, and the Link element that contains the download:default URL no longer appears in the vAppTemplate body. Upload a Media Image The vCloud API supports uploading virtual media such as CD‐ROM and floppy disk images.
Chapter 4 Provisioning When you move an object by copying it and deleting its source, an intermediate object is created in the target vDC, as part of the following sequence of events. 1 The source object is coped to an intermediate object whose name is a combination of the object name and a UUID. 2 The source object is deleted. 3 The intermediate object is renamed with the name specified for the target object in the copy request.
vCloud API Programming Guide Example 4-18. Move a vAppTemplate Request: POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVAppTemplate Content-Type: application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml true Response: 201 Created Content-Type: application/vnd.vmware.
Chapter 4 Provisioning Response: 201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml Cloned from Ubuntu FTP Server ... ...
vCloud API Programming Guide Change the Name or Description of a Media Image Example 4‐21 changes the description of a media image that was created by the copy operation in Example 4‐17. Example 4-21. Change the Description of a Media Image Request: PUT http://vcloud.example.com/api/v1.0/media/277 Content-Type: application/vnd.vmware.vcloud.media+xml ... PAGE 55Chapter 4 Provisioning To add an item to a catalog 1 Browse the vDCs in an organization to find ResourceEntity elements that reference the item you want to add to the catalog. 2 Create a CatalogItem element that contains a reference to the item. Example 3‐4 on page 37 lists a number of ResourceEntity elements in a vDC. To create a CatalogItem that references this one: PAGE 56vCloud API Programming Guide Remove an Item from a Catalog A organization administrator or a user with adequate permissions can remove a CatalogItem by making a DELETE request to the its rel="remove" link. Example 4‐23 removes the CatalogItem created in Example 4‐22. Example 4-23. Remove a CatalogItem Request: DELETE http://vcloud.example.com/api/v1.
Chapter 4 Provisioning Example 4-25. Viewing Access Control Settings for a Catalog Request: GET http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/ Response: 200 OK Content-Type: application/vnd.vmware.vcloud.controlAccess+xml ... false Because the value of IsSharedToEveryone is false, the administrator must grant access to individual users or groups, specified by reference.
vCloud API Programming Guide To specify global 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, as shown in Example 4‐27. Example 4-27. Granting Catalog Access to Everyone Request: POST http://vcloud.example.com/api/v1.0/catalog/32/controlAccess Content-Type: application/vnd.vmware.vcloud.controlAccess+xml ... PAGE 595 5 Datacenter Operations The vCloud API supports programmatic access to a range of self‐service datacenter operations that allow users to create, configure, operate, and connect to vApps.
vCloud API Programming Guide Table 5-1.
Chapter 5 Datacenter Operations An undeployed vApp, created when a vApp template is instantiated or a deployed vApp is undeployed. A deployed vApp, ready to be powered on and operated. You can specify that instantiation include deployment, power‐on, or both. Figure 5‐1 illustrates these state transitions. Figure 5-1. vApp State Transitions OVF package descriptor.ovf disk0.vmdk upload vApp template ... ...
vCloud API Programming Guide About Instantiation Parameters Instantiation parameters allow you to specify certain properties of a vApp, including: Details of its vApp network (required).
Chapter 5 Datacenter Operations Examine the template’s ovf:NetworkSection element to see whether any networks are defined there. If the vApp template includes an ovf:Network element, the name you specify for the vApp network must match the name specified in that element’s ovf:name attribute. See “About Instantiation Parameters” on page 62. Verify that your organization’s default lease settings are appropriate for this vApp.
vCloud API Programming Guide The response is a sparsely populated vApp body that contains a Task element The status of the vApp is initially 0. When instantiation is complete and the vApp is powered on, the Task no longer appears in the vApp body, and the vApp status changes to 4, indicating that all of its children are powered on. You can check the status of the task by issuing a GET request to the task URL or you can check the status of the vApp by issuing a GET request to the vApp URL.
Chapter 5 Datacenter Operations Compose a vApp The vCloud API supports composing a vApp from any combination of vApp templates, vApps, or virtual machines. When you compose a vApp, all children of each composition source become peers in the Children collection of the composed vApp.
vCloud API Programming Guide -
-
true Response: 201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... PAGE 67Chapter 5 Datacenter Operations Recompose a vApp to Add or Remove Virtual Machines The vCloud API supports recomposition of a vApp to add or remove virtual machines (Vm elements). To recompose a vApp, a client makes a recomposeVApp request, supplying a RecomposeVAppParams element as the request body. The RecomposeVAppParams element allows an arbitrary number of DeleteItem elements, but is otherwise identical to ComposeVAppParams.
vCloud API Programming Guide VApp startup section true PAGE 69Chapter 5 Datacenter Operations Reconfiguring vApps and Virtual Machines Configuration details for vApps and the virtual machines they contain are specified in ovf:SectionType elements such as LeaseSettingsSection, NetworkConfigSection, and OperatingSystemSection. These sections can be specified in the InstantiationParams for the vApp or Vm, and can also be edited in place using reconfiguration links (Link elements where rel="edit") that the server adds to these sections during instantiation.
vCloud API Programming Guide Example 5-9. Configuration Links for a vApp Request: GET http://vcloud.example.com/api/v1.0/vApp/vapp-7 Response: 200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... Example FTP Server ... PAGE 71Chapter 5 Datacenter Operations To modify a section 1 Retrieve the vApp or vApp template and examine the response to find the section that you want to modify. 2 Retrieve the section by making a GET request to the section’s edit link (a Link element in the section where rel="edit"). 3 Modify the section as needed. 4 PUT the modified section to the section’s edit link. Note that section edit URLs, unlike most other URLs presented by the vCloud API, end with a / character.
vCloud API Programming Guide A set of FirewallRules that allow TCP traffic to ports 21 and 22. Because these rules require you to specify a single IP address on the inside of the firewall, the IpScope element is modified to limit the range of IP addresses available on the vApp network to a single address. Any Vm that connects to the vApp network defined in this NetworkConfigSection is given this address.
Chapter 5 Datacenter Operations 10.147.115.1 true SSH Rule allow true 22 10.147.115.1 true ipTranslation allowTraffic manual 64.
vCloud API Programming Guide Table 5-3.
Chapter 5 Datacenter Operations Example 5‐12 shows a representative collection of these links. (This example does not show the configuration links for the parent vApp. To see them, refer to Example 5‐9 on page 70.) Example 5-12. Configuration Links for a Vm Request: GET http://vcloud.example.com/api/v1.0/vApp/vapp-7 Response: 200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ...
vCloud API Programming Guide ... PAGE 77
Chapter 5 Datacenter Operations Reconfiguration links in the body of a Vm can appear in two places: Individual Link elements in the ovf:Item elements defining cpu and memory. These links appear in the ovf:Item itself, and have type="application/vnd.vmware.vcloud.rasdItem+xml". Links to groups of related ovf:Item elements (disks, network cards, and media devices). These links appear at the end of the ovf:VirtualHardwareSection, and have type="application/vnd.vmware.vcloud.rasdItemsList+xml".
vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Retrieve or Modify the CPU Configuration of a Virtual Machine Example 5‐15 retrieves the CPU configuration of the Vm shown in Example 5‐12. Example 5‐16 modifies the section and uses the URL in the edit link from that section to apply the changes to the Vm. Example 5-15.
Chapter 5 Datacenter Operations Retrieve or Modify the Guest Customization Section of a Virtual Machine Example 5‐17 retrieves the GuestCustomizationSection of a Windows Vm. Example 5‐18 modifies the section and uses the URL in the edit link from that section to apply the changes to the Vm. Example 5-17. Retrieve the Guest Customization Section of a Virtual Machine Request: GET http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection Response: 200 OK Content-type: application/vnd.vmware.
vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ...
Chapter 5 Datacenter Operations Example 5-19. Deploy and Power On a vApp or Virtual Machine Request: POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deploy Content-type: application/vnd.vmware.vcloud.deployVAppParams+xml ... Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... PAGE 82vCloud API Programming Guide A powerOn request to a vApp or virtual machine that is undeployed forces deployment. Example 5-21. Power On a vApp or Virtual Machine Request to power on a vApp: POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOn Request to power on a virtual machine: POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOn Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ...
Chapter 5 Datacenter Operations Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Suspend a vApp or Virtual Machine A suspend request to a vApp URL suspends all of the virtual machines in the vApp, as specified in its ovf:StartupSection element. A suspend request to a virtual machine URL suspends the specified virtual machine. Example 5-24. Suspend a vApp or Virtual Machine Request to suspend a vApp: POST http://vcloud.example.com/api/v1.
vCloud API Programming Guide Shut Down a vApp or Virtual Machine A shutdown request to a vApp URL shuts down all of the virtual machines in the vApp, as specified in its ovf:StartupSection element. A shutdown request to a virtual machine URL shuts down the specified virtual machine. NOTE Because this request sends a signal to the guest OS, the vCloud API cannot track the progress or verify the result of the requested operation. Example 5-26.
Chapter 5 Datacenter Operations List Media Devices of a Virtual Machine You can make a GET request to the media URL of a Vm to return a list of all media devices attached to it. Example 5-28. List Media Devices Attached to a Vm Request: GET http://vcloud.example.com/api/v1.0/vapp/vm-5/virtualHardwareSection/media Response: 200 OK Content-Type: application/vnd.vmware.vcloud.rasditemslist+xml ... PAGE 86vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Eject Media from a Virtual Machine An ejectMedia request reverses a specific insertMedia request. The request must specify the ejectMedia URL of a Vm that was previously the target of an insertMedia request. The Media element in the request body must specify the href of the media image that was inserted by that request. Example 5-30.
Chapter 5 Datacenter Operations Get a Screen Ticket for a Virtual Machine An acquireTicket request returns a ticket that a client can use to gain access to the console of a virtual machine. Example 5-32. Get a Screen Ticket for a Virtual Machine Request: POST http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/action/acquireTicket Response: 200 OK Content-Type: application/vnd.vmware.vcloud.screenTicket+xml ... PAGE 88vCloud API Programming Guide Get a Request for User Input In Example 5‐34, the client uses the vmPendingQuestion link returned in Example 5‐33 to get a VmPendingQuestion document that includes the question and the set of choices allowed in the response. Example 5-34. Get a Vm Pending Question Request: GET http://vcloud.example.com/api/v1.0/vApp/vm-5/question Response: 200 OK Content-type: application/vnd.vmware.vcloud.vmPendingQuestion+xml ...
Chapter 5 Datacenter Operations Control Access to vApps Access control links for vApps are included in the vApp body. Example 5‐36, an excerpt from Example 2‐8 on page 27, shows these links. Example 5-36. Access Control Links for a vApp ... ...
vCloud API Programming Guide 90 VMware, Inc.
6 6 Administrative Operations The VMware vCloud API supports a variety of objects and operations that an organization administrator or other privileged user can use to automate tasks associated with provisioning organizations and users, and with allocation of resources to organization vDCs.
vCloud API Programming Guide Table 6-1.
Chapter 6 Administrative Operations Administrator Credentials and Privileges The vCloud API defines two levels of administrative privilege: Organization administrators, who have administrative privileges in a specific organization. System administrators, who have superuser privileges throughout the system.
vCloud API Programming Guide Example 6-2. List the Top-Level Administrative Objects in a vCloud Request: GET http://vcloud.example.com/api/v1.0/admin Response: 200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml ... PAGE 95Chapter 6 Administrative Operations Create an Organization To create an organization, a system administrator POSTs an AdminOrg body to the vCloud’s orgs URL, as shown in Example 6‐3. The response echoes the request, with several important additions: It includes both the administrative and user URLs for the new organization. The administrative URL is the value of the href element of the AdminOrg body, and the user URL is the value of the Link where rel="alternate".
vCloud API Programming Guide PAGE 97
Chapter 6 Administrative Operations Finance ... ... List All Tasks Owned by an Organization An administrative view of an organization includes a Link with a rel="down" attribute that the administrator can use to retrieve a list of all tasks owned by a user or object in an organization. The request in Example 6‐5 uses the tasksList URL returned in Example 6‐4 to return a TasksList element that contains several Task elements. Example 6-5.
vCloud API Programming Guide Example 6-6. Modify an Organization Request: PUT http://vcloud.example.com/api/v1.0/admin/org/26 Content-Type: application/vnd.vmware.admin.organization+xml ... PAGE 99Chapter 6 Administrative Operations Remove an Organization An organization administrator can use the remove link in an AdminOrg body to remove the organization from the vCloud. Example 6‐8 does this, making a DELETE request to the remove link returned in Example 6‐4. NOTE Before you can remove an organization, you must disable it and delete or change ownership of all objects that the organization users own. Example 6-8. Remove an Organization Request: DELETE http://vcloud.example.com/api/v1.
vCloud API Programming Guide Add a Network to an Organization An administrator can use the rel="add" link for networks in an AdminOrg body to add a network to the organization. Example 6‐10 does this by making a POST request to the networks link returned in Example 6‐4. The content of the FenceMode element in the request body specifies that organization network is bridged to its ParentNetwork, whose href value was retrieved from one of the Network elements in the response in Example 6‐2.
Chapter 6 Administrative Operations bridged The response echoes the request, and contains some additional elements: A Task that tracks creation of the network.
vCloud API Programming Guide false 3600 7200 10.6.35.3 10.6.255.
Chapter 6 Administrative Operations Examine the Contents of a Provider vDC ProviderVdc objects are listed among the top‐level objects in a vCloud. in Example 6‐2 on page 94 illustrates such a listing, which includes a ProviderVdcReferences element that contains references to the provider vDCs registered to this vCloud. PAGE 104vCloud API Programming Guide List the Organization vDCs Supported by a Provider vDC An administrator can use the href value from any ProviderVdcReference element in a VCloud as the target of a request that returns a list of organization vDCs that the provider vDC supports.
Chapter 6 Administrative Operations MHz 2048 2048 MB 2048 2048 0 0 Response: 201 Created Content-Type: application/vnd.vmware.admin.
vCloud API Programming Guide The response echoes the request, and includes a Task element that tracks creation of the vDC. The network created in Example 6‐10 appears in the AvailableNetworks element. If you added more networks to the organization that contains this vDC, they would also appear in that element. Get an Administrative View of a vDC References to an organization’s vDCs are contained in the Vdcs element of the Org or AdminOrg body.
Chapter 6 Administrative Operations MHz 4096 4096 ... ... Enable or Disable a vDC An administrator can use the enable or disable action links in an AdminVdc body to enable or disable a vDC. The request and response are similar to those shown in Example 6‐7 on page 98. The enablement state of the vDC is shown in its IsEnabled element.
vCloud API Programming Guide A Task that tracks the creation of the catalog An IsPublished element whose content is the string false. Example 6-19. Create a Catalog Request: POST http://vcloud.example.com/api/v1.0/admin/org/26/catalogs Content-Type: application/vnd.vmware.admin.catalog+xml Custom Catalog Response: 201 Created Content-Type: application/vnd.vmware.admin.catalog+xml ...
Chapter 6 Administrative Operations Custom Catalog ... ... Publish a Catalog Publishing a catalog makes the catalog visible to all organizations in a vCloud.
vCloud API Programming Guide Approved template for public FTP sites Tech Ops NOTE Modifying catalog metadata does not affect CatalogItem elements.
Chapter 6 Administrative Operations Response: 201 Created Content-Type: application/vnd.vmware.admin.user+xml ... Example User Full Name user@example.
vCloud API Programming Guide FullName and EmailAddress are retrieved from LDAP. Values for IsEnabled, Description, and other elements can be specified in the request body or add later. See “Modify User Metadata” on page 112. Get an Administrative View of a User Each user in an organization is represented by a UserReference element. A GET request to the URL in the href attribute of a UserReference returns a User element in the response, as shown in Example 6‐26. Example 6-26.
Chapter 6 Administrative Operations Response: 200 OK Content-Type: application/vnd.vmware.admin.user+xml ... PAGE 114vCloud API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.admin.user+xml ... Research and development ...
Chapter 6 Administrative Operations Example 6-31. Create a Role Request: POST http://vcloud.example.com/api/v1.0/admin/roles Content-Type: application/vnd.vmware.admin.role+xml Create and manage vApps PAGE 116vCloud API Programming Guide Create and manage vApps PAGE 1177 VMware vSphere Platform Operations 7 The VMware vCloud API includes extensions that support a variety of operations on the vSphere Platform, which provides resources to a VMware vCloud. NOTE All vSphere platform operations are restricted to the system administrator. Before attempting any of these operations, log in to the System organization with the user name and password of the system administrator account that was created when Cloud Director was installed.
vCloud API Programming Guide Table 7-1.
Chapter 7 VMware vSphere Platform Operations Table 7-1.
vCloud API Programming Guide PAGE 121Chapter 7 VMware vSphere Platform Operations Example 7-3. Get Information About a vCenter Server Request: GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100 Response: 200 OK Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml ... PAGE 122vCloud API Programming Guide RESOURCE_POOL datastore-10 DATASTORE datastore-11 DATASTORE datastore-12 DATASTORE
Chapter 7 VMware vSphere Platform Operations Example 7-6. Register a vCenter Server and vShield Manager Request: POST http://vcloud.example.com/api/v1.0/admin/extension/action/registervimserver Content-Type: application/vnd.vmware.admin.registerVimServerParams+xml ... PAGE 124vCloud API Programming Guide Example 7-7. Unregister a vCenter Server and vShield Manager Request: POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/unregister Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ...
Chapter 7 VMware vSphere Platform Operations Example 7-10. Get Information About a Host Request: GET http://vcloud.example.com/api/v1.0/admin/extension/host/22 Response: 200 OK Content-Type: application/vnd.vmware.admin.host+xml ... PAGE 126vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Unprepare a Host Unprepare a host to make it unavailable for use in the Cloud Director environment. A system administrator can unprepare a host by making a POST request to the host’s action/unprepare URL. Example 7‐12 unprepares the host reference by http://vcloud.example.com/api/v1.0/admin/extension/host/1. Example 7-12.
Chapter 7 VMware vSphere Platform Operations Example 7-14. Repair a Host Request: POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/repair Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Upgrade a Host Agent New releases of vCenter Cloud Director may include a new version of the host agent.
vCloud API Programming Guide Example 7-16. VimServer Element Request: GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101 Response: 200 OK Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml ... PAGE 129Chapter 7 VMware vSphere Platform Operations datastore-322 DATASTORE datastore-350 DATASTORE You can use this information to get values for the DataStoreRefs and ResourcePoolRef elements in the VMWProviderVdc, then POST the VMWProvide
vCloud API Programming Guide ... PAGE 131Chapter 7 VMware vSphere Platform Operations resgroup-220 RESOURCE_POOL PAGE 132vCloud API Programming Guide MB 18944 2260224 PAGE 133Chapter 7 VMware vSphere Platform Operations Example 7-21. Remove a vDC Request: DELETE http://vcloud.example.com/api/v1.0/admin/extension/providervdc/43 Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Create an External Network A system administrator can use the rel="add" link for externalnets in a VMWExtension element to add an external network to a vCloud.
vCloud API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... PAGE 135Chapter 7 VMware vSphere Platform Operations Modify an External Network To modify an external network, make a PUT request to its edit link, and supply a modified version of the VMWExternalNetwork element in the request body. In Example 7‐24, the client modifies the IpRange EndAddress of the external network created in Example 7‐22, then includes the modified body in a PUT request to the edit link that was returned when the external network was created. Example 7-24.
vCloud API Programming Guide Example 7-25. Remove an External Network Request: DELETE http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27 Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Create a Network Pool A system administrator can use the rel="add" link for networkPools in a VMWExtension body to add a network pool to a vCloud.
Chapter 7 VMware vSphere Platform Operations PAGE 138vCloud API Programming Guide Response: 200 OK ... ... The response, most of which is not shown here, echoes the request. Remove a Network Pool To remove a network pool, a system administrator can make a DELETE request to its href attribute value. The response contains a Task that tracks the delete operation.
Chapter 7 VMware vSphere Platform Operations Because the list of virtual machines registered to a vCenter server can be very long, responses to a GET .../vmslist request present the list as a series of pages. The default page size is 100 VmObjectRef elements, each representing a single virtual machine. The default response to a GET .../vmslist request returns the first page of the list. You can add query parameters to the request to specify a page size and a page number.
vCloud API Programming Guide Import a Virtual Machine as a vApp Template The workflow to import a virtual machine as a vApp template is similar. As shown in Example 7‐33, the request URL is the importVmAsVAppTemplate link in the VimServer response body. The request body is an ImportVmAsVAppTemplateParams element that can contain an optional reference to a catalog in which the template will be entered after the import is complete.
8 8 XML Representations in the vCloud API The vCloud API represents objects in a vCloud 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. This chapter provides reference information about how the vCloud API uses XML to represent vCloud objects.
vCloud API Programming Guide NOTE In the reference material, elements that are simply containers are listed by name, along with an explanation of the purpose of the container, but do not include a schema reference. Schema Validation This release of Cloud Director uses a validating XML parser that requires elements in XML documents to agree in both order and number with the schema. Required elements must appear in request bodies.
Chapter 8 XML Representations in the vCloud API Table 8-2. Primitive XML Data Types Used by the vCloud API (Continued) Value Description xs:long Numeric value in the range ‐9223372036854775808 to 9223372036854775807. xs:int Numeric value in the range ‐2147483648 to 2147483647. xs:string Any character data. Complex Types XML elements defined by the vCloud API are instances of complex types.
vCloud API Programming Guide name Every object requires a name attribute whose string value provides the display name for the object. The value of name must be unique within a given scope, as shown in Table 8‐3. Table 8-3.
Chapter 8 XML Representations in the vCloud API Table 8-4. vAppTemplate, vApp, and Vm status Attribute Values (Continued) Value Description vAppTemplate vApp † Vm 8 The object is powered off. YES YES YES 9 The object is in an inconsistent state. No YES YES 10 Children do not all have the same status.
vCloud API Programming Guide XML Namespace Prefixes in Request and Response Bodies When a request or response includes elements from multiple XML namespaces, each element name is prefixed with a namespace identifier. Unless all elements in a request or response originate in the same XML namespace, these prefixes are required in request bodies, and are always included in response bodies. Example 5‐16 on page 78 and Example 7‐22 on page 133 show how namespace prefixes appear in element names.
Chapter 8 XML Representations in the vCloud API Table 8-6. Minor Error Codes (Continued) Error Code Description of Error UNKNOWN The request raised an exception that did not match any HTTP status code. UNSUPPORTED_MEDIA_TYPE The wrong content type was specified for the request. Link A Link element defines a hyperlink with a relationship, URI, and an optional name and media type.
vCloud API Programming Guide application/vnd.vmware.vcloud.vdc+xml CatalogItemType http://vcloud.example.com/api/v1.0/schema/master.xsd ... SupportedVersions A SupportedVersions element is a container for VersionInfo elements.
Chapter 8 XML Representations in the vCloud API This extensibility mechanism, which is not used in this release of the vCloud API, allows new servers to extend the XML representations native to this release of the vCloud API without requiring existing clients to understand those extensions. VCloudExtension A client should be prepared to encounter a VCloudExtension element in any response.
vCloud API Programming Guide 150 VMware, Inc.
9 User API Reference 9 This chapter provides reference information about the XML elements that represent the object model defined for general use in this release of the vCloud API. Elements documented in this chapter are typically readable by all users, and can be modified by users with appropriate rights. For more information about how the vCloud API uses XML to represent objects, and how this reference material is organized, see “XML Representations in the vCloud API” on page 141.
vCloud API Programming Guide Object href prototype API‐URL/org/id Schema Name Min Max Type Description name 1 1 xs:string Common object name attribute any attribute name 0 n any Includes type, href, XML namespace identifiers Link 0 n LinkType Links to actions and contained objects Description 0 1 xs:string Optional description Tasks 0 1 TasksInProgressType Read‐only container for Task elements.
Chapter 9 User API Reference Schema (Continued) Name Min Max Type Description VmQuota 0 1 xs:int Maximum number of virtual machines that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number. IsEnabled 0 1 xs:boolean True if this vDC is enabled StorageCapacity The StorageCapacity element reports storage resource consumption in a vDC. Schema Name Min Max Type Description Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only.
vCloud API Programming Guide ResourceEntities The ResourceEntities element is a read‐only container for ResourceEntity elements. ResourceEntity The ResourceEntity element is a read‐only reference to a vAppTemplate or Media object contained by a vDC. Schema Name Min Max Type Description name 1 1 xs:string Common object name attribute status 0 1 xs:int Creation status of the referenced object.
Chapter 9 User API Reference Schema (Continued) Name Min Max Type Description Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object. Configuration 0 1 NetworkConfigurationType Properties of the network NetworkPool 0 1 ReferenceType A reference to the network pool from which this network is provisioned.
vCloud API Programming Guide Schema (Continued) Name Min Max Type Description Dns2 0 1 IpAddressType IP address of the secondary DNS server for this network DnsSuffix 0 1 xs:string Suffix to be applied when resolving hostnames that are not fully‐qualified. IpRanges 0 1 IpRangesType Read‐only container for IpRange elements. AllocatedIpAddresses 0 1 IpAddressesType List of addresses allocated to connections to this network. Must fall within any specified IpRanges.
Chapter 9 User API Reference FirewallRule The FirewallRule element defines a single firewall rule.
vCloud API Programming Guide NatType The NatType element specifies how network address translation is implemented by the NAT service. Table 9‐3 shows permitted values for element content and the results they produce. Table 9-3. NatType Element Values Value Result ipTranslation NAT service implemented by IP address translation portForwarding NAT service implemented by network port forwarding Policy The Policy element of a NatService element specifies how packets are handled by the NAT service.
Chapter 9 User API Reference MappingMode The MappingMode element specifies how IP address mapping is implemented by the NAT service. Table 9‐5 shows permitted values for element content and the results they produce. Table 9-5.
vCloud API Programming Guide Protocol The Protocol element of a VmRule element specifies the network protocol to which this rule applies. Table 9‐6 shows permitted values for element content and the results they produce. Table 9-6. VmRule Protocol Element Values Value Result TCP The rule applies to the TCP protocol UDP The rule applies to the UDP protocol TCP_UDP The rule applies to the TCP and UDP protocols Catalog A Catalog element is a container for CatalogItems.
Chapter 9 User API Reference Property Each CatalogItem can have up to ten Property elements, each of which expresses a key=value relationship. The key is an attribute value, and the value is the content of the Property element itself. This element can be used to hold arbitrary metadata attached to a CatalogItem. The vCloud API itself makes no use of this information. Schema Name Min Max Type Description key 1 1 xs:string Key associated with the string value contained in the element.
vCloud API Programming Guide Schema (Continued) Name Min Max Type Description ovfDescriptorUploaded 0 1 xs:boolean True if the OVF descriptor for the template has been uploaded to the containing vDC. any attribute name 0 n any Includes type, href, XML namespace identifiers Link 0 n LinkType Links to actions and contained objects Description 0 1 xs:string Optional description Tasks 0 1 TasksInProgressType Read‐only container for Task elements.
Chapter 9 User API Reference Schema (Continued) Name Min Max Type Section 0 n ovf:Section_Type Children 0 n VAppChildrenType Description Any of the following ovf:Section_Type elements: LeaseSettingsSection StartupSection NetworkConfigSection CustomizationSection Read‐only container for Vm elements representing virtual machines Vm A Vm represents a virtual machine, a member of a vApp’s Children container. Content-Type application/vnd.vmware.vcloud.
vCloud API Programming Guide The following section types are allowed in a Vm: VirtualHardwareSection OperatingSystemSection NetworkConnectionSection GuestCustomizationSection LeaseSettingsSection The LeaseSettingsSection element defines the terms of storage and deployment leases for a vApp. Content-Type application/vnd.vmware.vcloud.
Chapter 9 User API Reference Schema (Continued) Name Min Max Type Description CustomizeOnInstantiate 1 1 xs:boolean If true, then customization is executed for all children that include a GuestCustomizationSection. Default value is false. Link 0 n LinkType Configuration links NetworkConfigSection The NetworkConfigSection element specifies the configuration of a vApp network. Content-Type application/vnd.vmware.vcloud.
vCloud API Programming Guide Schema (Continued) Name Min Max Type Description href 0 1 xs:anyURI URL to access this section ovf:Info 1 1 ovf:Msg_Type Required by the base ovf:Section_Type. It can contain xs:string information about the containing element, or can be empty PrimaryNetworkConnectionIndex 0 1 xs:int The value of the rasd:AddressOnParent element of the device (NIC) supporting the primary network connection to the containing virtual machine.
Chapter 9 User API Reference VirtualHardwareSection The VirtualHardwareSection element of an ovf:VirtualSystem or Vm contains a description of the virtual hardware supported by a virtual machine. Content-Type application/vnd.vmware.vcloud.virtualHardwareSection+xml OperatingSystemSection The OperatingSystemSection element of an ovf:VirtualSystem or Vm specifies the guest operating system installed on the virtual machine. Content-Type application/vnd.vmware.vcloud.
vCloud API Programming Guide RasdItemsList A RasdItemsList element is a read‐only container for groups of related ovf:Item elements such as hard disks, network cards, and media devices. Vm elements typically contain several Link elements that reference elements of this type. Content-Type application/vnd.vmware.vcloud.rasdItemsList+xml ScreenTicket A ScreenTicket element contains a string that represents a screen ticket (required to access a virtual machine’s console). Content-Type application/vnd.vmware.
Chapter 9 User API Reference Schema (Continued) Name Min Max Type Description Owner 0 1 ReferenceType A link to the object that owns the task. For copy operations, the owner is the copy that is being created. For delete operations, the owner is the deleted object, so this element is not included. For all other operations, the owner is the object to which the request was made. Error 0 1 ErrorType Error message or related information returned by the task VMware, Inc.
vCloud API Programming Guide 170 VMware, Inc.
10 Request Parameters Reference 10 This chapter provides reference information about the request parameters defined in this release of the vCloud API. Elements documented in this chapter provide parameters to requests that create, delete, modify, or change the state of an object.
vCloud API Programming Guide InstantiateVAppTemplateParams The InstantiateVAppTemplateParams element forms the body of an instantiateVappTemplate request. Content-Type application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml Schema Name Min Max Type Description name 1 1 xs:string Specifies the name of the vApp created by this instantiation linkedClone 0 1 xs:boolean Ignored in this release deploy 0 1 xs:boolean True if the vApp should be deployed after instantiation.
Chapter 10 Request Parameters Reference InstantiationParams contained by any other element apply to a vApp and can contain the following section types: LeaseSettingsSection StartupSection NetworkConfigSection CustomizationSection ComposeVAppParams The ComposeVAppParams element forms the body of a composeVapp request. Content-Type application/vnd.vmware.vcloud.
vCloud API Programming Guide Schema (Continued) Name Min Max Type Description VAppScopedLocalId 0 1 xs:string If the object referenced in Source is a Vm, this element can be used to provide a unique identifier for this Vm in the composed vApp.
Chapter 10 Request Parameters Reference Schema (Continued) Name Min Max Type Description Item 0 n CompositionItemParamsType Specifies a source vAppTemplate, vApp, or Vm to include in the composition DeleteItem 0 n ReferenceType Reference to a Vm to remove from the vApp AllEULAsAccepted 0 1 xs:boolean True if you accept the terms and conditions in the template’s EULA sections. Composition fails if false. DeployVAppParams The DeployVAppParams element forms the body of a deploy request.
vCloud API Programming Guide CloneMediaParams The CloneMediaParams element forms the body of a cloneMedia request. Content-Type application/vnd.vmware.vcloud.cloneMediaParams+xml Schema Name Min Max Type Description name 1 1 xs:string Specifies the name of the new media image created by the clone operation Description 0 1 xs:string Optional description. Used for the Description of the cloned Media image.
Chapter 10 Request Parameters Reference Schema (Continued) Name Min Max Type Description Source 1 1 ReferenceType Reference to the vApp to clone (copy) IsSourceDelete 0 1 xs:boolean True if the object referenced by Source should be deleted after the copy is made MediaInsertOrEjectParams A MediaInsertOrEjectParams element forms the body of an insertMedia or ejectMedia request. Content-Type application/vnd.vmware.vcloud.
vCloud API Programming Guide AccessSettings The AccessSettings element is a container for AccessSetting elements. This container must be present and not empty if the value of IsSharedToEveryone in the containing ControlAccessParams element is set to false. AccessSetting An AccessSetting element defines the level of access granted to the user or group referenced in the Subject element.
11 11 Administrative API Reference This chapter provides reference information about the XML elements that support administrative operations in the vCloud API. Elements documented in this chapter are generally readable by all users, but can be created and modified only by a system administrator, organization administrator or other privileged user. Many of the schemas shown here extend elements and complex types that are defined in the user API.
vCloud API Programming Guide OrganizationReferences The OrganizationReferences element is a read‐only container for ReferenceType elements that reference AdminOrg objects a vCloud. To create a new organization, see “Create an Organization” on page 95. ProviderVdcReferences The ProviderVdcReferences element is a read‐only container for ReferenceType elements that reference ProviderVdc objects a vCloud. To create a ProviderVdc, see “Create a Provider vDC” on page 127.
Chapter 11 Administrative API Reference Schema (Continued) Name Min Max Type Description Description 0 1 xs:string Optional description Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
vCloud API Programming Guide Schema (Continued) Name Min Max Type Description UseServerBootSequence 0 1 xs:boolean True if virtual machines in this organization use the server boot sequence by default DelayAfterPowerOnSeconds 0 1 xs:int Specifies an organization default for virtual machine boot delay after power‐on OrgLeaseSettings The OrgLeaseSettings element defines default lease durations and policies for the organization.
Chapter 11 Administrative API Reference Schema (Continued) Name Min Max Type Description UserName 0 1 xs:string Username to use when logging in to LDAP, specified using LDAP attribute=value pairs (for example: cn="ldap-admin", dc="example", dc="com") Password 0 1 xs:string Password for the user identified by UserName. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.
vCloud API Programming Guide UserAttributes If OrgLdapMode is CUSTOM, the UserAttributes element defines how LDAP attributes are used when importing a user. Schema Name Min Max Type Description ObjectClass 1 1 xs:string LDAP objectClass of which imported users are members. For example, user or person ObjectIdentifier 1 1 xs:string LDAP attribute to use as the unique identifier for a user.
Chapter 11 Administrative API Reference OrgEmailSettings The OrgEmailSettings element defines the email settings for an organization. Schema Name Min Max Type Description IsDefaultSmtpServer 1 1 xs:boolean True if this organization uses the system default SMTP server IsDefaultOrgEmail 1 1 xs:boolean True if this organization uses the system default email properties.
vCloud API Programming Guide Catalog A Catalog element is a container for CatalogItems. An Org or AdminOrg may contain zero or more Catalog elements. To create, delete, or modify a catalog, an administrator must access it using the admin URL and content type shown here. Content-Type application/vnd.vmware.vcloud.admin.catalog+xml Object href prototype vCloud‐URL/admin/catalog/catalog‐id For more information about the Catalog element schema, see “Catalog” on page 160.
Chapter 11 Administrative API Reference Schema (Continued) Name Min Max Type Description Vdcs 0 1 VdcsType Container for Vdc objects that are provisioned from this provider vDC.
vCloud API Programming Guide Schema Name Min Max Type Description Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only. Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this vDC. This value is read‐only. StorageCapacity The administrative view of aStorageCapacity defines the amount of storage available in a ProvidervDC and optionally reports how much of that capacity is in use.
Chapter 11 Administrative API Reference Schema Name Min Max Type Description name 1 1 xs:string Common object name attribute any attribute name 0 n any Includes type, href, XML namespace identifiers status 0 1 xs:int The creation status of the vDC: -1 creation failed 0 not ready 1 ready 2 unknown 3 unrecognized status Description 0 1 xs:string Optional description Tasks 0 1 TasksInProgressType Read‐only container for Task elements.
vCloud API Programming Guide Schema (Continued) Name Min Max Type Description VCpuRatingMHz 0 1 xs:long Specifies a clock frequency, in Megahertz, for each virtual CPU core provisioned from this vDC IsThinProvision 0 1 xs:boolean True if thin provisioning has been enabled for this vDC NetworkPoolReference 0 1 ReferenceType Reference to a network pool in the provider vDC referenced by ProviderVdcReference ProviderVdcReference 0 1 ReferenceType Reference to the ProviderVdc from which
Chapter 11 Administrative API Reference Schema (Continued) Name Min Max Type Description StoredVmQuota 0 1 xs:int Quota of vApps that this user can store. A value of 0 specifies an unlimited quota. DeployedVmQuota 0 1 xs:int Quota of vApps that this user can deploy concurrently. A value of 0 specifies an unlimited quota Role 0 1 ReferenceType A reference to the user’s role. When you are creating a User, the request body must contain exactly one Role element.
vCloud API Programming Guide Right Right elements are predefined by Service Manager. They are read‐only to users and administrators, and can be retrieved with a GET operation that specifies the URL in a RightReference. For more information, see “Get an Administrative View of a Cloud” on page 93. Content-Type application/vnd.vmware.admin.
12 vSphere Platform Extensions Reference 12 This chapter provides reference information about the elements defined in the vSphere Platform extensions to this release of the vCloud API. Elements documented in this chapter can be created and modified only by a system administrator. For more information about how the vCloud API uses XML to represent objects, and how this reference material is organized, see “XML Representations in the vCloud API” on page 141.
vCloud API Programming Guide VMWProviderVdcReferences The VMWProviderVdcReferences element is a read‐only container for ProviderVdcReference elements. Content-Type application/vnd.vmware.admin.vmwProviderVdcReferences+xml Object href prototype API‐URL/admin/extension/providerVdcReferences VMWExternalNetworkReferences The VMWExternalNetworkReferences element is a read‐only container for ExternalNetworkReference elements. Content-Type application/vnd.vmware.admin.
Chapter 12 vSphere Platform Extensions Reference Schema (Continued) Name Min Max Type Description Password 0 1 xs:string Password for the user identified by Username. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.
vCloud API Programming Guide ResourcePoolList The ResourcePoolList element is a read‐only container for ResourcePool elements. Content-Type application/vnd.vmware.admin.resourcepoollist+xml Object href prototype API‐URL/admin/extension/vimServer/id/resourcePoolList ResourcePool The ResourcePool element includes the MoRef (managed object ID) of the pool itself and additional DataStoreRefs for each datastore in a pool.
Chapter 12 vSphere Platform Extensions Reference VMWProviderVdc A VMWProviderVdc object represents a provider vDC. Content-Type application/vnd.vmware.admin.
vCloud API Programming Guide VMWNetworkPool The VMWNetworkPool element represents a network pool. There are three different types of this element, all of which have the same name, VMWNetworkPool, and are distinguished in request bodies by the value of the HTTP Content‐Type header. FencePoolType A VMWNetworkPool of the FencePoolType represents a network pool backed by one or more vSphere isolated networks. Content-Type application/vnd.vmware.admin.
Chapter 12 vSphere Platform Extensions Reference Schema (Continued) Name Min Max Type Description VimSwitchRef 1 1 VimObjectRefType Reference to the switch that supports this VLAN UsedNetworksCount 0 1 xs:int Read‐only indication of how many networks in this pool are in use VMWExternalNetwork The VMWExternalNetwork element defines an external network. Content-Type application/vnd.vmware.vcloud.admin.
vCloud API Programming Guide Schema (Continued) Name Min Max Type Description Ready 1 1 xs:boolean True if the host is ready Available 1 1 xs:boolean True if the host is available Enabled 1 1 xs:boolean True if the host is enabled for use with Cloud Director Busy 1 1 xs:boolean True if the host is busy EnableHostForHostSpanning 1 1 xs:boolean True if the host is enabled for host spanning. If true, the host cannot be put in standby or maintenance mode.
Chapter 12 vSphere Platform Extensions Reference ImportVmAsVAppParams The ImportVmAsVAppParams element forms the body of an importVmAsVApp request.
vCloud API Programming Guide 202 VMware, Inc.
A OVF and the vCloud API A The Open Virtualization Format (OVF) is an open, portable, efficient and extensible format for packaging and distributing virtual systems. OVF was developed by the Distributed Management Task Force (DMTF), a not‐for‐profit association of industry members dedicated to promoting enterprise and systems management and interoperability. For more information about the DMTF and OVF, visit http://www.dmtf.org. The vCloud API supports Version 1 of the OVF standard.
vCloud API Programming Guide A virtual application or virtual machine is typically made up of one or more virtual disk files that contain the operating system and applications that run on the virtual machine, and a configuration file containing metadata that describe how the virtual machine is configured and deployed. An OVF package includes these components, as well as optional certificate and manifest files.
Appendix A OVF and the vCloud API Virtual Disk Files Virtual disk file information extracted from the References section of the OVF package is used to populate the Files element of the VAppTemplate. An OVF package can include exactly one References section. It lists all the files required by all the VirtualSystems defined in the package, including virtual disks and locale‐specific resource files. Virtual disk files are enumerated again in the DiskSection element of the package, one file per Disk element.
vCloud API Programming Guide The vCloud API NetworkConnectionSection is a read‐only section that lists the network connections and IP addresses that a vApp has acquired or been assigned at deployment. This section is present only in a deployed vApp that has a network connection. The OVF Item element, one of many that apply to the Envelope’s VirtualHardwareSection, specifies that the virtual machine’s NIC (resource type 10) is connected to Internet.
B An Introduction to REST for vCloud API Users B REST, an acronym for Representational State Transfer, is a term that has been widely employed to describe an architectural style characteristic of programs that rely on the inherent properties of hypermedia to create and modify the state of an object that is accessible at a URL.
vCloud API Programming Guide example, or the prescribed hierarchy with which elements can be nested) represent the data structures of objects in the cloud. A client can “read” an object by making an HTTP GET request to the object’s URL. A client can “write” (create or modify) an object with an HTTP PUT or POST request that includes a new or changed XML body document for the object. And a client can usually delete an object with an HTTP DELETE request.
Index A AccessLevel element example of use 57 schema reference 178 AccessSetting element example of use 56, 57 schema reference 178 AccessSettings element example of use 56 schema reference 178 AdminVdc element example of use 104 AllEULAsAccepted description 172 AllEULAsAccepted element example of use 63, 65 authentication about 18 example request 21 AvailableNetworks element example of use 103, 104, 129 schema reference 153 C CaptureVAppParams element example of use 68 schema reference 175 Catalog elemen
vCloud API Programming Guide schema reference 199 HTTP headers Content-Type 142 HTTP status codes 18 I InstantiateVAppTemplateParams element example of use 25, 63 schema reference 172 Instantiation Parameters about 62 InstantiationParams element example of use 25, 63 schema reference 172 IpRange element example of use 72 schema reference 156 L Link element about 15 rel attribute 15 login example of 21 logout example of 30 example of use 21 OrgNetwork element schema definition 154 OVF to create vApp temp
Index V vApp to compose from templates and virtual machines 65 to create from template 24, 61 to deploy and power-on 26 to instantiate 24 VApp element example of use 65, 66, 67, 69 schema reference 162 vApp networks about 62 vApp template add to catalog 54 to create from OVF 42 to create from vApp 68 VAppScopedVmId element example of use 72 VAppTemplate element example of use 61 schema reference 161 to create 42 vDC about 14 Vdc element example of use 24, 37 schema reference 152 VimServer example of use 12
vCloud API Programming Guide 212 VMware, Inc.
