VMware VCLOUD API 1.0 - TECHNICAL NOTE Operating instructions

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

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2VMware, Inc.
vCloud API Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
[e-mail]
Copyright © 2009, 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
intellectual property laws. VMware products are covered by one or more patents listed at
http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks
and names mentioned herein may be trademarks of their respective companies.

VMware, Inc. 3
Contents
AboutThisBook 11
1IntroducingtheVMwarevCloudAPI 13
vCloudObjectTaxonomy 13
vCloudOrganizations 13
Objects,References,andRepresentations 15
LinksandLinkRelations 15
vCloudClientWorkflowOverview 17
Requests 17
Responses 18
ConfiguringthevCloudAPIURL 19
RelatedPublications 19
AbouttheExamples 19
2HellovCloud:AStructuredRESTWorkflowExample 21
LoggingInandGettinganOrganizationList 21
BrowsinganOrganization 22
FindingavAppTemplate 23
GettingInformationAboutavDC 24
InstantiatingtheTemplateinthevDC 24
DeployingandPoweringOnthevApp 26
GettingInformationAboutthevApp 27
DisplayingtheConsole 29
RetrieveaScreenTicket 29
UsetheTicketwithvmware‐vmrc 30
DeletingthevApp 30
LoggingOut 30
MovingontoAdditionalUseCases 31
3Browsing 33
SummaryofBrowsingRequests 33
DiscoveringtheContentsofanOrganization,Catalog,orvDC 34
ListtheOrganizationsinavCloud 34
ListtheContentsofanOrganization 34
ListtheContentsofaCatalog 35
GetInformationAboutaCatalogItem 36
ListtheContentsofavDC 37
GettingMoreInformationAboutanObject 38
GetInformationAboutaMediaImage 38
GetInformationAboutavAppTemplate 39
GetInformationAboutavApporVirtualMachine 40
GetInformationAboutaNetwork 40

vCloud API Programming Guide
4VMware, Inc.
4Provisioning 41
SummaryofProvisioningRequests 41
UploadOVFtoCreateavAppTemplate 42
RestrictionsonUploadedContent 43
InitiatetheUpload 43
IncludingaManifest 45
UploadingtheFiles 45
ViewtheOVFDescriptorofavAppTemplate 47
DownloadavAppTemplateasOVF 47
EnableavAppTemplateforDownload 48
DisableavAppTemplateforDownload 49
UploadaMediaImage 50
CopyingandMoving 50
CopyorMoveaMediaImage 51
CopyorMoveavAppTemplate 51
CopyorMoveavApp 52
ChangingaNameorDescription 53
ChangetheNameorDescriptionofavAppTemplate 53
ChangetheNameorDescriptionofavApp 53
ChangetheNameorDescriptionofaMediaImage 54
DeleteavAppTemplate,vApp,orMediaImage 54
CatalogingvAppTemplatesandMediaImages 54
AddanItemtoaCatalog 54
RemoveanItemfromaCatalog 56
CatalogLinksinaVAppTemplateorMediaImage 56
ControllingAccess 56
ControlAccesstoCatalogs 56
5DatacenterOperations 59
SummaryofDatacenterOperationsRequests 59
vAppLifecycle 60
InstantiateavAppTemplate 61
AboutInstantiationParameters 62
AboutvAppNetworks 62
InstantiatingavAppTemplateUsingDefaultParameters 62
InstantiatingavAppTemplateUsingAdditionalParameters 62
RetrieveorModifytheCustomizationSectionofavAppTemplate 64
ComposeavApp 65
FindingVirtualMachineURLstoUseinaCompositionItem 66
RecomposeavApptoAddorRemoveVirtualMachines 67
CaptureavApptoCreateavAppTemplate 68
ReconfiguringvAppsandVirtualMachines 69
ReconfigureavApp 69
ReconfigureaVirtualMachine 73
DeployingandControllingvAppsandVirtualMachines 80
DeployavApporVirtualMachine 80
UndeployavApporVirtualMachine 81
PowerOnavApporVirtualMachine 81
PowerOffavApporVirtualMachine 82
ResetavApporVirtualMachine 82
SuspendavApporVirtualMachine 83
DiscardtheSuspendedStateofavApporVirtualMachine 83
ShutDownavApporVirtualMachine 84
RebootavApporVirtualMachine 84
ListMediaDevicesofaVirtualMachine 85

VMware, Inc. 5
Contents
InsertMediaIntoaVirtualMachine 85
EjectMediafromaVirtualMachine 86
GetaScreenThumbnailforaVirtualMachine 86
GetaScreenTicketforaVirtualMachine 87
ProvideUserInputRequestedbyaVirtualMachine 87
ControlAccesstovApps 89
RetrieveaTask 89
6AdministrativeOperations 91
SummaryofAdministrativeRequests 91
AdministratorCredentialsandPrivileges 93
AdministrativeObjectsandURLs 93
GetanAdministrativeViewofaCloud 93
OrganizationAdministration 94
CreateanOrganization 95
GetanAdministrativeViewofanOrganization 96
ListAllTasksOwnedbyanOrganization 97
ModifyanOrganization 97
EnableorDisableanOrganization 98
RemoveanOrganization 99
NetworkAdministration 99
ViewthePropertiesofanExternalNetwork 99
AddaNetworktoanOrganization 100
GetanAdministrativeViewofanOrganizationNetwork 101
ModifyanOrganizationNetwork 101
RemoveanOrganizationNetwork 102
vDCAdministration 102
ExaminetheContentsofaProvidervDC 103
ListtheOrganizationvDCsSupportedbyaProvidervDC 104
AllocateavDCtoanOrganization 104
GetanAdministrativeViewofavDC 106
ModifyavDC 106
EnableorDisableavDC 107
RemoveavDC 107
CatalogAdministration 107
CreateaCatalog 107
GetanAdministrativeViewofaCatalog 108
PublishaCatalog 109
ModifyCatalogMetadata 109
RemoveaCatalog 110
UserAdministration 110
CreateorImportaUser 110
GetanAdministrativeViewofaUser 112
ModifyUserMetadata 112
RemoveaUser 113
GroupAdministration 113
ImportaGroup 113
ViewGroupMetadata 114
ModifyGroupMetadata 114
RemoveaGroup 114

vCloud API Programming Guide
6VMware, Inc.
RoleAdministration 114
CreateaRole 114
ViewRoleMetadata 115
ModifyaRole 116
RemoveaRole 116
ViewaRight 116
7VMwarevSpherePlatformOperations 117
SummaryofvSpherePlatformOperationsRequests 117
ListvSpherePlatformOperationsandObjectsforavCloud 119
ListProvidervDCsinavCloud 120
ListExternalNetworksinavCloud 120
ListNetworkPoolsinavCloud 120
ListvCenterServersRegisteredtoavCloud 120
GetInformationAboutavCenterServer 120
ListAvailableResourcePoolsonavCenterServer 121
ModifyvCenterServerSettings 122
RegisteravCenterServerandvShieldManager 122
UnregisteravCenterServerandvShieldManager 123
ForceReconnectiontoavCenterServer 124
ListESX/ESXiHostsinavCloud 124
GetInformationAboutaHost 124
PrepareaHost 125
UnprepareaHost 126
EnableorDisableaHost 126
RepairaHost 126
UpgradeaHostAgent 127
CreateaProvidervDC 127
ExaminethevSphereObjectsinaProvidervDC 131
ModifyaProvidervDC 131
EnableorDisableaProvidervDC 132
RemoveaProvidervDC 132
CreateanExternalNetwork 133
GetInformationAboutanExternalNetwork 134
ModifyanExternalNetwork 135
RemoveanExternalNetwork 135
CreateaNetworkPool 136
GetInformationAboutaNetworkPool 137
ModifyaNetworkPool 137
RemoveaNetworkPool 138
ImportaVirtualMachinefromvCenter 138
DiscovertheVirtualMachinesinavCenter 138
ImportaVirtualMachineasavApp 139
ImportaVirtualMachineasavAppTemplate 140
8XMLRepresentationsinthevCloud API 141
AboutObjectRepresentations 141
Schema 141
ContentType 142
ObjectReferencePrototype 142
CommonDatatypes 142
PrimitiveXMLDatatypes 142
ComplexTypes 143

VMware, Inc. 7
Contents
CommonAttributes 143
name 144
href 144
type 144
status 144
XMLNamespaceIdentifiers 145
CommonElements 146
Description 146
Error 146
Link 147
APIVersioning 147
SupportedVersions 148
VersionInfo 148
Extensibility 148
VCloudExtension 149
9UserAPIReference 151
OrgList 151
Org 151
Vdc 152
StorageCapacity 153
ComputeCapacity 153
AvailableNetworks 153
ResourceEntities 154
ResourceEntity 154
OrgNetwork 154
Configuration 155
Catalog 160
CatalogItems 160
CatalogItem 160
Media 161
VAppTemplate 161
Children 162
VApp 162
Vm 163
Section 163
LeaseSettingsSection 164
StartupSection 164
CustomizationSection 164
NetworkConfigSection 165
NetworkConnectionSection 165
VirtualHardwareSection 167
OperatingSystemSection 167
GuestCustomizationSection 167
RasdItemsList 168
ScreenTicket 168
TasksList 168
Tasks 168
Task 168
10 RequestParametersReference 171
UploadVAppTemplateParams 171
InstantiateVAppTemplateParams 172
InstantiationParams 172

vCloud API Programming Guide
8VMware, Inc.
ComposeVAppParams 173
Item 173
NetworkAssignment 174
RecomposeVAppParams 174
DeployVAppParams 175
UndeployVAppParams 175
CaptureVAppParams 175
CloneMediaParams 176
CloneVAppTemplateParams 176
CloneVAppParams 176
MediaInsertOrEjectParams 177
VmPendingQuestion 177
VmQuestionAnswer 177
ControlAccessParams 177
AccessSettings 178
11 AdministrativeAPIReference 179
VCloud 179
OrganizationReferences 180
ProviderVdcReferences 180
RightReferences 180
RoleReferences 180
Networks 180
ExternalNetwork 180
AdminOrg 180
Settings 181
Users 185
Groups 185
Catalogs 185
Catalog 186
Vdcs 186
ProviderVdc 186
ComputeCapacity 187
StorageCapacity 188
NetworkPoolReferences 188
NetworkPoolReference 188
VdcReferences 188
AdminVdc 188
AllocationModel 190
User 190
Group 191
Role 191
RightReferences 191
RightReference 191
Right 192
12 vSpherePlatformExtensionsReference 193
VMWExtension 193
VMWProviderVdcReferences 194
VMWExternalNetworkReferences 194
VMWNetworkPoolReferences 194
VMWVimServerReferences 194
VMWHostReferences 194
VimServer 194

VMware, Inc. 9
Contents
VmObjectRefsList 195
VimObjectRef 195
ResourcePoolList 196
ResourcePool 196
ShieldManager 196
VMWProviderVdc 197
VMWNetworkPool 198
FencePoolType 198
PortGroupPoolType 198
VlanPoolType 198
VMWExternalNetwork 199
VlanRange 199
VMWHostReferences 199
Host 199
RequestParameters 200
PrepareHostParams 200
RegisterVimServerParams 200
ImportVmAsVAppParams 201
ImportVmAsVAppTemplateParams 201
AOVFandthevCloudAPI 203
AboutOVF 203
AboutOVFPackages 204
AboutOVAFiles 204
HowthevCloudAPIUsesOVF 204
VirtualMachines 204
VirtualDiskFiles 205
Networks 205
BAnIntroductiontoRESTforvCloudAPIUsers 207
HowRESTWorks 207
UsingthevCloudRESTAPI 207
RESTfulWorkflowPatterns 208
ForMoreInformationAboutREST 208
Index 209

vCloud API Programming Guide
10 VMware, Inc.