vmware vcloud api programming guide · vcloud api programming guide ... logging in and getting an...
TRANSCRIPT
vCloud API Programming GuidevCloud API 1.0
This document supports the version of each product listed andsupports all subsequent versions until the document is replacedby a new edition. To check for more recent editions of thisdocument, see http://www.vmware.com/support/pubs.
EN-000180-01
VMware, Inc.3401 Hillview Ave.Palo Alto, CA 94304www.vmware.com
2 VMware, Inc.
vCloud API Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
Copyright © 2009, 2011 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. 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.
VMware, Inc. 3
Contents
About This Book 11
1 Introducing the VMware vCloud API 13vCloud Object Taxonomy 13
vCloud Organizations 13
Objects, References, and Representations 15
Links and Link Relations 15
vCloud Client Workflow Overview 17
Requests 17
Responses 18
Configuring the vCloud API URL 19
Related Publications 19
About the Examples 19
2 Hello vCloud: A Structured REST Workflow Example 21Logging 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
Retrieve a Screen Ticket 29
Use the Ticket with vmware‐vmrc 30
Deleting the vApp 30
Logging Out 30
Moving on to Additional Use Cases 31
3 Browsing 33Summary of Browsing Requests 33
Discovering the Contents of an Organization, Catalog, or vDC 34
List the Organizations in a vCloud 34
List the Contents of an Organization 34
List the Contents of a Catalog 35
Get Information About a CatalogItem 36
List the Contents of a vDC 37
Getting More Information About an Object 38
Get Information About a Media Image 38
Get Information About a vAppTemplate 39
Get Information About a vApp or Virtual Machine 40
Get Information About a Network 40
4 Provisioning 41Summary of Provisioning Requests 41
Upload OVF to Create a vApp Template 42
vCloud API Programming Guide
4 VMware, Inc.
Restrictions on Uploaded Content 43
Initiate the Upload 43
Including a Manifest 45
Uploading the Files 45
View the OVF Descriptor of a vApp Template 47
Download a vApp Template as OVF 47
Enable a vApp Template for Download 48
Disable a vApp Template for Download 49
Upload a Media Image 50
Copying and Moving 50
Copy or Move a Media Image 51
Copy or Move a vApp Template 51
Copy or Move a vApp 52
Changing a Name or Description 53
Change the Name or Description of a vAppTemplate 53
Change the Name or Description of a vApp 53
Change the Name or Description of a Media Image 54
Delete a vAppTemplate, vApp, or Media Image 54
Cataloging vApp Templates and Media Images 54
Add an Item to a Catalog 54
Remove an Item from a Catalog 56
Catalog Links in a VApp Template or Media Image 56
Controlling Access 56
Control Access to Catalogs 56
5 Datacenter Operations 59Summary of Datacenter Operations Requests 59
vApp Lifecycle 60
Instantiate a vApp Template 61
About Instantiation Parameters 62
About vApp Networks 62
Instantiating a vAppTemplate Using Default Parameters 62
Instantiating a vApp Template Using Additional Parameters 62
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
Insert Media Into a Virtual Machine 85
Eject Media from a Virtual Machine 86
Get a Screen Thumbnail for a Virtual Machine 86
VMware, Inc. 5
Contents
Get a Screen Ticket for a Virtual Machine 87
Provide User Input Requested by a Virtual Machine 87
Control Access to vApps 89
Retrieve a Task 89
6 Administrative Operations 91Summary of Administrative Requests 91
Administrator Credentials and Privileges 93
Administrative Objects and URLs 93
Get an Administrative View of a Cloud 93
Organization Administration 94
Create an Organization 95
Get an Administrative View of an Organization 96
List All Tasks Owned by an Organization 97
Modify an Organization 97
Enable or Disable an Organization 98
Remove an Organization 99
Network Administration 99
View the Properties of an External Network 99
Add a Network to an Organization 100
Get an Administrative View of an Organization Network 101
Modify an Organization Network 101
Remove an Organization Network 102
vDC Administration 102
Examine the Contents of a Provider vDC 103
List the Organization vDCs Supported by a Provider vDC 104
Allocate a vDC to an Organization 104
Get an Administrative View of a vDC 106
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
Role Administration 114
Create a Role 114
View Role Metadata 115
Modify a Role 116
Remove a Role 116
View a Right 116
vCloud API Programming Guide
6 VMware, Inc.
7 VMware vSphere Platform Operations 117Summary 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
List ESX/ESXi Hosts in a vCloud 124
Get Information About a Host 124
Prepare a Host 125
Unprepare a Host 126
Enable or Disable a Host 126
Repair a Host 126
Upgrade a Host Agent 127
Create a Provider vDC 127
Examine the vSphere Objects in a Provider vDC 131
Modify a Provider vDC 131
Enable or Disable a Provider vDC 132
Remove a Provider vDC 132
Create an External Network 133
Get Information About an External Network 134
Modify an External Network 135
Remove an External Network 135
Create a Network Pool 136
Get Information About a Network Pool 137
Modify a Network Pool 137
Remove a Network Pool 138
Import a Virtual Machine from vCenter 138
Discover the Virtual Machines in a vCenter 138
Import a Virtual Machine as a vApp 139
Import a Virtual Machine as a vApp Template 140
8 XML Representations in the vCloud API 141About Object Representations 141
Schema 141
Content Type 142
Object Reference Prototype 142
Common Datatypes 142
Primitive XML Datatypes 142
Complex Types 143
Common Attributes 143
name 144
href 144
type 144
status 144
XML Namespace Identifiers 145
Common Elements 146
Description 146
Error 146
VMware, Inc. 7
Contents
Link 147
API Versioning 147
SupportedVersions 148
VersionInfo 148
Extensibility 148
VCloudExtension 149
9 User API Reference 151OrgList 151
Org 151
Vdc 152
StorageCapacity 153
ComputeCapacity 153
AvailableNetworks 153
ResourceEntities 154
ResourceEntity 154
OrgNetwork 154
Configuration 155
Catalog 160
CatalogItems 160
CatalogItem 160
Media 161
VAppTemplate 161
Children 162
VApp 162
Vm 163
Section 163
LeaseSettingsSection 164
StartupSection 164
CustomizationSection 164
NetworkConfigSection 165
NetworkConnectionSection 165
VirtualHardwareSection 167
OperatingSystemSection 167
GuestCustomizationSection 167
RasdItemsList 168
ScreenTicket 168
TasksList 168
Tasks 168
Task 168
10 Request Parameters Reference 171UploadVAppTemplateParams 171
InstantiateVAppTemplateParams 172
InstantiationParams 172
ComposeVAppParams 173
Item 173
NetworkAssignment 174
RecomposeVAppParams 174
DeployVAppParams 175
UndeployVAppParams 175
CaptureVAppParams 175
CloneMediaParams 176
CloneVAppTemplateParams 176
vCloud API Programming Guide
8 VMware, Inc.
CloneVAppParams 176
MediaInsertOrEjectParams 177
VmPendingQuestion 177
VmQuestionAnswer 177
ControlAccessParams 177
AccessSettings 178
11 Administrative API Reference 179VCloud 179
OrganizationReferences 180
ProviderVdcReferences 180
RightReferences 180
RoleReferences 180
Networks 180
ExternalNetwork 180
AdminOrg 180
Settings 181
Users 185
Groups 185
Catalogs 185
Catalog 186
Vdcs 186
ProviderVdc 186
ComputeCapacity 187
StorageCapacity 188
NetworkPoolReferences 188
NetworkPoolReference 188
VdcReferences 188
AdminVdc 188
AllocationModel 190
User 190
Group 191
Role 191
RightReferences 191
RightReference 191
Right 192
12 vSphere Platform Extensions Reference 193VMWExtension 193
VMWProviderVdcReferences 194
VMWExternalNetworkReferences 194
VMWNetworkPoolReferences 194
VMWVimServerReferences 194
VMWHostReferences 194
VimServer 194
VmObjectRefsList 195
VimObjectRef 195
ResourcePoolList 196
ResourcePool 196
ShieldManager 196
VMWProviderVdc 197
VMWNetworkPool 198
FencePoolType 198
PortGroupPoolType 198
VlanPoolType 198
VMware, Inc. 9
Contents
VMWExternalNetwork 199
VlanRange 199
VMWHostReferences 199
Host 199
Request Parameters 200
PrepareHostParams 200
RegisterVimServerParams 200
ImportVmAsVAppParams 201
ImportVmAsVAppTemplateParams 201
A OVF and the vCloud API 203About OVF 203
About OVF Packages 204
About OVA Files 204
How the vCloud API Uses OVF 204
Virtual Machines 204
Virtual Disk Files 205
Networks 205
B An Introduction to REST for vCloud API Users 207How REST Works 207
Using the vCloud REST API 207
RESTful Workflow Patterns 208
For More Information About REST 208
Index 209
vCloud API Programming Guide
10 VMware, Inc.
VMware, Inc. 11
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.
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 GlossaryVMware 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 FeedbackVMware welcomes your suggestions for improving our documentation. Send your feedback to
About This Book
Table 1. Revision History
Revision Date Description
08MAR11 GuestCustomizationSection not allowed in InstantiationParams
30AUG10 Version 1.0
vCloud API Programming Guide
12 VMware, Inc.
Technical Support and Education ResourcesThe 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. 13
1
The VMware vCloud API provides support for developers who are building interactive clients of VMware
Cloud Director using a RESTful application development style. vCloud API clients and servers communicate
over HTTP, exchanging representations of vCloud objects. These representations take the form of XML
elements. 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 TaxonomyThe 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
organization administrator or imported from a directory service such as LDAP. Groups must be imported
from the directory service. Permissions within an organization are controlled through the assignment of rights
and roles to users and groups.
vCloud Networks
An organization can be provisioned with one or more networks. These organization networks can be
configured to provide services such as DHCP, NAT, and firewalls.
Introducing the VMware vCloud API 1
vCloud API Programming Guide
14 VMware, Inc.
Figure 1-1. vCloud Object Taxonomy
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.
Catalog 2
Catalogitemememem
Catalog 1
Catalog 3
vDC2 CatalogitemCatalogitemCatalogitemCatalogitem
users
Media
vApptemplate
Media
vApp
TasksList
Organization
vDC1
Media
vApptemplate
Media
vApp
NetworkNetwork
Catalogitemememem
groups
VMware, Inc. 15
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 RepresentationsThe 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
in the value of the href attribute of the XML element that represents the object. It also appears in various
elements of LinkType and ReferenceType. This URL serves as a unique identifier that persists for the life of the object and is never re‐used. Although URLs have a well‐known syntax and a well‐understood
interpretation, a client should treat each href as an opaque string. The rules that govern construction of href strings by the server might change in future releases.
Object types, specified as MIME content types, are included in the XML representations of first‐class objects
such as the ones shown in Figure 1‐1. For more information, see “Content Type” on page 142.
Links and Link RelationsThe vCloud API makes extensive use of links (URLs) to provide references to objects and the actions that they
support. These links are the primary mechanism by which a server tells a client how to access and operate on
an object. Links are created by the server, and are read‐only at the client. (If a client request body includes a
link, the server ignores it.)
In the XML representation of a vCloud object, each link is defined in a Link element that has the following
form:
<Link rel="relationship" type="application/vnd.vmware.vcloud.type+xml" href="URL" name="string"/>
The rel attribute value defines the relationship of the object whose XML representation contains the Link to a target object. The relationship also indicates the HTTP request type to use when making a request
with the href attribute of the link, as shown in Table 1‐1:
Table 1-1. Link Relationships and HTTP Request Types
rel Attribute Value Relation Description HTTP Request
add adds an item to this container POST
alternate a link to an alternate representation of this object GET
catalogItem a link to the catalogItem that contains a reference to this object. GET
controlAccess apply access controls POST
copy not supported in this release N/A
deploy deploy this object POST
vCloud API Programming Guide
16 VMware, Inc.
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.
disable disable this object POST
discardState discard the suspended state of this virtual machine POST
down the referenced object is contained by this object GET
download:alternate not supported in this release N/A
download:default default download location for this file GET
edit modifies this object PUT
enable enable this object POST
extension not supported in this release N/A
media:ejectMedia eject virtual media from a virtual device POST
media:insertMedia insert virtual media in a virtual device POST
move not supported in this release N/A
ova not supported in this release N/A
ovf the OVF representation of this vAppTemplate GET
power:powerOff power off the referenced object POST
power:powerOn power on this object POST
power:reboot reboot this object POST
power:reset reset this object POST
power:shutdown shut down this object POST
power:suspend suspend this object POST
publish publish this catalog POST
recompose recompose this vApp POST
reconnect reconnect this vCenter Server POST
register register this vCenter Server POST
remove remove this object DELETE
repair repair this host POST
screen:acquireTicket acquire a screen ticket for this virtual machine GET
screen:thumbnail thumbnail view of a virtual machine screen, in png format GET
task:cancel not supported in this release N/A
undeploy undeploy this object POST
unregister unregister this vCenter Server POST
up the referenced object contains this object GET
upgrade upgrade this host POST
upload:alternate not supported in this release N/A
upload:default default upload location for this file PUT
Table 1-1. Link Relationships and HTTP Request Types (Continued)
rel Attribute Value Relation Description HTTP Request
VMware, Inc. 17
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).
vCloud Client Workflow OverviewClients 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.
<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221" name="Ubuntu Template with vsftpd"/>
Any request that includes a CatalogItem requires the following Content‐Type header:
Content-Type: application/vnd.vmware.vcloud.catalogItem+xml
When it appears as the value of a Content‐Type header or the type attribute of an element in the vCloud API,
this string is case‐insensitive in requests, and can be returned in either mixed case or lowercase characters in
responses.
For more information, see “Content Type” on page 142.
Request Bodies
This release of Cloud Director uses a validating XML parser that requires elements in a request body to agree
in both order and number with the schema. Request bodies are rejected as invalid unless they meet the
following criteria:
XML namespace attributes must be supplied for all namespaces represented by elements in the request.
See “XML Namespace Identifiers” on page 145.
If multiple namespaces are represented in the request, XML namespace attributes must include an
identifying prefix, and that prefix must be used with elements from that namespace. See “XML
Namespace Prefixes in Request and Response Bodies” on page 146.
NOTE When a client uses a link to reference an object, only the href attribute is required. The name and type
are ignored.
vCloud API Programming Guide
18 VMware, Inc.
All required elements must appear in request bodies. All elements that appear in request bodies must
appear in the order established by the schema, and with content that conforms to the type constraint
specified in the schema. See “Schema Validation” on page 142.
Authentication
HTTP communications between a vCloud client and server are typically secured with SSL. In addition, the
vCloud API implements Basic HTTP Authentication, as defined by RFC 2617, which enables a client to obtain
a token that it can use to authenticate individual HTTP requests.
To obtain and use an authentication token, a client must first discover the server’s login URL, and then POST
a login request to that URL, supplying the credentials of an authorized user.
To obtain and use an authentication token
1 Make an API version request to a vCloud service to obtain the login URL for that service. For more
information, see “API Versioning” on page 147.
2 Make an HTTP POST request to the login URL, as shown in Example 2‐1 on page 21.
If the authentication header is missing, the server returns HTTP response code 401.
If the credentials supplied in the authentication header are invalid, the server returns HTTP response
code 401.
If the request is successful, the server returns HTTP response code 200 (OK) and headers that include
an authorization header of the form:
x-vcloud-authorization: token
This header must be included in each subsequent vCloud API request.
The response body is an OrgList element, which is a list of all organizations that the user can access.
The authentication token expires after a configurable interval of client inactivity. The default is 30 minutes after
the token is created. After the token expires, all requests fail with HTTP response code 401 until the client logs
in again to obtain a new token.
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.
NOTE Certain administrative operations have special authentication requirements. For more information, see
“Administrator Credentials and Privileges” on page 93.
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. 19
Chapter 1 Introducing the VMware vCloud API
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
this hostname cannot be resolved from the client (for example, if the Cloud Director installation includes
multiple server hosts that you access through a load balancer) you can specify a URL for the server to use when
constructing href strings. For more information, see Configure the External REST API Base URI in the Cloud
Director Administratorʹs Guide.
Related PublicationsThe VMware Cloud Director Administratorʹs Guide and VMware Cloud Director User’s Guide contain detailed
information about many of the objects and operations referred to in this guide. Most users of the vCloud API
will find the information in those documents valuable when developing client applications. To access the
current versions of these and other VMware books, go to http://www.vmware.com/support/pubs.
About the ExamplesThis guide includes many examples of HTTP requests and responses. These examples are intended to show
the workflow and content associated with specific types of operations such as browsing, managing inventory,
and operating virtual systems. Example requests generally conform to the rules listed in “Request Bodies” on
page 17. Most example responses show only those elements and attributes that are relevant to the operation
being discussed. Ellipses (…) indicate omitted content within response bodies.
HTTP Content‐Type headers are shown where needed for all examples that are not fragments of some larger
example that includes this header. Although the examples show these strings using the character case in which
they are defined by the implementation, these strings are case‐insensitive in requests, and can be returned in
either mixed case or lowercase characters in responses. Other HTTP headers, such as Date, Content‐Length,
and Server, are omitted because they are not relevant to the specifics of any example. The XML version and
encoding header (<?xml version="1.0" encoding="UTF-8"?>) is not included in most examples, although
it is a required part of all requests and responses that contain an XML body.
In addition:
Unsecured URLs (http://) are used in the examples. In practice, most sites will require the use of SSL
(https://).
Object IDs shown in href attribute values appear as small integers (for example vapp-7 or org/3). In the vCloud API supported by Cloud Director, object IDs are 10‐digit decimal integers (for example
vapp-124237959 or org/5738592905).
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 Allowed
The HTTP method specified in the request is not supported for this object.
500 Internal Server Error
The request was received but could not be completed due to an internal error at the server.
501 Not Implemented The request is not implemented by the server.
503 Service Unavailable
One or more services needed to complete the request are not available on the server.
Table 1-2. HTTP Status Codes Returned by the vCloud API (Continued)
Status Code Status Description
vCloud API Programming Guide
20 VMware, Inc.
VMware, Inc. 21
2
This chapter presents a simple example of a structured REST workflow for discovering and deploying a
particular vApp (in this case, an FTP server with a connection to the public Internet).
This chapter includes the following topics:
“Logging In and Getting an Organization List” on page 21
“Browsing an Organization” on page 22
“Finding a vApp Template” on page 23
“Getting Information About a vDC” on page 24
“Instantiating the Template in the vDC” on page 24
“Deploying and Powering On the vApp” on page 26
“Getting Information About the vApp” on page 27
“Deleting the vApp” on page 30
“Logging Out” on page 30
Logging In and Getting an Organization ListEvery vCloud has a login URL that a client can obtain by making an unauthenticated GET request to the
vCloud’s versions URL, as shown in Example 8‐2 on page 147. Because all other vCloud API requests must
be authenticated, any vCloud API workflow has to begin with a login request that supplies user credentials in
the form required by Basic HTTP authentication (MIME Base64 encoding of a string having the form
user@vcloud‐organization:password). 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/loginAuthorization: Basic encoded-credentials
Response:
200 OKDate: request-datex-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"/>
Hello vCloud: A Structured REST Workflow Example 2
vCloud API Programming Guide
22 VMware, Inc.
<Org .../><Org .../>
</OrgList>
The response includes an authentication token supplied in the x-vcloud-authorization header, and a list of the organizations to which the authenticated user has access. Each Org has a URL (in its href attribute value) that the client can use to get more information about objects that the organization contains. For more
information about authentication, see “Authentication” on page 18.
Browsing an OrganizationYou can use an HTTP GET request and one of the Org URLs returned by the login request to discover the contents of an organization, as shown in Example 2‐2. (For a more complete version of this example, see
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 OKContent-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"/><Link ... /><Link rel="down" type="application/vnd.vmware.vcloud.network+xml"
href="http://vcloud.example.com/api/v1.0/network/14" name="IsolatedOrgNet"/><Link rel="down" type="application/vnd.vmware.vcloud.network+xml"
href="http://vcloud.example.com/api/v1.0/network/54" name="Internet"/><Description>Example Corp’s Primary Organization</Description>
</Org>
Links in the response whose rel attribute has a value of down are references to objects that the organization contains. Example 2‐2 shows the subset of those items that you will need for this exercise:
A catalog named MainCatalog, at URL http://vcloud.example.com/api/v1.0/catalog/32, where you can
look for vApp templates.
A vDC named ExampleVdc01, at URL http://vcloud.example.com/api/v1.0/vdc/5, where you can deploy
the vApp.
Two networks: one named Internet, at URL http://vcloud.example.com/api/v1.0/network/54, and one
named IsolatedOrgNet, at URL http://vcloud.example.com/api/v1.0/network/14. You can connect
connect the vApp to either of these networks.
NOTE This example, like other examples in this guide, omits certain required HTTP headers and other content
so that it can provide a concise, readable subset of an actual request and response. For more information, see
“About the Examples” on page 19.
VMware, Inc. 23
Chapter 2 Hello vCloud: A Structured REST Workflow Example
Finding a vApp TemplateThe client can use the catalog URL shown in Example 2‐2 as the target of a GET request that returns the
contents of the catalog, as shown in Example 2‐3.
Example 2-3. Finding a vApp Template in a Catalog
Request:
GET http://vcloud.example.com/api/v1.0/catalog/32
Response:
200 OKContent-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.
Example 2-4. Getting the vApp Template URL From a CatalogItem
Request:
GET http://vcloud.example.com/api/v1.0/catalogItem/221
Response:
200 OKContent-Type: application/vnd.vmware.vcloud.catalogItem+xml...<CatalogItem name="Ubuntu Template with vsftpd"
href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...>...<Description>Ubuntu Template with vsftpd</Description><Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"
type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>
...</CatalogItem>
This response shows that a suitable vApp template can be found at
http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate‐111.
vCloud API Programming Guide
24 VMware, Inc.
Getting Information About a vDCInstantiation, deployment, and operation of a vApp all take place in the context of a vDC. The XML
representation of a vDC object defines that context in detail. For this exercise, you need only two pieces of
information from the vDC:
The URL that a client can use to request an instantiateVAppTemplate operation in the vDC
A list of networks to which the vApp can connect.
Example 2‐5 shows this subset of vDC contents. (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 OKContent-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"/>
</AvailableNetworks>...
</Vdc>
The information you need is available here in two places:
An Link element containing an action URL,
http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate. The rel attribute of this Link has a value of add, indicating that it implements an action that adds an object to the vDC.
A list of AvailableNetworks that includes all the networks owned by the organization that contains this
vDC. Since we want this FTP server to be accessible on the public Internet, we will connect the vApp to
the network named Internet.
Both these pieces of information are put to use in Example 2‐6.
Instantiating the Template in the vDCTo create a vApp from this template, you must bind its abstract resource requirements, such as network
connections, storage resources, memory, and CPU capacity, to appropriate resources in the target vDC. This
binding operation is called instantiation. Although a client can specify these bindings in detail, a simple
instantiation, which relies on organization and vDC defaults, requires only a few pieces of information:
A name for the vApp that the request creates
The URL of the template to instantiate. In this case, the URL (retrieved in Example 2‐4) is
http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate‐111.
VMware, Inc. 25
Chapter 2 Hello vCloud: A Structured REST Workflow Example
Creation parameters for a vApp network. A vApp network defines how the vApp connects to an
organization network available in the target vDC. For more information, see “About vApp Networks” on
page 62.
The instantiateVAppTemplate request in Example 2‐6 supplies these parameters in the following places:
The name is supplied in the name attribute of the InstantiateVAppTemplateParams request. (This request also provides a description, which is optional but a good practice.)
The template URL is suppled in the Source element
The vApp network is specified in the NetworkConfigSection element. This specification includes three
parameters:
A name for the network, supplied in the name attribute of the NetworkConfigSection element. If
the vApp template includes an ovf:Network element, the name you specify for the vApp network
must match the name specified in that element’s ovf:name attribute.
A reference to the organization network to which the vApp network connects, specified in the
ParentNetwork element. The URL used here is one returned in Example 2‐5, in the
AvailableNetworks element of the vDC.
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/instantiateVAppTemplateContent-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>
</Configuration></NetworkConfig>
</NetworkConfigSection></InstantiationParams><Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/>
</InstantiateVAppTemplateParams>
Response:
201 CreatedContent-Type: application/vnd.vmware.vcloud.vApp+xml
<VApp deployed=”false” status="0" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...>
<Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/>
<Description>Example FTP Server vApp</Description><Tasks>
vCloud API Programming Guide
26 VMware, Inc.
<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>
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.
Deploying and Powering On the vAppAfter the instantiation task completes, the template has been transformed into a vApp. The vApp body no longer includes a Tasks element, and it now includes a number of Link elements that you can use to deploy
and operate the vApp. Example 2‐7 shows a request and response for a deploy action. The request URL is the rel="deploy" link returned in the vApp body (see Example 2‐8). The request body is a DeployVAppParams element, which specifies deployment details.
Example 2-7. Deploy and Power On a vApp
Request:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deployContent-type: application/vnd.vmware.vcloud.deployVAppParams+xml...<DeployVAppParams powerOn="true" deploymentLeaseSeconds="2592000"
xmlns="http://www.vmware.com/vcloud/v1"/>
Response:
202 Accepted<Task xmlns="http://www.vmware.com/vcloud/v1" status="running"
startTime="2010-06-25T11:15:55.558-07:00" operation="Starting 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/i9h1djqzsyllf0zvdy" ...>
<Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/>
</Task>
Because deployment is a long‐running operation that can fail for a variety of reasons (inability of the vDC to
satisfy the vApp’s resource requirements, for example), the response is a Task.
NOTE 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 63.
VMware, Inc. 27
Chapter 2 Hello vCloud: A Structured REST Workflow Example
Because the deployment request specified powerOn="true", the vApp is powered on and ready for use when
the task completes. The client can wait for a suitable interval and check the task status (see “Retrieve a Task”
on page 89), or simply begin requesting operations on the powered‐on vApp and checking the task status if
those requests fail. See “Deploying and Controlling vApps and Virtual Machines” on page 80.
Getting Information About the vAppAs other examples have shown, a client can always use an HTTP GET request to discover the current state of
any vCloud object, including a vApp. The response in Example 2‐8 reveals several things:
The vApp is deployed (its deployed attribute is set to true) and powered on (status="4").
The Vm in its Children collection is also powered on and deployed. The Vm is connected to the vApp network created during instantiation (see Example 2‐6). Properties of this network are included in the
NetworkConfigSection of the vApp, though most are not shown here.
Action links for all operations except powerOn are present in both the vApp itself and its child Vm. Because the vApp is already powered on, that operation is invalid for the vApp in its current state, so the link is
not part of the response. (The link for deploy is always present, even in a deployed vApp, because the
deploy action is always valid.) The Vm element also includes several links for actions that not applicable
to a vApp: actions like acquiring a screen ticket or thumbnail, and inserting or removing media, are
specific to a virtual machine. Other actions like shutdown and reboot, can be applied to either object. See “Deploying and Controlling vApps and Virtual Machines” on page 80.
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 OKContent-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"
href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/shutdown"/><Link rel="power:reset"
href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reset"/><Link rel="power:suspend"
href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/suspend"/><Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml"
href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/controlAccess/"/><Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml"
href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/controlAccess/"/><Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml"
href="http://vcloud.example.com/api/v1.0/vdc/5"/><Link rel="edit" type="application/vnd.vmware.vcloud.vApp+xml"
href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/><Description>Example FTP Server vApp</Description><LeaseSettingsSection ...>
...</LeaseSettingsSection><ovf:StartupSection ... >
...
vCloud API Programming Guide
28 VMware, Inc.
</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><Children>
<Vm deployed="true" status="4" name="ubuntu10-x86" type="application/vnd.vmware.vcloud.vm+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4">
<Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/reboot"/>
<Link rel="power:powerOff" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/powerOff"/>
<Link rel="undeploy" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/action/undeploy"/>
<Link rel="deploy" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/action/deploy"/>
<Link rel="power:shutdown" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/shutdown"/>
<Link rel="power:reset" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/reset"/>
<Link rel="power:suspend" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/suspend"/>
<Link rel="up" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/>
<Link rel="screen:thumbnail" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/screen"/>
<Link rel="screen:acquireTicket" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/action/acquireTicket"/>
<Link rel="media:insertMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/action/insertMedia"/>
<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:VirtualHardwareSection>...<NetworkConnectionSection>
...<NetworkConnection network="vAppNetwork">
...
VMware, Inc. 29
Chapter 2 Hello vCloud: A Structured REST Workflow Example
<IpAddress>10.147.122.134</IpAddress><IsConnected>true</IsConnected><MACAddress>00:50:56:01:01:49</MACAddress>...
</NetworkConnection>...
</NetworkConnectionSection><GuestCustomizationSection ...>
...</GuestCustomizationSection><VAppScopedLocalId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedLocalId>
</Vm></Children>
</VApp>
Displaying the ConsoleAfter the vApp has been powered on, you can retrieve a screen ticket from one of its virtual machines and use
that ticket to gain access to the console of the virtual machine.
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 OKContent-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%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O
</ScreenTicket>
The ticket itself has the following form:
mks://ip-address/VM-MoRef/ticket=encoded-ticket
where:
ip‐address is the IP address of the virtual machine
VM‐MoRef is the managed object reference of the virtual machine
encoded‐ticket is the encoded screen ticket. You must decode this ticket using a function such as
URLDecoder (Java) or url_escape (PERL) before you can use it.
The ticket is valid for 30 seconds.
vCloud API Programming Guide
30 VMware, Inc.
Use the Ticket with vmware-vmrc
The vmware-vmrc plug‐in is installed by your browser whenever you use the Cloud Director Web Console to
access the console of a running virtual machine. After this plug‐in has been installed, you can find it in the
folder that your browser uses for plug‐ins.
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:
vmware-vmrc -h ip-address -p decoded-ticket -M VM-MoRef
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 vAppYou 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" status="running"
startTime="2010-06-25T08:10:23.650-07:00" operation="Deleting 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/jul1tndoojgaesymci" ... >
<Owner type="application/vnd.vmware.vcloud.vApp+xml" name="Linux FTP server" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/>
</Task>
Logging OutTo log out and end a session, a vCloud API client makes a POST request to the logout URL, as shown in
Example 2‐11.
Example 2-11. Log Out
Request:
POST http://vcloud.example.com/api/v1.0/logoutx-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Response:
200 OK
NOTE 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.
VMware, Inc. 31
Chapter 2 Hello vCloud: A Structured REST Workflow Example
Moving on to Additional Use CasesThis “Hello” exercise, while simplified, demonstrates a pattern common to many vCloud API use cases:
browsing to discover a template, instantiating the template, then deploying and operating the vApp described
in the template. The remainder of this guide provides expanded examples of these and other use cases,
including:
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.
vCloud API Programming Guide
32 VMware, Inc.
VMware, Inc. 33
3
A vCloud API client can use HTTP GET requests to browse containers such as organizations, catalogs, and
vDCs. Responses to these requests include metadata about the container itself and references to the objects it
contains. These references are provided in Link elements, which have href attributes whose values the client
can use in requests to get more information about the objects themselves. This hierarchical structure of
containers lends itself to graphical representation as a folder hierarchy or tree view of vCloud objects, and
enables clients to use the same set of objects and operations to implement a breadth‐first or depth‐first
approach to browsing.
This chapter includes the following topics:
“Summary of Browsing Requests” on page 33
“Discovering the Contents of an Organization, Catalog, or vDC” on page 34
“Getting More Information About an Object” on page 38
Summary of Browsing RequestsTable 3‐1 summarizes browsing 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
Browsing 3
Table 3-1. Summary of Browsing Requests
Operation Request Request Body Response
Show Login URL and List Supported API Versions
GET http://hostname/api/versions None SupportedVersions
Log in POST API‐URL/login None OrgList
Log out POST API‐URL/logout 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 Org
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 Vdc
Get Information About a Media Image GET API‐URL/media/id None Media
Get Information About a vAppTemplate
GET API‐URL/vAppTemplate/vappTemplate‐id None VAppTemplate
Get Information About a vApp or Virtual Machine
GET API‐URL/vApp/vapp‐id None VApp
vCloud API Programming Guide
34 VMware, Inc.
Discovering the Contents of an Organization, Catalog, or vDCThe vCloud API defines three principal containers: organizations, catalogs, and vDCs. A client can use an
HTTP GET request to discover the contents of any of them.
List the Organizations in a vCloud
The response to a login request includes a list of the organizations to which the authenticated user has access.
If an authenticated client needs to retrieve this list, it can make a GET request to the URL shown in the href attribute of the OrgList that was returned in the response to its original login request. To retrieve the OrgList returned in Example 2‐1 on page 21, an authenticated client would issue the following request:
GET http://vcloud.example.com/api/v1.0/org/
For more information, see “Logging In and Getting an Organization List” on page 21.
List the Contents of an Organization
A vCloud organization is a high‐level abstraction that provides a unit of administration for objects and
resources. As viewed by a user, an organization (represented by an Org element) can contain Catalog, Network, and vDC elements. If there are any queued, running, or recently completed tasks owned by a member
of the organization, it also contains a TasksList element. As viewed by an administrator, an organization also
contains users, groups, and other information. For more information, see “Org” on page 151 and “AdminOrg”
on page 180.
A client can obtain a list of organizations in a vCloud by logging in to the server to get an OrgList (see “Authentication” on page 18). This lists includes only those organizations to which the logged‐in user has
access. The client can use a URL from this list to make an HTTP GET request that returns an Org document in
the response body. This document, a representation of the organization object, includes links to objects that the
organization contains and metadata about the organization itself. Example 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 OKContent-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"
href="http://vcloud.example.com/api/v1.0/catalog/37" name="Shared Catalog"/><Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml"
href="http://vcloud.example.com/api/v1.0/catalog/37/controlAccess/"/><Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml"
href="http://vcloud.example.com/api/v1.0/catalog/37/action/controlAccess/"/><Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml"
href="http://vcloud.example.com/api/v1.0/vdc/5" name="ExampleVdc01"/><Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml"
href="http://vcloud.example.com/api/v1.0/tasksList/5"/>
VMware, Inc. 35
Chapter 3 Browsing
<Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/14" name="IsolatedOrgNet"/>
<Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54" name="Internet"/>
<Description>Example Corp’s Primary Organization</Description></Org>
This response shows that the organization contains these objects, each of which is referenced by a Link whose
rel attribute has a value of down (indicating that the link references an object contained by the organization):
A catalog named MainCatalog, whose URL is http://vcloud.example.com/api/v1.0/catalog/32
A catalog named SharedCatalog, whose URL is http://vcloud.example.com/api/v1.0/catalog/37
A link to the organization’s TasksList
A vDC named ExampleVdc01 whose URL is http://vcloud.example.com/api/v1.0/vdc/5
Two networks: one named IsolatedOrgNet whose URL is
http://vcloud.example.com/api/v1.0/network/14, and one named Internet whose URL is
http://vcloud.example.com/api/v1.0/network/54
Action links that enable an administrator to control access to the catalogs
List the Contents of a Catalog
A client can use the href value from any of the rel="down" links in an Org body to get more information
about the object to which the link refers, as shown in Example 3‐2, which requests more information about one
of the catalogs in the organization.
Example 3-2. List the Contents of a Catalog
Request:
GET http://vcloud.example.com/api/v1.0/catalog/32
Response:
200 OKContent-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" ...><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>
vCloud API Programming Guide
36 VMware, Inc.
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
An Entity element that includes the href, type, and name of the object that the CatalogItem references. An Entity can appear in at most one Catalog.
Optional Property elements, each of which is a key=value pair. An organization can use Property elements to implement a key‐based lookup scheme for catalog items.
Example 3-3. Get Information About a CatalogItem
Request:
GET http://vcloud.example.com/api/v1.0/catalogItem/221
Response:
200 OKContent-Type: application/vnd.vmware.vcloud.catalogItem+xml...<CatalogItem name="Ubuntu Template with vsftpd"
href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...><Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml"
href="http://vcloud.example.com/api/v1.0/catalogItem/221"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/><Description>Ubuntu Template with vsftpd</Description><Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"
type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>
<Property key="Company">Example</Property></CatalogItem>
VMware, Inc. 37
Chapter 3 Browsing
List the Contents of a vDC
The response in Example 3‐1 also contains several Vdc elements, each of which represents a vDC object.
Example 3‐4 shows a request to browse one of those vDCs and shows a subset of the response.
Example 3-4. List the Contents of a vDC
Request:
GET http://vcloud.example.com/api/v1.0/vdc/5
Response:
200 OKContent-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="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.uploadVAppTemplateParams+xml"
href="http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate"/><Link rel="add" type="application/vnd.vmware.vcloud.media+xml"
href="http://vcloud.example.com/api/v1.0/vdc/5/media"/><Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml"
href="http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate"/>
<Link rel="add" type="application/vnd.vmware.vcloud.cloneVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVApp"/>
<Link rel="add" type="application/vnd.vmware.vcloud.captureVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/captureVApp"/>
<Link rel="add" type="application/vnd.vmware.vcloud.composeVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/composeVApp"/>
<AllocationModel>AllocationPool</AllocationModel><Description>Example Corp. Primary vDC</Description><StorageCapacity>
<Units>MB</Units><Allocated>1000</Allocated><Limit>1000</Limit><Used>512</Used><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"/>
vCloud API Programming Guide
38 VMware, Inc.
<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.
Getting More Information About an ObjectAn object in a vCloud can be represented by links in various types of XML containers. Regardless of where the
link appears, the object reference it contains (its href attribute value) is always the same. An organization
network can be represented by a link with rel="down" in an organization, or as a member of the
AvailableNetworks element of a vDC.
Catalogs provide a level of indirection for references to media images and vApp templates. A vApp template
or media image can be referenced by a CatalogItem in a catalog or a ResourceEntity in a vDC. The CatalogItem shown in Example 3‐2, a VAppTemplate whose URL is
http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate‐111, is also contained by the vDC
referenced in Example 3‐4. In the Vdc body, the VAppTemplate is represented as ResourceEntity element,
which includes a link (the value of the href attribute) to the template. The Catalog, on the other hand, contains only CatalogItem elements, each of which includes a link that a client can use to get more
information about the object that the CatalogItem represents. Both the ResourceEntity in the Vdc and the CatalogItem in the Catalog refer to the same vApp template. The ResourceEntity element includes a link
that a client can use to GET a representation of the vApp, but a client must first GET a CatalogItem to obtain that kind of link, which is not contained in the Catalog itself.
A ResourceEntity element appears in a Vdc element as soon as the underlying vApp template or media
image has been created. References to those objects do not appear in a catalog until the catalog owner adds
them to it. In most cases, the objects cannot be used until they have been added to a catalog.
Get Information About a Media Image
A client can discover the URL of a media image by browsing in a catalog and examining a CatalogItem to find the Entity element that references the image, or by browsing in a vDC for a ResourceEntity element
that references the image. After client has the image’s URL, it can use it as the target of a GET request, as shown
in Example 3‐5.
If the media image has been included in a catalog, the Media element in the response includes a link to the
CatalogItem that references it.
VMware, Inc. 39
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 OKContent-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"/><Link rel="edit" type="application/vnd.vmware.vcloud.media+xml"
href="http://vcloud.example.com/api/v1.0/media/123"/><Description>ISO Database Image</Description></Media>
Get Information About a vAppTemplate
A client can discover the URL of a vApp template by browsing in a catalog and examining a CatalogItem to find the Entity element that references the template, or by browsing in a vDC for a ResourceEntity element
that references the template. After client has the template’s URL, it can use it as the target of a GET request, as
shown in Example 3‐6, which uses the href of the CatalogItem returned in Example 3‐3.
Example 3-6. Get Information About a vAppTemplate
Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111
Response:
200 OKContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template with vsftpd"
type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" ... >
<Description>Description of Ubuntu Template with vsftpd</Description><Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml"
href="http://vcloud.example.com/api/v1.0/vdc/10"/><Link rel="catalogItem" type="application/vnd.vmware.vcloud.catalogItem+xml"
href="http://vcloud.example.com/api/v1.0/catalogItem/221"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><Link rel="edit" type="application/vnd.vmware.vcloud.vAppTemplate+xml"
href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><Link rel="ovf" type="text/xml"
href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111/ovf"/><Children>
...</Children>
</VAppTemplate>
vCloud API Programming Guide
40 VMware, Inc.
Get Information About a vApp or Virtual Machine
Catalogs cannot contain references to vApps or the virtual machines (Vm objects) that they contain. A client can discover the URL of a vApp by browsing in a vDC for a ResourceEntity element that references it. After
client has the template’s URL, it can use it as the target of a GET request, as shown in Example 2‐8 on page 39
to retrieve the vApp representation and the Vm elements it contains.
Get Information About a Network
Network (OrgNetwork) elements can be contained by Org and Vdc elements. If an organization contains any
networks, each one is referenced by a Link element where rel="down" in the Org body. Each organization network is a member of the AvailableNetworks element in each of the organization’s vDCs.
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"/><Description>Bridged to the Public Internet</Description><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>
<IpRange><StartAddress>10.147.56.1</StartAddress><EndAddress>10.147.56.255</EndAddress></IpRange>
</IpRanges></IpScope><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>
VMware, Inc. 41
4
The vCloud API supports upload and download of OVF packages, and upload of media images. Transfer
operations are characterized as uploads when the operation transfers content from the local host to a remote
one, and as downloads when the local host requests the transfer of content from a remote host. Uploads are
typically initiated by a POST request, and downloads by a GET request. Uploads and downloads are
facilitated by the vCloud transfer service, which provides temporary storage for files.
The vCloud API also supports a clone operation that copies vApps, vApp templates, or media images. The
clone operation also allows you to specify that the source object be deleted after the operation completes,
which effectively moves or renames the source object.
After they have been uploaded or cloned, templates and media images can be added to catalogs as needed.
This chapter includes the following topics:
“Summary of Provisioning Requests” on page 41
“Upload OVF to Create a vApp Template” on page 42
“View the OVF Descriptor of a vApp Template” on page 47
“Download a vApp Template as OVF” on page 47
“Upload a Media Image” on page 50
“Copying and Moving” on page 50
“Changing a Name or Description” on page 53
“Delete a vAppTemplate, vApp, or Media Image” on page 54
“Cataloging vApp Templates and Media Images” on page 54
“Controlling Access” on page 56
Summary of Provisioning RequestsTable 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.
Provisioning 4
Table 4-1. Summary of Provisioning Requests
Operation Request Request Body Response
Upload OVF to Create a vApp Template
POST API‐URL/vdc/id/action/uploadVAppTemplate
UploadVAppTemplateParams VAppTemplate
Download a vApp Template as OVF
GET download‐URL None Depends on file type
vCloud API Programming Guide
42 VMware, Inc.
Upload OVF to Create a vApp TemplateA vCloud API client that has access to an OVF package can use a simple workflow to upload the package and
create a vApp template.
1 The client POSTs an initial request that specifies a name for the template, a transfer format for the data,
and an optional description.
2 The server returns an unresolved (status="0") vAppTemplate document that includes an upload URL
for the OVF package.
3 The client uses an HTTP PUT request to upload the OVF package descriptor (the .ovf file) to the upload
URL.
4 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
5 The client uses HTTP PUT requests to upload each of the files.
6 If the OVF package includes a manifest file, the entire upload is validated against the contents of the
manifest file.
Enable a vApp Template for Download
POST API‐URL/vAppTemplate/vAppTemplate‐id/action/enableDownload
None Task
Disable a vApp Template for Download
POST API‐URL/vAppTemplate/vAppTemplate‐id/action/disableDownload
None 204 No Content
Upload a Media Image POST API‐URL/vdc/id/media Media Media
Copy or Move a Media Image
POST API‐URL/vdc/id/action/cloneMedia CloneMediaParams Media
Copy or Move a vApp Template
POST API‐URL/vdc/id/action/cloneVAppTemplate
CloneVAppTemplateParams VAppTemplate
Copy or Move a vApp POST API‐URL/vdc/id/action/cloneVApp CloneVAppParams VApp
Change the Name or Description of a vAppTemplate
PUT API‐URL/vAppTemplate/vappTemplate‐id VAppTemplate Task
Change the Name or Description of a vApp
PUT API‐URL/vApp/vapp‐id VApp Task
Change the Name or Description of a Media Image
PUT API‐URL/media/id Media Task
Delete a vAppTemplate, vApp, or Media Image
DELETE object‐URL None Task
Add an Item to a Catalog POST API‐URL/catalog/id/catalogItems CatalogItem CatalogItem
Remove an Item from a Catalog
DELETE API‐URL/catalog/id/catalogItem/id
None 204 No content
Control Access to Catalogs POSTAPI‐URL/catalog/id/action/controlAccess
ControlAccessParams ControlAccessParams
Table 4-1. Summary of Provisioning Requests (Continued)
Operation Request Request Body Response
VMware, Inc. 43
Chapter 4 Provisioning
Both monolithic and ranged (chunked) PUTs are supported. After starting an upload, a client can make
periodic requests to determine its progress. After all the files are uploaded (and validated if a manifest is
present), the server processes the uploads. When processing is complete, the server sets the value of the
template’s status attribute to 8, indicating that the template is ready for use. (This status value indicates that
all of the virtual machines in the template are powered off. For more information, including a complete list of
possible status values and their meanings, see “status” on page 144.)
Restrictions on Uploaded Content
This release of the vCloud API imposes the following restrictions on uploaded OVF content:
You can upload either OVF 1.0 or OVF 1.1 content. OVF 1.1 packages are converted to OVF 1.0 for
download, and any OVF 1.1 content is lost.
You cannot upload a compressed OVF package.
If you upload an OVF package in which any VirtualSystem element has an ovf:id attribute value that is longer than 13 characters, the name of the Vm that represents the VirtualSystem in the vAppTemplate created by the upload is rewritten as the first 13 characters of the ovf:id attribute followed by three
digits. For example, NewVirtualMachine1 and NewVirtualMachine2 become NewVirtualMa001 and
NewVirtualMa002.
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/uploadVAppTemplateContent-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 CreatedContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml
<VAppTemplate name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" status="0" ovfDescriptorUploaded="false" 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 name="descriptor.ovf" bytesTransferred="0"><Link rel="upload:default"
href="http://vcloud.example.com/transfer/.../descriptor.ovf"/></File>
</Files></VAppTemplate>
vCloud API Programming Guide
44 VMware, Inc.
The response body includes the following attributes:
An href attribute whose value is a link to the newly created vApp template object.
An ovfDescriptorUploaded attribute with a value of false, indicating that the OVF descriptor file has not yet been uploaded
A status attribute with a value of 0, indicating that the file references in the descriptor have not yet been
uploaded. (A VAppTemplate with a status of 0 is said to be unresolved.)
It also includes a File element with an upload URL (rel="upload:default") for the OVF descriptor. The name attribute of this File element has been created by the server and specifies a container that the server has
created to receive the contents of the descriptor. It has no relation to the file name of the descriptor in the
client’s file system.
The client uploads the OVF descriptor by making a PUT request to the upload URL, and supplying the
descriptor’s contents as an Envelope element in the request body. The server responds with a 200 OK status,
as shown in Example 4‐3.
Example 4-3. Upload OVF Descriptor
Request:
PUT http://vcloud.example.com/transfer/.../descriptor.ovfContent-Type text/xml...<Envelope ... >
...</Envelope>
Response:
200 OK
After the descriptor is uploaded, the server validates it and, if it is valid, creates upload URLs for each of the
files it references. To track the progress of this operation, the client can make periodic GET requests to the
vAppTemplate URL. When the operation is complete, the response to this kind of request includes additional
File elements beyond the one already created for the descriptor, as shown in Example 4‐4.
Example 4-4. GET vAppTemplate with Upload URLs
Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268
Response:
200 OKContent-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. 45
Chapter 4 Provisioning
<File size="1950489088" bytesTransferred="0" name="disk0.vmdk"><Link rel="upload:default" href="http://vcloud.example.com/transfer/.../disk0.vmdk"/>
</File></Files>
</VAppTemplate>
In this example, the ovfDescriptorUploaded attribute has a value of true and the status attribute has a value of 0. If the descriptor fails validation, the status is set to ‐1, and the template contains a Task element
whose Error element indicates the reason for the failure.
Each of the File elements includes an upload link (<Link rel="upload:default" ... />) and several attributes:
size. The file size, taken from the size attribute of the File element in the OVF descriptor.
bytesTransferred. For all file references other than the descriptor, this attribute is initially set to a value of
0 indicating that the upload has not yet begun. In the File reference to the descriptor, the value of the bytesTransferred attribute is equal to the value of the size attribute, indicating that all the bytes in the descriptor have been transferred.
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/uploadVAppTemplateContent-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.
Uploading the Files
Information from the server’s response in Example 4‐3 enables the client to construct a series of PUT requests,
one for each File in the list, that upload the files referenced by the template. Each request specifies an upload
URL and a content length in bytes.
Example 4‐6 shows an upload request for one of the files required by an OVF package. The upload request is
simply a few header lines, followed by the serialized file content.
vCloud API Programming Guide
46 VMware, Inc.
Example 4-6. Uploading File Data
Request:
PUT http://vcloud.example.com/transfer/.../disk0.vmdkContent-length: 1950489088
...serialized contents of file disk0.vmdk...
EOF
Response:
200 OK
To monitor the progress of an upload, a client can use an HTTP GET request specifying the VAppTemplate URL that was returned in the upload map. The response is the same upload map. After all the files have been
uploaded, the response includes a Task that the vAppTemplate creates to monitor the events leading up to its
resolution, and an updated value for the bytesTransferred attribute of each File element, as shown in
Example 4‐7. (The complete VAppTemplate body is returned. This example omits most of it for clarity.)
Example 4-7. Monitoring the Progress of an Upload
Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268
Response:
200 OK<VAppTemplate name="Ubuntu Template"
href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" status="0" ... >
...<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.
Example 4-8. Ranged PUT to Complete a Partial Upload
Request:
PUT http://vcloud.example.com/transfer/.../disk0.vmdkkContent-Range: bytes 500000000-1950489087/1950489088Content-length: 1450489088
...serialized contents of specified range...
EOF
NOTE Ranged PUT requests are typically required for very large uploads, especially when network
bandwidth or latency could cause the operation to time out.
VMware, Inc. 47
Chapter 4 Provisioning
Response:
200 OK
View the OVF Descriptor of a vApp TemplateThe representation of a resolved vApp template includes a link to its OVF descriptor.
<Link rel="ovf" type="text/xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/ovf"/>
A GET request specifying the URL in the href value of this Link returns the descriptor, as shown in
Example 4‐9. Only resolved VAppTemplate elements include this link. To get the OVF descriptor that defines
a vApp or virtual machine, you must start with the template from which it was created.
When you view the OVF descriptor of a vApp template, it includes deployment‐specific information.
Example 4-9. View the OVF Descriptor of a vApp Template
Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/ovf
Response:
200 OKContent-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>
Download a vApp Template as OVFA 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.
NOTE 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.
vCloud API Programming Guide
48 VMware, Inc.
Enable a vApp Template for Download
A vApp template must be explicitly enabled for download by an administrator or privileged user.
Example 4‐10 shows such a request. The response is a Task element. The time required for the task to complete
is determined by the number and size of the files comprising the template.
Example 4-10. Enable a vApp Template for Download
Request:
POST http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/action/enableDownload
Response:
202 AcceptedContent-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
Response:
200 OKContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template"
type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" ...>
...<Link type="text/xml" rel="download:default"
href="http://vcloud.example.com/transfer/.../descriptor.ovf"/>...
</VAppTemplate>
The client uses this download:default URL in a GET request that downloads the OVF descriptor (as shown
in Example 4‐12), then examines the contents of the descriptor to discover the href values for the remaining
files in the template’s References container.
Example 4-12. Downloading the OVF Descriptor
Request:
GET http://vcloud.example.com/transfer/..../descriptor.ovf
Response:
200 OK...<Envelope ...>
<References><File ovf:href="disk0.vmdk" ovf:id="file1" ovf:size="1950489088"/>
</References><DiskSection>
<Info>Virtual disk information</Info>
VMware, Inc. 49
Chapter 4 Provisioning
<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>
In this example, the descriptor references only one file:
<File ovf:href="disk0.vmdk" ovf:id="file1" ovf:size="1950489088"/>
The href attribute of the File element is the path to the file relative to the location of the descriptor itself. To
retrieve this file from the server, the client must make a GET request to a URL that it constructs with a simple
two‐step algorithm:
1 Start with the URL that was contained in the download:default attribute of the Link to the descriptor that was contained by template. (See Example 4‐11.)
2 Replace the final component of that URL with the value of the href attribute of the File in the downloaded OVF descriptor.
The result of this process, using the responses in Example 4‐11 and Example 4‐12, is the request URL shown
in Example 4‐13.
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...
EOF
When the download completes, the vApp template is available on the client as an OVF package.
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
NOTE 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).
vCloud API Programming Guide
50 VMware, Inc.
After the disableDownload request completes, the template’s files are removed from the transfer server, and
the Link element that contains the download:default URL no longer appears in the vAppTemplate body.
Upload a Media ImageThe vCloud API supports uploading virtual media such as CD‐ROM and floppy disk images. The workflow
for these procedures is similar to that described for vApp template uploads; the client POSTs a request to the
server that includes information about a virtual media item it intends to upload, and the server responds with
an upload URL, which the client can use to do a monolithic or ranged PUT of the file contents.
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/mediaContent-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+xml201 Created
<Media name="database.iso" size="242131" status="0" imageType="iso" href="http://vcloud.example.com/api/v1.0/media/254" type="application/vnd.vmware.vcloud.media+xml" ...>
<Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/>
<Description>ISO database image</Description><Files>
<File name="database.iso" size="242131" bytesTransferred="0" <Link rel="upload:default" href="http://vcloud.example.com/.../database.iso"/>
</File></Files>
</Media>
During the upload, the value of the bytesTransferred attribute of the File element indicates upload
progress. When the upload is complete, the value of the status attribute is set to 1, and the Files element is
no longer included in the Media representation.
Copying and MovingThe vCloud API provides object‐specific copy operations for media images, vApp templates, and vApps.
These operations support creating a copy of the object in the same vDC or in another vDC within the same
organization. Each copy operation supports an option to delete the source object after the copy is complete,
which effectively moves the source object to another vDC, or renames it within the same vDC. The vCloud API
does not include an explicit move operation.
NOTE Downloading media images is not supported in this release of Cloud Director.
VMware, Inc. 51
Chapter 4 Provisioning
When you move an object by copying it and deleting its source, an intermediate object is created in the target
vDC, as part of the following sequence of events.
1 The source object is coped to an intermediate object whose name is a combination of the object name and
a UUID.
2 The source object is deleted.
3 The intermediate object is renamed with the name specified for the target object in the copy request.
Copy or Move a Media Image
The cloneMedia request makes a copy of the media image 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 media image 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 media image.
Example 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/cloneMediaContent-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" type="application/vnd.vmware.vcloud.media+xml" ...>
<Link rel="up" href="http://vcloud.example.com/api/v1.0/vdc/5"/><Description>This is a backup copy of the ISO database image</Description><Tasks>
<Task ... operation="Busy Media File cloned(277)" ... >...
</Task></Tasks>
</Media>
Copy or Move a vApp Template
The cloneVAppTemplate request makes a copy of the vApp template 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 template
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 template.
Example 4‐18 moves the vApp template referenced by
http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate‐111 to the vDC referenced by
http://vcloud.example.com/api/v1.0/vdc/5. Because the IsSourceDelete element in the request body
contains a value of true, the source vApp template is removed after the copy is complete.
vCloud API Programming Guide
52 VMware, Inc.
Example 4-18. Move a vAppTemplate
Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVAppTemplateContent-Type: application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml<CloneVAppTemplateParams name="Ubuntu Copy" xmlns="http://www.vmware.com/vcloud/v1">
<Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><IsSourceDelete>true</IsSourceDelete>
</CloneVAppTemplateParams>
Response:
201 CreatedContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate ovfDescriptorUploaded="true" status="0" name="Ubuntu Copy"
href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-302" 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"/>
...<Tasks>
<Task ... operation="Busy Virtual Application Template Ubuntu Copy (382)" ...>...
</Task></Tasks>
</VAppTemplate>
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/cloneVAppContent-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. 53
Chapter 4 Provisioning
Response:
201 CreatedContent-Type: application/vnd.vmware.vcloud.vApp+xml
<VApp name="New Linux Server" status="0" href="http://vcloud.example.com/api/v1.0/vApp/vapp-999" ...>
<Description>Cloned from Ubuntu FTP Server</Description>...<Tasks>
<Task ... operation="Busy Virtual Application New Linux Server Copy (201)" ...>...
</Task></Tasks>
</VApp>
Changing a Name or DescriptionEvery vAppTemplate, vApp, and Media element includes an edit link that a client can use if to change the value of the object’s name attribute or Description element. In each case, the request must include all the
required elements of the object’s representation, even the ones that you are not changing.
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 39.
Example 4-20. Change the Name and Description of a vAppTemplate
Request:
PUT http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111Content-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 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ...>
...</Task>
Change the Name or Description of a vApp
You can change the name or description of a vApp using a procedure similar to the one shown in
Example 4‐20.
vCloud API Programming Guide
54 VMware, Inc.
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/277Content-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 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ...>
...</Task>
Delete a vAppTemplate, vApp, or Media ImageYou can use an HTTP DELETE request to delete a vAppTemplate, vApp, or media image. All of these
operations conform to the prototype (DELETE href, where href is the URL of the object you want to delete)
shown in Example 2‐10 on page 30. You cannot delete an object if it is in use. Any object that is being copied
or moved is in use. Other criteria that determine whether an object is in use depend on the object type.
A vApp template is in use if it is being instantiated. After instantiation is complete, the template is no
longer in use.
A vApp is in use if it is deployed.
A media image is in use if it is inserted in a Vm.
Cataloging vApp Templates and Media ImagesAlthough references to vApp templates and media images can be retrieved directly from the vDC to which
they were uploaded, it is a common practice to place references to such assets in one of an organization’s
catalogs. Doing so makes the asset easier to discover, because a catalog can include assets from all vDCs in an
organization. It also provides more flexible administrative control over these assets, because access to catalogs
and the items in them can be restricted to specific users and groups. Assets such as vApp templates are not
enabled for most uses until you include them in a catalog. For example, a vApp template that is not included
in a catalog can be modified but cannot be instantiated. A media image that is not included in a catalog cannot
be used by anyone but its owner.
Add an Item to a Catalog
A catalog can contain references to vApp templates and media images that have been uploaded to any vDC
in an organization. A vApp template or media image can be listed in at most one catalog.
VMware, Inc. 55
Chapter 4 Provisioning
To add an item to a catalog
1 Browse the vDCs in an organization to find ResourceEntity elements that reference the item you want
to add to the catalog.
2 Create a CatalogItem element that contains a reference to the item.
Example 3‐4 on page 37 lists a number of ResourceEntity elements in a vDC. To create a CatalogItem that references this one:
<ResourceEntity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>
follow these guidelines:
The name attribute of the CatalogItem can be the same as the one in the ResourceEntity, or you can make up a new value for name.
The Description element of the CatalogItem can be the same as the Description element for the
object referenced by the ResourceEntity, or you can make up a new Description.
The href attribute of the Entity element in the CatalogItem must have the same value as the href attribute of the ResourceEntity that the CatalogItem references.
Property elements are optional in any CatalogItem. For more information about how these elements
can be used, see Property on page 161.
3 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 35.
Example 4-22. Add an Item to a Catalog
Request:
POST http://vcloud.example.com/api/v1.0/catalog/32/catalogItemsContent-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 CreatedContent-Type: application/vnd.vmware.vcloud.catalogItem+xml...<CatalogItem name="Ubuntu Template with vsftpd"
type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...>
<Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/>
<Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32"/>
<Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/><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>
vCloud API Programming Guide
56 VMware, Inc.
Remove an Item from a Catalog
A organization administrator or a user with adequate permissions can remove a CatalogItem by making a
DELETE request to the its rel="remove" link. Example 4‐23 removes the CatalogItem created in Example 4‐22.
Example 4-23. Remove a CatalogItem
Request:
DELETE http://vcloud.example.com/api/v1.0/catalogItem/221
Response:
204 No Content
Catalog Links in a VApp Template or Media Image
Every vAppTemplate and Media element that has been added to a catalog contains a rel="catalogItem" link whose href value is the URL of the CatalogItem that references the template or media image (see the
response in Example 3‐6 on page 39). A client can GET that URL and examine the response to find the
rel="up" link in the CatalogItem (see the response in Example 4‐22). This link is a reference to the catalog
that contains the CatalogItem.
Controlling AccessAn 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 34.
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"/><Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml"
href="http://vcloud.example.com/api/v1.0/catalog/37/controlAccess/"/><Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml"
href="http://vcloud.example.com/api/v1.0/catalog/37/action/controlAccess/"/>...
</Org>
For each of the catalogs listed in this excerpt, three links are provided:
A Link with rel="down" that provides the URL for the catalog itself
Another Link with rel="down" that a client can use to retrieve the catalog’s access control settings
A Link with rel="controlAccess" that a client can use to modify the catalog’s access control setting
An organization administrator or privileged user can use these links to view or modify access controls on a
catalog. Example 4‐25 shows the request to view the access control settings for a catalog.
VMware, Inc. 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 OKContent-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/controlAccessContent-Type: application/vnd.vmware.vcloud.controlAccess+xml
<ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1"><IsSharedToEveryone>false</IsSharedToEveryone><AccessSettings>
<AccessSetting><Subject type="application/vnd.vmware.admin.user+xml"
href="http://vcloud.example.com/api/v1.0/admin/user/1"/><AccessLevel>FullControl</AccessLevel>
</AccessSetting><AccessSetting>
<Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/6"/>
<AccessLevel>ReadOnly</AccessLevel></AccessSetting>
</AccessSettings></ControlAccessParams>
Response:
200 OKContent-Type: application/vnd.vmware.vcloud.controlaccess+xml...<ControlAccessParams ...>
<IsSharedToEveryone>false</IsSharedToEveryone><AccessSettings>
<AccessSetting><Subject type="application/vnd.vmware.admin.user+xml"
href="http://vcloud.example.com/api/v1.0/admin/user/1"/><AccessLevel>FullControl</AccessLevel>
</AccessSetting><AccessSetting>
<Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/6"/>
<AccessLevel>ReadOnly</AccessLevel></AccessSetting>
</AccessSettings></ControlAccessParams>
vCloud API Programming Guide
58 VMware, Inc.
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/controlAccessContent-Type: application/vnd.vmware.vcloud.controlAccess+xml...<ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1">
<IsSharedToEveryone>true</IsSharedToEveryone><EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel>
</ControlAccessParams>
Response:
200 OKContent-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 89.
VMware, Inc. 59
5
The vCloud API supports programmatic access to a range of self‐service datacenter operations that allow users
to create, configure, operate, and connect to vApps.
This chapter includes the following topics:
“Summary of Datacenter Operations Requests” on page 59
“vApp Lifecycle” on page 60
“Instantiate a vApp Template” on page 61
“Compose a vApp” on page 65
“Recompose a vApp to Add or Remove Virtual Machines” on page 67
“Capture a vApp to Create a vApp Template” on page 68
“Reconfiguring vApps and Virtual Machines” on page 69
“Deploying and Controlling vApps and Virtual Machines” on page 80
“Control Access to vApps” on page 89
“Retrieve a Task” on page 89
Summary of Datacenter Operations RequestsTable 5‐1 summarizes datacenter operations 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
vApp‐or‐Vm‐URL is a URL of the form API‐URL/vApp/vapp‐id (for a vApp object) or
API‐URL/vApp/vm‐id (for a Vm object)
Datacenter Operations 5
Table 5-1. Summary of Datacenter Operations Requests
Operation Request Request Body Response
Instantiate a vApp Template POST API‐URL/vdc/id/action/instantiateVAppTemplate
InstantiateVAppTemplateParams VApp
Retrieve vApp Template CustomizationSection
GET API‐URL/vAppTemplate/vappTemplate‐id/customizationSection
None CustomizationSection
Modify vApp Template CustomizationSection
PUT API‐URL/vAppTemplate/vappTemplate‐id/customizationSection
CustomizationSection Task
Compose a vApp POST API‐URL/vdc/id/action/composeVApp
ComposeVAppParams VApp
vCloud API Programming Guide
60 VMware, Inc.
vApp LifecycleA 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
Recompose a vApp to Add or Remove Virtual Machines
POST API‐URL/vApp/vapp‐id/action/recomposeVApp
RecomposeVAppParams Task
Capture a vApp to Create a vApp Template
POST API‐URL/vdc/id/action/captureVApp
CaptureVAppParams VAppTemplate
Deploy a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/action/deploy
DeployVAppParams Task
Undeploy a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/action/undeploy
UndeployVAppParams Task
Power On a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/power/action/powerOn
None Task
Power Off a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/power/action/powerOff
None Task
Reset a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/power/action/reset
None Task
Suspend a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/power/action/suspend
None Task
Discard the Suspended State of a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/action/discardSuspendedState
None Task
Shut Down a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/power/action/shutdown
None 204 No Content
Reboot a vApp or Virtual Machine
POST vApp‐or‐Vm‐URL/power/action/reboot
None 204 No Content
Insert Media Into a Virtual Machine
POST API‐URL/vApp/vm‐id/media/action/insertMedia
MediaInsertOrEjectParams Task
Eject Media from a Virtual Machine
POST API‐URL/vApp/vm‐id/media/action/ejectMedia
MediaInsertOrEjectParams Task
List Media Devices of a Virtual Machine
GET API‐URL/vApp/vm‐id/virtualHardwareSection/media
None RasdItemsList
Get a Request for User Input GET API‐URL/vApp/vm‐id/question
None VmPendingQuestion
Provide Requested User Input
POST API‐URL/vApp/vm‐id/question/action/answer
VmQuestionAnswer 204 No Content
Get a Screen Thumbnail for a Virtual Machine
GET API‐URL/vApp/vm‐id/screen
None screen thumbnail (Content‐type: image/png)
Get a Screen Ticket for a Virtual Machine
POST API‐URL/vApp/vm‐id/screen/action/acquireTicket
None ScreenTicket
Control Access to vApps POST API‐URL/vApp/vapp‐id/action/controlAccess
ControlAccessParams ControlAccessParams
Retrieve a Task GET API‐URL/task/id None Task
Table 5-1. Summary of Datacenter Operations Requests (Continued)
Operation Request Request Body Response
VMware, Inc. 61
Chapter 5 Datacenter Operations
An undeployed vApp, created when a vApp template is instantiated or a deployed vApp is undeployed.
A deployed vApp, ready to be powered on and operated. You can specify that instantiation include
deployment, power‐on, or both.
Figure 5‐1 illustrates these state transitions.
Figure 5-1. vApp State Transitions
OVF upload and the creation of vApp templates is covered in “Upload OVF to Create a vApp Template” on
page 42.
Instantiate a vApp TemplateA 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.
descriptor.ovf
OVF package
<VApp Template...status=”8” href=”http://.../vapp Template-3”> ... ...</VApp Template>
instantiate
<VApp...status=”8” deployed=“false” href=”http://.../vapp-9”> ... <Link rel=”deploy”...> ...</VApp>
deploy
disk0.vmdk
upload
vApptemplate
vApp
<VApp...status=”8” deployed=“true” href=”http://.../vapp-9”> ... <Link rel=”power:powerOn”...> ...</VApp>
vApp
vCloud API Programming Guide
62 VMware, Inc.
About Instantiation Parameters
Instantiation parameters allow you to specify certain properties of a vApp, including:
Details of its vApp network (required).
Lease settings for the vApp (optional, if you want to override your organization’s defaults)
Startup and shutdown parameters for the vApp (applicable only if the vApp has multiple children)
Instantiation parameters also include a way to indicate that any terms and conditions (such as license
agreements) contained in the vApp have been accepted.
Instantiation parameters cannot be used to modify a Vm that appears in the vApp’s Chldren container. To change the properties of a Vm, use the reconfiguration links in its Item elements. (See “Reconfiguring vApps
and Virtual Machines” on page 69.)
About vApp Networks
A vApp network is a logical network that defines how the vApp connects to an organization network in the
target vDC. It is specified as part of an instantiateVAppTemplate or composeVApp request, created when
the vApp is deployed, and deleted when the vApp is undeployed. Virtual machines (Vm elements) in the
vApp’s Children collection all connect to this network, as specified in their NetworkConnection elements.
The details of a vApp network are specified in the NetworkConfig element of the
InstantiateVAppTemplateParams request body, and include the following:
A name for the vApp network, specified in the networkName attribute of the NetworkConfig element. If
the template that you are instantiating includes an ovf:NetworkSection element, the value of the
networkName attribute of the NetworkConfig element must match the value of the ovf:name attribute of the ovf:Network element in the template. If the template defines multiple networks, then you must do
the same in the InstantiateVAppTemplateParams request.
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. 63
Chapter 5 Datacenter Operations
Examine the template’s ovf:NetworkSection element to see whether any networks are defined there. If
the vApp template includes an ovf:Network element, the name you specify for the vApp network must
match the name specified in that element’s ovf:name attribute.
See “About Instantiation Parameters” on page 62.
Verify that your organization’s default lease settings are appropriate for this vApp. If they are not, you can
specify custom lease settings as part of instantiation.
Example 5‐1 shows an instantiation request similar to the one shown in Example 2‐6 on page 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">
<Configuration><ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/><FenceMode>bridged</FenceMode>
</Configuration></NetworkConfig>
</NetworkConfigSection><LeaseSettingsSection type="application/vnd.vmware.vcloud.leaseSettingsSection+xml">
<ovf:Info>Lease Settings</ovf:Info><StorageLeaseInSeconds>172800</StorageLeaseInSeconds><StorageLeaseExpiration>2010-04-11T08:08:16.438-07:00</StorageLeaseExpiration>
</LeaseSettingsSection></InstantiationParams><Source href=”http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111”/><AllEULAsAccepted>true</AllEULAsAccepted>
</InstantiateVAppTemplateParams>
Response:
201 CreatedContent-Type: application/vnd.vmware.vcloud.vApp+xml
<VApp name="Linux FTP server" deployed=”false” status="0" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...>
<Description>Example FTP Server</Description>...<Tasks>
<Task ... operation="Creating Virtual Application Linux FTP server(7)" ... >...
</Task></Tasks>
</VApp>
vCloud API Programming Guide
64 VMware, Inc.
The response is a sparsely populated vApp body that contains a Task element The status of the vApp is initially
0. When instantiation is complete and the vApp is powered on, the Task no longer appears in the vApp body, and the vApp status changes to 4, indicating that all of its children are powered on. You can check the status
of the task by issuing a GET request to the task URL or you can check the status of the vApp by issuing a GET
request to the vApp URL. These URLs are returned in the value of the object’s href attribute.
Retrieve or Modify the CustomizationSection of a vApp Template
A vApp template can include a CustomizationSection element that specifies whether or not the virtual
machines in the vApp should be customized when the vApp is instantiated. Example 5‐2 retrieves this section
from a vApp template.
Example 5-2. Retrieve vApp Template CustomizationSection
Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection
Response:
200 OKContent-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/customizationSectionContent-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>false</CustomizeOnInstantiate>
</CustomizationSection>
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ...>
...</Task>
VMware, Inc. 65
Chapter 5 Datacenter Operations
Compose a vAppThe vCloud API supports composing a vApp from any combination of vApp templates, vApps, or virtual
machines. When you compose a vApp, all children of each composition source become peers in the Children collection of the composed vApp.
To compose a vApp, a client makes a composeVApp request whose body, a ComposeVAppParams element,
includes the following information:
An InstantiationParams element that applies to the composed vApp itself and any vApp templates
referenced in Item elements. For more information, see “About Instantiation Parameters” on page 62.
An Item element for each virtual machine, vApp, or vAppTemplate to include in the composition. Each
Item can contain the following elements:
A required Source element whose href attribute value is a reference to a vApp template, vApp, or
Vm to include in the composition. If the Source element references a Vm, the Item must also include
an InstantiationParams element specific to that Vm.
An optional NetworkAssignment element that specifies how the network connections of child Vm elements are mapped to vApp networks in the parent.
If any of the composition items is subject to a EULA, the ComposeVAppParams element must include an
AllEULAsAccepted element that has a value of true, indicating that you accept the EULA. Otherwise,
composition fails.
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/composeVAppContent-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></InstantiationParams><Item>
<Source href="http://vcloud.example.com/api/v1.0/vApp/vm-4"/><InstantiationParams>
<NetworkConnectionSection type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ovf:required="false">
<ovf:Info/><PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex><NetworkConnection network="CRMApplianceNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex><IsConnected>true</IsConnected><IpAddressAllocationMode>DHCP</IpAddressAllocationMode>
</NetworkConnection>
vCloud API Programming Guide
66 VMware, Inc.
</NetworkConnectionSection></InstantiationParams>
</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 CreatedContent-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 element. The status of the vApp is initially 0. When composition is complete, the status changes to 1.
Finding Virtual Machine URLs to Use in a Composition Item
Virtual machines (Vm objects) are not listed in catalogs or vDCs. To find the URL of a Vm URL to include in a composition item Source, GET a vApp or vApp template that includes it, and examine the Children container of the VApp element. Each Vm in this container has an href attribute whose value you can use to
reference the Vm for this (or any other) purpose.
The Vm URL used in Example 5‐4 appears in the Children element of Example 5‐5.
Example 5-5. Vm URL in a vApp Body
Request:
GET http://vcloud.example.com/api/v1.0/vApp/vapp-7
Response:
200 OKContent-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"
...>...<Children>
<Vm status="8" href="http://vcloud.example.com/api/v1.0/vApp/vm-4" ...>...
</Children></VApp>
NOTE To be included in a composition request, a Vm must be powered off (status="8").
VMware, Inc. 67
Chapter 5 Datacenter Operations
Recompose a vApp to Add or Remove Virtual MachinesThe vCloud API supports recomposition of a vApp to add or remove virtual machines (Vm elements). To
recompose a vApp, a client makes a recomposeVApp request, supplying a RecomposeVAppParams element as
the request body. The RecomposeVAppParams element allows an arbitrary number of DeleteItem elements,
but is otherwise identical to ComposeVAppParams. This means that in addition to adding or removing virtual
machines, a recomposeVApp request can also change the name and description of the vApp, and can supply
new InstantiationParams to change various sections of the composed vApp or any of the added virtual
machines.
Example 5-6. vApp Before Recomposition
Request:
GET http://vcloud.example.com/api/v1.0/vApp/vapp-33
Response:
200 OKContent-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" ...>...</Vm><Vm status="8" name="CRM-HTTP" href="http://vcloud.example.com/api/v1.0/vApp/vm-45" ...>...</Vm>
</Children>...
</VApp>
Example 5‐7 shows a recomposeVApp request that modifies the vApp shown in Example 5‐6 by removing one
of the virtual machines it contains and creating a new StartupSection that specifies a startup order for the two virtual machines that remain in the vApp.
Example 5-7. Recompose a vApp
Request:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-33/action/recomposeVAppContent-Type: application/vnd.vmware.vcloud.recomposeVAppParams+xml...<RecomposeVAppParams 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>
vCloud API Programming Guide
68 VMware, Inc.
<ovf:StartupSection xmlns:vcloud="http://www.vmware.com/vcloud/v1" vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vapp-33/startupSection/" vcloud:type="application/vnd.vmware.vcloud.startupSection+xml">
<ovf:Info>VApp startup section</ovf:Info><ovf:Item ovf:order="0" ovf:id="CRM-DB"/><ovf:Item ovf:order="1" ovf:id="CRM-CRM"/>
</ovf:StartupSection></InstantiationParams><AllEULAsAccepted>true</AllEULAsAccepted><DeleteItem href="http://vcloud.example.com/api/v1.0/vApp/vm-45" />
</RecomposeVAppParams>
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Updating Virtual Application Example Corp’s CRM Appliance (33)" ...>
...</Task>
Capture a vApp to Create a vApp TemplateThe 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.
Example 5-8. Capture a vApp
Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/captureVAppContent-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 CreatedContent-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" ...>
<Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/>
<Description>Template captured from Ubuntu vApp</Description><Tasks>
<Task ... operation="Capturing Virtual Application Template CaturedTemplate (20)" ... >...
</Task></Tasks>...
</VAppTemplate>
The response is a vAppTemplate document that contains a Task. The status of the vAppTemplate is initially 0. When the capture operation is complete, the status changes to 8.
NOTE Before it can be captured, a vApp must be undeployed (deployed="false").
VMware, Inc. 69
Chapter 5 Datacenter Operations
Reconfiguring vApps and Virtual MachinesConfiguration details for vApps and the virtual machines they contain are specified in ovf:SectionType elements such as LeaseSettingsSection, NetworkConfigSection, and OperatingSystemSection. These sections can be specified in the InstantiationParams for the vApp or Vm, and can also be edited in place using reconfiguration links (Link elements where rel="edit") that the server adds to these sections during instantiation. For more information about the sections that can be included in InstantiationParams, see “InstantiationParams” on page 172.
The reconfiguration process for vApps and virtual machines is similar, but the set of sections that can be edited
during reconfiguration depends on the object being reconfigured.
Reconfigure a vApp
Table 5‐2 summarizes vApp reconfiguration 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
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.
Table 5-2. Summary of vApp Reconfiguration Requests
Operation Request Request Body Response
Retrieve vApp Lease Settings GET API‐URL/vApp/vapp‐id/leaseSettingsSection/
None LeaseSettingsSection
Modify vApp Lease Settings PUT API‐URL/vApp/vapp‐id/leaseSettingsSection/
LeaseSettingsSection Task
Retrieve vApp Startup Section GET API‐URL/vApp/vapp‐id/startupSection/
None StartupSection
Modify vApp Startup Section PUT API‐URL/vApp/vapp‐id/startupSection/
StartupSection Task
Retrieve vApp Network Section GET API‐URL/vApp/vapp‐id/networkSection/
None ovf:NetworkSection
Retrieve vApp Network Configuration GET API‐URL/vApp/vapp‐id/networkConfigSection/
None NetworkConfigSection
Modify vApp Network Configuration PUT API‐URL/vApp/vapp‐id/networkConfigSection/
NetworkConfigSection Task
NOTE 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 75.
vCloud API Programming Guide
70 VMware, Inc.
Example 5-9. Configuration Links for a vApp
Request:
GET http://vcloud.example.com/api/v1.0/vApp/vapp-7
Response:
200 OKContent-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/"/></ovf:StartupSection><ovf:NetworkSection ... >
... </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 ... >
...<Configuration>
...</Configuration><IsDeployed>false</IsDeployed>
</NetworkConfig></NetworkConfigSection><Children>
...</Children>
</VApp>
VMware, Inc. 71
Chapter 5 Datacenter Operations
To modify a section
1 Retrieve the vApp or vApp template and examine the response to find the section that you want to
modify.
2 Retrieve the section by making a GET request to the section’s edit link (a Link element in the section
where rel="edit").
3 Modify the section as needed.
4 PUT the modified section to the section’s edit link. Note that section edit URLs, unlike most other URLs
presented by the vCloud API, end with a / character.
Retrieve or Modify the NetworkConfigSection of a vApp Template
Example 5‐10 retrieves a vApp’s network configuration (NetworkConfigSection). Example 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 OKContent-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>
<IpRange><StartAddress>10.147.56.1</StartAddress><EndAddress>10.147.56.255</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>bridged</FenceMode>
</Configuration><IsDeployed>false</IsDeployed>
</NetworkConfig></NetworkConfigSection>
The modified NetworkConfigSection in the request body in Example 5‐11 changes the FenceMode value to natRouted and adds a Features element that defines several network features useful to an FTP server that
must be reachable from the public Internet, but only at the FTP port and the SSH port.
NOTE Sections that do not have a Link where rel="edit" cannot be modified.
vCloud API Programming Guide
72 VMware, Inc.
A set of FirewallRules that allow TCP traffic to ports 21 and 22. Because these rules require you to specify a single IP address on the inside of the firewall, the IpScope element is modified to limit the range
of IP addresses available on the vApp network to a single address. Any Vm that connects to the vApp network defined in this NetworkConfigSection is given this address.
A NatService element that maps a routable external IP address to the internal IP address allocated to the
Vm by the vApp network. The VAppScopedVmId value in this element is taken from the
VAppScopedLocalId element of the Vm and the VmNicId value is taken from its PrimaryNetworkConnectionIndex. See Example 5‐12 on page 75.
Whenever you modify a vApp network, as we do in this example, you must be sure that the modifications are
consistent with the network connection requirements of the virtual machines that connect to the network. The
vApp in this example contains a single Vm. As shown in Example 5‐12 on page 75, that virtual machine’s
NetworkConnection element specifies an IP address that will not be available after the vApp network has
been reconfigured as shown in Example 5‐11. Example 5‐14 on page 77 corrects this problem. While
Example 5‐11 uses the IpScope element to restrict the IP addresses available on a vApp network, it is usually
more practical to keep the range of addresses available on a vApp network somewhat wider, and apply any
firewall‐related IP address restrictions by modifying the NetworkConnection of the Vm to which the
FirewallRules apply, as we do in Example 5‐14. A wider range of IP addresses would allow this vApp to be
modified to include additional virtual machines, and the IP address restriction applied in Example 5‐14 would
allow the FirewallRules in Example 5‐14 to remain valid.
This request, like all request bodies derived from a response, omits the Link elements and href attributes that were part of the response. It also omits the IsDeployed element of the NetworkConfig. These elements and
attributes are created by the server and are read‐only. They are ignored if you include them in a request.
Example 5-11. Modify vApp Network Configuration
Request:
PUT http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml...<NetworkConfigSection>
<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. 73
Chapter 5 Datacenter Operations
<DestinationIp>10.147.115.1</DestinationIp></FirewallRule><FirewallRule>
<IsEnabled>true</IsEnabled><Description>SSH Rule</Description><Policy>allow</Policy><Protocols>
<Tcp>true</Tcp></Protocols><Port>22</Port><DestinationIp>10.147.115.1</DestinationIp>
</FirewallRule></FirewallService><NatService>
<IsEnabled>true</IsEnabled><NatType>ipTranslation</NatType><Policy>allowTraffic</Policy><NatRule>
<OneToOneVmRule><MappingMode>manual</MappingMode><ExternalIp>64.100.10.1</ExternalIp><VAppScopedVmId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedVmId><VmNicId>0</VmNicId>
</OneToOneVmRule></NatRule>
</NatService></Features>
</Configuration></NetworkConfig>
</NetworkConfigSection>
Response:
202 AcceptedContent-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.
Reconfigure a Virtual Machine
Table 5‐2 summarizes virtual machine reconfiguration 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
vCloud API Programming Guide
74 VMware, Inc.
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.
Table 5-3. Summary of Virtual Machine Reconfiguration Requests
Operation Request Request Body Response
Retrieve the Network Connection of a Virtual Machine
GET API‐URL/vApp/vm‐id/networkConnectionSection/
None NetworkConnectionSection
Modify the Network Connection of a Virtual Machine
PUT API‐URL/vApp/vm‐id/networkConnectionSection/
NetworkConnectionSection Task
Retrieve the Guest Customization Section of a Virtual Machine
GET API‐URL/vApp/vm‐id/guestCustomizationSection/
None GuestCustomizationSection
Modify the Guest Customization Section of a Virtual Machine
PUT API‐URL/vApp/vm‐id/guestCustomizationSection/
GuestCustomizationSection Task
Retrieve the Operating System Section of a Virtual Machine
GET API‐URL/vApp/vm‐id/operatingSystemSection/
None OperatingSystemSection
Modify the Operating System Section of a Virtual Machine
PUT API‐URL/vApp/vm‐id/operatingSystemSection/
OperatingSystemSection Task
Retrieve the Virtual Hardware Section of a Virtual Machine
GET API‐URL/vApp/vm‐id/virtualHardwareSection/
None VirtualHardwareSection
Modify the Virtual Hardware Section of a Virtual Machine
PUT API‐URL/vApp/vm‐id/virtualHardwareSection/
VirtualHardwareSection Task
Retrieve the CPU Configuration of a Virtual Machine
GET API‐URL/vApp/vm‐id/virtualHardwareSection/cpu
None ovf:Item
Modify the CPU Configuration of a Virtual Machine
PUT API‐URL/vApp/vm‐id/virtualHardwareSection/cpu
ovf:Item Task
Retrieve the Memory Item from the Virtual Hardware Section of a Virtual Machine
GET API‐URL/vApp/vm‐id/virtualHardwareSection/memory
None ovf:Item
Modify the Memory Item of the Virtual Hardware Section of a Virtual Machine
PUT API‐URL/vApp/vm‐id/virtualHardwareSection/memory
ovf:Item Task
Retrieve Virtual Disk Items from the Virtual Hardware Section of a Virtual Machine
GET API‐URL/vApp/vm‐id/virtualHardwareSection/disks
None RasdItemsList
Modify Virtual Disk Items of the Virtual Hardware Section of a Virtual Machine
PUT API‐URL/vApp/vm‐id/virtualHardwareSection/disks
RasdItemsList Task
Retrieve Network Card Items from the Virtual Hardware Section of a Virtual Machine
GET API‐URL/vApp/vm‐id/virtualHardwareSection/networkCards
None RasdItemsList
Modify Network Card Items of the Virtual Hardware Section of a Virtual Machine
PUT API‐URL/vApp/vm‐id/virtualHardwareSection/networkCards
RasdItemsList Task
Retrieve Removable Media Drive Items from the Virtual Hardware Section of a Virtual Machine
GET API‐URL/vApp/vm‐id/virtualHardwareSection/media
None RasdItemsList
VMware, Inc. 75
Chapter 5 Datacenter Operations
Example 5‐12 shows a representative collection of these links. (This example does not show the configuration
links for the parent vApp. To see them, refer to Example 5‐9 on page 70.)
Example 5-12. Configuration Links for a Vm
Request:
GET http://vcloud.example.com/api/v1.0/vApp/vapp-7
Response:
200 OKContent-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>...<Children>
<Vm status="8" name="ubuntu10-x86" href="http://vcloud.example.com/api/v1.0/vApp/vm-4" ...>
<Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/reboot"/>
...<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><ovf:Item>
...<rasd:Description>SCSI Controller</rasd:Description><rasd:ResourceType>6</rasd:ResourceType>...
</ovf:Item><ovf:Item>
...<rasd:Description>Hard disk</rasd:Description><rasd:ElementName>Hard disk 1</rasd:ElementName><rasd:ResourceType>17</rasd:ResourceType>
...</ovf:Item>
vCloud API Programming Guide
76 VMware, Inc.
<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><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><GuestCustomizationSection
type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/guestCustomizationSection/" ovf:required="false">
<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-4/guestCustomizationSection/"/>
</GuestCustomizationSection><VAppScopedLocalId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedLocalId></Vm>
</Children></VApp>
VMware, Inc. 77
Chapter 5 Datacenter Operations
Reconfiguration links in the body of a Vm can appear in two places:
Individual Link elements in the ovf:Item elements defining cpu and memory. These links appear in the ovf:Item itself, and have type="application/vnd.vmware.vcloud.rasdItem+xml".
Links to groups of related ovf:Item elements (disks, network cards, and media devices). These links
appear at the end of the ovf:VirtualHardwareSection, and have type="application/vnd.vmware.vcloud.rasdItemsList+xml".
Retrieve or Modify the Network Connection of a Virtual Machine
Example 5‐13 retrieves the NetworkConnectionSection configuration of the Vm shown in Example 5‐12. Example 5‐14 modifies the section and uses the URL in the edit link from that section to apply the changes to the Vm.
Example 5-13. Retrieve the Network Connection of a Virtual Machine
Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/
Response:
200 OKContent-Type: application/vnd.vmware.vcloud.networkconnectionsection+xml...
<NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ...>
<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-4networkConnectionSection/"/>
</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 ...
href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ...><ovf:Info>Specifies the available VM network connections</ovf:Info><PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex><NetworkConnection network="vAppNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex><IpAddress>10.147.115.1</IpAddress><IsConnected>false</IsConnected><MACAddress>00:50:56:01:01:49</MACAddress><IpAddressAllocationMode>POOL</IpAddressAllocationMode>
</NetworkConnection></NetworkConnectionSection>
vCloud API Programming Guide
78 VMware, Inc.
Response:
202 AcceptedContent-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
Response:
200 OKContent-type: application/vnd.vmware.vcloud.rasdItem+xml...<Item xmlns="http://www.vmware.com/vcloud/v1"
xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData" ... >
<rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits><rasd:Description>Number of Virtual CPUs</rasd:Description><rasd:ElementName>1 virtual CPU(s)</rasd:ElementName><rasd:InstanceID>1</rasd:InstanceID><rasd:ResourceType>3</rasd:ResourceType><rasd:VirtualQuantity>1</rasd:VirtualQuantity>
</Item>
The modified Item in the request body adds a second CPU to the Vm by changing the rasd:VirtualQuantity value of the Item to 2.
Example 5-16. Modify the CPU Configuration of a Virtual Machine
Request:
PUT http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/cpuContent-type: application/vnd.vmware.vcloud.rasdItem+xml...<Item xmlns="http://www.vmware.com/vcloud/v1"
xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData">
<rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits><rasd:Description>Number of Virtual CPUs</rasd:Description><rasd:ElementName>1 virtual CPU(s)</rasd:ElementName><rasd:InstanceID>1</rasd:InstanceID><rasd:ResourceType>3</rasd:ResourceType><rasd:VirtualQuantity>2</rasd:VirtualQuantity>
</Item>
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...</Task>
VMware, Inc. 79
Chapter 5 Datacenter Operations
Retrieve or Modify the Guest Customization Section of a Virtual Machine
Example 5‐17 retrieves the GuestCustomizationSection of a Windows Vm. Example 5‐18 modifies the
section and uses the URL in the edit link from that section to apply the changes to the Vm.
Example 5-17. Retrieve the Guest Customization Section of a Virtual Machine
Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection
Response:
200 OKContent-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml...<GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml"
href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/" ovf:required="false">
<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/guestCustomizationSectionContent-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml...<GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml"
href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/" ovf:required="false">
<ovf:Info>Specifies Guest OS Customization Settings</ovf:Info><Enabled>false</Enabled><ChangeSid>false</ChangeSid><VirtualMachineId>4</VirtualMachineId><JoinDomainEnabled>true</JoinDomainEnabled><UseOrgSettings>false</UseOrgSettings><DomainName>EXAMPLE</DomainName><DomainUserName>admin</DomainUserName><DomainUserPassword>Pa55w0rd</DomainUserPassword><AdminPasswordEnabled>false</AdminPasswordEnabled><AdminPasswordAuto>true</AdminPasswordAuto><ResetPasswordRequired>false</ResetPasswordRequired><CustomizationScript/><ComputerName>ubuntu10-x86</ComputerName>
vCloud API Programming Guide
80 VMware, Inc.
<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 AcceptedContent-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
elements in a VirtualHardwareSection. This simplifies retrieval and modification of Item elements that are
typically viewed or modified as a group. To retrieve one of these elements, use the link where rel="down". To modify it, use the link where rel="edit".
Deploying and Controlling vApps and Virtual MachinesA vApp or Vm body returned in response to a GET, PUT, or POST request includes a number of action links,
which have the form vApp‐or‐Vm‐URL/action/action‐name. A client can use action links to request various
actions on the vApp. Only those action links that are valid for the vApp or virtual machine in its current state
are returned. For example, if a vApp is instantiated but not deployed, only the links for deploy and remove are returned. For a vApp that is powered on, links for all actions except powerOn are returned (see Example 2‐8
on page 27).
Some of the requests documented in this section apply only to vApps, others apply only to virtual machines
(Vm objects), and others apply to both.
A request made to a vApp URL invokes the requested operation on each of the virtual machines in the
Children element of the vApp, in the order specified in its ovf:StartupSection element. This element,
if present, specifies a start order and related properties for each member of a VirtualSystemCollection (each Vm in the Children collection). If the element is not present, all members are started up at the same
time. The same logic applies to shutdown, reboot, and similar operations. For more information, see the
OVF specification, available at
http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf.
A request made to a Vm URL affects only that virtual machine.
Deploy a vApp or Virtual Machine
To deploy a vApp, the client makes a request to its action/deploy URL. Deploying a vApp automatically
deploys all of the virtual machines it contains.
To deploy a virtual machine, the client makes a request to its action/deploy URL. Deploying a Vm implicitly
deploys the parent vApp if that vApp is not already deployed.
The request body in each case is a DeployVAppParams element.
NOTE You cannot include a GuestCustomizationSection in the InstantiationParams passed to a Vm during instantiation, composition, or recomposition. To change this section, you must retrieve it from a Vm and update it.
NOTE Media devices are read‐only, so they have no rel="edit" link. For more information, see “List Media
Devices of a Virtual Machine” on page 85.
VMware, Inc. 81
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/deployContent-type: application/vnd.vmware.vcloud.deployVAppParams+xml...<DeployVAppParams powerOn="true" xmlns="http://www.vmware.com/vcloud/v1"/>
Response:
202 AcceptedContent-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
resources reserved for the vApp and sets the vApp’s deployed attribute to a value of false to indicate that it is not deployed.
Undeploying a virtual machine powers off or suspends the virtual machine, then frees the resources reserved
for it and sets the its deployed attribute to a value of false to indicate that it is not deployed. This operation has no effect on the containing vApp.
The saveState attribute specifies whether the undeployed virtual machines are suspended and their suspend
state saved, or simply powered off.
The request body in each case is an UndeployVAppParams element.
Example 5-20. Undeploy a vApp or Virtual Machine
Request to undeploy a vApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/undeployContent-type: application/vnd.vmware.vcloud.undeployVAppParams+xml...<UndeployVAppParams saveState="true" xmlns="http://www.vmware.com/vcloud/v1"/>
Request to undeploy a Vm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/action/undeployContent-type: application/vnd.vmware.vcloud.undeployVAppParams+xml...<UndeployVAppParams saveState="true" xmlns="http://www.vmware.com/vcloud/v1"/>
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ...>
...</Task>
Power On a vApp or Virtual Machine
A powerOn request to a vApp URL powers on all of the virtual machines in the vApp, as specified in the vApp’s
ovf:StartupSection element.
A powerOn request to a virtual machine URL powers on the specified virtual machine and forces deployment
of the parent vApp.
vCloud API Programming Guide
82 VMware, Inc.
A powerOn request to a vApp or virtual machine that is undeployed forces deployment.
Example 5-21. Power On a vApp or Virtual Machine
Request to power on a vApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOn
Request to power on a virtual machine:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOn
Response:
202 AcceptedContent-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.
Example 5-22. Power Off a vApp or Virtual Machine
Request to power off a vApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOff
Request to power off a virtual machine:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOff
Response:
202 Accepted...Content-Type: application/vnd.vmware.vcloud.task+xml<Task ...>
...</Task>
Reset a vApp or Virtual Machine
A reset request to a vApp URL resets all of the virtual machines in the vApp, as specified in its
ovf:StartupSection element.
A reset request to a virtual machine URL resets the specified virtual machine.
Example 5-23. Reset a vApp or Virtual Machine
Request to reset a vApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reset
Request to reset a Vm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/reset
VMware, Inc. 83
Chapter 5 Datacenter Operations
Response:
202 AcceptedContent-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 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ...>
...</Task>
Discard the Suspended State of a vApp or Virtual Machine
A discardSuspendedState request to a vApp URL discards the suspended state of all of the virtual machines
in the vApp, as specified in its ovf:StartupSection element.
A discardSuspendedState request to a virtual machine URL discards the suspended state of the specified
virtual machine.
You cannot resume a suspended vApp after its suspended state has been discarded.
Example 5-25. Discard the Suspended State of a vApp or Virtual Machine
Request to discard the suspended state of a vApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/discardSuspendedState
Request to discard the suspended state of a Vm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/action/discardSuspendedState
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ...>
...</Task>
vCloud API Programming Guide
84 VMware, Inc.
Shut Down a vApp or Virtual Machine
A shutdown request to a vApp URL shuts down all of the virtual machines in the vApp, as specified in its
ovf:StartupSection element.
A shutdown request to a virtual machine URL shuts down the specified virtual machine.
Example 5-26. Shut Down a vApp or Virtual Machine
Request to shut down a vApp:
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.
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
NOTE Because this request sends a signal to the guest OS, the vCloud API cannot track the progress or verify
the result of the requested operation.
NOTE Because this request sends a signal to the guest OS, the vCloud API cannot track the progress or verify
the result of the requested operation.
VMware, Inc. 85
Chapter 5 Datacenter Operations
List Media Devices of a Virtual Machine
You can make a GET request to the media URL of a Vm to return a list of all media devices attached to it.
Example 5-28. List Media Devices Attached to a Vm
Request:
GET http://vcloud.example.com/api/v1.0/vapp/vm-5/virtualHardwareSection/media
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.rasditemslist+xml...<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> </Item> <Item> <rasd:AddressOnParent>0</rasd:AddressOnParent> <rasd:Description>CD/DVD Drive</rasd:Description> <rasd:ElementName>CD/DVD Drive 1</rasd:ElementName> <rasd:HostResource xmlns:vcloud="http://www.vmware.com/vcloud/v1"
vcloud:connected="false"></rasd:HostResource> <rasd:InstanceID>3000</rasd:InstanceID> <rasd:Parent>1</rasd:Parent> <rasd:ResourceType>15</rasd:ResourceType> </Item> <Item> <rasd:AddressOnParent>0</rasd:AddressOnParent> <rasd:Description>Floppy Drive</rasd:Description> <rasd:ElementName>Floppy Drive 1</rasd:ElementName> <rasd:HostResource xmlns:vcloud="http://www.vmware.com/vcloud/v1"
vcloud:connected="false"></rasd:HostResource> <rasd:InstanceID>8000</rasd:InstanceID> <rasd:ResourceType>14</rasd:ResourceType> </Item></RasdItemsList>
Insert Media Into a Virtual Machine
An insertMedia request makes a virtual media image readable by a Vm. The request must specify the
insertMedia URL of a Vm. The Media element in the request body must specify the href of the media image
to insert. When processing an insertMedia request, the server examines the type of the media specified in the
request and then attempts to insert it in a device of the appropriate type, starting with the device that has the
lowest bus number and lowest address on that bus.
Example 5-29. Insert Media Into a Virtual Machine
Request:
POST http://vcloud.example.com/api/v1.0/vapp/vm-5/media/action/insertMediaContent-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"/></MediaInsertOrEjectParams>
vCloud API Programming Guide
86 VMware, Inc.
Response:
202 AcceptedContent-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/ejectMediaContent-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"/></MediaInsertOrEjectParams>
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ...>
...</Task>
Get a Screen Thumbnail for a Virtual Machine
A screen request returns a thumbnail view of a virtual machine’s console encoded in png format.
Example 5-31. Get a Screen Thumbnail for a Virtual Machine
Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-4/screen
Response:
200 OKContent-type image/png...
...serialized contents of thumbnail in png format...
EOF
VMware, Inc. 87
Chapter 5 Datacenter Operations
Get a Screen Ticket for a Virtual Machine
An acquireTicket request returns a ticket that a client can use to gain access to the console of a virtual machine.
Example 5-32. Get a Screen Ticket for a Virtual Machine
Request:
POST http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/action/acquireTicket
Response:
200 OKContent-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%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O
</ScreenTicket>
Provide User Input Requested by a Virtual Machine
A request for a virtual machine to change state (power on, suspend, reconfigure, and so on) might cause the
virtual machine to ask for additional user input before it can complete. A vApp that contains a Vm awaiting a
user response has status="5", and includes a link with rel="down" and type="application/vnd.vmware.vcloud.vmPendingQuestion+xml" that a client can GET to discover what input is needed. In this series of examples, a virtual machine that was recently reconfigured in vCenter
to add a new parallel port device and then powered on is requesting user input about where to send output
from the device. The powerOn request cannot complete until this input is supplied.
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 OKContent-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>
vCloud API Programming Guide
88 VMware, Inc.
Get a Request for User Input
In Example 5‐34, the client uses the vmPendingQuestion link returned in Example 5‐33 to get a
VmPendingQuestion document that includes the question and the set of choices allowed in the response.
Example 5-34. Get a Vm Pending Question
Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-5/question
Response:
200 OKContent-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><QuestionId>50</QuestionId><Choices>
<Id>0</Id><Text>Append</Text>
</Choices><Choices>
<Id>1</Id><Text>Replace</Text>
</Choices><Choices>
<Id>2</Id><Text>Cancel</Text>
</Choices></VmPendingQuestion>
Provide Requested User Input
Example 5‐35 shows the a response, delivered by a POST to the question/answer link of the Vm.
Example 5-35. Answer a Vm Pending Question
Request:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/question/action/answerContent-type: application/vnd.vmware.vcloud.vmPendingAnswer+xml ...<VmQuestionAnswer xmlns="http://www.vmware.com/vcloud/v1">
<ChoiceId>2</ChoiceId><QuestionId>50</QuestionId>
</VmQuestionAnswer>
Response:
204 No Content
VMware, Inc. 89
Chapter 5 Datacenter Operations
Control Access to vAppsAccess control links for vApps are included in the vApp body. Example 5‐36, an excerpt from Example 2‐8 on
page 27, shows these links.
Example 5-36. Access Control Links for a vApp
<vApp ... >...<Link rel="down" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/controlAccess/"/><Link rel="controlAccess"
href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/controlAccess/"/>...
</vApp>
An organization administrator can use these links in the same kinds of requests shown in “Control Access to
Catalogs” on page 56.
Retrieve a TaskWhenever the result of a request cannot be returned immediately, the server creates a Task object and includes it in the response, as a member of the Tasks container in the response body. Each Task has an href value, which is a URL that the client can use to retrieve the Task element alone, without the rest of the response in
which it was contained. All information about the task is included in the Task element when it is returned in
the response’s Tasks container, so a client does not need to make an additional request to the Task URL unless it wants to follow the progress of a task that was incomplete.
Example 5‐37 retrieves that task that was returned in the response in Example 2‐6 on page 25.
Example 5-37. Retrieve a Task
Request:
GET http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey
Response:
200 OKContent-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.
vCloud API Programming Guide
90 VMware, Inc.
VMware, Inc. 91
6
The VMware vCloud API supports a variety of objects and operations that an organization administrator or
other privileged user can use to automate tasks associated with provisioning organizations and users, and
with allocation of resources to organization vDCs.
This chapter includes the following topics:
“Summary of Administrative Requests” on page 91
“Administrator Credentials and Privileges” on page 93
“Administrative Objects and URLs” on page 93
“Get an Administrative View of a Cloud” on page 93
“Organization Administration” on page 94
“Network Administration” on page 99
“vDC Administration” on page 102
“Catalog Administration” on page 107
“User Administration” on page 110
“Group Administration” on page 113
“Role Administration” on page 114
Summary of Administrative RequestsTable 6‐1 summarizes administrative 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
Administrative Operations 6
Table 6-1. Summary of Administrative Requests
Operation Request Request Body Response
Get an Administrative View of a Cloud
GET API‐URL/admin None VCloud
Create an Organization POST API‐URL/admin/orgs AdminOrg AdminOrg
Get an Administrative View of an Organization
GET API‐URL/admin/org/id None AdminOrg
Modify an Organization PUT API‐URL/admin/org/id AdminOrg AdminOrg
List All Tasks Owned by an Organization
GET API‐URL/tasksList/id None TasksList
vCloud API Programming Guide
92 VMware, Inc.
Add a Network to an Organization POST API‐URL/admin/org/id/networks OrgNetwork OrgNetwork
Get an Administrative View of an Organization Network
GET API‐URL/admin/network/id None OrgNetwork
Modify an Organization Network PUT API‐URL/admin/network/id OrgNetwork Task
Remove an Organization Network DELETE API‐URL/admin/network/id None Task
Enable or Disable an Organization POST API‐URL/admin/org/id/action/enablePOST API‐URL/admin/org/id/action/disable
None 204 No Content
Remove an Organization DELETE API‐URL/admin/org/id None None
Examine the Contents of a Provider vDC
GET API‐URL/admin/providervdc/id None ProviderVdc
Allocate a vDC to an Organization POST API‐URL/admin/org/id/vdcs AdminVdc AdminVdc
List the Organization vDCs Supported by a Provider vDC
GET API‐URL/admin/providervdc/id/vdcReferences
None VdcReferences
Get an Administrative View of a vDC GET API‐URL/admin/vdc/id None AdminVdc
Modify a vDC PUT API‐URL/admin/vdc/id AdminVdc AdminVdc
Enable or Disable a vDC POST API‐URL/admin/vdc/id/action/enablePOST API‐URL/admin/vdc/id/action/disable
None 204 No Content
Remove a vDC DELETE API‐URL/admin/vdc/id None Task
Create a Catalog POST API‐URL/admin/org/id/catalogs Catalog Catalog
Get an Administrative View of a Catalog
GET API‐URL/admin/catalog/id None Catalog
Publish a Catalog POST API‐URL/admin/catalog/id/action/publish
PublishCatalogParams 204 No Content
Modify Catalog Metadata PUT API‐URL/admin/catalog/id Catalog Catalog
Remove a Catalog DELETE API‐URL/admin/catalog/id None 204 No Content
Create or Import a User POST API‐URL/admin/org/id/users User User
Get an Administrative View of a User GET API‐URL/admin/user/id None User
Modify User Metadata PUT API‐URL/admin/user/id User User
Remove a User DELETE API‐URL/admin/user/id 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
Table 6-1. Summary of Administrative Requests (Continued)
Operation Request Request Body Response
VMware, Inc. 93
Chapter 6 Administrative Operations
Administrator Credentials and PrivilegesThe vCloud API defines two levels of administrative privilege:
Organization administrators, who have administrative privileges in a specific organization.
System administrators, who have superuser privileges throughout the system. System administrators can
create, read, update, and delete all objects in a vCloud, and have organization administrator rights in all
organizations in a vCloud, and can operate directly on vSphere resources to create and modify provider
vDCs.
Some administrative operations (and 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 vCloud Service Director was
installed. For example, if the system administrator’s name and password had been defined as administrator and Pa55w0rd, the system administrator login credentials would be the MIME Base64 encoding of the string
administrator@System:Pa55w0rd.
The System organization is created automatically when vCloud Service Director is installed, and always has a
URL of the form API‐URL/org/1. It is not listed in an OrgList, but can be retrieved with an explicit GET
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 OKContent-Type: application/vnd.vmware.vcloud.org+xml
...<Org xmlns="http://www.vmware.com/vcloud/v1" name="System" ...>...
</Org>
Administrative Objects and URLsThe 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 CloudAn administrator can access a cloud‐wide namespace of administrative objects at API‐URL/admin, where
API‐URL is a URL of the form http://vcloud.example.com/api/v1.0. The primary administrative objects in a
vCloud include organizations, provider vDCs, rights, roles, and external networks. Each object type is
represented in a VCloud element by zero or more references, as illustrated in Example 6‐2. A system
administrator can obtain more information about any of these objects by making a GET request to the object
reference (the value of its href attribute).
The vCloud response document includes links that enable a system administrator to add roles and
organizations. Subordinate objects such as users, catalogs, and vDCs, are contained by individual
organizations and are not listed at this level. Other objects, such as rights, can be listed but cannot be modified
using the vCloud API.
vCloud API Programming Guide
94 VMware, Inc.
Example 6-2. List the Top-Level Administrative Objects in a vCloud
Request:
GET http://vcloud.example.com/api/v1.0/admin
Response:
200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml...<VCloud name="vCloud" href="http://vcloud.example.com/api/v1.0/admin" ...>
<Link rel="add" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/roles"/>
<Link rel="add" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/orgs"/>
<Description>Example Corporation’s vCloud</Description><OrganizationReferences>
<OrganizationReference type="application/vnd.vmware.admin.organization+xml" name="Engineering" href="http://vcloud.example.com/api/v1.0/admin/org/44"/>
<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 ... />...
</RoleReferences><Networks>
<Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/>
<Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC2" href="http://vcloud.example.com/api/v1.0/admin/network/33"/>
<Network ... />...
</Networks></VCloud>
Organization AdministrationAn AdminOrg is an extended representation of an Org object, and is accessed at API‐URL/admin/org/id, rather than API‐URL/org/id. Although system administrators work with AdminOrg elements to create and
modify organizations, most modifications to an AdminOrg also modify some user‐visible property of the
corresponding Org.
VMware, Inc. 95
Chapter 6 Administrative Operations
Create an Organization
To create an organization, a system administrator POSTs an AdminOrg body to the vCloud’s orgs URL, as shown in Example 6‐3.
The response echoes the request, with several important additions:
It includes both the administrative and user URLs for the new organization. The administrative URL is
the value of the href element of the AdminOrg body, and the user URL is the value of the Link where
rel="alternate".
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/orgsContent-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><StoredVmQuota>0</StoredVmQuota><OrgLeaseSettings>
<DeleteOnStorageLeaseExpiration>false</DeleteOnStorageLeaseExpiration><DeploymentLeaseSeconds>604800</DeploymentLeaseSeconds><StorageLeaseSeconds>2592000</StorageLeaseSeconds>
</OrgLeaseSettings><OrgLdapMode>SYSTEM</OrgLdapMode><OrgEmailSettings>
<IsDefaultSmtpServer>true</IsDefaultSmtpServer><IsDefaultOrgEmail>true</IsDefaultOrgEmail><FromEmailAddress>[email protected]</FromEmailAddress><DefaultSubjectPrefix>Attention</DefaultSubjectPrefix><IsAlertEmailToAllAdmins>true</IsAlertEmailToAllAdmins><SmtpServerSettings>
<IsUseAuthentication>true</IsUseAuthentication><Host>smtp.example.com</Host><Username>[email protected]</Username>
</SmtpServerSettings></OrgEmailSettings>
</Settings></AdminOrg>
Response:
201 CreatedContent-Type: application/vnd.vmware.admin.organization+xml...<AdminOrg xmlns="http://www.vmware.com/vcloud/v1"
href="http://vcloud.example.com/api/v1.0/admin/org/26" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml">
<Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/26"/>
<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"/>
<Link rel="add" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/groups"/>
vCloud API Programming Guide
96 VMware, Inc.
<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>
</OrgLeaseSettings><OrgLdapMode>SYSTEM</OrgLdapMode><OrgEmailSettings>
<IsDefaultSmtpServer>true</IsDefaultSmtpServer><IsDefaultOrgEmail>true</IsDefaultOrgEmail><FromEmailAddress>[email protected]</FromEmailAddress><DefaultSubjectPrefix>Attention</DefaultSubjectPrefix><IsAlertEmailToAllAdmins>true</IsAlertEmailToAllAdmins><SmtpServerSettings>
<IsUseAuthentication>true</IsUseAuthentication><Host>smtp.example.com</Host><Username>[email protected]</Username>
</SmtpServerSettings></OrgEmailSettings>
</Settings></AdminOrg>
Get an Administrative View of an Organization
To see an administrative view of an organization, an administrator can make a GET request to the
organization’s admin URL (the href element of the AdminOrg body), as shown in Example 6‐4. With the
exception of the HTTP response code (200 OK instead of 201 Created), the response to this request is identical
to the one returned in Example 6‐3, so we omit most of it from the example.
Example 6-4. Get an Administrative View of an Organization
Request:
GET http://vcloud.example.com/api/v1.0/admin/org/26
Response:
200 OKContent-Type:application/vnd.vmware.admin.organization+xml...<AdminOrg xmlns="http://www.vmware.com/vcloud/v1"
href="http://vcloud.example.com/api/v1.0/admin/org/26" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml">
<Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/26"/>
<Description>Example Corporation’s Finance Organization</Description>
VMware, Inc. 97
Chapter 6 Administrative Operations
<FullName>Finance</FullName>...<Settings>
...</Settings>
</AdminOrg>
List All Tasks Owned by an Organization
An administrative view of an organization includes a Link with a rel="down" attribute that the administrator
can use to retrieve a list of all tasks owned by a user or object in an organization. The request in Example 6‐5
uses the tasksList URL returned in Example 6‐4 to return a TasksList element that contains several Task elements.
Example 6-5. List All Tasks Owned by an Organization
Request:
GET http://vcloud.example.com/api/v1.0/tasksList/26
Response:
200 OKContent-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. Current state of the the VM is VMOn.at com.vmware.vcloud.val.internal.impl.VC20VirtualServer.throwVimInvalidStateException(VC20VirtualServer.java:292)at ...">
...</Task><Task... status="running" ... operation="Deleting Virtual Application (44)" ... >
...</Task>...
</TasksList>
Modify an Organization
As shown in Example 6‐3, an AdminOrg body includes rel="add" links for networks, vDCs, users, groups,
and catalogs. An organization administrator can use these links to add objects of those types to the
organization. To modify other attributes or elements of an AdminOrg, an organization administrator can make
a PUT request to its rel="edit" link and supply a modified version of the AdminOrg body. The request in Example 6‐6 modifies the default lease settings of the organization created in Example 6‐3.
NOTE If you modify an organization’s catalog publishing policy or LDAP options or modify a role, the
changes do not take effect for logged‐in users until the cache for the current session expires or the user logs
out and logs in again.
vCloud API Programming Guide
98 VMware, Inc.
Example 6-6. Modify an Organization
Request:
PUT http://vcloud.example.com/api/v1.0/admin/org/26Content-Type: application/vnd.vmware.admin.organization+xml...<AdminOrg xmlns="http://www.vmware.com/vcloud/v1" name="ExampleFinance">
<Description>Example Corporation’s Finance Organization</Description><FullName>Finance</FullName><Settings>
<OrgLeaseSettings><DeleteOnStorageLeaseExpiration>true</DeleteOnStorageLeaseExpiration><DeploymentLeaseSeconds>1209600</DeploymentLeaseSeconds><StorageLeaseSeconds>7776000</StorageLeaseSeconds>
</OrgLeaseSettings><OrgLdapMode>SYSTEM</OrgLdapMode>
</Settings></AdminOrg>
Response:
200 OKContent-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 organization, as shown in Example 6‐7. The enablement state of the AdminOrg is shown in its IsEnabled element.
Example 6-7. Disable an Organization
Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/action/disable
Response:
204 No Content
VMware, Inc. 99
Chapter 6 Administrative Operations
Remove an Organization
An organization administrator can use the remove link in an AdminOrg body to remove the organization from
the vCloud. Example 6‐8 does this, making a DELETE request to the remove link returned in Example 6‐4.
Example 6-8. Remove an Organization
Request:
DELETE http://vcloud.example.com/api/v1.0/admin/org/26
Response:
204 No Content
Network AdministrationA newly created organization has no networks in it. An organization administrator must create an
organization network from resources provided by one of the external networks listed in the Networks element
of the VCloud response (see Example 6‐2 on page 94).
View the Properties of an External Network
To create an organization network, and organization administrator must choose a parent network from one of
the networks grouped in the Networks element of the cloud. To get more information about any of these
networks, an administrator can make a GET request to the network’s URL (the href element of the Network element). Example 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 OKContent-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>
NOTE Before you can remove an organization, you must disable it and delete or change ownership of all
objects that the organization users own.
vCloud API Programming Guide
100 VMware, Inc.
Add a Network to an Organization
An administrator can use the rel="add" link for networks in an AdminOrg body to add a network to the
organization. Example 6‐10 does this by making a POST request to the networks link returned in Example 6‐4.
The content of the FenceMode element in the request body specifies that organization network is bridged to
its ParentNetwork, whose href value was retrieved from one of the Network elements in the response in
Example 6‐2.
Example 6-10. Add a Network to an Organization
Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/networksContent-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 CreatedContent-Type: application/vnd.vmware.admin.network+xm...<OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet"
type="application/vnd.vmware.admin.network+xml" href="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"/><Description>Bridged to the public Internet</Description><Tasks>
<Task ... operation="Creating Network Internet (2)" ... >...
</Task></Tasks><Configuration>
<IpScope><IsInherited>true</IsInherited><Gateway>10.147.122.190</Gateway><Netmask>255.255.255.192</Netmask><Dns1>10.115.120.71</Dns1><DnsSuffix>example.com</DnsSuffix><IpRanges>
<IpRange><StartAddress>10.147.122.129</StartAddress><EndAddress>10.147.122.189</EndAddress>
</IpRange></IpRanges><AllocatedIpAddresses/>
</IpScope>
NOTE A NetworkPool element must be included in the request when creating network whose FenceMode is natRouted or isolated.
VMware, Inc. 101
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
Response:
200 OKContent-Type: application/vnd.vmware.admin.network+xm...<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" ...>
...<Description>Bridged to the public Internet</Description>...
</OrgNetwork>
Modify an Organization Network
An administrator can use the rel="edit" link in an OrgNetwork body to modify the network’s name,
description, or configuration. Example 6‐12 does this by making a PUT request to the rel="edit" link returned in Example 6‐10. The request modifies the network’s FenceMode element and adds elements to the
Configuration to define the NAT service being added to the network.
Example 6-12. Modify a Network
Request:
PUT http://vcloud.example.com/api/v1.0/admin/network/54Content-Type: application/vnd.vmware.admin.network+xml...<OrgNetwork name="Internet" xmlns="http://www.vmware.com/vcloud/v1">
<Description>NAT-ed 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>natRouted</FenceMode>
<Features><DhcpService>
vCloud API Programming Guide
102 VMware, Inc.
<IsEnabled>false</IsEnabled><DefaultLeaseTime>3600</DefaultLeaseTime><MaxLeaseTime>7200</MaxLeaseTime><IpRange>
<StartAddress>10.6.35.3</StartAddress><EndAddress>10.6.255.254</EndAddress>
</IpRange></DhcpService><FirewallService>
<IsEnabled>true</IsEnabled></FirewallService><NatService>
<IsEnabled>false</IsEnabled><NatType>portForwarding</NatType><Policy>allowTraffic</Policy>
</NatService></Features>
</Configuration></OrgNetwork>
Response:
202 AcceptedContent-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
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Removing Network Internet (2)" ...>
...</Task>
vDC AdministrationA newly created organization has no vDCs in it. vDC administration involves the following objects:
A ProviderVdc, which a system administrator creates from vSphere platform resources (see “Create a
Provider vDC” on page 127).
An AdminVdc, which a system administrator creates to allocate a subset of ProviderVdc resources to a vDC in a specific organization. Organization members see an AdminVdc as a vDC.
VMware, Inc. 103
Chapter 6 Administrative Operations
Examine the Contents of a Provider vDC
ProviderVdc objects are listed among the top‐level objects in a vCloud. in Example 6‐2 on page 94 illustrates
such a listing, which includes a ProviderVdcReferences element that contains references to the provider
vDCs registered to this vCloud.
<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>
An administrator can use the value of the href attribute in any ProviderVdcReference as the target of a GET request. The response is a ProviderVdc body, as shown in Example 6‐14.
Example 6-14. Examine the Contents of a Provider vDC
Request:
GET http://vcloud.example.com/api/v1.0/admin/providervdc/2
Response:
200 OKContent-Type: application/vnd.vmware.admin.providervdc+xml...<ProviderVdc xmlns="http://www.vmware.com/vcloud/v1" status="1" name="PVDC_VC2"
type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2" ... >
<Link rel="up" href="http://vcloud.example.com/api/v1.0/admin/"/><Link rel="down" type="application/vnd.vmware.admin.vdcReferences+xml"
href="http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences"/><Description>PVDC_VC2</Description><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"/>
vCloud API Programming Guide
104 VMware, Inc.
<NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="VC2_VLAN_Backed" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/2"/>
</NetworkPoolReferences></ProviderVdc>
List the Organization vDCs Supported by a Provider vDC
An administrator can use the href value from any ProviderVdcReference element in a VCloud as the target of a request that returns a list of organization vDCs that the provider vDC supports.
Example 6‐15 shows a request of this type, made using the href of the provider vDC shown in Example 6‐2
on page 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:
<Link rel="add" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/vdcs"/>
Example 6‐16 uses that URL to add a new vDC to the organization. The new vDC allocates resources from the
provider vDC specified in the ProviderVdcReference element in the request body. The contents of that
element were obtained from this element, shown in the response in Example 6‐2.
<ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="MainProvider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/>
<ProviderVdcReference ... />
Example 6-16. Allocate a vDC to an Organization
Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/vdcsContent-Type: application/vnd.vmware.admin.vdc+xml...<AdminVdc name="org26vdc1" xmlns="http://www.vmware.com/vcloud/v1">
<Description>Example vDC</Description><AllocationModel>AllocationPool</AllocationModel><StorageCapacity>
<Units>MB</Units><Allocated>3072</Allocated><Limit>4096</Limit>
</StorageCapacity><ComputeCapacity>
<Cpu>
VMware, Inc. 105
Chapter 6 Administrative Operations
<Units>MHz</Units><Allocated>2048</Allocated><Limit>2048</Limit>
</Cpu><Memory>
<Units>MB</Units><Allocated>2048</Allocated><Limit>2048</Limit>
</Memory></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 CreatedContent-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)" ...>... </Task>
</Tasks><AllocationModel>AllocationPool</AllocationModel><StorageCapacity>
<Units>MB</Units><Allocated>3072</Allocated><Limit>4096</Limit>
</StorageCapacity><ComputeCapacity>
<Cpu><Units>MHz</Units><Allocated>2048</Allocated><Limit>2048</Limit>
</Cpu><Memory>
<Units>MB</Units><Allocated>2048</Allocated><Limit>2048</Limit>
</Memory></ComputeCapacity><ResourceEntities/><AvailableNetworks>
<Network type="application/vnd.vmware.admin.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/admin/network/54"/>
</AvailableNetworks><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>
vCloud API Programming Guide
106 VMware, Inc.
The response echoes the request, and includes a Task element that tracks creation of the vDC. The network
created in Example 6‐10 appears in the AvailableNetworks element. If you added more networks to the
organization that contains this vDC, they would also appear in that element.
Get an Administrative View of a vDC
References to an organization’s vDCs are contained in the Vdcs element of the Org or AdminOrg body. To get an administrative view of a vDC, an administrator can make a GET request to its admin URL. The request returns an AdminVdc body, similar to the one shown in the response section of Example 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/44Content-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><Memory>
<Units>MB</Units><Allocated>2048</Allocated><Limit>4096</Limit>
</Memory></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:
200 OKContent-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" ...>...<Tasks>
<Task status="running" ... operation="Updating Virtual Datacenter (44)"...>... </Task>
</Tasks>
VMware, Inc. 107
Chapter 6 Administrative Operations
<ComputeCapacity><Cpu>
<Units>MHz</Units><Allocated>4096</Allocated><Limit>4096</Limit>
</Cpu>...
</ComputeCapacity>...
</AdminVdc>
Enable or Disable a vDC
An administrator can use the enable or disable action links in an AdminVdc body to enable or disable a vDC. The request and response are similar to those shown in Example 6‐7 on page 98. The enablement state of the
vDC is shown in its IsEnabled element.
Remove a vDC
Before you can remove a vDC, you must disable it. After the vDC has been disabled, its representation includes
a rel="remove" link. An administrator can make a DELETE request to that link to remove a vDC from an
organization.
Example 6-18. Remove a vDC
Request:
DELETE http://vcloud.example.com/api/v1.0/admin/vdc/6
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Deleted Virtual Datacenter (6)" ...>
...</Task>
Catalog AdministrationA 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
vCloud API Programming Guide
108 VMware, Inc.
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/catalogsContent-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 CreatedContent-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 ...>...
<Task><Tasks><Link rel="up" type="application/vnd.vmware.admin.organization+xml"
href="http://vcloud.example.com/api/v1.0/admin/org/26"/><Link rel="alternate" href="http://vcloud.example.com/api/v1.0/catalog/32"/><Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml"
href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/><Link rel="edit" type="application/vnd.vmware.vcloud.catalog+xml"
href="http://vcloud.example.com/api/v1.0/catalog/32"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalog/32"/><Link rel="publish" href="http://vcloud.example.com/api/v1.0/catalog/32/action/publish"/><CatalogItems/><IsPublished>false</IsPublished>
</Catalog>
Get an Administrative View of a Catalog
An administrative view of a catalog is nearly identical to a user view but contains additional action links that
support administrative operations such as edit and remove. To see an administrative view of a catalog, an
administrator can make a GET request to its admin URL, as shown in Example 6‐20. For a user view of the
same catalog, see Example 3‐2 on page 35.
Example 6-20. Get an Administrative View of a Catalog
Request:
GET http://vcloud.example.com/api/v1.0/admin/catalog/32
Response:
200 OKContent-Type: application/vnd.vmware.admin.catalog+xml...<Catalog .... >
...<Link rel="edit" href="http://vcloud.example.com/api/v1.0/admin/catalog/32"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/catalog/32"/>
VMware, Inc. 109
Chapter 6 Administrative Operations
<Description>Custom Catalog</Description><CatalogItems>
...</CatalogItems>...
</Catalog>
Publish a Catalog
Publishing a catalog makes the catalog visible to all organizations in a vCloud. An administrator of an
organization that can publish catalogs (one whose CanPublishCatalogs element has a value of true) can publish a catalog by making a POST request to the catalog’s publish URL and supplying a PublishCatalogParams body that sets the value of the catalog’s IsPublished element to true. Example 6‐21
publishes the catalog created in Example 6‐19.
Example 6-21. Publish a Catalog
Request:
POST http://vcloud.example.com/api/v1.0/admin/catalog/32/action/publishContent-Type: application/vnd.vmware.admin.publishCatalogParams+xml...<PublishCatalogParams xmlns="http://www.vmware.com/vcloud/v1">
<IsPublished>true</IsPublished></PublishCatalogParams>
Response:
204 No Content
Modify Catalog Metadata
An administrator can modify catalog metadata such as its name and description by creating a modified
Catalog body and PUTting it to the catalog’s edit link. The request in Example 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/32Content-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 OKContent-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"
href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/>
vCloud API Programming Guide
110 VMware, Inc.
<CatalogItems><CatalogItem name="Ubuntu Template with vsftpd"
type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221">
<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></CatalogItems>
</Catalog>
Remove a Catalog
An administrator can remove a catalog by making a DELETE request to the catalog’s rel="remove" URL. Example 6‐23 removes the catalog created in Example 6‐19.
Example 6-23. Remove a Catalog
Request:
DELETE http://vcloud.example.com/api/v1.0/admin/catalog/32
Response:
204 No Content
User AdministrationUsers 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/usersContent-Type: application/vnd.vmware.admin.user+xml<User name="ExampleUser" xmlns="http://www.vmware.com/vcloud/v1">
<FullName>Example User Full Name</FullName><EmailAddress>[email protected]</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>
NOTE Modifying catalog metadata does not affect CatalogItem elements. You cannot create a catalog that
has CatalogItem elements in it. They must be added in a separate operation. For information about adding
and removing these elements, see “Cataloging vApp Templates and Media Images” on page 54.
VMware, Inc. 111
Chapter 6 Administrative Operations
Response:
201 CreatedContent-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>[email protected]</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.
Example 6-25. Import a User from LDAP
Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/usersContent-Type: application/vnd.vmware.admin.user+xml...<User name="[email protected]" type="application/vnd.vmware.admin.user+xml"
xmlns="http://www.vmware.com/vcloud/v1"><IsExternal>true</IsExternal><Role type="application/vnd.vmware.admin.role+xml"
href="http://vcloud.example.com/api/v1.0/admin/role/105"/></User>
Response:
201 CreatedContent-Type: application/vnd.vmware.admin.user+xml...<User name="[email protected]" 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</FullName><EmailAddress>[email protected]</EmailAddress><IsEnabled>false</IsEnabled><IM/><NameInSource>\F4\D3\42\8E\6A\BC\D3</NameInSource><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>
vCloud API Programming Guide
112 VMware, Inc.
FullName and EmailAddress are retrieved from LDAP. Values for IsEnabled, Description, and other elements can be specified in the request body or add later. See “Modify User Metadata” on page 112.
Get an Administrative View of a User
Each user in an organization is represented by a UserReference element. A GET request to the URL in the
href attribute of a UserReference returns a User element in the response, as shown in Example 6‐26.
Example 6-26. Get an Administrative View of a User
Request:
GET http://vcloud.example.com/api/v1.0/admin/user/85
Response:
200 OKContent-Type: application/vnd.vmware.admin.user+xml...<User name="[email protected]" 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>[email protected]</EmailAddress><Telephone/><IsEnabled>true</IsEnabled><IM/><NameInSource>[email protected]</NameInSource><IsAlertEnabled>false</IsAlertEnabled><IsDefaultCached>false</IsDefaultCached><StoredVmQuota>1000</StoredVmQuota><DeployedVmQuota>100</DeployedVmQuota><Role type="application/vnd.vmware.admin.role+xml" name="User"
href="http://vcloud.example.com/api/v1.0/admin/role/1"/><GroupReferences/>
</User>
Modify User Metadata
An administrator can use the edit link in a User element to modify user metadata. The request in
Example 6‐27 disables the User object by setting value of its IsEnabled element to false. As is the case with
all requests, the request body must include all required elements, whether or not you are changing them. The
response is the full User element, including the changed metadata, and includes the links and other metadata
typically supplied by the server.
Example 6-27. Modify User Metadata
Request:
PUT http://vcloud.example.com/api/v1.0/admin/user/85Content-Type: application/vnd.vmware.admin.user+xml...<User name="ExampleUser" xmlns="http://www.vmware.com/vcloud/v1">
<IsEnabled>false</IsEnabled><Role type="application/vnd.vmware.admin.role+xml"
href="http://vcloud.example.com/api/v1.0/admin/role/105"/></User>
VMware, Inc. 113
Chapter 6 Administrative Operations
Response:
200 OKContent-Type: application/vnd.vmware.admin.user+xml...<User name="[email protected]" 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"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/user/85"/><FullName>Example User Full Name</FullName><EmailAddress>[email protected]</EmailAddress><Role type="application/vnd.vmware.admin.role+xml"
href="http://vcloud.example.com/api/v1.0/admin/role/105"/><IsEnabled>false</IsEnabled>
</User>
Remove a User
Before you can remove a user, you must disable the User object by changing the value of its IsEnabled element to false, as shown in Example 6‐27. After it has been disabled, the User element contains a link
where rel="remove". An administrator can use this link remove the user from the organization, as shown in
Example 6‐28.
Example 6-28. Remove a User
Request:
DELETE http://vcloud.example.com/api/v1.0/admin/user/85
Response:
204 No Content
Group AdministrationGroups 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/groupsContent-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>
vCloud API Programming Guide
114 VMware, Inc.
Response:
201 CreatedContent-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.
Remove a Group
An administrator can use the remove link in a Group body to remove a group from a vCloud. Example 6‐30
removes the group imported in Example 6‐29.
Example 6-30. Remove a Group
Request:
DELETE http://vcloud.example.com/api/v1.0/admin/group/44
Response:
204 No Content
Role AdministrationA role associates the name of a user or group with a set of rights. Role names must be unique in a vCloud
instance.
Create a Role
A system administrator can create a role by aggregating a set of rights in a Role body, and then POSTing the body to the add URL for roles. Example 6‐31 creates a new role named vAppWrangler and adds it to the
vCloud shown in Example 6‐2. The response, like other responses to requests that create an object, includes
the POSTed content, a link to the new object, and links of type edit and remove that an administrator can use
to manage this role.
VMware, Inc. 115
Chapter 6 Administrative Operations
Example 6-31. Create a Role
Request:
POST http://vcloud.example.com/api/v1.0/admin/rolesContent-Type: application/vnd.vmware.admin.role+xml<Role name="vAppWrangler" xmlns="http://www.vmware.com/vcloud/v1">
<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>
Response:
201 CreatedContent-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 ... />...
</RightReferences></Role>
View Role Metadata
URLs for all roles in a vCloud appear as RoleReference elements in a vCloud body. An individual role’s URL is also displayed in the response to a request that creates the role A system administrator can GET a role URL
to view the Role body. Example 6‐32 does this for the role created in Example 6‐31.
Example 6-32. View Role Metadata
Request:
GET http://vcloud.example.com/api/v1.0/admin/role/102
Response:
200 OKContent-Type: application/vnd.vmware.admin.role+xml...<Role name="vApp Wrangler" type="application/vnd.vmware.admin.role+xml"
href="http://vcloud.example.com/api/v1.0/admin/role/102" ...>
vCloud API Programming Guide
116 VMware, Inc.
<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
a modified Role body to the edit URL of the Role. See Example 6‐27 for an example of the workflow for this
type of request.
Remove a Role
A system administrator can use the remove link in a Role element to remove a role from a vCloud.
Example 6‐33 removes the role created in Example 6‐31.
Example 6-33. Remove a Role
Request:
DELETE http://vcloud.example.com/api/v1.0/admin/role/102
Response:
204 No Content
View a Right
A system administrator can view, but not modify, the contents of a Right element, as shown in Example 6‐34,
which provides a view of one of the RightReferences shown in Example 6‐2.
Example 6-34. View a Right
Request:
GET http://vcloud.example.com/api/v1.0/admin/right/7
Response:
200 OKContent-Type: application/vnd.vmware.admin.right+xml...<Right xmlns="http://www.vmware.com/vcloud/v1" name="Catalog: Sharing"
type="application/vnd.vmware.admin.right+xml" href="http://vcloud.example.com/api/v1.0/admin/right/7" ... >
<Description>Share a Catalog</Description><Category>catalog</Category>
</Right>
VMware, Inc. 117
7
The VMware vCloud API includes extensions that support a variety of operations on the vSphere Platform,
which provides resources to a VMware vCloud.
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
“Import a Virtual Machine from vCenter” on page 138
Summary of vSphere Platform Operations RequestsTable 7‐1 summarizes vSphere platform operations 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.
VMware vSphere Platform Operations 7
NOTE All vSphere platform operations are restricted to the system administrator. Before attempting any of
these operations, log in to the System organization with the user name and password of the system
administrator account that was created when Cloud Director was installed. For more information, see
“Administrator Credentials and Privileges” on page 93.
Table 7-1. Summary of vSphere Platform Operations Requests
Operation Request Request Body Response
List vSphere Platform Operations and Objects for a vCloud
GET API‐URL/admin/extension None VMWExtension
List Provider vDCs in a vCloud
GET API‐URL/admin/extension/providerVdcReferences
None VMWProviderVdcReferences
List External Networks in a vCloud
GET API‐URL/admin/extension/externalNetworkReferences
None VMWExternalNetworkReferences
vCloud API Programming Guide
118 VMware, Inc.
List Network Pools in a vCloud
GET API‐URL/admin/extension/networkPoolReferences
None VMWNetworkPoolReferences
List vCenter Servers Registered to a vCloud
GET API‐URL/admin/extension/vimServerReferences
None VMWVimServerReferences
Get Information About a vCenter Server
GET API‐URL/admin/extension/vimServer/id
None VimServer
List Available Resource Pools on a vCenter Server
GET API‐URL/admin/extension/vimServer/id/resourcePoolList
None ResourcePoolList
Modify vCenter Server Settings
PUT API‐URL/admin/extension/vimServer/id/
VimServer Task
Register a vCenter Server and vShield Manager
POST API‐URL/admin/extension/action/registervimserver
RegisterVimServerParams RegisterVimServerParams
Unregister a vCenter Server and vShield Manager
POST API‐URL/admin/extension/vimServer/id/action/unregister
None Task
Force Reconnection to a vCenter Server
POST API‐URL/admin/extension/vimServer/id/forcevimserverreconnect
None 204 No Content
List ESX/ESXi Hosts in a vCloud
GET API‐URL/admin/extension/hostReferences
None VMWHostReferences
Get Information About a Host
GET API‐URL/admin/extension/host/id
None Host
Prepare a Host POST API‐URL/admin/extension/host/id/action/prepare
PrepareHostParams Task
Unprepare a Host POST API‐URL/admin/extension/host/id/action/unprepare
None Task
Enable or Disable a Host
POST API‐URL/admin/extension/host/id/action/enable
POST API‐URL/admin/extension/host/id/action/disable
None 204 No Content
Repair a Host POST API‐URL/admin/extension/host/id/action/repair
None 204 No Content
Upgrade a Host Agent POST API‐URL/admin/extension/host/id/action/upgrade
None Task
Create a Provider vDC POST API‐URL/admin/extension/providervdcs
VMWProviderVdc VMWProviderVdc
Examine the vSphere Objects in a Provider vDC
GET API‐URL/admin/extension/providervdc/id
None VMWProviderVdc
Modify a Provider vDC PUT API‐URL/admin/extension/providervdcs
VMWProviderVdc VMWProviderVdc
Enable or Disable a Provider vDC
POST API‐URL/admin/extension/providervdc/id/action/enablePOST API‐URL/admin/extension/providervdc/id/action/disable
None 204 No Content
Remove a Provider vDC
DELETEAPI‐URL/admin/extension/providervdc/id
None Task
Create an External Network
POST API‐URL/admin/extension/externalnets
VMWExternalNetwork VMWExternalNetwork
Table 7-1. Summary of vSphere Platform Operations Requests (Continued)
Operation Request Request Body Response
VMware, Inc. 119
Chapter 7 VMware vSphere Platform Operations
List vSphere Platform Operations and Objects for a vCloudAll resources exposed to vCloud tenants through provider vDCs originate in vCenter instances registered to
the vCloud service. A system administrator can request a list of vSphere objects currently registered for use
with a vCloud. The response also include links to actions that allow the system administrator to add or register
new vSphere objects. Example 7‐1 shows an example of such a request.
Example 7-1. List All vSphere Platform Operations and Objects for a vCloud
Request:
GET http://vcloud.example.com/api/v1.0/admin/extension
Response:
200 OKContent-Type: application/vnd.vmware.admin.vmwextension+xml ...<vmext:VMWExtension xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... >
<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwProviderVdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providerVdcReferences"/>
<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwExternalNetworkReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalNetworkReferences"/>
<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwNetworkPoolReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPoolReferences"/>
<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwVimServerReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServerReferences"/>
<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwHostReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/hostReferences"/>
<vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdcs"/>
<vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwexternalnet+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnets"/>
Get Information About an External Network
GET API‐URL/admin/extension/externalnet/id
none VMWExternalNetwork
Modify an External Network
PUT API‐URL/admin/extension/externalnet/id
VMWExternalNetwork VMWExternalNetwork
Remove an External Network
DELETEAPI‐URL/admin/extension/externalnet/id
none Task
Create a Network Pool POST API‐URL/admin/extension/networkPools
VMWNetworkPool VMWNetworkPool
Get Information About a Network Pool
GET API‐URL/admin/extension/networkPool/id
None VMWExternalNetwork
Modify a Network Pool PUT API‐URL/admin/extension/networkPool/id
VMWNetworkPool VMWNetworkPool
Remove a Network Pool
PUT API‐URL/admin/extension/networkPool/id
None 204 No Content
Import a Virtual Machine as a vApp
POST API‐URL/admin/extension/vimServer/id/importVmAsVapp
ImportVmAsVAppParams VApp
Import a Virtual Machine as a vApp Template
POST API‐URL/admin/extension/vimServer/id/importVmAsVappTemplate
ImportVmAsVAppTemplateParams
VAppTemplate
Table 7-1. Summary of vSphere Platform Operations Requests (Continued)
Operation Request Request Body Response
vCloud API Programming Guide
120 VMware, Inc.
<vcloud:Link rel="add" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPools"/>
<vcloud:Link rel="register" type="application/vnd.vmware.admin.registerVimServerParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/action/registervimserver"/>
<vcloud:Link rel="down" type="application/vnd.vmware.admin.licensingReportList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/licensing/reports"/>
</vmext:VMWExtension>
List Provider vDCs in a vCloudA system administrator can use the providerVdcReferences link returned in a VMWExtension response to request a list of all provider vDCs in the vCloud. Example 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 OKContent-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 vCloudThis operation follows the model shown in Example 7‐2, but uses the externalNetworkReferences link from the VMWExtension response as the target of the request. The response is a VMWExternalNetworkReferences element.
List Network Pools in a vCloudThis operation follows the model shown in Example 7‐2, but uses the networkPoolReferences link from the VMWExtension response as the target of the request. The response is a NetworkPoolReferences element.
List vCenter Servers Registered to a vCloudThis operation follows the model shown in Example 7‐2, but uses the vimServerReferences link from the VMWExtension response as the target of the request. The response is a VMWVimServerReferences element.
Get Information About a vCenter Server
A system administrator can use the href attribute value of any VimServerReference in a VMWVimServerReferences element to get more information about a specific vCenter server, as shown in
Example 7‐3.
VMware, Inc. 121
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" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVApp"/>
<vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVAppTemplate"/>
<vcloud:Link rel="unregister" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/unregister"/>
<vcloud:Description>vCenter created by the Configuration Wizard</vcloud:Description><vmext:Username>administrator</vmext:Username><vmext:Url>http://10.147.40.234:443</vmext:Url><vmext:IsEnabled>true</vmext:IsEnabled><vmext:ShieldManagerIP>10.147.44.59</vmext:ShieldManagerIP><vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName>
</vmext:VimServer>
List Available Resource Pools on a vCenter Server
The VimServer element returned in response to a GET request to a vimServer URL contains a rel="down" link whose href value is a URL that returns a list of available resource pools hosted on that server. A pool is considered available if it is not in use in a vDC. A system administrator can make a GET request to that URL
to list the available pools. Example 7‐4 makes such a request using the resourcePoolList URL from Example 7‐3.
Example 7-4. List Available Resource Pools on a vCenter Server
Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/resourcePoolList
Response:
200 OKContent-Type: application/vnd.vmware.admin.resourcepoollist+xml...<vmext:ResourcePoolList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"
xmlns:vcloud="http://www.vmware.com/vcloud/v1" ...><vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwvirtualcenter+xml"
href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/><vmext:ResourcePool name="Cluster-1">
<vmext:MoRef>resgroup-1159</vmext:MoRef><vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType><vmext:DataStoreRefs/>
</vmext:ResourcePool><vmext:ResourcePool name="Cluster-2">
<vmext:MoRef>resgroup-1064</vmext:MoRef>
vCloud API Programming Guide
122 VMware, Inc.
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType><vmext:DataStoreRefs>
<vmext:VimObjectRef><vmext:MoRef>datastore-10</vmext:MoRef><vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef><vmext:VimObjectRef>
<vmext:MoRef>datastore-11</vmext:MoRef><vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef><vmext:VimObjectRef>
<vmext:MoRef>datastore-12</vmext:MoRef><vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef></vmext:DataStoreRefs>
</vmext:ResourcePool></vmext:ResourcePoolList>
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/100Content-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 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Updating VirtualCenter (100)" ...>
...</Task>
Register a vCenter Server and vShield Manager
A system administrator can register a vCenter server and a companion vShield manager server for use with a
vCloud by making a POST request to the vCloud’s action/registervimserver URL and supplying a RegisterVimServerParams request body, as shown in Example 7‐6.
VMware, Inc. 123
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/registervimserverContent-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 OKContent-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" type="application/vnd.vmware.admin.vmwprovidervdc+xml">
<vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC-22" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100">
<vmext:Username>Administrator</vmext:Username><vmext:Url>https://10.100.121.123:443</vmext:Url><vmext:IsEnabled>false</vmext:IsEnabled>
</vmext:VimServer><vmext:ShieldManager>
<vmext:AssociatedVimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VSM-VC-22" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/>
<vmext:Username>Administrator</vmext:Username><vmext:Url>https://10.100.121.66</vmext:Url>
</vmext:ShieldManager></vmext:RegisterVimServerParams>
Unregister a vCenter Server and vShield Manager
Unregistering a vCenter server makes it and its vShield Manager server unavailable for use in the Cloud
Director environment. A system administrator can unregister a vCenter server and vShield manager by
making a POST request to the vCenter server’s action/unregister URL. Example 7‐7 unregisters the
vCenter server referenced by http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100.
NOTE You must disable the vCenter server before you unregister it.
vCloud API Programming Guide
124 VMware, Inc.
Example 7-7. Unregister a vCenter Server and vShield Manager
Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/unregister
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... >
...</Task>
Force Reconnection to a vCenter Server
If Cloud Director loses it connection to a vCenter Server, or if you change the connection settings, a system
administrator can make a POST request to the server’s action/forcevimserverreconnect link to try forcing a reconnection, as shown in Example 7‐8.
Example 7-8. Force Reconnection to a vCenter Server
Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/forcevimserverreconnect
Response:
204 No Content
List ESX/ESXi Hosts in a vCloudA system administrator can use the hostReferences link returned in a VMWExtension response to request a list of all ESX/ESXi hosts in the vCloud. Example 7‐9 makes such a request, using the hostReferences link returned in Example 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 OKContent-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 element to get detailed information about a specific host, as shown in Example 7‐10.
VMware, Inc. 125
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 OKContent-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><vmext:NumOfCpusPackages>2</vmext:NumOfCpusPackages><vmext:NumOfCpusLogical>8</vmext:NumOfCpusLogical><vmext:CpuTotal>1600</vmext:CpuTotal><vmext:MemUsed>0.0</vmext:MemUsed><vmext:MemTotal>8187.5546875</vmext:MemTotal><vmext:HostOsName>VMware ESXi</vmext:HostOsName><vmext:HostOsVersion>4.0.0</vmext:HostOsVersion><vmext:VimPropertyPageUrl>
vpxclient://7416E531-05B9-4C1F-854D-97EF7C546CB0::HostSystem:host-20/</vmext:VimPropertyPageUrl><vmext:VmMoRef>host-20</vmext:VmMoRef>
</vmext:Host>
Prepare a Host
When you add a host to a vSphere cluster that Cloud Director uses, you must prepare the host before a
provider vDC can use the host’s resources.
You cannot prepare a host that is in lockdown mode. After you prepare a host, you can enable lockdown mode.
A system administrator can prepare a host by making a POST request to the host’s action/prepare URL and supplying a PrepareHostParams request body that includes the username and password of a host
administrator, as shown in Example 7‐11.
Example 7-11. Prepare a Host
Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/prepareContent-Type: application/vnd.vmware.admin.prepareHostParams+xml...<vmext:PrepareHostParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"
xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml">
<vmext:Username>Administrator</vmext:Username><vmext:Password>Pa55w0rd</vmext:Password>
</vmext:PrepareHostParams>
vCloud API Programming Guide
126 VMware, Inc.
Response:
202 AcceptedContent-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 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... >
...</Task>
Enable or Disable a Host
You can disable a host to prevent vApps from starting up on the host. Virtual machines that are already
running on the host are not affected. To perform maintenance on a host, migrate all vApps off of the host or
stop all vApps and then disable the host.
A system administrator can enable or disable a host for use in a vCloud by making a POST request to the host’s
action/enable or action/disable URL. Example 7‐13 disables the host referenced by
http://vcloud.example.com/api/v1.0/admin/extension/host/1.
Example 7-13. Disable a Host
Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/disable
Response:
204 No Content
Repair a Host
If the Cloud Director agent on a host cannot be contacted, a system administrator can try to repair the host
POST request to the host’s action/repair URL. Example 7‐14 upgrades the host agent for the host referenced
by http://vcloud.example.com/api/v1.0/admin/extension/host/1.
VMware, Inc. 127
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 AcceptedContent-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
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Upgrading Host (1)" ...>
...</Task>
Create a Provider vDCAn VMWProviderVdc is an extended representation of a ProviderVdc object. It includes elements that allow
a system administrator to specify resources such as datastores and resource pools provided by a vCenter
instance registered to the vCloud. Only a system administrator can view or modify a VMWProviderVdc. An organization administrator or other privileged user can examine all other properties of a provider vDC (see
“Examine the Contents of a Provider vDC” on page 103).
After a system administrator creates a VMWProviderVdc, it becomes visible as a member of the
ProviderVdcReferences element of a VCloud. See “Get an Administrative View of a Cloud” on page 93.
A system administrator can use the rel="add" link for providervdcs in a VMWExtension body to add a provider vDC to a vCloud. Example 7‐18 does this by making a POST request to the providervdcs link returned in Example 7‐1.
To retrieve the values you need for the DataStoreRefs and ResourcePoolRef elements in the request body,
start by listing the vCenter Servers registered to this vCloud (see “List vCenter Servers Registered to a vCloud”
on page 120), then GET one of the vCenter Server URLs listed in the response. The result is a VimServer
element, as shown in Example 7‐16.
vCloud API Programming Guide
128 VMware, Inc.
Example 7-16. VimServer Element
Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101
Response:
200 OKContent-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" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/importVmAsVAppTemplate"/>
<vcloud:Link rel="edit" type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/>
<vcloud:Link rel="unregister" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/action/unregister"/>
<vcloud:Link rel="reconnect" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/action/forcevimserverreconnect"/>
<vmext:Username>administrator</vmext:Username><vmext:Url>https://10.147.20.155:443</vmext:Url><vmext:IsEnabled>true</vmext:IsEnabled><vmext:ShieldManagerIP>10.147.41.67</vmext:ShieldManagerIP><vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName>
</vmext:VimServer>
The resourcePoolList from a VimServer element (see Example 7‐17) includes the MoRef and VimObjectType values for all accessible datastores and resource pools associated with that vCenter server.
Example 7-17. Resource Pool List
Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/resourcePoolList
Response:
200 OKContent-Type: application/vnd.vmware.admin.resourcepoollist+xml...<vmext:ResourcePoolList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"
xmlns:vcloud="http://www.vmware.com/vcloud/v1" ... ><vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwvirtualcenter+xml"
href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/><vmext:ResourcePool name="gasare-vc2-rp">
<vmext:MoRef>resgroup-3582</vmext:MoRef><vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType><vmext:DataStoreRefs>
<vmext:VimObjectRef><vmext:MoRef>datastore-418</vmext:MoRef><vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef><vmext:VimObjectRef>
VMware, Inc. 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/providervdcsContent-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>
<vcloud:Cpu><vcloud:Units>MHz</vcloud:Units><vcloud:Allocation>2241</vcloud:Allocation><vcloud:Total>24675</vcloud:Total>
</vcloud:Cpu><vcloud:Memory><vcloud:Units>MB</vcloud:Units><vcloud:Allocation>1319056</vcloud:Allocation><vcloud:Total>2097152</vcloud:Total></vcloud:Memory>
</vcloud:ComputeCapacity><vcloud:StorageCapacity>
<vcloud:Units>MB</vcloud:Units><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:
201 CreatedContent-Type: application/vnd.vmware.admin.vmwprovidervdc+xml
vCloud API Programming Guide
130 VMware, Inc.
...<vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" status="0"
name="PvDC-VC2" xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2">
<vcloud:Link rel="enable" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2/action/enable"/>
<vcloud:Link rel="edit" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"/>
<vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"/>
<vcloud:Link rel="alternate" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/>
<vcloud:Link rel="down" type="application/vnd.vmware.admin.vdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences"/>
<vcloud:Description>New Provider vDC</vcloud:Description><vcloud:Tasks>
<vcloud:Task ... operation="Creating Provider Virtual Datacenter PvDC-VC2(2)" ... >...
</vcloud:Task></vcloud:Tasks><vcloud:Description>PVDC_VC2</vcloud:Description><vcloud:ComputeCapacity>
<vcloud:Cpu><vcloud:Units>MHz</vcloud:Units><vcloud:Allocation>21929</vcloud:Allocation><vcloud:Total>24675</vcloud:Total><vcloud:Used>10053</vcloud:Used><vcloud:Overhead>384</vcloud:Overhead>
</vcloud:Cpu><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" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/>
<vmext:MoRef>datastore-418</vmext:MoRef><vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
VMware, Inc. 131
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
provider vDC’s status attribute changes to 1.
A HostReferences element that contains references to the ESX/ESXi hosts registered to the vCenter
server backing this provider vDC.
Examine the vSphere Objects in a Provider vDC
A system administrator can retrieve a list of ProviderVdcReferences (see “List Provider vDCs in a vCloud” on page 120), then use the value of the href attribute in any ProviderVdcReference as the target of a GET request. The response is a VMWProviderVdc body similar to the one shown in the response in Example 7‐18.
Modify a Provider vDC
To modify a provider vDC, make a PUT request to its edit link, and supply a modified version of the
VMWProviderVdc element in the request body. In Example 7‐19, the client modifies the Cpu Allocation of the provider vDC created in Example 7‐18, then includes the modified element in a PUT request to the edit link in the VMWProviderVdc element.
You must include all required elements and attributes in the request, even those that you are not changing.
Example 7-19. Modify a Provider vDC
Request:
PUT http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2Content-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:ComputeCapacity><vcloud:Cpu>
<vcloud:Units>MHz</vcloud:Units><vcloud:Allocation>4096</vcloud:Allocation><vcloud:Total>24675</vcloud:Total>
</vcloud:Cpu><vcloud:Memory><vcloud:Units>MB</vcloud:Units><vcloud:Allocation>1319056</vcloud:Allocation><vcloud:Total>2097152</vcloud:Total>
vCloud API Programming Guide
132 VMware, Inc.
</vcloud:Memory></vcloud:ComputeCapacity><vcloud:StorageCapacity>
<vcloud:Units>MB</vcloud:Units><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 OKContent-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>
The response, most of which is not shown here, echoes the request.
Enable or Disable a Provider vDC
A system administrator can use the enable or disable action links in a VMWProviderVdc element to enable
or disable a provider vDC, as shown in Example 7‐20. The enablement state of the VMWProviderVdc is shown
in its IsEnabled element.
Example 7-20. Disable a Provider vDC
Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/providervdc/43/action/disable
Response:
204 No Content
Remove a Provider vDC
Before you can remove a provider vDC, you must disable it. After the provider vDC has been disabled, its
representation includes a rel="remove" link. A system administrator can make a DELETE request to that link
to remove a provider vDC from a vCloud. The response contains a Task that tracks the delete operation.
VMware, Inc. 133
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 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Deleting Provider Virtual Datacenter (43)" ...>
...</Task>
Create an External NetworkA 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.
Example 7-22. Create an External Network
Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/externalnetsContent-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"><vcloud: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><vcloud:Dns1>10.147.115.1</vcloud:Dns1><vcloud:Dns2>10.147.115.2</vcloud:Dns2><vcloud:DnsSuffix>eng.vmware.com</vcloud:DnsSuffix><vcloud:IpRanges>
<vcloud:IpRange><vcloud:StartAddress>10.147.58.1</vcloud:StartAddress><vcloud:EndAddress>10.147.58.100</vcloud:EndAddress>
</vcloud:IpRange></vcloud:IpRanges>
</vcloud:IpScope><vcloud:FenceMode>isolated</vcloud:FenceMode></vcloud:Configuration><vmext:VimPortGroupRef>
<vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/>
<vmext:MoRef>dvportgroup-25</vmext:MoRef><vmext:VimObjectType>NETWORK</vmext:VimObjectType>
</vmext:VimPortGroupRef></vmext:VMWExternalNetwork>
NOTE You must use the VMware vSphere API to obtain the values you need to populate the
VimPortGroupRef element.
vCloud API Programming Guide
134 VMware, Inc.
Response:
201 CreatedContent-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 element that tracks creation of the external network.
Get Information About an External Network
A system administrator can use the href attribute value of any ExternalNetworkReference element to get
more information about a specific external network. Example 7‐23 retrieves information about the external
network created in Example 7‐22. The entire VMWExternalNetwork body is returned in the response, but only part of the response is shown in the example
Example 7-23. Get Information About an External Network
Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27
Response:
200 OKContent-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:Configuration>...</vcloud:Configuration><vmext:VimPortGroupRef>
<vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/>
<vmext:MoRef>dvportgroup-25</vmext:MoRef><vmext:VimObjectType>NETWORK</vmext:VimObjectType>
</vmext:VimPortGroupRef></vmext:VMWExternalNetwork>
VMware, Inc. 135
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/27Content-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><vcloud:Dns1>10.147.115.1</vcloud:Dns1><vcloud:Dns2>10.147.115.2</vcloud:Dns2><vcloud:DnsSuffix>eng.vmware.com</vcloud:DnsSuffix><vcloud:IpRanges>
<vcloud:IpRange><vcloud:StartAddress>10.147.58.1</vcloud:StartAddress><vcloud:EndAddress>10.147.58.201</vcloud:EndAddress>
</vcloud:IpRange></vcloud:IpRanges>
</vcloud:IpScope><vcloud:FenceMode>isolated</vcloud:FenceMode></vcloud:Configuration><vmext:VimPortGroupRef>
<vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/>
<vmext:MoRef>dvportgroup-25</vmext:MoRef><vmext:VimObjectType>NETWORK</vmext:VimObjectType>
</vmext:VimPortGroupRef></vmext:VMWExternalNetwork>
Response:
200 OKContent-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">...
</vmext:VMWExternalNetwork>
Remove an External Network
To remove an external network, a system administrator can make a DELETE request to its rel="remove" link. The response is a Task that tracks the delete operation.
vCloud API Programming Guide
136 VMware, Inc.
Example 7-25. Remove an External Network
Request:
DELETE http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27
Response:
202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Deleting External Network (27)" ...>
...</Task>
Create a Network PoolA 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.
Example 7-26. Create a Network Pool
Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/networkPoolsContent-Type: application/vnd.vmware.admin.networkPool+xml...<vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"
xmlns:vcloud="http://www.vmware.com/vcloud/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance” xsi:type="vmext:VlanPoolType" name="NewVlanPool">
<vcloud:Description>Extra pool for new Orgs</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>120</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef> <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>
Response:
201 CreatedContent-Type: application/vnd.vmware.admin.networkPool+xml...<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" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41" ... >
<vcloud:Description>Extra pool for new Orgs</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>120</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef>
NOTE You must use the VMware vSphere API to obtain the values you need to populate the VimSwitchRef element.
VMware, Inc. 137
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"
xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41" ... >
<vcloud:Description>Extra pool for new Org Nets</vcloud:Description> ...</vmext:VMWNetworkPool>
Modify a Network Pool
To modify a network pool, make a PUT request to its edit link, and supply a modified version of the
VMWNetworkPool body. In Example 7‐28, the client modifies the VlanRange End of the network pool created
in Example 7‐26, then includes the modified body in a PUT request to the edit link that was returned when
the network pool was created.
Example 7-28. Modify a Network Pool
Request:
PUT http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41Content-Type: application/vnd.vmware.admin.networkPool+xml...<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">
<vcloud:Description>Extra pool for new Org Nets</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>150</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef> <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>
vCloud API Programming Guide
138 VMware, Inc.
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 vCenterA system administrator can import virtual machines from any vCenter registered to a vCloud. The virtual
machines can be imported to any vDC in the vCloud, and can be imported in vApp or vApp template form.
Discover the Virtual Machines in a vCenter
A GET request to the vmsList URL in a VimServer response body returns a list of virtual machines registered
to that vCenter server. Example 7‐30 retrieves the list of virtual machines from the vmsList URL shown in
Example 7‐3 on page 121.
Example 7-30. Discover the Virtual Machines in a vCenter
Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/vmsList
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmsobjectrefslist+xml...<vmext:VmObjectRefsList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"
xmlns:vcloud="http://www.vmware.com/vcloud/v1" ...><vmext:VmObjectRef name="Win2K8">
<vcloud:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="vCenter-PA-001" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/>
<vcloud:MoRef>vm-642</vcloud:MoRef><vcloud:VimObjectType>VIRTUAL_MACHINE</vcloud:VimObjectType>
</vmext:VmObjectRef><vmext:VmObjectRef ...>
...</vmext:VmObjectRef>
</vmext:VmObjectRefsList>
VMware, Inc. 139
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=p&pageSize=s
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 link in the VimServer response body whose vmslist contained the VmObjectRef that represents the virtual machine. Example 7‐32 imports the virtual machine shown in Example 7‐30 from the vCenter server
represented by the VimServer element shown in Example 7‐3 on page 121. The request body is an
ImportVmAsVAppParams element whose sourceMove attribute specifies whether or not the source virtual
machine should be removed from vCenter after the import is complete. The request body also specifies the
managed object reference of the virtual machine to import, and the href of the vDC to which the import goes.
The response is an unresolved vApp body containing a task that tracks the import.
Example 7-32. Import a Virtual Machine as a vApp
Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVappContent-type: application/vnd.vmware.admin.importVmAsVAppParams+xml...<ImportVmAsVAppParams xmlns="http://www.vmware.com/vcloud/extension/v1" name="ImportedWin2K8"
sourceMove="false"><VmMoRef>vm-642</VmMoRef><Vdc href="http://vcloud.example.com/api/v1.0/vdc/2"/>
</ImportVmAsVAppParams>
Response:
201 CreatedContent-Type: application/vnd.vmware.vcloud.vApp+xml
<VApp status="0" name="ImportedWin2K8" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-102" ...>
...<Description/><Tasks>
<Task ... operation=”Busy Virtual Application Win2K8” ...>...
</Task></Tasks>
</VApp>
vCloud API Programming Guide
140 VMware, Inc.
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/importVmAsVappTemplateContent-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 CreatedContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate status="0" name="ImportedWin2K8-Template"
type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-64" ...>
...<Description/><Tasks>
<Task ... operation=”Busy Virtual Application Template Win2K8” ...>...
</Task></Tasks>
</VApp>
VMware, Inc. 141
8
The vCloud API represents objects in a vCloud as XML documents in which object properties are encoded as
elements and attributes with typed values and an explicit object hierarchy defined by an XML schema. This
chapter provides reference information about how the vCloud API uses XML to represent vCloud objects.
This chapter includes the following topics:
“About Object Representations” on page 141
“Common Datatypes” on page 142
“Common Attributes” on page 143
“Common Elements” on page 146
“API Versioning” on page 147
“Extensibility” on page 148
About Object RepresentationsClient programs of RESTful Web services must be able to request object representations from the server, parse
the server’s responses to extract the information they contain, and compose requests that, in many cases, are
based on the information extracted from a response. Developers of such clients must understand the structure
of each representation that might be part of a request or response, as well as any requirements that the network
protocol (HTTP) places on client‐server interaction. In this guide, reference information on each object
representation includes the XML schema of the element that represents the object, the object type (encoded as
the MIME content type of the request or response), and a prototype of the object reference (a URL).
Schema
Each vCloud API object is defined in an XML schema document. Some objects are defined in their own schema
documents. Others are defined in the context of the larger schema in which they are used. Still others are
defined in a common schema document, from which other schemas inherit. This guide presents reference
information about XML schemas in tabular form, as shown in Table 8‐1.
XML Representations in the vCloud API 8
Table 8-1. Schema Reference Table Columns
Name Min Max Type Description
Name of an element or attribute contained. Element names begin with an uppercase character. Attribute names begin with a lowercase character.
Minimum number of this attribute or element required by the schema.
Maximum number of this attribute or element allowed by the schema. A value of n means that the maximum number is unlimited.
Type of the attribute or element, either a primitive XML datatype or a complex type defined by the vCloud API.
Description of the attribute or element
vCloud API Programming Guide
142 VMware, Inc.
Schema Validation
This release of Cloud Director uses a validating XML parser that requires elements in XML documents to agree
in both order and number with the schema. Required elements must appear in request bodies. All elements
that appear in request bodies must appear in the order established by the schema, and with content that
conforms to the type constraint specified in the schema. Default values, where defined, are supplied for
elements that are empty.
If a request contains elements from multiple XML namespaces, namespace identifiers must be supplied in
request bodies and prepended to element names. See “XML Namespace Identifiers” on page 145.
Content Type
All requests that have a body must include an HTTP Content‐Type header that specifies the content type of
the body. Content types have been defined for any element that can be used as a request body, and are shown
along with the schema and other reference information for the element.
Object Reference Prototype
Every object in a vCloud is uniquely identified by a URL. This URL is constructed by the server and returned
in the value of the href attribute of the XML element that represents the object. It also appears in various Link and ReferenceType elements that provide references to the object. This URL serves as a unique identifier that
persists for the life of the object and is never re‐used. When a client makes an HTTP GET request to an object
href, the server returns the current XML representation of that object.
Although URLs have a well‐known syntax and a well‐understood interpretation, a client should treat each
href as an opaque string. The rules that govern construction of href strings by the server are not guaranteed to remain in effect in future releases. In this release, they yield predictable content that conforms to one of two
prototypes:
Objects such as organizations, vDCs, networks, and catalogs have href values of the form API‐URL/object‐type/id
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 DatatypesThe 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.
NOTE In the reference material, elements that are simply containers are listed by name, along with an
explanation of the purpose of the container, but do not include a schema reference.
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. 143
Chapter 8 XML Representations in the vCloud API
Complex Types
XML elements defined by the vCloud API are instances of complex types. For most elements, the complex type
name is the element name concatenated with the string Type (for example, the Org element is an instance of
OrgType, the vDC element is an instance of VdcType, and so on). In most of these cases, the schema
representation of the element provides an adequate reference for the underlying complex type.
There are also a few generic types of which many different kinds of element can be an instance. Because these
types are not associated with a particular kind of element, we provide schema information for them here.
EntityType
This is the base complex type for elements such as Org, vDC, and vApp.
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.
Common AttributesElements 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.
xs:long Numeric value in the range ‐9223372036854775808 to 9223372036854775807.
xs:int Numeric value in the range ‐2147483648 to 2147483647.
xs:string Any character data.
Table 8-2. Primitive XML Data Types Used by the vCloud API (Continued)
Value Description
Schema
Name Min Max Type Description
name 1 1 xs:string Name of the object
Description 0 1 xs:string Optional description of the object
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object. Successfully completed tasks are not listed.
Schema
Name Min Max Type Description
href 1 1 xs:anyURI Hyperlink to the referenced object
type 0 1 xs:string Object type, expressed as the media type of the XML representing of the object
name 0 1 xs:string Name of the referenced object.
vCloud API Programming Guide
144 VMware, Inc.
name
Every object requires a name attribute whose string value provides the display name for the object. The value
of name must be unique within a given scope, as shown in Table 8‐3.
href
Every object has unique reference encoded in the href attribute of its XML representation. See “Object
Reference Prototype” on page 142.
type
Every object allows a type attribute in its XML representation. The value of this attribute is the object type
expressed as a string, which clients should interpret as the media type (HTTP Content‐Type) of the
representation. This string is case‐insensitive in requests, and can be returned in either mixed case or lowercase
characters in responses. For more information, see “Content Type” on page 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.
Table 8-3. Requirements for Unique Object Names
Object Type Name Scope
ProviderVdc vCloud
Org, AdminOrg vCloud
Vdc Containing organization
Catalog Containing organization
CatalogItem Containing catalog
vAppTemplate Not constrained
vApp Containing organization
Vm Containing vApp
Media Not constrained
Network Container (Org, vApp, or vCloud)
NOTE 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 Vm
‐1 The object could not be created. YES YES YES
0 The object is unresolved. YES YES YES
1 The object is resolved. YES YES YES
2 The object is deployed. No No No
3 The object is suspended. No YES † YES
4 The object is powered on. No YES † YES
5 The object is waiting for user input. No YES † YES
6 The object is in an unknown state. YES YES YES
7 The object is in an unrecognized state. YES YES YES
VMware, Inc. 145
Chapter 8 XML Representations in the vCloud API
XML Namespace Identifiers
Elements used as request or response bodies contain a set of attributes that enable XML validation. The body
of a PUT or POST request must contain all XML namespace identifiers required to validate the XML it
contains. A response body typically includes all the XML namespace identifiers that the server used to validate
it, in addition to other attributes that specify the schema locations searched during validation. Table 8‐5
summarizes these attributes and shows the namespace identifiers and prefixes used in the examples in this
guide.
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>
8 The object is powered off. YES YES † YES
9 The object is in an inconsistent state. No YES YES
10 Children do not all have the same status. YES YES No
11 Upload initiated, OVF descriptor pending YES No No
12 Upload initiated, copying contents YES No No
13 Upload initiated, disk contents pending YES No No
14 Upload has been quarantined YES No No
15 Upload quarantine period has expired YES No No
† Indicates that all Children have this status
Table 8-4. vAppTemplate, vApp, and Vm status Attribute Values (Continued)
Value Description vAppTemplate vApp Vm
Table 8-5. XML Namespace Identifiers
Name Value Requirement
xmlns http://www.vmware.com/vcloud/v1.0 Required in all request bodies.
xmlns:vmext http://www.vmware.com/vcloud/extension/v1 Required in request bodies that include elements from the vSphere Platform Extensions
xmlns:ovf http://schemas.dmtf.org/ovf/envelope/1 Required in request bodies that include elements prefixed with ovf:
xmlns:rasd http://schemas.dmtf.org/wbem/wscim/1/cim‐schema/2/CIM_ResourceAllocationSettingData
Required in request bodies that include elements prefixed with rasd:
xmlns:vssd http://schemas.dmtf.org/wbem/wscim/1/cim‐schema/2/CIM_VirtualSystemSettingData
Not required in request bodies.
xsi:schemaLocation An installation‐dependent schema location search path. For more information, see http://www.w3.org/TR/xmlschema‐0/#schemaLocation
Not required in request bodies.
xmlns:xsi http://www.w3.org/2001/XMLSchema‐instance Not required in request bodies.
vCloud API Programming Guide
146 VMware, Inc.
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 ElementsThe 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
Table 8‐6 lists the minor error code values defined in this release of the vCloud API.
Schema
Name Min Max Type Description
message 1 1 xs:string Message describing the error
majorErrorCode 1 1 xs:int Matches the HTTP status code. See “Status Codes” on page 18.
minorErrorCode 1 1 xs:string Error code specific to the failed operation
vendorSpecificErrorCode 0 1 xs:string Empty in this release
stackTrace 0 1 xs:string Stack trace of the error, if available. This attribute is returned only to a system administrator.
Table 8-6. Minor Error Codes
Error Code Description of Error
ACCESS_TO_RESOURCE_IS_FORBIDDEN The request was made by a user who had insufficient rights to the object or operation.
BAD_REQUEST The request could not be validated or contained invalid XML.
CONFLICT A conflict was detected between sections of an OVF descriptor.
EULA_NOT_ACCEPTED An attempt to instantiate a vAppTemplate or use a vAppTemplate or a Vm in a composition did not include an AllEULAsAccepted element with a value of true.
INTERNAL_SERVER_ERROR Returned for any failure that cannot be matched to another minor error code.
INVALID_REFERENCE One or more references (href attribute values) supplied in the request could not be resolved to an object.
METHOD_NOT_ALLOWED The HTTP method (GET, PUT, POST, DELETE) is not allowed for the request.
RESOURCE_NOT_FOUND One or more references (href attribute values) supplied in the request could not be resolved to an object, or the Content‐type of the request was incorrect.
VMware, Inc. 147
Chapter 8 XML Representations in the vCloud API
Link
A Link element defines a hyperlink with a relationship, URI, and an optional name and media type. For more
information about how Link elements are used and a list of the values allowed for the rel attribute, see “Links and Link Relations” on page 15.
This element is read‐only.
API VersioningvCloud 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 OKContent-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>
UNKNOWN The request raised an exception that did not match any HTTP status code.
UNSUPPORTED_MEDIA_TYPE The wrong content type was specified for the request.
Table 8-6. Minor Error Codes (Continued)
Error Code Description of Error
Schema
Name Min Max Type Description
rel 1 1 RelationType Relation of the link to the referenced object
href 1 1 xs:anyURI Hyperlink to the referenced object
type 0 1 xs:string Media type of the referenced object. Links to actions do not have a media type.
name 0 1 xs:string Name of the referenced object. Links to Tasks and actions do not have names.
vCloud API Programming Guide
148 VMware, Inc.
<MediaType>application/vnd.vmware.vcloud.vdc+xml</MediaType><ComplexTypeName>CatalogItemType</ComplexTypeName><SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation>
</MediaTypeMapping><MediaTypeMapping>
...</MediaTypeMapping>
</VersionInfo></SupportedVersions>
SupportedVersions
A SupportedVersions element is a container for VersionInfo elements.
VersionInfo
A VersionInfo element defines the login URL and media types supported by a version of the vCloud API.
This element is read‐only.
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.
ExtensibilityThe 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.
Schema
Name Min Max Type Description
Version 1 1 xs:string Version number
LoginUrl 1 1 xs:string URL for logging in to this version
MediaTypeMapping 0 n MediaTypeMappingType Media type of the referenced object. Links to actions do not have a media type.
Schema
Name Min Max Type Description
MediaType 1 1 xs:string MIME content type of this complex type
ComplexTypeName 1 1 xs:string Name of this complex type
SchemaLocation 1 1 xs:anyURI URL for the XML schema definition document that defines this complex type
VMware, Inc. 149
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 Min Max Type Description
required 0 1 xs:boolean True if this extension must be understood by the server
any attribute name 0 n xs:any An arbitrary number of attributes of any type
any element name 0 n xs:any An arbitrary number of elements of any type
vCloud API Programming Guide
150 VMware, Inc.
VMware, Inc. 151
9
This chapter provides reference information about the XML elements that represent the object model defined
for general use in this release of the vCloud API. Elements documented in this chapter are typically readable
by all users, and can be modified by users with appropriate rights. For more information about how the
vCloud API uses XML to represent objects, and how this reference material is organized, see “XML
Representations in the vCloud API” on page 141.
This chapter provides reference material on the following elements and the elements they contain:
“OrgList” on page 151
“Org” on page 151
“Vdc” on page 152
“OrgNetwork” on page 154
“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
OrgListAn 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
OrgThe 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
User API Reference 9
vCloud API Programming Guide
152 VMware, Inc.
Object href prototype API‐URL/org/id
VdcA 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 Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Link 0 n LinkType Links to actions and contained objects
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
FullName 1 1 xs:string Full name of the organization
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
status 0 1 xs:int The creation status of the vDC:
-1 creation failed
0 not ready
1 ready
2 unknown
3 unrecognized status
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
AllocationModel 1 1 AllocationModelType Defines how resources are allocated by the vDC. The value of this element is set by the administrator who created the vDC. It is read‐only to users.
StorageCapacity 1 1 CapacityWithUsageType Defines the storage capacity available in the vDC
ComputeCapacity 1 1 ComputeCapacityType Defines the compute capacity available in the vDC
ResourceEntities 0 1 ResourceEntitiesType Read‐only container for ResourceEntity elements
AvailableNetworks 0 1 AvailableNetworksType Read‐only container for OrgNetwork elements that represent organization networks contained by the vDC
NicQuota 1 1 xs:int Maximum number of virtual NICs allowed in this vDC. Defaults to 0, which specifies an unlimited number.
NetworkQuota 1 1 xs:int Maximum number of OrgNetwork objects that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number.
VMware, Inc. 153
Chapter 9 User API Reference
StorageCapacity
The StorageCapacity element reports storage resource consumption in a vDC.
ComputeCapacity
The ComputeCapacity element reports CPU and memory resource consumption in a vDC.
Cpu
The Cpu element reports CPU resource consumption in a vDC.
Memory
The Memory element reports memory resource consumption in a vDC.
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.
VmQuota 0 1 xs:int Maximum number of virtual machines that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number.
IsEnabled 0 1 xs:boolean True if this vDC is enabled
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only.
Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this vDC. This value is read‐only.
Schema
Name Min Max Type Description
Cpu 1 1 CapacityWithUsageType Reports CPU resource consumption in a vDC
Memory 1 1 CapacityWithUsageType Reports memory resource consumption in a vDC
Schema
Name Min Max Type Description
Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only.
Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this vDC. This value is read‐only.
Schema
Name Min Max Type Description
Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only.
Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this vDC. This value is read‐only.
vCloud API Programming Guide
154 VMware, Inc.
ResourceEntities
The ResourceEntities element is a read‐only container for ResourceEntity elements.
ResourceEntity
The ResourceEntity element is a read‐only reference to a vAppTemplate or Media object contained by a vDC.
Files
The Files element is a container for File elements.
File
File elements are constructed by the server in response to an upload or download request.
OrgNetworkAn 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 Min Max Type Description
name 1 1 xs:string Common object name attribute
status 0 1 xs:int Creation status of the referenced object.
any attribute name 0 n any Includes type, href, XML namespace identifiers
Files 0 1 FilesListType Read‐only container for File elements
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
size 0 1 xs:long Size of the file in bytes
bytesTransferred 0 1 xs:long 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 0 1 xs:normalizedString Ignored in this release
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Description 0 1 xs:string Optional description
VMware, Inc. 155
Chapter 9 User API Reference
Configuration
The Configuration element specifies properties of a network.
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.
IpScope
The IpScope element defines the address range, gateway, netmask, and other properties of the network.
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
Configuration 0 1 NetworkConfigurationType Properties of the network
NetworkPool 0 1 ReferenceType A reference to the network pool from which this network is provisioned. This element, which is required when creating a natRouted or isolated network, is returned in response to a creation request but not shown in subsequent GET requests.
AllowedExternalIpAddresses 0 1 IpAddressesType List of external IP addresses that this network can use for NAT.
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
IpScope 0 1 IpScopeType Defines the address range, gateway, netmask, and other properties of the network
ParentNetwork 0 1 ReferenceType Reference to a network to which this network connects
FenceMode 1 1 FenceModeValuesType Defines how this network is connected to its ParentNetwork
Features 0 1 NetworkFeaturesType Defines a set of network features.
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.
Schema
Name Min Max Type Description
IsInherited 1 1 xs:boolean True if the values in this IpScope element are inherited from the ParentNetwork of the containing Configuration
Gateway 0 1 IpAddressType IP address of the network gateway
Netmask 0 1 IpAddressType Netmask to apply to addresses on the network
Dns1 0 1 IpAddressType IP address of the primary DNS server for this network
vCloud API Programming Guide
156 VMware, Inc.
IpRange
The IpRange element defines a range of IP addresses available on a network.
Features
The Features element defines the DHCP and firewall features of a network.
DhcpService
The DhcpService element specifies the properties of the network’s DHCP service.
FirewallService
The FirewallService element defines the firewall service capabilities of a network.
Dns2 0 1 IpAddressType IP address of the secondary DNS server for this network
DnsSuffix 0 1 xs:string Suffix to be applied when resolving hostnames that are not fully‐qualified.
IpRanges 0 1 IpRangesType Read‐only container for IpRange elements.
AllocatedIpAddresses 0 1 IpAddressesType List of addresses allocated to connections to this network. Must fall within any specified IpRanges.
Schema
Name Min Max Type Description
StartAddress 1 1 IpAddressType Lowest IP address in the range
EndAddress 1 1 IpAddressType Highest IP address in the range
Schema
Name Min Max Type Description
DhcpService 0 1 DhcpServiceType Specifies the properties of the network’s DHCP service
FirewallService 0 1 FirewallServiceType Defines the firewall service capabilities of the network
NatService 0 1 NatServiceType Defines the NAT service capabilities of the network
Schema
Name Min Max Type Description
IsEnabled 0 1 xs:boolean True if the service is enabled
DefaultLeaseTime 0 1 xs:int Default duration of a DCHP address lease
MaxLeaseTime 0 1 xs:int Maximum duration of a DCHP address lease.
IpRange 0 1 IpRangeType Range of IP addresses available to DHCP clients
Schema
Name Min Max Type Description
IsEnabled 0 1 xs:boolean True if the service is enabled
FirewallRule 0 n FirewallRuleType Defines a single firewall rule
Schema (Continued)
Name Min Max Type Description
VMware, Inc. 157
Chapter 9 User API Reference
FirewallRule
The FirewallRule element defines a single firewall rule.
Policy
The Policy element of a FirewallRule specifies how packets are handled by the firewall. Table 9‐2 shows
permitted values for element content and the results they produce.
Protocols
The Protocols element specifies the protocols to which firewall rules apply.
NatService
The NatService element defines the network address translation capabilities of a network.
Schema
Name Min Max Type Description
IsEnabled 0 1 xs:boolean True if the rule is enabled
Description 0 1 xs:string description of the rule
Policy 0 1 FirewallPolicyType Specifies how packets are handled by the firewall
Protocols 0 1 ProtocolsType Specifies the protocols to which this firewall rule applies
Port 1 1 xs:int Specifies the network port to which this firewall rule applies. A value of ‐1 matches any port.
DestinationIp 1 1 IpAddressType Specifies the destination IP address, inside the firewall, to which this firewall rule applies
Table 9-2. FirewallRule Policy Element Values
Value Result
drop Drop packets of this type
allow Allow packets of this type to pass through the firewall
Schema
Name Min Max Type Description
Tcp 0 1 xs:boolean True if the firewall rules apply to the TCP protocol
Udp 0 1 xs:boolean True if the firewall rules apply to the UDP protocol
Schema
Name Min Max Type Description
IsEnabled 0 1 xs:boolean True if the service is enabled
NatType 0 1 NatTypeType Specifies how Network Address Translation is implemented by the NAT service
Policy 0 1 NatPolicyType Specifies how packets are handled by the NAT service
NatRule 0 n NatRuleType Specifies a single NAT rule
vCloud API Programming Guide
158 VMware, Inc.
NatType
The NatType element specifies how network address translation is implemented by the NAT service. Table 9‐3
shows permitted values for element content and the results they produce.
Policy
The Policy element of a NatService element specifies how packets are handled by the NAT service. Table 9‐4
shows permitted values for element content and the results they produce.
NatRule
The NatRule element specifies a single network address translation rule.
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.
Table 9-3. NatType Element Values
Value Result
ipTranslation NAT service implemented by IP address translation
portForwarding NAT service implemented by network port forwarding
Table 9-4. NatService Policy Element Values
Value Result
allowTraffic Packets of this type pass through the firewall in both directions
allowTrafficIn Only inbound packets of this type pass through the firewall
Schema
Name Min Max Type Description
Description 0 1 xs:string Optional description of the rule
OneToOneBasicRule 0 1 NatOneToOneBasicRuleType Ignored in this release
OneToOneVmRule 0 1 NatOneToOneVmRuleType Specifies network address translation details for a single virtual machine
PortForwardingRule 0 1 NatPortForwardingRuleType Maps an IP address and port in an organization network to an external IP address and port
VmRule 0 1 NatVmRuleType Maps an IP address and port in a vApp network to an external IP address and port
Schema
Name Min Max Type Description
MappingMode 1 1 NatMappingModeType Specifies how IP address mapping is implemented by the NAT service
ExternalIP 0 1 IpAddressType If MappingMode is manual, specifies the external IP address of this Vm
VAppScopedVmId 1 1 xs:string Read‐only identifier created on import
VmNicId 1 1 xs:int Device number of the NIC on the referenced virtual machine
VMware, Inc. 159
Chapter 9 User API Reference
MappingMode
The MappingMode element specifies how IP address mapping is implemented by the NAT service. Table 9‐5
shows permitted values for element content and the results they produce.
PortForwardingRule
The PortForwardingRule element describes a NAT rule that maps an IP address and port in an organization
network to an external IP address and port.
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.
Table 9-5. MappingMode Element Values
Value Result
manual The external IP address is specified in the ExternalIP element
automatic The external IP address is assigned automatically
Schema
Name Min Max Type Description
ExternalIP 1 1 IpAddressType IP address to which this NAT rule maps the IP address specified in the InternalIP element
ExternalPort 1 1 xs:int Network port to which this NAT rule maps the port number specified in the InternalPort element
InternalIP 1 1 IpAddressType IP address to which this NAT rule maps the IP address specified in the ExternalIp element.
InternalPort 1 1 xs:int Network port to which this NAT rule maps the port number specified in the ExternalPort element.
Protocol 1 1 Layer4ProtocolType Specifies the network protocol to which this rule applies
Schema
Name Min Max Type Description
ExternalIP 0 1 IpAddressType IP address to which this NAT rule maps the IP address specified in the InternalIP element.
ExternalPort 1 1 xs:int The network port to which this NAT rule maps the port number specified in the InternalPort element.
VAppScopedVmId 1 1 xs:string Read‐only identifier created on import
VmNicId 1 1 xs:int The device number of the NIC on the referenced virtual machine.
InternalPort 1 1 xs:int The network port to which this NAT rule maps the port number specified in the ExternalPort element.
Protocol 1 1 Layer4ProtocolType Specifies the network protocol to which this rule applies
vCloud API Programming Guide
160 VMware, Inc.
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.
CatalogA 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
CatalogItems
The CatalogItems element is a read‐only container for individual CatalogItem elements.
CatalogItem
The CatalogItem element contains a reference to a media image or vApp template and optional related
metadata.
Content-Type application/vnd.vmware.vcloud.catalogItem+xml
Object href prototype API‐URL/catalogItem/id
Table 9-6. VmRule Protocol Element Values
Value Result
TCP The rule applies to the TCP protocol
UDP The rule applies to the UDP protocol
TCP_UDP The rule applies to the TCP and UDP protocols
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Link 0 n LinkType Links to actions and contained objects
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
CatalogItems 0 1 CatalogItemsType Read‐only container for CatalogItem elements.
IsPublished 0 1 xs:boolean Read‐only element, true if the catalog is published
Schema
Name Min Max Type Description
Entity 1 1 ReferenceType Reference to the catalogued object
Property 0 n PropertyType Expresses a key=value relationship. (In this release, the maximum number of these elements in a CatalogItem is limited to ten).
VMware, Inc. 161
Chapter 9 User API Reference
Property
Each CatalogItem can have up to ten Property elements, each of which expresses a key=value relationship.
The key is an attribute value, and the value is the content of the Property element itself. This element can be
used to hold arbitrary metadata attached to a CatalogItem. The vCloud API itself makes no use of this
information.
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>
MediaThe 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
VAppTemplateA VAppTemplate is an abstract description of a vApp. It is created when you upload an OVF package to a vDC.
Content-Type application/vnd.vmware.vcloud.vAppTemplate+xml
Object href prototype API‐URL/vAppTemplate/vAppTemplate‐id
Schema
Name Min Max Type Description
key 1 1 xs:string 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.
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
status 0 1 xs:int Creation status of the object
imageType 1 1 ImageType One of:
iso Specifies ISO‐9660 media type
floppy Specifies 3.5” floppy media type
size 1 1 xs:long Size of the media file in bytes
Description 0 1 xs:string Optional description
Files 0 1 FilesListType Read‐only container for File elements
Schema
Name Min Max Type Description
status 0 1 xs:int Creation status of the VAppTemplate.
name 1 1 xs:string Common object name attribute
vCloud API Programming Guide
162 VMware, Inc.
Children
The Children element is a read‐only container for the virtual machines (Vm elements) that are members of a
vApp or vAppTemplate.
VAppA 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
ovfDescriptorUploaded 0 1 xs:boolean True if the OVF descriptor for the template has been uploaded to the containing vDC.
any attribute name 0 n any Includes type, href, XML namespace identifiers
Link 0 n LinkType Links to actions and contained objects
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
Files 0 n FilesListType Files that are part of the template
Children 0 1 VAppChildrenType Read‐only container for Vm elements representing virtual machines
Section 0 n ovf:Section_Type Any of the following ovf:Section_Type elements:
LeaseSettingsSection
StartupSection
NetworkConfigSection
CustomizationSection
VAppScopedLocalId 0 1 xs:string Read‐only identifier created on import
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
deployed 0 1 xs:boolean True if the vApp is deployed
status 0 1 xs:int Creation status of the vApp
name 1 1 xs:string Common object name attribute
ovfDescriptorUploaded 0 1 xs:boolean True if the associated OVF descriptor has been uploaded
any attribute name 0 n any Includes type, href, XML namespace identifiers
Link 0 n LinkType Action links to vApp operations
Description 0 0 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
VAppParent 0 1 ReferenceType Unsupported in this release
VMware, Inc. 163
Chapter 9 User API Reference
VmA 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
SectionA VAppTemplate, VApp, and Vm can contain an arbitrary number of ovf:SectionType elements. In a vApp or Vm, some of these elements can be specified as instantiation parameters. The others are copied from the source
OVF Envelope and treated as read‐only by the vCloud API.
The following section types are allowed in a vApp or vAppTemplate:
LeaseSettingsSection
StartupSection
NetworkConfigSection
CustomizationSection
Section 0 n ovf:Section_Type Any of the following ovf:Section_Type elements:
LeaseSettingsSection
StartupSection
NetworkConfigSection
CustomizationSection
Children 0 n VAppChildrenType Read‐only container for Vm elements representing virtual machines
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
deployed 0 1 xs:boolean True if the Vm is deployed
status 0 1 xs:int Creation status of the Vm
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Link 0 n LinkType Action links to operations
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
VAppParent 0 1 ReferenceType Unsupported in this release
Section 0 n ovf:Section_Type Any of the following ovf:Section_Type elements:
VirtualHardwareSection
OperatingSystemSection
NetworkConnectionSection
GuestCustomizationSection
VAppScopedLocalId 0 1 xs:string Read‐only identifier created on import or composition
vCloud API Programming Guide
164 VMware, Inc.
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
StartupSection
In an OVF package or VApp that contains multiple virtual machines, the StartupSection specifies the order in which the virtual machines (VirtualSystems in an OVF VirtualSystemCollection or the VAppChildren of a VApp) are powered on.
Content-Type application/vnd.vmware.vcloud.startupSection+xml
CustomizationSection
The CustomizationSection element of a VApp contains information about how customization is to be
applied to the virtual machines in the vApp.
Content-Type application/vnd.vmware.vcloud.customizationSection+xml
Schema
Name Min Max Type Description
ovf:required 0 1 xs:boolean Optional indication of whether this element is required
type 0 1 xs:string Media type of this section
href 0 1 xs:anyURI URL to access this section
ovf:Info 1 1 ovf:Msg_Type
Required by the base ovf:Section_Type. It can contain xs:string information about the containing element, or can be empty
Link 0 n LinkType Configuration links
DeploymentLeaseInSeconds 0 1 xs:string Duration of the deployment lease, in seconds
StorageLeaseInSeconds 0 1 xs:string Duration of the storage lease, in seconds
DeploymentLeaseExpiration 0 1 xs:dateTime Date and time when the deployment lease expires
StorageLeaseExpiration 0 1 xs:dateTime Date and time when the storage lease expires
Schema
Name Min Max Type Description
ovf:required 0 1 xs:boolean Optional indication of whether this element is required
type 0 1 xs:string Media type of this section
href 0 1 xs:anyURI URL to access this section
ovf:Info 1 1 ovf:Msg_Type Required by the base ovf:Section_Type. It can contain xs:string information about the containing element, or can be empty
VMware, Inc. 165
Chapter 9 User API Reference
NetworkConfigSection
The NetworkConfigSection element specifies the configuration of a vApp network.
Content-Type application/vnd.vmware.vcloud.networkConfigSection+xml
NetworkConfig
The NetworkConfig element defines the configuration of a vApp network.
NetworkConnectionSection
The NetworkConnectionSection element specifies how a Vm is connected to a vApp network. It extends the
ovf:NetworkConnection element.
Content-Type application/vnd.vmware.vcloud.networkConnectionSection+xml
CustomizeOnInstantiate 1 1 xs:boolean If true, then customization is executed for all children that include a GuestCustomizationSection. Default value is false.
Link 0 n LinkType Configuration links
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
ovf:required 0 1 xs:boolean Optional indication of whether this element is required
type 0 1 xs:string Media type of this section
href 0 1 xs:anyURI URL to access this section
ovf:Info 1 1 ovf:Msg_Type Required by the base ovf:Section_Type. It can contain xs:string information about the containing element, or can be empty
Link 0 n LinkType Configuration links
NetworkConfig 0 n VAppNetworkConfigurationType Defines the configuration of a VApp network
Schema
Name Min Max Type Description
networkName 1 1 xs:string Name of the vApp Network
Description 0 1 xs:string Optional description of the network
Configuration 1 1 NetworkConfigurationType Properties of the network
IsDeployed 0 1 xs:boolean True if the network has been deployed (read‐only)
NOTE The OVF NetworkSection element and the vCloud API NetworkConnectionSection element
specify many of the same parameters for a network connection. If both are present in a Vm body, the values specified in the NetworkConnectionSection override those specified in the NetworkSection.
Schema
Name Min Max Type Description
ovf:required 0 1 xs:boolean Optional indication of whether this element is required
type 0 1 xs:string Media type of this section
vCloud API Programming Guide
166 VMware, Inc.
NetworkConnection
The NetworkConnection element describes a single network 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.
href 0 1 xs:anyURI URL to access this section
ovf:Info 1 1 ovf:Msg_Type Required by the base ovf:Section_Type. It can contain xs:string information about the containing element, or can be empty
PrimaryNetworkConnectionIndex 0 1 xs:int The value of the rasd:AddressOnParent element of the device (NIC) supporting the primary network connection to the containing virtual machine.
NetworkConnection 0 n NetworkConnectionType Describes a single network connection
Link 0 n LinkType Configuration links
Schema
Name Min Max Type Description
any attribute name 0 n any Includes type, href, XML namespace identifiers
network 1 1 xs:string The name of the network to which this connection connects.
NetworkConnectionIndex 1 1 xs:int The value in the rasd:AddressOnParent element of the device supporting this connection.
IpAddress 0 1 IpAddressType IP address of this connection
ExternalIpAddress 0 1 IpAddressType If the network that the NIC is connected to has NAT or port mapping, the external address is populated in this element.
IsConnected 1 1 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 0 1 xs:string MAC address of this connection
IpAddressAllocationMode 1 1 IpAddressAllocationModeType Specifies how an IP address is allocated to this connection
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
Schema (Continued)
Name Min Max Type Description
VMware, Inc. 167
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 Min Max Type Description
ovf:required 0 1 xs:boolean Optional indication of whether this element is required
type 0 1 xs:string Media type of this section
href 0 1 xs:anyURI URL to access this section
ovf:Info 1 1 ovf:Msg_Type Required by the base ovf:Section_Type. It can contain xs:string information about the containing element, or can be empty
Link 0 n LinkType Configuration links
Enabled 0 1 xs:boolean If true, to enable guest customization at power on
ChangeSid 0 1 xs:boolean If true, customization will run sysprep to change the Windows SID for this virtual machine
VirtualMachineId 0 1 xs:int Unique identifier for this virtual machine (read‐only)
JoinDomainEnabled 0 1 xs:boolean If true, this virtual machine can join a Windows domain
UseOrgSettings 0 1 xs:boolean If true, this virtual machine uses the containing organization’s default values for Windows domain name, domain user name, and domain user password
DomainName 0 1 xs:string If UseOrgSettings is false, specifies the Windows domain to join. Required if JoinDomainEnabled is true.
DomainUserName 0 1 xs:string If UseOrgSettings is false, specifies the Windows domain user name. Required if JoinDomainEnabled is true.
DomainUserPassword 0 1 xs:string If UseOrgSettings is false, specifies the Windows domain user’s password. Required if JoinDomainEnabled is true.
AdminPasswordEnabled 0 1 xs:boolean True if the administrator password should be reset.
AdminPasswordAuto 0 1 xs:boolean True if the local administrator password should be automatically generated
AdminPassword 0 1 xs:string Local administrator password for this virtual machine
ResetPasswordRequired 0 1 xs:boolean If true, the local administrator must reset his password on first use
CustomizationScript 0 1 xs:string This element contains the customization script to run
ComputerName 0 1 xs:string Name of this virtual machine in DNS or Windows domain
vCloud API Programming Guide
168 VMware, Inc.
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
ScreenTicketA 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
TasksListThe 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 Min Max Type Description
status 1 1 TaskStatusType The current status of the task. One of:
queued The task has been queued for execution.
running The task is running.
success The task has completed and returned a value indicating success.
error The task has completed and returned a value indicating an error.
operation 0 1 xs:string Description of the operation being tracked by the task
startTime 0 1 xs:dateTime Date and time when the task was started.
endTime 0 1 xs:dateTime Date and time when the task completed. Does not appear for running tasks.
expiryTime 0 1 xs:dateTime Date and time at which the task expires. By default, tasks expire 24 hours after their start time. Expired tasks cannot be queried.
href 0 1 xs:anyURI Link to the task
VMware, Inc. 169
Chapter 9 User API Reference
Owner 0 1 ReferenceType A link to the object that owns the task. For copy operations, the owner is the copy that is being created. For delete operations, the owner is the deleted object, so this element is not included. For all other operations, the owner is the object to which the request was made.
Error 0 1 ErrorType Error message or related information returned by the task
Schema (Continued)
Name Min Max Type Description
vCloud API Programming Guide
170 VMware, Inc.
VMware, Inc. 171
10
This chapter provides reference information about the request parameters defined in this release of the vCloud
API. Elements documented in this chapter provide parameters to requests that create, delete, modify, or
change the state of an object. For more information about how the vCloud API uses XML to represent objects,
and how this reference material is organized, see “XML Representations in the vCloud API” on page 141
This chapter provides reference material on the following elements and the elements they contain:
“UploadVAppTemplateParams” on page 171
“InstantiateVAppTemplateParams” on page 172
“InstantiationParams” on page 172
“ComposeVAppParams” on page 173
“RecomposeVAppParams” on page 174
“DeployVAppParams” on page 175
“UndeployVAppParams” on page 175
“CaptureVAppParams” on page 175
“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
UploadVAppTemplateParamsThe UploadVAppTemplateParams element forms the body of an uploadVappTemplate request.
Content-Type application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml
Request Parameters Reference 10
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name given to the template
Description 0 1 xs:string Description of the template
transferFormat 0 1 xs:string Ignored in this release
manifestRequired 0 1 xs:boolean True if the upload includes a manifest file
vCloud API Programming Guide
172 VMware, Inc.
InstantiateVAppTemplateParamsThe InstantiateVAppTemplateParams element forms the body of an instantiateVappTemplate request.
Content-Type application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml
InstantiationParamsThe InstantiationParams element contains zero or more ovf:Section_Type elements that specify the
configuration of a vApp or virtual machine.
An InstantiationParams element can appear in a number of request bodies, including
InstantiateVAppTemplateParams, ComposeVAppParams, RecomposeVAppParams, and CloneVAppParams. The container of the InstantiationParams element determines what section types it can contain.
InstantiationParams contained by an Item element that specifies a Vm as its Source can contain the following section types:
VirtualHardwareSection
OperatingSystemSection
NetworkConnectionSection
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the vApp created by this instantiation
linkedClone 0 1 xs:boolean Ignored in this release
deploy 0 1 xs:boolean True if the vApp should be deployed after instantiation. Defaults to false.
powerOn 0 1 xs:boolean True if the vApp should be deployed and powered on after instantiation. Defaults to false.
Description 0 1 xs:string Optional description. Used for the Description of the vApp created by this instantiation.
VAppParent 0 1 ReferenceType Unsupported in this release
Source 1 1 ReferenceType A reference to the vApp template to instantiate
IsSourceDelete 0 1 xs:boolean True if the object referenced by Source should be deleted after the copy is made
InstantiationParams 0 1 InstantiationParamsType Container for any of the following ovf:Section_Type elements:
LeaseSettingsSection
StartupSection
NetworkConfigSection
CustomizationSection
AllEULAsAccepted 0 1 xs:boolean True if you accept the terms and conditions in the template’s EULA sections. Instantiation fails if false.
Schema
Name Min Max Type Description
Section 0 n ovf:Section_Type Any permitted OVF Section type
VMware, Inc. 173
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
ComposeVAppParamsThe ComposeVAppParams element forms the body of a composeVapp request.
Content-Type application/vnd.vmware.vcloud.composeVAppParams+xml
Item
An Item element is a container for information about a vApp template, vApp, or virtual machine to be used
when composing or recomposing a vApp.
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the vApp created by this composition
Description 0 1 xs:string Optional description. Used for the Description of the composed vApp
deploy 0 1 xs:boolean True if the vApp should be deployed after composition. Defaults to false.
powerOn 0 1 xs:boolean True if the vApp should be deployed and powered on after composition. Defaults to false.
linkedClone 0 1 xs:boolean Ignored in this release.
VAppParent 0 1 ReferenceType Unsupported in this release.
InstantiationParams 0 1 InstantiationParamsType Container for any of the following ovf:Section_Type elements:
LeaseSettingsSection
StartupSection
NetworkConfigSection
CustomizationSection
Item 0 n CompositionItemParamsType Specifies a source vAppTemplate, vApp, or Vm to include in the composition
AllEULAsAccepted 0 1 xs:boolean True if you accept the terms and conditions in the template’s EULA sections. Composition fails if false.
Schema
Name Min Max Type Description
sourceDelete 0 1 xs:boolean If the object referenced in Source is a Vm, this attribute specifies whether the Vm should be removed from its parent vApp or copied. Ignored if the object referenced in Source is not a Vm.
Source 1 1 ReferenceType A reference to a vAppTemplate, vApp, or Vm to include in the composition
vCloud API Programming Guide
174 VMware, Inc.
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.
RecomposeVAppParamsThe 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
VAppScopedLocalId 0 1 xs:string If the object referenced in Source is a Vm, this element can be used to provide a unique identifier for this Vm in the composed vApp.
InstantiationParams 0 1 InstantiationParamsType Required if Source is a Vm, and can contain for any of the following ovf:Section_Type elements:
VirtualHardwareSection
OperatingSystemSection
NetworkConnectionSection
NetworkAssignment 0 n NetworkAssignmentType Maps logical networks in the Source to logical networks in the composed vApp
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
innerNetwork 1 1 xs:string Name of the network in the Vm
containerNetwork 1 1 xs:string Name of the vApp network to which innerNetwork is mapped
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the vApp created by this composition
Description 0 1 xs:string Optional description. Used for the Description of the composed vApp
deploy 0 1 xs:boolean True if the vApp should be deployed after composition. Defaults to false.
powerOn 0 1 xs:boolean True if the vApp should be deployed and powered on after composition. Defaults to false.
linkedClone 0 1 xs:boolean Ignored in this release.
VAppParent 0 1 ReferenceType Unsupported in this release
InstantiationParams 0 1 InstantiationParamsType container for any of the following ovf:Section_Type elements:
LeaseSettingsSection
StartupSection
NetworkConfigSection
CustomizationSection
VMware, Inc. 175
Chapter 10 Request Parameters Reference
DeployVAppParamsThe DeployVAppParams element forms the body of a deploy request.
Content-Type application/vnd.vmware.vcloud.deployVAppParams+xml
UndeployVAppParamsThe UndeployVAppParams element forms the body of an undeploy request.
Content-Type application/vnd.vmware.vcloud.undeployVAppParams+xml
CaptureVAppParamsThe CaptureVAppParams element forms the body of a captureVapp request.
Content-Type application/vnd.vmware.vcloud.captureVAppParams+xml
Item 0 n CompositionItemParamsType Specifies a source vAppTemplate, vApp, or Vm to include in the composition
DeleteItem 0 n ReferenceType Reference to a Vm to remove from the vApp
AllEULAsAccepted 0 1 xs:boolean True if you accept the terms and conditions in the template’s EULA sections. Composition fails if false.
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
powerOn 0 1 xs:boolean True if the vApp should be powered on after deployment
deploymentLeaseSeconds 0 1 xs:int Duration of the deployment lease, in seconds
Schema
Name Min Max Type Description
saveState 0 1 xs:boolean True if powered‐on children should be suspended and their state saved before undeployment. Default is false, specifying that children are powered off.
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the vAppTemplate created by this operation
Description 0 1 xs:string Optional description. Used for the Description of the vAppTemplate created by this operation.
Source 1 1 ReferenceType Reference to the vApp to capture.
vCloud API Programming Guide
176 VMware, Inc.
CloneMediaParamsThe CloneMediaParams element forms the body of a cloneMedia request.
Content-Type application/vnd.vmware.vcloud.cloneMediaParams+xml
CloneVAppTemplateParamsThe CloneVAppTemplateParams element forms the body of a cloneVAppTemplate request.
Content-Type application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml
CloneVAppParamsThe CloneVAppParams element forms the body of a cloneVapp request.
Content-Type application/vnd.vmware.vcloud.cloneVAppParams+xml
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the new media image created by the clone operation
Description 0 1 xs:string Optional description. Used for the Description of the cloned Media image.
Source 1 1 ReferenceType Reference to the media image to clone (copy)
IsSourceDelete 0 1 xs:boolean True if the object referenced by Source should be deleted after the copy is made
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the new vApp template created by the clone operation
Description 0 1 xs:string Optional description. Used for the Description of the cloned vApp template
Source 1 1 ReferenceType Reference to the vAppTemplate to clone (copy)
IsSourceDelete 0 1 xs:boolean True if the object referenced by Source should be deleted after the copy is made
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the cloned vApp
Description 0 1 xs:string Common Description element. Used for the Description of the clone
deploy 0 1 xs:boolean True if the clone should be deployed. Defaults to false.
powerOn 0 1 xs:boolean True if the clone should be deployed and powered on. Defaults to false.
linkedClone 0 1 xs:boolean Ignored in this release
VAppParent 0 1 ReferenceType Unsupported in this release
InstantiationParams 0 1 InstantiationParamsType Container for any of the following ovf:Section_Type elements:
LeaseSettingsSection
StartupSection
NetworkConfigSection
CustomizationSection
VMware, Inc. 177
Chapter 10 Request Parameters Reference
MediaInsertOrEjectParamsA MediaInsertOrEjectParams element forms the body of an insertMedia or ejectMedia request.
Content-Type application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml
VmPendingQuestionThe VmPendingQuestion element contains a request from a virtual machine for user input.
Content-Type application/vnd.vmware.vcloud.vmPendingQuestion+xml
VmQuestionAnswerThe VmQuestionAnswer element contains user input to a specific VmPendingQuestion request.
Content-Type application/vnd.vmware.vcloud.vmPendingAnswer+xml
ControlAccessParamsThe ControlAccessParams element appears in Catalogs and vApps. This element can be read by all users but
can be modified only by administrators and privileged users.
Content-Type application/vnd.vmware.vcloud.controlAccess+xml
Source 1 1 ReferenceType Reference to the vApp to clone (copy)
IsSourceDelete 0 1 xs:boolean True if the object referenced by Source should be deleted after the copy is made
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
Media 1 1 ReferenceType Reference to a media image to insert or eject
Schema
Name Min Max Type Description
Question 1 1 xs:string The question requiring use input.
QuestionId 1 1 xs:int Question identifier
Choices 1 n VmQuestionAnswerChoiceType Allowable answers
Schema
Name Min Max Type Description
ChoiceId 1 1 xs:int The answer to provide
QuestionId 1 1 xs:int Question identifier
Schema
Name Min Max Type Description
IsSharedToEveryone 1 1 xs:boolean True if this object is shared with everyone in the organization. Defaults to false.
EveryoneAccessLevel 0 1 AccessLevelType If IsSharedToEveryone is true, this element must be present and determines the access level
AccessSettings 0 1 AccessSettingsType A container for AccessSetting elements. This element must be present and not empty if IsSharedToEveryone is false.
vCloud API Programming Guide
178 VMware, Inc.
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.
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.
Schema
Name Min Max Type Description
Subject 1 1 ReferenceType Reference to the user or group to which the specified AccessLevel applies.
AccessLevel 1 1 AccessLevelType Specifies the access level allowed for the user or groups specified in Subject
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. 179
11
This chapter provides reference information about the XML elements that support administrative operations
in the vCloud API. Elements documented in this chapter are generally readable by all users, but can be created
and modified only by a system administrator, organization administrator or other privileged user. Many of
the schemas shown here extend elements and complex types that are defined in the user API. For more
information about how the vCloud API uses XML to represent objects, and how this reference material is
organized, see “XML Representations in the vCloud API” on page 141.
This chapter provides reference material on the following elements and the elements they contain:
“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
VCloudThe 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
Administrative API Reference 11
Schema
Name Min Max Type Description
OrganizationReferences 0 1 OrganizationReferencesType A container for references to AdminOrg objects in the vCloud
ProviderVdcReferences 0 1 ProviderVdcReferencesType A container for references to ProviderVdc objects in the vCloud
RightReferences 0 1 RightReferencesType A container for references to Right objects in the vCloud
RoleReferences 0 1 RoleReferencesType A container for references to Role objects in the vCloud
Networks 0 1 NetworksType A container for references to ExternalNetwork objects in the vCloud.
vCloud API Programming Guide
180 VMware, Inc.
OrganizationReferences
The OrganizationReferences element is a read‐only container for ReferenceType elements that reference
AdminOrg objects a vCloud. To create a new organization, see “Create an Organization” on page 95.
ProviderVdcReferences
The ProviderVdcReferences element is a read‐only container for ReferenceType elements that reference
ProviderVdc objects a vCloud. To create a ProviderVdc, see “Create a Provider vDC” on page 127.
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.
ExternalNetworkA 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
AdminOrgThe AdminOrg element provides an administrative view of an organization. It includes all members of the Org element, and adds several elements that can be viewed and modified only by system administrators.
Content-Type application/vnd.vmware.admin.organization+xml
Object href prototype API‐URL/admin/organization/id
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Description 0 1 xs:string Optional description
Configuration 0 1 NetworkConfigurationType Properties of the network
ProviderInfo 1 1 xs:string Read‐only information about the underlying vCenter network
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
VMware, Inc. 181
Chapter 11 Administrative API Reference
Settings
The Settings element establishes quotas and policies for the organization. It also contains elements that
specify the details of how the organization connects to LDAP and email services.
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
FullName 1 1 xs:string Full name of the organization
Settings 1 1 OrgSettingsType Establishes quotas and policies, specifies how the organization connects to LDAP and email services
Users 0 1 UsersListType Container for ReferenceType elements that reference users in the organization.
Groups 0 1 GroupsListType Container for ReferenceType elements that reference groups in the organization.
Catalogs 0 1 CatalogsListType Container for ReferenceType elements that reference catalogs in the organization.
Vdcs 0 1 VdcsType Container for ReferenceType elements that reference vDCs in the organization.
Networks 0 1 NetworksType Container for ReferenceType elements that reference networks in the organization.
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
IsEnabled 0 1 xs:boolean True if this organization is enabled. If enabled, the organization allows login and all other operations.
CanPublishCatalogs 0 1 xs:boolean True if this organization is allowed to publish catalogs
DeployedVmQuota 0 1 xs:int Maximum number of virtual machines that can be deployed simultaneously by a member of this organization
StoredVmQuota 0 1 xs:int Maximum number of vApps or vApp templates that can be stored (in an undeployed state) by a member of this organization
OrgLeaseSettings 0 1 OrgLeaseSettingsType Defines default lease durations and related policies
OrgLdapMode 0 1 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 0 1 xs:string If OrgLdapMode is SYSTEM, specifies an LDAP attribute=value pair to use for OU (organizational unit)
OrgLdapSettings 0 1 OrgLdapSettingsType Defines the hostname and connection details for the organization’s primary LDAP service
OrgEmailSettings 0 1 OrgEmailSettingsType Defines the email settings for this organization
vCloud API Programming Guide
182 VMware, Inc.
OrgLeaseSettings
The OrgLeaseSettings element defines default lease durations and policies for the organization.
OrgLdapMode
The OrgLdapMode element defines whether this organization is connected to an LDAP service, and whether it
uses the system default LDAP service or a custom LDAP service. Table 11‐1 shows permitted values for
element content and the results they produce.
OrgLdapSettings
If OrgLdapMode is CUSTOM, the OrgLdapSettings element defines the hostname and connection details for the
organization’s LDAP service.
UseServerBootSequence 0 1 xs:boolean True if virtual machines in this organization use the server boot sequence by default
DelayAfterPowerOnSeconds 0 1 xs:int Specifies an organization default for virtual machine boot delay after power‐on
Schema
Name Min Max Type Description
DeleteOnStorageLeaseExpiration 0 1 xs:boolean If true, storage for a vApp is deleted when the vApp’s lease expires. If false, the storage is flagged for deletion, but not deleted.
DeploymentLeaseSeconds 0 1 xs:int Default duration of a vApp deployment lease, in seconds.
StorageLeaseSeconds 0 1 xs:int Default duration of a storage lease, in seconds.
NOTE The value of OrgLdapMode cannot be changed after the organization has been created.
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
Schema
Name Min Max Type Description
HostName 1 1 xs:string Hostname of the LDAP server.
Port 1 1 xs:int Port at which to connect to the LDAP service
IsSsl 0 1 xs:boolean True if the LDAP service requires an SSL connection
IsSslAcceptAll 0 1 xs:boolean True if the LDAP service accepts all SSL certificates
Realm 0 1 xs:string LDAP realm to use when looking up users
SearchBase 0 1 xs:string LDAP search base
Schema (Continued)
Name Min Max Type Description
VMware, Inc. 183
Chapter 11 Administrative API Reference
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.
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.
UserName 0 1 xs:string Username to use when logging in to LDAP, specified using LDAP attribute=value pairs (for example: cn="ldap-admin", dc="example", dc="com")
Password 0 1 xs:string Password for the user identified by UserName. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.
AuthenticationMechanism 1 1 LdapAuthenticationMechanismType
Defines the authentication mechanism used by the LDAP service
GroupSearchBase 0 1 xs:string LDAP group search base
IsGroupSearchBaseEnabled 1 1 xs:boolean True if the group search base is enabled
ConnectorType 1 1 LdapConnectorType Defines the type of the LDAP service
UserAttributes 1 1 OrgLdapUserAttributesType Defines how LDAP attributes are used when importing a user
GroupAttributes 1 1 OrgLdapGroupAttributesType Defines how LDAP attributes are used when importing a group
Table 11-2. AuthenticationMechanism Element Values
Value Result
SIMPLE LDAP connection uses simple authentication as specified in RFC 2251 and RFC 2829.
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.
Table 11-3. ConnectorType Element Values
Value Result
ACTIVE_DIRECTORY LDAP service is provided by Windows Active Directory
OPEN_LDAP LDAP service is provided by OpenLDAP (see http://www.openldap.org).
Schema (Continued)
Name Min Max Type Description
vCloud API Programming Guide
184 VMware, Inc.
UserAttributes
If OrgLdapMode is CUSTOM, the UserAttributes element defines how LDAP attributes are used when
importing a user.
GroupAttributes
If OrgLdapMode is CUSTOM, the GroupAttributes element defines how a group is imported from LDAP.
Schema
Name Min Max Type Description
ObjectClass 1 1 xs:string LDAP objectClass of which imported users are members. For example, user or person
ObjectIdentifier 1 1 xs:string LDAP attribute to use as the unique identifier for a user. For example, objectGuid
UserName 1 1 xs:string LDAP attribute to use when looking up a user name to import. For example, userPrincipalName or samAccountName
Email 1 1 xs:string LDAP attribute to use for the user’s email address. For example mail
FullName 1 1 xs:string LDAP attribute to use for the user’s full name. For example displayName
GivenName 1 1 xs:string LDAP attribute to use for the user’s given name. For example, givenName
Surname 1 1 xs:string LDAP attribute to use for the user’s surname. For example sn
Telephone 1 1 xs:string LDAP attribute to use for the user’s telephone number. For example telephoneNumber
GroupMembershipIdentifier 1 1 xs:string LDAP attribute that identifies a user as a member of a group. For example, dn
GroupBackLink 0 1 xs:string LDAP attribute that returns the identifiers of all the groups of which the user is a member
Schema
Name Min Max Type Description
ObjectClass 1 1 xs:string LDAP objectClass of which imported groups are members. For example, group
ObjectIdentifier 1 1 xs:string LDAP attribute to use as the unique identifier for a group. For example, objectGuid
GroupName 1 1 xs:string LDAP attribute to use for the group name. For example, cn
Membership 1 1 xs:string LDAP attribute to use when getting the members of a group. For example, member
MembershipIdentifier 1 1 xs:string LDAP attribute that identifies a group as a member of another group. For example, dn
BackLinkIdentifier 0 1 xs:string LDAP group attribute used to identify a group member
VMware, Inc. 185
Chapter 11 Administrative API Reference
OrgEmailSettings
The OrgEmailSettings element defines the email settings for an organization.
SmtpServerSettings
If IsDefaultSmtpServer (in OrgEmailSettings) is false, the SmtpServerSettings element specifies
connection details for the organization’s SMTP server.
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.
Schema
Name Min Max Type Description
IsDefaultSmtpServer 1 1 xs:boolean True if this organization uses the system default SMTP server
IsDefaultOrgEmail 1 1 xs:boolean True if this organization uses the system default email properties.
FromEmailAddress 1 1 xs:string If IsDefaultOrgEmail is false, specifies the sender’s email address that appears in email notifications.
DefaultSubjectPrefix 1 1 xs:string If IsDefaultOrgEmail is false, specifies a prefix for system email notifications.
IsAlertEmailToAllAdmins 1 1 xs:boolean True if system email notifications should be sent to all users who have the Administrator role
AlertEmailTo 0 n xs:string If IsAlertEmailToAllAdmins is false, specifies a list of users to receive system email notifications.
SmtpServerSettings 0 1 SmtpServerSettingsType If IsDefaultSmtpServer is False, this element specifies connection details for an SMTP server to use.
Schema
Name Min Max Type Description
IsUseAuthentication 1 1 xs:boolean True if the SMTP server requires authentication
Host 1 1 xs:string Hostname of the SMTP server.
Username 1 1 xs:string Username to use when logging in to the SMTP service. (Required if IsUseAuthentication is True).
Password 0 1 xs:string Password for the user identified by Username. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed. Required if IsUseAuthentication is true.
vCloud API Programming Guide
186 VMware, Inc.
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.
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.
ProviderVdcA ProviderVdc element represents a provider vDC object.
Content-Type application/vnd.vmware.admin.providervdc+xml
Object href prototype API‐URL/admin/providervdc/id
Schema
Name Min Max Type Description
IsPublished 1 1 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.
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
status 0 1 xs:int creation status of the ProviderVdc:
-1 Creation failed
0 Not ready
1 Ready
2 Unknown
3 Unrecognized
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object
ComputeCapacity 0 1 RootComputeCapacityType Defines the compute capacity available in this provider vDC
StorageCapacity 0 1 ProviderVdcCapacityType Defines the storage capacity available in this provider vDC
AvailableNetworks 0 1 AvailableNetworksType Container for references to ExternalNetwork objects provisioned from this provider vDC.
VMware, Inc. 187
Chapter 11 Administrative API Reference
ComputeCapacity
The administrative view of a ComputeCapacity element includes two elements: IsElastic and IsHa, that an administrator can change. These elements are not visible in the user view.
Cpu
Unlike the Cpu element that appears in the ComputeCapacity of a Vdc, the Cpu element that appears in the
ComputeCapacity of a ProviderVdc is an instance of ProviderVdcCapacityType. It defines the CPU capacity that can be allocated from a vDC and optionally reports how much of that capacity is in use.
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.
Vdcs 0 1 VdcsType Container for Vdc objects that are provisioned from this provider vDC.
IsEnabled 0 1 xs:boolean True if this provider vDC is enabled
NetworkPoolReferences 0 1 NetworkPoolReferencesType Container for NetworkPoolReference objects that are provisioned from this provider vDC
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
Cpu 1 1 ProviderVdcCapacityType Defines CPU capacity available in the provider vDC
Memory 1 1 ProviderVdcCapacityType Defines memory capacity available in the provider vDC
IsElastic 0 1 xs:boolean True if compute capacity can grow or shrink based on demand
IsHA 0 1 xs:boolean True if compute capacity is highly available.
Schema
Name Min Max Type Description
Units 1 1 xs:string Units in which the capacity is measured. For CPU devices, this is always Megahertz, represented by the string MHz.
Allocation 0 1 xs:long Number of Units that have been allocated to consumers
Total 1 1 xs:long Maximum number of Units that can be allocated to all consumers
Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only, and is always 0 if AllocationModel is AllocationVApp.
Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this vDC. This value is read‐only, and is always 0 if AllocationModel is AllocationVApp.
Schema
Name Min Max Type Description
Units 1 1 xs:string Specifies the units in which the capacity is measured. For storage devices, this is always Megabytes, represented by the string MB.
Allocation 0 1 xs:long Number of Units that have been allocated to consumers. This value is read‐only, and is always 0 if AllocationModel is AllocationVApp.
Total 1 1 xs:long Maximum number of Units that can be allocated to all consumers. This value is read‐only, and is always 0 if AllocationModel is AllocationVApp.
vCloud API Programming Guide
188 VMware, Inc.
StorageCapacity
The administrative view of aStorageCapacity defines the amount of storage available in a ProvidervDC and
optionally reports how much of that capacity is in use.
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
AdminVdcThe 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
Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only.
Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this vDC. This value is read‐only.
Schema
Name Min Max Type Description
Schema
Name Min Max Type Description
Units 1 1 xs:string Units in which the capacity is measured. For CPU devices, this is always Megahertz, represented by the string MHz.
Allocation 0 1 xs:long Number of Units that have been allocated to consumers
Total 1 1 xs:long Total number of Units that can be allocated to all consumers
Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only.
Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this provider vDC. This value is read‐only.
Schema
Name Min Max Type Description
any attribute name 0 n any Includes type, href, XML namespace identifiers
Link 0 n LinkType Link to containing provider vDC
VdcReference 0 n ReferenceType Reference to an organization vDCs supported by this provider vDC
VMware, Inc. 189
Chapter 11 Administrative API Reference
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
status 0 1 xs:int The creation status of the vDC:
-1 creation failed
0 not ready
1 ready
2 unknown
3 unrecognized status
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
AllocationModel 1 1 AllocationModelType Defines how resources are allocated by the vDC
StorageCapacity 1 1 StorageCapacityType Defines the storage capacity available in the vDC
ComputeCapacity 1 1 ComputeCapacityType Defines the compute capacity available in the vDC
ResourceEntities 0 1 ResourceEntitiesType Container for ResourceEntity elements
AvailableNetworks 0 1 AvailableNetworksType Container for Network elements that reference OrgNetwork objects contained by the vDC
NicQuota 1 1 xs:int Maximum number of virtual NICs allowed in this vDC. Defaults to 0, which specifies an unlimited number.
NetworkQuota 1 1 xs:int Maximum number of OrgNetwork objects that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number.
VmQuota 0 1 xs:int Maximum number of virtual machines that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number.
IsEnabled 0 1 xs:boolean True if this vDC is enabled
ResourceGuaranteedMemory 0 1 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 0 1 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.
vCloud API Programming Guide
190 VMware, Inc.
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.
UserA 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
VCpuRatingMHz 0 1 xs:long Specifies a clock frequency, in Megahertz, for each virtual CPU core provisioned from this vDC
IsThinProvision 0 1 xs:boolean True if thin provisioning has been enabled for this vDC
NetworkPoolReference 0 1 ReferenceType Reference to a network pool in the provider vDC referenced by ProviderVdcReference
ProviderVdcReference 0 1 ReferenceType Reference to the ProviderVdc from which this vDC is provisioned
Schema (Continued)
Name Min Max Type Description
Table 11-4. AllocationModel Element Values
Value Result
AllocationVApp Resources are committed to a vDC only when vApps are created in it
AllocationPool Only a percentage of the resources you allocate are committed to the organization vDC.
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.
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute. The name of the user.
any attribute name 0 n any Includes type, href, XML namespace identifiers
Description 0 1 xs:string Optional description
FullName 0 1 xs:string User’s full name.
EmailAddress 0 1 xs:string User’s email address
Telephone 0 1 xs:string User’s telephone number
IsEnabled 0 1 xs:boolean True if the user can log in
IM 0 1 xs:string User’s instant messaging address
NameInSource 0 1 xs:string User name as retrieved from, and in the encoding used by, LDAP
IsAlertEnabled 0 1 xs:boolean True if alerts are enabled for the user
AlertEmailPrefix 0 1 xs:string String to prepend to alert message Subject line
AlertEmail 0 1 xs:string Alert email address
isExternal 0 1 xs:boolean True if this user was imported from LDAP
IsDefaultCached 0 1 xs:boolean True if this user is cached
IsGroupRole 0 1 xs:boolean True if this user has a group role
VMware, Inc. 191
Chapter 11 Administrative API Reference
GroupA Group object defines a group.
Content-Type application/vnd.vmware.admin.group+xml
Object href prototype API‐URL/admin/group/id
RoleThe Role element contains a single RightReferences element, which is a container for RightReference elements.
Content-Type application/vnd.vmware.admin.role+xml
Object href prototype API‐URL/admin/role/id
RightReferences
The RightReferences element is a container for zero or more RightReference elements.
RightReference
The RightReference element contains a reference to a Right.
StoredVmQuota 0 1 xs:int Quota of vApps that this user can store. A value of 0 specifies an unlimited quota.
DeployedVmQuota 0 1 xs:int Quota of vApps that this user can deploy concurrently. A value of 0 specifies an unlimited quota
Role 0 1 ReferenceType A reference to the user’s role. When you are creating a User, the request body must contain exactly one Role element.
Password 0 1 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 0 1 GroupsListType Container for ReferenceType elements that reference groups of which this user is a member
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute. The Group’s name.
any attribute name 0 n any Includes type, href, XML namespace identifiers
Description 0 1 xs:string Optional description
NameInSource 0 1 xs:string Group name as retrieved from, and in the encoding used by, LDAP
UsersList 0 1 UsersListType A list of references to users in the group
Role 0 1 ReferenceType Reference to the group’s role.
Schema
Name Min Max Type Description
Right 1 1 ReferenceType A reference to a right defined in the vCloud.
vCloud API Programming Guide
192 VMware, Inc.
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 Min Max Type Description
name 1 1 xs:string Name of the right
Description 0 1 xs:string Optional description of the right.
Category 1 1 xs:string Optional category name
VMware, Inc. 193
12
This chapter provides reference information about the elements defined in the vSphere Platform extensions to
this release of the vCloud API. Elements documented in this chapter can be created and modified only by a
system administrator. For more information about how the vCloud API uses XML to represent objects, and
how this reference material is organized, see “XML Representations in the vCloud API” on page 141.
This chapter provides reference material on the following elements and the elements they contain:
“VMWExtension” on page 193
“VimServer” on page 194
“VmObjectRefsList” on page 195
“ResourcePoolList” on page 196
“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
VMWExtensionThe 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
vSphere Platform Extensions Reference 12
Schema
Name Min Max Type Description
href 1 1 xs:anyURI Object reference
type 0 1 xs:string Media type of the element (application/vnd.vmware.admin.vmwExtension+xml)
any attribute name 0 n any Includes XML Namespace Identifiers.
Link 0 n LinkType Links to actions and contained objects.
vCloud API Programming Guide
194 VMware, Inc.
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
VimServerA VimServer object represents a vCenter server.
Content-Type application/vnd.vmware.admin.vmwvirtualcenter+xml
Object href prototype API‐URL/admin/extension/vimServer/id
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML Namespace Identifiers
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.
Username 1 1 xs:string User name of the administrator of this vCenter server
VMware, Inc. 195
Chapter 12 vSphere Platform Extensions Reference
VmObjectRefsListThe 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.
VimObjectType
The VimObjectType element defines the type of a Virtual Infrastructure Management object. Table 12‐1 shows
permitted values for element content. These values are read‐only.
Password 0 1 xs:string Password for the user identified by Username. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.
Url 1 1 xs:anyURI URL, including port, to use when connecting to this vCenter server with a vSphere client
IsEnabled 1 1 xs:boolean True if the server is enabled for use with Cloud Director
IsConnected 0 1 xs:boolean True if this vCenter is ready to be used by the vCloud
ShieldManagerIP 0 1 xs:anyURI IP address of the associated vShield Manager
ShieldManagerUserName 0 1 xs:string User name of vShield Manager administrator
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
VimServerRef 1 1 ReferenceType Reference to the server hosting this object
MoRef 1 1 xs:string Managed object ID of this object
VimObjectType 1 1 VimObjectTypeEnum Type of this object
Table 12-1. VimObjectType Element Values
Value Object Type
RESOURCE_POOL The object is a resource pool.
DATASTORE The object is a vSphere datastore.
HOST The object is an ESX host.
VIRTUAL_MACHINE The object is a virtual machine.
VIRTUAL_APP The object is a vApp.
NETWORK The object is an external network.
DV_PORTGROUP The object is a distributed virtual portgroup
DV_SWITCH The object is a distributed virtual switch.
vCloud API Programming Guide
196 VMware, Inc.
ResourcePoolListThe 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.
ShieldManagerThe 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 Min Max Type Description
MoRef 1 1 xs:string Managed object ID of this object
VimObjectType 1 1 VimObjectTypeEnum Type of this object
DataStoreRefs 0 1 VimObjectRefsType Read‐only container for references to datastores in this resource pool
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML Namespace Identifiers
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or recently completed Task owned by this organization.
Username 1 1 xs:string User name of the administrator of this vShield Manager server
Password 0 1 xs:string Password for the user identified by Username. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.
Url 1 1 xs:anyURI URL, including port, to use when connecting to this vShield Manager server with a vSphere client
AssociatedVimServer 0 1 ReferenceType Reference to the vCenter server associated with this vShield Manager server
VMware, Inc. 197
Chapter 12 vSphere Platform Extensions Reference
VMWProviderVdcA 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 Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML Namespace Identifiers
status 0 1 xs:int The creation status of the ProviderVdc:
‐1 – Creation failed
0 – Not ready
1 – Ready
2 – Unknown
3 – Unrecognized
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or recently completed Task owned by this organization.
ComputeCapacity 0 1 RootComputeCapacityType Defines the compute capacity available in this provider vDC
StorageCapacity 0 1 ProviderVdcCapacityType Defines the storage capacity available in this provider vDC
AvailableNetworks 0 1 AvailableNetworksType Read‐only container for Network elements that reference external networks contained by the provider vDC
Vdcs 0 1 VdcsType Read‐only container for references to Vdc objects that are provisioned from this provider vDC.
IsEnabled 0 1 xs:boolean True if this provider vDC is enabled
NetworkPoolReferences 0 1 NetworkPoolReferencesType Container for NetworkPoolReference elements
DataStoreRefs 1 1 VimObjectRefsType Container for VimObjectRef elements of type DATASTORE
ResourcePoolRef 1 1 VimObjectRefType Reference to the resource pool backing this provider vDC (VimObjectRef element of type RESOURCE_POOL)
VimServer 1 1 ReferenceType Reference to the vCenter server hosting the datastores contained in DataStoreRefs and the resource pool contained in ResourcePoolRef
HostReferences 0 1 HostsType Read‐only container for Host objects
vCloud API Programming Guide
198 VMware, Inc.
VMWNetworkPoolThe 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
PortGroupPoolType
A VMWNetworkPool of the PortGroupPoolType represents a network pool backed by one or more vSphere
port groups.
Content-Type application/vnd.vmware.admin.portGroupPool+xml
VlanPoolType
A VMWNetworkPool of the VlanPoolType represents a network pool backed by one or more vSphere VLANs.
Content-Type application/vnd.vmware.admin.vlanPool+xml
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Description 0 1 xs:string Optional description
FenceIdCount 1 1 xs:int Number of fence IDs in this pool
VlanId 1 1 xs:int Set to 0 for no VLAN
VimSwitchRef 1 1 VimObjectRefType Reference to the switch that supports this VLAN
UsedNetworksCount 0 1 xs:int Read‐only indication of how many networks in this pool are in use
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Description 0 1 xs:string Optional description
PortGroupRefs 1 1 VimObjectRefsType References to the portgroups that support this VLAN
VimServer 1 1 ReferenceType Reference to the server hosting this object
UsedNetworksCount 0 1 xs:int Read‐only indication of how many networks in this pool are in use
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Description 0 1 xs:string Optional description
VlanRange 1 n NumericRangeType Defines a range of VLAN IDs
VMware, Inc. 199
Chapter 12 vSphere Platform Extensions Reference
VMWExternalNetworkThe VMWExternalNetwork element defines an external network.
Content-Type application/vnd.vmware.vcloud.admin.network+xml
Object href prototype API‐URL/admin/extension/externalnet/id
VlanRange
The VlanpRange element defines a range of VLAN IDs.
VMWHostReferencesThe VMWHostReferences element is a read‐only container for Host elements representing the hosts in a
specific provider vDC.
Host
A Host object represents an ESX/ESXi host in a provider vDC.
Content-Type application/vnd.vmware.admin.+xml
Object href prototype API‐URL/admin/extension/host/id
VimSwitchRef 1 1 VimObjectRefType Reference to the switch that supports this VLAN
UsedNetworksCount 0 1 xs:int Read‐only indication of how many networks in this pool are in use
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML namespace identifiers
Description 0 1 xs:string Optional description
Configuration 0 1 NetworkConfigurationType Properties of the network
VimPortGroupRef 1 1 VimObjectRefType Reference to the portgroup that supports this network
Schema
Name Min Max Type Description
Start 1 1 xs:int Lowest VLAN ID in the range
End 1 1 xs:int Highest VLAN ID in the range
Schema
Name Min Max Type Description
name 1 1 xs:string Common object name attribute
any attribute name 0 n any Includes type, href, XML Namespace Identifiers.
Description 0 1 xs:string Optional description
Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed Task owned by this object.
Link 0 n LinkType Links to contained objects.
vCloud API Programming Guide
200 VMware, Inc.
Request ParametersThe 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.
RegisterVimServerParams
The RegisterVimServerParams element forms the body of a registervimserver request.
Ready 1 1 xs:boolean True if the host is ready
Available 1 1 xs:boolean True if the host is available
Enabled 1 1 xs:boolean True if the host is enabled for use with Cloud Director
Busy 1 1 xs:boolean True if the host is busy
EnableHostForHostSpanning 1 1 xs:boolean True if the host is enabled for host spanning. If true, the host cannot be put in standby or maintenance mode.
CpuType 0 1 xs:string CPU type of the host
NumOfCpusLogical 1 1 xs:int Number of logical CPUs
NumOfCpusPackages 1 1 xs:int Number of CPU packages
CpuTotal 1 1 xs:long Total CPU capability of this host
MemUsed 1 1 xs:double Memory reserved
MemTotal 1 1 xs:double Total memory
HostOsName 0 1 xs:string Host operating system name
HostOsVersion 0 1 xs:string Host operating system version
SystemMessages 0 1 xs:string vCenter messages for this host
VimPropertyPageUrl 0 1 xs:string URL for host property page in vSphere
VmMoRef 0 1 xs:string vSphere managed object reference for this object
Schema (Continued)
Name Min Max Type Description
Schema
Name Min Max Type Description
Username 1 1 xs:string User name of a host administrator
Password 1 1 xs:string Password for specified Username
Schema
Name Min Max Type Description
VimServer 1 1 VimServerType vCenter server to register
ShieldManager 1 1 ShieldManagerType vShield Manager associated with the vCenter server to register
VMware, Inc. 201
Chapter 12 vSphere Platform Extensions Reference
ImportVmAsVAppParams
The ImportVmAsVAppParams element forms the body of an importVmAsVApp request.
ImportVmAsVAppTemplateParams
The ImportVmAsVAppTemplateParams element forms the body of an importVmAsVAppTemplate request.
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the vApp created by this operation
sourceMove 0 1 xs:boolean True if the imported VM should be removed from the source vCenter
deploy 0 1 xs:boolean Not supported in this release
powerOn 0 1 xs:boolean Not supported in this release
Description 0 1 xs:string Optional description
InstantiationParams 0 1 InstantiationParamsType Container for any of the following ovf:Section_Type elements:
LeaseSettingsSection
StartupSection
NetworkConfigSection
CustomizationSection
VmName 0 1 xs:string Virtual machine name
VAppScopedLocalId 0 1 xs:string Read‐only identifier created on import
ComputerName 0 1 xs:string Display name of this virtual machine
VmMoRef 1 1 xs:string Managed object reference of the VM to import
Vdc 1 1 ReferenceType URL of the target vDC
Schema
Name Min Max Type Description
name 1 1 xs:string Specifies the name of the vApp created by this operation
sourceMove 0 1 xs:boolean True if the imported VM should be removed from the source vCenter
Description 0 1 xs:string Optional description
VmMoRef 1 1 xs:string Managed object reference of the VM to import
Vdc 1 1 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 0 1 xs:string Virtual machine name
VAppScopedLocalId 0 1 xs:string Read‐only identifier created on import
ComputerName 0 1 xs:string Display name of this virtual machine
vCloud API Programming Guide
202 VMware, Inc.
VMware, Inc. 203
A
The Open Virtualization Format (OVF) is an open, portable, efficient and extensible format for packaging and
distributing virtual systems. OVF was developed by the Distributed Management Task Force (DMTF), a
not‐for‐profit association of industry members dedicated to promoting enterprise and systems management
and interoperability. For more information about the DMTF and OVF, visit http://www.dmtf.org.
The vCloud API supports Version 1 of the OVF standard. In particular, it supports uploading and
downloading vApp templates as OVF packages. In addition, vApp, Vm, and vAppTemplate elements
incorporate a number of ovf:Section_Type elements in their definitions of virtual machines (see “Section”
on page 163 for details on how these sections are used).
This appendix includes the following topics:
“About OVF” on page 203
“How the vCloud API Uses OVF” on page 204
About OVFBecause 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.
OVF and the vCloud API A
NOTE 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.
vCloud API Programming Guide
204 VMware, Inc.
A virtual application or virtual machine is typically made up of one or more virtual disk files that contain the
operating system and applications that run on the virtual machine, and a configuration file containing
metadata that describe how the virtual machine is configured and deployed. An OVF package includes these
components, as well as optional certificate and manifest files. The package can be distributed and stored as a
collection of individual files, or as a single archive (OVA) file.
About OVF Packages
An OVF package includes four kinds of files:
An OVF descriptor, an XML file that contains metadata that describe a virtual machine or collection of
related virtual machines and the deployment environment they require. By convention, this file has the
suffix .ovf.
Virtual disk files. The descriptor lists these files and includes information about their format.
An optional certification file, which can be used to certify the authenticity of the package.
An optional manifest file, which contains a SHA‐1 digest of each of the files in the package.
About OVA Files
An OVA file collects all the files in an OVF package into a single archive. By convention, this file has the
suffix .ova. This release of the vCloud API does not support upload or download of OVA files.
How the vCloud API Uses OVFThe 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. 205
Appendix A OVF and the vCloud API
Virtual Disk Files
Virtual disk file information extracted from the References section of the OVF package is used to populate the Files element of the VAppTemplate. An OVF package can include exactly one References section. It lists all the files required by all the VirtualSystems defined in the package, including virtual disks and locale‐specific resource files. Virtual disk files are enumerated again in the DiskSection element of the
package, one file per Disk element. Disk elements include additional information about the capacity and
format of each disk. (Disk elements can also specify empty virtual disk, in which case they are not associated
with a virtual disk file.)
Example A‐1 shows how a virtual disk reference appears in an Envelope. (In this example, attributes and
other elements in the Envelope have been omitted for clarity.) The href value of the File element in the
References section specifies the file pathname relative to the location of the OVF descriptor file in which the
Envelope appears. (In this case, the disk file, SimpleVM-disk1.vmdk, is in the same folder as the OVF
descriptor.) The Disk element is then associated with a virtual machine, as a HostResource of a VirtualSystem, referenced by its ovf:diskId attribute value.
Example A-1. Virtual Disks in an OVF Envelope
<Envelope ......<References>
<File ovf:href="SimpleVM-disk1.vmdk" ovf:id="file1" ovf:size="68096"/></References>...<DiskSection>
<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#streamOptimized"/>
</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.
vCloud API Programming Guide
206 VMware, Inc.
The vCloud API NetworkConnectionSection is a read‐only section that lists the network connections
and IP addresses that a vApp has acquired or been assigned at deployment. This section is present only
in a deployed vApp that has a network connection.
The OVF Item element, one of many that apply to the Envelope’s VirtualHardwareSection, specifies that the virtual machine’s NIC (resource type 10) is connected to Internet. It also specifies many other
details about the device. For more information about DMTF resource types, visit http://www.dmtf.org.
Example A-2. Network Information in an OVF Envelope
<Envelope ......<NetworkSection>
<ovf:Info>The list of logical networks</ovf:Info><Network ovf:name="Internet"/>
</NetworkSection><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. 207
B
REST, an acronym for Representational State Transfer, is a term that has been widely employed to describe an
architectural style characteristic of programs that rely on the inherent properties of hypermedia to create and
modify the state of an object that is accessible at a URL.
This appendix includes the following topics:
“How REST Works” on page 207
“Using the vCloud REST API” on page 207
“For More Information About REST” on page 208
How REST WorksIf 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 APIA “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
An Introduction to REST for vCloud API Users B
vCloud API Programming Guide
208 VMware, Inc.
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 RESTFor 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. 209
Index
AAccessLevel element
example of use 57
schema reference 178
AccessSetting element
example of use 56, 57
schema reference 178
AccessSettings element
example of use 56
schema reference 178
AdminVdc element
example of use 104
AllEULAsAccepted
description 172
AllEULAsAccepted element
example of use 63, 65
authentication
about 18
example request 21
AvailableNetworks element
example of use 103, 104, 129
schema reference 153
CCaptureVAppParams element
example of use 68
schema reference 175
Catalog element
example of use 35
schema reference 160
CatalogItem element
example of use 36
schema reference 160
CatalogItems element
schema reference 160
Catalogs
about 14
controlling access to 56
CloneMediaParams element
example of use 51
schema reference 176
CloneVAppParams element
example of use 52
schema reference 176
CloneVAppTemplateParams element
example of use 51
schema reference 176
ComposeVAppParams element
example of use 65
schema reference 173
Configuration element
schema reference 155
ControlAccessParams element
example of use 56
schema reference 177
DDeployVAppParams
example of use 26, 81
DeployVAppParams element
schema reference 175
EError codes 146
Error element
schema reference 146
examples
about 19
ExternalNetwork element
example of use 99
schema reference 180
FFile element
schema reference 154
Firewall rules
to create or modify 72
FirewallRule element
example of use 72
FirewallService element
example of use 72
schema reference 156
GGroup element
example of use 113
schema reference 191
GuestCustomizationSection element
cannot be passed in InstantiationParams 80
HHost element
example of use 124
vCloud API Programming Guide
210 VMware, Inc.
schema reference 199
HTTP headers
Content-Type 142
HTTP status codes 18
IInstantiateVAppTemplateParams element
example of use 25, 63
schema reference 172
Instantiation Parameters
about 62
InstantiationParams element
example of use 25, 63
schema reference 172
IpRange element
example of use 72
schema reference 156
LLink element
about 15
rel attribute 15
login
example of 21
logout
example of 30
MMedia element
example of use 50
schema reference 161
MediaInsertOrEjectParams element
example of use 85
schema reference 177
NNAT rules
to create or modify 72
NatRule element
example of use 72
schema reference 158
network
vApp 62
NetworkConfigSection element
example of use 71
OOrg element
example of use 22
schema reference 151
Org entity
to retrieve 34
OrgList element
example of use 21
OrgNetwork element
schema definition 154
OVF
to create vApp template from 42
to download vApp template as 47
to upload 171
PProperty element
example of use 36, 161
schema reference 161
Rrel attribute
about 15
ResourceEntity element
about 38
example of use 37, 55
schema reference 154
responses
contents of 18
Role element
example of use 114
schema reference 191
SScreenTicket element
example of use 30, 87
Source element
example of use 63, 65, 67
TTask element
example of use 89
schema reference 168
Tasks
about 14
TasksList element
example of use 97
technical support resources 12
UUndeployVAppParams element
schema reference 175
UploadVAppTemplateParams element
example of use 43
schema reference 171
User element
example of use 110
schema reference 190
VMware, Inc. 211
Index
VvApp
to compose from templates and virtual machines 65
to create from template 24, 61
to deploy and power-on 26
to instantiate 24
VApp element
example of use 65, 66, 67, 69
schema reference 162
vApp networks
about 62
vApp template
add to catalog 54
to create from OVF 42
to create from vApp 68
VAppScopedVmId element
example of use 72
VAppTemplate element
example of use 61
schema reference 161
to create 42
vDC
about 14
Vdc element
example of use 24, 37
schema reference 152
VimServer
example of use 120
schema reference 194
Vm element
example of use 65, 66, 73
schema reference 163
searching for 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
vCloud API Programming Guide
212 VMware, Inc.