1. Manuals
  2. Brands
  3. VMware Manuals
  4. Software
  5. VCLOUD API 1.0 - TECHNICAL NOTE
  6. Programming manual

VMware VCLOUD API 1.0 - API Programming Manual

Hide thumbs
Table of Contents

Advertisement

Quick Links

Download this manual
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.
EN-000180-00

Advertisement

Table of Contents
loading

Related Manuals for VMware VCLOUD API 1.0 - API

Summary of Contents for VMware VCLOUD API 1.0 - API

  • Page 1 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. EN-000180-00...
  • Page 2 VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

  • Page 3: Table Of Contents

    Contents About This Book 11 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 Hello vCloud: A Structured REST Workflow Example 21 Logging In and Getting an Organization List 21 Browsing an Organization 22 Finding a vApp Template 23 Getting Information About a vDC 24 Instantiating the Template in the vDC 24 Deploying and Powering On the vApp 26 Getting Information About the vApp 27 Displaying the Console 29...
  • Page 4 Retrieve or Modify the CustomizationSection of a vApp Template 64 Compose a vApp 65 Finding Virtual Machine URLs to Use in a Composition Item 66 Recompose a vApp to Add or Remove Virtual Machines 67 Capture a vApp to Create a vApp Template 68 Reconfiguring vApps and Virtual Machines 69 Reconfigure a vApp 69 Reconfigure a Virtual Machine 73 Deploying and Controlling vApps and Virtual Machines 80 Deploy a vApp or Virtual Machine 80 Undeploy a vApp or Virtual Machine 81 Power On a vApp or Virtual Machine 81 Power Off a vApp or Virtual Machine 82 Reset a vApp or Virtual Machine 82 Suspend a vApp or Virtual Machine 83 Discard the Suspended State of a vApp or Virtual Machine 83 Shut Down a vApp or Virtual Machine 84 Reboot a vApp or Virtual Machine 84 List Media Devices of a Virtual Machine 85 VMware, Inc.
  • Page 5 Modify a vDC 106 Enable or Disable a vDC 107 Remove a vDC 107 Catalog Administration 107 Create a Catalog 107 Get an Administrative View of a Catalog 108 Publish a Catalog 109 Modify Catalog Metadata 109 Remove a Catalog 110 User Administration 110 Create or Import a User 110 Get an Administrative View of a User 112 Modify User Metadata 112 Remove a User 113 Group Administration 113 Import a Group 113 View Group Metadata 114 Modify Group Metadata 114 Remove a Group 114 VMware, Inc.
  • Page 6 API Programming Guide Role Administration 114 Create a Role 114 View Role Metadata 115 Modify a Role 116 Remove a Role 116 View a Right 116 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 Manager 122 Unregister a vCenter Server and vShield Manager 123 Force Reconnection to a vCenter Server 124...
  • Page 7 Vm 163 Section 163 LeaseSettingsSection 164 StartupSection 164 CustomizationSection 164 NetworkConfigSection 165 NetworkConnectionSection 165 VirtualHardwareSection 167 OperatingSystemSection 167 GuestCustomizationSection 167 RasdItemsList 168 ScreenTicket 168 TasksList 168 Tasks 168 Task 168 Request Parameters Reference 171 UploadVAppTemplateParams 171 InstantiateVAppTemplateParams 172 InstantiationParams 172 VMware, Inc.
  • Page 8 NetworkPoolReferences 188 NetworkPoolReference 188 VdcReferences 188 AdminVdc 188 AllocationModel 190 User 190 Group 191 Role 191 RightReferences 191 RightReference 191 Right 192 vSphere Platform Extensions Reference 193 VMWExtension 193 VMWProviderVdcReferences 194 VMWExternalNetworkReferences 194 VMWNetworkPoolReferences 194 VMWVimServerReferences 194 VMWHostReferences 194 VimServer 194 VMware, Inc.
  • Page 9 Request Parameters 200 PrepareHostParams 200 RegisterVimServerParams 200 ImportVmAsVAppParams 201 ImportVmAsVAppTemplateParams 201 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 An Introduction to REST for vCloud API Users 207 How REST Works 207 Using the vCloud REST API 207 RESTful Workflow Patterns 208 For More Information About REST 208 Index 209 VMware, Inc.
  • Page 10 API Programming Guide VMware, Inc.

  • Page 11: About This Book

    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. Revision History This book is revised with each release of the product or when necessary. A revised version can contain minor  or major changes. Table 1 summarizes the significant changes in each version of this book. Table 1. Revision History Revision Date Description 30AUG10 Version 1.0 Intended Audience This guide is intended for software developers who are building VMware Ready Cloud Services, including  interactive clients of VMware Cloud Director. This guide assumes you are familiar with Representational State  Transfer (REST) and RESTful programming conventions, the Open Virtualization Format Specification, and  VMware Virtual machine technology. Familiarity with other widely‐deployed technologies such as XML,  HTTP, and the Windows or Linux operating systems is also assumed. VMware Technical Publications Glossary VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions  of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs. Document Feedback VMware welcomes your suggestions for improving our documentation. Send your feedback to  docfeedback@vmware.com. VMware, Inc.
  • Page 12 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. Support Offerings To find out how VMware support offerings can help meet your business needs, go to  http://www.vmware.com/support/services. VMware Professional Services VMware Education Services courses offer extensive hands‐on labs, case study examples, and course materials  designed to be used as on‐the‐job reference tools. Courses are available onsite, in the classroom, and live  online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides  offerings to help you assess, plan, build, and manage your virtual environment. To access information about  education classes, certification programs, and consulting services, go to http://www.vmware.com/services.  VMware, Inc.

  • Page 13: Introducing The Vmware Vcloud Api

    Introducing the VMware vCloud API 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. HTTP GET requests are used to retrieve the current representation of an object, HTTP POST and  PUT requests are used to create or modify an object, and HTTP DELETE requests are typically used to delete  an object. This chapter introduces the vCloud API and includes the following topics:  “vCloud Object Taxonomy” on page 13  “Objects, References, and Representations” on page 15  “Links and Link Relations” on page 15  “vCloud Client Workflow Overview” on page 17  “About the Examples” on page 19 vCloud Object Taxonomy The vCloud API defines a set of objects common to cloud computing environments. Figure 1‐1 illustrates the  principal object types. vCloud Organizations A vCloud contains one or more organizations. A vCloud organization is a unit of administration for a  collection of users, groups, and computing resources. Users authenticate at the organization level, supplying  credentials established by an organization administrator when the user was created or imported. vCloud Users and Groups An organization can contain an arbitrary number of users and groups. Users can be created by the ...
  • Page 14 Catalogitem vApp vApp Catalogitem template Catalogitem Media Media Network users groups TasksList Network vCloud Virtual Datacenters A vCloud virtual datacenter (vDC) is an allocation mechanism for resources such as networks, storage, CPU,  and memory. In a vDC, computing resources are fully virtualized, and can be allocated based on demand,  service level requirements, or a combination of the two. There are two kinds of vDCs:  Provider vDCs. These vDCs contain all the resources available from the vCloud service provider.  Provider vDCs are created and managed by vCloud system administrators.   Organization vDCs. These vDCs provide an environment where virtual systems can be stored, deployed,  and operated. They also provide storage for virtual media, such as floppy disks and CD ROMs. An organization administrator specifies how resources from a provider vDC are distributed to the vDCs in an  organization. vCloud Catalogs Catalogs contain references to virtual systems and media images. A catalog can be shared to make it visible to  other members of an organization, and can be published to make it visible to other organizations. A vCloud  system administrator specifies which organizations can publish catalogs, and an organization administrator  controls access to catalogs by organization members. vCloud Tasks Long‐running operations initiated by members of an organization create tasks, which are kept on the  organization’s tasks list. VMware, Inc.

  • Page 15: Objects, References, And Representations

    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). These templates can be retrieved from catalogs and transformed into virtual  systems, called vApps, through a process called instantiation, which binds a template’s abstract resource  requirements to resources available in a vDC. A vApp contains one or more individual virtual machines (Vm  elements), along with parameters that define operational details such as:  How the contained virtual machines are connected to each other and to external networks.  The order in which individual virtual machines are powered on or off.  End‐user license agreement terms for each virtual machine.  Deployment lease terms (typically inherited from the containing organization) that constrain the vApp’s  consumption of vDC resources  Access control information specifying which users and groups can perform operations such as deploy,  power on, modify, and suspend on the vApp and the virtual machines it contains.  Objects, References, and Representations The vCloud API represents objects in the 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.  Every object in a vCloud is uniquely identified by a URL. This URL is constructed by the server and returned ...
  • Page 16 POST remove remove this object DELETE repair repair this host POST screen:acquireTicket acquire a screen ticket for this virtual machine screen:thumbnail thumbnail view of a virtual machine screen, in png format task:cancel not supported in this release undeploy undeploy this object POST unregister unregister this vCenter Server POST the referenced object contains this object upgrade upgrade this host POST upload:alternate not supported in this release upload:default default upload location for this file  The type attribute value defines the media type (HTTP Content‐Type) of the request or response  document. This attribute is present only for links to objects. It is not present for links to actions.  The href attribute value is a URL, which should be considered an opaque identifier (one that the client  should not attempt to parse or interpret). An href uniquely identifies, and persists for the life of, the  referenced object. These identifiers are never re‐used.  The name attribute value of the Link is the same as the name of the referenced object. Action links do not  include a name attribute. VMware, Inc.

  • Page 17: Vcloud Client Workflow Overview

    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. Links to actions and contained objects are omitted from responses if the  request was made by a user who has insufficient privileges to access the object or perform the action. Action  links are also omitted when the action cannot be performed (powering on a virtual machine that is already  powered on, for example).    When a client uses a link to reference an object, only the href attribute is required. The name and type  are ignored. vCloud Client Workflow Overview Clients of the vCloud API implement a RESTful workflow, making HTTP requests to the server and retrieving  the information they need from the server’s responses. Requests Clients make HTTP requests to vCloud URLs, href attribute values which are typically provided by the server  in response to GET requests by the client. Every vCloud has a well‐known URL from which a client can get the  server’s login URL and the list of vCloud API versions that the server supports, along with additional  information (see “API Versioning” on page 147). After a client has logged in, all vCloud API URLs can be  discovered by making GET requests to URLs listed in the login response and the URLs contained in responses  to those requests. Request Headers All requests from authenticated clients must include an authentication header. See “Authentication” on  page 18. Requests that include a document body must start with the appropriate HTTP Content‐Type header. The type  attribute of a response body indicates the content type of the document. For example, this response fragment  indicates that the content type associated with a CatalogItem entity is  application/vnd.vmware.vcloud.catalogItem+xml.

  • Page 18: Responses

    “Administrator Credentials and Privileges” on page 93. Responses All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content‐Type  header. Response content depends on the request. Some responses include a document body, some include  only a URL, and some are empty. Status Codes Table 1‐2 lists the subset of HTTP status codes that a vCloud API client can expect in a response. Table 1-2. HTTP Status Codes Returned by the vCloud API Status Code Status Description 200 OK The request is valid and was completed. The response includes a document body.  201 Created The request is valid. The requested object was created and can be found at the URL specified in  the Location header. 202 Accepted The request is valid and a task was created to handle it. This response is usually accompanied  by a task URL.  204 No Content The request is valid and was completed. The response does not include a body.  303 See Other The response to the request can be found at the URL specified in the Location header.  400 Bad Request The request body is malformed, incomplete, or otherwise invalid. VMware, Inc.

  • Page 19: Configuring The Vcloud Api Url

    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. 405 Method Not  The HTTP method specified in the request is not supported for this object. Allowed 500 Internal Server  The request was received but could not be completed due to an internal error at the server. Error  501 Not Implemented  The request is not implemented by the server. 503 Service  One or more services needed to complete the request are not available on the server. Unavailable Configuring the vCloud API URL The base URL used in href values includes the fully‐qualified domain name of the server host. In cases where ...
  • Page 20 API Programming Guide VMware, Inc.

  • Page 21: Hello Vcloud: A Structured Rest Workflow Example

    2‐1 shows a login request and response for a vCloud whose login  URL is http://vcloud.example.com/api/v1.0/login. Example 2-1. Login Request and Response Request: POST http://vcloud.example.com/api/v1.0/login encoded-credentials Authorization: Basic Response: 200 OK Date: request-date x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.orgList+xml <?xml version="1.0" encoding="UTF-8"?> <OrgList ... href="http://vcloud.example.com/api/v1.0/org/" ... > <Org type="application/vnd.vmware.vcloud.org+xml" name="ExampleOrg" href="http://vcloud.example.com/api/v1.0/org/5"/> VMware, Inc.

  • Page 22: Browsing An Organization

    Example 3‐1 on page 34.) Example 2-2. List the Contents of an Organization Request: GET http://vcloud.example.com/api/v1.0/org/5 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.org+xml <Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5" ... > <Link ... /> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/> <Link ... /> <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" name="ExampleVdc01"/>...

  • Page 23: Finding A Vapp Template

    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 <Catalog name="MainCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" ...> <Description>Main Org Catalog</Description> <CatalogItems> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> </CatalogItems> </Catalog> Every vApp template or media image that has been added to the catalog is represented as a CatalogItem  element. When a client browses a catalog, it can read only the name, type, and href of each CatalogItem. To  retrieve an item from the catalog, more information is required. In Example 2‐4, the client makes a GET request  to a CatalogItem URL (its href value). The response provides more information, including a description of  the referenced object and another URL that the client can use to retrieve a representation of the object.

  • Page 24: Getting Information About A Vdc

    Example 2‐5 shows this subset of vDC contents. (For a more complete look at those contents, see Example 3‐4  on page 37.) Example 2-5. 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 <Vdc name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" ...> <Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate" /> <AvailableNetworks> <Network href="http://vcloud.example.com/api/v1.0/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet"/> <Network href="http://vcloud.example.com/api/v1.0/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet"/>...
  • Page 25  A fence mode, specified in the FenceMode element. A value of bridged indicates that the vApp  network is connected directly to the organization network. The target of the request is the instantiateVAppTemplate URL of this vDC (see Example 2‐5). Because the  operation creates a new object (a vApp), the HTTP request type is POST. Example 2-6. Instantiating a vApp Template Request: POST http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml <InstantiateVAppTemplateParams name="Linux FTP server" xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" > <Description>Example FTP Server vApp</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode>...

  • Page 26: Deploying And Powering On The Vapp

    API Programming Guide <Task status="running" startTime="2010-06-25T08:00:55.402-07:00" operation="Creating Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey"> <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/> </Task> </Tasks> </VApp>    A vApp template might include a license agreement or other terms that you must accept before you  can create a vApp from it. In this example, the template contains no such terms. If it did, the request would  fail if it did not include an AllEULAsAccepted element, as shown in Example 5‐1 on page The response to the instantiation request is a sparsely populated vApp body, which includes the following  information:  The status of the vApp. The status value 0 indicates that the vApp is unresolved, because instantiation  has not completed.  The name of the vApp, as supplied in the request  The vApp URL, shown in the href attribute of the VApp body  A task created to track the instantiation. The Task element has an operation attribute that describes what  is happening, and contains an Owner element that is a reference the vApp being created. For more  information, see “Task” on page 168.

  • Page 27: Getting Information About The Vapp

    Much additional information is available, though most of it is not shown here. The example does show  where to find the IP address of the vApp, in the IpAddress element of the NetworkConnection. Example 2-8. Get Information About the vApp Request: GET http://vcloud.example.com/api/v1.0/vApp/vapp-7 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp status="4" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ... > <Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reboot"/> <Link rel="power:powerOff" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOff"/> <Link rel="undeploy" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/undeploy"/> <Link rel="deploy" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deploy"/> <Link rel="power:shutdown"...
  • Page 28 API Programming Guide </ovf:StartupSection> <ovf:NetworkSection ... > <ovf:Info/> <ovf:Network ovf:name="vAppNetwork"> <ovf:Description/> </ovf:Network> </ovf:NetworkSection> <NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/ networkConfigSection/"/> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> <IsDeployed>true</IsDeployed> </NetworkConfig> </NetworkConfigSection>...

  • Page 29: Displaying The Console

    Retrieve a Screen Ticket A screen ticket is a string that includes the virtual machine’s IP address, its managed object reference, and a  string that has been encoded as described in RFC 2396. Each Vm element in a vApp includes a link where  rel="screen:acquireTicket". You can use that link to request a screen ticket that you can use with the  vmware-vmrc utility to open a VMware Remote Console for the virtual machine represented by that Vm  element. Example 2‐9 makes such a request using the acquireTicket link returned in Example 2‐8. Example 2-9. 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 <ScreenTicket xmlns="http://www.vmware.com/vcloud/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...> mks://10.147.43.171/vm-61?ticket=Pznh4HMb7k%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3 SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O </ScreenTicket> The ticket itself has the following form: mks:// ip-address VM-MoRef /ticket=...

  • Page 30: Use The Ticket With Vmware-Vmrc

       The version of vmware-vmrc included with Cloud Director cannot be used to access virtual machines  in vCenter. In addition, it is incompatible with the version of vmware-vmrc installed by VMware vSphere Web  Access, which is also installed as a browser plug‐in, and cannot co‐exist with the Cloud Director version of  vmware-vmrc. To use a screen ticket with vmware-vmrc, open a command shell in the folder where vmware-vmrc.exe is  installed and run a command that has the form: ip-address decoded-ticket VM-MoRef vmware-vmrc -h For the ticket shown in Example 2‐9, the command line would look similar to this one. vmware-vmrc -h 10.147.43.171 -p 9XVUXZ... -M vm-61 The command contacts the specified IP address, presents the decoded ticket for validation, and displays a  VMware Remote Console window. If the ticket is valid, you can access the virtual machine’s console in the  window. If the ticket is improperly decoded or has timed out, and error message is displayed. Deleting the vApp You can use an HTTP DELETE request to delete a vApp, as shown in Example 2‐10. (You must power off and  undeploy the vApp before you delete it.) The response is a Task body. Because the task tracks a deletion, it  does not include an Owner element. (The owner is the object being deleted.) Example 2-10. Delete a vApp Request: DELETE http://vcloud.example.com/api/v1.0/vApp/vapp-7 Response: 202 Accepted <Task xmlns="http://www.vmware.com/vcloud/v1"...

  • Page 31: Moving On To Additional Use Cases

     Creating vApp templates by uploading OVF packages or capturing vApps (“Provisioning” on page 41)  Non‐default instantiation using detailed instantiation parameters (“Instantiate a vApp Template” on  page 61)  Creating a copy of a vApp by cloning, or composing a vApp from multiple vApps or templates  Reconfiguration of a vApp to add or remove virtual hardware, modify network connections, and change  other vApp properties (“Reconfiguring vApps and Virtual Machines” on page 69)  Administrative operations to create vDCs and Catalogs, and to administer users, groups, and roles  (“Administrative Operations” on page 91).  Operations that a system administrator can use to access the vSphere platform that supports a vCloud  roles (“VMware vSphere Platform Operations” on page 117). This guide also includes complete reference information on XML elements defined by the vCloud API (see  Chapter 9, “User API Reference,” on page 151 and Chapter 11, “Administrative API Reference,” on page 179),  and those defined by the vSphere platform extensions (see Chapter 12, “vSphere Platform Extensions  Reference,” on page 193). It also includes an introduction to OVF Appendix A, “OVF and the vCloud API,” on  page 203, which concentrates on those aspects of OVF that might be of interest to advanced vCloud API  programmers. VMware, Inc.
  • Page 32 API Programming Guide VMware, Inc.

  • Page 33: Browsing

    None 200 OK List the Organizations in a vCloud GET API‐URL/org None OrgList List the Contents of an Organization GET API‐URL/org/id None Get Information About a Network GET API‐URL/network/id None OrgNetwork List the Contents of a Catalog GET API‐URL/catalog/id None Catalog Get Information About a CatalogItem GET API‐URL/catalogItem/id None CatalogItem List the Contents of a vDC GET API‐URL/vdc/id None Get Information About a Media Image GET API‐URL/media/id None Media Get Information About a  GET API‐URL/vAppTemplate/vappTemplate‐id None VAppTemplate vAppTemplate Get Information About a vApp or  GET API‐URL/vApp/vapp‐id None VApp Virtual Machine VMware, Inc.

  • Page 34: Discovering The Contents Of An Organization, Catalog, Or Vdc

    3‐1 shows such a request and  response. Example 3-1. List the Contents of an Organization Request: GET http://vcloud.example.com/api/v1.0/org/5 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.org+xml <Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5" ...> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess/"/> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml"...

  • Page 35: List The Contents Of A Catalog

    <Catalog name="MainCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" ...> <Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/> <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/> <Description>Main Org Catalog</Description> <CatalogItems> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Boot Floppy" href="http://vcloud.example.com/api/v1.0/catalogItem/222"/> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu ISO Image" href="http://vcloud.example.com/api/v1.0/catalogItem/223"/> </CatalogItems> <IsPublished>true</IsPublished> </Catalog> VMware, Inc.

  • Page 36: Get Information About A Catalogitem

    API Programming Guide This response body includes:  A Link element that references the organization that contains this catalog: <Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/>  A Link element that you can use to add an item to the catalog: <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/>  Several CatalogItem elements. Each of these elements includes an href attribute whose value is a URL  that you can GET to obtain more information about the item, as shown in Example 3‐3.  An IsPublished element whose value indicates whether this catalog is visible to other organizations. For more information about creating catalogs and managing their contents, see “Cataloging vApp Templates  and Media Images” on page 54 and “Catalog Administration” on page 107. For more information about the  Catalog element schema, see “Catalog” on page 160. Get Information About a CatalogItem A CatalogItem element can reference a vApp template or a media object. Requests to get more information  about a CatalogItem return a CatalogItem document that includes:  The URL of the referenced object  Link elements that enable an authorized user to modify or remove the CatalogItem ...

  • Page 37: List The Contents Of A Vdc

    <Overhead>0</Overhead> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>100</Allocated> <Limit>100</Limit> <Used>32</Used> <Overhead>0</Overhead> </Cpu> <Memory> <Units>MB</Units> <Allocated>100</Allocated> <Limit>100</Limit> <Used>64</Used> <Overhead>0</Overhead> </Memory> </ComputeCapacity> <ResourceEntities> <ResourceEntity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> <ResourceEntity href="http://vcloud.example.com/api/v1.0/media/112" type="application/vnd.vmware.vcloud.media+xml" name="Ubuntu Boot Floppy"/> <ResourceEntity href="http://vcloud.example.com/api/v1.0/media/113" type="application/vnd.vmware.vcloud.media+xml" name="Ubuntu ISO Image"/> VMware, Inc.

  • Page 38: Getting More Information About An Object

    API Programming Guide <ResourceEntity href="http://vcloud.example.com/vApp/vapp-413" type="application/vnd.vmware.vcloud.vApp+xml" name="Example Corp. CRM"/> </ResourceEntities> <AvailableNetworks> <Network href="http://vcloud.example.com/api/v1.0/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet"/> <Network href="http://vcloud.example.com/api/v1.0/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet"/> </AvailableNetworks> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <VmQuota>0</VmQuota> <IsEnabled>true</IsEnabled> </Vdc> The response is a detailed description of the vDC and its contents. It includes:  Link elements whose rel attribute has a value of add. Each of these links has an href attribute whose  value is a URL that a client can use to add vApps, vApp templates, and media images to vDC inventory.  Several methods of adding inventory are supported, including upload, clone, and compose.   ResourceEntity elements that reference vApps that have been instatiated in or imported to this vDC,  and vApp templates and virtual media images that have been uploaded to the vDC.  A list of organization networks that are available in the vDC.  Other metadata, including quota and vDC state information. For more information, see “Vdc” on page 152.

  • Page 39: Get Information About A Vapptemplate

    Chapter 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 <Media xmlns="http://www.vmware.com/vcloud/v1" size="242131" imageType="iso" status="1" name="sql2000.iso" type="application/vnd.vmware.vcloud.media+xml" href="http://vcloud.example.com/api/v1.0/media/254" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/21"/> <Link rel="catalogItem" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/211"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/media/123"/>...

  • Page 40: Get Information About A Vapp Or Virtual Machine

    To get information about a network, make a GET request to its URL, as shown in Example 3‐7. Example 3-7. Get Information About a Network Request: GET http://vcloud.example.com/api/v1.0/network/54 Response: 200 OK Content-Type: application/vnd.vmware.admin.network+xml <OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet" type="application/vnd.vmware.admin.network+xml" ref="http://vcloud.example.com/api/v1.0/admin/network/54" ...> <Link rel="alternate" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54"/> <Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0//org/26"/>...

  • Page 41: Provisioning

    “Cataloging vApp Templates and Media Images” on page 54  “Controlling Access” on page 56 Summary of Provisioning Requests Table 4‐1 summarizes provisioning requests supported in this release. The table uses the following  conventions:  API‐URL is a URL of the form http://vcloud.example.com/api/v1.0.  id is an integer. Table 4-1. Summary of Provisioning Requests Operation Request Request Body Response Upload OVF to Create a  POST API‐URL/vdc/id/ UploadVAppTemplateParams VAppTemplate vApp Template action/uploadVAppTemplate Download a vApp  GET download‐URL None Depends on  Template as OVF file type VMware, Inc.

  • Page 42: Upload Ovf To Create A Vapp Template

    CatalogItem Remove an Item from a  DELETE API‐URL/ None 204 No content Catalog catalog/id/catalogItem/id Control Access to Catalogs POST  ControlAccessParams ControlAccess API‐URL/catalog/id/action/ Params controlAccess Upload OVF to Create a vApp Template A vCloud API client that has access to an OVF package can use a simple workflow to upload the package and  create a vApp template. The client POSTs an initial request that specifies a name for the template, a transfer format for the data,  and an optional description. The server returns an unresolved (status="0") vAppTemplate document that includes an upload URL  for the OVF package. The client uses an HTTP PUT request to upload the OVF package descriptor (the .ovf file) to the upload  URL.  The server reads the descriptor and constructs a complete vAppTemplate document (one that includes an  upload URL for each file listed in the References section of the descriptor). While the server is constructing  this document, the client makes periodic requests for it and examines the response for additional upload  URLs. When the response contains any upload URLs beyond the one returned in Step 2, template is  complete The client uses HTTP PUT requests to upload each of the files. If the OVF package includes a manifest file, the entire upload is validated against the contents of the  manifest file. VMware, Inc.

  • Page 43: Restrictions On Uploaded Content

    Initiate the Upload To initiate the upload, a client makes an HTTP POST request specifying a target vDC and an  uploadVAppTemplate action. The request body, shown in Example 4‐1, is an UploadVAppTemplateParams  element. Example 4-1. uploadVappTemplate Request POST http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml <UploadVAppTemplateParams name="Ubuntu Template" xmlns="http://www.vmware.com/vcloud/v1" > <Description>Ubuntu vApp Template</Description> </UploadVAppTemplateParams> This request creates a new VAppTemplate object in the target vDC and returns the objectʹs XML representation  in a response, as shown in Example 4‐2.  Example 4-2. Unresolved vAppTemplate Body with Upload URL for OVF Descriptor 201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...
  • Page 44 Example 4-4. GET vAppTemplate with Upload URLs Request: GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml <VAppTemplate ovfDescriptorUploaded="true" status="0" name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Ubuntu vApp Template</Description> <Files> <File size="3940" bytesTransferred="3940" name="descriptor.ovf"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../descriptor.ovf"/> </File> VMware, Inc.

  • Page 45: Including A Manifest

     name. The file name, taken from the href attribute of the File element in the OVF descriptor. Including a Manifest Some OVF packages include a manifest document, which specifies a checksum for each file in the package. If  you are uploading a package that includes a manifest file, add a manifestRequired="true" attribute to the  request body, as shown in Example 4‐5. Example 4-5. uploadVappTemplate Request for an OVF Package That Includes a Manifest POST http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml <UploadVAppTemplateParams name="Ubuntu Template" manifestRequired="true" xmlns="http://www.vmware.com/vcloud/v1" > <Description>Ubuntu vApp Template</Description> </UploadVAppTemplateParams> When you specify that a manifest is required, the set of File elements returned after you upload the OVF  descriptor includes one for the manifest itself. After all the files are uploaded, each file is checked by the server  to verify that its checksum matches the one stated in the manifest. If any checksums do not match, the  template’s status attribute is set to ‐1 and the template contains a Task element whose Error element  indicates the reason for the failure.
  • Page 46 ... > <Files> <File size="1950489088" bytesTransferred="500000000" name="disk0.vmdk"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../disk0.vmdk"/> </File> </Files> </VAppTemplate> If the response to an upload progress request indicates that the upload terminated before it was complete (for  example, if repeated progress requests show the same bytesTransferred value), a client can use the size  and bytesTransferred values from the response to construct a ranged PUT of the remaining contents, as  shown in Example 4‐8.    Ranged PUT requests are typically required for very large uploads, especially when network  bandwidth or latency could cause the operation to time out. Example 4-8. Ranged PUT to Complete a Partial Upload Request: PUT http://vcloud.example.com/transfer/.../disk0.vmdkk Content-Range: bytes 500000000-1950489087/1950489088 Content-length: 1450489088 ...serialized contents of specified range... VMware, Inc.

  • Page 47: View The Ovf Descriptor Of A Vapp Template

    Content-Type text/xml <Envelope ...> <DiskSection> <Info>Virtual disk information</Info> <Disk ovf:capacity="100" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/ vmdk.html#streamOptimized"/> </DiskSection> <VirtualSystem ... ovf:id="Ubuntu Template"> </VirtualSystem> </Envelope>    The OVF descriptor does not include any File references. These are removed by the server after the  template is resolved and recreated when the template is enabled for download. Download a vApp Template as OVF A vAppTemplate can be downloaded as an OVF package. After locating the template by browsing a catalog  or vDC, a client can request that the template be enabled for download. This operation constructs a download  URL for the template’s OVF descriptor file and adds it to the template. A client can download the descriptor  from this URL, examine it to discover the download URLs of the files it references, then make a series of GET  requests that download the files themselves. When you download a vApp template as OVF, all deployment‐specific information is removed from the OVF. VMware, Inc.

  • Page 48: Enable A Vapp Template For Download

    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.0/vAppTemplate/vappTemplate-268/action/enableDownload Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... operation="Enabling download of Virtual Application Template Ubuntu Template (268)" ... > </Task> When the enableDownload task completes, the template’s files are available from the vCloud transfer service,  and the vAppTemplate includes a Link element that contains a URL from which the template’s OVF descriptor  can be downloaded, as shown in Example 4‐11. Example 4-11. vApp Template with DownloadURL for OVF Descriptor Request: GET http://vcloud.example.com/api/vAppTemplate/vappTemplate-268...

  • Page 49: Disable A Vapp Template For Download

    Example 4-13. Downloading a Referenced File Request: GET http://vcloud.example.com/transfer/../disk0.vmdk Response: 200 OK ...serialized contents of file disk0.vmdk... When the download completes, the vApp template is available on the client as an OVF package.     Make sure that the downloaded files maintain the same relationship to each other in the local file  system as they had on the transfer server file system. In this case, the descriptor and disk0.vmdk were both  in the same directory (the default arrangement). Disable a vApp Template for Download An administrator or authorized user can use the disableDownload action to disable a vApp template for  download, as shown in Example 4‐14. The response is an HTTP 204 (No Content) status.  Example 4-14. Disable a vApp Template for Download Request: POST http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/action/disableDownload Response: 204 No Content VMware, Inc.

  • Page 50: Upload A Media Image

    Example 4‐15 shows a request to upload a CD‐ROM image in ISO format. The request body is a Media  element, which specifies the name, size, and type of the file. Example 4-15. Request to Upload an ISO Image POST http://vcloud.example.com/api/v1.0/vdc/5/media Content-Type: application/vnd.vmware.vcloud.media+xml <Media name="database.iso" size="242131" imageType="iso" xmlns="http://www.vmware.com/vcloud/v1"> <Description>ISO database image</Description> </Media> The server returns a Media representation that includes a single File element, as shown in Example 4‐16. The  client responds with a PUT request, sending serialized file data to the File element’s upload:default URL.  Example 4‐6 shows a similar request. Example 4-16. Server Response to Request to Upload an ISO Image Content-Type: application/vnd.vmware.vcloud.media+xml...

  • Page 51: Copy Or Move A Media Image

    4‐17 copies the virtual media image referenced by http://vcloud.example.com/api/v1.0/media/254 to  the vDC referenced by http://vcloud.example.com/api/v1.0/vdc/5 and provides a new name and description  for the copy. The source image remains in place after the copy is complete. Example 4-17. Copy a Virtual Media Image Request: POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneMedia Content-Type: application/vnd.vmware.vcloud.cloneMediaParams+xml <CloneMediaParams name="databse-backup.iso" xmlns="http://www.vmware.com/vcloud/v1"> <Description>This is a backup copy of the ISO database image</Description> <Source href="http://vcloud.example.com/api/v1.0/media/254"/> </CloneMediaParams> Response: 201 Created <Media name="database-backup.iso" size="242131" status="0" imageType="iso" href="http://vcloud.example.com/api/v1.0/media/277"...

  • Page 52: Copy Or Move A Vapp

    The cloneVApp request makes a copy of the vApp referenced in the Source element of the request body. The  request specifies a new name and, optionally, a new description for the copy. The request can optionally  include an IsSourceDelete element whose value specifies whether the source vApp is deleted after the copy  is complete. If IsSourceDelete is missing from the request body or present with a value of false, the source  object remains in place after the copy is complete. Setting IsSourceDelete to true effectively moves the  vApp. You cannot copy or move a vApp that is deployed. Example 4‐19 copies the vApp referenced by http://vcloud.example.com/api/v1.0/vApp/vApp‐201 to the vDC  referenced by http://vcloud.example.com/api/v1.0/vdc/5 and provides a new name and description for the  copy. Because the IsSourceDelete element in the request body contains a value of false, the source vApp  is unaffected by the copy operation. (The default value of IsSourceDelete is false. The example includes it  for illustrative purposes only.) The response is a Task element owned by the copy. Example 4-19. Copy a vApp Request: POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVApp Content-Type: application/vnd.vmware.vcloud.cloneVAppParams+xml <CloneVAppParams name="New Linux Server" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Cloned from Ubuntu FTP Server</Description> <Source href=”http://vcloud.example.com/api/v1.0/vApp/vApp-201”/> <IsSourceDelete>false</IsSourceDelete> </CloneVAppParams> VMware, Inc.

  • Page 53: Changing A Name Or Description

    Change the Name or Description of a vAppTemplate Example 4‐20 changes the description of the vApp template shown in Example 3‐6 on page Example 4-20. Change the Name and Description of a vAppTemplate Request: PUT http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111 Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml <VAppTemplate xmlns="http://www.vmware.com/vcloud/v1 name="Ubuntu 9.10" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"> <Description>Ubuntu 9.10 Server Edition, with vsftpd</Description> </VAppTemplate> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml...

  • Page 54: 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 <Media name="database.iso" size="242131" imageType="iso" xmlns="http://www.vmware.com/vcloud/v1"> <Description>New description</Description> </Media> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ...> </Task> Delete a vAppTemplate, vApp, or Media Image You can use an HTTP DELETE request to delete a vAppTemplate, vApp, or media image. All of these ...
  • Page 55 161. POST the CatalogItem body to the rel="add" URL included in the Catalog body. Example 4‐22 adds a CatalogItem to the catalog listed in Example 3‐2 on page Example 4-22. Add an Item to a Catalog Request: POST http://vcloud.example.com/api/v1.0/catalog/32/catalogItems Content-Type: application/vnd.vmware.vcloud.catalogItem+xml <CatalogItem name="Ubuntu Template with vsftpd" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Approved template for public FTP sites</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Property key="Owner">Tech Ops</Property> </CatalogItem> Response: 201 Created Content-Type: application/vnd.vmware.vcloud.catalogItem+xml <CatalogItem name="Ubuntu Template with vsftpd"...

  • Page 56: Remove An Item From A Catalog

    Controlling Access An organization administrator can use controlAccess links to control access to catalogs and vApps. Control Access to Catalogs When you list the contents of an organization, each catalog includes access control links, as shown in  Example 4‐24, which is an excerpt from Example 3‐1 on page Example 4-24. Access Control Links for a Catalog <Org ... > <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess/"/> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/37" name="Shared Catalog"/>...
  • Page 57 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 <ControlAccessParams ...> <IsSharedToEveryone>false</IsSharedToEveryone> </ControlAccessParams> Because the value of IsSharedToEveryone is false, the administrator must grant access to individual users  or groups, specified by reference. In Example 4‐26, the administrator POSTs a modified version of the  ControlAccessParams element received in Example 4‐25 to the catalog’s access control URL. The  modifications populate the AccessSettings container with two AccessSetting elements, each of which  assigns an access level to a specific user. Example 4-26. Granting Catalog Access to Users Request: POST http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess Content-Type: application/vnd.vmware.vcloud.controlAccess+xml...
  • Page 58 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 <ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1"> <IsSharedToEveryone>true</IsSharedToEveryone> <EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel> </ControlAccessParams> Response: 200 OK Content-Type: application/vnd.vmware.vcloud.controlaccess+xml <ControlAccessParams ...> <IsSharedToEveryone>true</IsSharedToEveryone> <EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel> </ControlAccessParams> Access control for vApps is implemented in a similar way. See Example 5‐36 on page VMware, Inc.

  • Page 59: Datacenter Operations

    API‐URL/vApp/vm‐id (for a Vm object) Table 5-1. Summary of Datacenter Operations Requests Operation Request Request Body Response Instantiate a vApp Template POST API‐URL/vdc/id/action/ InstantiateVAppTemplateParams VApp instantiateVAppTemplate Retrieve vApp Template  GET API‐URL/vAppTemplate/ None CustomizationSection CustomizationSection vappTemplate‐id/ customizationSection Modify vApp Template  PUT API‐URL/vAppTemplate/ CustomizationSection Task CustomizationSection vappTemplate‐id/ customizationSection Compose a vApp POST API‐URL/vdc/id/action/ ComposeVAppParams VApp composeVApp VMware, Inc.

  • Page 60: Vapp Lifecycle

    Provide Requested User  POST API‐URL/vApp/vm‐id/ VmQuestionAnswer 204 No Content Input question/action/answer Get a Screen Thumbnail for a  GET API‐URL/vApp/vm‐id/ None screen thumbnail  Virtual Machine screen (Content‐type: image/png) Get a Screen Ticket for a  POST API‐URL/vApp/vm‐id/ None ScreenTicket Virtual Machine screen/action/acquireTicket Control Access to vApps POST  ControlAccessParams ControlAccessParams API‐URL/vApp/vapp‐id/action/ controlAccess Retrieve a Task GET API‐URL/task/id None Task vApp Lifecycle A vApp contains one or more Vm elements, which represent individual virtual machines. It also contains  information that defines operational details for the vApp and the virtual machines it contains. The vApp  lifecycle includes several distinct states:  An OVF package, the form in which vApps are typically made available for download and distribution  A vApp template, created when a client uploads an OVF package to a vDC VMware, Inc.

  • Page 61: Instantiate A Vapp Template

    <VApp Template...status=”8” href=”http://.../vapp Template-3”> </VApp Template> instantiate vApp <VApp...status=”8” deployed=“false” href=”http://.../vapp-9”> <Link rel=”deploy”...> </VApp> deploy vApp <VApp...status=”8” deployed=“true” href=”http://.../vapp-9”> <Link rel=”power:powerOn”...> </VApp> OVF upload and the creation of vApp templates is covered in “Upload OVF to Create a vApp Template” on  page 42. Instantiate a vApp Template A vApp template specifies a set of files, such as virtual disks, that the vApp requires, and a set of abstract  resources, such as CPU, memory, and network connections, that must be allocated to the vApp by the vDC in  which it is deployed. Instantiation creates a vApp from the files specified in the template, and allocates  vDC‐specific bindings for networks and other resources. (These bindings are advisory; they do not guarantee  that the resources will be available when the vApp is deployed.) Instantiation is a prerequisite to deployment.  In the most common use case, a client instantiates a vApp template and immediately deploys it. VMware, Inc.

  • Page 62: About Instantiation Parameters

     A Configuration element that specifies the organization network to which the vApp network connects  and a FenceMode value that controls how those two networks are connected. Instantiating a vAppTemplate Using Default Parameters An instantiation request can supply a minimal InstantiateVAppTemplateParams element to specify that  instantiation should use the target vDC’s default bindings (see “Instantiating the Template in the vDC” on  page 24). This type of request can be appropriate for a vApp that has simple requirements for storage,  network, and compute resources. A vApp instantiated in this way can be reconfigured if necessary to correct  problems caused by a default instantiation. For more information, see “Reconfiguring vApps and Virtual  Machines” on page 69. Instantiating a vApp Template Using Additional Parameters If a client wants to specify vApp instantiation parameters in detail, rather than relying on vDC defaults, it can  include the details in the body of the instantiateVAppTemplate request.  The instantiation request takes the form of a POST to a vDC’s instantiateVAppTemplate URL. The request  body is an InstantiateVAppTemplateParams element. To obtain the information required in an InstantiateVAppTemplateParams element, the client must take  several steps:  Examine the template’s OVF to discover any EULA sections that it includes. The  InstantiateVAppTemplateParams element can include an AllEULAsAccepted element whose value  indicates whether all EULA terms included in the template were accepted. If a vApp template includes  any EULA sections, AllEULAsAccepted must be set to a value of true. Otherwise, instantiation fails.  Examine the template’s ovf:StartupSection element to verify that the prescribed startup order for  children does not need to be modified. VMware, Inc.
  • Page 63 25, but includes  an AllEULAsAccepted element that denotes acceptance of terms and conditions embedded in the child Vm  elements, and a LeaseSettingsSection element that specifies custom deployment and storage lease terms  for this vApp. It also specifies that the vApp should be deployed and powered on after it is instantiated. (If  you omit the deploy and powerOn attributes, the default value of false is assumed.) Example 5-1. Instantiating a vApp Template wIth Custom Lease Settings Request: POST http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml <InstantiateVAppTemplateParams name="Linux FTP server" deploy=”true” powerOn=”true” xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Example FTP Server</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="vAppNetwork">...

  • Page 64: Retrieve Or Modify The Customizationsection Of A Vapp Template

    Response: 200 OK Content-type: application/vnd.vmware.vcloud.customizationSection+xml <CustomizationSection xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ovf:required="false" vcloud:href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/ customizationSection/" vcloud:type="application/vnd.vmware.vcloud.customizationSection+xml" ...> <ovf:Info>VApp template customization section</ovf:Info> <CustomizeOnInstantiate>true</CustomizeOnInstantiate> <Link rel="edit" type="application/vnd.vmware.vcloud.customizationSection+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/ customizationSection/"/> </CustomizationSection> To change the value of CustomizeOnInstantiate, PUT a CustomizationSection body that has the changed  value to the section’s rel="edit" URL, as shown in Example 5‐3. Example 5-3. Modify vApp Template CustomizationSection Request: PUT http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection Content-type: application/vnd.vmware.vcloud.customizationSection+xml <CustomizationSection xmlns="http://www.vmware.com/vcloud/v1"...

  • Page 65: Compose A Vapp

    The composed vApp must be deployed and powered on before it can be used. Example 5‐4 shows a composeVApp request that specifies two vAppTemplate sources and one Vm source. The  Vm source requires InstantiationParams that modify its NetworkConnectionSection to specify the vApp  network created for this vApp. The vAppTemplate sources inherit this setting from the base  InstantiationParams element (the one that appears before the first Item is specified). Example 5-4. Compose a vApp Request: POST http://vcloud.example.com/api/v1.0/vdc/5/action/composeVApp Content-Type: application/vnd.vmware.vcloud.composeVAppParams+xml <ComposeVAppParams name="Example Corp’s CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection>...

  • Page 66: Finding Virtual Machine Urls To Use In A Composition Item

    </Item> <Item> <Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-114"/> </Item> <Item> <Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-190"/> </Item> <AllEULAsAccepted>true</AllEULAsAccepted> </ComposeVAppParams> Response: 201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp name="Example Corp’s CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Composed CRM Appliance</Description> <Tasks> <Task ...> </Task> </Tasks> </VApp> The response is similar to the one shown in Example 5‐1, a sparsely populated vApp body that contains a Task ...

  • Page 67: Recompose A Vapp To Add Or Remove Virtual Machines

    Example 5-6. vApp Before Recomposition Request: GET http://vcloud.example.com/api/v1.0/vApp/vapp-33 Response: 200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml <VApp name="Example Corp’s CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Composed CRM Appliance</Description> <Children> <Vm status="8" name="CRM-DB" href="http://vcloud.example.com/api/v1.0/vApp/vm-7" ...> </Vm> <Vm status="8" name="CRM-CRM" href="http://vcloud.example.com/api/v1.0/vApp/vm-44" ...>...

  • Page 68: Capture A Vapp To Create A Vapp Template

    The captureVApp request creates a vApp template from an instantiated vApp. The request body, shown in  Example 5‐8, is a captureVAppParams element that specifies the href of the vApp to capture, along with a  name and optional description for the template that the capture creates.    Before it can be captured, a vApp must be undeployed (deployed="false"). Example 5-8. Capture a vApp Request: POST http://vcloud.example.com/api/v1.0/vdc/5/action/captureVApp Content-Type: application/vnd.vmware.vcloud.captureVAppParams+xml <CaptureVAppParams name="Linux Server Template" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Template captured from Ubuntu vApp</Description> <Source href=”http://vcloud.example.com/api/v1.0/vApp/vApp-201”/> </CaptureVAppParams> Response: 201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml <VAppTemplate name="Linux Server Template"" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-20"...

  • Page 69: Reconfiguring Vapps And Virtual Machines

    GET API‐URL/vApp/vapp‐id/ None StartupSection startupSection/ Modify vApp Startup Section PUT API‐URL/vApp/vapp‐id/ StartupSection Task startupSection/ Retrieve vApp Network Section GET API‐URL/vApp/vapp‐id/ None ovf:NetworkSection networkSection/ Retrieve vApp Network Configuration GET API‐URL/vApp/vapp‐id/ None NetworkConfigSection networkConfigSection/ Modify vApp Network Configuration PUT API‐URL/vApp/vapp‐id/ NetworkConfigSection Task networkConfigSection/ You can reconfigure a vApp by making changes to any of the following sections:  LeaseSettingsSection  StartupSection  NetworkConfigSection Modified sections must contain all required elements, even if you are not changing their values. Some  elements in some sections are read‐only. See the schema references for details.    Each Vm in the vApp’s Children collection includes additional links for configuring its guest operating  system, virtual hardware, and other properties. For clarity, the Children are not shown in Example 5‐9. To see  them, refer to Example 5‐12 on page VMware, Inc.
  • Page 70 GET http://vcloud.example.com/api/v1.0/vApp/vapp-7 Response: 200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml <VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Description>Example FTP Server</Description> <LeaseSettingsSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/leaseSettingsSection/" ovf:required="false"> <ovf:Info>VApp lease settings</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.leaseSettingsSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/ leaseSettingsSection/"/> <DeploymentLeaseInSeconds>3600</DeploymentLeaseInSeconds> <StorageLeaseInSeconds>3600</StorageLeaseInSeconds> <DeploymentLeaseExpiration>2010-01-21T13:50:59.764-08:00</DeploymentLeaseExpiration> </LeaseSettingsSection> <ovf:StartupSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/startupSection/"> <ovf:Info>VApp startup section</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.startupSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/startupSection/"/>...
  • Page 71 5‐11 modifies the  section and applies the changes. Changes to the StartupSection or LeaseSettingsSection can use the  same procedure. Example 5-10. Retrieve vApp Network Configuration Request: GET http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/ Response: 200 OK Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml <NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/"/> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> <IsInherited>true</IsInherited> <Gateway>10.147.56.253</Gateway> <Netmask>255.255.255.0</Netmask> <Dns1>10.147.115.1</Dns1> <Dns2>10.147.115.2</Dns2> <DnsSuffix>example.com</DnsSuffix> <IpRanges>...
  • Page 72 <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> <IsInherited>false</IsInherited> <Gateway>10.147.56.253</Gateway> <Netmask>255.255.255.0</Netmask> <Dns1>10.147.115.1</Dns1> <Dns2>10.147.115.2</Dns2> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.56.1</StartAddress> <EndAddress>10.147.56.1</EndAddress> </IpRange> </IpRanges> </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>natRouted</FenceMode> <Features> <FirewallService> <IsEnabled>true</IsEnabled> <FirewallRule> <IsEnabled>true</IsEnabled> <Description>FTP Rule</Description> <Policy>allow</Policy> <Protocols> <Tcp>true</Tcp> </Protocols> <Port>21</Port> VMware, Inc.

  • Page 73: Reconfigure A Virtual Machine

    <VAppScopedVmId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedVmId> <VmNicId>0</VmNicId> </OneToOneVmRule> </NatRule> </NatService> </Features> </Configuration> </NetworkConfig> </NetworkConfigSection> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... operation="Updating Virtual Application Linux FTP server (7)" ...> </Task> The response is a Task element. View or Modify vApp Lease Settings Lease settings apply to both vApps and vApp templates, although vApp templates do not include deployment  lease information (DeploymentLeaseInSeconds and DeploymentLeaseExpiration). Default vApp lease  settings are inherited from the organization that owns the vDC in which the vApp is deployed. You can  override these defaults in the InstantiateVAppTemplateParams request body (see “Instantiating a vApp  Template Using Additional Parameters” on page 62). You can view the lease settings by retrieving the vApp or  vAppTemplate representation. To modify them, use the edit link in the LeaseSettingsSection, as  described in “Reconfigure a vApp” on page 69.
  • Page 74 Task Virtual Hardware Section of a  virtualHardwareSection/disks Virtual Machine Retrieve Network Card Items  GET API‐URL/vApp/vm‐id/ None RasdItemsList from the Virtual Hardware Section  virtualHardwareSection/ of a Virtual Machine networkCards Modify Network Card Items of the  PUT API‐URL/vApp/vm‐id/ RasdItemsList Task Virtual Hardware Section of a  virtualHardwareSection/ Virtual Machine networkCards Retrieve Removable Media Drive  GET API‐URL/vApp/vm‐id/ None RasdItemsList Items from the Virtual Hardware  virtualHardwareSection/media Section of a Virtual Machine You can reconfigure a virtual machine (Vm element) by making changes to any of the following sections:  VirtualHardwareSection  OperatingSystemSection  NetworkConnectionSection  GuestCustomizationSection Modified sections must contain all required elements, even if you are not changing their values. Some  elements in some sections are read‐only. See the schema references for details. VMware, Inc.
  • Page 75 <Link rel="media:ejectMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/ action/ejectMedia"/> <Description/> <ovf:VirtualHardwareSection ... "> <ovf:System> </ovf:System> <ovf:Item vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/cpu" ... > <rasd:Description>Number of Virtual CPUs</rasd:Description> <rasd:ResourceType>3</rasd:ResourceType> <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/cpu"/> </ovf:Item> <ovf:Item vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/memory" ...> <rasd:Description>Memory Size</rasd:Description> <rasd:ResourceType>4</rasd:ResourceType> <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/memory"/> </ovf:Item>...
  • Page 76 API Programming Guide <Link rel="edit" type="application/vnd.vmware.vcloud.virtualHardwareSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/"/> <Link type="application/vnd.vmware.vcloud.rasdItemsList+xml" rel="edit href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/disks"/> <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/networkCards"/> </ovf:VirtualHardwareSection> <ovf:OperatingSystemSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ operatingSystemSection/"> <Link rel="edit" type="application/vnd.vmware.vcloud.operatingSystemSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ operatingSystemSection/"/> </ovf:OperatingSystemSection> <NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ networkConnectionSection/" ...> <ovf:Info>Specifies the available VM network connections</ovf:Info>...
  • Page 77 ...> <ovf:Info>Specifies the available VM network connections</ovf:Info> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.122.134</IpAddress> <IsConnected>false</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4 networkConnectionSection/"/> </NetworkConnectionSection> The modified NetworkConnectionSection in the request body changes the value in the IpAddress element. Example 5-14. Modify the Network Connection of a Virtual Machine Request: PUT "http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/ Content-type: application/vnd.vmware.vcloud.networkConnectionSection+xml <NetworkConnectionSection ...
  • Page 78 API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... operation="Updating Virtual Application Linux FTP server (7)" ...> </Task> 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. Retrieve the CPU Configuration of a Virtual Machine Request: GET http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/cpu...
  • Page 79 <ovf:Info>Specifies Guest OS Customization Settings</ovf:Info> <Enabled>false</Enabled> <ChangeSid>false</ChangeSid> <VirtualMachineId>4</VirtualMachineId> <JoinDomainEnabled>false</JoinDomainEnabled> <UseOrgSettings>false</UseOrgSettings> <AdminPasswordEnabled>false</AdminPasswordEnabled> <AdminPasswordAuto>true</AdminPasswordAuto> <ResetPasswordRequired>false</ResetPasswordRequired> <CustomizationScript/> <ComputerName>ubuntu10-x86</ComputerName> <Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/ guestCustomizationSection/"/> </GuestCustomizationSection> The modified GuestCustomizationSection in the request body changes the value of the  JoinDomainEnabled element to true. This change requires you to specify a domain to join, along with the  name and password of a domain administrator, so the request body includes DomainName, DomainUserName,  and DomainUserPassword elements. Example 5-18. Modify the Guest Customization Section of a Virtual Machine Request: PUT http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection Content-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml <GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml"...

  • Page 80: Deploying And Controlling Vapps And Virtual Machines

    API Programming Guide <Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/ guestCustomizationSection/"/> </GuestCustomizationSection> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... operation="Updating Virtual Application Win2K3 (12)" ...> </Task> View or Modify Groups of Related Sections in a Vm As shown in Example 5‐12 on page 75, Link elements for disks, media devices, and network cards are grouped  at the end of the VirtualHardwareSection. These links have content type  application/vnd.vmware.vcloud.rasdItemsList+xml, and reference a RasdItemsList element in the  VirtualHardwareSection of a Vm. The vCloud API uses the RasdItemsList element to aggregate related ...

  • Page 81: Undeploy A Vapp Or Virtual Machine

    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 <DeployVAppParams powerOn="true" xmlns="http://www.vmware.com/vcloud/v1"/> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... operation="Starting Virtual Application Linux FTP server (7) ...> </Task> Undeploy a vApp or Virtual Machine Undeploying a vApp powers off or suspends any running virtual machines it contains, then frees the ...

  • Page 82: Power Off A Vapp Or Virtual Machine

    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 <Task ... operation="Starting Virtual Application Linux FTP server (7) ...> </Task> Power Off a vApp or Virtual Machine A powerOff request to a vApp URL powers off all of the virtual machines in the vApp, as specified in its  ovf:StartupSection element. A powerOff request to a virtual machine URL powers off the specified virtual machine.

  • Page 83: Suspend A Vapp Or Virtual Machine

    Chapter 5 Datacenter Operations Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ...> </Task> 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.0/vApp/vapp-7/power/action/suspend Request to suspend a Vm: POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/suspend Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ...>...

  • Page 84: Shut Down A Vapp Or Virtual Machine

    POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/shutdown Request to shut down a Vm: POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/shutdown Response: 204 No Content Reboot a vApp or Virtual Machine A reboot request to a vApp URL reboots all of the virtual machines in the vApp, as specified in its  ovf:StartupSection element. A reboot request to a virtual machine URL reboots the specified virtual machine.    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-27. Reboot a vApp or Virtual Machine Request to reboot a vApp: POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reboot Request to reboot a Vm: POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/reboot Response: 204 No Content VMware, Inc.

  • Page 85: List Media Devices Of A Virtual Machine

    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 <RasdItemsList xmlns="http://www.vmware.com/vcloud/v1" ... href="http://vcloud.example.com/api/v1.0/vApp/vm-5/virtualHardwareSection/media" ... > <Item> <rasd:Address>0</rasd:Address> <rasd:Description>IDE Controller</rasd:Description> <rasd:ElementName>IDE Controller 0</rasd:ElementName> <rasd:InstanceID>1</rasd:InstanceID> <rasd:ResourceType>5</rasd:ResourceType>...

  • Page 86: Eject Media From A Virtual Machine

    API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ...> </Task> 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. Eject Media from a Virtual Machine Request: POST http://vcloud.example.com/api/v1.0/vapp/vm-5/media/action/ejectMedia Content-Type: application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml <MediaInsertOrEjectParams xmlns="http://www.vmware.com/vcloud/v1"> <Media href="http://vcloud.example.com/api/v1.0/media/3"/>...

  • Page 87: Get A Screen Ticket For A Virtual Machine

    Example 5‐33 shows the link to the question, in the body of the vApp. Example 5-33. vApp Requesting Input Request: GET http://vcloud.example.com/api/v1.0/vApp/vapp-7 Response: 200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml <VApp name="Linux FTP server" status="5" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Link rel="down" type="application/vnd.vmware.vcloud.vmPendingQuestion+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-5/question"/> <Description>Example FTP Server</Description> <Children> </Children> </vApp> VMware, Inc.
  • Page 88 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 ... <VmPendingQuestion xmlns="http://www.vmware.com/vcloud/v1" ... > <Link type="application/vnd.vmware.vcloud.vmPendingAnswer+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-5/question/action/answer"/> <Question>msg.parallel.file.open:Parallel port output file "/vmfs/volumes/d6162a46-58e50cab/linuxftp/vm-mgi.log" already exists. Do you want to replace it with any newly created content, or append new content to the end of the file? </Question>...

  • Page 89: Control Access To Vapps

    Example 5‐37 retrieves that task that was returned in the response in Example 2‐6 on page Example 5-37. Retrieve a Task Request: GET http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey Response: 200 OK Content-Type: application/vnd.vmware.vcloud.task+xml <Task status="running" startTime="2010-06-25T08:00:55.402-07:00" operation="Creating Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey"> <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/> </Task> Tasks expire after a configurable interval. The default interval is 24 hours. VMware, Inc.
  • Page 90 API Programming Guide VMware, Inc.

  • Page 91: Administrative Operations

     API‐URL is a URL of the form http://vcloud.example.com/api/v1.0  id is an integer Table 6-1. Summary of Administrative Requests Operation Request Request Body Response Get an Administrative View of a  GET API‐URL/admin None VCloud Cloud Create an Organization POST API‐URL/admin/orgs AdminOrg AdminOrg Get an Administrative View of an  GET API‐URL/admin/org/id None AdminOrg Organization Modify an Organization PUT API‐URL/admin/org/id AdminOrg AdminOrg List All Tasks Owned by an  GET API‐URL/tasksList/id None TasksList Organization VMware, Inc.
  • Page 92 None 204 No Content Import a Group POST API‐URL/admin/org/id/groups Group Group View Group Metadata GET API‐URL/admin/group‐id None Group Modify Group Metadata PUT API‐URL/admin/group/id Group Group Remove a Group DELETE API‐URL/admin/group/id None 204 No Content Create a Role POST API‐URL/admin/roles Role Role View Role Metadata GET API‐URL/admin/role/id None Role Modify a Role PUT API‐URL/admin/role/id Role Role Remove a Role DELETE API‐URL/admin/role/id None 204 No Content View a Right GET API‐URL/admin/right/id None Right VMware, Inc.

  • Page 93: Administrator Credentials And Privileges

    API‐URL/ request, as shown in Example 6‐1. Example 6-1. The System Organization Request: GET http://vcloud.example.com/api/v1.0/org/1 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.org+xml <Org xmlns="http://www.vmware.com/vcloud/v1" name="System" ...> </Org> Administrative Objects and URLs The vCloud API defines several objects that are used only in administrative operations. These objects are listed  in Chapter 11, “Administrative API Reference,” on page 179. Some, like User, Group, and Role are unique to  administrative operations. Others extend common vCloud API objects to add elements and attributes that  enable administrative control. An AdminOrg, for example, supports the administrative view of an Org, and an  AdminVdc does the same thing for a Vdc. Get an Administrative View of a Cloud An administrator can access a cloud‐wide namespace of administrative objects at API‐URL/admin, where ...

  • Page 94: Organization Administration

    <OrganizationReference ... /> </OrganizationReferences> <ProviderVdcReferences> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <ProviderVdcReference ... /> </ProviderVdcReferences> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml name="vApp_Deploy" href="http://vcloud.example.com/api/v1.0/admin/right/3"/> <RightReference type="application/vnd.vmware.admin.right+xml name="Catalog: Sharing" href="http://vcloud.example.com/api/v1.0/admin/right/7"/> <RightReference ... /> </RightReferences> <RoleReferences> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Organization Administrator" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Catalog Creator" href="http://vcloud.example.com/api/v1.0/admin/role/103"/> <RoleReference ... />...

  • Page 95: Create An Organization

    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".  It includes links that an administrator can use to modify or remove the new organization. For example,  an administrator could use this Link to add a catalog. <Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/> Example 6-3. Create an Organization Request: POST http://vcloud.example.com/api/v1.0/admin/orgs Content-Type: application/vnd.vmware.admin.organization+xml <AdminOrg xmlns="http://www.vmware.com/vcloud/v1" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml"> <Description>Example Corporation’s Finance Organization</Description> <FullName>Finance</FullName> <Settings> <CanPublishCatalogs>true</CanPublishCatalogs> <DeployedVMQuota>0</DeployedVMQuota>...

  • Page 96: Get An Administrative View Of An Organization

    API Programming Guide <Link rel="add" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/vdcs"/> <Link rel="add" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/networks"/> <Link rel="edit" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/org/26/action/disable"/> <Link rel="alternate" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/26"/> <Description>Example Corporation’s Finance Organization</Description> <FullName>Finance</FullName> <Settings> <IsEnabled>false</IsEnabled> <CanPublishCatalogs>true</CanPublishCatalogs> <DeployedVMQuota>0</DeployedVMQuota> <StoredVmQuota>0</StoredVmQuota> <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>false</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>604800</DeploymentLeaseSeconds> <StorageLeaseSeconds>2592000</StorageLeaseSeconds>...

  • Page 97: List All Tasks Owned By An Organization

    Example 6-5. List All Tasks Owned by an Organization Request: GET http://vcloud.example.com/api/v1.0/tasksList/26 Response: 200 OK Content-Type: application/vnd.vmware.vcloud.tasksList+xml <TasksList name="Tasks Lists" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/18" ...> <Task... status="success" ... operation="Deleted Virtual Application Template (21)" ... > </Task> <Task... status="error" ... operation="Powered On Virtual Machine WIn2K8 (15)" ... > <Error stackTrace="com.vmware.ssdc.library.exceptions.VimInvalidStateException The operation could not be performed because the object is in an invalid state.

  • Page 98: Enable Or Disable An Organization

    <FullName>Finance</FullName> <Settings> <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>true</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>1209600</DeploymentLeaseSeconds> <StorageLeaseSeconds>7776000</StorageLeaseSeconds> </OrgLeaseSettings> <OrgLdapMode>SYSTEM</OrgLdapMode> </Settings> </AdminOrg> Response: 200 OK Content-Type: application/vnd.vmware.admin.organization+xml <AdminOrg name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml" ...> <Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/> <Link rel="add" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/users"/> <Settings> <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>true</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>1209600</DeploymentLeaseSeconds> <StorageLeaseSeconds>7776000</StorageLeaseSeconds> </OrgLeaseSettings> </Settings> </AdminOrg> Enable or Disable an Organization An administrator can use the enable or disable action links in an AdminOrg body to enable or disable an ...

  • Page 99: Remove An Organization

    6‐9 makes such a request to the href of a Network element returned in Example 6‐2 on  page 94. The response is an ExternalNetwork element that shows the Configuration and other properties  of the network, including a ProviderInfo element that specifies details of the underlying vSphere network.  The ExternalNetwork element is read‐only. Example 6-9. View the Properties of an External Network Request: GET http://vcloud.example.com/api/v1.0/admin/network/7 Response: 200 OK Content-Type:pplication/vnd.vmware.admin.network+xm <ExternalNetwork xmlns="http://www.vmware.com/vcloud/v1" href="http://vcloud.example.com/api/v1.0/admin/network/7" name="ExternalNetwork-VC1" ...> <Description>VLAN 7</Description> <Configuration> </Configuration> <ProviderInfo> NETWORK:dvportgroup-1587 on com.vmware.vcloud.entity.vimserver:1043863313 </ProviderInfo> </ExternalNetwork> VMware, Inc.

  • Page 100: Add A Network To An Organization

    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.    A NetworkPool element must be included in the request when creating network whose FenceMode is  natRouted or isolated. Example 6-10. Add a Network to an Organization Request: POST http://vcloud.example.com/api/v1.0/admin/org/26/networks Content-Type: application/vnd.vmware.admin.network+xml <OrgNetwork name="Internet" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Bridged to the public Internet</Description> <Configuration> <ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <FenceMode>bridged</FenceMode> </Configuration> </OrgNetwork> Response: 201 Created Content-Type: application/vnd.vmware.admin.network+xm <OrgNetwork xmlns="http://www.vmware.com/vcloud/v1"...

  • Page 101: Get An Administrative View Of An Organization Network

    Chapter 6 Administrative Operations <ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <FenceMode>bridged</FenceMode> </Configuration> </OrgNetwork> The response echoes the request, and contains some additional elements:  A Task that tracks creation of the network.  Additional members of the Configuration element that are inherited from the organization’s defaults,  because they were not specified in the request. The same request with a different value for FenceMode contents would create a network with a different type  of connection to the parent. For more information, see “FenceMode” on page 155. Get an Administrative View of an Organization Network To see an administrative view of an organization network, an administrator can make a GET request to the  network’s admin URL (the href element of the OrgNetwork body), as shown in Example 6‐11. The response,  most of which is not shown here, would be identical to the one shown in Example 6‐10, but without the Tasks  element. Example 6-11. Get an Administrative View of an Organization Network Request: GET http://vcloud.example.com/api/v1.0/admin/network/54...

  • Page 102: Remove An Organization Network

    </FirewallService> <NatService> <IsEnabled>false</IsEnabled> <NatType>portForwarding</NatType> <Policy>allowTraffic</Policy> </NatService> </Features> </Configuration> </OrgNetwork> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... operation="Updating Network Internet (2)" ...> </Task> Remove an Organization Network An organization administrator can use the remove link in an OrgNetwork body to remove the network from  the organization. Example 6‐13 does this, making a DELETE request to the remove link returned in  Example 6‐11. Example 6-13. Remove a Network from an Organization Request: DELETE http://vcloud.example.com/api/v1.0/admin/network/54...

  • Page 103: Examine The Contents Of A Provider Vdc

    <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocation>21929</Allocation> <Total>24675</Total> <Used>10053</Used> <Overhead>384</Overhead> </Cpu> <Memory> <Units>MB</Units> <Allocation>16207</Allocation> <Total>24475</Total> <Used>15771</Used> <Overhead>977</Overhead> </Memory> </ComputeCapacity> <StorageCapacity> <Units>MB</Units> <Allocation>1311368</Allocation> <Total>2097152</Total> <Used>489361</Used> <Overhead>2436</Overhead> </StorageCapacity> <AvailableNetworks> <Network type="application/vnd.vmware.admin.network+xml" name="External Network VC2" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> </AvailableNetworks> <IsEnabled>true</IsEnabled> <NetworkPoolReferences> <NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="VC2-Direct" href="http://vcloud.example.com/api/v1.0/admin/extension/ networkPool/22"/> VMware, Inc.

  • Page 104: List The Organization Vdcs Supported By A Provider Vdc

    94. The response, a VdcReferences element, indicates that the provider vDC at  http://vcloud.example.com/api/v1.0/admin/providervdc/2 is supporting the organization vDC,  http://vcloud.example.com/api/v1.0/admin/vdc/44, created in Example 6‐16. Example 6-15. List the Organization vDCs Supported by a Provider vDC Request: GET http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences Response: <VdcReferences xmlns="http://www.vmware.com/vcloud/v1" ... > <Link rel="up" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <VdcReference type="application/vnd.vmware.admin.vdc+xml" name="org3vdc1" href="http://vcloud.example.com/api/v1.0/admin/vdc/44"/> </VdcReferences> Allocate a vDC to an Organization An organization administrator can allocate resources from a provider vDC to a vDC in an organization by  POSTing an AdminVdc body to an organization’s add URL for vDCs. Example 6‐4 includes such a URL:...
  • Page 105 </ComputeCapacity> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> </AdminVdc> Response: 201 Created Content-Type: application/vnd.vmware.admin.vdc+xm <AdminVdc name="org26vdc1" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/vdc/44" ...> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="edit" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/vdc/44"/> <Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/vdc/44/action/disable"/> <Link rel="alternate" href="http://vcloud.example.com/api/v1.0/vdc/44"/> <Description>Example vDC</Description> <Tasks> <Task status="running" ... operation="Creating Virtual Datacenter (44)" ...>...

  • Page 106: Get An Administrative View Of A Vdc

    6‐3. Modify a vDC To modify a vDC, make a PUT request to its edit link, and supply a modified version of the Vdc body. In  Example 6‐17, the client modifies the vDC created in Example 6‐3 to change the values in the Cpu element, then  includes the modified body in a PUT request to the edit link that was returned when the vDC was created.  The response, only part of which is shown in the example, is an AdminVdc body containing the modified  values. Example 6-17. Modify a vDC Request: PUT http://vcloud.example.com/api/v1.0/admin/vdc/44 Content-Type: application/vnd.vmware.admin.vdc+xm <AdminVdc name="org3vdc1" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Example vDC</Description> <AllocationModel>AllocationPool</AllocationModel> <StorageCapacity> <Units>MB</Units> <Allocated>4096</Allocated> <Limit>8192</Limit> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>4096</Allocated> <Limit>4096</Limit> </Cpu>...

  • Page 107: Enable Or Disable A Vdc

    202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... operation="Deleted Virtual Datacenter (6)" ...> </Task> Catalog Administration A newly created organization has no catalogs in it. An organization administrator must create them and  specify their scope before items can be catalogued. You do not have to be an administrator to add or remove  CatalogItem elements. See “Cataloging vApp Templates and Media Images” on page 54. Create a Catalog Every organization has an add URL for catalogs. An administrator can create a catalog by POSTing a Catalog  body to this URL. Example 6‐19 does this, using the URL in this Link shown in Example 6‐3. <Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/> The response echoes the request, and includes these additions created by the server.  A URL (the value of the href attribute of the response body) that references the new catalog.  Links that a client can use to request operations like add an item to the catalog, edit catalog properties, or  remove the catalog.  A link to the alternate (user) view of this catalog  An empty CatalogItems element VMware, Inc.

  • Page 108: Get An Administrative View Of A Catalog

    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 <Catalog name="Custom Catalog" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Custom Catalog</Description> </Catalog> Response: 201 Created Content-Type: application/vnd.vmware.admin.catalog+xml <Catalog href="http://vcloud.example.com/api/v1.0/catalog/32" name="Custom Catalog" ...> <Description>Custom Catalog</Description> <Tasks> <Task ...>...

  • Page 109: Publish A Catalog

    6‐22 changes the name and  description of the catalog created in Example 6‐19. The response contains the modified Catalog body,  including the CatalogItems element, which was unchanged by, and not included in, the request. Example 6-22. Modify Catalog Metadata Request: PUT http://vcloud.example.com/api/v1.0/admin/catalog/32 Content-Type: application/vnd.vmware.admin.catalog+xml <Catalog name="TechOps Catalog 01" xmlns="http://www.vmware.com/vcloud/v1"> <Description>TechOps Approved Templates Catalog</Description> </Catalog> Response: 200 OK Content-Type: application/vnd.vmware.admin.catalog+xml <Catalog href="http://vcloud.example.com/api/v1.0/catalog/32" name="TechOps Catalog 01" ...> <Description>TechOps Approved Templates Catalog</Description> <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml"...

  • Page 110: Remove A Catalog

    User Administration Users can be created in an organization or imported into the organization from an LDAP directory service.  Create or Import a User Every user exists within the context of an organization. An administrator can add a user to an organization by  POSTing a User body to the organization’s add URL for users, as shown in Example 6‐24, which adds the user  to the organization created in Example 6‐3. The response is a User element, most of which is not shown in the  example. The element includes a link that an administrator can use to edit the user, and additional elements,  such as IsDefaultCached and StoredVmQuota, inherited from organization defaults. Example 6-24. Create a User Request: POST http://vcloud.example.com/api/v1.0/admin/org/26/users Content-Type: application/vnd.vmware.admin.user+xml <User name="ExampleUser" xmlns="http://www.vmware.com/vcloud/v1"> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <IsEnabled>true</IsEnabled> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <Password>Pa55w0rd</Password> </User> VMware, Inc.
  • Page 111 Chapter 6 Administrative Operations Response: 201 Created Content-Type: application/vnd.vmware.admin.user+xml <User name="ExampleUser" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <IsEnabled>true</IsEnabled> <IsAlertEnabled>false</IsAlertEnabled> <IsDefaultCached>false</IsDefaultCached> <StoredVmQuota>0</StoredVmQuota> <DeployedVmQuota>0</DeployedVmQuota> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <GroupReferences/> </User> To import a user from an LDAP directory service, POST a User body whose name attribute specifies the user’s  name in the LDAP directory, and includes an IsExternal element with a value of true. The server matches  the value of the name attribute in the request body with the value of the LDAP attribute that the organization  has specified for the user name (the value of the UserName element in UserAttributes), and imports that user  from LDAP. See “UserAttributes” on page 184. Example 6‐25 illustrates this sort of request.

  • Page 112: Get An Administrative View Of A User

    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. Get an Administrative View of a User Request: GET http://vcloud.example.com/api/v1.0/admin/user/85 Response: 200 OK Content-Type: application/vnd.vmware.admin.user+xml <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <Telephone/> <IsEnabled>true</IsEnabled> <IM/> <NameInSource>user@example.com</NameInSource>...

  • Page 113: Remove A User

    DELETE http://vcloud.example.com/api/v1.0/admin/user/85 Response: 204 No Content Group Administration Groups must be imported from LDAP. You cannot use the vCloud API to add or remove group members, or  change the name of the group. Instead, you must make the changes in the source LDAP database and then  import the group again. Import a Group To import a group from an LDAP directory service, POST an empty Group body to the organization’s add URL  for groups. The value of the name attribute in the request body must match the value of the group’s name  attribute in LDAP. Example 6-29. Import a Group from LDAP Request: POST http://vcloud.example.com/api/v1.0/admin/org/26/groups Content-Type: application/vnd.vmware.admin.group+xml <Group name="Engineering" xmlns="http://www.vmware.com/vcloud/v1"> <Role type="application/vnd.vmware.admin.role+xml" name="vApp Wrangler" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> </Group> VMware, Inc.

  • Page 114: View Group Metadata

    API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.admin.user+xml <Group name="Engineering" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/group/44" ...> <Link rel="edit" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/group/44"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/group/44"/> <Description>Research and development</Description> <UsersList/> <Role type="application/vnd.vmware.admin.role+xml" name="vApp Wrangler" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> </Group> View Group Metadata Each group in an organization can be referenced by the URL contained in one of its GroupReference  elements. These elements are contained by the Groups element of an AdminOrg body. A group’s URL also  appears in the response to the request that imports the group. An administrator can GET a group URL to view  the Group body. Modify Group Metadata An administrator can modify a Group body to change its Description or Role by PUTting a modified Group  body to the edit URL for the group. See Example 6‐27 for an example of the workflow for this type of request.

  • Page 115: View Role Metadata

    201 Created Content-Type: application/vnd.vmware.admin.role+xml <Role name="vAppWrangler" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102" ...> <Link rel="edit" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Description>Create and manage vApps</Description> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: View" href="http://vcloud.example.com/api/v1.0/admin/right/16"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Power Operations" href="http://vcloud.example.com/api/v1.0/admin/right/9"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Download" href="http://vcloud.example.com/api/v1.0/admin/right/11"/> <RightReference ... />...

  • Page 116: Modify A Role

    API Programming Guide <Link rel="edit" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Description>Create and manage vApps</Description> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: View" href="http://vcloud.example.com/api/v1.0/admin/right/16"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Power Operations" href="http://vcloud.example.com/api/v1.0/admin/right/9"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Download" href="http://vcloud.example.com/api/v1.0/admin/right/11"/> <RightReference ... /> </RightReferences> </Role> Modify a Role A system administrator can modify a role to add or remove rights or change the name of the role by PUTting ...

  • Page 117: Vmware Vsphere Platform Operations

    VMware vSphere Platform Operations The VMware vCloud API includes extensions that support a variety of operations on the vSphere Platform,  which provides resources to a VMware vCloud.    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. For more information, see  “Administrator Credentials and Privileges” on page 93. This chapter includes the following topics:  “Summary of vSphere Platform Operations Requests” on page 117  “List vSphere Platform Operations and Objects for a vCloud” on page 119  “List Provider vDCs in a vCloud” on page 120  “List Network Pools in a vCloud” on page 120  “List vCenter Servers Registered to a vCloud” on page 120  “List ESX/ESXi Hosts in a vCloud” on page 124  “Create a Provider vDC” on page 127  “Create an External Network” on page 133  “Create a Network Pool” on page 136 ...
  • Page 118 Task host/id/action/upgrade Create a Provider vDC POST API‐URL/admin/extension/ VMWProviderVdc VMWProviderVdc providervdcs Examine the vSphere  GET API‐URL/admin/extension/ None VMWProviderVdc Objects in a Provider  providervdc/id Modify a Provider vDC POST API‐URL/admin/extension/ VMWProviderVdc VMWProviderVdc providervdcs Enable or Disable a  POST API‐URL/admin/extension/ None 204 No Content Provider vDC providervdc/id/action/enable POST API‐URL/admin/extension/ providervdc/id/action/disable Remove a Provider  DELETE None Task API‐URL/admin/extension/ providervdc/id Create an External  POST API‐URL/admin/extension/ VMWExternalNetwork VMWExternalNetwork Network externalnets VMware, Inc.

  • Page 119: List Vsphere Platform Operations And Objects For A Vcloud

    Chapter 7 VMware vSphere Platform Operations Table 7-1. Summary of vSphere Platform Operations Requests (Continued) Operation Request Request Body Response Get Information About  GET API‐URL/admin/extension/ none VMWExternalNetwork an External Network externalnet/id Modify an External  PUT API‐URL/admin/extension/ VMWExternalNetwork VMWExternalNetwork Network externalnet/id Remove an External  DELETE none Task Network API‐URL/admin/extension/ externalnet/id Create a Network Pool POST API‐URL/admin/extension/...

  • Page 120: List Provider Vdcs In A Vcloud

    7‐2 makes such a request, using the  providerVdcReferences link returned in Example 7‐1. Example 7-2. List Provider vDCs in a vCloud Request: GET http://vcloud.example.com/api/v1.0/admin/extension/providerVdcReferences Response: 200 OK Content-Type: application/vnd.vmware.admin.vmwprovidervdcreferences+xml <vmext:VMWProviderVdcReferences xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... > <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwExtension+xml" href="http://vcloud.example.com/api/v1.0/admin/extension"/> <vmext:ProviderVdcReference type="application/vnd.vmware.admin.vmwprovidervdc+xml" name="PVDC-VC3" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/1"/> <vmext:ProviderVdcReference ... > <vmext:ProviderVdcReference ... > </vmext:VVMWProviderVdcReferences> List External Networks in a vCloud This operation follows the model shown in Example...

  • Page 121: List Available Resource Pools On A Vcenter Server

    Chapter 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 <vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC-02" ... > <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmsObjectRefsList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ vmsList"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.resourcePoolList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ resourcePoolList"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppParams+xml"...

  • Page 122: Modify Vcenter Server Settings

    Modify vCenter Server Settings A system administrator can change the values of name, Description, and IsEnabled for a vCenter server by  making a PUT request to the server’s edit URL. A system administrator must also modify the values of  Username, Password, and URL when any of those are changed on the server host. You cannot change those  values for the vCenter server by modifying its VimServer element, but you must update the element if you  make these changes to the server. Example 7‐5 disables the vCenter server shown in Example 7‐3 and also changes its Description. Example 7-5. Modify vCenter Server Settings Request: PUT http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100 Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml <vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC-02" type="application/vnd.vmware.admin.vmwvirtualcenter+xml"> <vcloud:Description>Temporarily disabled for maintenance</vcloud:Description> <vmext:Username>administrator</vmext:Username> <vmext:Url>http://10.147.40.234:443</vmext:Url> <vmext:IsEnabled>false</vmext:IsEnabled> </vmext:VimServer> Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ...

  • Page 123: Unregister A Vcenter Server And Vshield Manager

    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 <vmext:RegisterVimServerParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1"> <vmext:VimServer name="VC-22"> <vmext:Username>Administrator</vmext:Username> <vmext:Password>Pa55w0rd</vmext:Password> <vmext:Url>https://10.100.121.123:443</vmext:Url> <vmext:IsEnabled>false</vmext:IsEnabled> </vmext:VimServer> <vmext:ShieldManager name="VSM-VC-22"> <vmext:Username>Administrator</vmext:Username> <vmext:Password>Pa55w0rd</vmext:Password> <vmext:Url>https://10.100.121.66</vmext:Url> </vmext:ShieldManager> </vmext:RegisterVimServerParams> Response: 200 OK Content-Type: application/vnd.vmware.admin.registerVimServerParams+xml...

  • Page 124: Force Reconnection To A Vcenter Server

    7‐1. Example 7-9. List ESX/ESXi Hosts in a vCloud Request: GET http://vcloud.example.com/api/v1.0/admin/extension/hostReferences Response: 200 OK Content-Type: application/vnd.vmware.admin.vmwhostreferences+xml <vmext:VMWHostReferences xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... > <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwExtension+xml" href="http://vcloud.example.com/api/v1.0/admin/extension"/> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.12" href="http://vcloud.example.com/api/v1.0/admin/extension/host/180"/> <vmext:HostReference ... > <vmext:HostReference ... > </vmext:VMWHostReferences> Get Information About a Host A system administrator can use the href attribute value of any HostReference in a VMWHostReferences ...

  • Page 125: Prepare A Host

    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 <vmext:Host xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="10.115.121.14" href="http://vcloud.example.com/api/v1.0/admin/extension/host/22" ... > <vcloud:Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/extension/host/22/action/disable"/> <vcloud:Description/> <vmext:Ready>true</vmext:Ready> <vmext:Available>true</vmext:Available> <vmext:Enabled>true</vmext:Enabled> <vmext:Busy>false</vmext:Busy> <vmext:EnableHostForHostSpanning>true</vmext:EnableHostForHostSpanning> <vmext:CpuType>Intel(R) Xeon(R) CPU E5310 @ 1.60GHz</vmext:CpuType>...

  • Page 126: Unprepare A Host

    API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... operation="Preparing Host (1)" ...> </Task> 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. Unprepare a Host Request: POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/unprepare Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml <Task ... > </Task>...

  • Page 127: Upgrade A Host Agent

    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 <Task ... > </Task> Upgrade a Host Agent New releases of vCenter Cloud Director may include a new version of the host agent. A system administrator  can upgrade the host agent on a host to the version included in the current installation of Cloud Director by  making a POST request to the host’s action/upgrade URL. Example 7‐15 upgrades the host agent for the host  referenced by http://vcloud.example.com/api/v1.0/admin/extension/host/1. Example 7-15. Upgrade a Host Agent Request: POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/upgrade...
  • Page 128 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 <vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101" ...> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmsObjectRefsList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ vmsList"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.resourcePoolList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ resourcePoolList"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ importVmAsVApp"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml"...
  • Page 129 Chapter 7 VMware vSphere Platform Operations <vmext:MoRef>datastore-322</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef> <vmext:MoRef>datastore-350</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> </vmext:ResourcePool> </vmext:ResourcePoolList> You can use this information to get values for the DataStoreRefs and ResourcePoolRef elements in the  VMWProviderVdc, then POST the VMWProviderVdc body to the rel="add"link for providervdcs in the  VMWExtension element, as shown in Example 7‐18. Example 7-18. Create a Provider vDC Request: POST http://vcloud.example.com/api/v1.0/admin/extension/providervdcs Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml"> <vcloud:Description>New Provider vDC</vcloud:Description> <vcloud:ComputeCapacity>...
  • Page 130 <vcloud:Memory> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>16207</vcloud:Allocation> <vcloud:Total>24475</vcloud:Total> <vcloud:Used>15771</vcloud:Used> <vcloud:Overhead>977</vcloud:Overhead> </vcloud:Memory> </vcloud:ComputeCapacity> <vcloud:StorageCapacity> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>1311368</vcloud:Allocation> <vcloud:Total>2097152</vcloud:Total> <vcloud:Used>489361</vcloud:Used> <vcloud:Overhead>2436</vcloud:Overhead> </vcloud:StorageCapacity> <vcloud:AvailableNetworks> <vcloud:Network type="application/vnd.vmware.admin.network+xml" name="External Network VC2" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> </vcloud:AvailableNetworks> <vcloud:IsEnabled>false</vcloud:IsEnabled> <vcloud:NetworkPoolReferences> <vcloud:NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="s-org-vdc-vc2-DirectNET" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/ 22"/> <vcloud:NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="Netpool_VC2_VLAN_Backed" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/2"/> </vcloud:NetworkPoolReferences> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2"...

  • Page 131: Examine The Vsphere Objects In A Provider Vdc

    Chapter 7 VMware vSphere Platform Operations </vmext:VimObjectRef> </vmext:DataStoreRefs> <vmext:ResourcePoolRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:MoRef>resgroup-220</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> </vmext:ResourcePoolRef> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:HostReferences> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.11" href="http:// vcloud.example.com/api/v1.0/admin/extension/host/1"/> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.9" href="http:// vcloud.example.com/api/v1.0/admin/extension/host/2"/> </vmext:HostReferences> </vmext:VMWProviderVdc> The response echoes the request but now has a status attribute whose value is initially 0 and an href  attribute whose value is the URL of the new provider vDC. It also includes some additional elements created  by the server:  Link elements for actions and related references  A Task element that tracks creation of the provider vDC. When the task completes, the value of the ...

  • Page 132: Enable Or Disable A Provider Vdc

    <vcloud:Allocation>18944</vcloud:Allocation> <vcloud:Total>2260224</vcloud:Total> </vcloud:StorageCapacity> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/ 101"/> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> <vmext:ResourcePoolRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:MoRef>resgroup-220</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> </vmext:ResourcePoolRef> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> </vmext:VMWProviderVdc> Response: 200 OK Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml" ... > </vmext:VMWProviderVdc>...

  • Page 133: Create An External Network

    Chapter 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 <Task ... operation="Deleting Provider Virtual Datacenter (43)" ...> </Task> 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. Example 7‐22 does this by making a POST request to the externalnets link  returned in Example 7‐1. The content of the VimPortGroupRef element in the request body specifies that  vCenter portgroup that supports the new external network.    You must use the VMware vSphere API to obtain the values you need to populate the  VimPortGroupRef element.

  • Page 134: Get Information About An External Network

    API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="alternate" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/27"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Description>Portgroup-25 on VC-100</vcloud:Description> <vcloud:Tasks> <vcloud:Task status="running"... operation="Creating External Network ExternalNet-VC100(27)" href="http:// vcloud.example.com/api/v1.0/task/579"/> </vcloud:Tasks> </vmext:VMWExternalNetwork> The response echoes the request and includes Link elements for actions and related references, and a Task ...

  • Page 135: Modify An External Network

    Chapter 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. Modify an External Network Request: PUT http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27 Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Description>Description>Portgroup-25 on VC-100</vcloud:Description> <vcloud:Configuration> <vcloud:IpScope> <vcloud:IsInherited>false</vcloud:IsInherited> <vcloud:Gateway>10.147.58.253</vcloud:Gateway> <vcloud:Netmask>255.255.255.0</vcloud:Netmask>...

  • Page 136: Create A Network Pool

    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 <Task ... operation="Deleting External Network (27)" ...> </Task> 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. Example 7‐26 creates a network pool of the VlanPoolType by making a POST  request to the networkPools link returned in Example 7‐1. Requests to create network pools of other types  (FencePoolType and PortGroupPoolType) follow a similar pattern.    You must use the VMware vSphere API to obtain the values you need to populate the VimSwitchRef  element. Example 7-26. Create a Network Pool Request: POST http://vcloud.example.com/api/v1.0/admin/extension/networkPools...

  • Page 137: Get Information About A Network Pool

    Chapter 7 VMware vSphere Platform Operations <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvs-28</vmext:MoRef> <vmext:VimObjectType>DV_SWITCH</vmext:VimObjectType> </vmext:VimSwitchRef> </vmext:VMWNetworkPool> Get Information About a Network Pool A system administrator can use the href attribute value of any NetworkPoolReference or VMWNetworkPool  element to get more information about the network pool. Example 7‐27 retrieves information about the  network pool created in Example 7‐26. The entire VMWNetworkPool body is returned in the response, but only  part of the response is shown in the example Example 7-27. Get Information About a Network Pool Request: GET http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41 Response: 200 OK <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"...

  • Page 138: Remove A Network Pool

    API Programming Guide Response: 200 OK <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool"> <vmext:VMWNetworkPool> 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. Example 7-29. Remove a Network Pool Request: DELETE http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41 Response: 204 No Content Import a Virtual Machine from vCenter A system administrator can import virtual machines from any vCenter registered to a vCloud. The virtual ...

  • Page 139: Import A Virtual Machine As A Vapp

    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. The syntax  for the query specification is: GET API-URL/admin/extension/vimServer/id/vmsList?page= &pageSize= where p represents an integer page number (starting with 1) and s represents an integer page size. The request  shown in Example 7‐30 could be rewritten as shown in Example 7‐31 to return the first ten entries in the  vmsList. Example 7-31. vmsList with Page Number and Page Size Query Request: GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/vmsList?page=1&pageSize=10 To return the complete list of virtual machines, make additional requests that increment the value of page. Import a Virtual Machine as a vApp To import a virtual machine as a vApp, a system administrator can make a request to the importVmAsVApp ...

  • Page 140: Import A Virtual Machine As A Vapp Template

    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. The response is an unresolved vAppTemplate body  containing a task that tracks the import. Example 7-33. Import a Virtual Machine as a vApp Template Request: POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVappTemplate Content-type: application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml <ImportVmAsVAppTemplateParams xmlns="http://www.vmware.com/vcloud/extension/v1" name="ImportedWin2K8-Template" sourceMove="false"> <VmMoRef>vm-642</VmMoRef> <Vdc href="http://vcloud.example.com/api/v1.0/vdc/2"/> <Catalog href="http://vcloud.example.com/api/v1.0/catalog/32"/> </ImportVmAsVAppTemplateParams> Response: 201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml <VAppTemplate status="0"...

  • Page 141: Xml Representations In The Vcloud Api

    8‐1. Table 8-1. Schema Reference Table Columns Name Type Description Name of an element or  Minimum number of  Maximum number of  Type of the attribute or  Description of the  attribute contained.  this attribute or  this attribute or  element, either a  attribute or element Element names begin  element required by  element allowed by the  primitive XML  with an uppercase  the schema. schema. A value of n  datatype or a complex  character. Attribute  means that the  type defined by the  names begin with a  maximum number is  vCloud API. lowercase character. unlimited. VMware, Inc.

  • Page 142: Content Type

    Objects such as vApp templates, vApps, and Vms have href values of the form API‐URL/xxxxxx/yyy‐id For each prototype, API‐URL has the form http://vcloud.example.com/api/v1.0, and id is an integer. An  object href prototype is included in the reference information for each object type that has an href attribute. Common Datatypes The vCloud API uses a number of primitive XML datatypes, as defined in W3C Recommendation 28  (http://www.w3.org/TR/xmlschema‐2/). It also defines a number of complex types, of which vCloud API  elements are instances. Primitive XML Datatypes Attributes and some element content are represented by primitive XML datatypes, which are shown in  Table 8‐2.  Table 8-2. Primitive XML Data Types Used by the vCloud API Value Description xs:boolean A logical value, including true, false, 0, and 1. xs:date Date values. xs:dateTime Date/time values (timestamps). xs:double  Numeric value that corresponds to the IEEE double‐precision 64‐bit floating point type  defined in IEEE 754‐1985. VMware, Inc.

  • Page 143: Complex Types

    Optional description of the object Tasks TasksInProgressType Read‐only container for Task elements. Each element in  the container represents a queued, running, or failed task  owned by this object. Successfully completed tasks are not  listed. IpAddressType The IpAddressType imposes a pattern on the primitive xs:string type. The pattern defines an IPv4 address: <xs:pattern value = "((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0 -9][0-9]|[1-9][0-9]|[0-9])"/> Attributes of this type are invalid unless they conform to the pattern ReferenceType Many container elements are populated with references to contained objects. Each reference consists of a  hyperlink, an optional media type, and a name. Schema Name Type Description href xs:anyURI Hyperlink to the referenced object type xs:string Object type, expressed as the media type of the XML  representing of the object name xs:string Name of the referenced object. Common Attributes Elements such as Org, Catalog, and vDC have a number of common attributes. With the exception of name,  none of these attributes are required in request bodies, and are ignored if included. All of them are included  in response bodies. VMware, Inc.

  • Page 144: Name

    142. status Objects such as vAppTemplate, vApp, and Vm, that extend the ResourceEntity type have a status attribute  whose value indicates the state of the object, as shown in Table 8‐4, where YES indicates that a status value is  allowed for the object listed in the column header. Status for an object, such as a vAppTemplate or vApp, whose  Children (Vm objects) each have a status of their own, is computed from the status of the Children.    The deployment status of an object is indicated by the value of its deployed attribute. Table 8-4. vAppTemplate, vApp, and Vm status Attribute Values Value Description vAppTemplate vApp ‐1 The object could not be created. The object is unresolved. The object is resolved. The object is deployed. † The object is suspended. YES  † The object is powered on. YES  † The object is waiting for user input. YES  The object is in an unknown state. The object is in an unrecognized state. VMware, Inc.

  • Page 145: Xml Namespace Identifiers

    Not required in request bodies. CIM_VirtualSystemSettingData xsi:schemaLocation An installation‐dependent schema location search path.  Not required in request bodies. For more information, see  http://www.w3.org/TR/xmlschema‐0/#schemaLocation xmlns:xsi http://www.w3.org/2001/XMLSchema‐instance Not required in request bodies. XML namespace identifiers are omitted from most of the example responses (see “About the Examples” on  page 19). Example 8‐1 shows how they appear in a typical response body. Example 8-1. Response Body Showing XML Namespace Identifiers <VApp xmlns="http://www.vmware.com/vcloud/v1" status="8" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 http://vcloud.example.com/api/v1.0/schema/master.xsd"> </vApp> VMware, Inc.

  • Page 146: Common Elements

    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. Common Elements The vCloud API defines a number of elements that can be contained by the representations of many kinds of  objects. Description The Description element contains a string that describes the object. This element is always optional. Error Error elements are used to transmit read‐only error information in a response. Content-Type application/vnd.vmware.vcloud.error+xml Schema Name Type Description message xs:string Message describing the error majorErrorCode xs:int Matches the HTTP status code. See “Status Codes” on page 18. minorErrorCode xs:string Error code specific to the failed operation...

  • Page 147: Link

    API schema version information appears in the values of the xsi:schemaLocation and xmlns  attributes in a response document. For example, a response body that used schema version 1.0 would include  the following attributes: xsi:schemaLocation="http://vcloud.example.com/api/v1.0/schema/master.xsd" xmlns="http://www.vmware.com/vcloud/v1" To discover the schema versions supported by a server, a client can make an unauthenticated GET request to  a well‐known URL on the server, as shown in Example 8‐2. The response to this kind of request is a  SupportedVersions document, from which the client can derive information about the media types and  schema locations used by the version of the API that the server supports. The response contains a  MediaTypeMapping element for each media type defined by the API. (The example shows only a few of these  elements.) The response also includes a LoginUrl element, which contains a URL that a client can use to obtain  an authentication token. For more information about using the LoginUrl, see “Authentication” on page 18. Example 8-2. API Version Request Request: GET http://vcloud.example.com/api/versions Response: 200 OK Content-Type: text/xml <SupportedVersions ...> <VersionInfo> <Version>1</Version> <LoginUrl>http://vcloud.example.com/api/v1/login</LoginUrl> <MediaTypeMapping> <MediaType>application/vnd.vmware.vcloud.org+xml</MediaType> <ComplexTypeName>CatalogType</ComplexTypeName> <SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation> </MediaTypeMapping> <MediaTypeMapping> VMware, Inc.

  • Page 148: Supportedversions

    URL for logging in to this version MediaTypeMapping MediaTypeMappingType Media type of the referenced object. Links to  actions do not have a media type. MediaTypeMapping A MediaTypeMapping element defines the name, MIME content type, and schema location of a complex type  supported by this version of the vCloud API.  This element is read‐only. Schema Name Type Description MediaType xs:string MIME content type of this complex type ComplexTypeName xs:string Name of this complex type SchemaLocation xs:anyURI URL for the XML schema definition document that defines  this complex type Extensibility The vCloud API is designed to be extensible. All complex types defined by the API extend a single abstract  complex type. This complex type and all types based on it can include zero or more instances of an extension  element that can contain an arbitrary number of elements and attributes.  VCloudExtensibleType is an abstract type that all complex types defined in the vCloud API namespace  (http://www.vmware.com/vcloud/v1) extend. This type allows custom attributes to be added to any type and  supports definition of custom elements within the VCloudExtension element. The VCloudExtension element has an attribute named required that specifies how clients and servers  proceed when they see unknown extension. The required attribute is optional but if omitted is assumed to  be present with a value of true. That is to say, all VCloudExtension elements are assumed to require a server  that understands them. VMware, Inc.

  • Page 149: Vcloudextension

    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. If the element declares  required=”true” and 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. A server  must return a failure when a request includes a VCloudExtension element that declares required=”true”  but the server does not understand the extension. Schema Name Type Description required xs:boolean True if this extension must be understood by the server any attribute name xs:any An arbitrary number of attributes of any type any element name xs:any An arbitrary number of elements of any type VMware, Inc.
  • Page 150 API Programming Guide VMware, Inc.

  • Page 151: User Api Reference

    “Catalog” on page 160  “Media” on page 161  “VAppTemplate” on page 161  “VApp” on page 162  “Vm” on page 163  “Section” on page 163  “ScreenTicket” on page 168  “TasksList” on page 168 OrgList An OrgList element is a container for references to organizations. It is returned in the response to a successful  login or a GET API‐URL/org request, and contains a reference to each organization to which the logged‐in user  has access. This element is read‐only. Content-Type application/vnd.vmware.vcloud.orgList+xml Object href prototype API‐URL/org The Org element represents the user view of a vCloud organization object, which is a container and unit of  administration for resources and users. Content-Type application/vnd.vmware.vcloud.org+xml VMware, Inc.

  • Page 152: Vdc

    Includes type, href, XML namespace identifiers Link LinkType Links to actions and contained objects Description xs:string Optional description Tasks TasksInProgressType Read‐only container for Task elements. Each element  in the container represents a queued, running, or  failed task owned by this object. FullName xs:string Full name of the organization A vDC is a deployment environment for vApps. A Vdc element provides a user view of a vDC. Content-Type application/vnd.vmware.vcloud.vdc+xml Object href prototype API‐URL/vdc/id Schema Name Type Description name xs:string Common object name attribute any attribute name Includes type, href, XML namespace identifiers status xs:int The creation status of the vDC:  -1 creation failed  0 not ready ...

  • Page 153: Storagecapacity

    Schema Name Type Description CapacityWithUsageType Reports CPU resource consumption in a vDC Memory CapacityWithUsageType Reports memory resource consumption in a vDC The Cpu element reports CPU resource consumption in a vDC. Schema Name Type Description Used xs:long Percentage of the allocation in use. This value is read‐only. Overhead xs:long Number of Units allocated to vShield Manager virtual machines provisioned  from this vDC. This value is read‐only. Memory The Memory element reports memory resource consumption in a vDC. Schema Name Type Description Used xs:long Percentage of the allocation in use. This value is read‐only. Overhead xs:long Number of Units allocated to vShield Manager virtual machines provisioned  from this vDC. This value is read‐only. AvailableNetworks The AvailableNetworks element is a read‐only container for OrgNetwork elements. Network Each Network element contains a reference to an OrgNetwork object in the same organization as this vDC. VMware, Inc.

  • Page 154: Resourceentities

    If an upload or download of this file is in progress, this  attribute indicates the number of bytes that have been  transferred by the upload or download checksum xs:normalizedString Ignored in this release Description xs:string Optional description Tasks TasksInProgressType Read‐only container for Task elements. Each element in  the container represents a queued, running, or failed  task owned by this object. OrgNetwork An OrgNetwork element defines a network that has been allocated to an organization by the system  administrator. Content-Type application/vnd.vmware.vcloud.network+xml Object href prototype API‐URL/network/id Schema Name Type Description name xs:string Common object name attribute any attribute name Includes type, href, XML namespace  identifiers Description xs:string Optional description VMware, Inc.

  • Page 155: Configuration

    FenceMode The FenceMode element defines how this network is connected to its ParentNetwork. Table 9‐1 shows  permitted values for element content and the results they produce. Table 9-1. FenceMode Element Values Value Result bridged The two networks are bridged isolated The two networks are not connected. natRouted The two networks are connected as specified in their NatService elements. IpScope The IpScope element defines the address range, gateway, netmask, and other properties of the network. Schema Name Type Description IsInherited xs:boolean True if the values in this IpScope element are  inherited from the ParentNetwork of the  containing Configuration Gateway IpAddressType IP address of the network gateway Netmask IpAddressType Netmask to apply to addresses on the network Dns1 IpAddressType IP address of the primary DNS server for this  network VMware, Inc.
  • Page 156 DhcpServiceType Specifies the properties of the network’s DHCP service FirewallService FirewallServiceType Defines the firewall service capabilities of the network NatService NatServiceType Defines the NAT service capabilities of the network DhcpService The DhcpService element specifies the properties of the network’s DHCP service. Schema Name Type Description IsEnabled xs:boolean True if the service is enabled DefaultLeaseTime xs:int Default duration of a DCHP address lease MaxLeaseTime xs:int Maximum duration of a DCHP address lease. IpRange IpRangeType Range of IP addresses available to DHCP clients FirewallService The FirewallService element defines the firewall service capabilities of a network. Schema Name Type Description IsEnabled xs:boolean True if the service is enabled FirewallRule FirewallRuleType Defines a single firewall rule VMware, Inc.
  • Page 157 Table 9-2. FirewallRule Policy Element Values Value Result drop Drop packets of this type Allow packets of this type to pass through the firewall allow Protocols The Protocols element specifies the protocols to which firewall rules apply. Schema Name Type Description xs:boolean True if the firewall rules apply to the TCP protocol xs:boolean True if the firewall rules apply to the UDP protocol NatService The NatService element defines the network address translation capabilities of a network. Schema Name Type Description IsEnabled xs:boolean True if the service is enabled NatType NatTypeType Specifies how Network Address Translation is  implemented by the NAT service Policy NatPolicyType Specifies how packets are handled by the NAT service NatRule NatRuleType Specifies a single NAT rule VMware, Inc.
  • Page 158 OneToOneBasicRule NatOneToOneBasicRuleType Ignored in this release OneToOneVmRule NatOneToOneVmRuleType Specifies network address translation details for  a single virtual machine PortForwardingRule NatPortForwardingRuleType Maps an IP address and port in an organization  network to an external IP address and port VmRule NatVmRuleType Maps an IP address and port in a vApp network  to an external IP address and port OneToOneVmRule The OneToOneVmRule element describes a NAT rule that specifies network address translation details for a  single virtual machine. The external IP address can be specified manually or assigned automatically at  deployment time. The internal IP address is discovered by looking up the specified VmReference and NIC ID. Schema Name Type Description MappingMode NatMappingModeType Specifies how IP address mapping is implemented by  the NAT service ExternalIP IpAddressType If MappingMode is manual, specifies the external IP  address of this Vm VAppScopedVmId xs:string Read‐only identifier created on import VmNicId xs:int Device number of the NIC on the referenced virtual  machine VMware, Inc.
  • Page 159 InternalPort xs:int Network port to which this NAT rule maps the port number  specified in the ExternalPort element. Protocol Layer4ProtocolType Specifies the network protocol to which this rule applies VmRule The VmRule element describes a NAT rule that maps an IP address and port in a vApp network to an external  IP address and port. The external IP address, external port, and internal port are specified in the element. The  internal IP address is discovered by looking up the specified VmReference and VmNicId. Schema Name Type Description ExternalIP IpAddressType IP address to which this NAT rule maps the IP address  specified in the InternalIP element. ExternalPort xs:int The network port to which this NAT rule maps the port  number specified in the InternalPort element. VAppScopedVmId xs:string Read‐only identifier created on import VmNicId xs:int The device number of the NIC on the referenced virtual  machine. InternalPort xs:int The network port to which this NAT rule maps the port  number specified in the ExternalPort element. Protocol Layer4ProtocolType Specifies the network protocol to which this rule applies VMware, Inc.

  • Page 160: Catalog

    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 The rule applies to the TCP protocol The rule applies to the UDP protocol The rule applies to the TCP and UDP protocols TCP_UDP Catalog A Catalog element is a container for CatalogItems. An organization can contain zero or more catalogs. Users  with appropriate privileges can add or remove CatalogItem elements from a catalog. Content-Type application/vnd.vmware.vcloud.catalog+xml Object href prototype API‐URL/catalog/id Schema Name Type Description name xs:string Common object name attribute any attribute name Includes type, href, XML namespace identifiers Link LinkType Links to actions and contained objects Description xs:string Optional description...

  • Page 161: Media

    Key associated with the string value contained in the  element. The length of the key cannot exceed 80  characters. The length of the value cannot exceed 256  characters. Example 9‐1 illustrates the use of the Property element in a CatalogItem. Example 9-1. CatalogItem With Property Elements <CatalogItem <Property key="Originator">Example Corp.</Property> <Property key="Project">Redwood</Property> </CatalogItem> Media The Media element represents virtual media, such as an ISO or floppy image. Content-Type application/vnd.vmware.vcloud.media+xml Object href prototype API‐URL/media/id Schema Name Type Description name xs:string Common object name attribute any attribute name Includes type, href, XML namespace identifiers status xs:int Creation status of the object...

  • Page 162: Children

    Any of the following ovf:Section_Type elements:  LeaseSettingsSection  StartupSection  NetworkConfigSection  CustomizationSection VAppScopedLocalId xs:string Read‐only identifier created on import Children The Children element is a read‐only container for the virtual machines (Vm elements) that are members of a  vApp or vAppTemplate. VApp A VApp element represents a vApp, which is the result of instantiation of a vApp template. Content-Type application/vnd.vmware.vcloud.vApp+xml Object href prototype API‐URL/vApp/vapp‐id Schema Name Type Description deployed xs:boolean True if the vApp is deployed status xs:int Creation status of the vApp name xs:string Common object name attribute ovfDescriptorUploaded xs:boolean True if the associated OVF descriptor has been ...

  • Page 163: Section

    Type Description Section ovf:Section_Type Any of the following ovf:Section_Type elements:  LeaseSettingsSection  StartupSection  NetworkConfigSection  CustomizationSection Children VAppChildrenType Read‐only container for Vm elements representing  virtual machines A Vm represents a virtual machine, a member of a vApp’s Children container. Content-Type application/vnd.vmware.vcloud.vApp+xml Object href prototype API‐URL/vAppTemplate/vm‐id or API‐URL/vApp/vm‐id Schema Name Type Description deployed xs:boolean True if the Vm is deployed status xs:int Creation status of the Vm name xs:string Common object name attribute any attribute name Includes type, href, XML namespace identifiers Link LinkType Action links to operations...

  • Page 164: Leasesettingssection

    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.leaseSettingsSection+xml Schema Name Type Description ovf:required xs:boolean Optional indication of whether this element is required type xs:string Media type of this section href xs:anyURI URL to access this section ovf:Info ovf: Required by the base ovf:Section_Type. It can contain  Msg_Type xs:string information about the containing element, or  can be empty Link LinkType Configuration links DeploymentLeaseInSeconds xs:string Duration of the deployment lease, in seconds...

  • Page 165: Networkconfigsection

    Chapter 9 User API Reference Schema (Continued) Name Type Description CustomizeOnInstantiate xs:boolean If true, then customization is executed for all children that  include a GuestCustomizationSection. Default value is  false. Link LinkType Configuration links NetworkConfigSection The NetworkConfigSection element specifies the configuration of a vApp network. Content-Type application/vnd.vmware.vcloud.networkConfigSection+xml Schema Name Type Description ovf:required xs:boolean Optional indication of whether this element is  required type xs:string Media type of this section href xs:anyURI URL to access this section ovf:Info ovf:Msg_Type Required by the base ovf:Section_Type. It can  contain xs:string information about the ...
  • Page 166 IpAddressType If the network that the NIC is connected  to has NAT or port mapping, the  external address is populated in this  element. IsConnected xs:boolean If the vApp is deployed, specifies the  current state of its connection. If the  vApp is undeployed, specifies whether  this connection should be connected at  deployment time.  MACAddress xs:string MAC address of this connection IpAddressAllocationMode IpAddressAllocationModeType Specifies how an IP address is allocated  to this connection IpAddressAllocationMode The IpAddressAllocationMode element specifies how an IP address is allocated to this connection. Table 9‐7  shows permitted values for element content and the results they produce. Table 9-7. IpAddressAllocationMode Element Values Value Result NONE No IP addressing mode specified MANUAL Static IP address assigned manually POOL Static IP address allocated from a pool DHCP IP address assigned by DHCP VMware, Inc.

  • Page 167: Virtualhardwaresection

    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.operatingSystemSection+xml GuestCustomizationSection The GuestCustomizationSection element of a Vm contains customization parameters for the guest  operating system of the virtual machine. Content-Type application/vnd.vmware.vcloud.guestCustomizationSection+xm Schema Name Type Description ovf:required xs:boolean Optional indication of whether this element is required type xs:string Media type of this section href xs:anyURI URL to access this section ovf:Info ovf:Msg_Type Required by the base ovf:Section_Type. It can contain  xs:string information about the containing element, or  can be empty Link LinkType Configuration links...

  • Page 168: Rasditemslist

    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.vcloud.screenTicket+xml TasksList The TasksList element is a read‐only container for Task elements that represent queued, running, or recently  completed tasks owned by a member of the organization that contains the TasksList. Content-Type application/vnd.vmware.vcloud.tasksList+xml Tasks The Tasks element is a read‐only container for Task elements owned by the containing object. Tasks shown  in this element also appear in the TasksList of the organization that contains the object. Task Whenever the result of a request cannot be returned immediately, the server creates a Task object. Tasks  owned by an object such as a vApp or vDC are contained in the Tasks element of the object’s XML  representation. Each Task in a Tasks or TasksList element contains all the information about the task. A GET  request to an individual task’s href does not return any additional information about the task. This element is read‐only. Content-Type application/vnd.vmware.vcloud.taskt+xml Schema Name Type Description status TaskStatusType The current status of the task. One of:  queued The task has been queued for execution.
  • Page 169 Chapter 9 User API Reference Schema (Continued) Name Type Description Owner 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 ErrorType Error message or related information returned by the task VMware, Inc.
  • Page 170 API Programming Guide VMware, Inc.

  • Page 171: Request Parameters Reference

     “CloneMediaParams” on page 176  “CloneVAppTemplateParams” on page 176  “CloneVAppParams” on page 176  “MediaInsertOrEjectParams” on page 177  “VmPendingQuestion” on page 177  “VmQuestionAnswer” on page 177  “ControlAccessParams” on page 177 UploadVAppTemplateParams The UploadVAppTemplateParams element forms the body of an uploadVappTemplate request. Content-Type application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml Schema Name Type Description name xs:string Specifies the name given to the template Description xs:string Description of the template transferFormat xs:string Ignored in this release manifestRequired xs:boolean True if the upload includes a manifest file...

  • Page 172: Instantiatevapptemplateparams

    API Programming Guide InstantiateVAppTemplateParams The InstantiateVAppTemplateParams element forms the body of an instantiateVappTemplate request. Content-Type application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml Schema Name Type Description name xs:string Specifies the name of the vApp created by this  instantiation linkedClone xs:boolean Ignored in this release deploy xs:boolean True if the vApp should be deployed after  instantiation. Defaults to false. powerOn xs:boolean True if the vApp should be deployed and powered on  after instantiation. Defaults to false. Description xs:string Optional description. Used for the Description of the  vApp created by this instantiation. VAppParent ReferenceType Unsupported in this release Source ReferenceType A reference to the vApp template to instantiate IsSourceDelete xs:boolean True if the object referenced by Source should be ...

  • Page 173: Composevappparams

    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.composeVAppParams+xml Schema Name Type Description name xs:string Specifies the name of the vApp created by this  composition Description xs:string Optional description. Used for the  Description of the composed vApp deploy xs:boolean True if the vApp should be deployed after  composition. Defaults to false. powerOn xs:boolean True if the vApp should be deployed and  powered on after composition. Defaults to ...

  • Page 174: Networkassignment

    For more information, see “Compose a vApp” on page 65. NetworkAssignment When a vApp includes Vm elements that connect to networks with different names, you can use a  NetworkAssignment element to assign the network connection for each Vm to a specific network in the parent  vApp. Schema Name Type Description innerNetwork xs:string Name of the network in the Vm containerNetwork xs:string Name of the vApp network to which innerNetwork is mapped RecomposeVAppParams The RecomposeVAppParams element forms the body of a recomposeVapp request. This element allows an  arbitrary number of DeleteItem elements, but is otherwise identical to ComposeVAppParams.  Content-Type application/vnd.vmware.vcloud.recomposeVAppParams+xml Schema Name Type Description name xs:string Specifies the name of the vApp created by this  composition Description xs:string Optional description. Used for the  Description of the composed vApp deploy xs:boolean True if the vApp should be deployed after  composition. Defaults to false. powerOn xs:boolean True if the vApp should be deployed and ...

  • Page 175: Deployvappparams

    Schema (Continued) Name Type Description Item CompositionItemParamsType Specifies a source vAppTemplate, vApp, or Vm  to include in the composition DeleteItem ReferenceType Reference to a Vm to remove from the vApp AllEULAsAccepted 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. Content-Type application/vnd.vmware.vcloud.deployVAppParams+xml Schema Name Type Description powerOn xs:boolean True if the vApp should be powered on after deployment deploymentLeaseSeconds xs:int Duration of the deployment lease, in seconds UndeployVAppParams The UndeployVAppParams element forms the body of an undeploy request. Content-Type application/vnd.vmware.vcloud.undeployVAppParams+xml Schema Name Type Description saveState xs:boolean True if powered‐on children should be suspended and their state saved ...

  • Page 176: Clonemediaparams

    API Programming Guide CloneMediaParams The CloneMediaParams element forms the body of a cloneMedia request. Content-Type application/vnd.vmware.vcloud.cloneMediaParams+xml Schema Name Type Description name xs:string Specifies the name of the new media image created by the clone  operation Description xs:string Optional description. Used for the Description of the cloned  Media image. Source ReferenceType Reference to the media image to clone (copy) IsSourceDelete xs:boolean True if the object referenced by Source should be deleted after  the copy is made CloneVAppTemplateParams The CloneVAppTemplateParams element forms the body of a cloneVAppTemplate request. Content-Type application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml Schema Name Type Description name xs:string Specifies the name of the new vApp template  created by the clone operation...

  • Page 177: Mediainsertorejectparams

    Chapter 10 Request Parameters Reference Schema (Continued) Name Type Description Source ReferenceType Reference to the vApp to clone (copy) IsSourceDelete 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.mediaInsertOrEjectParams+xml Schema Name Type Description Media ReferenceType Reference to a media image to insert or eject VmPendingQuestion The VmPendingQuestion element contains a request from a virtual machine for user input. Content-Type application/vnd.vmware.vcloud.vmPendingQuestion+xml Schema Name Type Description Question xs:string The question requiring use input. QuestionId xs:int Question identifier...

  • Page 178: Accesssettings

    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. Schema Name Type Description Subject ReferenceType Reference to the user or group to which the specified AccessLevel  applies. AccessLevel AccessLevelType Specifies the access level allowed for the user or groups specified in  Subject AccessLevel The AccessLevel element specifies the access level allowed for the user or group specified in Subject.  Table 10‐1 shows permitted values for element content and the results they produce. Table 10-1. AccessLevel Element Values Value Result FullControl Subject has full control of this object Change Subject can change this object ReadOnly Subject has read access to this object VMware, Inc.

  • Page 179: Administrative Api Reference

    “VCloud” on page 179  “ExternalNetwork” on page 180  “AdminOrg” on page 180  “ProviderVdc” on page 186  “User” on page 190  “Group” on page 191  “Role” on page 191 VCloud The vCloud element is a read‐only container for references to top‐level objects in a vCloud instance. Content-Type application/vnd.vmware.admin.vcloud+xml Object href prototype API‐URL/admin Schema Name Type Description OrganizationReferences OrganizationReferencesType A container for references to AdminOrg objects  in the vCloud ProviderVdcReferences ProviderVdcReferencesType A container for references to ProviderVdc  objects in the vCloud RightReferences RightReferencesType A container for references to Right objects in ...

  • Page 180: Organizationreferences

    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. RightReferences The RightReferences element is a read‐only container for ReferenceType elements that reference the  predefined Right objects in a vCloud. RoleReferences The RoleReferences element is a read‐only container for ReferenceType elements that reference Role  objects in a vCloud. To create a role, see “Create a Role” on page 114. Networks The Networks element is a read‐only container for ReferenceType elements that reference ExternalNetwork  objects in a vCloud. To add a network to an AdminOrg, see “Add a Network to an Organization” on page 100. ExternalNetwork A ExternalNetwork element defines a network that has been allocated to an organization by the system  administrator. Content-Type application/vnd.vmware.vcloud.admin.network+xml Object href prototype API‐URL/admin/network/id Schema Name Type Description name xs:string Common object name attribute any attribute name Includes type, href, XML namespace  identifiers Description xs:string Optional description Configuration NetworkConfigurationType Properties of the network...

  • Page 181: Settings

    CanPublishCatalogs xs:boolean True if this organization is allowed to publish  catalogs DeployedVmQuota xs:int Maximum number of virtual machines that can  be deployed simultaneously by a member of  this organization StoredVmQuota xs:int Maximum number of vApps or vApp templates  that can be stored (in an undeployed state) by a  member of this organization OrgLeaseSettings OrgLeaseSettingsType Defines default lease durations and related  policies OrgLdapMode LdapModeType Defines whether this organization is connected  to an LDAP service, and whether it uses the  system default LDAP service or a custom LDAP  service. Cannot be changed after the  organization has been created. CustomUsersOu xs:string If OrgLdapMode is SYSTEM, specifies an LDAP  attribute=value pair to use for OU  (organizational unit) OrgLdapSettings OrgLdapSettingsType Defines the hostname and connection details for  the organization’s primary LDAP service OrgEmailSettings OrgEmailSettingsType Defines the email settings for this organization VMware, Inc.
  • Page 182 Table 11-1. OrgLdapMode Element Values Value Result NONE Organization does not use an LDAP service. SYSTEM Organization uses the system default LDAP service. CUSTOM Organization uses a custom LDAP service defined in OrgLdapSettings OrgLdapSettings If OrgLdapMode is CUSTOM, the OrgLdapSettings element defines the hostname and connection details for the  organization’s LDAP service. Schema Name Type Description HostName xs:string Hostname of the LDAP server. Port xs:int Port at which to connect to the LDAP  service IsSsl xs:boolean True if the LDAP service requires an  SSL connection IsSslAcceptAll xs:boolean True if the LDAP service accepts all SSL  certificates Realm xs:string LDAP realm to use when looking up  users SearchBase xs:string LDAP search base VMware, Inc.
  • Page 183 OrgLdapGroupAttributesType Defines how LDAP attributes are used  when importing a group AuthenticationMechanism The AuthenticationMechanism element defines the authentication mechanism used by the LDAP service.  Table 11‐2 shows permitted values for element content and the results they produce. Table 11-2. AuthenticationMechanism Element Values Value Result LDAP connection uses simple authentication as specified in RFC 2251 and RFC 2829. SIMPLE KERBEROS LDAP connection uses Kerberos authentication. MD5DIGEST LDAP connection uses Digest‐MD5 authentication as specified in RFC 2831. NTLM LDAP connection uses Windows NTLM authentication. ConnectorType The ConnectorType element defines the type of an LDAP service. Table 11‐3 shows permitted values for  element content and the results they produce. Table 11-3. ConnectorType Element Values Value Result ACTIVE_DIRECTORY LDAP service is provided by Windows Active Directory http://www.openldap.org). OPEN_LDAP LDAP service is provided by OpenLDAP (see  VMware, Inc.
  • Page 184 LDAP attribute to use for the user’s telephone  number. For example telephoneNumber GroupMembershipIdentifier xs:string LDAP attribute that identifies a user as a member of  a group. For example, dn GroupBackLink xs:string LDAP attribute that returns the identifiers of all the  groups of which the user is a member GroupAttributes If OrgLdapMode is CUSTOM, the GroupAttributes element defines how a group is imported from LDAP. Schema Name Type Description ObjectClass xs:string LDAP objectClass of which imported groups are members. For  example, group ObjectIdentifier xs:string LDAP attribute to use as the unique identifier for a group. For  example, objectGuid GroupName xs:string LDAP attribute to use for the group name. For example, cn Membership xs:string LDAP attribute to use when getting the members of a group. For  example, member MembershipIdentifier xs:string LDAP attribute that identifies a group as a member of another  group. For example, dn BackLinkIdentifier xs:string LDAP group attribute used to identify a group member VMware, Inc.

  • Page 185: Users

    SmtpServerSettings If IsDefaultSmtpServer (in OrgEmailSettings) is false, the SmtpServerSettings element specifies  connection details for the organization’s SMTP server. Schema Name Type Description SMTP server requires authentication IsUseAuthentication xs:boolean True if the  Host xs:string Hostname of the SMTP server. Username xs:string Username to use when logging in to the SMTP service.  (Required if IsUseAuthentication is True). Password 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. Required if  IsUseAuthentication is true. Users The Users element is a read‐only container for ReferenceType elements that reference users in an  organization. To add users to an organization, see “Create or Import a User” on page 110. Groups The Groups element is a read‐only container for ReferenceType elements that reference groups in an  organization. To add groups to an organization, see “Import a Group” on page 113. Catalogs The Catalogs element is a read‐only container for ReferenceType elements that reference the catalogs in an  organization. To add catalogs to an organization, see “Create a Catalog” on page 107. VMware, Inc.

  • Page 186: Catalog

    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. For information about  user operations on Catalogs, see “Cataloging vApp Templates and Media Images” on page 54. PublishCatalogParams The PublishCatalogParams element forms the body of a publish request for a catalog. Schema Name Type Description IsPublished xs:boolean Set to true to publish a catalog (make it visible to all organizations). Set to  false to unpublish a catalog. This element can be changed only in a publish  request. It is Read‐only in a Catalog body. Vdcs The Vdcs element is a read‐only container for ReferenceType elements that reference vDCs in an  organization. To add a vDC to an organization, see “Allocate a vDC to an Organization” on page 104. ProviderVdc A ProviderVdc element represents a provider vDC object. Content-Type application/vnd.vmware.admin.providervdc+xml Object href prototype API‐URL/admin/providervdc/id...

  • Page 187: Computecapacity

    Allocation xs:long Number of Units that have been allocated to consumers Total xs:long Maximum number of Units that can be allocated to all consumers Used xs:long Percentage of the allocation in use. This value is read‐only. Overhead xs:long Number of Units allocated to vShield Manager virtual machines provisioned  from this vDC. This value is read‐only. Memory Unlike the Memory element that appears in the ComputeCapacity of a Vdc, the Memory element that appears  in the ComputeCapacity of a ProviderVdc is an instance of ProviderVdcCapacityType. It defines the  memory capacity that can be allocated from a vDC and optionally reports how much of that capacity is in use. Schema Name Type Description Units xs:string Specifies the units in which the capacity is measured. For storage devices, this is  always Megabytes, represented by the string MB. Allocation xs:long Number of Units that have been allocated to consumers Total xs:long Maximum number of Units that can be allocated to all consumers Used xs:long Percentage of the allocation in use. This value is read‐only. Overhead xs:long Number of Units allocated to vShield Manager virtual machines provisioned  from this vDC. This value is read‐only. VMware, Inc.

  • Page 188: Storagecapacity

    Number of Units that have been allocated to consumers Total xs:long Total number of Units that can be allocated to all consumers Used xs:long Percentage of the allocation in use. This value is read‐only. Overhead xs:long Number of Units allocated to vShield Manager virtual machines provisioned  from this provider vDC. This value is read‐only. NetworkPoolReferences The NetworkPoolReferences element is a read‐only container for NetworkPoolReference elements. NetworkPoolReference A NetworkPoolReference element is a ReferenceType element that references a network pool in a provider  vDC. This element is read‐only. VdcReferences The VdcReferences element is a read‐only container for VdcReference elements that reference organization  vDCs supported by this provider vDC. Content-Type application/vnd.vmware.vcloud.admin.vdcreferences+xml Schema Name Type Description any attribute name Includes type, href, XML namespace  identifiers Link LinkType Link to containing provider vDC VdcReference ReferenceType Reference to an organization vDCs  supported by this provider vDC AdminVdc The AdminVdc element provides an administrative view of a vDC. It includes all members of the Vdc element,  and adds several elements that can be viewed and modified only by administrators. Content-Type application/vnd.vmware.admin.vdc+xml Object href prototype API‐URL/admin/vdc/id...
  • Page 189 Maximum number of virtual machines  that can be deployed in this vDC.  Defaults to 0, which specifies an  unlimited number. IsEnabled xs:boolean True if this vDC is enabled ResourceGuaranteedMemory xs:double Percentage of allocated memory  resources guaranteed to vApps  deployed in this vDC. For example, if  this value is 0.75, then 75% of allocated  resources are guaranteed. Required  when AllocationModel is  AllocationVApp or AllocationPool.  Value defaults to 1.0 if the element is  empty. ResourceGuaranteedCpu xs:double Percentage of allocated CPU resources  guaranteed to vApps deployed in this  vDC. For example, if this value is 0.75,  then 75% of allocated resources are  guaranteed. Required when  AllocationModel is AllocationVApp  or AllocationPool. Value defaults to  1.0 if the element is empty. VCpuRatingMHz xs:long Specifies a clock frequency, in  Megahertz, for each virtual CPU core  provisioned from this vDC IsThinProvision xs:boolean True if thin provisioning has been  enabled for this vDC VMware, Inc.

  • Page 190: Allocationmodel

    AllocationModel The AllocationModel element defines how resources are allocated in a vDC. Table 11‐4 shows permitted  values for element content and the results they produce. Table 11-4. AllocationModel Element Values Value Result AllocationVApp Resources are committed to a vDC only when vApps are created in it Only a percentage of the resources you allocate are committed to the organization vDC. AllocationPool ReservationPool All the resources you allocate are committed as a pool to the organization vDC. vApps in vDCs  that support this allocation model can specify values for resource and limit. User A User object defines a member of an organization or group. Content-Type application/vnd.vmware.admin.user+xml Object href prototype API‐URL/admin/user/id Schema Name Type Description name xs:string Common object name attribute. The name of the user. any attribute name Includes type, href, XML namespace identifiers Description xs:string Optional description FullName xs:string User’s full name.

  • Page 191: Group

    Description Role ReferenceType A reference to the user’s role. When you are creating a  User, the request body must contain exactly one Role  element. Password xs:string The user’s password. 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. GroupReferences GroupsListType Container for ReferenceType elements that reference  groups of which this user is a member Group A Group object defines a group. Content-Type application/vnd.vmware.admin.group+xml Object href prototype API‐URL/admin/group/id Schema Name Type Description name xs:string Common object name attribute. The Group’s name. any attribute name Includes type, href, XML namespace identifiers Description xs:string Optional description NameInSource xs:string Group name as retrieved from, and in the encoding  used by, LDAP...

  • Page 192: Right

    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.right+xml Object href prototype API‐URL/admin/right/id Schema Name Type Description name xs:string Name of the right Description xs:string Optional description of the right. Category xs:string Optional category name VMware, Inc.

  • Page 193: Vsphere Platform Extensions Reference

     “ShieldManager” on page 196  “VMWProviderVdc” on page 197  “VMWNetworkPool” on page 198  “VMWExternalNetwork” on page 199  “VMWHostReferences” on page 199  “Request Parameters” on page 200 VMWExtension The VMWExtension element is a read‐only container for links to vCenter servers registered to Cloud Director  and vSphere objects such as ESX/ESXi hosts, resource pools and networks. Content-Type application/vnd.vmware.admin.vmwExtension+xml Object href prototype API‐URL/admin/extension Schema Name Type Description href xs:anyURI Object reference type xs:string Media type of the element  (application/vnd.vmware.admin.vmwExtension+xml) any attribute name Includes XML Namespace Identifiers.

  • Page 194: Vmwprovidervdcreferences

    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.vmwExternalNetworkReferences+xml Object href prototype API‐URL/admin/extension/externalNetworkReferences VMWNetworkPoolReferences The VMWNetworkPoolReferences element is a read‐only container for NetworkPoolReference elements. Content-Type application/vnd.vmware.admin.vmwNetworkPoolReferences+xml Object href prototype API‐URL/admin/extension/networkPoolReferences VMWVimServerReferences The VMWVimServerReferences element is a read‐only container for VimServerReference elements. Content-Type application/vnd.vmware.admin.vmwVimServerReferences+xml Object href prototype API‐URL/admin/extension/vimServerReferences VMWHostReferences The VMWHostReferences element is a read‐only container for HostReference elements. Content-Type application/vnd.vmware.admin.vmwHostReferences+xml Object href prototype API‐URL/admin/extension/hostReferences...

  • Page 195: Vmobjectrefslist

    URL, including port, to use when connecting to this  vCenter server with a vSphere client IsEnabled xs:boolean True if the server is enabled for use with Cloud  Director IsConnected xs:boolean True if this vCenter is ready to be used by the  vCloud ShieldManagerIP xs:anyURI IP address of the associated vShield Manager ShieldManagerUserName xs:string User name of vShield Manager administrator VmObjectRefsList The VmObjectRefsList element is a read‐only container for VmObjectRef elements. Content-Type application/vnd.vmware.admin.vmsobjectrefslist+xml Object href prototype API‐URL/admin/extension/vimServer/id/vmsList VimObjectRef The VimObjectRef element is a reference to a Virtual Infrastructure Management object. Schema Name Type Description VimServerRef ReferenceType Reference to the server hosting this object MoRef xs:string Managed object ID of this object VimObjectType VimObjectTypeEnum Type of this object VimObjectType The VimObjectType element defines the type of a Virtual Infrastructure Management object. Table...

  • Page 196: Resourcepoollist

    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. Schema Name Type Description MoRef xs:string Managed object ID of this object VimObjectType VimObjectTypeEnum Type of this object DataStoreRefs VimObjectRefsType Read‐only container for references to datastores in  this resource pool ShieldManager The ShieldManager object represents a vShield Manager server. Content-Type application/vnd.vmware.admin.vmwvirtualcenter+xml Object href prototype API‐URL/admin/extension/shieldmanager/id Schema Name Type...

  • Page 197: Vmwprovidervdc

    Chapter 12 vSphere Platform Extensions Reference VMWProviderVdc A VMWProviderVdc object represents a provider vDC. Content-Type application/vnd.vmware.admin.vmwprovidervdc+xml Object href prototype API‐URL/admin/extension/providervdc/id Schema Name Type Description name xs:string Common object name attribute any attribute name Includes type, href, XML Namespace  Identifiers status xs:int The creation status of the ProviderVdc:  ‐1 – Creation failed  0 – Not ready  1 – Ready ...

  • Page 198: Vmwnetworkpool

    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.fencePool+xml Schema Name Type Description name xs:string Common object name attribute any attribute name Includes type, href, XML namespace identifiers Description xs:string Optional description FenceIdCount xs:int Number of fence IDs in this pool VlanId xs:int Set to 0 for no VLAN VimSwitchRef VimObjectRefType Reference to the switch that supports this VLAN UsedNetworksCount xs:int Read‐only indication of how many networks in this  pool are in use PortGroupPoolType A VMWNetworkPool of the PortGroupPoolType represents a network pool backed by one or more vSphere ...

  • Page 199: Vmwexternalnetwork

    Chapter 12 vSphere Platform Extensions Reference Schema (Continued) Name Type Description VimSwitchRef VimObjectRefType Reference to the switch that supports this VLAN UsedNetworksCount 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.network+xml Object href prototype API‐URL/admin/extension/externalnet/id Schema Name Type Description name xs:string Common object name attribute any attribute name Includes type, href, XML namespace identifiers Description xs:string Optional description Configuration NetworkConfigurationType Properties of the network...

  • Page 200: Request Parameters

    Host operating system version SystemMessages xs:string vCenter messages for this host VimPropertyPageUrl xs:string URL for host property page in vSphere VmMoRef xs:string vSphere managed object reference for this object Request Parameters The vSphere Platform extensions defined several elements that provide parameters to requests that create,  delete, modify, or change the state of a vSphere Platform object. PrepareHostParams The PrepareHostParams element forms the body of a prepare or unprepare request for an ESX host. Schema Name Type Description Username xs:string User name of a host administrator Password xs:string Password for specified Username RegisterVimServerParams The RegisterVimServerParams element forms the body of a registervimserver request. Schema Name Type Description VimServer VimServerType vCenter server to register ShieldManager ShieldManagerType vShield Manager associated with the vCenter server to register VMware, Inc.

  • Page 201: Importvmasvappparams

    URL of the target vDC ImportVmAsVAppTemplateParams The ImportVmAsVAppTemplateParams element forms the body of an importVmAsVAppTemplate request. Schema Name Type Description name xs:string Specifies the name of the vApp created by this  operation sourceMove xs:boolean True if the imported VM should be removed from the  source vCenter Description xs:string Optional description VmMoRef xs:string Managed object reference of the VM to import ReferenceType URL of the target vDC Catalog ReferenceType Reference to a catalog in which the template will be  included. If this element is omitted or empty, the  template is imported into the target vDC but not  references in any catalog. VmName xs:string Virtual machine name VAppScopedLocalId xs:string Read‐only identifier created on import ComputerName xs:string Display name of this virtual machine VMware, Inc.
  • Page 202 API Programming Guide VMware, Inc.

  • Page 203: Ovf And The Vcloud Api

    163 for details on how these sections are used).    The vCloud API supports uploading OVF 1.0 and OVF 1.1, and downloading OVF 1.0. OVF 1.1  packages are converted to OVF 1.0 for download. This appendix includes the following topics:  “About OVF” on page 203  “How the vCloud API Uses OVF” on page 204 About OVF Because it is a widely accepted standard format, OVF provides considerable flexibility in accommodating the  needs of a diverse collection of virtualization technologies. While this flexibility entails more complexity than  a vendor‐specific format might require, it also provides many advantages.  Virtual machines and appliances are distributed as OVF packages by many vendors.   Many vendors, including VMware, offer tools that simplify creating and customizing OVF virtual  machines, support converting virtual machines on existing virtualization platforms to OVF, or both.  OVF has the power to express the complex relationships between virtual appliances in enterprise  applications. Most of the complexity can be handled by the author of the appliance rather than the user  deploying it.  OVF is extensible, allowing new policies and requirements to be inserted by ISVs and implemented by  the virtualization platforms that support them without requiring changes to other clients, other platforms,  or the vCloud API itself. While most users do not need to interact directly with the OVF‐derived elements of the vCloud API,  administrators and advanced users should become familiar with the details of the OVF standard before  developing applications with the vCloud API. This chapter provides an overview of OVF, one that  concentrates on the aspects of the standard that are of special interest to users of the vCloud API. The complete  OVF specification document is available at  http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf. An informative white paper on  OVF is available at http://www.dmtf.org/standards/published_documents/DSP2017_1.0.0.pdf. VMware, Inc.

  • Page 204: About Ovf Packages

    .ova. This release of the vCloud API does not support upload or download of OVA files. How the vCloud API Uses OVF The vCloud API uses the OVF package as a unit of distribution and storage for vApp templates. Because these  artifacts are uploaded, downloaded, and stored in OVF package form, the vCloud API supports access to and  deployment of the widest possible variety of virtual applications. The vCloud API implements an instantiation  mechanism that transforms an OVF package into a vApp by binding the package’s abstract resource  requirements to specific resources in a deployment environment defined by a vDC. Because of its generality, the OVF includes a great deal of information, nearly all of which is reused in VApp  elements. Some of this information is reused in unaltered form, with entire ovf:Section_Type elements  included in the VApp body. Other sections are transformed or extended by instantiation. While it is not  necessary for a user of the vCloud API to have a detailed knowledge of all the elements of an OVF package, a  basic understanding of a few key parts the package and how they relate to vApp templates and vApps can be  useful. Virtual Machines An OVF Envelope collects all of the metadata that describes a single virtual machine into a VirtualSystem  element. An Envelope that contains more than one VirtualSystem collects them into a  VirtualSystemCollection element. This arrangement supports packaging a group of related virtual  machines as a single object, and includes provisions for specifying global parameters such as virtual machine  startup order, network connections, and a range of resource configurations (such as processing power and  memory) to which the virtual machines can be deployed. The vCloud API also supports this kind of packaging of multiple virtual machines. When you instantiate a  VAppTemplate, information from its VirtualSystem and VirtualSystemCollection elements is  propagated to the created VApp. VirtualSystem elements in a VirtualSystemCollection become Vm  elements contained by the Children element of a VApp. For more information about instantiation, see “Instantiate a vApp Template” on page 61. For a detailed  example of an Envelope and its sections, see “Reconfiguring vApps and Virtual Machines” on page 69. For  more information about the purpose and contents of the OVF Sections included in a vApp or Vm, see “VApp”  on page 162. VMware, Inc.

  • Page 205: Virtual Disk Files

    <Info>Virtual disk information</Info> <Disk ovf:capacity="8589934593" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/vmdk.html#str eamOptimized"/> </DiskSection> <VirtualHardwareSection> <VirtualSystem> <Item> <rasd:ElementName>Hard Disk 1</rasd:ElementName> <rasd:HostResource>ovf:/disk/vmdisk1</rasd:HostResource> </Item> </VirtualHardwareSection> </VirtualSystem> </Envelope> Networks The NetworkSection element of an OVF Envelope lists all the logical networks required by the package. Each  network is defined in this section by a name and can have an optional description. Logical network names are  used when specifying connection details for a virtual NIC. The OVF is extensible, and the vCloud API has implemented extensions that enable a more comprehensive  specification of network features, such as firewall and NAT rules, than what is currently supported by the OVF  standard. See “NetworkConfig” on page 165. Example A‐2 illustrates a subset of Envelope elements that specify vApp networking configuration.  The OVF NetworkSection element specifies the name of the network  The vCloud API NetworkConfigSection defines various network features such as DHCP and firewall  services. VMware, Inc.
  • Page 206 <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="Internet"> <Features> <Dhcp>true</Dhcp> <Nat></Nat> <Firewall></Firewall> </Features> </NetworkConfig> </NetworkConfigSection> <NetworkConnectionSection> <NetworkConnection network="Internet"> <IPAddress>192.168.1.100</IPAddress> </NetworkConnection> </NetworkConnectionSection> <VirtualSystem> <VirtualHardwareSection> <Item> <rasd:Connection>Internet</rasd:Connection> <rasd:Description>PCNet32 ethernet adapter on "Internet" network</rasd:Description> <rasd:ElementName>Network Adapter 1</rasd:ElementName> </Item> </VirtualSystem> <VirtualHardwareSection> </Envelope> VMware, Inc.

  • Page 207: An Introduction To Rest For Vcloud Api Users

    “For More Information About REST” on page 208 How REST Works If a URL of such an object is known to a client, the client can use an HTTP GET request to discover the  properties of the object. These properties are typically communicated in a structured document with an HTTP  Content‐Type of XML or JSON, that provides a representation of the state of the object. In a RESTful workflow,  documents (representations of object state) are passed back and forth (transferred) between a client and a  service with the explicit assumption that neither party need know anything about an object other than what is  presented in a single request or response. The URLs at which these documents are available are often “sticky,”  in that they persist beyond the lifetime of the request or response that includes them. The other content of the  documents is nominally valid until the expiration date noted in the HTTP Expires header. Using the vCloud REST API A “REST API” is in some ways an unfortunate term, since the application programs written to a REST API  actually use HTTP requests (which are often executed by a script or other higher‐level language) as a way of  making what are essentially remote procedure calls that create, modify, or delete the objects defined by the  API. This REST API (and others) is defined by a collection of XML documents that represent the objects on  which the API operates. The operations themselves (HTTP requests) are generic to all HTTP clients. To write a RESTful client, you need to understand only the HTTP protocol and the semantics of standard  HTML markup. To use the vCloud API effectively in such a client, you need to know three things  the set of objects that the API supports, and what they represent (What is a vDC? How does it relate to an  organization or catalog?)  how the API represents these objects (What does the XML schema for an Org look like? What do the  individual elements and attributes represent?)  how the client refers to an object on which it wants to operate (Where are the links to objects in a vDC?  How does a client obtain and use them?) To answer these questions, you need to understand the vCloud API XML schemas. These schemas define a  number of XML types, many of which are extended by other types. The vCloud API schemas also use and  extend types defined by the Open Virtualization Format. The XML elements defined in these schemas, along  with their attributes and composition rules (minimum and maximum number of elements or attributes, for  VMware, Inc.

  • Page 208: Restful Workflow Patterns

    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. In this document, we present example requests and responses, and also provide reference information on the  XML schemas that define the request and response bodies.  RESTful Workflow Patterns All RESTful workflows fall into a pattern that includes only two fundamental operations:  Make an HTTP request (typically GET, PUT, POST, or DELETE). The target of this request is either a  well‐known URL (such as the root of a vCloud service or an organization hosted on such a service) or a  link obtained from the response to a previous request. (For example, a GET request to an organization  URL returns links to catalog and vDC objects contained by the organization.)  Examine the response, which always includes an HTTP response code and often includes a body (an XML  document, in the vCloud API). The response body may contain links or other information about the state  of an object. (For example, a response that includes a vApp body contains the details of the vApp’s current  virtual hardware configurations, as well as links that you can use to edit that configuration). If the  response is an HTTP response code, it indicates whether the request succeeded or failed, and may be  accompanied by a URL that points to a location from which additional information can be retrieved. These two operations can repeat, in this order, for as long as necessary. For More Information About REST For a comprehensive discussion of REST from both the client and server perspectives, see: Richardson, Leonard, and Sam Ruby. RESTful Web Services. North Mankato: OʹReilly Media, Inc., 2007. There are also many sources of information about REST on the Web, including:  http://www.infoq.com/articles/rest‐introduction  http://www.infoq.com/articles/subbu‐allamaraju‐rest  http://www.stucharlton.com/blog/archives/000141.html VMware, Inc.

  • Page 209: Index

    14 controlling access to 56 Group element CloneMediaParams element example of use 113 example of use 51 schema reference 191 schema reference 176 CloneVAppParams element example of use 52 schema reference 176 CloneVAppTemplateParams element example of use 51 VMware, Inc.
  • Page 210 12 schema reference 158 network vApp 62 UndeployVAppParams element NetworkConfigSection element schema reference 175 example of use 71 UploadVAppTemplateParams element example of use 43 schema reference 171 Org element example of use 22 schema reference 151 VMware, Inc.
  • Page 211 66 VmQuestionAnswer schema reference 177 VMWExtension example of use 119 schema reference 193 VMWExternalNetwork example of use 133 schema reference 199 VMWNetworkPool example of use 136 schema reference 198 VMWProviderVdc example of use 127 schema reference 197 VMware, Inc.
  • Page 212 API Programming Guide VMware, Inc.

Table of Contents