VMware vCloud vCloud Director 1.0 User guide

Category
Software
Type
User guide
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-01
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2 VMware, Inc.
vCloud API Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2009, 2011 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
intellectual property laws. VMware products are covered by one or more patents listed at
http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks
and names mentioned herein may be trademarks of their respective companies.
VMware, Inc. 3
Contents
AboutThisBook 11
1 IntroducingtheVMwarevCloudAPI 13
vCloudObjectTaxonomy 13
vCloudOrganizations 13
Objects,References,andRepresentations 15
LinksandLinkRelations 15
vCloudClientWorkflowOverview 17
Requests 17
Responses 18
ConfiguringthevCloudAPIURL 19
RelatedPublications 19
AbouttheExamples 19
2 HellovCloud:AStructuredRESTWorkflowExample 21
LoggingInandGettinganOrganizationList 21
BrowsinganOrganization 22
FindingavAppTemplate 23
GettingInformationAboutavDC 24
InstantiatingtheTemplateinthevDC 24
DeployingandPoweringOnthevApp 26
GettingInformationAboutthevApp 27
DisplayingtheConsole 29
RetrieveaScreenTicket 29
UsetheTicketwithvmwarevmrc 30
DeletingthevApp 30
LoggingOut 30
Movingonto
AdditionalUseCases 31
3 Browsing 33
SummaryofBrowsingRequests 33
DiscoveringtheContentsofanOrganization,Catalog,orvDC 34
ListtheOrganizationsinavCloud 34
ListtheContentsofanOrganization 34
ListtheContentsofaCatalog 35
GetInformationAboutaCatalogItem 36
ListtheContentsofavDC 37
GettingMoreInformationAboutanObject 38
GetInformationAboutaMediaImage 38
Get
InformationAboutavAppTemplate 39
GetInformationAboutavApporVirtualMachine 40
GetInformationAboutaNetwork 40
4 Provisioning 41
SummaryofProvisioningRequests 41
UploadOVFtoCreateavAppTemplate 42
vCloud API Programming Guide
4 VMware, Inc.
RestrictionsonUploadedContent 43
InitiatetheUpload 43
IncludingaManifest 45
UploadingtheFiles 45
ViewtheOVFDescriptorofavAppTemplate 47
DownloadavAppTemplateasOVF 47
EnableavAppTemplateforDownload 48
DisableavAppTemplateforDownload 49
UploadaMediaImage 50
CopyingandMoving 50
CopyorMoveaMediaImage 51
CopyorMovea
vAppTemplate 51
CopyorMoveavApp 52
ChangingaNameorDescription 53
ChangetheNameorDescriptionofavAppTemplate 53
ChangetheNameorDescriptionofavApp 53
ChangetheNameorDescriptionofaMediaImage 54
DeleteavAppTemplate,vApp,orMediaImage 54
CatalogingvAppTemplatesandMediaImages 54
AddanItemtoa
Catalog 54
RemoveanItemfromaCatalog 56
CatalogLinksinaVAppTemplateorMediaImage 56
ControllingAccess 56
ControlAccesstoCatalogs 56
5 DatacenterOperations 59
SummaryofDatacenterOperationsRequests 59
vAppLifecycle 60
InstantiateavAppTemplate 61
AboutInstantiationParameters 62
AboutvAppNetworks 62
InstantiatingavAppTemplateUsingDefaultParameters 62
InstantiatingavAppTemplateUsingAdditionalParameters 62
RetrieveorModifytheCustomizationSectionofavAppTemplate 64
ComposeavApp 65
FindingVirtualMachineURLstoUseinaCompositionItem 66
RecomposeavAppto
AddorRemoveVirtualMachines 67
CaptureavApptoCreateavAppTemplate 68
ReconfiguringvAppsandVirtualMachines 69
ReconfigureavApp 69
ReconfigureaVirtualMachine 73
DeployingandControllingvAppsandVirtualMachines 80
DeployavApporVirtualMachine 80
UndeployavApporVirtualMachine 81
PowerOnavApporVirtualMachine 81
PowerOffavApp
orVirtualMachine 82
ResetavApporVirtualMachine 82
SuspendavApporVirtualMachine 83
DiscardtheSuspendedStateofavApporVirtualMachine 83
ShutDownavApporVirtualMachine 8 4
RebootavApporVirtualMachine 84
ListMediaDevicesofaVirtualMachine 85
InsertMediaIntoaVirtualMachine 85
EjectMediafrom
aVirtualMachine 86
GetaScreenThumbnailforaVirtualMachine 86
VMware, Inc. 5
Contents
GetaScreenTicketforaVirtualMachine 87
ProvideUserInputRequestedbyaVirtualMachine 87
ControlAccesstovApps 89
RetrieveaTask 89
6 AdministrativeOperations 91
SummaryofAdministrativeRequests 91
AdministratorCredentialsandPrivileges 93
AdministrativeObjectsandURLs 93
GetanAdministrativeViewofaCloud 93
OrganizationAdministration 94
CreateanOrganization 95
GetanAdministrativeViewofanOrganization 96
ListAllTasksOwnedbyanOrganization 97
ModifyanOrganization 97
EnableorDisableanOrganization 98
RemoveanOrganization 9 9
NetworkAdministration 99
ViewthePropertiesofanExternal
Network 99
AddaNetworktoanOrganization 100
GetanAdministrativeViewofanOrganizationNetwork 101
ModifyanOrganizationNetwork 101
RemoveanOrganizationNetwork 102
vDCAdministration 102
ExaminetheContentsofaProvidervDC 103
ListtheOrganizationvDCsSupportedbyaProvidervDC 104
AllocateavDCtoanOrganization 104
GetanAdministrativeViewofavDC 106
Modify
avDC 106
EnableorDisableavDC 107
RemoveavDC 107
CatalogAdministration 107
CreateaCatalog 107
GetanAdministrativeViewofaCatalog 108
PublishaCatalog 109
ModifyCatalogMetadata 109
RemoveaCatalog 110
UserAdministration 110
CreateorImportaUser 110
GetanAdministrativeViewofaUser 112
ModifyUserMetadata 112
RemoveaUser 113
GroupAdministration 113
ImportaGroup 113
ViewGroupMetadata 114
ModifyGroupMetadata 114
RemoveaGroup 114
RoleAdministration 114
CreateaRole 114
ViewRoleMetadata 115
ModifyaRole 116
RemoveaRole 116
ViewaRight 116
vCloud API Programming Guide
6 VMware, Inc.
7 VMwarevSpherePlatformOperations 117
SummaryofvSpherePlatformOperationsRequests 117
ListvSpherePlatformOperationsandObjectsforavCloud 119
ListProvidervDCsinavCloud 120
ListExternalNetworksinavCloud 120
ListNetworkPoolsinavCloud 120
ListvCenterServersRegisteredtoavCloud 120
GetInformationAboutavCenterServer 120
ListAvailableResourcePoolsonavCenterServer 121
ModifyvCenterServerSettings 122
RegisteravCenterServerandvShieldManager 122
UnregisteravCenterServerandvShieldManager 123
ForceReconnectiontoavCenterServer 124
ListESX/ESXiHostsinavCloud 124
GetInformationAboutaHost 124
PrepareaHost 125
UnprepareaHost 126
EnableorDisableaHost 126
RepairaHost 126
UpgradeaHostAgent 127
CreateaProvidervDC 127
ExaminethevSphereObjectsinaProvidervDC 131
ModifyaProvidervDC 131
EnableorDisableaProvidervDC 132
RemoveaProvidervDC 132
CreateanExternalNetwork 133
GetInformationAboutanExternalNetwork 134
ModifyanExternalNetwork 135
RemoveanExternalNetwork 135
CreateaNetworkPool 136
GetInformationAboutaNetworkPool 137
ModifyaNetworkPool 137
Removea
NetworkPool 138
ImportaVirtualMachinefromvCenter 138
DiscovertheVirtualMachinesinavCenter 138
ImportaVirtualMachineasavApp 139
ImportaVirtualMachineasavAppTemplate 140
8 XMLRepresentationsinthevCloud API 141
AboutObjectRepresentations 141
Schema 141
ContentType 142
ObjectReferencePrototype 142
CommonDatatypes 142
PrimitiveXMLDatatypes 142
ComplexTypes 143
CommonAttributes 143
name 144
href 144
type 144
status 144
XMLNamespaceIdentifiers 145
CommonElements 146
Description 146
Error 146
VMware, Inc. 7
Contents
Link 147
APIVersioning 147
SupportedVersions 148
VersionInfo 148
Extensibility 148
VCloudExtension 149
9 UserAPIReference 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 RequestParametersReference 171
UploadVAppTemplateParams 171
InstantiateVAppTemplateParams 172
InstantiationParams 172
ComposeVAppParams 173
Item 173
NetworkAssignment 174
RecomposeVAppParams 174
DeployVAppParams 175
UndeployVAppParams 175
CaptureVAppParams 175
CloneMediaParams 176
CloneVAppTemplateParams 176
vCloud API Programming Guide
8 VMware, Inc.
CloneVAppParams 176
MediaInsertOrEjectParams 177
VmPendingQuestion 177
VmQuestionAnswer 177
ControlAccessParams 177
AccessSettings 178
11 AdministrativeAPIReference 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 vSpherePlatformExtensionsReference 193
VMWExtension 193
VMWProviderVdcReferences 194
VMWExternalNetworkReferences 194
VMWNetworkPoolReferences 194
VMWVimServerReferences 194
VMWHostReferences 194
VimServer 194
VmObjectRefsList 195
VimObjectRef 195
ResourcePoolList 196
ResourcePool 196
ShieldManager 196
VMWProviderVdc 197
VMWNetworkPool 198
FencePoolType 198
PortGroupPoolType 198
VlanPoolType 198
VMware, Inc. 9
Contents
VMWExternalNetwork 199
VlanRange 199
VMWHostReferences 199
Host 199
RequestParameters 200
PrepareHostParams 200
RegisterVimServerParams 200
ImportVmAsVAppParams 201
ImportVmAsVAppTemplateParams 201
A OVFandthevCloudAPI 203
AboutOVF 203
AboutOVFPackages 204
AboutOVAFiles 204
HowthevCloudAPIUsesOVF 204
VirtualMachines 204
VirtualDiskFiles 205
Networks 205
B AnIntroductiontoRESTforvCloudAPIUsers 207
HowRESTWorks 207
UsingthevCloudRESTAPI 207
RESTfulWorkflowPatterns 208
ForMoreInformationAboutREST 208
Index 209
vCloud API Programming Guide
10 VMware, Inc.
VMware, Inc. 11
ThevCloudAPIProgrammingGuideprovidesinformationaboutversion1.0ofthevCloudAPI.
VMwareprovidesmanydifferentAPIsandSDKsforvariousapplicationsandgoals.Thisbookprovides
informationaboutthevCloudAPIfordevelopersthatareinterestedincreatingRESTfulclientsofVMware
CloudDirector.
Toviewthecurrent
versionofthisbookaswellasallVMwareAPIandSDKdocumentation,goto
http://www.vmware.com/support/pubs/sdk_pubs.html.
Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor
ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisbook.
Intended Audience
ThisguideisintendedforsoftwaredeveloperswhoarebuildingVMwareReadyCloudServices,including
interactiveclientsofVMwareCloudDirector.ThisguideassumesyouarefamiliarwithRepresentationalState
Transfer(REST)andRESTfulprogrammingconventions,theOpenVirtualizationFormatSpecification,and
VMwareVirtualmachinetechnology.Familiaritywithotherwidelydeployed
technologiessuchasXML,
HTTP,andtheWindowsorLinuxoperatingsystemsisalsoassumed.
VMware Technical Publications Glossary
VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions
oftermsastheyareusedinVMwaretechnicaldocumentationgotohttp://www.vmware.com/support/pubs.
Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto
About This Book
Table 1. Revision History
Revision Date Description
08MAR11 GuestCustomizationSectionnotallowedinInstantiationParams
30AUG10 Version1.0
vCloud API Programming Guide
12 VMware, Inc.
Technical Support and Education Resources
Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Toaccessthecurrentversions
ofotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.
Online and Telephone Support
Touseonlinesupporttosubmittechnicalsupportrequests,viewyourproductandcontractinformation,and
registeryourproducts,gotohttp://www.vmware.com/support.
Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto
http://www.vmware.com/support/services.
VMware Professional Services
VMwareEducationServicescoursesofferextensivehandsonlabs,casestudyexamples,andcoursematerials
designedtobeusedasonthejobreferencetools.Coursesareavailableonsite,intheclassroom,andlive
online.Foronsitepilotprograms andimplementationbestpractices,VMwareConsultingServicesprovides
offeringsto helpyouassess,plan,
build,andmanageyourvirtualenvironment.Toaccessinformationabout
educationclasses,certificationprograms,andconsultingservices,gotohttp://www.vmware.com/services.
VMware, Inc. 13
1
TheVMwarevCloudAPIprovidessupportfordeveloperswhoarebuildinginteractiveclientsofVMware
CloudDirectorusingaRESTfulapplicationdevelopmentstyle.vCloudAPIclientsandserverscommunicate
overHTTP,exchangingrepresentationsofvCloudobjects.TheserepresentationstaketheformofXML
elements.HTTPGETrequestsareusedtoretrieve
thecurrentrepresentationofanobject,HTTPPOSTand
PUTrequestsareusedtocreateormodifyanobject,andHTTPDELETErequestsaretypicallyusedtodelete
anobject.
ThischapterintroducesthevCloudAPIandincludesthefollowingtopics:
“vCloudObjectTaxonomy”onpage 13
“Objects,References,andRepresentations”onpage 15
“LinksandLinkRelations”onpage 15
“vCloudClientWorkflowOverviewonpage 17
“A b o u t theExamples”onpage 19
vCloud Object Taxonomy
ThevCloudAPIdefinesasetofobjectscommontocloudcomputingenvironments.Figure 11illustratesthe
principalobjecttypes.
vCloud Organizations
AvCloudcontainsoneormoreorganizations.AvCloudorganizationisaunitofadministrationfora
collectionofusers,groups,andcomputingresources.Usersauthenticateattheorganizationlevel,supplying
credentialsestablishedbyanorganizationadministratorwhentheuserwascreatedorimported.
vCloud Users and Groups
Anorganizationcancontainanarbitrarynumberofusersandgroups.Userscanbecreatedbythe
organizationadministratororimportedfromadirectoryservicesuchasLDAP.Groupsmustbeimported
fromthedirectoryservice.Permissionswithinanorganizationarecontrolledthroughtheassignmentofrights
androlestousers
andgroups.
vCloud Networks
Anorganizationcanbeprovisionedwithoneormorenetworks.Theseorganizationnetworkscanbe
configuredtoprovideservicessuchasDHCP,NAT,andfirewalls.
Introducing the VMware vCloud API
1
vCloud API Programming Guide
14 VMware, Inc.
Figure 1-1. vCloud Object Taxonomy
vCloud Virtual Datacenters
AvCloudvirtualdatacenter(vDC)isanallocationmechanismforresourcessuchasnetworks,storage,CPU,
andmemory.InavDC,computingresourcesarefullyvirtualized,andcanbeallocatedbasedondemand,
servicelevelrequirements,oracombinationofthetwo.
TherearetwokindsofvDCs:
ProvidervDCs.ThesevDCscontainalltheresourcesavailablefromthevCloudserviceprovider.
ProvidervDCsarecreatedandmanagedbyvCloudsystemadministrators.
OrganizationvDCs.ThesevDCsprovideanenvironmentwherevirtualsystemscanbestored,deployed,
andoperated.Theyalsoprovidestorageforvirtualmedia,suchasfloppydisksandCDROMs.
AnorganizationadministratorspecifieshowresourcesfromaprovidervDCaredistributedtothevDCsinan
organization.
vCloud Catalogs
Catalogscontainreferencestovirtualsystemsandmediaimages.Acatalogcanbesharedtomakeitvisibleto
othermembersofanorganization,andcanbepublishedtomakeitvisibletootherorganizations.AvCloud
systemadministratorspecifieswhichorganizationscanpublishcatalogs,andanorganizationadministrator
controlsaccess
tocatalogsbyorganizationmembers.
vCloud Tasks
Longrunningoperationsinitiatedbymembersofanorganizationcreatetasks,whicharekeptonthe
organization’staskslist.
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
Network
Network
Catalogitem
em
em
em
groups
VMware, Inc. 15
Chapter 1 Introducing the VMware vCloud API
Virtual Systems and Media Images in a vCloud
VirtualsystemsandmediaimagesarestoredinavDCandcanbeincludedinacatalog.Mediaimagesare
storedintheirnativerepresentation(ISOorfloppy).Virtualsystemsarestoredastemplates,usinganopen
standardformat(OVF1.0).Thesetemplatescanberetrievedfromcatalogsandtransformedinto
virtual
systems,calledvApps,throughaprocesscalledinstantiation,whichbindsatemplate’sabstractresource
requirementstoresourcesavailableinavDC.AvAppcontainsoneormoreindividualvirtualmachines(Vm
elements),alongwithparametersthatdefineoperationaldetailssuchas:
Howthecontainedvirtualmachinesareconnectedtoeachotherandtoexternalnetworks.
Theorderinwhichindividualvirtualmachinesarepoweredonoroff.
Enduserlicenseagreementtermsforeachvirtualmachine.
Deploymentleaseterms(typicallyinheritedfromthecontainingorganization)thatconstrainthevApp’s
consumptionofvDCresources
Accesscontrolinformationspecifyingwhichusersandgroupscanperformoperationssuchasdeploy,
poweron,modify,andsuspendonthevAppandthevirtualmachinesitcontains.
Objects, References, and Representations
ThevCloudAPIrepresentsobjectsinthevCloudasXMLdocumentsinwhichobjectpropertiesareencoded
aselementsandattributeswithtypedvaluesandanexplicitobjecthierarchydefinedbyanXMLschema.
EveryobjectinavCloudisuniquelyidentifiedbyaURL.ThisURLisconstructedbythe
serverandreturned
inthevalueofthehrefattributeoftheXMLelementthatrepresentstheobject.Italsoappearsinvarious
elementsofLinkTypeandReferenceType.ThisURLservesasauniqueidentifierthatpersistsforthelifeof
theobjectandisneverreused.AlthoughURLs
haveawellknownsyntaxandawellunderstood
interpretation,aclientshouldtreateachhrefasanopaquestring.Therulesthatgovernconstructionofhref
stringsbytheservermightchangeinfuturereleases.
Objecttypes,specifiedasMIMEcontenttypes,areincludedintheXMLrepresentationsoffirst
classobjects
suchastheonesshowninFigure 11.Formoreinformation,see“ContentTypeonpage 142.
Links and Link Relations
ThevCloudAPImakesextensiveuseoflinks(URLs)toprovidereferencestoobjectsandtheactionsthatthey
support.Theselinksaretheprimarymechanismbywhichaservertellsaclienthowtoaccessandoperateon
anobject.Linksarecreatedbytheserver,andarereadonly
attheclient.(Ifaclientrequestbodyincludesa
link,theserverignoresit.)
IntheXMLrepresentationofavCloudobject,eachlinkisdefinedinaLinkelementthathasthefollowing
form:
<Link rel="
relationship
" type="application/vnd.vmware.vcloud.type+xml" href="
URL
" name="
string
"/>
TherelattributevaluedefinestherelationshipoftheobjectwhoseXMLrepresentationcontainstheLink
toatargetobject.TherelationshipalsoindicatestheHTTPrequesttypetousewhenmakingarequest
withthehrefattributeofthelink,asshowninTable 11:
Table 1-1. Link Relationships and HTTP Request Types
rel Attribute Value Relation Description HTTP Request
add addsanitemtothiscontainer POST
alternate alinktoanalternaterepresentationofthisobject GET
catalogItem alinktothecatalogItemthatcontainsareferencetothisobject. GET
controlAccess applyaccesscontrols POST
copy notsupportedinthisrelease N/A
deploy deploythisobject POST
vCloud API Programming Guide
16 VMware, Inc.
Thetypeattributevaluedefinesthemediatype(HTTPContentType)oftherequestorresponse
document.Thisattributeispresentonlyforlinkstoobjects.Itisnotpresentforlinkstoactions.
ThehrefattributevalueisaURL,whichshouldbeconsideredanopaqueidentifier(onethattheclient
shouldnotattempttoparseorinterpret).Anhrefuniquelyidentifies,andpersistsforthelifeof,the
referencedobject.Theseidentifiersareneverreused.
ThenameattributevalueoftheLinkisthesameasthenameofthereferencedobject.Actionlinksdonot
includeanameattribute.
disable disablethisobject POST
discardState discardthesuspendedstateofthisvirtualmachine POST
down thereferencedobjectiscontainedbythisobject GET
download:alternate notsupportedinthisrelease N/A
download:default defaultdownloadlocationforthisfile GET
edit modifiesthisobject PUT
enable enablethisobject POST
extension notsupportedinthisrelease N/A
media:ejectMedia ejectvirtualmediafromavirtualdevice POST
media:insertMedia insertvirtualmediainavirtualdevice POST
move not
supportedinthisrelease N/A
ova notsupportedinthisrelease N/A
ovf theOVFrepresentationofthisvAppTemplate GET
power:powerOff poweroffthereferencedobject POST
power:powerOn poweronthisobject POST
power:reboot rebootthisobject POST
power:reset resetthisobject POST
power:shutdown shutdownthisobject POST
power:suspend suspendthisobject POST
publish publishthiscatalog POST
recompose recomposethisvApp POST
reconnect reconnectthisvCenterServer POST
register registerthisvCenterServer POST
remove removethisobject DELETE
repair repairthishost POST
screen:acquireTicket acquire
ascreenticketforthisvirtualmachine GET
screen:thumbnail thumbnailviewofavirtualmachinescreen,inpngformat GET
task:cancel notsupportedinthisrelease N/A
undeploy undeploythisobject POST
unregister unregisterthisvCenterServer POST
up thereferencedobjectcontainsthisobject GET
upgrade upgradethishost POST
upload:alternate notsupportedinthisrelease N/A
upload:default defaultuploadlocationforthisfile PUT
Table 1-1. Link Relationships and HTTP Request Types (Continued)
rel Attribute Value Relation Description HTTP Request
VMware, Inc. 17
Chapter 1 Introducing the VMware vCloud API
Linksprovideawayfortheservertoinformaclientaboutobjectrelationshipsandtheoperationsthatobjects
support.Forexample,acontainersuchasanorganizationorcatalogcanreturnlinkstotheobjectsitcontains,
andavirtualsystem(avApporVm)cancontainactionlinks
thatenableoperationssuchaspowerstatechanges
orvirtualdevicereconfiguration.Linkstoactionsandcontainedobjectsareomittedfromresponsesifthe
requestwasmadebyauserwhohasinsufficientprivilegestoaccesstheobjectorperformtheaction.Action
linksarealsoomittedwhentheactioncannot
beperformed(poweringonavirtualmachinethatisalready
poweredon,forexample).
vCloud Client Workflow Overview
ClientsofthevCloudAPIimplementaRESTfulworkflow,makingHTTPrequeststotheserverandretrieving
theinformationtheyneedfromtheserversresponses.
Requests
ClientsmakeHTTPrequeststovCloudURLs,hrefattributevalueswhicharetypicallyprovidedbytheserver
inresponsetoGETrequestsbytheclient.EveryvCloudhasawellknownURLfromwhichaclientcangetthe
serversloginURLandthelistofvCloudAPIversionsthatthe
serversupports,alongwithadditional
information(see“AP I Versioning”onpage 147).Afteraclienthasloggedin,allvCloudAPIURLscanbe
discoveredbymakingGETrequeststoURLslistedintheloginresponseandtheURLscontainedinresponses
tothoserequests.
Request Headers
Allrequestsfromauthenticatedclientsmustincludeanauthenticationheader.SeeAuthentication”on
page 18.
RequeststhatincludeadocumentbodymuststartwiththeappropriateHTTPContentTypeheader.Thetype
attributeofaresponsebodyindicatesthecontenttypeofthedocument.Forexample,thisresponsefragment
indicatesthatthe
contenttypeassociatedwithaCatalogItem entityis
application/vnd.vmware.vcloud.catalogItem+xml.
<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml"
href="http://vcloud.example.com/api/v1.0/catalogItem/221" name="Ubuntu Template with
vsftpd"/>
AnyrequestthatincludesaCatalogItemrequiresthefollowingContentTypeheader:
Content-Type: application/vnd.vmware.vcloud.catalogItem+xml
Whenitappearsas thevalueofaContentTypeheaderorthetypeattributeofanelementinthevCloudAPI,
thisstringiscaseinsensitiveinrequests,andcanbereturnedineithermixedcaseorlowercasecharactersin
responses.
Formoreinformation,see“ContentTypeonpage 142.
Request Bodies
ThisreleaseofCloudDirectorusesavalidatingXMLparserthatrequireselementsinarequestbodytoagree
inbothorderandnumberwiththeschema.Requestbodiesarerejectedasinvalidunlesstheymeetthe
followingcriteria:
XMLnamespaceattributesmustbesuppliedforallnamespacesrepresentedbyelementsintherequest.
See“XMLNamespaceIdentifiers”onpage 145.
Ifmultiplenamespacesarerepresentedintherequest,XMLnamespaceattributesmustincludean
identifyingprefix,andthatprefixmustbeusedwithelementsfromthatnamespace.See“XML
NamespacePrefixesinRequestandResponseBodies”onpage 146.
N
OTEWhenaclientusesalinktoreferenceanobject,onlythehrefattributeisrequired.Thenameandtype
areignored.
vCloud API Programming Guide
18 VMware, Inc.
Allrequiredelementsmustappearinrequestbodies.Allelementsthatappearinrequestbodiesmust
appearintheorderestablishedbytheschema,andwithcontentthatconformstothetypeconstraint
specifiedintheschema.See“SchemaValidationonpage 142.
Authentication
HTTPcommunicationsbetweenavCloudclientandserveraretypicallysecuredwithSSL.Inaddition,the
vCloudAPIimplementsBasicHTTPAuthentication,asdefinedbyRFC2617,whichenablesaclienttoobtain
atokenthatitcanusetoauthenticateindividualHTTPrequests.
Toobtainanduseanauthenticationtoken,
aclientmustfirstdiscovertheserversloginURL,andthenPOST
aloginrequesttothatURL,supplyingthecredentialsofanauthorizeduser.
To obtain and use an authentication token
1MakeanAPIversionrequesttoavCloudservicetoobtaintheloginURLforthatservice.Formore
information,see“A P I Versioningonpage 147.
2Make
anHTTPPOSTrequesttotheloginURL,asshowninExample 21onpage 21.
Iftheauthenticationheaderismissing,theserverreturnsHTTPresponsecode401.
Ifthecredentialssuppliedintheauthenticationheaderareinvalid,theserverreturnsHTTPresponse
code401.
Iftherequestissuccessful,theserverreturnsHTTPresponsecode200(OK)andheadersthatinclude
anauthorizationheaderoftheform:
x-vcloud-authorization:
token
ThisheadermustbeincludedineachsubsequentvCloudAPIrequest.
TheresponsebodyisanOrgListelement,whichisalistofallorganizationsthattheusercanaccess.
Theauthenticationtokenexpiresafteraconfigurableintervalofclientinactivity.Thedefaultis30minutesafter
thetokeniscreated.After
thetokenexpires,allrequestsfailwithHTTPresponsecode401untiltheclientlogs
inagaintoobtainanewtoken.
Responses
AllresponsesincludeanHTTPstatuscodeand,unlessthestatuscodeis204(NoContent),aContentType
header.Responsecontentdependsontherequest.Someresponsesincludeadocumentbody,someinclude
onlyaURL,andsomeareempty.
Status Codes
Table 12liststhesubsetofHTTPstatuscodesthatavCloudAPIclientcanexpectinaresponse.
N
OTECertainadministrativeoperationshavespecialauthenticationrequirements.Formoreinformation,see
AdministratorCredentialsandPrivileges”onpage 93.
Table 1-2. HTTP Status Codes Returned by the vCloud API
Status Code Status Description
200OK Therequestisvalidandwascompleted.Theresponseincludesadocumentbody.
201Created Therequestisvalid.TherequestedobjectwascreatedandcanbefoundattheURLspecifiedin
theLocationheader.
202Accepted Therequestisvalidandataskwascreatedtohandleit.Thisresponse
isusuallyaccompanied
byataskURL.
204NoContent Therequestisvalidandwascompleted.Theresponsedoesnotincludeabody.
303SeeOther TheresponsetotherequestcanbefoundattheURLspecifiedintheLocationheader .
400BadRequest Therequestbodyismalformed,incomplete,or
otherwiseinvalid.
VMware, Inc. 19
Chapter 1 Introducing the VMware vCloud API
Configuring the vCloud API URL
ThebaseURLusedinhrefvaluesincludesthefullyqualifieddomainnameoftheserverhost.Incaseswhere
thishostnamecannotberesolvedfromtheclient(forexample,iftheCloudDirectorinstallationincludes
multipleserverhoststhatyouaccessthroughaloadbalancer)youcanspecifyaURL
fortheservertousewhen
constructinghrefstrings.Formoreinformation,seeConfiguretheExternalRESTAPIBaseURIintheCloud
DirectorAdministratorʹsGuide.
Related Publications
TheVMwareCloudDirectorAdministratorʹsGuideandVMwareCloudDirectorUser’sGuidecontaindetailed
informationaboutmanyoftheobjectsandoperationsreferredtointhisguide.MostusersofthevCloudAPI
willfindtheinformationinthosedocumentsvaluablewhendevelopingclientapplications.Toaccessthe
currentversions
oftheseandotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.
About the Examples
ThisguideincludesmanyexamplesofHTTPrequestsandresponses.Theseexamplesareintendedtoshow
theworkflowandcontentassociatedwithspecifictypesofoperationssuchasbrowsing,managinginventory,
andoperatingvirtualsystems.Examplerequestsgenerallyconformtotheruleslistedin“RequestBodies”on
page 17.Mostexampleresponses
showonlythoseelementsandattributesthatarerelevanttotheoperation
beingdiscussed.Ellipses(…)indicateomittedcontentwithinresponsebodies.
HTTPContentTypeheadersareshownwhereneededforallexamplesthatarenotfragmentsofsomelarger
examplethatincludesthisheader.Althoughtheexamplesshowthesestrings
usingthecharactercaseinwhich
theyaredefinedbytheimplementation,thesestringsarecaseinsensitiveinrequests,andcanbereturnedin
eithermixedcaseorlowercasecharactersinresponses.OtherHTTPheaders,suchasDate,ContentLength,
andServer,areomittedbecausetheyarenotrelevantto
thespecificsofanyexample.TheXMLversionand
encodingheader(<?xml version="1.0" encoding="UTF-8"?>)isnotincludedinmostexamples,although
itisarequiredpartofallrequestsandresponsesthatcontainanXMLbody.
Inaddition:
UnsecuredURLs(http://)areusedintheexamples.Inpractice,mostsiteswillrequiretheuseofSSL
(https://).
ObjectIDsshowninhrefattributevaluesappearassmallintegers(forexamplevapp-7ororg/3).Inthe
vCloudAPIsupportedbyCloudDirector,objectIDsare10digitdecimalintegers(forexample
vapp-124237959ororg/5738592905).
401Unauthorized Anauthorizationheaderwasexpectedbutnotfound.
403Forbidden Therequestinguserdoesnothaveadequateprivilegestoaccessoneormoreobjectsspecified
intherequest.
404NotFound Oneormoreobjectsspecifiedintherequestcouldnotbefoundinthespecifiedcontainer.
405MethodNot
Allowed
TheHTTP
methodspecifiedintherequestisnotsupportedforthisobject.
500InternalServer
Error
Therequestwasreceivedbutcouldnotbecompletedduetoaninternalerrorattheserver.
501NotImplemented Therequestisnotimplementedbytheserver.
503Service
Unavailable
Oneormoreservicesneededto
completetherequestarenotavailableontheserver.
Table 1-2. HTTP Status Codes Returned by the vCloud API (Continued)
Status Code Status Description
vCloud API Programming Guide
20 VMware, Inc.
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40
  • Page 41 41
  • Page 42 42
  • Page 43 43
  • Page 44 44
  • Page 45 45
  • Page 46 46
  • Page 47 47
  • Page 48 48
  • Page 49 49
  • Page 50 50
  • Page 51 51
  • Page 52 52
  • Page 53 53
  • Page 54 54
  • Page 55 55
  • Page 56 56
  • Page 57 57
  • Page 58 58
  • Page 59 59
  • Page 60 60
  • Page 61 61
  • Page 62 62
  • Page 63 63
  • Page 64 64
  • Page 65 65
  • Page 66 66
  • Page 67 67
  • Page 68 68
  • Page 69 69
  • Page 70 70
  • Page 71 71
  • Page 72 72
  • Page 73 73
  • Page 74 74
  • Page 75 75
  • Page 76 76
  • Page 77 77
  • Page 78 78
  • Page 79 79
  • Page 80 80
  • Page 81 81
  • Page 82 82
  • Page 83 83
  • Page 84 84
  • Page 85 85
  • Page 86 86
  • Page 87 87
  • Page 88 88
  • Page 89 89
  • Page 90 90
  • Page 91 91
  • Page 92 92
  • Page 93 93
  • Page 94 94
  • Page 95 95
  • Page 96 96
  • Page 97 97
  • Page 98 98
  • Page 99 99
  • Page 100 100
  • Page 101 101
  • Page 102 102
  • Page 103 103
  • Page 104 104
  • Page 105 105
  • Page 106 106
  • Page 107 107
  • Page 108 108
  • Page 109 109
  • Page 110 110
  • Page 111 111
  • Page 112 112
  • Page 113 113
  • Page 114 114
  • Page 115 115
  • Page 116 116
  • Page 117 117
  • Page 118 118
  • Page 119 119
  • Page 120 120
  • Page 121 121
  • Page 122 122
  • Page 123 123
  • Page 124 124
  • Page 125 125
  • Page 126 126
  • Page 127 127
  • Page 128 128
  • Page 129 129
  • Page 130 130
  • Page 131 131
  • Page 132 132
  • Page 133 133
  • Page 134 134
  • Page 135 135
  • Page 136 136
  • Page 137 137
  • Page 138 138
  • Page 139 139
  • Page 140 140
  • Page 141 141
  • Page 142 142
  • Page 143 143
  • Page 144 144
  • Page 145 145
  • Page 146 146
  • Page 147 147
  • Page 148 148
  • Page 149 149
  • Page 150 150
  • Page 151 151
  • Page 152 152
  • Page 153 153
  • Page 154 154
  • Page 155 155
  • Page 156 156
  • Page 157 157
  • Page 158 158
  • Page 159 159
  • Page 160 160
  • Page 161 161
  • Page 162 162
  • Page 163 163
  • Page 164 164
  • Page 165 165
  • Page 166 166
  • Page 167 167
  • Page 168 168
  • Page 169 169
  • Page 170 170
  • Page 171 171
  • Page 172 172
  • Page 173 173
  • Page 174 174
  • Page 175 175
  • Page 176 176
  • Page 177 177
  • Page 178 178
  • Page 179 179
  • Page 180 180
  • Page 181 181
  • Page 182 182
  • Page 183 183
  • Page 184 184
  • Page 185 185
  • Page 186 186
  • Page 187 187
  • Page 188 188
  • Page 189 189
  • Page 190 190
  • Page 191 191
  • Page 192 192
  • Page 193 193
  • Page 194 194
  • Page 195 195
  • Page 196 196
  • Page 197 197
  • Page 198 198
  • Page 199 199
  • Page 200 200
  • Page 201 201
  • Page 202 202
  • Page 203 203
  • Page 204 204
  • Page 205 205
  • Page 206 206
  • Page 207 207
  • Page 208 208
  • Page 209 209
  • Page 210 210
  • Page 211 211
  • Page 212 212

VMware vCloud vCloud Director 1.0 User guide

Category
Software
Type
User guide

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI