VMware vCloud Director - 5.5 Programming Guide

vCloud API Programming Guide

vCloud Director 5.5

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

EN-001031-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–2013 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 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 17

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

Undeploy, Power Off, and 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 49

Retrieve an Administrative View of a Cloud 50

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 58

Download a vApp or vApp Template as OVF 68

Upload a Media Image 72

Download a Media Image 74

Capturing and Importing vApps 75

Managing Catalog Items 76

Creating and Using Independent Disks 80

View or Change the Owner of an Object 83

Controlling Access to vApps and Catalogs 84

vCloud API Programming Guide

Deploying and Operating vApps 89

Summary of vCloud API vApp and Virtual Machine Operations Requests 91

Create a vApp From a Template 93

Create a vApp From an OVF Package 97

Compose a vApp From Existing Virtual Machines 101

Recompose a vApp to Add or Remove Virtual Machines 103

Clone a vApp 106

Capture a vApp as a Template 108

Update vApp Access Controls 110

Provide User Input Requested by a Virtual Machine 111

Attach or Detach an Independent Disk 112

Creating and Using vApp Snapshots 114

Operate a vApp 115

Configuring vApps and Virtual Machines 116

Creating and Managing Organizations 149

Summary of Administrative Requests 149

Administrator Credentials and Privileges 152

Organization Administration 153

VDC Administration 160

Network Administration 169

Catalog Administration 197

User and Group Administration 219

Working With Roles and Rights 227

Managing and Monitoring a Cloud 235

Summary of System Administration Requests 235

Retrieve or Update System Settings 239

Attach a vCenter Server 240

Finding Available vCenter Resources 242

Create a Provider VDC 251

Create an External Network 261

Create a Network Pool 264

Import a Virtual Machine from vCenter 270

Relocate a Virtual Machine to a Different Datastore 273

Truststore and Keytab Maintenance 275

Retrieve the vSphere URL of an Object 277

Working With Object Metadata 281

Retrieve or Update a Metadata Element 283

Retrieve or Update a Metadata Value 286

Using the Query Service 289

Typed Queries 290

Packaged Queries 294

Query Parameters 299

Add a Metadata Filter to a Query 303

4 VMware, Inc.

Contents

Configuring and Using Blocking Tasks and Notifications 307

Configure Notifications and AMQP Settings 308

Retrieve or Update Blocking Task Settings 318

Monitor Blocking Tasks 324

Take Action on a Blocking Task 325

Extend The Timeout Expiration of an Active Task 327

vCloud Director Extension Services 329

Summary of vCloud API Extension Services Framework Requests 330

Adding or Removing Service Links 336

Service-Specific Tasks and Events 339

Authorization Framework for Extension Service Operations 342

Localization Framework for Extension Services 350

REST APIs for Extension Services 353

XML Representations in the vCloud API 357

XML Namespace Identifiers 359

Common vCloud API Attributes 360

Retrieve an Object as an Entity 362

Index 365

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.5 of the vCloud API.

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

Revision History

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

Table 1. Revision History

Revision Date Description

19SEP13 API Version 5.5

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

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 publications, 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 17

“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

Publish

External catalog

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 vApp templates and media images. You can configure a catalog in several different ways:

as a repository for local content that can remain private to the catalog owner or can be shared with other users, groups, or organizations in your cloud

as a source of published content, to which other clouds can subscribe.

10 VMware, Inc.

Chapter 1 About the VMware vCloud API

as a local repository for content published by another cloud or any Web

site that hosts a VMware Content Subscription Protocol (VCSP) endpoint.

An organization administrator or catalog owner controls catalog sharing. Organization administrators in organizations that have permission to publish catalogs control publication and subscription options for catalogs in their organization. A system administrator can enable background synchronization of catalogs with external sources and set background synchronization schedules to regulate consumption of network bandwidth by this activity.

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 ISO-format media images are stored in a catalog and represented as catalog item objects. Virtual systems are stored as templates, using an open standard format (OVF 1.0). These templates can be retrieved from catalogs and transformed into virtual systems, called vApps, through a process called instantiation, which binds a template’s abstract resource requirements to resources available in a VDC. A vApp contains one or more individual virtual machines (Vm elements), along with parameters that define operational details, including:

How the contained virtual machines are connected to each other and to

external networks.

The order in which individual virtual machines are powered on or off.

End-user license agreement terms for each virtual machine.

Deployment lease terms, typically inherited from the containing

organization, that constrain the 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.

Tasks

Asynchronous operations are tracked by task objects. Running and recently completed tasks initiated by members of an organization 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 362).

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:

12 VMware, Inc.

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

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.

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

POST

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 References an object contained by this object. GET

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

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

down:apiDefinitions Retrieve the API definitions for this extension service. 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:serviceLinks Retrieve the service links defined by this extension

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

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

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

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

GET

resource class.

GET

service.

GET

service.

class.

GET

be downloaded.

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

PUT Gateway.

POST by 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

fail Fail this blocking task. POST

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

installVmwareTools Install VMware Tools on this virtual machine. POST

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

keystore:update Updates the keystore used by this service. 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.

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 Share this catalog. POST

publishToExternalOrganizations Publish this catalog externally 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

POST

GET

POST

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

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

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

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

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

shadowVms List shadow virtual machines associated with the virtual

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

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

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

storageProfile References the storage profile for this object. GET

subscribeToExternalCatalog Add an external subscription to this catalog. POST

sync Synchronize this catalog or catalog item with its external

syncSyslogSettings Synchronize syslog server addresses used by this vApp

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 host. POST

upload:alternate Reserved N/A

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

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

GET service.

POST extension service.

GET machine.

GET machines in this vApp template.

POST this vApp.

POST snapshot.

POST source.

POST network with system defaults.

PUT be uploaded.

GET vSphere Web Client

16 VMware, Inc.

Client Workflow Overview

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

About RESTful Workflows

REST, an acronym for Representational State Transfer, describes an architectural style characteristic of programs that use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects between a client and a server. In the vCloud API, these representations are XML documents.

In a RESTful workflow, representations of objects are passed back and forth between a client and a server 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.

Chapter 1 About the VMware vCloud API

To write a RESTful client application, 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 that information in this Guide, and in the vCloud API Schema Reference. See “About the Schema

Reference,” on page 22.

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 document that can contain any of the following items.

XML elements and attributes that represent object properties

Link elements that implement operations on the object or its contents

Iif the object is being created or modified, an embedded Task object that tracks the progress of the

creation or modification

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. Each type of request is characterized by the use of specific HTTP verb to access a URL found in a Link element that has an operation-specific value for its rel (relation) attribute.

Table 1‑2. CRUD Operations Summary

Operation Type HTTP Verb Link Relation Operation Summary

Create POST add Creates a new object.

Retrieve GET down Retrieves the representation of an existing object in its current

Update PUT edit Modifies an existing object.

Delete DELETE remove Deletes an existing object. If the object is a container, you must

state.

remove all of its contents before you can delete it.

For example, this Link element indicates that you can use the URL https://vcloud.example.com/api/admin/org/26 to update the Org object that contains it.

The implied HTTP verb is PUT.

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 vCloud API version that the client supports. The following header indicates that the request is from a vCloud API version 5.5 client:

Accept: application/*+xml;version=5.5

18 VMware, Inc.

Chapter 1 About the VMware vCloud API

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

Accept-Encoding

Authorization

version=5.5

version=5.1

version=1.5

The request is from a vCloud API version 5.5 client.

The request is from a vCloud API version 5.1 client.

The request is from a vCloud API version 1.5 client.

In general, client requests can access objects defined by any version of the vCloud API that is less than or equal to the version specified in the Accept header. Exceptions to this rule are mentioned in the vCloud Director Release Notes.

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.

Content-Type

Requests that include a body must include an appropriate HTTP Content-

Type header. Content types for all elements are listed 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 359.

VMware, Inc. 19

vCloud API Programming Guide

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.

Request Limits

To guard against denial-of-service attacks, vCloud Director imposes the following limits on vCloud API requests:

Requests cannot exceed 512 KB.

Requests cannot contain more than 4096 XML elements.

Requests cannot have a depth greater than 100.

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 is not authenticated or 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.

20 VMware, Inc.

Table 1‑3. HTTP Status Codes that the vCloud API Returns (Continued)

Status Code Status Description

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

generating a response of the type specified in the request's Accept header.

409 Conflict The object state is not compatible with the requested

operation.

415 Unsupported Media Type The resource identified by the request does not support a

request of the specified Content-Type and HTTP 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 request URL.

Using the vCloud API with vCloud Director

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

Chapter 1 About the VMware vCloud API

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

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.

VMware, Inc. 21

vCloud API Programming Guide

About the Schema Reference

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

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

About the vCloud API Examples

The vCloud API Programming Guide includes many examples of HTTP requests and responses. 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.5 of the vCloud API,

is omitted from most examples.

Accept: application/*+xml;version=5.5

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 Undeploy, Power Off, and Delete the vApp on page 38

After you undeploy a vApp and power it off, you can use an HTTP DELETE request to delete the vApp object.

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

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

24 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

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

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

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

the objects it contains.

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 152. 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 encoded-credentials Accept: application/*+xml;version=5.5

Response:

200 OK x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.5 ... <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:

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:

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"

30 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"> ... <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.

VMware, Inc. 31

vCloud API Programming Guide

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

Supply the InstantiateVAppTemplateParams element as the request body.

The server takes the requested action and returns a VApp element. The element has a status attribute value of 0, meaning it is unresolved because it is still being constructed. It also contains a Task element that tracks the progress of the request.

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

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 94. 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 169.

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

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> </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:

VMware, Inc. 33

vCloud API Programming Guide

status="running" operation="Creating Virtual Application Linux FTP server(7)" ... > <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 361.

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

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.

NOTE A Vm element might also contain a link of the form:

This link acqures a special kind ticket to be used with the WebMKS Javascript API, which is described in the VMware Remote Console SDK documentation.

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.

VMware, Inc. 37

vCloud API Programming Guide

Verify that your browser has an installed copy of the vmware-vmrc plug-in. This plug-in is installed by

your browser whenever you use the vCloud Director Web Console to access the console of a running virtual machine. After this plug-in is installed, you can find it in the folder where your browser stores plug-ins.

Procedure

1 Retrieve the screen ticket.

POST a request to the acquireTicket link of the Vm.

Request:

POST https://vcloud.example.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 ...>ticket-string </ScreenTicket>

The ticket string itself has the following form:

mks://ip-address/VM-MoRef/ticket=encoded-ticket

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

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

encoded-ticket is the encoded screen ticket. You must decode this ticket using a function such as 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 Remote Console SDK documentation.

Undeploy, Power Off, and Delete the vApp

After you undeploy a vApp and power it off, you can 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 the vApp and 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 the vApp.

Prerequisites

Verify that you are logged in to the vCloud API as an administrator or vApp Author.

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 was returned when you created the vApp from the template. See “Get Information About a vApp,” on page 34.

38 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

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

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

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

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

3 Retrieve the XML representation of the vApp again.

After it is 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

You can use the undeploy request body, an UndeployVAppParams element, to specify an UndeployPowerAction element. This example specifies an UndeployPowerAction of powerOff.

NOTE powerOff is the default UndeployPowerAction. It appears 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 is undeployed and powered off, its representation includes a link where rel="remove". Make a DELETE request to this link to remove the vApp.

VMware, Inc. 39

vCloud API Programming Guide

Request:

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

Response:

202 Accepted ... <Task ... operation="Deleting Virtual Application Linux FTP server (7)" ... > </Task>

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 49

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

“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 well-known 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

Retrieve properties of a virtual machine

Retrieve metadata for an object such as an organization, network, vApp, virtual machine, media image, or independent disk.

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

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

GET API-URL/vApp/vapp-idNone

GET API-URL/vApp/vm-id None

GET API-

None

VApp

Metadata

URL/object/id/metadata

GET API-

None

AllocatedIpAddresses

URL/network/id/allocatedA ddresses

42 VMware, Inc.

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> ... </MediaTypeMapping> ... </VersionInfo> <VersionInfo> <Version>5.5</Version> <LoginUrl>https://vcloud.example.com/api/sessions</LoginUrl> <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 239.

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 encoded-credentials Accept: application/*+xml;version=5.5

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" userUrn="urn:vcloud:user:2a60c0c3-..." 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.org+xml"

VMware, Inc. 45

vCloud API Programming Guide

name="System" href="https://vcloud.example.com/api/org/99" /> <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/" /> <Link rel="down:extensibility" type="application/vnd.vmware.vcloud.apiextensibility+xml" href="https://vcloud.example.com/api/extensibility" /> </Session>

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

org

A link to the user's organization. See “Retrieve a List of Organizations

Accessible to You,” on page 49.

vcloud

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

Managing Organizations,” on page 149

vmwExtension

A link to the vCloud API extensions, accessible to a system administrator. See Chapter 7, “Managing and Monitoring a Cloud,” on page 235.

queryList

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

Query Service,” on page 289.

entity

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

extensibility

A link to the extensibility framework entry point. See Chapter 11, “vCloud

Director Extension Services,” on page 329.

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.

The vCloud API login mechanism supports Security Assertion Markup Language (SAML) authentication using two types security assertions:

Bearer assertions, which can make no guarantees about message integrity and claimed client identity.

Holder-of-key assertions, which guarantee subject identity by including a signature generated with the

subject's private key.

46 VMware, Inc.

Chapter 3 Exploring a Cloud

Prerequisites

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

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:

Table 3‑2. Authorization Header Attributes and Values

Attribute Name Attribute Value

token

signature Base64 encoded signature of the token XML (the

signature_alg The algorithm used to generate the signature,

org

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

uncompressed identity assertion from your SAML identity provider) generated using client's private key. Required when using holder-of-key subject confirmation.

expressed as one of the values listed in

http://docs.oracle.com/javase/7/docs/technotes/guides/se curity/StandardNames.html#Signature Required if

signature is present.

The name of your vCloud Director organization. Defaults to org="system" if not specified.

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

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:

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.

VMware, Inc. 47

vCloud API Programming Guide

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

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

example shows two varieties of the request.

Request (bearer token):

POST https://vcloud.example.com/api/sessions Authorization: SIGN token="compressed-encoded-credentials", org="Finance" Accept: application/*+xml;version=5.5

When using a SAML assertion that provides holder-of-key (HOK) subject confirmation, the request header must include signature and signature_alg attributes, as shown in this example, which assumes a signature created with a SHA encoding and RSA encryption algorithms:

Request (holder-of-key token):

POST https://vcloud.example.com/api/sessions Authorization: SIGN token="compressed-encoded-credentials", org="Finance", signature="encoded-signature" signature_alg="SHA1withRSA" Accept: application/*+xml;version=5.5

The response is the same in both cases.

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" userUrn="urn:vcloud:user:fe50b0b5-..." user="bob" org="Finance" ... > <Link rel="down" type="application/vnd.vmware.vcloud.org+xml" name="System" href="https://vcloud.example.com/api/org/5" /> <Link rel="down" type="application/vnd.vmware.vcloud.query.queryList+xml" href="https://vcloud.example.com/api/query" /> <Link

48 VMware, Inc.

rel="entityResolver" type="application/vnd.vmware.vcloud.entity+xml" href="https://vcloud.example.com/api/entity/" /> </Session>

Because this user has limited rights, the response includes only a few link types:

Chapter 3 Exploring a Cloud

org

A link to the user's organization. See “Retrieve a List of Organizations

Accessible to You,” on page 49.

queryList

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

Query Service,” on page 289.

entity

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

An administrator would see a more extensive set of links in the returned Session object. See

“Example: Create a Login Session Using the Integrated Identity Provider,” on page 45.

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

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

VMware, Inc. 49

vCloud API Programming Guide

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

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.orgList+xml ... <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.

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:

50 VMware, Inc.

Chapter 3 Exploring a Cloud

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

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

Example: Retrieve an Administrative View of a Cloud

Request:

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

Response:

200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml ... <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" 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

VMware, Inc. 51

vCloud API Programming Guide

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>

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 servers and hosts, vShield Manager, portgroups, virtual switches, and so on. The VMWExtension element provides access to a cloud-wide namespace of vSphere platform objects that are registered for use by the system, and links that allow you to add vSphere servers and related resources to your cloud. Objects in the admin/extension XML namespace 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

52 VMware, Inc.

Chapter 3 Exploring a Cloud

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

This link has the following form:

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

Step 2.

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

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

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

VMware, Inc. 53

vCloud API Programming Guide

rel="down" type="application/vnd.vmware.admin.extensionServices+xml" href="https://vcloud.example.com/api/admin/extension/service" /> </vmext:VMWExtension>

54 VMware, Inc.

Provisioning an Organization 4

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

The vCloud API allows you to upload and download OVF packages and ISO-format media images. Operations are characterized as uploads when they transfer content from a vCloud API client system to a target catalog in a vCloud Director organization, and as downloads when a vCloud API client requests the transfer of content from vCloud Director. 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. Uploaded vApp templates and media images are made available as catalog items in the target catalog.

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

Cloning

Capturing

Importing

Subscribing

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 58

“Download a vApp or vApp Template as OVF,” on page 68

The vCloud API cloneVApp operation creates a copy of a vApp in a specified VDC. You can specify whether to delete the source vApp after the operation completes. Deleting the source vApp after cloning it moves or renames it.

The vCloud API captureVApp operation creates a vApp template from a vApp and places the template in a specified catalog.

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.

Organizations that have the appropriate permissions can create catalogs with external subscriptions. These contents of these catalogs are downloaded from a catalog hosted on another instance of vCloud Director, or any Web site that implements the VMware Content Subscription Protocol. See “Create a

Catalog With an External Subscription,” on page 203.

VMware, Inc.

“Upload a Media Image,” on page 72

“Download a Media Image,” on page 74

vCloud API Programming Guide

“Capturing and Importing vApps,” on page 75

“Managing Catalog Items,” on page 76

“Creating and Using Independent Disks,” on page 80

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

“Controlling Access to vApps and Catalogs,” on page 84

Summary of vCloud API Provisioning Requests

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

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 a catalog create a vApp template. [NEW]

Upload OVF to a VDC to create a vApp template. [DEPRECATED]

Enable a vApp for download. [NEW]

Disable a vApp for download. [NEW]

Enable a vApp template for download.

Disable a vApp template for download.

Download a vApp or vApp template as an OVF package.

Upload a media image to a catalog. [NEW]

Upload a media image to a VDC. [DEPRECATED]

POST API-URL/catalog/id/ action/upload

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

POST API- URL/vApp/id/action/enable Download

POST API- URL/vApp/id/action/disabl eDownload

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

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

GET download-URL None Depends on file type.

POST API- URL/catalog/id/action/uplo ad

POST API- URL/vdc/id/media

UploadVAppTemplateParamsCatalogItem

UploadVAppTemplateParamsVAppTemplate

None

None 204 No Content

Media Media

Task

56 VMware, Inc.

Chapter 4 Provisioning an Organization

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

Operation Request Request Body Response

Move a catalog item. [NEW] POST API-

URL/catalogItem/id/

action/move

Copy a catalog item. [NEW] POST API-

URL/catalogItem/id/ action/copy

Synchronize a catalog with its remote source. [NEW]

Synchronize a catalog item with its remote source. [NEW]

Copy or move a media image. [DEPRECATED]

POST API-URL/catalog/id/ action/sync

POST API- URL/catalogItemid/ action/sync

POST API- URL/vdc/id/action/cloneMe dia

Copy or move a vApp template. [DEPRECATED]

POST API- URL/vdc/id/action/ cloneVAppTemplate

Change the name or description of a vApp template.

Change the name or

PUT API- URL/vAppTemplate/vappT emplate-id

PUT API-URL/media/id

description of a media image.

Delete a vApp template,

DELETE object-URL None

vApp, or media image.

Synchronize a catalog with its external source. [NEW]

Synchronize a catalog item with its external source. [NEW]

Add an item to a catalog. [DEPRECATED]

POST API- URL/catalog/id/action/sync

POST API- URL/catalogItem/id/actio n/sync

POST API- URL/catalog/id/catalogItem s

Remove an item from a catalog.

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

Control access to catalogs. POST API-

URL/catalog/id/action/contr olAccess

Retrieve the owner of a media object.

Retrieve the owner of a vApp template.

GET API- URL/media/id/owner

GET API- URL/vAppTemplate/vappT emplate-id/owner

Retrieve the owner of a vApp.

Update the owner of a vApp.

Create an independent disk in a VDC.

GET API- URL/vApp/id/owner

PUT API- URL/vApp/id/owner

POST API-URL/vdc/id/ disk

CopyOrMoveCatalogItemP

Task

arams

CopyOrMoveCatalogItemP

Task

arams

None

Task

CloneMediaParams Media

CloneVAppTemplateParamsVAppTemplate

VAppTemplate Task

Media Task

Task

None

Task

CatalogItem CatalogItem

None 204 No content

ControlAccessParams ControlAccessParams

None

Owner

204 No Content

DiskCreateParams Disk

VMware, Inc. 57

vCloud API Programming Guide

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

Operation Request Request Body Response

Retrieve properties of an independent disk.

Update an independent disk in a VDC.

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

Delete an independent disk. DELETE API-URL/disk/id None

GET API-URL/disk/id None

POST API-URL/disk/id

GET API- URL/disk/id/attachedVms

Disk Disk

None

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

An OVF package includes several kinds of files.

Disk

Vms

Task

An OVF descriptor

An XML file that contains metadata that describe a virtual machine or collection of related virtual machines and the deployment environment they require. By convention, this file has the suffix .ovf.

Virtual disk files

An optional certificate

An optional manifest

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.

Upload Workflow

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

1 The client makes a POST request to the catalog chosen to hold the template derived form the uploaded

OVF. The request body specifies a name, description, and other parameters used when creating the template.

2 The server returns a CatalogItem that references a vApp template.

3 The client makes a GET request to the entity reference in the CatalogItem to retrieve the VAppTemplate,

which includes an upload URL for the OVF descriptor. Because the template is not yet complete, the

VAppTemplate element has status="0".

4 The client makes a PUT request to the upload URL and supplies the OVF descriptor in the request

body.

5 The server processes 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.

6 The client uses PUT requests to upload each of the files.

58 VMware, Inc.

Chapter 4 Provisioning an Organization

7 If the OVF package includes a manifest file, the entire upload is validated against the contents of the

manifest file.

Both monolithic and ranged, or chunked, PUT requests are supported. After starting an upload, a client can make periodic requests to assess its progress. After all of the files are uploaded (and validated if a manifest is present), the server processes them and updates the vApp template. 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 361.

NOTE If you have an OVF package that you want to deploy immediately as a vApp, without creating a vApp template and corresponding catalog item, make an instantiateOvf request. See “Create a vApp From

an OVF Package,” on page 97.

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 60

To initiate the OVF upload, a client makes a POST request to an action/upload link in the target catalog. The type of this link is application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml. The request body is an UploadVAppTemplateParams element.

2 Retrieving the Upload URL for the OVF Descriptor on page 62

After the vApp template and corresponding catalog item have been created, you must retrieve the template to get the upload URL for the OVF descriptor.

3 Uploading the OVF Descriptor on page 63

You upload the OVF descriptor by making a PUT request to the upload URL created for it in the

VAppTemplate. The request body is the descriptor's Envelope element. If the request is valid, the server

responds with a 200 OK status.

4 Retrieving Additional Upload URLs on page 64

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.

5 Uploading Referenced Files on page 66

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

VMware, Inc. 59

vCloud API Programming Guide

Initiating the OVF Upload

To initiate the OVF upload, a client makes a POST request to an action/upload link in the target catalog. The

type of this link is application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml. The request body is an UploadVAppTemplateParams element.

The first step in uploading an OVF package is to request vCloud Director to create a catalog item in the target catalog and a corresponding vAppTemplate object to represent the template that will be constructed from the upload.

Prerequisites

Verify that the following are true:

You have 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 catalog that will receive the upload. Retrieve the XML representation of

your organization to see a list of the catalogs that it contains.

Procedure

1 Find the action/upload link for vApp templates in the target catalog.

Retrieve the XML representation of the catalog 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 action/upload link, which has the following form:

2 Create an UploadVAppTemplateParams element that specifies the parameters for the vApp template that

this request creates.

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

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 upload 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 61.

5 Examine the response.

The response, a CatalogITem element, contains an Entity element that contains a reference to the vApp template that will be constructed from the uploaded OVF. See the response portion of

“Example: Initiating the Upload,” on page 61.

The server creates a VAppTemplate object and a corresponding CatalogItem in the target catalog, and returns an XML representation of the CatalogItem. See the response portion of “Example: Initiating the Upload,” on page 61.

60 VMware, Inc.

Chapter 4 Provisioning an Organization

Example: Initiating the Upload

This example assumes an OVF package that has no manifest.

Request:

POST https://vcloud.example.com/api/catalog/32/action/upload Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml ... <?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.catalogItem+xml ... <CatalogItem xmlns="http://www.vmware.com/vcloud/v1.5" name="Ubuntu Template" 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 vApp Template"/> </CatalogItem>

VMware, Inc. 61

vCloud API Programming Guide

Retrieving the Upload URL for the OVF Descriptor

After the vApp template and corresponding catalog item have been created, you must retrieve the template to get the upload URL for the OVF descriptor.

Procedure

1 Examine the CatalogItem returned by the upload request to find the reference to the new vApp

template.

The reference is the value of the href attribute of the Entity element, as shown here.

2 Retrieve the VAppTemplate.

See the request portion of “Example: OVF Descriptor Upload URL in a vAppTemplate,” on page 62.

3 Examine the template to find the upload URL for the OVF descriptor.

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

Example: OVF Descriptor Upload URL in a vAppTemplate

This request uses the vApp template URL referenced in the Entity element shown in the response portion of

“Example: Initiating the Upload,” on page 61.

Request:

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

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:111" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" 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-111" /> <Description>Ubuntu vApp Template</Description> <Files> <File name="descriptor.ovf"

62 VMware, Inc.

Chapter 4 Provisioning an Organization

bytesTransferred="0"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../descriptor.ovf" /> </File> </Files> <Owner> ... </Owner> <Children /> <LeaseSettingsSection> ... </LeaseSettingsSection> <CustomizationSection> ... </CustomizationSection> </VAppTemplate>

The response body includes the following attributes:

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

You upload the OVF descriptor by making a PUT request to the upload URL created for it in the

VAppTemplate. The request body is the descriptor's Envelope element. If the request is valid, the server

responds with a 200 OK status.

Prerequisites

Verify that you have an upload URL for the OVF descriptor. See “Retrieving the Upload URL for the OVF

Descriptor,” on page 62.

Procedure

1 Upload the OVF descriptor.

Make a PUT request to the upload URL in the VAppTemplate. The upload URL for the OVF descriptor is in a Link element with the following form:

Supply the OVF descriptor as the request body. The OVF descriptor contains a single Envelope element.

VMware, Inc. 63

vCloud API Programming Guide

2 Verify that the request succeeded.

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

200 OK

Example: Uploading the OVF Descriptor

Request:

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

Response:

200 OK

Retrieving Additional Upload URLs

Procedure

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

See the request portion of “Example: Upload URLs in a vAppTemplate,” on page 64.

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 “Retrieving the Upload URL for the OVF Descriptor,” on page 62.

Request:

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

Response:

64 VMware, Inc.

Chapter 4 Provisioning an Organization

id="urn:vcloud:vapptemplate:111" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml"> ... <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" 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 61, 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 239.

VMware, Inc. 65

vCloud API Programming Guide

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

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

page 64.

Procedure

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

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

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

Data,” on page 66.

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 checking 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 67.

66 VMware, Inc.

Chapter 4 Provisioning an Organization

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

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

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

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

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

Example: Monitoring the Progress of an Upload

Request:

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

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 ... name="Ubuntu Template" id="urn:vcloud:vapptemplate:111" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" 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

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

Procedure

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

VMware, Inc. 67

vCloud API Programming Guide

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

contents of the range.

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

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.

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 or vApp Template as OVF

You can download a vApp or vApp template object as an OVF package. After you enable the object for download, you can download the OVF descriptor, then download all of the files referenced by the descriptor. A vApp must powered off and undeployed before you can enable it for download.

When you enable a vApp or 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 or vApp template. The

server excludes any deployment-specific information that the object contains, and populates the descriptor's References element with references 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 descriptor references.

3 The server updates the corresponding VApp or VAppTemplate element with a link that contains a URL

from which you can retrieve the OVF descriptor.

4 After you retrieve the descriptor, you can examine it to discover the download URLs for the files it

references.

You can download any file referenced in the descriptor by making a GET request to its download URL.

68 VMware, Inc.

Chapter 4 Provisioning an Organization

1 Enable a vApp or vApp Template for Download on page 69

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

2 Download the OVF Descriptor of a vApp or vApp Template on page 70

To download the OVF descriptor, make a GET request to the download:default URL in the downloadenabled VApp or VAppTemplate element.

3 Download a Referenced File on page 71

After you download the OVF descriptor of a vApp or vApp template, you can examine the contents of the descriptor to discover download URLs for .vmdk and other files in the package.

Enable a vApp or vApp Template for Download

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

Prerequisites

Verify that you are logged in as an administrator or other user who has privileges to enable a vApp or

vApp template for download.

Verify that any vApp you plan to enable for download is powered off and undeployed. See “Undeploy,

Power Off, and Delete the vApp,” on page 38.

Procedure

1 Retrieve the XML representation of object to find its action/enableDownload link.

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

Every vApp element includes a similar link:

2 Enable the object for download.

Make a POST request to the action/enableDownload URL, which you retrieved in Step 1. The response is a Task that tracks the completion of the enablement operation.

3 When the task completes, retrieve the representation of the object, 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 239.

Example: vApp Template with Download URL for OVF Descriptor

Request:

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

VMware, Inc. 69

vCloud API Programming Guide

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>

Download the OVF Descriptor of a vApp or vApp Template

To download the OVF descriptor, make a GET request to the download:default URL in the downloadenabled VApp or VAppTemplate element.

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 or vApp template that is enabled for download. See “Enable a vApp or

vApp Template for Download,” on page 69.

Procedure

1 Examine the object 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 70.

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

70 VMware, Inc.

Chapter 4 Provisioning an Organization

Download a Referenced File

After you download the OVF descriptor of a vApp or vApp template, you can examine the contents of the descriptor to discover download URLs for .vmdk and other files in the package.

The OVF descriptor includes an href value for each file that the descriptor references. To retrieve one of these files, you must create a download URL for it by combining this href value with a URL derived from the download URL that you used to retrieve the descriptor. You must retrieve all of the referenced 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 or vApp template that has been enabled for download.

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

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

VMware, Inc. 71

vCloud API Programming Guide

Upload a Media Image

Uploading an ISO-format media image to a catalog creates a Media object and a corresponding CatalogItem object.

vCloud Director supports using the vCloud API to upload media images to a catalog.

NOTE Media images in formats other than ISO can be uploaded, but are given an imageType of other in the catalog.

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

Create a vApp Template,” on page 58.

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 catalog that will receive the upload. Retrieve the XML representation of

your organization to see a list of the catalogs that it contains.

Procedure

1 Find the add link for media in the target catalog

This link has the following form:

2 POST an action/upload request to the URL shown in Step 1

The request body is a Media element. See the request portion of “Example: Upload a Media Image,” on page 72.

The server uses this information to create a CatalogItem and corresponding Media object, then returns the CatalogItem in its response. See the response portion of “Example: Upload a Media Image,” on page 72.

3 Use the URL in the Entity element of the CatalogItem to retrieve the Media object.

The Media element includes a File element that contains an upload:default URL.

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

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

Example: Upload a Media Image

There are two steps to uploading a media file. The first step is to make an action/upload request to the catalog. The request body is a Media element that specifies the size of the ISO file and the name that you want to apply to the created Media object. The imageType attribute is optional, and must be set to a value of

iso if you supply it.

72 VMware, Inc.

Request:

POST https://vcloud.example.com/api/catalog/32/action/upload 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>

Response:

201 Created Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem xmlns="http://www.vmware.com/vcloud/v1.5" name="database.iso" 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 type="application/vnd.vmware.vcloud.media+xml" name="database.iso" href="https://vcloud.example.com/api/media/254" /> </CatalogItem>

Chapter 4 Provisioning an Organization

Examine the response to the action/upload request, then make a GET request to the URL in the Entity element of the CatalogItem to retrieve the Media object.

GET https://vcloud.example.com/api/media/254

The Media object includes an upload URL for the media file itself.

VMware, Inc. 73

vCloud API Programming Guide

PUT the media file contents to the upload:default link in the response. The procedure is the same as the one shown in “Uploading Referenced Files,” on page 66.

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

System Settings,” on page 239.

Download a Media Image

The vCloud API supports downloading media images from a catalog.

Prerequisites

Verify that the following conditions are met:

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

You know the URL of the catalog item that references the media image.

Procedure

1 Retrieve the XML representation of the catalog and examine the catalog items that it contains.

2 Retrieve the catalog item that represents the media image.

3 Use the URL in the Entity element of the CatalogItem to retrieve the Media object.

The Media element includes a Link element of the following form, where id is the id of the media image:

4 Enable the media image for download.

Make a POST request to the action/enableDownload URL shown in Step 2. The response is a Task element.

5 When the task completes, retrieve the media item again.

The Media object now includes a download URL for the media file.

6 Make a GET request to the download:default URL.

The media file is downloaded to the current working directory.

Example: Download a Media Image

When you download a media file, you first enable the file for download.

Request:

POST https://vcloud.example.com/api/media/254/action/enableDownload

74 VMware, Inc.

Chapter 4 Provisioning an Organization

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Enabling download of Media database.iso (254)" ... > ... </Task>

The Task in the response tracks the creation of the downloadable image. When the task completes, retrieve the Media element again.

GET https://vcloud.example.com/api/media/254

The Media object now includes a download URL for the media file.

The download 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 239.

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.

As an administrator, catalog author, or vApp author, you can capture an undeployed vApp to create a vApp template in a catalog. Instantiating this template recreates the vApp from which the template was captured. Capturing a vApp in this way provides a way to save the results of composing, recomposing, or modifying a vApp after the vApp is undeployed. In addition, capturing a vApp preserves all vApp reconfiguration in template form. Although most elements of a vApp template are read-only, you can instantiate a template, modify the resulting vApp, and capture it to create a modified version of the template. See “Capture a vApp as a Template,” on page 108

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

VMware, Inc. 75

vCloud API Programming Guide

Managing Catalog Items

Catalog items are references to vApp templates and media files. If you have the appropriate rights, you can copy, move, rename, or delete catalog items in your organization's catalogs. You cannot modify catalog items in catalogs that have an external subscription.

After you add vApp templates or media files to a catalog, you might need to modify the CatalogItem objects that represent them. Your rights to manipulate catalog items depend on the source from which the catalog items were created.

If you are a catalog author or an administrator, you can copy, move, delete, or rename catalog items

that were uploaded, imported, or captured to a catalog that your organization owns, whether or not the catalog is published externally. Changes you make to an externally published catalog are replicated to all of the catalog's subscribers when those subscribers synchronize their copy of the catalog.

You cannot make changes to catalog items in catalogs that have an external subscription.

Changes to a catalog item increment the version number of the item and its containing catalog. See “Version

Numbers,” on page 198.

In addition to providing storage for locally created vApp templates and media files, catalogs provide a flexible publication mechanism that supports distribution of content to other organizations and clouds. If your organization allows it, you can publish a catalog to external consumers. You can also subscribe to catalogs that external sources publish, although catalog items in such catalogs cannot be managed by subscribers. See “Catalog Administration,” on page 197.

Copy or Move a Catalog Item

A Catalog object includes links that implement copy and move operations for the catalog items it contains.

To copy or move a catalog item from a source catalog to a target catalog, POST a

CopyOrMoveCatalogItemParams element that contains a reference to the catalog item to move to the copy or

move link of the target catalog.

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.

Verify that the target catalog does not have an external subscription.

Procedure

1 Retrieve the XML representation of the source catalog.

Use a request like this one:

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

2 Examine the Catalog element to find the CatalogItem elements it contains.

Each CatalogItem in the CatalogItems container has name, type, and href attributes. If you need more information about a catalog item, you can retrieve it with a GET request to the URL in its href attribute.

3 Retrieve the XML representation of the target catalog.

76 VMware, Inc.

Chapter 4 Provisioning an Organization

4 Examine the Catalog element to find the copy and move links it contains.

These links have the following form:

5 Create a CopyOrMoveCatalogItemParams element that specifies the catalog item in the Source element.

See “Example: Copy a Catalog Item,” on page 77.

POST the CopyOrMoveCatalogItemParams to the appropriate link from the target catalog.

Option Description

Copy the Catalog Item

Move the Catalog Item

POST the CopyOrMoveCatalogItemParams to the rel="copy" link.

POST the CopyOrMoveCatalogItemParams to the rel="move" link.

Example: Copy a Catalog Item

This request copies the catalog item shown in “Example: Retrieve a Catalog Item,” on page 29 to another catalog. The response is a Task.

Request:

POST https://vcloud.example.com/api/catalog/44/action/copy Content-Type: application/vnd.vmware.vcloud.copyOrMoveCatalogItemParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <CopyOrMoveCatalogItemParams xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" name="Ubuntu 10.04 Template"> <Description>Reference copy of Ubuntu FTP Server</Description> <Source href="https://vcloud.example.com/api/catalogItem/221" /> </CopyOrMoveCatalogItemParams>

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Copying Virtual Application Template Ubuntu 10.04 Template" ...> ... </Task>

VMware, Inc. 77

vCloud API Programming Guide

Change the Name or Description of a Catalog Item

Every CatalogItem object includes a rel="edit" link that you can use to modify the name or description of the catalog item.

Prerequisites

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.

Verify that the target catalog does not have an external subscription.

Procedure

1 Retrieve the catalog item from the catalog.

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

3 Modify the retrieved CatalogItem element to change its name, description, or both.

See “Example: Change the Name and Description of a Catalog Item,” on page 78.

4 Make a PUT request to the href value of the rel="edit" link in the CatalogItem, supplying the modified

CatalogItem in the request body.

Example: Change the Name and Description of a Catalog Item

This request changes the name and the description of the catalog item shown in “Example: Retrieve a

Catalog Item,” on page 29. The request body excludes components such as Link elements and id attributes

that were present in the retrieved CatalogItem. These components are ignored if you include them in a request.

Request:

PUT https://vcloud.example.com/api/catalogItem/221 Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <?xml version="1.0" encoding="UTF-8"?> <CatalogItem xmlns="http://www.vmware.com/vcloud/v1.5" name="DEPRECATED Ubuntu Template"> <Description>Deprecated. Use https://vcloud.example.com/api/vAppTemplate/vappTemplate-230 instead </Description> <Entity href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd" /> </CatalogItem>

The response shows the modified CatalogItem.

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem xmlns="http://www.vmware.com/vcloud/v1.5" name="DEPRECATED Ubuntu Template"> <Description>Deprecated. Use https://vcloud.example.com/api/vAppTemplate/vappTemplate-230 instead </Description>

78 VMware, Inc.

Chapter 4 Provisioning an Organization

Remove an Item from a Catalog

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

Removing a CatalogItem also removes the referenced vApp template or media image from the catalog's storage.

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.

Verify that the target catalog does not have an external subscription.

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.

Example: Remove an Item from a Catalog

This request removes the source catalog item that was copied in “Example: Copy a Catalog Item,” on page 77.

Request:

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

Response:

204 No Content

Synchronize a Catalog or Catalog Item

Catalogs that have external subscriptions are synchronized with their external sources by a background process that the system administrator controls. You can also force synchronization of individual catalog items or entire catalogs at any time.

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 XML representation of a catalog that has an external subscription.

Use a request like this one:

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

2 Examine the Catalog element to find the CatalogItem elements that it contains.

VMware, Inc. 79

vCloud API Programming Guide

3 Examine the Catalog and CatalogItem element to find the sync links that they contain.

In catalogs, these links have the following form:

In catalog items, these links have the following form:

4 Synchronize the catalog or catalog item.

Make a POST request to the appropriate action/sync link.

Option Description

Synchronize a Catalog

Synchronize a Catalog Item

Example: Synchronize a Catalog Item

Make a POST request to the action/sync link in the Catalog element.

Make a POST request to the action/sync link in the CatalogItem element.

This request synchronizes a single catalog item. The response is a task that tracks the progress of the synchronization.

Request:

POST https://vcloud.example.com/api/catalogItem/102/action/sync

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Synchronizing Catalog Item DB.iso (102)" ...> ... </Task>

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.

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.

80 VMware, Inc.

Chapter 4 Provisioning an Organization

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

Owner of an Object,” on page 83.

Procedure

1 Choose an organization VDC to contain the disk.

2 Create a DiskCreateParams element.

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

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

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

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 161. 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" 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"

VMware, Inc. 81

vCloud API Programming Guide

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>

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.

82 VMware, Inc.

Chapter 4 Provisioning an Organization

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

vmDiskRelation

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>

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

Prerequisites

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

Procedure

1 Retrieve the Owner element from the object.

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

VMware, Inc. 83

vCloud API Programming Guide

2 Modify the Owner element to specify a different User.

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

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

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

element in the request body.

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

a vApp,” on page 84.

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

Controlling Access to vApps and Catalogs

Upon creation, catalogs and vApps grant full access to their owners and no access to other users. The vCloud API access control mechanism enables object owners to retrieve or update these access controls as needed.

To retrieve or update the access controls on a vApp or catalog, use controlAccess links. The controlAccess links for catalogs are included when you retrieve the containing AdminOrg. The controlAccess links for a vApp are included in the VApp element itself.

vCloud Director defines three levels of access:

ReadOnly

Change

FullControl

See “Access Rights to vCloud Director Objects,” on page 87 for detailed information about the rights granted by each access level.

The ReadOnly access level grants rights to read or use the object.

The Change access level includes all rights granted by ReadOnly access and grants additional rights to modify the object and its properties.

The FullControl access level includes all rights granted by Change access and grants additional rights to change the owner of the object, share it, or delete it.

84 VMware, Inc.

Chapter 4 Provisioning an Organization

Access Control for vApps

An administrator or vApp owner can control access to a vApp. Each VApp element includes two types of access control links:

Links where rel="down".

Use this kind of link to retrieve the access control settings for the vApp identified in the href value.

Links where rel="controlAccess".

Use this kind of link to specify new access control settings for the vApp identified in the href value. You specify the new access control settings in a ControlAccessParams element that you post to the URL that the href value of this link specifies. See “Update vApp Access Controls,” on page 110 for an example.

Access Control for Catalogs

A system administrator or organization administrator can control access to a catalog. Each Org element includes two types of access control links for the catalogs owned by the organization it represents:

Links where rel="down".

Use this kind of link to retrieve the access control settings for the catalog identified in the href value.

Links where rel="controlAccess".

Use this kind of link to specify new access control settings for the catalog identified in the href value. You specify the new access control settings in a ControlAccessParams element that you post to the URL that the href value of this link specifies.

NOTE The controlAccess links for catalogs are not returned in the AdminOrg response when you retrieve the organization in admin view.

VMware, Inc. 85

vCloud API Programming Guide

Granting Access to All Members of an Organization

To specify access controls that apply to all members of an organization, an organization administrator can set IsSharedToEveryone to true and specify an access level in the EveryoneAccessLevel element. The following ControlAccessParams element grants read access to all members of the organization.

<ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1.5"> <IsSharedToEveryone>true</IsSharedToEveryone> <EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel> </ControlAccessParams>

Granting Access to Individual Members of an Organization

To specify access controls that apply to specific users, an organization administrator can set

IsSharedToEveryone to false and specify an access level in an AccessSettings element that the ControlAccessParams request contains. An AccessSettings element is populated with one or more AccessSetting elements, each of which assigns an access level to the user identified in the Subject element.

The following ControlAccessParams element grants full control to one user and read-only access to another user.

<ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1.5"> <IsSharedToEveryone>false</IsSharedToEveryone> <AccessSettings> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="https://vcloud.example.com/api/admin/user/40"/> <AccessLevel>FullControl</AccessLevel> </AccessSetting> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="https://vcloud.example.com/api/admin/user/45"/> <AccessLevel>ReadOnly</AccessLevel> </AccessSetting> </AccessSettings> </ControlAccessParams>

Viewing or Changing the Owner of a vApp or Catalog

Ownership of a VApp or Catalog object is expressed in an Owner element that you can retrieve from the object. This element contains a User element that identifies the owner with a reference to a specific user. The initial owner of an object is the user who created it.

A system administrator can view or change the owner of a VApp or Catalog object using the procedure documented in “View or Change the Owner of an Object,” on page 83.

86 VMware, Inc.

Chapter 4 Provisioning an Organization

Access Rights to vCloud Director Objects

Each access level supported by vCloud Director grants one or more users a specific set of rights to an object.

vCloud Director access levels are similar to roles in that they give a name to a set of rights. When you apply an access control to an object, you grant one or more users in your organization a set of rights to the object. Access rights are additive. You can make an object more accessible to users who have limited rights, but you cannot to restrict the rights that a user may already have. For example, an organization administrator retains full control of an object even if you apply ReadOnlyaccess rights to it for all organization members.

Table 4‑2. Access Levels and the Rights They Grant

FullControl Change ReadOnly

Catalog: Add vApp from My Cloud

Catalog: Change Owner X

Catalog: VCSP Publish Subscribe

Catalog: Edit Properties X X

Catalog: Publish X X

Catalog: View Private and Shared Catalogs

Catalog: View Published Catalogs

vApp Template or Media: Copy

vApp Template or Media: Create or Upload

vApp Template or Media: Edit

vApp Template or Media: View

vApp Template: Checkout (Add to My Cloud)

vApp Template: Download X X X

vApp: Change Owner X

vApp: Copy X X X

vApp: Create or Reconfigure X

vApp: Delete X

vApp: Edit Properties X X

vApp: Edit VM CPU X X

vApp: Edit VM Hard Disk X X

vApp: Edit VM Memory X X

vApp: Edit VM Network X X

vApp: Edit VM Properties X X

vApp: Manage VM Password Settings

vApp: Power Operations X X

X X

X X X

X X

X X X

VMware, Inc. 87

vCloud API Programming Guide

Table 4‑2. Access Levels and the Rights They Grant (Continued)

vApp: Sharing X

vApp: Use Console X X X

FullControl Change ReadOnly

88 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 catalog.

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, power-

on, 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 91

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

“Create a vApp From an OVF Package,” on page 97

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

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

“Clone a vApp,” on page 106

“Capture a vApp as a Template,” on page 108

90 VMware, Inc.

Chapter 5 Deploying and Operating vApps

“Update vApp Access Controls,” on page 110

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

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

“Creating and Using vApp Snapshots,” on page 114

“Operate a vApp,” on page 115

“Configuring vApps and Virtual Machines,” on page 116

Summary of vCloud API vApp and Virtual Machine Operations Requests

These vCloud API operations requests create, manage, operate, and delete vApps and the 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

Create a vApp from an OVF package [NEW]

Instantiate a vApp template to create a vApp

Change the name or description of a vApp.

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

Capture a vApp as a Template

Clone a vApp. POST API-

Recompose a vApp to add or remove virtual machines

Deploy a vApp or Virtual Machine

POST API-URL/vdc/id/ action/instantiateOvf

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

PUT API-URL/vApp/vapp-

action/composeVApp

POST API- URL/catalog/id/action/capt ureVApp

URL/vdc/id/action/cloneVA pp

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

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

InstantiateOvfParams VApp

InstantiateVAppTemplat eParams

VApp Task

ComposeVAppParams VApp

CaptureVAppParams VAppTemplate

CloneVAppParams VApp

RecomposeVAppParams Task

DeployVAppParams Task

VApp

VMware, Inc. 91

vCloud API Programming Guide

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

Operation Request Request Body Response

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

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

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

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

GET VApp-or-Vm- URL/productSections

PUT VApp-or-Vm- URL/productSections

GET API- URL/vAppTemplate/vappT emplate-id/productSections

GET Vm- URL/runtimeInfoSection

POST Vm- URL/action/installVMware Tools

POST Vm- URL/action/consolidate

POST Vm- URL/action/upgradeHardw areVersion

POST Vm- URL/action/insertMedia

POST Vm- URL/action/ejectMedia

GET Vm-URL/ virtualHardwareSection/m edia

POST Vm- URL/question/action/answ er

UndeployVAppParams Task

None

Task

ProductSectionList

ProductSectionList Task

None

ProductSectionList

RuntimeInfoSection

Task

MediaInsertOrEjectParamsTask

None

RasdItemsList

VmPendingQuestion

VmQuestionAnswer

204 No Content

92 VMware, Inc.

Chapter 5 Deploying and Operating vApps

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

Operation Request Request Body Response

Get a Screen Thumbnail for a Virtual Machine

Get a Screen Ticket for a Virtual Machine

Attach an independent disk to a virtual machine.

Detach an independent disk from a virtual machine.

Create snapshots of all virtual machines in a vApp.

Remove snapshots of all virtual machines in a vApp.

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

Retrieve information about vApp snapshots.

Validate the storage profile compliance of a virtual machine.

Retrieve a virtual machine storage profile validation report.

GET Vm-URL/screen None Returns a screen thumbnail

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

POST Vm- URL/screen/action/acquire Ticket

POST Vm- URL/disk/action/attach

POST Vm- URL/disk/action/detach

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

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

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

None

DiskAttachOrDetachParamsTask

CreateSnapshotParams Task

None

ScreenTicket

Task

SnapshotSection

Task

ComplianceResult

Create a vApp From a Template

An instantiateVAppTemplate request creates a vApp from a vApp template.

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.

VMware, Inc. 93

vCloud API Programming Guide

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.

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 94 for guidelines.

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

Supply the InstantiateVAppTemplateParams element as the request body.

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

Request:

94 VMware, Inc.

Chapter 5 Deploying and Operating vApps

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

Modify Virtual Machine Hardware During vApp Template Instantiation

An InstantiateVAppTemplateParams request body can include a SourcedVmInstantiationParams element for each virtual machine in the vApp. With the values in this element, you can modify a subset of virtual machine hardware configuration parameters during instantiation.

SourcedVmInstantiationParams supports the following configuration changes:

Specify a storage profile for the virtual machine.

Increase the capacity of the virtual machine's SATA or SCSI disks.

Increase or decrease the size of the virtual machine's memory.

Increase or decrease the number of CPU cores per virtual socket.

Add or remove CPUs.

You can also modify any of these configuration settings after the vApp is deployed. See “Configuring

vApps and Virtual Machines,” on page 116

Prerequisites

Most of the virtual machine configuration parameters that you can reconfigure during instantiation are defined in the OVF descriptor for the vApp template that contains the virtual machine. The easiest way to access these parameters is to download the OVF descriptor of the vApp template. See “Download the OVF

Descriptor of a vApp or vApp Template,” on page 70. You do not need to download any files other than the

descriptor.

VMware, Inc. 95

vCloud API Programming Guide

Procedure

1 Examine the OVF descriptor of the template to determine the values that you can include in a

SourcedVmInstantiationParams element.

See “Example: Modify Virtual Machine Hardware During vApp Template Instantiation,” on page 96 for guidelines.

2 Include the SourcedVmInstantiationParams element in an InstantiateVAppTemplateParams element.

See “Example: Modify Virtual Machine Hardware During vApp Template Instantiation,” on page 96.

3 Make a POST request to the action/instantiateVAppTemplate URL of the VDC.

Supply the InstantiateVAppTemplateParams element as the request body.

Example: Modify Virtual Machine Hardware During vApp Template Instantiation

This InstantiateVAppTemplateParams request extends the one shown in “Example: Instantiate a vApp

Template,” on page 94 to include a SourcedVmInstantiationParams element that makes several configuration

changes in the virtual machine referenced at https://vcloud.example.com/api/vAppTemplate/vm-4.

Specifies a storage profile for the virtual machine.

Adds a virtual CPU and changes the value of CoresPerSocket to 2. If you include a CoresPerSocket

element, its value must be an integer multiple of the value of the existing rasd:VirtualQuantity of CPU items, or of the value you supply in NumberOfCpus. “Example: Modify the CPU Configuration of a

Virtual Machine,” on page 136 shows the original CPU configuration, and how to make this change by

reconfiguring the virtual machine in a deployed vApp.

Increases the capacity of the hard disk from 1GB to 10GB by including a Disk element that specifies a

Size of 10240 for the disk that has a rasd:InstanceID value of 2000. The value you supply for Size is

interpreted as megabytes. You can see the original disk configuration in “Example: Retrieve the Hard

Disks and Controllers in a Virtual Machine,” on page 142. “Example: Modify the Hard Disk Configuration of a Virtual Machine,” on page 144 shows how to make the same change by

reconfiguring the virtual machine in a deployed vApp. If you include a Disk element, the value of its

instanceId attribute must match the value in the rasd:InstanceID element of an existing Item that

defines a virtual disk (RASD resource type 17). Disk capacity can be raised, but not lowered, for disks on SATA and SCSI controllers. The capacity of other disk types cannot be changed. Item elements that represent SATA disks have a vcloud:busType attribute with the value 20. Those that represent SCSI disks have a vcloud:busType attribute with the value 6.

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">

96 VMware, Inc.

Chapter 5 Deploying and Operating vApps

<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>2013-04-11T08:08:16.438-07:00</StorageLeaseExpiration> </LeaseSettingsSection> </InstantiationParams> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" /> <SourcedVmInstantiationParams>

Create a vApp From an OVF Package

An instantiateOvf request uploads an OVF package and then creates a vApp from it. By default, this operation also deploys the vApp and powers it on.

If you want to deploy an OVF package as a vApp without creating a vApp template and corresponding catalog item, make an instantiateOvf request. This request initiates a workflow similar to the one shown in

“Upload an OVF Package to Create a vApp Template,” on page 58, but with a few important differences.

The target of the upload is a VDC, not a catalog.

The request body is an InstantiateOvfParams element, not an UploadVAppTemplateParams element.

The response is a VApp element that includes an upload URL for the OVF descriptor.

After you retrieve the VApp element created by the instantiateOvf request, you can upload the descriptor and the files it references.

Prerequisites

Verify that the following are true:

You have an OVF package to upload.

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

VMware, Inc. 97

vCloud API Programming Guide

You know the URL of the target VDC that will receive the upload. Retrieve the XML representation of

your organization to see a list of the VDCs that it contains.

Review the contents of the Envelope element in the descriptor file of your OVF package. Several properties in this file have implications for the InstantiateOvfParams request body you must construct to initiate the upload.

Procedure

1 Retrieve the XML representation of the target VDC.

2 Examine the response to locate the Link element that contains the URL for creating a vApp from an

OVF package.

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

application/vnd.vmware.vcloud.instantiateOvfParams+xml, as shown here:

3 Create an InstantiateOvfParams request body.

See the request portion of “Example: Create a vApp From an OVF Package,” on page 99.

4 POST the InstantiateOvfParams to the instantiateOvf URL you retrieved in Step 2

See the request portion of “Example: Create a vApp From an OVF Package,” on page 99.

5 Examine the response.

The response, a VApp element, contains a File element that specifies an upload URL for the OVF descriptor. See the response portion of “Example: Create a vApp From an OVF Package,” on page 99

6 Upload the OVF descriptor.

Make a PUT request to the upload URL in the VApp. The upload URL for the OVF descriptor is in a Link element with the following form:

Supply the OVF descriptor as the request body. The OVF descriptor contains a single Envelope element.

7 Retrieve the remaining upload URLs

a Retrieve the VApp.

b Verify that the value of the ovfDescriptorUploaded attribute is true.

c Examine the VApp to find the upload URLs for the files referenced in the OVF descriptor.

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

8 Upload the referenced files.

You can follow the progress of the upload by retrieving the vApp and noting the progress of the embedded Task.

After all of the referenced files are uploaded, the VApp element no longer includes an embedded Task. The vApp is placed in the power and deployment state that the values of the powerOn and deploy attributes specify in the request body.

98 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Example: Create a vApp From an OVF Package

This request includes a NetworkMapping element that maps a network name found in the uploaded OVF descriptor to the name of a network available in the target VDC.

Request:

POST https://vcloud.example.com/api/vdc/5/action/instantiateOvf Content-Type: application/vnd.vmware.vcloud.instantiateOvfParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <InstantiateOvfParams xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns="http://www.vmware.com/vcloud/v1.5" name="W2K8"> <Description>Example vApp</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> <AllEULAsAccepted>true</AllEULAsAccepted> <NetworkMapping> <Source>Network 1</Source> <Target>vAppNetwork</Target> </NetworkMapping> <InstantiateVmParams id="VM-1"> <Name>VM-1</Name> <NetworkConnectionSection> <ovf:Info /> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="Network 1"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IsConnected>true</IsConnected> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> </NetworkConnectionSection> <ComputerName>W2K8</ComputerName> </InstantiateVmParams> </InstantiateOvfParams>

The response is a sparsely populated VApp element that includes an upload URL for the OVF descriptor. See

“Uploading Referenced Files,” on page 66 for file upload procedures.

VMware, Inc. 99

vCloud API Programming Guide

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="W2K8" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-23"> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"/> <Description>Example vApp</Description> <Link rel="remove" href="https://vcloud.example.com/api/vApp/vapp-23" /> <Description>Example vApp</Description> <Tasks> <Task status="running" operation="Creating Virtual Application W2K8(23)" ... > ... </Task> </Tasks> <Files> <File name="descriptor.ovf" bytesTransferred="0"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../descriptor.ovf" /> </File> </Files> <Owner> ... </Owner> <InMaintenanceMode>false</InMaintenanceMode> </VApp>

100 VMware, Inc.

VMware vCloud Director - 5.5 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

Undeploy, Power Off, and 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

Retrieving the Upload URL for the OVF Descriptor

Uploading the OVF Descriptor

Retrieving Additional Upload URLs

Uploading Referenced Files

Monitoring the Progress of an Upload

Using Ranged PUT requests to Complete a Partial Upload

Download a vApp or vApp Template as OVF

Enable a vApp or vApp Template for Download

Download the OVF Descriptor of a vApp or vApp Template

Download a Referenced File

Upload a Media Image

Download a Media Image

Capturing and Importing vApps

Managing Catalog Items

Copy or Move a Catalog Item

Change the Name or Description of a Catalog Item

Remove an Item from a Catalog

Synchronize a Catalog or Catalog Item

Creating and Using Independent Disks

Create or Update an Independent Disk

Remove an Independent Disk

View or Change the Owner of an Object

Controlling Access to vApps and Catalogs

Access Rights to vCloud Director Objects

Deploying and Operating vApps 5

Summary of vCloud API vApp and Virtual Machine Operations Requests

Create a vApp From a Template

Modify Virtual Machine Hardware During vApp Template Instantiation

Create a vApp From an OVF Package