VMware vCloud Director - 5.1 Programming Guide

vCloud API Programming Guide

vCloud Director 5.1

This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.

EN-000750-00

vCloud API Programming Guide

You can find the most up-to-date technical documentation on the VMware Web site at:

http://www.vmware.com/support/

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to:

docfeedback@vmware.com

Copyright © 2009–2012 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. 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.

3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

2 VMware, Inc.

vCloud API Programming Guide 7

About the VMware vCloud API 9

Object Taxonomy 10

Objects, References, and Representations 12

Links and Link Relations 12

Client Workflow Overview 16

Using the vCloud API with vCloud Director 21

About the vCloud API Examples 22

Hello vCloud: A Simplified RESTful Workflow 23

Logging In 24

Find a Catalog and a vDC 26

Retrieve the Contents of a Catalog 27

Retrieve a Catalog Item 28

Retrieve Deployment Information From the vDC 30

Deploy the vApp 31

Get Information About a vApp 34

Displaying the Virtual Machine Console 37

Delete the vApp 38

Log Out 40

Exploring a Cloud 41

Summary of vCloud API Browsing Requests 41

Retrieve the Login URL and List of Supported API Versions 43

Create a Login Session Using the Integrated Identity Provider 44

Retrieve a List of Organizations Accessible to You 48

Retrieve an Administrative View of a Cloud 49

Retrieve a List of vSphere Platform Operations and Objects for a Cloud 52

VMware, Inc.

Provisioning an Organization 55

Summary of vCloud API Provisioning Requests 56

Upload an OVF Package to Create a vApp Template 57

Download a vApp Template as OVF 66

Upload a Media Image 69

Copying and Moving with the vCloud API 71

Capturing and Importing vApps 72

Cataloging vApp Templates and Media Images 72

Creating and Using Independent Disks 75

View or Change the Owner of an Object 79

vCloud API Programming Guide

Deploying and Operating vApps 81

Summary of vCloud API vApp and Virtual Machine Operations Requests 83

Create a vApp From a Template 85

Compose a vApp From Existing Virtual Machines 87

Recompose a vApp to Add or Remove Virtual Machines 90

Provide User Input Requested by a Virtual Machine 92

Attach or Detach an Independent Disk 93

Creating and Using vApp Snapshots 95

Operate a vApp 96

Configuring vApps and Virtual Machines 97

Creating and Managing Organizations 129

Summary of Administrative Requests 129

Administrator Credentials and Privileges 132

Organization Administration 132

vDC Administration 139

Network Administration 147

Catalog Administration 176

User and Group Administration 179

Working With Roles and Rights 187

Controlling Access to vApps and Catalogs 191

Managing and Monitoring a Cloud 193

Summary of vSphere Platform Extension Requests 193

Retrieve or Update System Settings 197

Attach a vCenter Server 198

Finding Available vCenter Resources 200

Create a Provider vDC 209

Create an External Network 219

Create a Network Pool 222

Import a Virtual Machine from vCenter 228

Relocate a Virtual Machine to a Different Datastore 231

Truststore and Keytab Maintenance 233

Retrieve the vSphere URL of an Object 236

Working With Object Metadata 239

Retrieve or Update a Metadata Element 241

Retrieve or Update a Metadata Value 244

Using the Query Service 247

Typed Queries 248

Packaged Queries 252

Query Parameters 257

Add a Metadata Filter to a Query 260

Configuring and Using Blocking Tasks and Notifications 263

Configure Notifications and AMQP Settings 264

Retrieve or Update Blocking Task Settings 273

4 VMware, Inc.

Monitor Blocking Tasks 276

Take Action on a Blocking Task 277

Extend The Timeout Expiration of an Active Task 279

Contents

vCloud Director Extension Services 281

Summary of vCloud API Extensibility Requests 282

Adding or Removing Service Links 288

Service-Specific Tasks and Events 291

Authorization Framework for Extension Service Operations 294

Localization Framework for Extension Services 302

REST APIs for Extension Services 302

XML Representations in the vCloud API 307

XML Namespace Identifiers 309

Common vCloud API Attributes 310

Retrieve an Object as an Entity 312

Index 315

VMware, Inc. 5

vCloud API Programming Guide

6 VMware, Inc.

vCloud API Programming Guide

This edition of the vCloud API Programming Guide provides information about version 5.1 of the vCloud API.

VMware provides many different APIs and SDKs for applications and goals. This guide provides information about the vCloud API for developers who are interested in creating RESTful clients of VMware vCloud Director.

Revision History

The vCloud API Programming Guide is revised with each release of the product or when necessary. A revised version can contain minor or major changes.

Table 1. Revision History

Revision Date Description

10SEP12 API Version 5.1

01SEP11 API Version 1.5

30AUG10 API Version 1.0

14APR10 API Version 0.9

Intended Audience

This guide is intended for software developers who are building VMware Ready Cloud Services, including interactive clients of VMware vCloud Director. This guide discusses Representational State Transfer (REST) and RESTful programming conventions, the Open Virtualization Format Specification, and VMware Virtual machine technology. You must be familiar with these and other widely deployed technologies such as XML, HTTP, and the Windows or Linux operating system.

Related Publications

The VMware vCloud Director Administrator's Guide and VMware vCloud 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.

VMware, Inc.

vCloud API Programming Guide

8 VMware, Inc.

About the VMware vCloud API 1

The VMware vCloud API provides support for developers who are building interactive clients of VMware vCloud Director using a RESTful application development style.

vCloud API clients and vCloud Director servers communicate over HTTP, exchanging representations of vCloud objects. These representations take the form of XML elements. You use HTTP GET requests to retrieve the current representation of an object, HTTP POST and PUT requests to create or modify an object, and HTTP DELETE requests to delete an object.

This chapter includes the following topics:

“Object Taxonomy,” on page 10

“Objects, References, and Representations,” on page 12

“Links and Link Relations,” on page 12

“Client Workflow Overview,” on page 16

“Using the vCloud API with vCloud Director,” on page 21

“About the vCloud API Examples,” on page 22

VMware, Inc.

Catalog 2

Catalogitem

em em em

Catalog 1

Catalog 3

vDC2

Catalogitem Catalogitem Catalogitem Catalogitem

users

Media

vApp

template

Media

vApp

TasksList

Organization

vDC1

Media

vApp

template

Media

vApp

Catalogitem

em em em

groups

Network

vCloud API Programming Guide

Object Taxonomy

The vCloud API defines a set of objects common to cloud computing environments. An understanding of these objects, their properties, and their relationships is essential to using the vCloud API.

Figure 1-1. vCloud API Object Taxonomy

vCloud API objects have the following high-level properties:

Organizations

A cloud can contain one or more organizations. Each organization is a unit of administration for a collection of users, groups, and computing resources. Users authenticate at the organization level, supplying credentials established when the user was created or imported. User credentials are authenticated by the organization's identity provider, which can be either the integrated identity provider included in vCloud Director or an external SAML-based identity provider.

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 an LDAP directory service or SAML-based identity provider. Groups must be imported. Permissions within an organization are controlled through the assignment of rights and roles to users and groups.

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 administrators in other organizations. A system administrator specifies which organizations can publish catalogs, and an organization administrator controls access to catalogs by organization members.

10 VMware, Inc.

Chapter 1 About the VMware vCloud API

Organization vDCs

Organization vDC Networks

Virtual Systems and Media Images

An organization virtual datacenter (organization vDC) is a deployment environment for virtual systems owned by the containing organization, and an allocation mechanism for resources such as networks, storage, CPU, and memory. In an organization vDC, computing resources are fully virtualized, and can be allocated based on demand, service level requirements, or a combination of the two.

An organization vDC can be provisioned with one or more networks. These organization vDC networks can be configured to provide direct or routed connections to external networks, or can be isolated from external networks and other organization vDC networks. Routed connections require an Edge Gateway and network pool in the vDC. The Edge Gateway provides firewall, network address translation, static routing, VPN, and load balancing services.

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 initially 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, including:

How the contained virtual machines are connected to each other and to external networks.

Tasks

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 consumption of vDC resources by the vApp.

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 that it contains.

Asynchronous operations that members of an organization initiate are tracked by task objects, which are kept on the organization’s tasks list.

VMware, Inc. 11

vCloud API Programming Guide

Objects, References, and Representations

The vCloud API represents objects as XML documents in which object properties are encoded as elements and attributes with typed values and an explicit object hierarchy defined by an XML schema.

XML representations of first-class vCloud API objects, such as the objects in Figure 1-1, include these attributes.

The object identifier, expressed in URN format. The value of the id attribute uniquely identifies the object, persists for the life of the object, and is never reused. The id attribute value is intended to provide a context-free identifier that can be used with the vCloud API entityResolver (see “Retrieve an Object

as an Entity,” on page 312).

type

href

The object type, specified as a MIME content type.

An object reference, expressed in URL format. Because this URL includes the object identifier portion of the id attribute value, it uniquely identifies the object, persists for the life of the object, and is never reused. The value of the

href attribute is a reference to a view of the object, and can be used to access a

representation of the object that is valid in a particular context. 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 how the server constructs href strings might change in future releases.

Example: Object id, type, and href Attributes

This XML fragment, extracted from the representation of a vApp, shows its id, type, and href attributes.

Links and Link Relations

The vCloud API makes extensive use of Link elements to provide references to objects and the actions that they support. These elements are the primary mechanism by which a server tells a client how to access and operate on an object.

The server creates Link elements in a response body. They are read-only at the client. If a request body includes a Link element, the server ignores it.

Attributes of a Link Element

In the XML representation of a vCloud object, each Link element has the following form:

<Link rel=" type="application/vnd.vmware.vcloud. href=" name="

12 VMware, Inc.

relationship

URL

string

"/>

object_type

+xml"

Attribute values in a Link element supply the following information:

Chapter 1 About the VMware vCloud API

rel

Defines the relationship of the link to the object that contains it. A relationship can be the name of an operation on the object, a reference to a contained or containing object, or a reference to an alternate representation of the object. The relationship value implies the HTTP verb to use when you use the link's href value as a request URL.

type

The object type, specified as a MIME content type, of the object that the link references. This attribute is present only for links to objects. It is not present for links to actions.

href

href attribute is a reference to a view of the object, and can be used to access a

name

The name of the referenced object, taken from the value of that object's name attribute. Action links do not include a name attribute.

Table 1-1. Link Relationships and HTTP Request Types

rel Attribute Value Action or Relationship Description Implied HTTP Verb

abort Abort this blocking task. POST

add Add an item to this container. POST

alternate References an alternate representation of this object. GET

answer Provide user input requested by a virtual machine. POST

authorization:check Check whether an extension service operation is

authorized for an entity.

blockingTask A list of pending blocking task requests in this cloud. GET

bundle:upload Upload an extension service localization bundle. PUT

bundles:cleanup Remove unused extension service localization bundles. POST

catalogItem References the CatalogItem object that refers to this object. GET

certificate:reset Removes the SSL certificate used by this service. POST

certificate:update Updates the SSL certificate used by this service. POST

checkCompliance Check that this virtual machine is using a storage profile

of the intended type.

consolidate Consolidate this virtual machine. POST

controlAccess Apply access controls to this object. POST

copy Reserved N/A

deploy Deploy this vApp. POST

disable Disable this object. POST

discardState Discard the suspended state of this virtual machine. POST

disk:attach Attach an independent disk to this virtual machine. POST

disk:detach Detach an independent disk from this virtual machine. POST

down References an object contained by this object. GET

POST

VMware, Inc. 13

vCloud API Programming Guide

Table 1-1. Link Relationships and HTTP Request Types (Continued)

rel Attribute Value Action or Relationship Description Implied HTTP Verb

down:aclRules Retrieve the ACL rules for this resource class action. GET

down:apidefinitions Retrieve the API definitions for this extension service. GET

down:apiDefinitions Retrieve the API definitions for this extension service. GET

down:apiFilters Retrieve the API filters for this extension service. GET

down:extensibility Add an extension service to the system. POST

down:fileDescriptors Retrieve file descriptors for extension services APIs GET

down:files Retrieve files for extension services APIs GET

down:resourceClassActions Retrieve the actions defined for this extension service

down:resourceClasses Retrieve the resource classes defined by this extension

down:service

down:serviceLinks Retrieve the service links defined by this extension service. GET

down:serviceResources Retrieve the list of extension service resources of this class.

down:services Retrieve the list of registered extension services. GET

download:alternate Reserved N/A

download:default References the default location from which this file can be

download:identity References the extended OVF descriptor of this vApp

edgeGateway:configureServices Update the network services offered by this Edge

edgeGateway:reapplyServices Reapply (after an update) the network services offered by

edgeGateway:redeploy Redeploy the vShield Edge supporting this Edge

edgeGateway:syncSyslogSettings Synchronize syslog server addresses used by this Edge

edgeGateway:upgrade Upgrade the backing configuration of this Edge Gateway

edgeGateways List the Edge Gateway objects in this organization vDC. GET

edit Modify this object, typically by replacing its current

enable Enable this object. POST

enterMaintenanceMode Put this virtual machine into maintenance mode. POST

entity Retrieve a representation of the object on which an

entityResolver Retrieve an object id as a context-free Entity element. GET

event:create Create an event in an this organization's event stream. POST

exitMaintenanceMode Take this virtual machine out of maintenance mode. POST

fail Fail this blocking task. POST

firstPage Reference to the first page of a paginated response. GET

GET

resource class.

GET

service.

GET

downloaded.

GET template. The extended OVF descriptor contains additional information such as MAC address, BIOS UUID, and NetworkConfigSection

PUT Gateway.

POST this Edge Gateway.

POST Gateway.

POST Gateway with system defaults.

POST from compact to full.

PUT representation with the one in the request body.

GET operation triggered this notification.

14 VMware, Inc.

Chapter 1 About the VMware vCloud API

Table 1-1. Link Relationships and HTTP Request Types (Continued)

rel Attribute Value Action or Relationship Description Implied HTTP Verb

installVmwareTools Install VMware Tools on this virtual machine. POST

keystore:reset Removes the keystore used by this service. POST

keystore:update Updates the keystore used by this service. POST

keytab:reset Removes the keytab used by this service. POST

keytab:update Updates the keytab used by this service. POST

lastPage Reference to the last page of a paginated response. GET

media:ejectMedia Eject virtual media from a virtual device. POST

media:insertMedia Insert virtual media into a virtual device. POST

merge Merge one or more Provider vDCs with this Provider vDC. POST

migrateVms Migrate virtual machines from this resource pool to a

different one.

move Reserved N/A

nextPage Reference to the next page of a paginated response. GET

orgVdcNetworks List the organization vDC networks supported by this

Edge Gateway.

ova Reserved N/A

ovf References the OVF descriptor of this vApp template. GET

power:powerOff Power off this vApp or virtual machine. POST

power:powerOn Power on this vApp or virtual machine. POST

power:reboot Reboot this vApp or virtual machine. POST

power:reset Reset this vApp or virtual machine. POST

power:shutdown Shut down this vApp or virtual machine. POST

power:suspend Suspend this vApp or virtual machine. POST

previousPage Reference to the previous page of a paginated response. GET

publish Publish this catalog. POST

recompose Recompose this vApp to add, remove, or reconfigure

virtual machines.

reconfigureVm Update multiple sections of a virtual machine. POST

reconnect Reconnect this vCenter Server to the system. POST

refreshStorageProfiles Refresh the list of storage profiles that exist on the vCenter

service backing this Provider vDC.

refreshVirtualCenter Refresh the representation of this vCenter server POST

relocate Relocate this virtual machine. POST

remove Remove this object. DELETE

remove:force Force removal of this object. DELETE

repair Repair this host or network. POST

resourcePoolVmList List the virtual machines using this resource pool. GET

resume Resume this blocking task. POST

rights List the service-specific rights created by this extension

service.

POST

GET

POST

GET

VMware, Inc. 15

vCloud API Programming Guide

Table 1-1. Link Relationships and HTTP Request Types (Continued)

rel Attribute Value Action or Relationship Description Implied HTTP Verb

rights:cleanup Remove service-specific rights no longer used by any

extension service.

screen:acquireTicket Retrieve a screen ticket for this virtual machine. GET

screen:thumbnail Retrieve a thumbnail view of the screen of this virtual

machine.

shadowVms List shadow virtual machines associated with the virtual

machines in this vApp template.

snapshot:create Create a snapshot of the virtual machines in this vApp. POST

snapshot:removeAll Remove all snapshots created for the virtual machines in

this vApp.

snapshot:revertToCurrent Revert all virtual machines in this vApp to their current

snapshot.

storageProfile References the storage profile for this object. GET

syncSyslogSettings Synchronize syslog server addresses used by this vApp

network with system defaults.

task Retrieve the blocking task that triggered this notification. GET

task:cancel Cancel this task. POST

task:create Create a task object. POST

task:owner Reference to the owner of a task. GET

truststore:reset Remove the truststore used by this service. POST

truststore:update Update the truststore used by this service. PUT

undeploy Undeploy this vApp. POST

unlock Unlock this user account. POST

unregister Unregister this vCenter Server. POST

up References an object that contains this object. GET

update:resourcePools Update the resource pools of this Provider vDC POST

updateProgress Request an update of this task's progress. POST

upgrade Upgrade this ESX/ESXi host. POST

upload:alternate Reserved N/A

upload:default References the default location to which this object can be

uploaded.

vSphereWebClientUrl A URL that you can use to view this object with the

vSphere Web Client

POST

GET

POST

PUT

GET

Client Workflow Overview

vCloud API clients implement a RESTful workflow, making HTTP requests to the server and retrieving the information they need from the server’s responses.

About RESTful Workflows

REST, an acronym for Representational State Transfer, describes an architectural style characteristic of programs that rely on the inherent properties of hypermedia to create and modify the state of an object whose serialized representation is accessible at a URL.

16 VMware, Inc.

Chapter 1 About the VMware vCloud API

If a URL of such an object is known to a client, the client can use an HTTP GET request to retrieve the representation of the object. In the vCloud API, this representation is an XML document. In a RESTful workflow, representations of object state are passed back and forth between a client and a service with the explicit assumption that neither party need know anything about an object other than what is presented in a single request or response. The URLs at which these documents are available often 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.

vCloud REST API Workflows

Application programs written to a REST API use HTTP requests that are often executed by a script or other higher-level language to make remote procedure calls that create, retrieve, update, or delete objects that the API defines. In the vCloud REST API, these objects are defined by a collection of XML schemas. The operations themselves are HTTP requests, and so are generic to all HTTP clients.

To write a RESTful client, you must understand only the HTTP protocol and the semantics of XML, the transfer format that the vCloud API uses. To use the vCloud API effectively in such a client, you need to know only a few things:

The set of objects that the API supports, and what they represent; for example, what is a vDC and how does it relate to an organization or catalog?

How the API represents these objects; for example, what does the XML schema for an Org look like? What do the individual elements and attributes represent?

How a client refers to an object on which it wants to operate; for example, where are the links to objects in a vDC? How does a client obtain and use them?

You can find this information in the vCloud API XML schemas. The XML elements, attributes, and composition rules defined in these schemas 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 create or modify an object with an HTTP PUT or POST request that includes a new or changed XML body document for the object. A client can usually delete an object with an HTTP DELETE request.

The vCloud API schema reference includes detailed information about the XML representations of all vCloud API objects and examples of HTTP requests that operate on those objects. See “About the Schema

Reference,” on page 21.

RESTful Workflow Patterns

All RESTful workflows follow a common pattern.

1 Make an HTTP request, typically GET, PUT, POST, or DELETE. The target of this request is either a well-

known URL such as the vCloud API versions URL, or a URL obtained from the response to a previous request. For example, a GET request to an organization URL returns links to catalog and vDC objects that the organization contains.

2 Examine the response, which always includes an HTTP response code and usually includes a body. In the

vCloud API, a response body is an XML representation of an object, including elements and attributes that represent object properties, links that implement operations on the object or provide references to contained or containing objects and, if the object is being created or modified, an embedded Task object that tracks the progress of the creation or modification. The response also includes an HTTP response code, which indicates whether the request succeeded or failed, and might be accompanied by a URL that points to a location from which you can retrieve additional information.

These operations can repeat, in this order, for as long as necessary.

VMware, Inc. 17

vCloud API Programming Guide

vCloud API REST Requests

To retrieve object representations, clients make HTTP requests to object references. The server supplies these references as href attribute values in responses to GET requests.

Every cloud has a well-known URL from which an unauthenticated user can retrieve a SupportedVersions document, which lists each version of the of vCloud API that the server supports. For each version, the response lists the names and MIME types of the complex types defined in the version's XML namespace, and the version login URL. A system administrator can use that URL to authenticate to the cloud by logging in to the System organization. An authenticated user can discover other vCloud API URLs by making GET requests to URLs retrieved from the login response, and the URLs contained in responses to those requests. See Chapter 3,

“Exploring a Cloud,” on page 41.

Requests are typically categorized in terms of the type of requested operation: create, retrieve, update, and delete. This sequence of verbs is often abbreviated with the acronym CRUD.

Table 1-2. CRUD Operations Summary

Operation Type HTTP Verb Operation Summary

Create POST Creates a new object.

Retrieve GET Retrieves the representation of an

Update PUT Modifies an existing object.

Delete DELETE Deletes an existing object.

existing object.

Authentication

HTTP communications between a vCloud API client and server are secured with SSL. The vCloud API also implements Basic HTTP Authentication, as defined by RFC 2617, which enables a client to authenticate individual HTTP requests by including an authentication header in the request. See “Logging In,” on page 24.

Request Headers

The following HTTP headers are typically included in vCloud API requests:

All requests must include an HTTP Accept header that designates the API version that the client supports. The following header indicates that the request is for vCloud API version 5.1:

Accept: application/*+xml;version=5.1

Valid values for the HTTP Accept header in this release are:

version=5.1

version=1.5

The request is from a vCloud API version 5.1 client.

The request is from a vCloud API version 1.5 client.

18 VMware, Inc.

Chapter 1 About the VMware vCloud API

Requests that specify API version 5.1 cannot access objects that do not exist in the vCloud API version 5.1 namespace.

Accept-Encoding

Authorization

Content-Type

By default, vCloud Director returns response content as uncompressed XML. Compressing the response can improve performance, especially when the response is large and network bandwidth is a factor. (Requests cannot be compressed.) To request a response to be returned as compressed XML, include the following header:

Accept-Encoding: gzip

The response is encoded using gzip encoding as described in RFC 1952, and includes the following header:

Content-Encoding: gzip

In the default configuration, responses smaller than 64KB are never compressed.

All requests from authenticated clients must include an Authorization header. See “Logging In,” on page 24 for details about the value of this header.

Requests that include a body must start with the appropriate HTTP Content-

Type header. Content types for all elements are included in the schema

reference. In addition, 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 object is

application/vnd.vmware.vcloud.catalogItem+xml.

A POST or PUT request that supplies a CatalogItem in the request body 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.

Request Bodies

vCloud Director uses a validating XML parser that requires elements in a request body to agree with the schema in order and number. 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 309.

If multiple namespaces are represented in the request, XML namespace attributes must include an identifying prefix, and that prefix must be used with all elements from that namespace.

All required elements must appear in request bodies. All elements that appear in request bodies must appear in the order that the schema establishes, and with content that conforms to the type constraint that the schema specifies.

VMware, Inc. 19

vCloud API Programming Guide

vCloud API REST Responses

All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content-Type header. Response content depends on the request. Some responses include a document body, some include only a URL, and some are empty.

Response Content

Response content depends on the requested operation. The response to a GET request is typically the complete representation of an existing object. The response to a PUT or POST request always contains values for the

href, name, and id attributes of the object being created or updated. It also contains at most one Task element

that you can retrieve to track the progress of the operation. When the Task completes with a status of

success, a GET request to the object's href returns all properties of the object. If the Task completion status is

not success, the object is in an indeterminate state, and should be deleted.

HTTP Response Codes

A vCloud API client can expect a subset of HTTP status codes in a response.

Table 1-3. HTTP Status Codes that the vCloud API Returns

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 element.

204 No Content The request is valid and was completed. The response does

not include a body.

400 Bad Request The request body is malformed, incomplete, or otherwise

invalid.

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.

406 Not Acceptable The resource identified by the request is only capable of

generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

409 Conflict The object state is not compatible with the requested

operation.

415 Unsupported Media Type The server is refusing to service the request because the entity

of the request is in a format not supported by the requested resource for the requested method.

500 Internal Server Error The request was received but could not be completed

because of an internal error at the server.

504 Gateway Timeout The server, while acting as a gateway or proxy, did not

receive a timely response from the upstream server specified by the URI.

20 VMware, Inc.

Using the vCloud API with vCloud Director

VMware vCloud Director 5.1 supports version 5.1 of the vCloud API. You can use a browser or other HTTP client program to send requests and receive responses.

The vCloud Director REST API Reference documentation includes HTML reference material for all XML elements and complex types defined by the vCloud API. It also includes example XML representations. See

“About the Schema Reference,” on page 21. For information about HTTP client programs to use with

vCloud Director, see “REST Client Programs,” on page 21.

Procedure

1 Configure the vCloud Director REST API base URL.

a Log in to the vCloud Director Web Console as a system administrator.

b In the vCloud Director Web Console, open System Settings > Public Addresses

c Type the URL in the VCD public REST API base URL text box.

2 (Optional) If you want to use the vSphere Web Client to access vCloud API objects on a vSphere server,

verify that the vSphere Web Client URL is enabled for all vCenter servers from which you want to retrieve the vSphere URL of an object.

Chapter 1 About the VMware vCloud API

You can manage this feature on the General tab of the vSphere Properties page of the vCloud Director Web console.

What to do next

Decide on an HTTP client program to use. See “REST Client Programs,” on page 21.

REST Client Programs

Any client application that can send HTTPS requests can be an appropriate tool for developing RESTful applications with the vCloud API.

REST client plug-ins are available for most browsers and many IDEs. The examples in this information were developed using two open-source programs: cURL (http://curl.haxx.se/) and the RESTclient (http://code.google.com/p/rest-client/).

VMware provides additional SDK products that implement language-specific bindings for the vCloud API, and include their own HTTP client capability. See

http://communities.vmware.com/community/developer/forums.

About the Schema Reference

The vCloud API Schema Reference includes reference material for all elements, types, queries, and operations in the vCloud API. It also includes the schema definition files.

The schema reference is available in HTML format in the vCloud Director documentation center.

VMware, Inc. 21

vCloud API Programming Guide

About the vCloud API Examples

The vCloud API Programming Guide includes many examples of HTTP requests and responses. These examples show the workflow and content associated with operations such as browsing, provisioning, and managing your cloud and its contents, and operating virtual systems.

Example requests generally conform to the rules listed in “Request Bodies,” on page 19. Most example responses show only those elements and attributes that are relevant to the operation being discussed. Ellipses (…) indicate omitted content within response bodies. Several additional conventions apply.

The following HTTP header, which is required in all requests that access version 5.1 of the vCloud API, is omitted from most examples.

Accept: application/*+xml;version=5.1

All other request headers required by the vCloud API are included in example requests that are not fragments of some larger example. Although the examples show these strings using the character case in which the implementation defines them, header names and values are case-insensitive, and can be submitted or returned in any character case. 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 included in example requests but omitted from example responses.

Object IDs shown in href attribute values appear as small integers, for example vapp-7 or org/3. In the vCloud API that vCloud Director supports, object IDs are universal unique identifiers (UUIDs) as defined by RFC 4122, for example vapp-f5e185a4-7c00-41f1-8b91-0e552d538101 or org/89a1a8f9-

c518-4f53-960c-950db9e3a1fd.

22 VMware, Inc.

Hello vCloud: A Simplified RESTful

Workflow 2

vCloud API clients and vCloud Director servers communicate over HTTPS, exchanging XML representations of vCloud API objects.

This simplified example of a RESTful workflow includes requests that discover and deploy a particular vApp, in this case, an FTP server with a connection to the public Internet.

These examples assume that you have access to a catalog that includes a vApp template with certain characteristics and an organization network that supports connections to the public Internet. The workflow and examples are flexible, and can accommodate various vApp templates and cloud capabilities.

1 Logging In on page 24

vCloud Director requires API requests to be authenticated. The first step in any RESTful workflow is to obtain an authentication token.

2 Find a Catalog and a vDC on page 26

Before you can deploy a vApp, you must find a vApp template in one of your organization's catalogs and a vDC in your organization to use for the deployment.

3 Retrieve the Contents of a Catalog on page 27

You can make a GET request to a catalog URL to retrieve a list of vApp templates and media images referenced by the catalog.

VMware, Inc.

4 Retrieve a Catalog Item on page 28

You can examine the list of items in a catalog to find items of interest based on the values of their name and type attributes. You must retrieve a catalog item to get a Description and a usable reference to the underlying object.

5 Retrieve Deployment Information From the vDC on page 30

To deploy your template as a vApp, you must specify an organization vDC to deploy it in and an organization vDC network to connect it to.

6 Deploy the vApp on page 31

To create a vApp from a vApp template, you must bind the template's 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.

7 Get Information About a vApp on page 34

When you instantiate a vApp template, the server returns the URL of the resulting vApp. You can use this URL with a GET request to retrieve information that you can use to connect to the vApp, modify its configuration, and operate it.

vCloud API Programming Guide

8 Displaying the Virtual Machine Console on page 37

After a vApp is powered on, you can retrieve a screen ticket from one of its virtual machines. You use that ticket with the VMRC browser plug-in to gain access to the console of the virtual machine.

9 Delete the vApp on page 38

To delete the vApp, undeploy it and power it off, then use an HTTP DELETE request to delete the vApp object.

10 Log Out on page 40

To log out and terminate a vCloud API session, delete the Session you created when you logged in.

Logging In

vCloud Director requires API requests to be authenticated. The first step in any RESTful workflow is to obtain an authentication token.

Every cloud has a login URL that a client can obtain by making an unauthenticated GET request to the vCloud Director api/versions URL. See “Retrieve the Login URL and List of Supported API Versions,” on page 43. Because all other vCloud API requests must be authenticated, any vCloud API workflow must begin with a login request that supplies user credentials in the form that Basic HTTP authentication requires.

For information about how to create a login request and view the response, see “Example: Login Request and

Response,” on page 25.

NOTE This procedure assumes that you are logging in with credentials managed by the vCloud Director integrated identity provider. Users whose credentials are managed by a SAML identity provider must follow a different login workflow.

Prerequisites

Verify that the following conditions are met:

You are a member of an organization in the cloud, and have permission to create and operate vApps.

Your organization contains at least one vDC and one network. For more information about setting up an organization to support the Hello vCloud workflow, see Chapter 6, “Creating and Managing

Organizations,” on page 129.

Your organization contains a catalog in which at least one vApp template is available. For more information about adding a vApp template to a catalog, see Chapter 4, “Provisioning an Organization,” on page 55.

Procedure

1 Make an API versions request to vCloud Director to obtain the login URL for the REST API.

2 Use the login URL to create a login session.

POST a request to this URL that includes your username, password, and organization name in a MIME Base64 encoding. See “Example: Login Request and Response,” on page 25.

3 Examine the response.

The response code indicates whether the request succeeded, or how it failed.

A successful login request returns an authentication token that you can use in subsequent requests. It also returns a Session element, which contains one or more Link elements, each of which provides a URL that you can use to explore a subset of objects in the cloud. If you log in as a system administrator or organization administrator, this list includes multiple links. See “Example: Create a Login Session Using the Integrated

24 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Identity Provider,” on page 45. Otherwise, the list typically includes a link of type

application/vnd.vmware.vcloud.orgList+xml, as shown in the response portion of “Example: Login Request

and Response,” on page 25. You can use this link to find out more about your organization and the objects

it contains.

For more information about the other links in the Session element, see “Create a Login Session Using the

Integrated Identity Provider,” on page 44.

Example: Login Request and Response

A request to create a login session must supply the user's credentials in the following form:

user@organization:password

user is the user's login name.

organization is the name of an organization of which the user is a member.

password is the user's password.

These credentials must be supplied in a MIME Base64 encoding, as specified in RFC 1421.

NOTE System administrators must log in to the System organization. See “Administrator Credentials and

Privileges,” on page 132. Because the System organization does not support some of the features demonstrated

in the Hello vCloud workflow, you should try this example in another organization.

This example shows a login request and response for a user named HelloUser logging into an organization named ExampleOrg in a cloud whose login URL is https://vcloud.example.com/api/sessions.

Request:

POST https://vcloud.example.com/api/sessions Authorization: Basic Accept: application/*+xml;version=5.1

encoded-credentials

Response:

200 OK x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.1 ... <Session xmlns="http://www.vmware.com/vcloud/v2.0" user="HelloUser" org="ExampleOrg" ... > <Link rel="down" type="application/vnd.vmware.vcloud.orgList+xml" href="https://vcloud.example.com/api/org"/> <Link rel="down" type="application/vnd.vmware.vcloud.query.queryList+xml" href="https://vcloud.example.com/api/query" /> <Link rel="entityResolver" type="application/vnd.vmware.vcloud.entity+xml" href="https://vcloud.example.com/api/entity/" /> </Session>

VMware, Inc. 25

vCloud API Programming Guide

The response code indicates whether the request succeeded, or how it failed.

If the request is successful, the server returns HTTP response code 200 (OK) and headers that include an authorization header of the following form:

x-vcloud-authorization:

token

This header must be included in each subsequent vCloud API request.

If the authentication header is missing, the server returns HTTP response code 403.

If the credentials supplied in the authentication header are invalid, or if the token has expired, the server returns HTTP response code 401. The token expires after a configurable interval of client inactivity. The default is 30 minutes after the token is created. After the token expires, you must log in again to obtain a new token.

Find a Catalog and a vDC

Before you can deploy a vApp, you must find a vApp template in one of your organization's catalogs and a vDC in your organization to use for the deployment.

After you log in, you can make a GET request to your organization's URL to retrieve the XML representation of the organization. This representation shows the organization's attributes and contents, including links to its catalogs and vDCs.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Examine the list of organizations to which you have access.

Make a GET request to the URL in the href value of the orgList link, which is present in the response to all login requests.

GET https://vcloud.example.com/api/org/

Unless you are a system administrator, the response to this request is an OrgList element containing a single Org element, which represents your organization.

2 Retrieve the representation of your organization.

See the request portion of “Example: Retrieve the Contents of an Organization,” on page 26.

3 Examine the response to find the links to the organization's catalogs and vDCs.

See the response portion of “Example: Retrieve the Contents of an Organization,” on page 26.

Example: Retrieve the Contents of an Organization

This example retrieves the ExampleOrg organization listed in the OrgList element shown in Step 1.

26 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Request:

GET https://vcloud.example.com/api/org/5

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... <Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml" href="https://vcloud.example.com/api/org/5"> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32" name="ExampleCatalog" /> <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5" name="ExampleVdc01" /> <Link ... /> <Link ... /> <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. This example shows the subset of those items that we reference in the Hello vCloud example:

A catalog named ExampleCatalog, at URL https://vcloud.example.com/api/catalog/32, where you can look for vApp templates.

An organization vDC named ExampleVdc01, at URL https://vcloud.example.com/api/vdc/5, where you can deploy the vApp.

Retrieve the Contents of a Catalog

You can make a GET request to a catalog URL to retrieve a list of vApp templates and media images referenced by the catalog.

To use a vApp template or media image listed in a catalog, retrieve the catalog to discover the set of

CatalogItem elements it contains, then make an additional request to retrieve the CatalogItem of interest.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of your organization.

Use a request like this one:

GET https://vcloud.example.com/api/org/5

VMware, Inc. 27

vCloud API Programming Guide

2 Examine the response to find the links to the organization's catalogs.

These links have the following form:

<Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/id" name="

catalog_name

" />

3 Retrieve the contents of the catalog.

Use a GET request of the form shown in the request portion of “Example: Retrieve the Contents of a

Catalog,” on page 28.

Example: Retrieve the Contents of a Catalog

This example retrieves the catalog shown in the response portion of “Example: Retrieve the Contents of an

Organization,” on page 26.

Request:

GET https://vcloud.example.com/api/catalog/32

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.catalog+xml ... <Catalog xmlns="http://www.vmware.com/vcloud/v1.5" name="ExampleCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32"> <Description>Main Org Catalog</Description> <CatalogItems> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="https://vcloud.example.com/api/catalogItem/221"/> <CatalogItem ... /> <CatalogItem ... /> </CatalogItems> </Catalog>

Retrieve a Catalog Item

You can examine the list of items in a catalog to find items of interest based on the values of their name and

type attributes. You must retrieve a catalog item to get a Description and a usable reference to the underlying

object.

Every vApp template or media image that is 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, the client requires more information. In “Example: Retrieve a Catalog Item,” on page 29, the client makes a GET request to the URL in the value of the href attribute of a CatalogItem. 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.

28 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the representation of a catalog in your organization.

Use a request like this one:

GET https://vcloud.example.com/api/catalog/32

2 Examine the response to find the CatalogItem elements that the catalog contains.

The value of the name attribute of a CatalogItem element is taken from the name attribute of the referenced object. You can use it as a preliminary indicator of what the item represents.

3 Retrieve a CatalogItem.

Use a GET request of the form shown in the request portion of “Example: Retrieve a Catalog Item,” on page 29.

Example: Retrieve a Catalog Item

This example retrieves the CatalogItem shown in the response portion of “Example: Retrieve the Contents of

a Catalog,” on page 28.

Request:

GET https://vcloud.example.com/api/catalogItem/221

In addition to the name attribute and Description element, the CatalogItem contains a rel="up" link to the catalog that contains it, and other links that you can use to manage the CatalogItem.

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem xmlns="http://www.vmware.com/vcloud/v1.5" name="Ubuntu Template with vsftpd" id="urn:vcloud:catalogitem:221" href="https://vcloud.example.com/api/catalogItem/221" ... > <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32" /> <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/catalogItem/221/metadata" /> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud.example.com/api/catalogItem/221" /> <Link rel="remove" href="https://vcloud.example.com/api/catalogItem/221" /> <Description>Approved template for public FTP sites</Description> <Entity

VMware, Inc. 29

vCloud API Programming Guide

href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> </CatalogItem>

Retrieve Deployment Information From the vDC

To deploy your template as a vApp, you must specify an organization vDC to deploy it in and an organization vDC network to connect it to.

Instantiation, deployment, and operation of a vApp all take place in the context of an organization vDC. The XML representation of a vDC object defines that context in detail. For this exercise, you need several 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 in the organization vDC that the vApp can connect to.

“Example: Deployment Information in a vDC,” on page 30 shows this subset of vDC contents.

Prerequisites

Verify that the following conditions are met:

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Retrieve the representation of your organization. See the request portion of “Example: Retrieve the

Contents of an Organization,” on page 26. The response portion contains links to the organization's vDCs.

Procedure

1 Examine the Org response to find the links to the organization's vDCs.

Links to vDCs have the form:

<Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/ name="

vDC_name

" />

2 Retrieve the contents of the vDC.

Use a GET request of the form shown in the request portion of “Example: Deployment Information in a

vDC,” on page 30.

Example: Deployment Information in a vDC

This example shows a request to retrieve the XML representation of a vDC. It shows only the subset of the response that contains deployment information.

Request:

GET https://vcloud.example.com/api/vdc/5

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vdc+xml ... <Vdc xmlns="http://www.vmware.com/vcloud/v1.5" name="ExampleVdc01"

30 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"> ... <Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" href="https://vcloud.example.com/api/vdc/5/action/instantiateVAppTemplate" /> ... <AvailableNetworks> <Network href="https://vcloud.example.com/api/network/14" type="application/vnd.vmware.vcloud.network+xml" name="Isolated" /> <Network href="https://vcloud.example.com/api/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet" /> </AvailableNetworks> ... </Vdc>

The information that you need is available in the following elements of the response:

A Link element that contains an action URL for instantiateVAppTemplate. The rel attribute of this link has a value of add. It implements an action that adds an object (a vApp) to the vDC.

A list of AvailableNetworks that includes all the networks in the vDC.

Deploy the vApp

To deploy the vApp, you construct an InstantiateVAppTemplateParams element that specifies a vApp template to use and a network to connect to, then POST the element to the action/instantiateVAppTemplate URL of the vDC.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of the vApp template.

Make a GET request to the URL provided in the href attribute of the Entity contained by the

CatalogItem that references the template.

2 Examine the template to find the Vm elements of the virtual machines that it contains.

Look for a NetworkConnection element in the Vm. You need some of the information in that element to create a vApp network that the virtual machine can connect to.

3 Create an InstantiateVAppTemplateParams element.

See “Example: Deploying a vApp,” on page 32 for guidelines.

4 Make a POST request to the action/instantiateVAppTemplate URL of the vDC.

Supply the InstantiateVAppTemplateParams element as the request body.

VMware, Inc. 31

vCloud API Programming Guide

The server takes the requested action and returns a VApp element. The element has a status attribute value of

0, meaning it is unresolved because it is still being constructed. It also contains a Task element that tracks the

progress of the request.

See the response portion of “Example: Deploying a vApp,” on page 32.

Example: Deploying a vApp

This simple instantiateVAppTemplate request assumes that the vApp template includes one Vm and has no special requirements other than connecting that Vm to a network. For a look at a more complex instantiation request, see “Example: Instantiate a vApp Template,” on page 86. The InstantiateVAppTemplateParams includes the following information:

A name for the vApp, supplied in the name attribute of the InstantiateVAppTemplateParams element. This request also provides a description, which is optional but a good practice.

A reference to a template, obtained from the href attribute of the Entity contained by the CatalogItem that you retrieved in “Retrieve a Catalog Item,” on page 28 and suppled in the Source element of the

InstantiateVAppTemplateParams.

Configuration parameters for a vApp network, supplied in the NetworkConfigSection element. This specification includes the following parameters:

A name for the network, supplied in the name attribute of the NetworkConfigSection element. The name you specify for the vApp network must match the value of the network attribute of the

NetworkConnection of the Vm. This example assumes that this NetworkConnection element includes the

following values, which specify that the Vm connects to a network named VappNetwork:

A reference to the organization vDC network to which the vApp network connects, specified in the

ParentNetwork element. The URL used in this reference is one shown in the AvailableNetworks

element in “Example: Deployment Information in a vDC,” on page 30.

A fence mode, specified in the FenceMode element. A value of bridged indicates that the vApp network is connected directly to the organization vDC network.

For more information about creating networks with the vCloud API, see “About vCloud Director

Networks,” on page 148.

The target of the request is the instantiateVAppTemplate URL of this vDC. See “Example: Deployment

Information in a vDC,” on page 30. Because the operation creates a new vApp object, the HTTP request type

is POST.

Request:

32 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Example FTP Server</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks </ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <ParentNetwork href="https://vcloud.example.com/api/network/54" /> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> </InstantiationParams> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" /> </InstantiateVAppTemplateParams>

The response to the instantiation request is a sparsely populated vApp element that includes the following information:

The status of the vApp. The status value 0 indicates that the vApp is unresolved, because instantiation is not complete.

The name of the vApp, as supplied in the request.

The vApp URL, shown in the href attribute of the VApp element. You can use this reference to retrieve information about the vApp.

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. The vApp is the owner of the task.

Response:

201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" deployed="false" status="0" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-7"> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"/> <Description>Example FTP Server vApp</Description> <Tasks> <Task status="running" operation="Creating Virtual Application Linux FTP server(7)"

VMware, Inc. 33

vCloud API Programming Guide

... > <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="https://vcloud.example.com/vApp/vapp-7" /> </Task> </Tasks> </VApp>

Get Information About a vApp

As other examples have shown, a client can always use an HTTP GET request to the URL in the object's href attribute to discover the current state of any vCloud API object, including a vApp.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of the vApp.

Make a GET request to the URL in the href attribute of the VApp element that is returned when you create the vApp from the template.

2 Examine the response.

See “Example: Getting Information About the vApp,” on page 34.

Example: Getting Information About the vApp

This response reveals several things about the vApp:

The vApp is deployed (its deployed attribute is set to true) and powered on (status="4"). See “Object

Creation Status,” on page 311.

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: Deploying a vApp,” on page 32. Properties of this network are included in the NetworkConfigSection of the vApp, although most are not shown here. Properties of the virtual machine's connection to the network, including its IP address, are shown in the

NetworkConnection of the Vm.

Action links for all operations except powerOn are present in the VApp element and the Vm element that it contains. 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 are not applicable to a vApp. Actions such as acquiring a screen ticket or thumbnail, and inserting or removing media, are meaningful only in the context of a virtual machine. Other actions, like shutdown and reboot, can be applied to either object. See Chapter 5, “Deploying and Operating vApps,” on page 81.

Request:

GET https://vcloud.example.com/api/vApp/vapp-7

34 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp ... deployed="true" status="4" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-7" ... > ... <Link rel="power:reboot" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/reboot" /> <Link rel="power:powerOff" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/powerOff" /> <Link rel="undeploy" href="https://vcloud.example.com/api/vApp/vapp-7/action/undeploy" /> <Link rel="deploy" href="https://vcloud.example.com/api/vApp/vapp-7/action/deploy" /> <Link rel="power:shutdown" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/shutdown" /> <Link rel="power:reset" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/reset" /> <Link rel="power:suspend" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/suspend" /> <Link ... /> ... <Description>Example FTP Server vApp</Description> <LeaseSettingsSection ... > ... </LeaseSettingsSection> <ovf:StartupSection ... > ... </ovf:StartupSection> <ovf:NetworkSection ... > <ovf:Info /> <ovf:Network ovf:name="vAppNetwork"> <ovf:Description /> </ovf:Network> </ovf:NetworkSection> <NetworkConfigSection href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml"

VMware, Inc. 35

vCloud API Programming Guide

href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" /> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScopes> ... </IpScopes> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="https://vcloud.example.com/api/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="https://vcloud.example.com/api/vApp/vm-4"> ... <Link rel="power:reboot" href="https://vcloud.example.com/api/vApp/vm-4/power/action/reboot" /> <Link rel="power:powerOff" href="https://vcloud.example.com/api/vApp/vm-4/power/action/powerOff" /> <Link rel="undeploy" href="https://vcloud.example.com/api/vApp/vm-4/action/undeploy" /> <Link rel="deploy" href="https://vcloud.example.com/api/vApp/vm-4/action/deploy" /> <Link rel="power:shutdown" href="https://vcloud.example.com/api/vApp/vm-4/power/action/shutdown" /> <Link rel="power:reset" href="https://vcloud.example.com/api/vApp/vm-4/power/action/reset" /> <Link rel="power:suspend" href="https://vcloud.example.com/api/vApp/vm-4/power/action/suspend" /> <Link rel="up" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-7" /> <Link rel="screen:thumbnail" href="https://vcloud.example.com/api/vApp/vm-4/screen" /> <Link rel="screen:acquireTicket"

36 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

href="https://vcloud.example.com/api/vApp/vm-4/screen/action/acquireTicket" /> <Link rel="media:insertMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="https://vcloud.example.com/api/vApp/vm-4/media/action/insertMedia" /> <Link ... /> ... <Description /> <ovf:VirtualHardwareSection> ... </ovf:VirtualHardwareSection> ... <NetworkConnectionSection> ... <NetworkConnection> network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.201.10</IpAddress> <IsConnected>true</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>DHCP</IpAddressAllocationMode> </NetworkConnection> </NetworkConnectionSection> <GuestCustomizationSection> ... </GuestCustomizationSection> ... </Vm> </Children> </VApp>

Displaying the Virtual Machine Console

After a vApp is powered on, you can retrieve a screen ticket from one of its virtual machines. You use that ticket with the VMRC browser plug-in to gain access to the console of the virtual machine.

A screen ticket is a string that includes the virtual machine’s IP address, its managed object reference, and a residual that is encoded as described in RFC 2396. Each Vm element in a vApp includes a link where

rel="screen:acquireTicket" if the virtual machine it represents is powered on. You can use that link to retrieve

a screen ticket that you can use with the VMRC API to open a VMware Remote Console for the virtual machine.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Verify that the virtual machine whose console you want to display is powered on.

Verify that your browser has an installed copy of the vmware-vmrc plug-in. This plug-in is installed by your browser whenever you use the vCloud Director Web Console to access the console of a running virtual machine. After this plug-in is installed, you can find it in the folder where your browser stores plug-ins.

VMware, Inc. 37

vCloud API Programming Guide

Procedure

1 Retrieve the screen ticket.

POST a request to the acquireTicket link of the Vm.

Request:

POST https://vcloud.example.com/api/vApp/vm-4/screen/action/acquireTicket

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.screenTicket+xml ... <ScreenTicket xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...> </ScreenTicket>

The ticket string itself has the following form:

mks://

ip-address/VM-MoRef

ip-address is the IP address of the virtual machine.

VM-MoRef is the managed object reference of the virtual machine.

/ticket=

ticket-string

encoded-ticket

encoded-ticket is the encoded screen ticket. You must decode this ticket using a function such as the Java URLDecoder or PERL url_escape before you can use it.

2 Use the ticket with the VMRC API.

The ticket is valid for 30 seconds. To use it, you must initialize the VMRC browser plug-in and use the VMRC API, as described in the VMware Technical Note Using the VMRC API.

Delete the vApp

To delete the vApp, undeploy it and power it off, then use an HTTP DELETE request to delete the vApp object.

A deployed vApp has a link that you can use with a POST request to undeploy it and then take a power action such as powering it off or suspending it. A powered-off vApp has a link that you can use with a DELETE request to remove it.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or the object owner.

Procedure

1 Retrieve the XML representation of the vApp.

Make a GET request to the URL provided in the href attribute of the VApp element returned when you created the vApp from the template. See “Get Information About a vApp,” on page 34.

2 Undeploy the vApp, and specify that it should also be powered off.

Make a POST request to the vApp's action/undeploy link, which has the following form:

In the request body, specify that the undeployment include powering off the vApp. See

“Example: Undeploy, Power Off, and Delete a vApp,” on page 39.

38 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

3 Retrieve the XML representation of the vApp again.

Now that it has been powered off and undeployed, the vApp includes a rel="remove" link of the following form:

4 Remove the vApp.

Make a DELETE request to the vApp's rel="remove" link, as shown in the request portion of

“Example: Undeploy, Power Off, and Delete a vApp,” on page 39.

The server starts a task to manage the events that lead up to the removal of the vApp, and returns a Task element that you can use to track the progress of the task.

Example: Undeploy, Power Off, and Delete a vApp

The undeploy request body, an UndeployVAppParams element, allows you to specify an UndeployPowerAction. This example specifies an UndeployPowerAction of powerOff. Although powerOff is the default

UndeployPowerAction, we show it here for clarity.

Request:

POST https://vcloud.example.com/api/vApp/vapp-7/action/undeploy Content-Type: application/vnd.vmware.vcloud.undeployVAppParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <UndeployVAppParams xmlns="http://www.vmware.com/vcloud/v1.5"> <UndeployPowerAction>powerOff</UndeployPowerAction> </UndeployVAppParams>

Response:

202 Accepted ... <Task xmlns="http://www.vmware.com/vcloud/v1.5" ... operation="Undeploying Virtual Application Linux FTP server (7)" ... > </Task>

After the vApp has been undeployed and powered off, its representation includes a link where

rel="remove". Make a DELETE request to this link to remove the vApp.

Request:

DELETE https://vcloud.example.com/api/vApp/vapp-7

Response:

202 Accepted ... <Task ... operation="Deleting Virtual Application Linux FTP server (7)" expiryTime="2010-09-23T08:00:55.402-07:00" ... > </Task>

VMware, Inc. 39

vCloud API Programming Guide

Log Out

To log out and terminate a vCloud API session, delete the Session you created when you logged in.

The logout request, like all other authenticated requests, must include the authorization header, as shown in

“Example: Logging Out,” on page 40.

Prerequisites

Verify that you are logged in.

Procedure

Make a DELETE request specifying the href of the current Session object.

Example: Logging Out

This example deletes the current user's Session, which logs the user out.

Request:

DELETE https://vcloud.example.com/api/session x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=

Response:

200 OK

40 VMware, Inc.

Exploring a Cloud 3

You can use HTTP GET requests to browse containers such as organizations, catalogs, and vDCs in a cloud.

Responses to these requests include metadata about the container itself and references to the objects it contains. These references are provided in Link elements, which have href attributes whose values the client can use in requests to get more information about the objects themselves. This process is sometimes called serial discovery, because the contents of one response provides links to locations where you can look for more information. The hierarchical structure of vCloud API container objects lends itself to graphical representation as a folder hierarchy or tree view of vCloud API objects, and enables clients to use the same set of objects and operations to implement a breadth-first or depth-first approach to browsing.

The list of entry points from which you can begin browsing is contained in the Session element that is returned in response to a successful login. The contents of this list is based on your role and privileges.

This chapter includes the following topics:

“Summary of vCloud API Browsing Requests,” on page 41

“Retrieve the Login URL and List of Supported API Versions,” on page 43

“Create a Login Session Using the Integrated Identity Provider,” on page 44

“Retrieve a List of Organizations Accessible to You,” on page 48

“Retrieve an Administrative View of a Cloud,” on page 49

“Retrieve a List of vSphere Platform Operations and Objects for a Cloud,” on page 52

Summary of vCloud API Browsing Requests

Browsing requests provide read-only access to a cloud and the objects it contains.

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

IMPORTANT Request URLs are always available in Link elements contained by the representation of the object on which they operate. URL forms shown here are for reference purposes only. Although URLs have a wellknown syntax and a well-understood interpretation, a client should treat vCloud API request URLs as opaque strings. The rules that govern how the server constructs these strings might change in future releases.

This summary may not cover all requests in this category. For the complete list of requests, along with detailed information about input and output types, see the Operations lists in the schema reference.

VMware, Inc.

vCloud API Programming Guide

Table 3-1. Summary of vCloud API Browsing Requests

Operation Request Request Body Response

Show login URL and list of supported API versions

Log out DELETE API-URL/session None 200 OK

Log out [DEPRECATED] POST API-URL/login None 200 OK

Retrieve a list of entry points for browsing operations

Retrieve a list of organizations to which you have access

Retrieve the contents of an organization

Retrieve properties of a network

Retrieve the contents of a catalog

Retrieve properties of a catalog item

Retrieve the contents of a vDC

Retrieve properties of a media image

Retrieve a vApp template GET API-

Retrieve properties of a vApp GET API-URL/vApp/vapp-idNone

GET API-URL/versions None

SupportedVersions

Session

OrgList

GET API-URL/session None 200 OK

GET API-URL/org/ None

GET API-URL/org/id None

GET API-URL/network/id None

GET API-URL/catalog/id None

GET API-

None

OrgList

Org

OrgNetwork

Catalog

CatalogItem

URL/catalogItem/id

GET API-URL/vdc/id None

GET API-URL/media/id None

None

Vdc

Media

VAppTemplate

URL/vAppTemplate/vappT emplate-id

VApp

Retrieve properties of a

GET API-URL/vApp/vm-id None

virtual machine

Retrieve metadata for an object such as an

GET API- URL/object/id/metadata

None

Metadata

organization, network, vApp, virtual machine, media image, or independent disk.

Retrieve a list of IP addresses allocated to a network. [NEW]

42 VMware, Inc.

GET APIURL/network/ id/allocatedAddresses

None

AllocatedIpAddresses

Chapter 3 Exploring a Cloud

Retrieve the Login URL and List of Supported API Versions

Every cloud has a login URL that a client can obtain by making an unauthenticated GET request to the vCloud Director api/versions URL. The response to this request also lists vCloud API versions that the server supports.

Procedure

1 Make an API version request to vCloud Director to obtain the login URL for the REST API.

See the request portion of “Example: Versions Request and Response,” on page 43.

2 Examine the response to find the login URLs.

Each version of the vCloud API that the server supports has its own login URL. Look for a line of the following form:

<LoginUrl>http://vcloud.example.com/api/...</LoginUrl>

3 Use the login URL to log in to the cloud.

Example: Versions Request and Response

The api/versions request does not need to be authenticated. The response, a small subset of which is shown here, includes a VersionInfo element for each API version that the server supports. Each VersionInfo element contains:

A LoginUrl element that contains the URL to which a client can make a login request to access that version of the vCloud API. See “Logging In,” on page 24.

MediaTypeMapping elements for each complex type supported by that version of the vCloud API.

Request:

GET http://vcloud.example.com/api/versions

Response:

200 OK Content-Type: text/xml ... <SupportedVersions xmlns="http://www.vmware.com/vcloud/versions" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/versions http://vcloud.example.com/api/versions/schema/versions.xsd"> <VersionInfo> <Version>1.5</Version> <LoginUrl>https://vcloud.example.com/api/login</LoginUrl> <MediaTypeMapping> <MediaType>application/vnd.vmware.vcloud.catalog+xml</MediaType> <ComplexTypeName>CatalogType</ComplexTypeName> <SchemaLocation>http://vcloud.example.com/api/v1.5/schema/master.xsd</SchemaLocation> </MediaTypeMapping> <MediaTypeMapping> ... </MediaTypeMapping> </VersionInfo> <VersionInfo> <Version>5.1</Version>

VMware, Inc. 43

vCloud API Programming Guide

<LoginUrl>https://vcloud.example.com/api/sessions</LoginUrl> <MediaTypeMapping> <MediaType>application/vnd.vmware.vcloud.catalog+xml</MediaType> <ComplexTypeName>CatalogType</ComplexTypeName> <SchemaLocation>http://vcloud.example.com/api/v1.5/schema/master.xsd</SchemaLocation> </MediaTypeMapping> <MediaTypeMapping> ... </MediaTypeMapping> ... </VersionInfo> </SupportedVersions>

NOTE You can use the URL in the SchemaLocation element with a GET request to retreive the file in which that complex type is defined. For example:

GET http://vcloud.example.com/api/v1.5/schema/master.xsd

Create a Login Session Using the Integrated Identity Provider

The vCloud API login mechanism authenticates a user and creates a Session object that contains the URLs from which that user can begin browsing. Users who authenticate to the integrated identity provider use basic HTTP authentication.

Prerequisites

Verify that you know the login URL. See “Retrieve the Login URL and List of Supported API Versions,” on page 43.

Verify that you are logging in as a user whose identity is managed by the vCloud Director integrated identity provider.

Procedure

1 Use the login URL to authenticate to the cloud.

POST a request to this URL. The request must include your username, organization name, and password in a MIME Base64 encoding. See “Example: Create a Login Session Using the Integrated Identity

Provider,” on page 45.

2 Examine the response.

The response code indicates whether the request succeeded, or how it failed.

If the authentication header is missing, the server returns HTTP response code 403.

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.

44 VMware, Inc.

Chapter 3 Exploring a Cloud

The Session element returned from a successful login contains one or more URLs from which you can begin browsing.

The list of URLs in the Session object is based on the role and privileges of the authenticated user. A Session object expires after a configurable interval of client inactivity. To change the length of this client inactivity timeout, a system administrator can change the value of SessionTimeoutMinutes in the system's

GeneralSettings. See “Retrieve or Update System Settings,” on page 197.

A Session object can be deleted by its owner or an administrator. After your Session expires or is deleted, you are not authenticated.

Example: Create a Login Session Using the Integrated Identity Provider

A request to create a login session must supply the user's credentials in the following form:

user@organization:password

user is the user's login name.

organization is the name of an organization of which the user is a member.

password is the user's password.

These credentials must be supplied in a MIME Base64 encoding, as specified in RFC 1421.

This example shows a login request and response for a system administrator logging in to a cloud whose login URL is https://vcloud.example.com/api/sessions.

Request:

POST https://vcloud.example.com/api/sessions Authorization: Basic Accept: application/*+xml;version=1.5

encoded-credentials

Response:

200 OK x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.session+xml ... <Session xmlns="http://www.vmware.com/vcloud/v1.5" user="sysadmin" org="System" ... > <Link rel="down" type="application/vnd.vmware.vcloud.orgList+xml" href="https://vcloud.example.com/api/org"/> <Link rel="down" type="application/vnd.vmware.admin.vcloud+xml" href="https://vcloud.example.com/api/admin"/> <Link rel="down" type="application/vnd.vmware.admin.vmwExtension+xml" href="https://vcloud.example.com/api/admin/extension"/> <Link rel="down" type="application/vnd.vmware.vcloud.query.queryList+xml" href="https://vcloud.example.com/api/query" />

VMware, Inc. 45

vCloud API Programming Guide

This response includes the following link types:

orgList

A link to the list of organizations that you can access. See “Retrieve a List of

Organizations Accessible to You,” on page 48.

vcloud

A link to administrative objects and operations. See Chapter 6, “Creating and

Managing Organizations,” on page 129

vmwExtension

A link to the vCloud API extensions, accessible to a system administrator. See

Chapter 7, “Managing and Monitoring a Cloud,” on page 193.

queryList

A link to the set of typed queries you can run. See Chapter 9, “Using the Query

Service,” on page 247.

entity

A link to the entity resolver. See “Retrieve an Object as an Entity,” on page 312.

Create a Login Session Using a SAML Identity Provider

The vCloud API login mechanism authenticates a user and creates a Session object that contains the URLs from which that user can begin browsing. Users who authenticate to a SAML identity provider must acquire and process a security assertion from that identity provider, then submit the processed assertion to the vCloud API login URL.

Prerequisites

NOTE This procedure assumes that you are logging in with credentials managed by a SAML identity provider. Users whose credentials are managed by the vCloud Director integrated identity provider must follow a different login workflow.

Verify that you know the login URL. See “Retrieve the Login URL and List of Supported API Versions,” on page 43

Verify that you are logging in as a user whose identity is managed by the SAML identity provider defined by your organization.

Procedure

1 Acquire the SAML assertion from your identity provider.

The system administrator must use the vSphere SSO Service as the identity provider.

2 Compress the assertion using GZIP.

3 Encode the compressed assertion a MIME Base64 encoding, as specified in RFC 1421.

4 Use the login URL to authenticate to the cloud.

POST a request to this URL. The request must include an Authorization header that specifies SIGN as the authorization method and has the following attributes:

46 VMware, Inc.

Table 3-2. Authorization Header Attributes and Values

Attribute Name Attribute Value

token

org

The compressed, encoded identity assertion from your SAML identity provider.

The name of your vCloud Director organization.

See “Example: Create a Login Session Using a SAML Identity Provider,” on page 47.

5 Examine the response.

The response code indicates whether the request succeeded, or how it failed.

If the authentication header is missing, the server returns HTTP response code 403.

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:

Chapter 3 Exploring a Cloud

x-vcloud-authorization:

token

This header must be included in each subsequent vCloud API request.

The Session element returned from a successful login contains one or more URLs from which you can begin browsing.

GeneralSettings. See “Retrieve or Update System Settings,” on page 197.

A Session object can be deleted by its owner or an administrator. After your Session expires or is deleted, you are not authenticated.

Example: Create a Login Session Using a SAML Identity Provider

This example shows a login request and response for a user of a SAML identity provider logging in to the

Finance organization of a cloud whose login URL is https://vcloud.example.com/api/sessions. The user

name is included in the encoded credentials.

Request:

POST https://vcloud.example.com/api/sessions Authorization: SIGN token=" Accept: application/*+xml;version=5.1

compressed-encoded-credentials

Response:

",org="Finance"

VMware, Inc. 47

vCloud API Programming Guide

This response includes the following link types:

orgList

A link to the list of organizations that you can access. See “Retrieve a List of

Organizations Accessible to You,” on page 48.

vcloud

A link to administrative objects and operations. See Chapter 6, “Creating and

Managing Organizations,” on page 129

vmwExtension

A link to the vCloud API extensions, accessible to a system administrator. See

Chapter 7, “Managing and Monitoring a Cloud,” on page 193.

queryList

A link to the set of typed queries you can run. See Chapter 9, “Using the Query

Service,” on page 247.

entity

A link to the entity resolver. See “Retrieve an Object as an Entity,” on page 312.

Retrieve a List of Organizations Accessible to You

A successful login request returns a Session element, which contains a link to a list of all organizations that you are permitted to access.

Every authenticated user has an associated Session object that contains one or more Link elements. The set of

Link elements in your Session is based on your role and privileges. Each of these elements includes a URL that

you can use with a GET request to explore a subset of objects in the cloud.

All Session elements include a link that you can use to retrieve an OrgList element. For an ordinary user, this list includes just the organization to which the user logged in. For an organization administrator or system administrator, the list includes all organizations in the cloud.

Prerequisites

Create a login session. See “Create a Login Session Using the Integrated Identity Provider,” on page 44.

Procedure

1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET https://vcloud.example.com/api/session

48 VMware, Inc.

Chapter 3 Exploring a Cloud

2 Examine the contents of the Session element to locate the link to the organization list.

This link has the following form:

3 Retrieve the list of organizations by making a GET request to the href value of the Link.

See “Example: Retrieve an Organization List,” on page 49.

Example: Retrieve an Organization List

Request:

GET https://vcloud.example.com/api/org

The request returns an OrgList element similar to the one shown here. Additional Org elements are returned only when a system administrator makes the request.

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.orgList+xml ... <OrgList xmlns="http://www.vmware.com/vcloud/v1.5" type="application/vnd.vmware.vcloud.orgList+xml" href="https://vcloud.example.com/api/org"> <Org type="application/vnd.vmware.vcloud.org+xml" name="ExampleOrg" href="https://vcloud.example.com/api/org/5" /> <Org ... /> <Org ... /> </OrgList>

Retrieve an Administrative View of a Cloud

A successful login by an organization or system administrator returns a Session element that contains a link that you can use to retrieve a VCloud element. The VCloud element provides access to a cloud-wide namespace of objects that an organization administrator can view and, in most cases, modify.

The primary administrative objects in a cloud include organizations, provider vDCs, rights, roles, and external networks. Each object type is represented in a VCloud element by zero or more references. The vCloud API defines several objects that are used only in administrative operations. Some, like User, Group, and Role, are unique to administrative operations. Others extend common vCloud API objects to add elements and attributes that only administrators can view or modify. An AdminOrg, for example, provides an administrative view of an Org, and an AdminVdc does the same thing for a Vdc.

A system administrator can obtain more information about any of these objects by making a GET request to its URL, which is the value of its href attribute.

The vCloud element includes links that enable a system administrator to add organizations and roles. Subordinate objects such as users, catalogs, and vDCs are contained by individual organizations and not listed at this level.

VMware, Inc. 49

vCloud API Programming Guide

Prerequisites

Use the credentials of an organization administrator or system administrator to create a login session. See

“Create a Login Session Using the Integrated Identity Provider,” on page 44.

Procedure

1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET https://vcloud.example.com/api/session

2 Examine the contents of the Session element to locate the link to the VCloud object.

This link has the following form:

3 Retrieve the VCloud element by making a GET request to the href value of the Link described in Step 2.

See “Example: Retrieve an Administrative View of a Cloud,” on page 50

Example: Retrieve an Administrative View of a Cloud

Request:

GET https://vcloud.example.com/api/admin

Response:

200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml ... <VCloud xmlns="http://www.vmware.com/vcloud/v1.5" name="vCloud" href="https://vcloud.example.com/api/admin"> <Link rel="add" type="application/vnd.vmware.admin.role+xml" href="https://vcloud.example.com/api/admin/roles" /> <Link rel="add" type="application/vnd.vmware.admin.organization+xml" href="https://vcloud.example.com/api/admin/orgs" /> <Link rel="down" type="application/vnd.vmware.admin.systemOrganization+xml" name="System" href="https://vcloud.example.com/api/admin/org/99" /> <Link ... /> ... <Description>Example Corporation’s vCloud</Description> <OrganizationReferences> <OrganizationReference type="application/vnd.vmware.admin.organization+xml" name="Engineering"

50 VMware, Inc.

href="https://vcloud.example.com/api/admin/org/1"/> <OrganizationReference type="application/vnd.vmware.admin.organization+xml" name="Engineering" href="https://vcloud.example.com/api/admin/org/44"/> <OrganizationReference ... /> ... </OrganizationReferences> <ProviderVdcReferences> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="https://vcloud.example.com/api/admin/providervdc/2" /> <ProviderVdcReference ... /> ... </ProviderVdcReferences> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml name="vApp_Deploy" href="https://vcloud.example.com/api/admin/right/3" /> <RightReference type="application/vnd.vmware.admin.right+xml name="Catalog:Sharing" href="https://vcloud.example.com/api/admin/right/7" /> <RightReference ... /> ... </RightReferences> <RoleReferences> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Organization Administrator" href="https://vcloud.example.com/api/admin/role/102" /> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Catalog Creator" href="https://vcloud.example.com/api/admin/role/103" /> <RoleReference /> </RoleReferences> <Networks> <Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="https://vcloud.example.com/api/admin/network/7" /> <Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC2" href="https://vcloud.example.com/api/admin/network/33" /> </Networks> </VCloud>

Chapter 3 Exploring a Cloud

VMware, Inc. 51

vCloud API Programming Guide

Retrieve a List of vSphere Platform Operations and Objects for a Cloud

A successful login by a system administrator returns a Session element that contains a link that you can use to retrieve a VMWExtension element.

Every vCloud Director installation depends on vSphere platform resources such as vCenter, ESX/ESXi, and vShield Manager. The VMWExtension element provides access to a cloud-wide namespace of vSphere platform objects that are registered for use by the cloud, and links that allow you to add vSphere servers and related resources such as networks and resource pools to your cloud. The administrative extensions to the vCloud API provide a system administrator with programmatic access to these resources.

Prerequisites

Use the credentials of a system administrator to create a login session. See “Create a Login Session Using the

Integrated Identity Provider,” on page 44.

Procedure

1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET https://vcloud.example.com/api/session

2 Examine the contents of the Session element to locate the link to the VMWExtension object.

This link has the following form:

3 Retrieve the list of organizations by making a GET request to the href value of the Link described in

Step 2.

The request returns a VMWExtension element, as shown in “Example: Retrieve a List of vSphere Platform

Operations and Objects for a Cloud,” on page 52.

Example: Retrieve a List of vSphere Platform Operations and Objects for a Cloud

Request:

GET https://vcloud.example.com/api/admin/extension

The response is a VMWExtension element containing a number of Link elements. This example shows only a subset of VMWExtension contents.

Response:

200 OK Content-Type: application/vnd.vmware.admin.vmwextension+xml ... <vmext:VMWExtension xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5" xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" type="application/vnd.vmware.admin.vmwExtension+xml"> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwProviderVdcReferences+xml" href="https://vcloud.example.com/api/admin/extension/providerVdcReferences" /> <vcloud:Link

52 VMware, Inc.

Chapter 3 Exploring a Cloud

rel="down" type="application/vnd.vmware.admin.vmwExternalNetworkReferences+xml" href="https://vcloud.example.com/api/admin/extension/externalNetworkReferences" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwNetworkPoolReferences+xml" href="https://vcloud.example.com/api/admin/extension/networkPoolReferences" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwVimServerReferences+xml" href="https://vcloud.example.com/api/admin/extension/vimServerReferences" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwHostReferences+xml" href="https://vcloud.example.com/api/admin/extension/hostReferences" /> <vcloud:Link ... /> ... <vcloud:Link rel="down" type="application/vnd.vmware.admin.extensionServices+xml" href="https://vcloud.example.com/api/admin/extension/service" /> </vmext:VMWExtension>

VMware, Inc. 53

vCloud API Programming Guide

54 VMware, Inc.

Provisioning an Organization 4

The vCloud API provides several ways for you to make vApp templates, vApps, media images, and idependent disks available to users in an organization.

The vCloud API allows you to upload and download OVF packages, and upload media images. Operations are characterized as uploads when they transfer content from the local host to a remote host, and as downloads when the local host requests the transfer of content from a remote host. A POST request initiates an upload, and a GET request initiates a download. The vCloud Director transfer service facilitates uploads and downloads and provides temporary storage for files. After they are uploaded, you can add templates and media images to catalogs to make them available to other users.

In addition to uploading, you can use the following operations to provision an organization with vApp templates, vApps, and media images:

Cloning

The vCloud API clone operation creates a copy of a vApp, vApp template, or media image. You can specify whether to delete the source object after the operation completes. Deleting the source object after cloning it moves or renames it. You can add cloned templates and media images to catalogs.

Capturing

The vCloud API capture operation creates a vApp template from a vApp. You can add the captured template to a catalog or download it as an OVF package.

Importing

A system administrator can import a virtual machine from a vCenter server that is registered to the cloud. You can import the virtual machine as a vApp or as a vApp template. You can add an imported template to a catalog or download it as an OVF package.

You can also create independent disks that are contained by an organization vDC and can be connected to any virtual machine in that vDC.

This chapter includes the following topics:

“Summary of vCloud API Provisioning Requests,” on page 56

“Upload an OVF Package to Create a vApp Template,” on page 57

“Download a vApp Template as OVF,” on page 66

“Upload a Media Image,” on page 69

“Copying and Moving with the vCloud API,” on page 71

“Capturing and Importing vApps,” on page 72

VMware, Inc.

“Cataloging vApp Templates and Media Images,” on page 72

“Creating and Using Independent Disks,” on page 75

“View or Change the Owner of an Object,” on page 79

vCloud API Programming Guide

Summary of vCloud API Provisioning Requests

Provisioning requests add vApp templates and media to a vDC and a catalog. You can also use provisioning requests to copy, move, rename, and delete these objects.

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

Table 4-1. Summary of Provisioning Requests

Operation Request Request Body Response

Upload OVF to create a vApp template.

Download a vApp template as OVF.

Enable a vApp template for download.

Disable a vApp template for download.

Upload a media image. POST API-

Copy or move a media image. POST API-

Copy or move a vApp template.

Copy or move a vApp. POST API-

Change the name or description of a vApp template.

Change the name or description of a media image.

Delete a vApp template, vApp, or media image.

Add an item to a catalog. POST API-

POST API-URL/vdc/id/ action/uploadVAppTempla te

GET download-URL None Depends on file type

POST API- URL/vAppTemplate/ vAppTemplateid/action/enableDownload

POST API- URL/vAppTemplate/ vAppTemplate-

id/action/disableDownload

URL/vdc/id/media

URL/vdc/ id/action/cloneMedia

POST APIURL/vdc/id/action/

cloneVAppTemplate

URL/vdc/ id/action/cloneVApp

PUT APIURL/vAppTemplate/vappT

emplate-id

PUT API-URL/media/id

DELETE object-URL None

URL/catalog/ id/catalogItems

UploadVAppTemplateParamsVAppTemplate

None

None 204 No Content

Media Media

CloneMediaParams Media

CloneVAppTemplateParamsVAppTemplate

CloneVAppParams VApp

VAppTemplate Task

Media Task

CatalogItem CatalogItem

Task

56 VMware, Inc.

Chapter 4 Provisioning an Organization

Table 4-1. Summary of Provisioning Requests (Continued)

Operation Request Request Body Response

Remove an item from a catalog.

Control access to catalogs. POST API-

Retrieve the owner of a media object.

Retrieve the owner of a vApp template.

Retrieve the owner of a vApp. GET API-

Update the owner of a vApp. PUT API-

Create an independent disk in a vDC. [NEW]

Retrieve properties of an independent disk. [NEW]

Update an independent disk in a vDC. [NEW]

Retrieve a list of all virtual machines attached to an independent disk. [NEW]

Delete an independent disk. [NEW]

DELETE API-URL/ catalog/id/catalogItem/id

URL/catalog/ id/action/controlAccess

GET APIURL/media/id/owner

GET APIURL/vAppTemplate/vappT emplate-id/owner

URL/vApp/id/owner

POST API-URL/vdc/id/ disk

GET API-URL/disk/id None

POST API-URL/disk/id

GET API- URL/disk/id/attachedVms

DELETE API-URL/disk/id None

None 204 No content

ControlAccessParams ControlAccessParams

None

Owner

DiskCreateParams Disk

Disk Disk

None

Owner

204 No Content

Disk

Vms

Task

Upload an OVF Package to Create a vApp Template

A vCloud API client that has access to an OVF package can use a standard workflow to upload the package and create a vApp template.

The initial configuration of a vApp is established in the OVF package on which its source template is based. In the vCloud API, vApp templates are based OVF 1.0, an open standard format. For more information about OVF and how the vCloud API uses it, see “About OVF,” on page 81.

An OVF package includes several kinds of files.

An OVF descriptor

Virtual disk files

An optional certificate

An optional manifest

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.

The descriptor lists these files and includes information about their format.

You can use this file to certify the authenticity of the package.

Contains a SHA-1 digest of each of the files in the package.

VMware, Inc. 57

vCloud API Programming Guide

Upload Workflow

The upload workflow for OVF packages uses a combination of vCloud API requests and standard HTTP file transfer requests.

1 The client uses a POST request that specifies a name and description for the template, and a transfer format

for the data.

2 The server returns an unresolved VAppTemplate element with (status="0") that includes an upload URL

for the OVF descriptor.

3 The client uses an HTTP PUT request to upload the descriptor to the upload URL.

4 The server reads the descriptor and modifies the vAppTemplate to include an upload URL for each file

listed in the References section of the descriptor. While the server is modifying the vAppTemplate, the client makes periodic requests for it and examines the response for additional upload URLs. When the response contains additional upload URLs that were not present in the initial response, template construction 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.

Both monolithic and ranged, or chunked, PUT requests are supported. After starting an upload, a client can make periodic requests to assess its progress. After all of the files are uploaded, and validated if a manifest is present, the server processes them and updates the vApp template. When processing is complete, the server sets the value of the template's status attribute to 8, indicating that it 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 “Object Creation Status,” on page 311.

Restrictions on Uploaded Content

The vCloud Director transfer service 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 that VirtualSystem in the vAppTemplate that the upload creates is rewritten as the first 13 characters of the ovf:id attribute followed by three digits. For example, NewVirtualMachine1 and NewVirtualMachine2 become NewVirtualMac001 and

NewVirtualMac002.

1 Initiating the OVF Upload on page 59

To initiate the OVF upload, a client makes a POST request to the uploadVAppTemplate URL of the target vDC. The request body is an UploadVAppTemplateParams element.

2 Uploading the OVF Descriptor on page 61

You upload the OVF descriptor by making a PUT request to an upload URL and supplying the descriptor’s contents as an Envelope element in the request body. If the request is valid, the server responds with a 200 OK status.

3 Retrieving the Upload URLs on page 62

After an OVF descriptor is uploaded, the server validates it and, if it is valid, updates the corresponding template with upload URLs for each of the files referenced in the descriptor. You must retrieve the template to see these URLs.

58 VMware, Inc.

Chapter 4 Provisioning an Organization

4 Uploading Referenced Files on page 63

You can use a PUT request to upload each file that the vApp template references.

Initiating the OVF Upload

To initiate the OVF upload, a client makes a POST request to the uploadVAppTemplate URL of the target vDC. The request body is an UploadVAppTemplateParams element.

The first step in uploading an OVF package is to request vCloud Director to create a vAppTemplate object to represent the template that will be constructed from the upload. This request returns a response that includes a URL to which you can upload the package's descriptor file.

Prerequisites

Verify that you have the following information:

An OVF package to upload.

You are logged in as a user who has permission to upload OVF packages and create vApp templates.

You know the URL of the target vDC that will receive the upload. Retrieve the XML representation of your organization to see a list of the vDCs that it contains.

Procedure

1 Find the uploadVappTemplate link in the target vDC.

Retrieve the XML representation of the vDC using a request like the one shown in the request portion of

“Example: Deployment Information in a vDC,” on page 30. The response contains an

uploadVappTemplate link, which has the following form:

2 Create an UploadVAppTemplateParams element that specifies a name for the template.

The Description element is optional. Using it to provide a concise description of this object is a best practice. See the request portion of “Example: Initiating the Upload,” on page 59.

3 (Optional) If the OVF package includes a manifest, include a manifestRequired="true" attribute in the

UploadVAppTemplateParams element.

Some OVF packages include a manifest document, which provides a checksum for each file in the package. When the UploadVAppTemplateParams element includes a manifestRequired="true" attribute, the set of

File elements returned after you upload the OVF descriptor includes one for the manifest itself.

4 Make an HTTP POST request to the uploadVAppTemplate link that you retrieved in Step 1, supplying the

UploadVAppTemplateParams element in the request body.

See the request portion of “Example: Initiating the Upload,” on page 59.

5 Examine the response.

The response, a VAppTemplate element, contains a File element that specifies an upload URL for the package's OVF descriptor. See the response portion of “Example: Initiating the Upload,” on page 59.

The server creates a new VAppTemplate object in the target vDC and returns the object's XML representation in the response. See the response portion of “Example: Initiating the Upload,” on page 59.

Example: Initiating the Upload

This example assumes an OVF package that has no manifest.

VMware, Inc. 59

vCloud API Programming Guide

Request:

POST https://vcloud.example.com/api/vdc/5/action/uploadVAppTemplate Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <UploadVAppTemplateParams name="Ubuntu Template" xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Ubuntu vApp Template</Description> </UploadVAppTemplateParams>

Response:

201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" ovfDescriptorUploaded="true" goldMaster="false" status="0" name="Ubuntu Template" id="urn:vcloud:vapptemplate:268" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml"> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"/> <Link rel="remove" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" /> <Description>Ubuntu vApp Template</Description> <Files> <File name="descriptor.ovf" bytesTransferred="0"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../descriptor.ovf" /> </File> </Files> <Owner> ... </Owner> <Children /> <LeaseSettingsSection> ... </LeaseSettingsSection> <CustomizationSection> ... </CustomizationSection> </VAppTemplate>

60 VMware, Inc.

Chapter 4 Provisioning an Organization

The response body includes the following attributes:

An href attribute whose value is a link to the new VAppTemplate object.

An ovfDescriptorUploaded attribute with a value of false, indicating that the OVF descriptor file is not uploaded.

A status attribute with a value of 0, indicating that the file references in the descriptor are not uploaded. (A VAppTemplate with a status of 0 is said to be unresolved.)

A goldMaster attribute, initially set to false.

An id attribute. See “Objects, References, and Representations,” on page 12.

The response body also includes a File element with an upload URL (rel="upload:default") for the OVF descriptor. The server creates the name attribute of this File element, which specifies a container that the server creates to receive the contents of the descriptor. The name attribute has no relation to the file name of the descriptor in the client’s file system.

In addition to the File element, the response includes Owner, Children, LeaseSettingsSection, and

CustomizationSection elements that the server creates and sets to their default contents. For more information

about these elements, see the schema reference.

Uploading the OVF Descriptor

OK status.

Prerequisites

Verify that you initiated the upload with an uploadVAppTemplate request and received an upload URL for the descriptor. See “Initiating the OVF Upload,” on page 59.

Procedure

1 Upload the OVF descriptor.

Make a PUT request to the upload URL returned in the response to the uploadVAppTemplate request, and supply the OVF descriptor as the request body. The OVF descriptor contains a single Envelope element.

2 Verify that the request succeeded.

A response of the following form indicates that the request was valid and is being processed:

200 OK

Example: Uploading the OVF Descriptor

Request:

PUT https://vcloud.example.com/transfer/.../descriptor.ovf Content-Type text/xml ... <?xml version="1.0" encoding="UTF-8"?> <Envelope xmlns="http://schemas.dmtf.org/ovf/envelope/1" ... > ... </Envelope>

Response:

200 OK

VMware, Inc. 61

vCloud API Programming Guide

Retrieving the Upload URLs

Procedure

1 Retrieve the VAppTemplate to verify that the OVF descriptor is uploaded.

Use the URL returned in the response to your uploadVAppTemplate request. See the request portion of

“Example: Upload URLs in a vAppTemplate,” on page 62.

2 Verify that the value of the template's ovfDescriptorUploaded attribute is true.

3 Examine the template to find the upload URLs for the files referenced in the OVF descriptor.

These URLs are contained in Link elements where rel="upload:default".

Example: Upload URLs in a vAppTemplate

This request uses the vApp template URL returned in “Example: Initiating the Upload,” on page 59.

Request:

GET https://vcloud.example.com/api/vAppTemplate/vappTemplate-268

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" ovfDescriptorUploaded="true" goldMaster="false" status="0" name="Ubuntu Template" id="urn:vcloud:vapptemplate:268" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml"> ... <Description>Ubuntu vApp Template</Description> <Files> <File size="3940" bytesTransferred="3940" name="descriptor.ovf"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../descriptor.ovf"/> </File> <File size="1024" bytesTransferred="0" name="manifest.mf"> <Link rel="upload:default"

62 VMware, Inc.

Chapter 4 Provisioning an Organization

href="https://vcloud.example.com/transfer/.../manifest.mf"/> </File> <File size="1950489088" bytesTransferred="0" name="disk0.vmdk"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../disk0.vmdk"/> </File> </Files> ... </VAppTemplate>

In this example, which omits most of the additional elements shown in “Example: Initiating the Upload,” on page 59, the ovfDescriptorUploaded attribute has a value of true and the status attribute has a value of 0. If the descriptor fails validation, 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 where 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 begun. In the File element that references the OVF descriptor, the value of the bytesTransferred attribute is equal to the value of the size attribute, indicating that all the bytes in the descriptor were transferred.

name

The file name, taken from the href attribute of the File element in the OVF descriptor.

NOTE Upload URLs remain valid while a transfer session is in progress, and for a maximum of 60 minutes of transfer session idle time. A system administrator can change this default value. See “Retrieve or Update

System Settings,” on page 197.

Uploading Referenced Files

You can use a PUT request to upload each file that the vApp template references.

Prerequisites

Verify that you uploaded the OVF descriptor. See “Uploading the OVF Descriptor,” on page 61.

Retrieve the upload URLs for all files in the package. See “Retrieving the Upload URLs,” on page 62.

Procedure

1 Find the upload:default URL for the file you want to upload.

2 Use the upload:default URL to construct a PUT request for the file.

The request specifies an upload URL and a content length in bytes. See “Example: Uploading File

Data,” on page 64.

VMware, Inc. 63

vCloud API Programming Guide

After all the files are uploaded, the vApp template is complete, and has a status attribute value of 8. If the upload included a manifest file, the server checks each file in the upload to verify that its checksum matches the one stated in the manifest. If a checksum does not match, the template’s status attribute is set to -1 and the template contains a Task element whose Error element indicates the reason for the failure.

Example: Uploading File Data

This example shows an upload request for one of the files that an OVF package requires. The upload request is a Content-Length header followed by the serialized file content.

Request:

PUT https://vcloud.example.com/transfer/.../disk0.vmdk Content-length: 1950489088

...serialized contents of file disk0.vmdk...

EOF

Response:

200 OK

Monitoring the Progress of an Upload

After you initiate the upload of a file referenced by a vApp template, you can monitor the progress of the upload by periodically retrieving the vApp template and tracking the value of the file's bytesTransferred attribute.

To monitor the progress of an upload, you can watch the bytesTransferred attribute of the file. Each File element in the template includes a bytesTransferred attribute whose value indicates the number of bytes that the server received.

Prerequisites

Verify that you initiated the upload of a file referenced by the vApp template.

Procedure

1 Make a GET request specifying the URL of the vApp template.

See the request portion of “Example: Monitoring the Progress of an Upload,” on page 64.

2 Compare the values of the size and the bytesTransferred attributes of each File element.

When these two values are equal, the file transfer is complete.

After all the files are uploaded, the response includes final values for the bytesTransferred attribute of each

File, and a Task that tracks the events leading up to resolution of the template with the uploaded files, as

shown in “Example: Monitoring the Progress of an Upload,” on page 64.

Example: Monitoring the Progress of an Upload

Request:

GET https://vcloud.example.com/api/vAppTemplate/vappTemplate-268

The complete VAppTemplate body is returned. This example omits most of it for clarity.

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate

64 VMware, Inc.

... name="Ubuntu Template" id="urn:vcloud:vapptemplate:268" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ... > ... <Files> ... <File size="1950489088" bytesTransferred="500000000" name="disk0.vmdk"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../disk0.vmdk"/> </File> </Files> ... </VAppTemplate>

Using Ranged PUT requests to Complete a Partial Upload

Chapter 4 Provisioning an Organization

You typically need ranged PUT requests for very large uploads, especially when network bandwidth or latency might cause the operation to time out.

If the response to an upload progress request indicates that the upload terminated before it was complete, you can use the size and bytesTransferred values from the response to construct a ranged PUT request of the remaining contents, as shown in “Example: Ranged PUT Request to Complete a Partial Upload,” on page 65.

Procedure

1 Retrieve the VAppTemplate and find the File element that references the partially uploaded file.

2 Make a PUT request that specifies a Content-Range and Content-Length and includes the serialized

contents of the range.

For Content-Range, specify the value of the File element's bytesTransferred attribute for the low end of the range and the value of its size attribute for the high end of the range. For Content-Length, subtract the value of the File element's bytesTransferred attribute from the value of its size attribute.

Example: Ranged PUT Request to Complete a Partial Upload

The following request completes the upload of the file disk0.vmdk shown in this fragment of a VAppTemplate.

VMware, Inc. 65

vCloud API Programming Guide

Request:

PUT https://vcloud.example.com/transfer/.../disk0.vmdk Content-Range: bytes 500000000-1950489087/1950489088 Content-Length: 1450489088

...serialized contents of specified range...

EOF

Response:

200 OK

Download a vApp Template as OVF

You can download a vApp template as an OVF package. After you find the template by browsing a catalog, you can request that the template be enabled for download.

When you enable a vApp template for download, the server performs several operations to create an OVF package and make it available to the transfer service.

1 The server reconstructs the OVF descriptor using information in the vApp template. The server excludes

any deployment-specific information that the template contains, and populates the descriptor's

References element with links to files, such as .vmdk files, that are part of the package.

2 The server copies the reconstructed OVF descriptor to transfer service storage, along with all files that the

OVF descriptor references.

3 The server updates the vAppTemplate with a link that contains a URL from which you can retrieve the OVF

descriptor.

After the template is enabled for download, you can retrieve it to see the download:default URL for the descriptor, then parse the descriptor to find the URLs from which you can retrieve the referenced files.

1 Enable the vApp Template for Download on page 66

Before you can download a vApp template, an administrator or privileged user must explicitly enable it for download.

2 Download the OVF Descriptor on page 68

To download the OVF descriptor, you make a GET request to the download:default URL in the download-enabled VappTemplate.

3 Download a Referenced File on page 68

After you download the OVF descriptor of a vApp template, you can examine the contents of the descriptor to discover download URLs for files that the template references.

Enable the vApp Template for Download

Before you can download a vApp template, an administrator or privileged user must explicitly enable it for download.

Prerequisites

Verify that you are logged in as an administrator or other user who has privileges to enable vApp template for download.

66 VMware, Inc.

Chapter 4 Provisioning an Organization

Procedure

1 Retrieve the template to find its action/enableDownload link.

Every vApp template includes a link of the following form, where id is the id of the template:

2 Enable the template for download.

Make a POST request to the template's action/enableDownload URL.

Request:

POST https://vcloud.example.com/api/vAppTemplate/vappTemplate-268/action/enableDownload

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Enabling download of Virtual Application Template Ubuntu Template (268)" ... > ... </Task>

The Task in the response tracks the creation of the download package.

3 When the task completes, retrieve the template, which now contains a download URL for the OVF

descriptor.

This URL remains valid while a transfer session is in progress, and for a maximum of 60 minutes of transfer session idle time. A system administrator can change this default value. See “Retrieve or Update System

Settings,” on page 197.

Example: vApp Template with Download URL for OVF Descriptor

Request:

GET https://vcloud.example.com/api/vAppTemplate/vappTemplate-268

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template" ... > ... <Link type="text/xml" rel="download:default" href="https://vcloud.example.com/transfer/.../descriptor.ovf"/> ... </VAppTemplate>

VMware, Inc. 67

vCloud API Programming Guide

Download the OVF Descriptor

To download the OVF descriptor, you make a GET request to the download:default URL in the downloadenabled VappTemplate.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Verify that you have a vApp template that is enabled for download. See “Enable the vApp Template for

Download,” on page 66.

Procedure

1 Examine the VAppTemplate to find the the download:default URL for the descriptor.

2 Make a GET request to the download:default URL to retrieve the descriptor

See “Example: Downloading the OVF Descriptor,” on page 68.

Example: Downloading the OVF Descriptor

This example downloads the OVF descriptor from the URL shown in the href value of the Link shown in

“Example: vApp Template with Download URL for OVF Descriptor,” on page 67. The response includes the

entire Envelope element, only part of which appears here.

Request:

GET https://vcloud.example.com/transfer/..../descriptor.ovf

Response:

200 OK Content-Type text/xml ... <Envelope xmlns="http://schemas.dmtf.org/ovf/envelope/1" ... > ... </Envelope>

Download a Referenced File

After you download the OVF descriptor of a vApp template, you can examine the contents of the descriptor to discover download URLs for files that the template references.

The OVF descriptor that you download from a vApp template includes the names of files that the template references. To retrieve one of these files, you must create a download URL for it by combining its name with a URL derived from the download URL that you used to retrieve the descriptor. You must retrieve all of the files to create a valid OVF package.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Retrieve the OVF descriptor of a vApp template that was enabled for download.

68 VMware, Inc.

Chapter 4 Provisioning an Organization

Procedure

1 For each File element in the References element of the descriptor, construct a download URL.

a Start with the URL that you used to download the descriptor.

This URL is the href value of the download:default link that the template contains.

b Replace the final component of that URL with the value of the href attribute of the File element.

2 Use the constructed URLs to download each file.

See “Example: Downloading a Referenced File,” on page 69.

Example: Downloading a Referenced File

The request URL shown in this example combines the URL used in the request portion of

“Example: Downloading the OVF Descriptor,” on page 68 with the file name shown in this File element:

Request:

GET https://vcloud.example.com/transfer/..../disk0.vmdk

Response:

200 OK ...

...serialized contents of file disk0.vmdk...

EOF

NOTE The downloaded package is valid only if the descriptor and all of its referenced files maintain the same relationship in the local file system that they had on the transfer server file system. In this case, the descriptor and disk0.vmdk were both in the same directory, which is the default arrangement.

Upload a Media Image

The vCloud API supports uploading virtual media such as CD-ROM and floppy disk images.

The workflow for uploading media images is similar to the one described in “Upload an OVF Package to Create

a vApp Template,” on page 57.

NOTE You cannot download media images.

Prerequisites

Verify that the following conditions are met:

You have a media image to upload.

You are logged in as a user who has permission to upload media images.

You know the URL of the target vDC that will receive the upload. Retrieve the XML representation of your organization to see a list of the vDCs that it contains.

VMware, Inc. 69

vCloud API Programming Guide

Procedure

1 Find the add link for media in the target vDC.

This link has the following form:

2 POST a media request to the server.

The request body is a Media element that includes information about the virtual media item to upload. See the request portion of “Example: Upload a Media Image,” on page 70.

The server uses this information to create a Media object, then returns a representation of the object that contains an upload URL. See the response portion of “Example: Upload a Media Image,” on page 70.

3 PUT the media file contents to the upload:default link in the response.

The procedure is the same as the one shown in “Uploading Referenced Files,” on page 63.

Example: Upload a Media Image

Request:

POST https://vcloud.example.com/api/vdc/5/media Content-Type: application/vnd.vmware.vcloud.media+xml ... <?xml version="1.0" encoding="UTF-8"?> <Media xmlns="http://www.vmware.com/vcloud/v1.5" name="database.iso" size="51242131" imageType="iso"> <Description>ISO database image</Description> </Media>

In addition to the File element that contains the upload:default URL, the response includes an Owner element and several Link elements that the server creates.

Response:

Content-Type: application/vnd.vmware.vcloud.media+xml 201 Created ... <Media xmlns="http://www.vmware.com/vcloud/v1.5" size="3121215488" imageType="iso" status="0" name="database.iso" id="urn:vcloud:media:254" type="application/vnd.vmware.vcloud.media+xml" href="https://vcloud.example.com/api/media/254" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5" /> <Link

70 VMware, Inc.

rel="remove" href="https://vcloud.example.com/api/media/254" /> <Description>ISO database image</Description> <Files> <File size="51242131" bytesTransferred="0" name="file"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../file" /> </File> </Files> <Owner ... </Owner> </Media>

Copying and Moving with the vCloud API

The vCloud API provides object-specific copy operations, implemented by clone actions, for media images, vApp templates, and vApps. With these operations, you can create a copy of the object in the same vDC or in another vDC in the same organization.

Chapter 4 Provisioning an Organization

vCloud API copy operations support an option to delete the source object after the copy is complete. Doing so when the source and target objects are in different vDCs moves the source object to the target vDC. Doing so when the source and target objects are in the same vDC renames the source object. The vCloud API does not include an explicit move operation. 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 copied 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.

For more information and an example, see the cloneMedia operation in the schema reference.

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.

For more information and an example, see the cloneVAppTemplate operation in the schema reference.

VMware, Inc. 71

vCloud API Programming Guide

Copy or Move a vApp

The cloneVApp request makes a copy of the vApp referenced in the Source element of the request body. The request specifies a new name and, optionally, a new description for the copy. The request can optionally include an IsSourceDelete element whose value specifies whether to delete the source vApp after the copy is complete. 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.

NOTE You cannot copy or move a vApp that is deployed.

For more information and an example, see the cloneVApp operation in the schema reference.

Capturing and Importing vApps

You can capture a vApp to create a vApp template from it. If you are a system administrator, you can also import vApps and vApp templates from vSphere.

Every vDC includes a Link of the following form:

You can POST a CaptureVAppParams request to this link to capture an undeployed vApp. The operation returns a VAppTemplate that you can add to a catalog. Instantiating this template recreates the vApp from which it was captured. Most elements of a vApp template are read-only, but you can instantiate a template, modify the resulting vApp, and then capture it to create a modified version of the template.

For more information and an example, see the captureVApp operation in the schema reference.

Importing vApps or vApp Templates from vSphere

A system administrator can import vApps and vApp templates from vSphere. See “Import a Virtual Machine

from vCenter,” on page 228.

Cataloging vApp Templates and Media Images

Catalogs can contain references to vApp templates and media images. A system administrator or a privileged member of the organization that owns the catalog can create and remove these references.

Although you can retrieve references to vApp templates and media images directly from the vDC to which they were uploaded, it is common practice to place references to such assets in one of an organization’s catalogs. When you place the references in a catalog, the assets are easier to discover, because a catalog can include assets from all vDCs in an organization. You also have more flexible administrative control over them, because you can restrict access to catalogs and the items in them 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, you cannot instantiate a vApp template that is not included in a catalog. A media image that is not included in a catalog cannot be copied or inserted by anyone but its owner.

72 VMware, Inc.

Chapter 4 Provisioning an Organization

Add an Item to a Catalog

A catalog can contain references to vApp templates and media images from any vDC in an organization. A vApp template or media image can be listed in at most one catalog.

Prerequisites

Verify that you are logged in as a user with the Catalog Author role, as an organization administrator, or as a system administrator.

Procedure

1 Retrieve the XML representation of your organization and look for links to the catalogs and vDCs it

contains.

Links to catalogs have the following form:

Links to vDCs have the following form:

2 Browse the vDCs in your organization to find the ResourceEntity element that represents the item to add

to the catalog.

Resource entities are contained in the ResourceEntities element of a Vdc .

3 Retrieve the XML representation of the catalog to which to add the item.

Use a request like this one:

GET https://vcloud.example.com/api/catalog/32

VMware, Inc. 73

vCloud API Programming Guide

4 Examine the response to locate the Link element that contains the URL for adding items to the catalog.

This element has a rel attribute value of add and a type attribute value of

application/vnd.vmware.admin.catalogItem+xml, as this example shows:

5 Create a CatalogItem element that contains a reference to the ResourceEntity

See “Example: ResourceEntity and Corresponding CatalogItem,” on page 74 for an example.

6 POST the CatalogItem body to the catalog's rel="add" URL.

Step 4 explains how to find this URL.

Example: ResourceEntity and Corresponding CatalogItem

This example starts with this ResourceEntity, which references a vApp template.

Follow these guidelines to create a CatalogItem from a ResourceEntity.

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 that the ResourceEntity element references, or you can create a Description element.

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.

This request creates the catalog item that is retrieved in “Example: Retrieve a Catalog Item,” on page 29. The response contains information extracted from the request, and includes links that an administrator or catalog owner can use to manage the CatalogItem.

Request:

POST https://vcloud.example.com/api/catalog/32/catalogItems Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <?xml version="1.0" encoding="UTF-8"?> <CatalogItem name="Ubuntu Template with vsftpd" type="application/vnd.vmware.vcloud.catalogItem+xml" xmlns="http://www.vmware.com/vcloud/v1.5"> <Description>Approved template for public FTP sites</Description> <Entity href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111"/> </CatalogItem>

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem

74 VMware, Inc.

Chapter 4 Provisioning an Organization

xmlns="http://www.vmware.com/vcloud/v1.5" name="Ubuntu Template with vsftpd" id="urn:vcloud:catalogitem:221" href="https://vcloud.example.com/api/catalogItem/221" ... > <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32" /> <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/catalogItem/221/metadata" /> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud.example.com/api/catalogItem/221" /> <Link rel="remove" href="https://vcloud.example.com/api/catalogItem/221" /> <Description>Approved template for public FTP sites</Description> <Entity href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> </CatalogItem>

Remove an Item from a Catalog

An organization administrator or a user with adequate permissions can remove a CatalogItem by making a DELETE request to its rel="remove" link.

For more information and an example, see the catalogItem operation in the schema reference.

Prerequisites

Verify that you are logged in as a user with the Catalog Author role, as an organization administrator of the organization that owns the catalog, or as a system administrator.

Procedure

1 Retrieve the catalog item from the catalog.

2 Locate the rel="remove" link in the CatalogItem element.

3 Make a DELETE request to the href value of the rel="remove" link in the CatalogItem.

Creating and Using Independent Disks

Independent disks are stand-alone virtual disks that you create in organization vDCs. Administrators and users who have adequate rights can create, remove, and update independent disks, and connect them to virtual machines.

When you create an independent disk, it is associated with an organization vDC but not with a virtual machine. After the disk has been created in a vDC, the disk owner or an administrator can attach it to any virtual machine deployed in that vDC. The disk owner can also modify disk properties, detach it from a virtual machine, and remove it from the vDC. The system administrator and organization administrator of the organization that contains the vDC have the same rights to use and modify the disk as the disk owner.

VMware, Inc. 75

vCloud API Programming Guide

Create or Update an Independent Disk

To create an independent disk in an organization vDC, POST a DiskCreateParams element to the vDC's disk link.

To create an independent disk, you must specify its name and size. You can optionally include a description and specify a storage profile to be used by the disk. After you have created the disk, you can modify its name, description, and storage profile.

The owner of a disk is initially the user who created it. To change the owner, see “View or Change the Owner

of an Object,” on page 79.

Procedure

1 Choose an organization vDC to contain the disk.

2 Create a DiskCreateParams element.

You must specify the size (in Megabytes) and name of the independent disk. See the request portion of

“Example: Create an Independent Disk,” on page 76.

3 POST the DiskCreateParams element you created in Step 2 to the URL for adding disks to the organization

vDC.

See the request portion of “Example: Create an Independent Disk,” on page 76.

Example: Create an Independent Disk

This example adds an independent disk to the organization vDC created in “Add a vDC to an

Organization,” on page 140. Because optional attributes busType and busSubType are omitted, a SCSI disk is

created.

Request:

POST https://vcloud.example.com/api/admin/vdc/44/disk Content-Type: application/vnd.vmware.admin.diskCreateParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <DiskCreateParams xmlns="http://www.vmware.com/vcloud/v1.5"> <Disk name="500GB-SCSI" size="500000000"> <Description>500 GB SCSI Disk</Description> </Disk> </DiskCreateParams>

The response, a subset of which appears here, is a Disk element that contains an embedded Task that tracks creation of the disk. Because the request did not specify a storage profile for the disk, it uses the default storage profile for the containing organization vDC. The response also includes Link elements that enable access to disk operations and metadata. While the disk is under construction, its status remains 0.

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.disk+xml ... <?xml version="1.0" encoding="UTF-8"?> <Disk xmlns="http://www.vmware.com/vcloud/v1.5" size="500000000"

76 VMware, Inc.

status="0" name="500GB-SCSI" id="urn:vcloud:disk:128" type="application/vnd.vmware.vcloud.disk+xml" href="https://vcloud.example.com/api/disk/128" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/44" /> <Link rel="remove" href="https://vcloud.example.com/api/disk/128" /> <Link rel="edit" type="application/vnd.vmware.vcloud.disk+xml" href="https://vcloud.example.com/api/disk/128" /> <Link rel="down" type="application/vnd.vmware.vcloud.owner+xml" href="https://vcloud.example.com/api/disk/128/owner" /> <Link rel="down" type="application/vnd.vmware.vcloud.vms+xml" href="https://vcloud.example.com/api/disk/128/attachedVms" /> <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/disk/128/metadata" /> <Description>Independent Disk</Description> <Tasks> <Task ... operationName="vdcCreateDisk" ... > ... </Task> </Tasks> <StorageProfile type="application/vnd.vmware.vcloud.vdcStorageProfile+xml" name="bronze" href="https://vcloud/example.com/api/vdcStorageProfile/128" /> <Owner type="application/vnd.vmware.vcloud.owner+xml"> <User type="application/vnd.vmware.admin.user+xml" href="https://vcloud.example.com/api/admin/user/120" /> </Owner> </Disk>

Chapter 4 Provisioning an Organization

VMware, Inc. 77

vCloud API Programming Guide

Remove an Independent Disk

To remove an independent disk, verify that no powered-on virtual machines are attached to it, then use a DELETE request to delete it.

A Disk element includes a link of the following form, which you can GET to return a list of virtual machines to which the disk is attached.

There are also two queries that you can use to return a list of virtual machines, the disks connected to them, and the vDC that contains them:

vmDiskRelation

AdminvmDiskRelation

Lists this information for Vm and Disk objects that you own.

Lists this information for all Vm and Disk objects in a cloud (system administrators only).

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or the object owner.

Procedure

1 Verify that the independent disk is not connected to any virtual machines.

2 Delete the independent disk.

Make a DELETE request to the URL in the rel="remove" link in the Disk.

The server starts a task to manage the events that lead up to the removal of the object, and returns a Task element that you can use to track the progress of the task.

Example: Remove an Independent Disk

Request:

DELETE https://vcloud.example.com/api/disk/128

Response:

202 Accepted ... <Task ... operation="Deleting Disk (128)" ... > </Task>

78 VMware, Inc.

View or Change the Owner of an Object

You can view the owner of a VApp, VAppTemplate, Disk, or Media object by making a GET request to the object's

owner link. If you have adequate rights, you can change the owner of a Disk or VApp object, but not that of a VAppTemplate or Media object. An administrator can view or change the owner of any object.

The initial owner of a VApp, VAppTemplate, Catalog, Disk, or Media object is the user who created it. Ownership is expressed in an Owner element that the object representation contains. This element includes a User element that references the owner. Object-specific rights to change ownership are included in several predefined roles. See “Predefined Roles and Their Rights,” on page 187.

Prerequisites

To change the owner of a Disk or VApp object, you must be an organization administrator or system administrator, or a user whose role includes the right to change the owner of these objects.

To change the owner of a Catalog object, you must be an organization administrator or the system administrator.

Procedure

1 Retrieve the Owner element from the object.

Chapter 4 Provisioning an Organization

This element includes a reference to the current owner and an edit URL you can use to change the owner. This request retrieves the owner of a vApp.

GET https://vcloud.example.com/api/vApp/vapp-7/owner

2 Modify the Owner element to specify a different User.

The user must be a member of the organization that contains the object.

NOTE You cannot modify the Owner of a Media or VAppTemplate object.

3 To change the owner, make a PUT request to the Owner element's rel="edit" URL and supply an Owner

element in the request body.

The User element in the Owner element references the new owner. See “Example: Change the Owner of a

vApp,” on page 79.

Example: Change the Owner of a vApp

Request:

PUT https://vcloud.example.com/api/vApp/vapp-7/owner Content-type: application/vnd.vmware.vcloud.owner+xml ... <?xml version="1.0" encoding="UTF-8"?> <Owner xmlns="http://www.vmware.com/vcloud/v1.5"> <User type="application/vnd.vmware.admin.user+xml" href="https://vcloud.example.com/api/admin/user/120" /> </Owner>

Response:

204 No Content

VMware, Inc. 79

vCloud API Programming Guide

80 VMware, Inc.

Deploying and Operating vApps 5

The vCloud API supports programmatic access to a range of self-service datacenter operations that allow users to create, configure, deploy, and operate vApps.

The initial configuration of a vApp is established in the OVF package on which its source template is based. In the vCloud API, vApp templates are based on OVF 1.0. 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.

About OVF

OVF is a widely accepted standard format that applies to many virtualization technologies.

Virtual machines and appliances are distributed as OVF packages by many vendors.

Many vendors, including VMware, offer tools that simplify creating and customizing OVF, support converting virtual machines on existing virtualization platforms to OVF, or both.

OVF can express the complex relationships between virtual appliances in enterprise applications. The author of the appliance can handle most of the complexity, rather than the user who deploys 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.

Administrators and advanced users should become familiar with the details of the OVF standard before developing applications with 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.

A 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. The vCloud API does not support uploading or downloading OVA files.

vApp Life Cycle

A vApp contains one or more Vm elements, which represent individual virtual machines. It also contains information that defines operational details for the vApp and the virtual machines that it contains. The vApp lifecycle includes several distinct states:

An OVF package, the form in which vApps are typically distributed.

A vApp template, created when a client uploads an OVF package to a vDC.

VMware, Inc.

vCloud API Programming Guide

An undeployed vApp, created when a vApp template is instantiated without also being deployed, or a deployed vApp is undeployed.

A deployed vApp, ready to be powered on and operated. Instantiation can include deployment, poweron, or both.

Figure 5-1. vApp State Transitions

This chapter includes the following topics:

“Summary of vCloud API vApp and Virtual Machine Operations Requests,” on page 83

“Create a vApp From a Template,” on page 85

“Compose a vApp From Existing Virtual Machines,” on page 87

“Recompose a vApp to Add or Remove Virtual Machines,” on page 90

“Provide User Input Requested by a Virtual Machine,” on page 92

“Attach or Detach an Independent Disk,” on page 93

“Creating and Using vApp Snapshots,” on page 95

82 VMware, Inc.

Chapter 5 Deploying and Operating vApps

“Operate a vApp,” on page 96

“Configuring vApps and Virtual Machines,” on page 97

Summary of vCloud API vApp and Virtual Machine Operations Requests

These vCloud API operations requests create, manage, operate, and delete vApps and the virtual machines that they contain.

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

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)

Vm-URL is a URL of the form API-URL/vApp/vm-id

Table 5-1. Summary of vApp and Virtual Machine Operations Requests

Operation Request Request Body Response

Instantiate a vApp template to create a vApp

Change the name or description of a vApp.

Compose a vApp POST API-URL/vdc/id/

Recompose a vApp to add or remove virtual machines

Deploy a vApp or Virtual Machine

Undeploy a vApp or Virtual Machine

Power On a vApp or Virtual Machine

Power Off a vApp or Virtual Machine

Reset a vApp or Virtual Machine

Suspend a vApp or Virtual Machine

Discard the Suspended State of a vApp or Virtual Machine

Shut Down a vApp or Virtual Machine

POST API-URL/vdc/id/ action/instantiateVAppTe mplate

PUT API-URL/vApp/vapp-

action/composeVApp

POST API- URL/vApp/vapp-id/ action/recomposeVApp

POST VApp-or-Vm- URL/action/deploy

POST VApp-or-Vm- URL/action/undeploy

POST VApp-or-Vm- URL/action/powerOn

POST VApp-or-Vm- URL/action/powerOff

POST VApp-or-Vm- URL/action/reset

POST VApp-or-Vm- URL/action/suspend

POST VApp-or-Vm- URL/action/ discardSuspendedState

POST VApp-or-Vm- URL/action/shutdown

InstantiateVAppTemplat eParams

VApp Task

ComposeVAppParams VApp

RecomposeVAppParams Task

DeployVAppParams Task

UndeployVAppParams Task

None

VApp

Task

VMware, Inc. 83

vCloud API Programming Guide

Table 5-1. Summary of vApp and Virtual Machine Operations Requests (Continued)

Operation Request Request Body Response

Reboot a vApp or Virtual Machine

Retrieve product sections of a vApp or virtual machine

Update product sections of a vApp or virtual machine

Retrieve product sections of a vApp template

Retrieve version of VMware Tools installed on a virtual machine

Install VMware Tools on a virtual machine

Consolidate a virtual machine

Upgrade the hardware version of a virtual machine

Insert Media Into a Virtual Machine

Eject Media from a Virtual Machine

List Media Devices of a Virtual Machine

Get a Request for User Input GET Vm-URL/question None

Provide Requested User Input

Get a Screen Thumbnail for a Virtual Machine

Get a Screen Ticket for a Virtual Machine

Attach an independent disk to a virtual machine. [NEW]

Detach an independent disk from a virtual machine. [NEW]

Create snapshots of all virtual machines in a vApp. [NEW]

Remove snapshots of all virtual machines in a vApp. [NEW]

POST VApp-or-Vm-

None

Task

URL/action/reboot

GET VApp-or-Vm-

None

ProductSectionList

URL/productSections

PUT VApp-or-Vm-

ProductSectionList Task

URL/productSections

GET API-

None

ProductSectionList

URL/vAppTemplate/vappT emplate-id/productSections

GET Vm-

None

RuntimeInfoSection

URL/runtimeInfoSection

POST Vm-

None

Task

URL/action/installVMware Tools

POST Vm-

None

Task

URL/action/consolidate

POST Vm-

None

Task

URL/action/upgradeHardw areVersion

POST Vm-

MediaInsertOrEjectParamsTask

URL/action/insertMedia

POST Vm-

MediaInsertOrEjectParamsTask

URL/action/ejectMedia

GET Vm-URL/

None

RasdItemsList

virtualHardwareSection/m edia

VmPendingQuestion

POST Vm-

VmQuestionAnswer

204 No Content

URL/question/action/answ er

GET Vm-URL/screen None Returns a screen thumbnail

(Content-type: image/png) if one is available. Otherwise returns null (Content-Length:

0).

POST Vm-

None

ScreenTicket

URL/screen/action/acquire Ticket

POST Vm-

DiskAttachOrDetachParamsTask

URL/disk/action/attach

POST Vm-

DiskAttachOrDetachParamsTask

URL/disk/action/detach

POST API-

CreateSnapshotParams Task

URL/vApp/vapp-id/ action/createSnapshot

POST API-

None

Task

URL/vApp/vapp-id/ action/removeAllSnapshots

84 VMware, Inc.

Table 5-1. Summary of vApp and Virtual Machine Operations Requests (Continued)

Operation Request Request Body Response

Revert all virtual machines in a vApp to their current snapshots. [NEW]

Retrieve information about vApp snapshots. [NEW]

Validate the storage profile compliance of a virtual machine. [NEW]

Retrieve a virtual machine storage profile validation report. [NEW]

POST API- URL/vApp/vapp-id/ action/revertToCurrentSna pshot

GET API-URL/vApp/vappid/snapshotSection

POST API-URL/vApp/vmid/action/checkCompliance

GET API-URL/vApp/vmid/complianceResult

Create a vApp From a Template

An instantiateVAppTemplate request creates a vApp from a vApp template. By default, this operation also deploys the vApp and powers it on.

None

Chapter 5 Deploying and Operating vApps

Task

SnapshotSection

Task

ComplianceResult

For an example of a simple instantiation request, see “Deploy the vApp,” on page 31. You can also specify additional parameters as part of instantiation.

Template contents that might influence composition of the request body include the following sections:

A NetworkConnectionSection that specifies network connection details for a virtual machine. Unless you want to create a vApp in which none of the virtual machines are connected to a network, your instantiation parameters must include at least one NetworkConfigSection that defines a vApp network, and that section must include a NetworkConfig element whose networkName attribute value matches the value of the

network attribute of the NetworkConnection of each Vm in the template. If this attribute has the value none

or is missing, the Vm can connect to any network. If the template contains Vm elements that specify different names for their network connections, you must create a vApp network for each.

One or more EulaSection elements that specify licensing terms or other conditions that you must accept before creating the vApp. The InstantiateVAppTemplateParams element can include an

AllEULAsAccepted element whose value indicates whether you accept all EULA terms included in the

template. If a vApp template includes any ovf:EulaSection elements, AllEULAsAccepted must be set to a value of true. Otherwise, instantiation fails.

A LeaseSettingsSection. If this section is present and specifies settings that are appropriate for the vApp, you do not need to modify it. If it is absent or empty, the vApp is created with your organization’s default lease settings. If you specify new lease settings in a LeaseSettingsSection that you provide as part of instantiation, those settings replace any existing settings and override your organization's defaults.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of the vApp template.

Make a GET request to the URL provided in the href attribute of the Entity contained by the

CatalogItem that references the template.

VMware, Inc. 85

vCloud API Programming Guide

2 Examine the template to determine the set of instantiation parameters that the request must include.

3 Create an InstantiateVAppTemplateParams element.

See “Example: Instantiate a vApp Template,” on page 86 for guidelines.

4 Make a POST request to the action/instantiateVAppTemplate URL of the vDC.

Supply the InstantiateVAppTemplateParams element as the request body.

The server takes the requested action and returns a VApp element. The element has a status attribute value of

0, meaning it is unresolved because it is still being constructed. It also contains a Task element that tracks the

progress of the request.

Example: Instantiate a vApp Template

This InstantiateVAppTemplateParams request extends the request shown in “Example: Deploying a vApp,” on page 32 to include additional elements in its InstantiationParams:

A LeaseSettingsSection that specifies custom lease settings, overriding the settings that would otherwise be inherited from the organization.

An acknowledgement of EulaSection acceptance, supplied in the AllEULAsAccepted element. If the template does not include EulaSection elements, you can omit this acknowledgement.

For more information and a list of sections that you can include in InstantiationParams, see “Configuring a

vApp,” on page 98.

Request:

POST https://vcloud.example.com/api/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <InstantiateVAppTemplateParams xmlns="http://www.vmware.com/vcloud/v1.5" name="Linux FTP server" deploy="true" powerOn="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Example FTP Server</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <ParentNetwork href="https://vcloud.example.com/api/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>

86 VMware, Inc.

</LeaseSettingsSection> </InstantiationParams> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" /> <AllEULAsAccepted>true</AllEULAsAccepted> </InstantiateVAppTemplateParams>

The response is a sparsely populated VApp element, as shown in the response portion of “Example: Deploying

a vApp,” on page 32.

Compose a vApp From Existing Virtual Machines

With the vCloud API composeVApp operation, you can build a vApp from existing virtual machines, including virtual machines contained by vApps and vApp templates to which you have access.

Every vDC includes a link to a composeVApp operation, which creates a new vApp in it. To compose a vApp, POST a composeVApp request to this link. The request body is a ComposeVAppParams element, which includes the following information:

An InstantiationParams element that can include any of the section types listed under “Configuring a

vApp,” on page 98. This is where you define the vApp network to which all the virtual machines in the

composed vApp connect, and custom vApp lease settings and startup parameters for the virtual machines.

An optional Description of the composed vApp.

Chapter 5 Deploying and Operating vApps

Zero or more SourcedItem elements, each of which defines a source of virtual machines to include in the composition. Each SourcedItem must contain a Source element that references a composition source, the

href of a Vm, VApp, or VAppTemplate. If the Source element references a virtual machine, the SourcedItem

can include any of the following elements:

An InstantiationParams element specific to that virtual machine. This element can include any of the section types listed under “Configuring a Virtual Machine,” on page 98.

A NetworkAssignment element that specifies how the network connections in the virtual machine are mapped to vApp networks defined in the InstantiationParams element that applies to the composed vApp.

A VAppScopedLocalId element that provides a unique identifier for the virtual machine in the scope of the composed vApp.

If the Source element references a vApp or vApp template, all Vm elements from each composition source become peers in the Children collection of the composed vApp.

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 you can use it.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

VMware, Inc. 87

vCloud API Programming Guide

Procedure

1 Find the composeVApp link in the target vDC.

The XML representation of the vDC contains a composeVapp link, which has the following form:

2 Create a ComposeVappParams element that specifies the details of the composition.

3 POST the ComposeVappParams element to the composeVapp link of the target vDC.

See the Request portion of “Example: Compose a vApp,” on page 88.

Example: Compose a vApp

This request specifies two vAppTemplate items and one Vm item. The Vm item requires InstantiationParams that modify its NetworkConnectionSection to specify the vApp network created for this vApp. The vAppTemplate items inherit this setting from the base InstantiationParams element that appears before the first

SourcedItem is specified.

NOTE Virtual machines specified in Source elements must be powered off or this operation will fail. You can use a query like this one to return a list of references to powered-off virtual machines that you have access to.

https://vcloud.example.com/api/query?type=adminVM&format=references&filter=status==POWERED_OFF

See Chapter 9, “Using the Query Service,” on page 247.

Request:

POST https://vcloud.example.com/api/vdc/5/action/composeVApp Content-Type: application/vnd.vmware.vcloud.composeVAppParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <ComposeVAppParams name="Example Corp’s CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Composed CRM Appliance</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="https://vcloud.example.com/api/network/54" /> <FenceMode>natRouted</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> </InstantiationParams> <SourcedItem> <Source href="https://vcloud.example.com/api/vApp/vm-4" /> <InstantiationParams> <NetworkConnectionSection

88 VMware, Inc.

Chapter 5 Deploying and Operating vApps

xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="https://vcloud.example.com/api/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> </NetworkConnectionSection> </InstantiationParams> </SourcedItem> <SourcedItem> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-114" /> </SourcedItem> <SourcedItem> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-190" /> </SourcedItem> <AllEULAsAccepted>true</AllEULAsAccepted> </ComposeVAppParams>

Response:

201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Example Corp’s CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="https://vcloud.example.com/api/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"/> ... <Description>Composed CRM Appliance</Description> ... <Tasks> <Task operation="Composing Virtual Application Example Corp’s CRM Appliance (33)" ...> ... </Task> </Tasks> </VApp>

VMware, Inc. 89

vCloud API Programming Guide

Recompose a vApp to Add or Remove Virtual Machines

The vCloud API supports recomposition of a vApp to add or remove virtual machines. To recompose a vApp, make a recomposeVApp request, supplying a RecomposeVAppParams element as the request body.

The RecomposeVAppParams element allows an arbitrary number of DeleteItem elements, but is otherwise identical to ComposeVAppParams. 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.

Unlike a composeVapp request, which operates on a vDC and creates a new vApp, a recomposeVapp request operates on (and modifies) an existing vApp.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Find the recomposeVApp link in the target vApp.

The XML representation of a vApp contains a recomposeVapp link, which has the following form:

2 Create a RecomposeVappParams element that specifies the details of the recomposition.

See “Example: Recompose a vApp,” on page 90.

3 POST the RecomposeVappParams element to the recomposeVapp link of the target vApp.

Example: Recompose a vApp

This example uses the recomposeVApp operation to modify this vApp, which contains three virtual machines. Only a few of the elements in the vApp appear here.

<VApp name="Example Corp’s CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="https://vcloud.example.com/api/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"/> ... <Children> <Vm status="8" name="CRM-DB" href="https://vcloud.example.com/api/vApp/vm-7" ...> ... </Vm> <Vm status="8"

90 VMware, Inc.

Chapter 5 Deploying and Operating vApps

name="CRM-CRM" href="https://vcloud.example.com/api/vApp/vm-44" ...> ... </Vm> <Vm status="8" name="CRM-HTTP" href="https://vcloud.example.com/api/vApp/vm-45" ...> ... </Vm> </Children> ... </VApp>

The request removes one of the virtual machines from the vApp and creates a StartupSection that specifies a startup order for the remaining virtual machines.

Request:

POST https://vcloud.example.com/api/vApp/vapp-33/action/recomposeVApp Content-Type: application/vnd.vmware.vcloud.recomposeVAppParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <RecomposeVAppParams name="Example Corp’s CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Composed CRM Appliance</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="https://vcloud.example.com/api/network/54" /> <FenceMode>natRouted</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> <ovf:StartupSection xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" 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="https://vcloud.example.com/api/vApp/vm-45" /> </RecomposeVAppParams>

VMware, Inc. 91

vCloud API Programming Guide

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Example Corp’s CRM Appliance (33)" ...> ... </Task>

https://vcloud.example.com/api/query?type=adminVM&format=references&filter=status==POWERED_OFF

See Chapter 9, “Using the Query Service,” on page 247.

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 that you can GET to discover what input is needed.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or the object owner.

Procedure

1 Find the question link in the target vApp.

This link has the following form:

2 Make a GET request to the URL in that link's href value.

The response is a VmPendingQuestion response that includes the question and the set of possible answers.

3 Create a VmQuestionAnswer element that supplies the answer.

See “Example: Provide User Input Requested by a Virtual Machine,” on page 92.

4 POST the element to the question/action/answer link included in the VmPendingQuestion response.

Example: Provide User Input Requested by a Virtual Machine

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.

The first step is to use the vmPendingQuestion link, shown in Step 1, to get a VmPendingQuestion response that includes the question and the set of possible answers.

Request:

GET https://vcloud.example.com/api/vApp/vm-5/question

92 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Response:

200 OK Content-type: application/vnd.vmware.vcloud.vmPendingQuestion+xml ... <VmPendingQuestion xmlns="http://www.vmware.com/vcloud/v1.5"> <Link rel="answer" type="application/vnd.vmware.vcloud.vmPendingAnswer+xml" href="http://vcloud.example.com/api/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>

To supply the answer, POST a VmQuestionAnswer element to the question/action/answer link of the Vm.

Request:

POST http://vcloud.example.com/api/vApp/vm-5/question/action/answer Content-type: application/vnd.vmware.vcloud.vmPendingAnswer+xml <?xml version="1.0" encoding="UTF-8"?> <VmQuestionAnswer xmlns="http://www.vmware.com/vcloud/v1.5"> <ChoiceId>2</ChoiceId> <QuestionId>50</QuestionId> </VmQuestionAnswer>

Attach or Detach an Independent Disk

Use the disk/action/attach or disk/action/detach links in a Vm to attach or detach an independent disk. You must be the owner of the Vm element and the disk.

Every Vm element includes links of the following form:

VMware, Inc. 93

vCloud API Programming Guide

You can POST a DiskAttachOrDetachParams element to one of these URLs to attach or detach an independent disk.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or the object owner.

Verify that the vDC contains an independent disk. If the vDC does not contain independent disks, you can create one. See “Create or Update an Independent Disk,” on page 76.

Procedure

1 Retrieve a reference to the independent disk to attach to a virtual machine.

The independent disk and the virtual machine must be contained by the same vDC. You can retrieve references to independent disks in a vDC in the following ways:

Use the query service. A query like this one returns references to all Disk objects in the vDC named

MyVdc.

GET https://vcloud.example.com/api/query? type=disk&format=references&filter=vdcName==MyVdc

Retrieve the vDC and look for ResourceEntity elements whose type attribute has a value of

application/vnd.vmware.vcloud.disk+xml. The href value of a ResourceEntity that represents a disk

is a reference to that Disk object.

2 Create a DiskAttachOrDetachParams element.

Provide a reference to the independent disk in the href attribute of the Disk element.

3 POST the DiskAttachOrDetachParams to the disk/action/attach link of the Vm.

Example: Attach an Independent Disk to a Virtual Machine

This request attaches the disk created in “Create or Update an Independent Disk,” on page 76 to a virtual machine.

Request:

POST https://vcloud.example.com/api/vApp/vm-4/disk/action/attach Content-Type: application/vnd.vmware.vcloud.diskAttachOrDetachParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <DiskAttachOrDetachParams xmlns="http://www.vmware.com/vcloud/v1.5"> <Disk type="application/vnd.vmware.vcloud.disk+xml" href="https://vcloud.example.com/api/disk/128" /> </DiskAttachOrDetachParams>

The response is a Task.

Response:

<Task href="https://vcloud.example.com/api/task/57" ... status="running"

94 VMware, Inc.

operationName="vappAttachDisk" ... /> ... </Task>

Creating and Using vApp Snapshots

You can take a snapshot of all the virtual machines in a vApp. After the snapshots are taken, you can revert all virtual machines in the vApp to the most recent snapshot, or remove all snapshots.

You can take a snapshot of a vApp whether or not it is powered on. The createSnapshot operation always creates a snapshot for each virtual machine in the vApp. Snapshots are created in the order specified for virtual machines in the StartupSection of the VApp element.

vApp snapshots have the following limitations:

They do not capture the ovf:ProductSection elements in the vApp.

They do not capture NIC configurations.

They cannot be created if any virtual machine in the vApp is connected to an independent disk.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or the object owner.

Chapter 5 Deploying and Operating vApps

Procedure

1 (Optional) Retrieve information about current vApp snapshots.

When you create a snapshot, it overwrites any existing snapshots without warning. Before creating a new snapshot, you might want to verify whether there are any existing snapshots. Make a request like this one:

GET https://vcloud.example.com/api/vApp/vapp-33/snapshotSection

The response is a SnapshotSection element containing a link to each of the current snapshots for the vApp.

2 Create a CreateSnapshotParams request body.

See “Example: Create a vApp Snapshot,” on page 95.

3 POST the CreateSnapshotParams to the action/createSnapshot link of the vApp.

Example: Create a vApp Snapshot

In this example, the memory and quiesce options are not specified, so default values default to true. The name attribute is optional. If you omit it from the request, the system generates a name for the snapshot.

Request:

POST https://vcloud.example.com/api/vApp/vapp-33/action/createSnapshot Content-Type: application/vnd.vmware.vcloud.createSnapshotParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <CreateSnapshotParams xmlns="http://www.vmware.com/vcloud/v1.5" name="snap1"> <Description>Demo snapshot</Description> </CreateSnapshotParams>

The response is a Task.

VMware, Inc. 95

vCloud API Programming Guide

Response:

<?xml version="1.0" encoding="UTF-8"?> <Task ... operationName="vappCreateSnapshot" ... /> ... </Task>

After the snapshot is created, you can revert the vApp to the state captured in the snapshot.

POST https://vcloud.example.com/api/vApp/vapp-33/action/revertToCurrentSnapshot

You can also remove all snapshots.

POST https://vcloud.example.com/api/vApp/vapp-33/action/removeAllSnapshots

Neither of these requests has a request body. Both return a Task.

Operate a vApp

vApp and Vm elements include a number of action links. You can use these links to operate a vApp or one of its

virtual machines by making requests such as power on, suspend, power off, undeploy, and so on.

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. Some requests apply only to vApps, some apply only to virtual machines (Vm objects), and some apply to both.

A request made to the power URL of a VApp 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 contained by the Children element). 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.

A request made to the power URL of a Vm affects only that virtual machine.

See “Summary of vCloud API vApp and Virtual Machine Operations Requests,” on page 83 for details of each request.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of the vApp to find the action links it contains.

Use a request like this one:

GET https://vcloud.example.com/api/vApp/vapp-7

2 POST a request to the URL that implements the desired action.

Many of these requests do not require a body.

The server takes the requested action and returns a Task element that tracks the progress of the request.

96 VMware, Inc.

Configuring vApps and Virtual Machines

You specify configuration details for vApps and the virtual machines they contain in ovf:SectionType elements contained in a VApp or Vm element. You can include most of these sections in the InstantiationParams that you supply when you instantiate a vApp template. You can also retrieve, modify, and update these sections to reconfigure a deployed vApp.

You establish the initial configuration of a vApp in the OVF package on which its source template is based. You cannot modify most sections of the template, but you can update the configuration during the following operations:

When you create a vApp by making an instantiateVAppTemplate request, you can update its configuration by including modified sections in the request's InstantiationParams element.

When you compose or recompose a vApp, you can update its configuration by including modified sections in the request's InstantiationParams element.

When you update any of the modifiable sections in a deployed vApp or the virtual machines that it contains.

You can capture the reconfigured vApp to create a vApp template that preserves your modifications. See

“Capturing and Importing vApps,” on page 72.

Chapter 5 Deploying and Operating vApps

Updating a vApp Template

You can update the following sections of a vApp template.

CustomizationSection

Name and description

Owner

ProductSection elements

Except for the Owner element, all updates to a vApp template propagate to the vApp during instantiation. The owner of the vApp is set to the identity of the user who instantiates the template.

You can use a PUT request to update this section, which contains a Boolean value, CustomizeOnInstantiate, that specifies whether guest customization should be run during instantiation. You cannot modify this element if the vApp template has been added to a catalog.

You can use a PUT request to update the value of the template's name attribute or the contents of its Description element.

You can use a PUT request to update the value of the template's Owner element. See “View or Change the Owner of an Object,” on page 79.

You can retrieve or update the template's ProductSection elements, which provide a way to pass runtime information to the virtual machines defined in the template. See “Retrieve or Modify ProductSection Elements,” on page 120.

VMware, Inc. 97

vCloud API Programming Guide

Configuring a vApp

You can include the following sections in the InstantiationParams associated with an

instantiateVAppTemplate, composeVApp, or recomposeVApp request. You can also modify them in a deployed

vApp.

LeaseSettingsSection

Defines the terms of storage and deployment leases for the vApp. If this section is omitted, the vApp inherits the default lease settings of the containing organization.

NetworkConfigSection

Defines the properties of the vApp network and specifies how it is connected to a network in the vDC. Unless you intend to create a vApp that has no connection to any network, you must include this section in the

InstantiationParams element of an instantiateVappTemplate request.

StartupSection

Defines the order in which the virtual machines in the vApp start up and shut down. If this section is omitted, the startup and shutdown order of virtual machines in the vApp is indeterminate.

Configuring a Virtual Machine

You can configure a virtual machine by updating any of the following sections of a Vm element:

VirtualHardwareSection

OperatingSystemSection

NetworkConnectionSectio n

GuestCustomizationSecti on

Contains a description of the virtual hardware supported by a virtual machine. You can reconfigure individual items in this section, or reconfigure groups of related items such as hard disks or network interface cards.

Specifies the guest operating system installed on the virtual machine.

Specifies how the virtual NIC devices on the virtual machine are connected to the vApp network.

Contains guest customization parameters for the virtual machine.

There are several ways to update these sections:

You can include any or all of the sections in the InstantiationParams for a Vm.

You can include any or all of the sections in a reconfigureVm request.

You can use the workflow in “Reconfiguration Workflow,” on page 98 to update individual section or groups of related section.

Reconfiguration Workflow

The workflow for reconfiguring a vApp or virtual machine is the same regardless of the section you are modifying.

1 Retrieve the vApp or Vm and examine the response to find the section that you want to modify.

2 Retrieve the section by making a GET request to the URL in the section’s href attribute value.

3 Modify the section as needed.

4 Update the section by making a PUT request to the section’s edit link, a Link element in the section where

rel="edit", and supplying the modified section in the request body.

98 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Modified sections must contain all required elements, even if you are not changing their values. Because optional elements revert to default values if they are omitted or empty, it is a best practice to include optional elements in updates. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes might be read-only. See the schema reference for details.

NOTE You cannot make configuration changes to a vApp if it is in maintenance mode. A system administrator can put a vApp into maintenance mode to prevent metadata changes during administrative operations such as backup, restore, and upgrade. See “Summary of vSphere Platform Extension Requests,” on page 193.

Retrieve the Configuration Links for a vApp

Each modifiable section of a vApp includes a Link element whose rel attribute has the value edit. You cannot modify sections that do not contain this Link element.

Any ovf:SectionType element can include an arbitrary number of Link elements. Sections that you can modify include a Link element where rel="edit". To modify one of these sections, retrieve it by making a GET request to the URL in the section's href attribute. Then make a PUT request to the href attribute value of Link where

rel="edit" to update the section with your modifications.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of the vApp.

Use a GET request as shown in “Example: Configuration Links in a vApp,” on page 99.

2 Examine the response for edit links to modifiable sections.

The response portion of “Example: Configuration Links in a vApp,” on page 99 includes one of these links for each of the modifiable sections of the vApp. You cannot modify sections that do not contain a

Link element where rel="edit".

Example: Configuration Links in a vApp

In this example, the response was edited to show only the modifiable sections of the VApp element. Each Vm in the Children element of the VApp includes additional configuration links, shown in “Example: Configuration

Links in a Vm Element,” on page 101.

Request:

GET https://vcloud.example.com/api/vApp/vapp-7

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp ... href="https://vcloud.example.com/api/vApp/vapp-7"> ... <LeaseSettingsSection ... href="https://vcloud.example.com/api/vApp/vapp-7/leaseSettingsSection/" ...> ... <Link rel="edit" type="application/vnd.vmware.vcloud.leaseSettingsSection+xml" href="https://vcloud.example.com/api/vApp/vapp-7/leaseSettingsSection/" /> ...

VMware, Inc. 99

vCloud API Programming Guide

</LeaseSettingsSection> <ovf:StartupSection ... href="https://vcloud.example.com/api/vApp/vapp-7/startupSection/" ... > ... <Link rel="edit" type="application/vnd.vmware.vcloud.startupSection+xml" href="https://vcloud.example.com/api/vApp/vapp-7/startupSection/" /> ... </ovf:StartupSection> <NetworkConfigSection ... href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" ... /> ... <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" /> ... </NetworkConfigSection> <Children> <Vm ... status="8" name="ubuntu10-x86" href="https://vcloud.example.com/api/vApp/vm-4"> ... </Vm> </Children> </VApp>

Summary of vApp Reconfiguration Requests

vApp reconfiguration requests retrieve or update modifiable sections of a vApp.

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

Table 5-2. Summary of vApp Reconfiguration Requests

Operation Request Request Body Response

Retrieve vApp

LeaseSettingsSection

Update vApp

LeaseSettingsSection

Retrieve vApp

StartupSection

Update vApp

StartupSection

GET API-URL/vApp/vapp- id/ leaseSettingsSection/

PUT API-URL/vApp/vapp- id/ leaseSettingsSection/

GET API-URL/vApp/vapp- id/ startupSection/

PUT API-URL/vApp/vapp- id/ startupSection/

None

LeaseSettingsSection Task

None

StartupSection Task

LeaseSettingsSection

StartupSection

100 VMware, Inc.

VMware vCloud Director - 5.1 Programming Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

vCloud API Programming Guide

About the VMware vCloud API 1

Object Taxonomy

Objects, References, and Representations

Links and Link Relations

Client Workflow Overview

vCloud API REST Requests

vCloud API REST Responses

Using the vCloud API with vCloud Director

REST Client Programs

About the Schema Reference

About the vCloud API Examples

Logging In

Find a Catalog and a vDC

Retrieve the Contents of a Catalog

Retrieve a Catalog Item

Retrieve Deployment Information From the vDC

Deploy the vApp

Get Information About a vApp

Displaying the Virtual Machine Console

Delete the vApp

Log Out

Exploring a Cloud 3

Summary of vCloud API Browsing Requests

Retrieve the Login URL and List of Supported API Versions

Create a Login Session Using the Integrated Identity Provider

Create a Login Session Using a SAML Identity Provider

Retrieve a List of Organizations Accessible to You

Retrieve an Administrative View of a Cloud

Retrieve a List of vSphere Platform Operations and Objects for a Cloud

Provisioning an Organization 4

Summary of vCloud API Provisioning Requests

Upload an OVF Package to Create a vApp Template

Initiating the OVF Upload

Uploading the OVF Descriptor

Retrieving the Upload URLs

Uploading Referenced Files

Monitoring the Progress of an Upload

Using Ranged PUT requests to Complete a Partial Upload

Download a vApp Template as OVF

Enable the vApp Template for Download

Download the OVF Descriptor

Download a Referenced File

Upload a Media Image

Copying and Moving with the vCloud API

Capturing and Importing vApps

Cataloging vApp Templates and Media Images

Add an Item to a Catalog

Remove an Item from a Catalog

Creating and Using Independent Disks

Create or Update an Independent Disk

Remove an Independent Disk

View or Change the Owner of an Object

Deploying and Operating vApps 5

Summary of vCloud API vApp and Virtual Machine Operations Requests

Create a vApp From a Template

Compose a vApp From Existing Virtual Machines

Recompose a vApp to Add or Remove Virtual Machines

Provide User Input Requested by a Virtual Machine

Attach or Detach an Independent Disk

Creating and Using vApp Snapshots

Operate a vApp

Configuring vApps and Virtual Machines

Retrieve the Configuration Links for a vApp

Summary of vApp Reconfiguration Requests