VCD 10 API 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
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. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com
VMware, Inc.
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 BrowsinganOrganization 22 FindingavAppTemplate 23 GettingInformationAboutavDC 24 InstantiatingtheTemplateinthevDC 24 DeployingandPoweringOnthevApp 26 GettingInformationAboutthevApp 27 DisplayingtheConsole 29 RetrieveaScreenTicket 29 UsetheTicketwithvmwarevmrc 30 DeletingthevApp 30 LoggingOut 30 MovingontoAdditionalUseCases 31 21
3 Browsing 33
SummaryofBrowsingRequests 33 DiscoveringtheContentsofanOrganization,Catalog,orvDC 34 ListtheOrganizationsinavCloud 34 ListtheContentsofanOrganization 34 ListtheContentsofaCatalog 35 GetInformationAboutaCatalogItem 36 ListtheContentsofavDC 37 GettingMoreInformationAboutanObject 38 GetInformationAboutaMediaImage 38 GetInformationAboutavAppTemplate 39 GetInformationAboutavApporVirtualMachine 40 GetInformationAboutaNetwork 40
4 Provisioning 41
SummaryofProvisioningRequests 41 UploadOVFtoCreateavAppTemplate 42
VMware, Inc.
RestrictionsonUploadedContent 43 InitiatetheUpload 43 IncludingaManifest 45 UploadingtheFiles 45 ViewtheOVFDescriptorofavAppTemplate 47 DownloadavAppTemplateasOVF 47 EnableavAppTemplateforDownload 48 DisableavAppTemplateforDownload 49 UploadaMediaImage 50 CopyingandMoving 50 CopyorMoveaMediaImage 51 CopyorMoveavAppTemplate 51 CopyorMoveavApp 52 ChangingaNameorDescription 53 ChangetheNameorDescriptionofavAppTemplate 53 ChangetheNameorDescriptionofavApp 53 ChangetheNameorDescriptionofaMediaImage 54 DeleteavAppTemplate,vApp,orMediaImage 54 CatalogingvAppTemplatesandMediaImages 54 AddanItemtoaCatalog 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 RecomposeavApptoAddorRemoveVirtualMachines 67 CaptureavApptoCreateavAppTemplate 68 ReconfiguringvAppsandVirtualMachines 69 ReconfigureavApp 69 ReconfigureaVirtualMachine 73 DeployingandControllingvAppsandVirtualMachines 80 DeployavApporVirtualMachine 80 UndeployavApporVirtualMachine 81 PowerOnavApporVirtualMachine 81 PowerOffavApporVirtualMachine 82 ResetavApporVirtualMachine 82 SuspendavApporVirtualMachine 83 DiscardtheSuspendedStateofavApporVirtualMachine 83 ShutDownavApporVirtualMachine 84 RebootavApporVirtualMachine 84 ListMediaDevicesofaVirtualMachine 85 InsertMediaIntoaVirtualMachine 85 EjectMediafromaVirtualMachine 86 GetaScreenThumbnailforaVirtualMachine 86
VMware, Inc.
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 99 NetworkAdministration 99 ViewthePropertiesofanExternalNetwork 99 AddaNetworktoanOrganization 100 GetanAdministrativeViewofanOrganizationNetwork 101 ModifyanOrganizationNetwork 101 RemoveanOrganizationNetwork 102 vDCAdministration 102 ExaminetheContentsofaProvidervDC 103 ListtheOrganizationvDCsSupportedbyaProvidervDC 104 AllocateavDCtoanOrganization 104 GetanAdministrativeViewofavDC 106 ModifyavDC 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
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 RemoveaNetworkPool 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.
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
VMware, Inc.
CloneVAppParams 176 MediaInsertOrEjectParams 177 VmPendingQuestion 177 VmQuestionAnswer 177 ControlAccessParams 177 AccessSettings 178
11 AdministrativeAPIReference 179
VCloud 179 OrganizationReferences ProviderVdcReferences 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 NetworkPoolReference VdcReferences 188 AdminVdc 188 AllocationModel 190 User 190 Group 191 Role 191 RightReferences 191 RightReference 191 Right 192 180 180
188 188
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
8 VMware, Inc.
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
VMware, Inc.
10
VMware, Inc.
About This Book
ThevCloudAPIProgrammingGuideprovidesinformationaboutversion1.0ofthevCloudAPI. VMwareprovidesmanydifferentAPIsandSDKsforvariousapplicationsandgoals.Thisbookprovides informationaboutthevCloudAPIfordevelopersthatareinterestedincreatingRESTfulclientsofVMware CloudDirector. ToviewthecurrentversionofthisbookaswellasallVMwareAPIandSDKdocumentation,goto http://www.vmware.com/support/pubs/sdk_pubs.html.
Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisbook. Table 1. Revision History
Revision Date 08MAR11 30AUG10 Description GuestCustomizationSectionnotallowedinInstantiationParams Version1.0
Intended Audience
ThisguideisintendedforsoftwaredeveloperswhoarebuildingVMwareReadyCloudServices,including interactiveclientsofVMwareCloudDirector.ThisguideassumesyouarefamiliarwithRepresentationalState Transfer(REST)andRESTfulprogrammingconventions,theOpenVirtualizationFormatSpecification,and VMwareVirtualmachinetechnology.FamiliaritywithotherwidelydeployedtechnologiessuchasXML, HTTP,andtheWindowsorLinuxoperatingsystemsisalsoassumed.
VMware Technical Publications Glossary

VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions oftermsastheyareusedinVMwaretechnicaldocumentationgotohttp://www.vmware.com/support/pubs.
Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto docfeedback@vmware.com.
VMware, Inc.
11
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.
12
VMware, Inc.
Introducing the VMware vCloud API
TheVMwarevCloudAPIprovidessupportfordeveloperswhoarebuildinginteractiveclientsofVMware CloudDirectorusingaRESTfulapplicationdevelopmentstyle.vCloudAPIclientsandserverscommunicate overHTTP,exchangingrepresentationsofvCloudobjects.TheserepresentationstaketheformofXML elements.HTTPGETrequestsareusedtoretrievethecurrentrepresentationofanobject,HTTPPOSTand PUTrequestsareusedtocreateormodifyanobject,andHTTPDELETErequestsaretypicallyusedtodelete anobject. ThischapterintroducesthevCloudAPIandincludesthefollowingtopics:

vCloudObjectTaxonomyonpage 13 Objects,References,andRepresentationsonpage 15 LinksandLinkRelationsonpage 15 vCloudClientWorkflowOverviewonpage 17 AbouttheExamplesonpage 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 androlestousersandgroups.
vCloud Networks
Anorganizationcanbeprovisionedwithoneormorenetworks.Theseorganizationnetworkscanbe configuredtoprovideservicessuchasDHCP,NAT,andfirewalls.
VMware, Inc.
13
Figure 1-1. vCloud Object Taxonomy
Organization vDC1
vApp vApp template
Catalog 3
Catalogitem em Catalog 2 em em Catalogitem em Catalog 1 em em Catalogitem Catalogitem Catalogitem Catalogitem
Media Media
vDC2
vApp vApp template
Media Media
Network Network
users
groups
TasksList
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 controlsaccesstocatalogsbyorganizationmembers.
vCloud Tasks
Longrunningoperationsinitiatedbymembersofanorganizationcreatetasks,whicharekeptonthe organizationstaskslist.
14
VMware, Inc.
Chapter 1 Introducing the VMware vCloud API
Virtual Systems and Media Images in a vCloud

VirtualsystemsandmediaimagesarestoredinavDCandcanbeincludedinacatalog.Mediaimagesare storedintheirnativerepresentation(ISOorfloppy).Virtualsystemsarestoredastemplates,usinganopen standardformat(OVF1.0).Thesetemplatescanberetrievedfromcatalogsandtransformedintovirtual systems,calledvApps,throughaprocesscalledinstantiation,whichbindsatemplatesabstractresource requirementstoresourcesavailableinavDC.AvAppcontainsoneormoreindividualvirtualmachines(Vm elements),alongwithparametersthatdefineoperationaldetailssuchas:

Howthecontainedvirtualmachinesareconnectedtoeachotherandtoexternalnetworks. Theorderinwhichindividualvirtualmachinesarepoweredonoroff. Enduserlicenseagreementtermsforeachvirtualmachine. Deploymentleaseterms(typicallyinheritedfromthecontainingorganization)thatconstrainthevApps consumptionofvDCresources Accesscontrolinformationspecifyingwhichusersandgroupscanperformoperationssuchasdeploy, poweron,modify,andsuspendonthevAppandthevirtualmachinesitcontains.
Objects, References, and Representations

ThevCloudAPIrepresentsobjectsinthevCloudasXMLdocumentsinwhichobjectpropertiesareencoded aselementsandattributeswithtypedvaluesandanexplicitobjecthierarchydefinedbyanXMLschema. EveryobjectinavCloudisuniquelyidentifiedbyaURL.ThisURLisconstructedbytheserverandreturned inthevalueofthehrefattributeoftheXMLelementthatrepresentstheobject.Italsoappearsinvarious elementsofLinkTypeandReferenceType.ThisURLservesasauniqueidentifierthatpersistsforthelifeof theobjectandisneverreused.AlthoughURLshaveawellknownsyntaxandawellunderstood interpretation,aclientshouldtreateachhrefasanopaquestring.Therulesthatgovernconstructionofhref stringsbytheservermightchangeinfuturereleases. Objecttypes,specifiedasMIMEcontenttypes,areincludedintheXMLrepresentationsoffirstclassobjects suchastheonesshowninFigure 11.Formoreinformation,seeContentTypeonpage 142.
Links and Link Relations

ThevCloudAPImakesextensiveuseoflinks(URLs)toprovidereferencestoobjectsandtheactionsthatthey support.Theselinksaretheprimarymechanismbywhichaservertellsaclienthowtoaccessandoperateon anobject.Linksarecreatedbytheserver,andarereadonlyattheclient.(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 add alternate catalogItem controlAccess copy deploy Relation Description addsanitemtothiscontainer alinktoanalternaterepresentationofthisobject alinktothecatalogItemthatcontainsareferencetothisobject. applyaccesscontrols notsupportedinthisrelease deploythisobject HTTP Request POST GET GET POST N/A POST
VMware, Inc.
15
Table 1-1. Link Relationships and HTTP Request Types (Continued)

rel Attribute Value disable discardState down download:alternate download:default edit enable extension media:ejectMedia media:insertMedia move ova ovf power:powerOff power:powerOn power:reboot power:reset power:shutdown power:suspend publish recompose reconnect register remove repair screen:acquireTicket screen:thumbnail task:cancel undeploy unregister up upgrade upload:alternate upload:default Relation Description disablethisobject discardthesuspendedstateofthisvirtualmachine thereferencedobjectiscontainedbythisobject notsupportedinthisrelease defaultdownloadlocationforthisfile modifiesthisobject enablethisobject notsupportedinthisrelease ejectvirtualmediafromavirtualdevice insertvirtualmediainavirtualdevice notsupportedinthisrelease notsupportedinthisrelease theOVFrepresentationofthisvAppTemplate poweroffthereferencedobject poweronthisobject rebootthisobject resetthisobject shutdownthisobject suspendthisobject publishthiscatalog recomposethisvApp reconnectthisvCenterServer registerthisvCenterServer removethisobject repairthishost acquireascreenticketforthisvirtualmachine thumbnailviewofavirtualmachinescreen,inpngformat notsupportedinthisrelease undeploythisobject unregisterthisvCenterServer thereferencedobjectcontainsthisobject upgradethishost notsupportedinthisrelease defaultuploadlocationforthisfile HTTP Request POST POST GET N/A GET PUT POST N/A POST POST N/A N/A GET POST POST POST POST POST POST POST POST POST POST DELETE POST GET GET N/A POST POST GET POST N/A PUT
Thetypeattributevaluedefinesthemediatype(HTTPContentType)oftherequestorresponse document.Thisattributeispresentonlyforlinkstoobjects.Itisnotpresentforlinkstoactions. ThehrefattributevalueisaURL,whichshouldbeconsideredanopaqueidentifier(onethattheclient shouldnotattempttoparseorinterpret).Anhrefuniquelyidentifies,andpersistsforthelifeof,the referencedobject.Theseidentifiersareneverreused. ThenameattributevalueoftheLinkisthesameasthenameofthereferencedobject.Actionlinksdonot includeanameattribute.

VMware, Inc.
16
Linksprovideawayfortheservertoinformaclientaboutobjectrelationshipsandtheoperationsthatobjects support.Forexample,acontainersuchasanorganizationorcatalogcanreturnlinkstotheobjectsitcontains, andavirtualsystem(avApporVm)cancontainactionlinksthatenableoperationssuchaspowerstatechanges orvirtualdevicereconfiguration.Linkstoactionsandcontainedobjectsareomittedfromresponsesifthe requestwasmadebyauserwhohasinsufficientprivilegestoaccesstheobjectorperformtheaction.Action linksarealsoomittedwhentheactioncannotbeperformed(poweringonavirtualmachinethatisalready poweredon,forexample). NOTEWhenaclientusesalinktoreferenceanobject,onlythehrefattributeisrequired.Thenameandtype areignored.
vCloud Client Workflow Overview

ClientsofthevCloudAPIimplementaRESTfulworkflow,makingHTTPrequeststotheserverandretrieving theinformationtheyneedfromtheserversresponses.
Requests
ClientsmakeHTTPrequeststovCloudURLs,hrefattributevalueswhicharetypicallyprovidedbytheserver inresponsetoGETrequestsbytheclient.EveryvCloudhasawellknownURLfromwhichaclientcangetthe serversloginURLandthelistofvCloudAPIversionsthattheserversupports,alongwithadditional information(seeAPIVersioningonpage 147).Afteraclienthasloggedin,allvCloudAPIURLscanbe discoveredbymakingGETrequeststoURLslistedintheloginresponseandtheURLscontainedinresponses tothoserequests.
Request Headers
Allrequestsfromauthenticatedclientsmustincludeanauthenticationheader.SeeAuthenticationon page 18. RequeststhatincludeadocumentbodymuststartwiththeappropriateHTTPContentTypeheader.Thetype attributeofaresponsebodyindicatesthecontenttypeofthedocument.Forexample,thisresponsefragment indicatesthatthecontenttypeassociatedwithaCatalogItem 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
WhenitappearsasthevalueofaContentTypeheaderorthetypeattributeofanelementinthevCloudAPI, thisstringiscaseinsensitiveinrequests,andcanbereturnedineithermixedcaseorlowercasecharactersin responses. Formoreinformation,seeContentTypeonpage 142.
Request Bodies
ThisreleaseofCloudDirectorusesavalidatingXMLparserthatrequireselementsinarequestbodytoagree inbothorderandnumberwiththeschema.Requestbodiesarerejectedasinvalidunlesstheymeetthe followingcriteria:
XMLnamespaceattributesmustbesuppliedforallnamespacesrepresentedbyelementsintherequest. SeeXMLNamespaceIdentifiersonpage 145. Ifmultiplenamespacesarerepresentedintherequest,XMLnamespaceattributesmustincludean identifyingprefix,andthatprefixmustbeusedwithelementsfromthatnamespace.SeeXML NamespacePrefixesinRequestandResponseBodiesonpage 146.
VMware, Inc.
17
Allrequiredelementsmustappearinrequestbodies.Allelementsthatappearinrequestbodiesmust appearintheorderestablishedbytheschema,andwithcontentthatconformstothetypeconstraint specifiedintheschema.SeeSchemaValidationonpage 142.
Authentication
HTTPcommunicationsbetweenavCloudclientandserveraretypicallysecuredwithSSL.Inaddition,the vCloudAPIimplementsBasicHTTPAuthentication,asdefinedbyRFC2617,whichenablesaclienttoobtain atokenthatitcanusetoauthenticateindividualHTTPrequests. Toobtainanduseanauthenticationtoken,aclientmustfirstdiscovertheserversloginURL,andthenPOST aloginrequesttothatURL,supplyingthecredentialsofanauthorizeduser. To obtain and use an authentication token 1 2 MakeanAPIversionrequesttoavCloudservicetoobtaintheloginURLforthatservice.Formore information,seeAPIVersioningonpage 147. MakeanHTTPPOSTrequesttotheloginURL,asshowninExample 21onpage 21.

Iftheauthenticationheaderismissing,theserverreturnsHTTPresponsecode401. Ifthecredentialssuppliedintheauthenticationheaderareinvalid,theserverreturnsHTTPresponse code401. Iftherequestissuccessful,theserverreturnsHTTPresponsecode200(OK)andheadersthatinclude anauthorizationheaderoftheform:

x-vcloud-authorization: token
ThisheadermustbeincludedineachsubsequentvCloudAPIrequest. TheresponsebodyisanOrgListelement,whichisalistofallorganizationsthattheusercanaccess. Theauthenticationtokenexpiresafteraconfigurableintervalofclientinactivity.Thedefaultis30minutesafter thetokeniscreated.Afterthetokenexpires,allrequestsfailwithHTTPresponsecode401untiltheclientlogs inagaintoobtainanewtoken. NOTECertainadministrativeoperationshavespecialauthenticationrequirements.Formoreinformation,see AdministratorCredentialsandPrivilegesonpage 93.
Responses
AllresponsesincludeanHTTPstatuscodeand,unlessthestatuscodeis204(NoContent),aContentType header.Responsecontentdependsontherequest.Someresponsesincludeadocumentbody,someinclude onlyaURL,andsomeareempty.
Status Codes
Table 12liststhesubsetofHTTPstatuscodesthatavCloudAPIclientcanexpectinaresponse. Table 1-2. HTTP Status Codes Returned by the vCloud API
Status Code 200OK 201Created 202Accepted 204NoContent 303SeeOther 400BadRequest Status Description Therequestisvalidandwascompleted.Theresponseincludesadocumentbody. Therequestisvalid.TherequestedobjectwascreatedandcanbefoundattheURLspecifiedin theLocationheader. Therequestisvalidandataskwascreatedtohandleit.Thisresponseisusuallyaccompanied byataskURL. Therequestisvalidandwascompleted.Theresponsedoesnotincludeabody. TheresponsetotherequestcanbefoundattheURLspecifiedintheLocationheader. Therequestbodyismalformed,incomplete,orotherwiseinvalid.
18
VMware, Inc.
Table 1-2. HTTP Status Codes Returned by the vCloud API (Continued)
Status Code 401Unauthorized 403Forbidden 404NotFound 405MethodNot Allowed 500InternalServer Error 501NotImplemented 503Service Unavailable Status Description Anauthorizationheaderwasexpectedbutnotfound. Therequestinguserdoesnothaveadequateprivilegestoaccessoneormoreobjectsspecified intherequest. Oneormoreobjectsspecifiedintherequestcouldnotbefoundinthespecifiedcontainer. TheHTTPmethodspecifiedintherequestisnotsupportedforthisobject. Therequestwasreceivedbutcouldnotbecompletedduetoaninternalerrorattheserver. Therequestisnotimplementedbytheserver. Oneormoreservicesneededtocompletetherequestarenotavailableontheserver.
Configuring the vCloud API URL

ThebaseURLusedinhrefvaluesincludesthefullyqualifieddomainnameoftheserverhost.Incaseswhere thishostnamecannotberesolvedfromtheclient(forexample,iftheCloudDirectorinstallationincludes multipleserverhoststhatyouaccessthroughaloadbalancer)youcanspecifyaURLfortheservertousewhen constructinghrefstrings.Formoreinformation,seeConfiguretheExternalRESTAPIBaseURIintheCloud DirectorAdministratorsGuide.
Related Publications
TheVMwareCloudDirectorAdministratorsGuideandVMwareCloudDirectorUsersGuidecontaindetailed informationaboutmanyoftheobjectsandoperationsreferredtointhisguide.MostusersofthevCloudAPI willfindtheinformationinthosedocumentsvaluablewhendevelopingclientapplications.Toaccessthe currentversionsoftheseandotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.
About the Examples

ThisguideincludesmanyexamplesofHTTPrequestsandresponses.Theseexamplesareintendedtoshow theworkflowandcontentassociatedwithspecifictypesofoperationssuchasbrowsing,managinginventory, andoperatingvirtualsystems.ExamplerequestsgenerallyconformtotheruleslistedinRequestBodieson page 17.Mostexampleresponsesshowonlythoseelementsandattributesthatarerelevanttotheoperation beingdiscussed.Ellipses()indicateomittedcontentwithinresponsebodies. HTTPContentTypeheadersareshownwhereneededforallexamplesthatarenotfragmentsofsomelarger examplethatincludesthisheader.Althoughtheexamplesshowthesestringsusingthecharactercaseinwhich theyaredefinedbytheimplementation,thesestringsarecaseinsensitiveinrequests,andcanbereturnedin eithermixedcaseorlowercasecharactersinresponses.OtherHTTPheaders,suchasDate,ContentLength, andServer,areomittedbecausetheyarenotrelevanttothespecificsofanyexample.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).
VMware, Inc.
19
20
VMware, Inc.
Hello vCloud: A Structured REST Workflow Example
ThischapterpresentsasimpleexampleofastructuredRESTworkflowfordiscoveringanddeployinga particularvApp(inthiscase,anFTPserverwithaconnectiontothepublicInternet). Thischapterincludesthefollowingtopics:

LoggingInandGettinganOrganizationListonpage 21 BrowsinganOrganizationonpage 22 FindingavAppTemplateonpage 23 GettingInformationAboutavDConpage 24 InstantiatingtheTemplateinthevDConpage 24 DeployingandPoweringOnthevApponpage 26 GettingInformationAboutthevApponpage 27 DeletingthevApponpage 30 LoggingOutonpage 30
Logging In and Getting an Organization List

EveryvCloudhasaloginURLthataclientcanobtainbymakinganunauthenticatedGETrequesttothe vCloudsversionsURL,asshowninExample 82onpage 147.BecauseallothervCloudAPIrequestsmust beauthenticated,anyvCloudAPIworkflowhastobeginwithaloginrequestthatsuppliesusercredentialsin theformrequiredbyBasicHTTPauthentication(MIMEBase64encodingofastringhavingtheform user@vcloudorganization:password).Example 21showsaloginrequestandresponseforavCloudwhoselogin URLishttp://vcloud.example.com/api/v1.0/login. Example 2-1. Login Request and Response Request:
POST http://vcloud.example.com/api/v1.0/login Authorization: Basic encoded-credentials
Response:
200 OK Date: request-date x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.orgList+xml ... <?xml version="1.0" encoding="UTF-8"?> <OrgList ... href="http://vcloud.example.com/api/v1.0/org/" ... > <Org type="application/vnd.vmware.vcloud.org+xml" name="ExampleOrg" href="http://vcloud.example.com/api/v1.0/org/5"/>
VMware, Inc.
21
<Org .../> <Org .../> </OrgList>
Theresponseincludesanauthenticationtokensuppliedinthe x-vcloud-authorizationheader,andalist oftheorganizationstowhichtheauthenticateduserhasaccess.EachOrghasaURL(initshrefattribute value)thattheclientcanusetogetmoreinformationaboutobjectsthattheorganizationcontains.Formore informationaboutauthentication,seeAuthenticationonpage 18. NOTEThisexample,likeotherexamplesinthisguide,omitscertainrequiredHTTPheadersandothercontent sothatitcanprovideaconcise,readablesubsetofanactualrequestandresponse.Formoreinformation,see AbouttheExamplesonpage 19.
Browsing an Organization
YoucanuseanHTTPGETrequestandoneoftheOrgURLsreturnedbytheloginrequesttodiscoverthe contentsofanorganization,asshowninExample 22.(Foramorecompleteversionofthisexample,see Example 31onpage 34.) Example 2-2. List the Contents of an Organization Request:
GET http://vcloud.example.com/api/v1.0/org/5
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... <Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5" ... > <Link ... /> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/> <Link ... /> <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" name="ExampleVdc01"/> <Link ... /> <Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/14" name="IsolatedOrgNet"/> <Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54" name="Internet"/> <Description>Example Corps Primary Organization</Description> </Org>
Linksintheresponsewhoserelattributehasavalueofdownarereferencestoobjectsthattheorganization contains.Example 22showsthesubsetofthoseitemsthatyouwillneedforthisexercise:
AcatalognamedMainCatalog,atURLhttp://vcloud.example.com/api/v1.0/catalog/32,whereyoucan lookforvApptemplates. AvDCnamedExampleVdc01,atURLhttp://vcloud.example.com/api/v1.0/vdc/5,whereyoucandeploy thevApp. Twonetworks:onenamedInternet,atURLhttp://vcloud.example.com/api/v1.0/network/54,andone namedIsolatedOrgNet,atURLhttp://vcloud.example.com/api/v1.0/network/14.Youcanconnect connectthevApptoeitherofthesenetworks.
22
VMware, Inc.
Chapter 2 Hello vCloud: A Structured REST Workflow Example
Finding a vApp Template

TheclientcanusethecatalogURLshowninExample 22asthetargetofaGETrequestthatreturnsthe contentsofthecatalog,asshowninExample 23. Example 2-3. Finding a vApp Template in a Catalog Request:
GET http://vcloud.example.com/api/v1.0/catalog/32
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.catalog+xml ... <Catalog name="MainCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" ...> ... <Description>Main Org Catalog</Description> <CatalogItems> ... <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> ... </CatalogItems> ... </Catalog>
EveryvApptemplateormediaimagethathasbeenaddedtothecatalogisrepresentedasaCatalogItem element.Whenaclientbrowsesacatalog,itcanreadonlythename,type,andhrefofeachCatalogItem.To retrieveanitemfromthecatalog,moreinformationisrequired.InExample 24,theclientmakesaGETrequest toaCatalogItemURL(itshrefvalue).Theresponseprovidesmoreinformation,includingadescriptionof thereferencedobjectandanotherURLthattheclientcanusetoretrievearepresentationoftheobject. Example 2-4. Getting the vApp Template URL From a CatalogItem Request:
GET http://vcloud.example.com/api/v1.0/catalogItem/221
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...> ... <Description>Ubuntu Template with vsftpd</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> ... </CatalogItem>
ThisresponseshowsthatasuitablevApptemplatecanbefoundat http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate111.
VMware, Inc.
23
Getting Information About a vDC

Instantiation,deployment,andoperationofavAppalltakeplaceinthecontextofavDC.TheXML representationofavDCobjectdefinesthatcontextindetail.Forthisexercise,youneedonlytwopiecesof informationfromthevDC:

TheURLthataclientcanusetorequestaninstantiateVAppTemplateoperationinthevDC AlistofnetworkstowhichthevAppcanconnect.
Example 25showsthissubsetofvDCcontents.(Foramorecompletelookatthosecontents,seeExample 34 onpage 37.) Example 2-5. List the Contents of a vDC Request:
GET http://vcloud.example.com/api/v1.0/vdc/5
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vdc+xml ... <Vdc name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" ...> ... <Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate" /> ... <AvailableNetworks> <Network href="http://vcloud.example.com/api/v1.0/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet"/> <Network href="http://vcloud.example.com/api/v1.0/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet"/> </AvailableNetworks> ... </Vdc>
Theinformationyouneedisavailablehereintwoplaces:
AnLinkelementcontaininganactionURL, http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate.Therelattributeofthis Linkhasavalueofadd,indicatingthatitimplementsanactionthataddsanobjecttothevDC. AlistofAvailableNetworksthatincludesallthenetworksownedbytheorganizationthatcontainsthis vDC.SincewewantthisFTPservertobeaccessibleonthepublicInternet,wewillconnectthevAppto thenetworknamedInternet.
BoththesepiecesofinformationareputtouseinExample 26.
Instantiating the Template in the vDC

TocreateavAppfromthistemplate,youmustbinditsabstractresourcerequirements,suchasnetwork connections,storageresources,memory,andCPUcapacity,toappropriateresourcesinthetargetvDC.This bindingoperationiscalledinstantiation.Althoughaclientcanspecifythesebindingsindetail,asimple instantiation,whichreliesonorganizationandvDCdefaults,requiresonlyafewpiecesofinformation:

AnameforthevAppthattherequestcreates TheURLofthetemplatetoinstantiate.Inthiscase,theURL(retrievedinExample 24)is http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate111.
24
VMware, Inc.
CreationparametersforavAppnetwork.AvAppnetworkdefineshowthevAppconnectstoan organizationnetworkavailableinthetargetvDC.Formoreinformation,seeAboutvAppNetworkson page 62.
TheinstantiateVAppTemplaterequestinExample 26suppliestheseparametersinthefollowingplaces:
ThenameissuppliedinthenameattributeoftheInstantiateVAppTemplateParamsrequest.(This requestalsoprovidesadescription,whichisoptionalbutagoodpractice.) ThetemplateURLissuppledintheSourceelement ThevAppnetworkisspecifiedintheNetworkConfigSectionelement.Thisspecificationincludesthree parameters:
Anameforthenetwork,suppliedinthenameattributeoftheNetworkConfigSectionelement.If thevApptemplateincludesanovf:Networkelement,thenameyouspecifyforthevAppnetwork mustmatchthenamespecifiedinthatelementsovf:nameattribute. AreferencetotheorganizationnetworktowhichthevAppnetworkconnects,specifiedinthe ParentNetworkelement.TheURLusedhereisonereturnedinExample 25,inthe AvailableNetworkselementofthevDC. Afencemode,specifiedintheFenceModeelement.AvalueofbridgedindicatesthatthevApp networkisconnecteddirectlytotheorganizationnetwork.
ThetargetoftherequestistheinstantiateVAppTemplateURLofthisvDC(seeExample 25).Becausethe operationcreatesanewobject(avApp),theHTTPrequesttypeisPOST. Example 2-6. Instantiating a vApp Template Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml ... <InstantiateVAppTemplateParams name="Linux FTP server" xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" > <Description>Example FTP Server vApp</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> </InstantiationParams> <Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> </InstantiateVAppTemplateParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp deployed=false status="0" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Example FTP Server vApp</Description> <Tasks>
VMware, Inc.
25
<Task status="running" startTime="2010-06-25T08:00:55.402-07:00" operation="Creating Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey"> <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/> </Task> </Tasks> </VApp>
NOTEAvApptemplatemightincludealicenseagreementorothertermsthatyoumustacceptbeforeyou cancreateavAppfromit.Inthisexample,thetemplatecontainsnosuchterms.Ifitdid,therequestwould failifitdidnotincludeanAllEULAsAcceptedelement,asshowninExample 51onpage 63. TheresponsetotheinstantiationrequestisasparselypopulatedvAppbody,whichincludesthefollowing information:
ThestatusofthevApp.Thestatusvalue0indicatesthatthevAppisunresolved,becauseinstantiation hasnotcompleted. ThenameofthevApp,assuppliedintherequest ThevAppURL,showninthehrefattributeoftheVAppbody Ataskcreatedtotracktheinstantiation.TheTaskelementhasanoperationattributethatdescribeswhat ishappening,andcontainsanOwnerelementthatisareferencethevAppbeingcreated.Formore information,seeTaskonpage 168.
Deploying and Powering On the vApp

Aftertheinstantiationtaskcompletes,thetemplatehasbeentransformedintoavApp.ThevAppbodyno longerincludesaTaskselement,anditnowincludesanumberofLinkelementsthatyoucanusetodeploy andoperatethevApp.Example 27showsarequestandresponseforadeployaction.TherequestURListhe rel="deploy"linkreturnedinthevAppbody(seeExample 28).TherequestbodyisaDeployVAppParams element,whichspecifiesdeploymentdetails. Example 2-7. Deploy and Power On a vApp Request:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deploy Content-type: application/vnd.vmware.vcloud.deployVAppParams+xml ... <DeployVAppParams powerOn="true" deploymentLeaseSeconds="2592000" xmlns="http://www.vmware.com/vcloud/v1"/>
Response:
202 Accepted <Task xmlns="http://www.vmware.com/vcloud/v1" status="running" startTime="2010-06-25T11:15:55.558-07:00" operation="Starting Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/i9h1djqzsyllf0zvdy" ...> <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/> </Task>
Becausedeploymentisalongrunningoperationthatcanfailforavarietyofreasons(inabilityofthevDCto satisfythevAppsresourcerequirements,forexample),theresponseisaTask.
26
VMware, Inc.
BecausethedeploymentrequestspecifiedpowerOn="true",thevAppispoweredonandreadyforusewhen thetaskcompletes.Theclientcanwaitforasuitableintervalandcheckthetaskstatus(seeRetrieveaTask onpage 89),orsimplybeginrequestingoperationsonthepoweredonvAppandcheckingthetaskstatusif thoserequestsfail.SeeDeployingandControllingvAppsandVirtualMachinesonpage 80.
Getting Information About the vApp

Asotherexampleshaveshown,aclientcanalwaysuseanHTTPGETrequesttodiscoverthecurrentstateof anyvCloudobject,includingavApp.TheresponseinExample 28revealsseveralthings:

ThevAppisdeployed(itsdeployedattributeissettotrue)andpoweredon(status="4"). TheVminitsChildrencollectionisalsopoweredonanddeployed.TheVmisconnectedtothevApp networkcreatedduringinstantiation(seeExample 26).Propertiesofthisnetworkareincludedinthe NetworkConfigSectionofthevApp,thoughmostarenotshownhere. ActionlinksforalloperationsexceptpowerOnarepresentinboththevAppitselfanditschildVm.Because thevAppisalreadypoweredon,thatoperationisinvalidforthevAppinitscurrentstate,sothelinkis notpartoftheresponse.(Thelinkfordeployisalwayspresent,eveninadeployedvApp,becausethe deployactionisalwaysvalid.)TheVmelementalsoincludesseverallinksforactionsthatnotapplicable toavApp:actionslikeacquiringascreenticketorthumbnail,andinsertingorremovingmedia,are specifictoavirtualmachine.Otheractionslikeshutdownandreboot,canbeappliedtoeitherobject.See DeployingandControllingvAppsandVirtualMachinesonpage 80. Muchadditionalinformationisavailable,thoughmostofitisnotshownhere.Theexampledoesshow wheretofindtheIPaddressofthevApp,intheIpAddresselementoftheNetworkConnection.
Example 2-8. Get Information About the vApp Request:

GET http://vcloud.example.com/api/v1.0/vApp/vapp-7
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp status="4" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ... > <Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reboot"/> <Link rel="power:powerOff" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOff"/> <Link rel="undeploy" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/undeploy"/> <Link rel="deploy" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deploy"/> <Link rel="power:shutdown" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/shutdown"/> <Link rel="power:reset" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reset"/> <Link rel="power:suspend" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/suspend"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/controlAccess/"/> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Link rel="edit" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/> <Description>Example FTP Server vApp</Description> <LeaseSettingsSection ...> ... </LeaseSettingsSection> <ovf:StartupSection ... > ...
VMware, Inc.
27
</ovf:StartupSection> <ovf:NetworkSection ... > <ovf:Info/> <ovf:Network ovf:name="vAppNetwork"> <ovf:Description/> </ovf:Network> </ovf:NetworkSection> <NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/ networkConfigSection/"/> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> ... </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> <IsDeployed>true</IsDeployed> </NetworkConfig> </NetworkConfigSection> <Children> <Vm deployed="true" status="4" name="ubuntu10-x86" type="application/vnd.vmware.vcloud.vm+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4"> <Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/reboot"/> <Link rel="power:powerOff" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/powerOff"/> <Link rel="undeploy" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/action/undeploy"/> <Link rel="deploy" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/action/deploy"/> <Link rel="power:shutdown" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/shutdown"/> <Link rel="power:reset" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/reset"/> <Link rel="power:suspend" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/suspend"/> <Link rel="up" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/> <Link rel="screen:thumbnail" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/screen"/> <Link rel="screen:acquireTicket" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/ action/acquireTicket"/> <Link rel="media:insertMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/ action/insertMedia"/> <Link rel="media:ejectMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/ action/ejectMedia"/> <Description/> <ovf:VirtualHardwareSection ...> ... </ovf:VirtualHardwareSection> ... <NetworkConnectionSection> ... <NetworkConnection network="vAppNetwork"> ...
28
VMware, Inc.
<IpAddress>10.147.122.134</IpAddress> <IsConnected>true</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> ... </NetworkConnection> ... </NetworkConnectionSection> <GuestCustomizationSection ...> ... </GuestCustomizationSection> <VAppScopedLocalId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedLocalId> </Vm> </Children> </VApp>
Displaying the Console

AfterthevApphasbeenpoweredon,youcanretrieveascreenticketfromoneofitsvirtualmachinesanduse thattickettogainaccesstotheconsoleofthevirtualmachine.
Retrieve a Screen Ticket

AscreenticketisastringthatincludesthevirtualmachinesIPaddress,itsmanagedobjectreference,anda stringthathasbeenencodedasdescribedinRFC2396.EachVmelementinavAppincludesalinkwhere rel="screen:acquireTicket".Youcanusethatlinktorequestascreenticketthatyoucanusewiththe vmware-vmrcutilitytoopenaVMwareRemoteConsoleforthevirtualmachinerepresentedbythatVm element.Example 29makessucharequestusingtheacquireTicketlinkreturnedinExample 28. Example 2-9. Get a Screen Ticket for a Virtual Machine Request:
POST http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/action/acquireTicket
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.screenTicket+xml ... <ScreenTicket xmlns="http://www.vmware.com/vcloud/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...> mks://10.147.43.171/vm-61?ticket=Pznh4HMb7k%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3 SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O </ScreenTicket>
Theticketitselfhasthefollowingform:
mks://ip-address/VM-MoRef/ticket=encoded-ticket
where:

ipaddressistheIPaddressofthevirtualmachine VMMoRefisthemanagedobjectreferenceofthevirtualmachine encodedticketistheencodedscreenticket.Youmustdecodethisticketusingafunctionsuchas URLDecoder(Java)orurl_escape(PERL)beforeyoucanuseit.
Theticketisvalidfor30seconds.
VMware, Inc.
29
Use the Ticket with vmware-vmrc

Thevmware-vmrcpluginisinstalledbyyourbrowserwheneveryouusetheCloudDirectorWebConsoleto accesstheconsoleofarunningvirtualmachine.Afterthispluginhasbeeninstalled,youcanfinditinthe folderthatyourbrowserusesforplugins. NOTETheversionofvmware-vmrcincludedwithCloudDirectorcannotbeusedtoaccessvirtualmachines invCenter.Inaddition,itisincompatiblewiththeversionofvmware-vmrcinstalledbyVMwarevSphereWeb Access,whichisalsoinstalledasabrowserplugin,andcannotcoexistwiththeCloudDirectorversionof vmware-vmrc. Touseascreenticketwithvmware-vmrc,openacommandshellinthefolderwherevmware-vmrc.exeis installedandrunacommandthathastheform:
vmware-vmrc -h ip-address -p decoded-ticket -M VM-MoRef
FortheticketshowninExample 29,thecommandlinewouldlooksimilartothisone.
vmware-vmrc -h 10.147.43.171 -p 9XVUXZ... -M vm-61
ThecommandcontactsthespecifiedIPaddress,presentsthedecodedticketforvalidation,anddisplaysa VMwareRemoteConsolewindow.Iftheticketisvalid,youcanaccessthevirtualmachinesconsoleinthe window.Iftheticketisimproperlydecodedorhastimedout,anderrormessageisdisplayed.
Deleting the vApp

YoucanuseanHTTPDELETErequesttodeleteavApp,asshowninExample 210.(Youmustpoweroffand undeploythevAppbeforeyoudeleteit.)TheresponseisaTaskbody.Becausethetasktracksadeletion,it doesnotincludeanOwnerelement.(Theowneristheobjectbeingdeleted.) Example 2-10. Delete a vApp Request:
DELETE http://vcloud.example.com/api/v1.0/vApp/vapp-7
Response:
202 Accepted <Task xmlns="http://www.vmware.com/vcloud/v1" status="running" startTime="2010-06-25T08:10:23.650-07:00" operation="Deleting Virtual Application Linux FTP server (7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/jul1tndoojgaesymci" ... > <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="Linux FTP server" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/> </Task>
Logging Out
Tologoutandendasession,avCloudAPIclientmakesaPOSTrequesttothelogoutURL,asshownin Example 211. Example 2-11. Log Out Request:
POST http://vcloud.example.com/api/v1.0/logout x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Response:
200 OK
30
VMware, Inc.
Moving on to Additional Use Cases

ThisHelloexercise,whilesimplified,demonstratesapatterncommontomanyvCloudAPIusecases: browsingtodiscoveratemplate,instantiatingthetemplate,thendeployingandoperatingthevAppdescribed inthetemplate.Theremainderofthisguideprovidesexpandedexamplesoftheseandotherusecases, including:

CreatingvApptemplatesbyuploadingOVFpackagesorcapturingvApps(Provisioningonpage 41) Nondefaultinstantiationusingdetailedinstantiationparameters(InstantiateavAppTemplateon page 61) CreatingacopyofavAppbycloning,orcomposingavAppfrommultiplevAppsortemplates ReconfigurationofavApptoaddorremovevirtualhardware,modifynetworkconnections,andchange othervAppproperties(ReconfiguringvAppsandVirtualMachinesonpage 69) AdministrativeoperationstocreatevDCsandCatalogs,andtoadministerusers,groups,androles (AdministrativeOperationsonpage 91). OperationsthatasystemadministratorcanusetoaccessthevSphereplatformthatsupportsavCloud roles(VMwarevSpherePlatformOperationsonpage 117).
ThisguidealsoincludescompletereferenceinformationonXMLelementsdefinedbythevCloudAPI(see Chapter 9,UserAPIReference,onpage 151andChapter 11,AdministrativeAPIReference,onpage 179), andthosedefinedbythevSphereplatformextensions(seeChapter 12,vSpherePlatformExtensions Reference,onpage 193).ItalsoincludesanintroductiontoOVFAppendix A,OVFandthevCloudAPI,on page 203,whichconcentratesonthoseaspectsofOVFthatmightbeofinteresttoadvancedvCloudAPI programmers.
VMware, Inc.
31
32
VMware, Inc.
Browsing
AvCloudAPIclientcanuseHTTPGETrequeststobrowsecontainerssuchasorganizations,catalogs,and vDCs.Responsestotheserequestsincludemetadataaboutthecontaineritselfandreferencestotheobjectsit contains.ThesereferencesareprovidedinLinkelements,whichhavehrefattributeswhosevaluestheclient canuseinrequeststogetmoreinformationabouttheobjectsthemselves.Thishierarchicalstructureof containerslendsitselftographicalrepresentationasafolderhierarchyortreeviewofvCloudobjects,and enablesclientstousethesamesetofobjectsandoperationstoimplementabreadthfirstordepthfirst approachtobrowsing. Thischapterincludesthefollowingtopics:

SummaryofBrowsingRequestsonpage 33 DiscoveringtheContentsofanOrganization,Catalog,orvDConpage 34 GettingMoreInformationAboutanObjectonpage 38
Summary of Browsing Requests

Table 31summarizesbrowsingrequestssupportedinthisrelease.Thetableusesthefollowingconventions:

APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0 idisaninteger
Table 3-1. Summary of Browsing Requests

Operation ShowLoginURLandListSupported APIVersions Login Logout ListtheOrganizationsinavCloud ListtheContentsofanOrganization GetInformationAboutaNetwork ListtheContentsofaCatalog GetInformationAboutaCatalogItem ListtheContentsofavDC GetInformationAboutaMediaImage GetInformationAbouta vAppTemplate GetInformationAboutavAppor VirtualMachine Request GEThttp://hostname/api/versions POSTAPIURL/login POSTAPIURL/logout GETAPIURL/org GETAPIURL/org/id GETAPIURL/network/id GETAPIURL/catalog/id GETAPIURL/catalogItem/id GETAPIURL/vdc/id GETAPIURL/media/id GETAPIURL/vAppTemplate/vappTemplateid GETAPIURL/vApp/vappid Request Body None None None None None None None None None None None None Response SupportedVersions OrgList 200OK OrgList Org OrgNetwork Catalog CatalogItem Vdc Media VAppTemplate VApp
VMware, Inc.
33
Discovering the Contents of an Organization, Catalog, or vDC

ThevCloudAPIdefinesthreeprincipalcontainers:organizations,catalogs,andvDCs.Aclientcanusean HTTPGETrequesttodiscoverthecontentsofanyofthem.
List the Organizations in a vCloud

Theresponsetoaloginrequestincludesalistoftheorganizationstowhichtheauthenticateduserhasaccess. Ifanauthenticatedclientneedstoretrievethislist,itcanmakeaGETrequesttotheURLshowninthehref attributeoftheOrgListthatwasreturnedintheresponsetoitsoriginalloginrequest.ToretrievetheOrgList returnedinExample 21onpage 21,anauthenticatedclientwouldissuethefollowingrequest:
GET http://vcloud.example.com/api/v1.0/org/
Formoreinformation,seeLoggingInandGettinganOrganizationListonpage 21.
List the Contents of an Organization

AvCloudorganizationisahighlevelabstractionthatprovidesaunitofadministrationforobjectsand resources.Asviewedbyauser,anorganization(representedbyanOrgelement)cancontainCatalog, Network,andvDCelements.Ifthereareanyqueued,running,orrecentlycompletedtasksownedbyamember oftheorganization,italsocontainsaTasksListelement.Asviewedbyanadministrator,anorganizationalso containsusers,groups,andotherinformation.Formoreinformation,seeOrgonpage 151andAdminOrg onpage 180. AclientcanobtainalistoforganizationsinavCloudbyloggingintotheservertogetanOrgList(see Authenticationonpage 18).Thislistsincludesonlythoseorganizationstowhichtheloggedinuserhas access.TheclientcanuseaURLfromthislisttomakeanHTTPGETrequestthatreturnsanOrgdocumentin theresponsebody.Thisdocument,arepresentationoftheorganizationobject,includeslinkstoobjectsthatthe organizationcontainsandmetadataabouttheorganizationitself.Example 31showssucharequestand response. Example 3-1. List the Contents of an Organization Request:
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... <Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5" ...> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess/"/> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/37" name="Shared Catalog"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/37/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/37/action/controlAccess/"/> <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" name="ExampleVdc01"/> <Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/5"/>
34
VMware, Inc.
Chapter 3 Browsing
<Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/14" name="IsolatedOrgNet"/> <Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54" name="Internet"/> <Description>Example Corps Primary Organization</Description> </Org>
Thisresponseshowsthattheorganizationcontainstheseobjects,eachofwhichisreferencedbyaLinkwhose relattributehasavalueofdown(indicatingthatthelinkreferencesanobjectcontainedbytheorganization):

AcatalognamedMainCatalog,whoseURLishttp://vcloud.example.com/api/v1.0/catalog/32 AcatalognamedSharedCatalog,whoseURLishttp://vcloud.example.com/api/v1.0/catalog/37 AlinktotheorganizationsTasksList AvDCnamedExampleVdc01whoseURLishttp://vcloud.example.com/api/v1.0/vdc/5 Twonetworks:onenamedIsolatedOrgNetwhoseURLis http://vcloud.example.com/api/v1.0/network/14,andonenamedInternetwhoseURLis http://vcloud.example.com/api/v1.0/network/54 Actionlinksthatenableanadministratortocontrolaccesstothecatalogs
List the Contents of a Catalog

Aclientcanusethehrefvaluefromanyoftherel="down"linksinanOrgbodytogetmoreinformation abouttheobjecttowhichthelinkrefers,asshowninExample 32,whichrequestsmoreinformationaboutone ofthecatalogsintheorganization. Example 3-2. List the Contents of a Catalog Request:
GET http://vcloud.example.com/api/v1.0/catalog/32
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.catalog+xml ... <Catalog name="MainCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" ...> <Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/> <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/> <Description>Main Org Catalog</Description> <CatalogItems> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Boot Floppy" href="http://vcloud.example.com/api/v1.0/catalogItem/222"/> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu ISO Image" href="http://vcloud.example.com/api/v1.0/catalogItem/223"/> ... </CatalogItems> <IsPublished>true</IsPublished> </Catalog>
VMware, Inc.
35
Thisresponsebodyincludes:
ALinkelementthatreferencestheorganizationthatcontainsthiscatalog:
<Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/>
ALinkelementthatyoucanusetoaddanitemtothecatalog:
<Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/>
SeveralCatalogItemelements.EachoftheseelementsincludesanhrefattributewhosevalueisaURL thatyoucanGETtoobtainmoreinformationabouttheitem,asshowninExample 33. AnIsPublishedelementwhosevalueindicateswhetherthiscatalogisvisibletootherorganizations.
Formoreinformationaboutcreatingcatalogsandmanagingtheircontents,seeCatalogingvAppTemplates andMediaImagesonpage 54andCatalogAdministrationonpage 107.Formoreinformationaboutthe Catalogelementschema,seeCatalogonpage 160.
Get Information About a CatalogItem

ACatalogItemelementcanreferenceavApptemplateoramediaobject.Requeststogetmoreinformation aboutaCatalogItemreturnaCatalogItemdocumentthatincludes:

TheURLofthereferencedobject LinkelementsthatenableanauthorizedusertomodifyorremovetheCatalogItem AnEntityelementthatincludesthehref,type,andnameoftheobjectthattheCatalogItemreferences. AnEntitycanappearinatmostoneCatalog. OptionalPropertyelements,eachofwhichisakey=valuepair.AnorganizationcanuseProperty elementstoimplementakeybasedlookupschemeforcatalogitems.
Example 3-3. Get Information About a CatalogItem Request:

GET http://vcloud.example.com/api/v1.0/catalogItem/221
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Description>Ubuntu Template with vsftpd</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> <Property key="Company">Example</Property> </CatalogItem>
36
VMware, Inc.
Chapter 3 Browsing
List the Contents of a vDC

TheresponseinExample 31alsocontainsseveralVdcelements,eachofwhichrepresentsavDCobject. Example 34showsarequesttobrowseoneofthosevDCsandshowsasubsetoftheresponse. Example 3-4. List the Contents of a vDC Request:
GET http://vcloud.example.com/api/v1.0/vdc/5
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vdc+xml ... <Vdc name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" ...> <Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/> <Link rel="add" type="application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate"/> <Link rel="add" type="application/vnd.vmware.vcloud.media+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/media"/> <Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate" /> <Link rel="add" type="application/vnd.vmware.vcloud.cloneVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVApp"/> <Link rel="add" type="application/vnd.vmware.vcloud.captureVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/captureVApp"/> <Link rel="add" type="application/vnd.vmware.vcloud.composeVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/composeVApp"/> <AllocationModel>AllocationPool</AllocationModel> <Description>Example Corp. Primary vDC</Description> <StorageCapacity> <Units>MB</Units> <Allocated>1000</Allocated> <Limit>1000</Limit> <Used>512</Used> <Overhead>0</Overhead> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>100</Allocated> <Limit>100</Limit> <Used>32</Used> <Overhead>0</Overhead> </Cpu> <Memory> <Units>MB</Units> <Allocated>100</Allocated> <Limit>100</Limit> <Used>64</Used> <Overhead>0</Overhead> </Memory> </ComputeCapacity> <ResourceEntities> <ResourceEntity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> <ResourceEntity href="http://vcloud.example.com/api/v1.0/media/112" type="application/vnd.vmware.vcloud.media+xml" name="Ubuntu Boot Floppy"/> <ResourceEntity href="http://vcloud.example.com/api/v1.0/media/113" type="application/vnd.vmware.vcloud.media+xml" name="Ubuntu ISO Image"/>
VMware, Inc.
37
<ResourceEntity href="http://vcloud.example.com/vApp/vapp-413" type="application/vnd.vmware.vcloud.vApp+xml" name="Example Corp. CRM"/> ... </ResourceEntities> <AvailableNetworks> <Network href="http://vcloud.example.com/api/v1.0/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet"/> <Network href="http://vcloud.example.com/api/v1.0/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet"/> </AvailableNetworks> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <VmQuota>0</VmQuota> <IsEnabled>true</IsEnabled> </Vdc>
TheresponseisadetaileddescriptionofthevDCanditscontents.Itincludes:
Linkelementswhoserelattributehasavalueofadd.Eachoftheselinkshasanhrefattributewhose valueisaURLthataclientcanusetoaddvApps,vApptemplates,andmediaimagestovDCinventory. Severalmethodsofaddinginventoryaresupported,includingupload,clone,andcompose. ResourceEntityelementsthatreferencevAppsthathavebeeninstatiatedinorimportedtothisvDC, andvApptemplatesandvirtualmediaimagesthathavebeenuploadedtothevDC. AlistoforganizationnetworksthatareavailableinthevDC. Othermetadata,includingquotaandvDCstateinformation.
Formoreinformation,seeVdconpage 152.
Getting More Information About an Object

AnobjectinavCloudcanberepresentedbylinksinvarioustypesofXMLcontainers.Regardlessofwherethe linkappears,theobjectreferenceitcontains(itshrefattributevalue)isalwaysthesame.Anorganization networkcanberepresentedbyalinkwithrel="down"inanorganization,orasamemberofthe AvailableNetworkselementofavDC. CatalogsprovidealevelofindirectionforreferencestomediaimagesandvApptemplates.AvApptemplate ormediaimagecanbereferencedbyaCatalogIteminacatalogoraResourceEntityinavDC.The CatalogItemshowninExample 32,aVAppTemplatewhoseURLis http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate111,isalsocontainedbythevDC referencedinExample 34.IntheVdcbody,theVAppTemplateisrepresentedasResourceEntityelement, whichincludesalink(thevalueofthehrefattribute)tothetemplate.TheCatalog,ontheotherhand, containsonlyCatalogItemelements,eachofwhichincludesalinkthataclientcanusetogetmore informationabouttheobjectthattheCatalogItemrepresents.BoththeResourceEntityintheVdcandthe CatalogItemintheCatalogrefertothesamevApptemplate.TheResourceEntityelementincludesalink thataclientcanusetoGETarepresentationofthevApp,butaclientmustfirstGETaCatalogItemtoobtain thatkindoflink,whichisnotcontainedintheCatalogitself. AResourceEntityelementappearsinaVdcelementassoonastheunderlyingvApptemplateormedia imagehasbeencreated.Referencestothoseobjectsdonotappearinacataloguntilthecatalogowneradds themtoit.Inmostcases,theobjectscannotbeuseduntiltheyhavebeenaddedtoacatalog.
Get Information About a Media Image

AclientcandiscovertheURLofamediaimagebybrowsinginacatalogandexaminingaCatalogItemto findtheEntityelementthatreferencestheimage,orbybrowsinginavDCforaResourceEntityelement thatreferencestheimage.AfterclienthastheimagesURL,itcanuseitasthetargetofaGETrequest,asshown inExample 35. Ifthemediaimagehasbeenincludedinacatalog,theMediaelementintheresponseincludesalinktothe CatalogItemthatreferencesit.
38 VMware, Inc.
Chapter 3 Browsing
Example 3-5. Get Information About a Media Image Request:

GET http://vcloud.example.com/api/v1.0/media/254
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.media+xml ... <Media xmlns="http://www.vmware.com/vcloud/v1" size="242131" imageType="iso" status="1" name="sql2000.iso" type="application/vnd.vmware.vcloud.media+xml" href="http://vcloud.example.com/api/v1.0/media/254" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/21"/> <Link rel="catalogItem" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/211"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/media/123"/> <Link rel="edit" type="application/vnd.vmware.vcloud.media+xml" href="http://vcloud.example.com/api/v1.0/media/123"/> <Description>ISO Database Image</Description> </Media>
Get Information About a vAppTemplate

AclientcandiscovertheURLofavApptemplatebybrowsinginacatalogandexaminingaCatalogItemto findtheEntityelementthatreferencesthetemplate,orbybrowsinginavDCforaResourceEntityelement thatreferencesthetemplate.AfterclienthasthetemplatesURL,itcanuseitasthetargetofaGETrequest,as showninExample 36,whichusesthehrefoftheCatalogItemreturnedinExample 33. Example 3-6. Get Information About a vAppTemplate Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template with vsftpd" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" ... > <Description>Description of Ubuntu Template with vsftpd</Description> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/10"/> <Link rel="catalogItem" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Link rel="edit" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Link rel="ovf" type="text/xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111/ovf"/> <Children> ... </Children> </VAppTemplate>
VMware, Inc.
39
Get Information About a vApp or Virtual Machine

CatalogscannotcontainreferencestovAppsorthevirtualmachines(Vmobjects)thattheycontain.Aclientcan discovertheURLofavAppbybrowsinginavDCforaResourceEntityelementthatreferencesit.After clienthasthetemplatesURL,itcanuseitasthetargetofaGETrequest,asshowninExample 28onpage 39 toretrievethevApprepresentationandtheVmelementsitcontains.
Get Information About a Network

Network(OrgNetwork)elementscanbecontainedbyOrgandVdcelements.Ifanorganizationcontainsany networks,eachoneisreferencedbyaLinkelementwhererel="down"intheOrgbody.Eachorganization networkisamemberoftheAvailableNetworkselementineachoftheorganizationsvDCs. Togetinformationaboutanetwork,makeaGETrequesttoitsURL,asshowninExample 37. Example 3-7. Get Information About a Network Request:
GET http://vcloud.example.com/api/v1.0/network/54
Response:
200 OK Content-Type: application/vnd.vmware.admin.network+xml ... <OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet" type="application/vnd.vmware.admin.network+xml" ref="http://vcloud.example.com/api/v1.0/admin/network/54" ...> <Link rel="alternate" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54"/> <Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0//org/26"/> <Description>Bridged to the Public Internet</Description> <Configuration> <IpScope> <IsInherited>true</IsInherited> <Gateway>10.147.56.253</Gateway> <Netmask>255.255.255.0</Netmask> <Dns1>10.147.115.1</Dns1> <Dns2>10.147.115.2</Dns2> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.56.1</StartAddress> <EndAddress>10.147.56.255</EndAddress> </IpRange> </IpRanges> </IpScope> <ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <FenceMode>bridged</FenceMode> </Configuration> </OrgNetwork>
40
VMware, Inc.
Provisioning
ThevCloudAPIsupportsuploadanddownloadofOVFpackages,anduploadofmediaimages.Transfer operationsarecharacterizedasuploadswhentheoperationtransferscontentfromthelocalhosttoaremote one,andasdownloadswhenthelocalhostrequeststhetransferofcontentfromaremotehost.Uploadsare typicallyinitiatedbyaPOSTrequest,anddownloadsbyaGETrequest.Uploadsanddownloadsare facilitatedbythevCloudtransferservice,whichprovidestemporarystorageforfiles. ThevCloudAPIalsosupportsacloneoperationthatcopiesvApps,vApptemplates,ormediaimages.The cloneoperationalsoallowsyoutospecifythatthesourceobjectbedeletedaftertheoperationcompletes, whicheffectivelymovesorrenamesthesourceobject. Aftertheyhavebeenuploadedorcloned,templatesandmediaimagescanbeaddedtocatalogsasneeded. Thischapterincludesthefollowingtopics:

SummaryofProvisioningRequestsonpage 41 UploadOVFtoCreateavAppTemplateonpage 42 ViewtheOVFDescriptorofavAppTemplateonpage 47 DownloadavAppTemplateasOVFonpage 47 UploadaMediaImageonpage 50 CopyingandMovingonpage 50 ChangingaNameorDescriptiononpage 53 DeleteavAppTemplate,vApp,orMediaImageonpage 54 CatalogingvAppTemplatesandMediaImagesonpage 54 ControllingAccessonpage 56
Summary of Provisioning Requests

Table 41summarizesprovisioningrequestssupportedinthisrelease.Thetableusesthefollowing conventions:

APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0. idisaninteger.
Table 4-1. Summary of Provisioning Requests

Operation UploadOVFtoCreatea vAppTemplate DownloadavApp TemplateasOVF Request POSTAPIURL/vdc/id/ action/uploadVAppTemplate GETdownloadURL Request Body UploadVAppTemplateParams None Response VAppTemplate Dependson filetype
VMware, Inc.
41
Table 4-1. Summary of Provisioning Requests (Continued)

Operation EnableavAppTemplatefor Download DisableavAppTemplate forDownload UploadaMediaImage CopyorMoveaMedia Image CopyorMoveavApp Template CopyorMoveavApp ChangetheNameor Descriptionofa vAppTemplate ChangetheNameor DescriptionofavApp ChangetheNameor DescriptionofaMedia Image DeleteavAppTemplate, vApp,orMediaImage AddanItemtoaCatalog RemoveanItemfroma Catalog ControlAccesstoCatalogs Request POSTAPIURL/vAppTemplate/ vAppTemplateid/action/enableDownload POSTAPIURL/vAppTemplate/ vAppTemplateid/action/disableDownload POSTAPIURL/vdc/id/media POSTAPIURL/vdc/id/action/cloneMedia POSTAPIURL/vdc/id/action/ cloneVAppTemplate POSTAPIURL/vdc/id/action/cloneVApp PUTAPIURL/vAppTemplate/vappTemplateid Request Body None None Media CloneMediaParams CloneVAppTemplateParams CloneVAppParams VAppTemplate Response Task 204No Content Media Media VAppTemplate VApp Task
PUTAPIURL/vApp/vappid PUTAPIURL/media/id
VApp Media
Task Task
DELETEobjectURL POSTAPIURL/catalog/id/catalogItems DELETEAPIURL/ catalog/id/catalogItem/id POST APIURL/catalog/id/action/ controlAccess
None CatalogItem None ControlAccessParams
Task CatalogItem 204Nocontent ControlAccess Params
Upload OVF to Create a vApp Template

AvCloudAPIclientthathasaccesstoanOVFpackagecanuseasimpleworkflowtouploadthepackageand createavApptemplate. 1 2 3 4 TheclientPOSTsaninitialrequestthatspecifiesanameforthetemplate,atransferformatforthedata, andanoptionaldescription. Theserverreturnsanunresolved(status="0")vAppTemplatedocumentthatincludesanuploadURL fortheOVFpackage. TheclientusesanHTTPPUTrequesttouploadtheOVFpackagedescriptor(the .ovffile)totheupload URL. TheserverreadsthedescriptorandconstructsacompletevAppTemplatedocument(onethatincludesan uploadURLforeachfilelistedintheReferencessectionofthedescriptor).Whiletheserverisconstructing thisdocument,theclientmakesperiodicrequestsforitandexaminestheresponseforadditionalupload URLs.WhentheresponsecontainsanyuploadURLsbeyondtheonereturnedinStep2,templateis complete TheclientusesHTTPPUTrequeststouploadeachofthefiles. IftheOVFpackageincludesamanifestfile,theentireuploadisvalidatedagainstthecontentsofthe manifestfile.
5 6
42
VMware, Inc.
Chapter 4 Provisioning
Bothmonolithicandranged(chunked)PUTsaresupported.Afterstartinganupload,aclientcanmake periodicrequeststodetermineitsprogress.Afterallthefilesareuploaded(andvalidatedifamanifestis present),theserverprocessestheuploads.Whenprocessingiscomplete,theserversetsthevalueofthe templatesstatusattributeto8,indicatingthatthetemplateisreadyforuse.(Thisstatusvalueindicatesthat allofthevirtualmachinesinthetemplatearepoweredoff.Formoreinformation,includingacompletelistof possiblestatusvaluesandtheirmeanings,seestatusonpage 144.)
Restrictions on Uploaded Content

ThisreleaseofthevCloudAPIimposesthefollowingrestrictionsonuploadedOVFcontent:
YoucanuploadeitherOVF1.0orOVF1.1content.OVF1.1packagesareconvertedtoOVF1.0for download,andanyOVF1.1contentislost. YoucannotuploadacompressedOVFpackage. IfyouuploadanOVFpackageinwhichanyVirtualSystemelementhasanovf:idattributevaluethat islongerthan13characters,thenameoftheVmthatrepresentstheVirtualSysteminthevAppTemplate createdbytheuploadisrewrittenasthefirst13charactersoftheovf:id attributefollowedbythree digits.Forexample,NewVirtualMachine1andNewVirtualMachine2becomeNewVirtualMa001and NewVirtualMa002.
Initiate the Upload

Toinitiatetheupload,aclientmakesanHTTPPOSTrequestspecifyingatargetvDCandan uploadVAppTemplateaction.Therequestbody,showninExample 41,isanUploadVAppTemplateParams element. Example 4-1. uploadVappTemplate Request
POST http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml <UploadVAppTemplateParams name="Ubuntu Template" xmlns="http://www.vmware.com/vcloud/v1" > <Description>Ubuntu vApp Template</Description> </UploadVAppTemplateParams>
ThisrequestcreatesanewVAppTemplateobjectinthetargetvDCandreturnstheobjectsXMLrepresentation inaresponse,asshowninExample 42. Example 4-2. Unresolved vAppTemplate Body with Upload URL for OVF Descriptor
201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml <VAppTemplate name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" status="0" ovfDescriptorUploaded="false" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> ... <Description>Ubuntu vApp Template</Description> <Files> <File name="descriptor.ovf" bytesTransferred="0"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../descriptor.ovf"/> </File> </Files> </VAppTemplate>
VMware, Inc.
43
Theresponsebodyincludesthefollowingattributes:

AnhrefattributewhosevalueisalinktothenewlycreatedvApptemplateobject. AnovfDescriptorUploadedattributewithavalueoffalse,indicatingthattheOVFdescriptorfilehas notyetbeenuploaded Astatusattributewithavalueof0,indicatingthatthefilereferencesinthedescriptorhavenotyetbeen uploaded.(AVAppTemplatewithastatusof0issaidtobeunresolved.)
ItalsoincludesaFileelementwithanuploadURL(rel="upload:default")fortheOVFdescriptor.The nameattributeofthisFileelementhasbeencreatedbytheserverandspecifiesacontainerthattheserverhas createdtoreceivethecontentsofthedescriptor.Ithasnorelationtothefilenameofthedescriptorinthe clientsfilesystem. TheclientuploadstheOVFdescriptorbymakingaPUTrequesttotheuploadURL,andsupplyingthe descriptorscontentsasanEnvelopeelementintherequestbody.Theserverrespondswitha200OKstatus, asshowninExample 43. Example 4-3. Upload OVF Descriptor Request:
PUT http://vcloud.example.com/transfer/.../descriptor.ovf Content-Type text/xml ... <Envelope ... > ... </Envelope>
Response:
200 OK
Afterthedescriptorisuploaded,theservervalidatesitand,ifitisvalid,createsuploadURLsforeachofthe filesitreferences.Totracktheprogressofthisoperation,theclientcanmakeperiodicGETrequeststothe vAppTemplateURL.Whentheoperationiscomplete,theresponsetothiskindofrequestincludesadditional Fileelementsbeyondtheonealreadycreatedforthedescriptor,asshowninExample 44. Example 4-4. GET vAppTemplate with Upload URLs Request:
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="0" name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> ... <Description>Ubuntu vApp Template</Description> <Files> <File size="3940" bytesTransferred="3940" name="descriptor.ovf"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../descriptor.ovf"/> </File>
44
VMware, Inc.
<File size="1950489088" bytesTransferred="0" name="disk0.vmdk"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../disk0.vmdk"/> </File> </Files> </VAppTemplate>
Inthisexample,theovfDescriptorUploadedattributehasavalueoftrueandthestatusattributehasa valueof0.Ifthedescriptorfailsvalidation,thestatusissetto1,andthetemplatecontainsaTaskelement whoseErrorelementindicatesthereasonforthefailure. EachoftheFileelementsincludesanuploadlink(<Link rel="upload:default" ... />)andseveral attributes:

size.Thefilesize,takenfromthesizeattributeoftheFileelementintheOVFdescriptor. bytesTransferred.Forallfilereferencesotherthanthedescriptor,thisattributeisinitiallysettoavalueof 0indicatingthattheuploadhasnotyetbegun.IntheFilereferencetothedescriptor,thevalueofthe bytesTransferredattributeisequaltothevalueofthesizeattribute,indicatingthatallthebytesinthe descriptorhavebeentransferred. name.Thefilename,takenfromthehrefattributeoftheFileelementintheOVFdescriptor.
Including a Manifest
SomeOVFpackagesincludeamanifestdocument,whichspecifiesachecksumforeachfileinthepackage.If youareuploadingapackagethatincludesamanifestfile,addamanifestRequired="true"attributetothe requestbody,asshowninExample 45. Example 4-5. uploadVappTemplate Request for an OVF Package That Includes a Manifest
POST http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml <UploadVAppTemplateParams name="Ubuntu Template" manifestRequired="true" xmlns="http://www.vmware.com/vcloud/v1" > <Description>Ubuntu vApp Template</Description> </UploadVAppTemplateParams>
Whenyouspecifythatamanifestisrequired,thesetofFileelementsreturnedafteryouuploadtheOVF descriptorincludesoneforthemanifestitself.Afterallthefilesareuploaded,eachfileischeckedbytheserver toverifythatitschecksummatchestheonestatedinthemanifest.Ifanychecksumsdonotmatch,the templatesstatusattributeissetto1andthetemplatecontainsaTaskelementwhoseErrorelement indicatesthereasonforthefailure.
Uploading the Files

InformationfromtheserversresponseinExample 43enablestheclienttoconstructaseriesofPUTrequests, oneforeachFileinthelist,thatuploadthefilesreferencedbythetemplate.Eachrequestspecifiesanupload URLandacontentlengthinbytes. Example 46showsanuploadrequestforoneofthefilesrequiredbyanOVFpackage.Theuploadrequestis simplyafewheaderlines,followedbytheserializedfilecontent.
VMware, Inc.
45
Example 4-6. Uploading File Data Request:

PUT http://vcloud.example.com/transfer/.../disk0.vmdk Content-length: 1950489088
...serializedcontentsoffiledisk0.vmdk... EOF Response:

200 OK
Tomonitortheprogressofanupload,aclientcanuseanHTTPGETrequestspecifyingtheVAppTemplate URLthatwasreturnedintheuploadmap.Theresponseisthesameuploadmap.Afterallthefileshavebeen uploaded,theresponseincludesaTaskthatthevAppTemplatecreatestomonitortheeventsleadinguptoits resolution,andanupdatedvalueforthebytesTransferredattributeofeachFileelement,asshownin Example 47.(ThecompleteVAppTemplatebodyisreturned.Thisexampleomitsmostofitforclarity.) Example 4-7. Monitoring the Progress of an Upload Request:
Response:
200 OK <VAppTemplate name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" status="0" ... > ... <Files> ... <File size="1950489088" bytesTransferred="500000000" name="disk0.vmdk"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../disk0.vmdk"/> </File> </Files> ... </VAppTemplate>
Iftheresponsetoanuploadprogressrequestindicatesthattheuploadterminatedbeforeitwascomplete(for example,ifrepeatedprogressrequestsshowthesamebytesTransferredvalue),aclientcanusethesize andbytesTransferredvaluesfromtheresponsetoconstructarangedPUToftheremainingcontents,as showninExample 48. NOTERangedPUTrequestsaretypicallyrequiredforverylargeuploads,especiallywhennetwork bandwidthorlatencycouldcausetheoperationtotimeout. Example 4-8. Ranged PUT to Complete a Partial Upload Request:
PUT http://vcloud.example.com/transfer/.../disk0.vmdkk Content-Range: bytes 500000000-1950489087/1950489088 Content-length: 1450489088
...serializedcontentsofspecifiedrange... EOF
46
VMware, Inc.
Response:
200 OK
View the OVF Descriptor of a vApp Template

TherepresentationofaresolvedvApptemplateincludesalinktoitsOVFdescriptor.
<Link rel="ovf" type="text/xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/ovf"/>
AGETrequestspecifyingtheURLinthehrefvalueofthisLinkreturnsthedescriptor,asshownin Example 49.OnlyresolvedVAppTemplateelementsincludethislink.TogettheOVFdescriptorthatdefines avApporvirtualmachine,youmuststartwiththetemplatefromwhichitwascreated. WhenyouviewtheOVFdescriptorofavApptemplate,itincludesdeploymentspecificinformation. Example 4-9. View the OVF Descriptor of a vApp Template Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/ovf
Response:
200 OK Content-Type text/xml ... <Envelope ...> <DiskSection> <Info>Virtual disk information</Info> <Disk ovf:capacity="100" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/ vmdk.html#streamOptimized"/> </DiskSection> <VirtualSystem ... ovf:id="Ubuntu Template"> ... </VirtualSystem> </Envelope>
NOTETheOVFdescriptordoesnotincludeanyFilereferences.Theseareremovedbytheserverafterthe templateisresolvedandrecreatedwhenthetemplateisenabledfordownload.
Download a vApp Template as OVF

AvAppTemplatecanbedownloadedasanOVFpackage.Afterlocatingthetemplatebybrowsingacatalog orvDC,aclientcanrequestthatthetemplatebeenabledfordownload.Thisoperationconstructsadownload URLforthetemplatesOVFdescriptorfileandaddsittothetemplate.Aclientcandownloadthedescriptor fromthisURL,examineittodiscoverthedownloadURLsofthefilesitreferences,thenmakeaseriesofGET requeststhatdownloadthefilesthemselves. WhenyoudownloadavApptemplateasOVF,alldeploymentspecificinformationisremovedfromtheOVF.
VMware, Inc.
47
Enable a vApp Template for Download

AvApptemplatemustbeexplicitlyenabledfordownloadbyanadministratororprivilegeduser. Example 410showssucharequest.TheresponseisaTaskelement.Thetimerequiredforthetasktocomplete isdeterminedbythenumberandsizeofthefilescomprisingthetemplate. Example 4-10. Enable a vApp Template for Download Request:
POST http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/action/enableDownload
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Enabling download of Virtual Application Template Ubuntu Template (268)" ... > ... </Task>
WhentheenableDownloadtaskcompletes,thetemplatesfilesareavailablefromthevCloudtransferservice, andthevAppTemplateincludesaLinkelementthatcontainsaURLfromwhichthetemplatesOVFdescriptor canbedownloaded,asshowninExample 411. Example 4-11. vApp Template with DownloadURL for OVF Descriptor Request:
GET http://vcloud.example.com/api/vAppTemplate/vappTemplate-268
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" ...> ... <Link type="text/xml" rel="download:default" href="http://vcloud.example.com/transfer/.../descriptor.ovf"/> ... </VAppTemplate>
Theclientusesthisdownload:defaultURLinaGETrequestthatdownloadstheOVFdescriptor(asshown inExample 412),thenexaminesthecontentsofthedescriptortodiscoverthehrefvaluesfortheremaining filesinthetemplatesReferencescontainer. Example 4-12. Downloading the OVF Descriptor Request:
GET http://vcloud.example.com/transfer/..../descriptor.ovf
Response:
200 OK ... <Envelope ...> <References> <File ovf:href="disk0.vmdk" ovf:id="file1" ovf:size="1950489088"/> </References> <DiskSection> <Info>Virtual disk information</Info>
48
VMware, Inc.
<Disk ovf:capacity="100" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/ vmdk.html#streamOptimized"/> </DiskSection> <VirtualSystem ... ovf:id="Ubuntu Template"> ... </VirtualSystem> </Envelope>
Inthisexample,thedescriptorreferencesonlyonefile:
<File ovf:href="disk0.vmdk" ovf:id="file1" ovf:size="1950489088"/>
ThehrefattributeoftheFileelementisthepathtothefilerelativetothelocationofthedescriptoritself.To retrievethisfilefromtheserver,theclientmustmakeaGETrequesttoaURLthatitconstructswithasimple twostepalgorithm: 1 2 StartwiththeURLthatwascontainedinthedownload:defaultattributeoftheLinktothedescriptor thatwascontainedbytemplate.(SeeExample 411.) ReplacethefinalcomponentofthatURLwiththevalueofthehrefattributeoftheFileinthe downloadedOVFdescriptor.
Theresultofthisprocess,usingtheresponsesinExample 411andExample 412,istherequestURLshown inExample 413. Example 4-13. Downloading a Referenced File Request:
GET http://vcloud.example.com/transfer/..../disk0.vmdk
Response:
200 OK ...
...serializedcontentsoffiledisk0.vmdk... EOF
Whenthedownloadcompletes,thevApptemplateisavailableontheclientasanOVFpackage. NOTEMakesurethatthedownloadedfilesmaintainthesamerelationshiptoeachotherinthelocalfile systemastheyhadonthetransferserverfilesystem.Inthiscase,thedescriptoranddisk0.vmdkwereboth inthesamedirectory(thedefaultarrangement).
Disable a vApp Template for Download

AnadministratororauthorizedusercanusethedisableDownloadactiontodisableavApptemplatefor download,asshowninExample 414.TheresponseisanHTTP204(NoContent)status. Example 4-14. Disable a vApp Template for Download Request:
POST http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/action/disableDownload
Response:
204 No Content
VMware, Inc.
49
AfterthedisableDownloadrequestcompletes,thetemplatesfilesareremovedfromthetransferserver,and theLinkelementthatcontainsthedownload:defaultURLnolongerappearsinthevAppTemplatebody.
Upload a Media Image

ThevCloudAPIsupportsuploadingvirtualmediasuchasCDROMandfloppydiskimages.Theworkflow fortheseproceduresissimilartothatdescribedforvApptemplateuploads;theclientPOSTsarequesttothe serverthatincludesinformationaboutavirtualmediaitemitintendstoupload,andtheserverrespondswith anuploadURL,whichtheclientcanusetodoamonolithicorrangedPUTofthefilecontents. Example 415showsarequesttouploadaCDROMimageinISOformat.TherequestbodyisaMedia element,whichspecifiesthename,size,andtypeofthefile. Example 4-15. Request to Upload an ISO Image
POST http://vcloud.example.com/api/v1.0/vdc/5/media Content-Type: application/vnd.vmware.vcloud.media+xml <Media name="database.iso" size="242131" imageType="iso" xmlns="http://www.vmware.com/vcloud/v1"> <Description>ISO database image</Description> </Media>
TheserverreturnsaMediarepresentationthatincludesasingleFileelement,asshowninExample 416.The clientrespondswithaPUTrequest,sendingserializedfiledatatotheFileelementsupload:defaultURL. Example 46showsasimilarrequest. Example 4-16. Server Response to Request to Upload an ISO Image
Content-Type: application/vnd.vmware.vcloud.media+xml 201 Created <Media name="database.iso" size="242131" status="0" imageType="iso" href="http://vcloud.example.com/api/v1.0/media/254" type="application/vnd.vmware.vcloud.media+xml" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>ISO database image</Description> <Files> <File name="database.iso" size="242131" bytesTransferred="0" <Link rel="upload:default" href="http://vcloud.example.com/.../database.iso"/> </File> </Files> </Media>
Duringtheupload,thevalueofthebytesTransferredattributeoftheFileelementindicatesupload progress.Whentheuploadiscomplete,thevalueofthestatusattributeissetto1,andtheFileselementis nolongerincludedintheMediarepresentation. NOTEDownloadingmediaimagesisnotsupportedinthisreleaseofCloudDirector.
Copying and Moving

ThevCloudAPIprovidesobjectspecificcopyoperationsformediaimages,vApptemplates,andvApps. TheseoperationssupportcreatingacopyoftheobjectinthesamevDCorinanothervDCwithinthesame organization.Eachcopyoperationsupportsanoptiontodeletethesourceobjectafterthecopyiscomplete, whicheffectivelymovesthesourceobjecttoanothervDC,orrenamesitwithinthesamevDC.ThevCloudAPI doesnotincludeanexplicitmoveoperation.
50
VMware, Inc.
Whenyoumoveanobjectbycopyingitanddeletingitssource,anintermediateobjectiscreatedinthetarget vDC,aspartofthefollowingsequenceofevents. 1 2 3 Thesourceobjectiscopedtoanintermediateobjectwhosenameisacombinationoftheobjectnameand aUUID. Thesourceobjectisdeleted. Theintermediateobjectisrenamedwiththenamespecifiedforthetargetobjectinthecopyrequest.
Copy or Move a Media Image

ThecloneMediarequestmakesacopyofthemediaimagereferencedintheSourceelementoftherequest body.Therequestspecifiesanewnameand,optionally,anewdescriptionforthecopy.Therequestcan optionallyincludeanIsSourceDeleteelementwhosevaluespecifieswhetherthesourcemediaimageis deletedafterthecopyiscomplete.IfIsSourceDeleteismissingfromtherequestbodyorpresentwitha valueoffalse,thesourceobjectremainsinplaceafterthecopyiscomplete.SettingIsSourceDeletetotrue effectivelymovesthemediaimage. Example 417copiesthevirtualmediaimagereferencedbyhttp://vcloud.example.com/api/v1.0/media/254to thevDCreferencedbyhttp://vcloud.example.com/api/v1.0/vdc/5andprovidesanewnameanddescription forthecopy.Thesourceimageremainsinplaceafterthecopyiscomplete. Example 4-17. Copy a Virtual Media Image Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneMedia Content-Type: application/vnd.vmware.vcloud.cloneMediaParams+xml <CloneMediaParams name="databse-backup.iso" xmlns="http://www.vmware.com/vcloud/v1"> <Description>This is a backup copy of the ISO database image</Description> <Source href="http://vcloud.example.com/api/v1.0/media/254"/> </CloneMediaParams>
Response:
201 Created ... <Media name="database-backup.iso" size="242131" status="0" imageType="iso" href="http://vcloud.example.com/api/v1.0/media/277" type="application/vnd.vmware.vcloud.media+xml" ...> <Link rel="up" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>This is a backup copy of the ISO database image</Description> <Tasks> <Task ... operation="Busy Media File cloned(277)" ... > ... </Task> </Tasks> </Media>
Copy or Move a vApp Template

ThecloneVAppTemplaterequestmakesacopyofthevApptemplatereferencedintheSourceelementofthe requestbody.Therequestspecifiesanewnameand,optionally,anewdescriptionforthecopy.Therequest canoptionallyincludeanIsSourceDeleteelementwhosevaluespecifieswhetherthesourcevApptemplate isdeletedafterthecopyiscomplete.IfIsSourceDeleteismissingfromtherequestbodyorpresentwitha valueoffalse,thesourceobjectremainsinplaceafterthecopyiscomplete.SettingIsSourceDeletetotrue effectivelymovesthevApptemplate. Example 418movesthevApptemplatereferencedby http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate111tothevDCreferencedby http://vcloud.example.com/api/v1.0/vdc/5.BecausetheIsSourceDeleteelementintherequestbody containsavalueoftrue,thesourcevApptemplateisremovedafterthecopyiscomplete.
VMware, Inc.
51
Example 4-18. Move a vAppTemplate Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVAppTemplate Content-Type: application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml <CloneVAppTemplateParams name="Ubuntu Copy" xmlns="http://www.vmware.com/vcloud/v1"> <Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <IsSourceDelete>true</IsSourceDelete> </CloneVAppTemplateParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="0" name="Ubuntu Copy" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-302" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> ... <Tasks> <Task ... operation="Busy Virtual Application Template Ubuntu Copy (382)" ...> ... </Task> </Tasks> </VAppTemplate>
Copy or Move a vApp

ThecloneVApprequestmakesacopyofthevAppreferencedintheSourceelementoftherequestbody.The requestspecifiesanewnameand,optionally,anewdescriptionforthecopy.Therequestcanoptionally includeanIsSourceDeleteelementwhosevaluespecifieswhetherthesourcevAppisdeletedafterthecopy iscomplete.IfIsSourceDeleteismissingfromtherequestbodyorpresentwithavalueoffalse,thesource objectremainsinplaceafterthecopyiscomplete.SettingIsSourceDeletetotrueeffectivelymovesthe vApp. YoucannotcopyormoveavAppthatisdeployed. Example 419copiesthevAppreferencedbyhttp://vcloud.example.com/api/v1.0/vApp/vApp201tothevDC referencedbyhttp://vcloud.example.com/api/v1.0/vdc/5andprovidesanewnameanddescriptionforthe copy.BecausetheIsSourceDeleteelementintherequestbodycontainsavalueoffalse,thesourcevApp isunaffectedbythecopyoperation.(ThedefaultvalueofIsSourceDeleteisfalse.Theexampleincludesit forillustrativepurposesonly.) TheresponseisaTaskelementownedbythecopy. Example 4-19. Copy a vApp Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVApp Content-Type: application/vnd.vmware.vcloud.cloneVAppParams+xml <CloneVAppParams name="New Linux Server" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Cloned from Ubuntu FTP Server</Description> <Source href=http://vcloud.example.com/api/v1.0/vApp/vApp-201/> <IsSourceDelete>false</IsSourceDelete> </CloneVAppParams>
52
VMware, Inc.
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp name="New Linux Server" status="0" href="http://vcloud.example.com/api/v1.0/vApp/vapp-999" ...> <Description>Cloned from Ubuntu FTP Server</Description> ... <Tasks> <Task ... operation="Busy Virtual Application New Linux Server Copy (201)" ...> ... </Task> </Tasks> </VApp>
Changing a Name or Description

EveryvAppTemplate,vApp,andMediaelementincludesaneditlinkthataclientcanuseiftochangethe valueoftheobjectsnameattributeorDescriptionelement.Ineachcase,therequestmustincludeallthe requiredelementsoftheobjectsrepresentation,eventheonesthatyouarenotchanging.
Change the Name or Description of a vAppTemplate

Example 420changesthedescriptionofthevApptemplateshowninExample 36onpage 39. Example 4-20. Change the Name and Description of a vAppTemplate Request:
PUT http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111 Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate xmlns="http://www.vmware.com/vcloud/v1 name="Ubuntu 9.10" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"> <Description>Ubuntu 9.10 Server Edition, with vsftpd</Description> </VAppTemplate>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
Change the Name or Description of a vApp

YoucanchangethenameordescriptionofavAppusingaproceduresimilartotheoneshownin Example 420.
VMware, Inc.
53
Change the Name or Description of a Media Image

Example 421changesthedescriptionofamediaimagethatwascreatedbythecopyoperationin Example 417. Example 4-21. Change the Description of a Media Image Request:
PUT http://vcloud.example.com/api/v1.0/media/277 Content-Type: application/vnd.vmware.vcloud.media+xml ... <Media name="database.iso" size="242131" imageType="iso" xmlns="http://www.vmware.com/vcloud/v1"> <Description>New description</Description> </Media>
Response:
Delete a vAppTemplate, vApp, or Media Image

YoucanuseanHTTPDELETErequesttodeleteavAppTemplate,vApp,ormediaimage.Allofthese operationsconformtotheprototype(DELETEhref,wherehrefistheURLoftheobjectyouwanttodelete) showninExample 210onpage 30.Youcannotdeleteanobjectifitisinuse.Anyobjectthatisbeingcopied ormovedisinuse.Othercriteriathatdeterminewhetheranobjectisinusedependontheobjecttype.
AvApptemplateisinuseifitisbeinginstantiated.Afterinstantiationiscomplete,thetemplateisno longerinuse. AvAppisinuseifitisdeployed. AmediaimageisinuseifitisinsertedinaVm.
Cataloging vApp Templates and Media Images

AlthoughreferencestovApptemplatesandmediaimagescanberetrieveddirectlyfromthevDCtowhich theywereuploaded,itisacommonpracticetoplacereferencestosuchassetsinoneofanorganizations catalogs.Doingsomakestheasseteasiertodiscover,becauseacatalogcanincludeassetsfromallvDCsinan organization.Italsoprovidesmoreflexibleadministrativecontrolovertheseassets,becauseaccesstocatalogs andtheitemsinthemcanberestrictedtospecificusersandgroups.AssetssuchasvApptemplatesarenot enabledformostusesuntilyouincludetheminacatalog.Forexample,avApptemplatethatisnotincluded inacatalogcanbemodifiedbutcannotbeinstantiated.Amediaimagethatisnotincludedinacatalogcannot beusedbyanyonebutitsowner.
Add an Item to a Catalog

AcatalogcancontainreferencestovApptemplatesandmediaimagesthathavebeenuploadedtoanyvDC inanorganization.AvApptemplateormediaimagecanbelistedinatmostonecatalog.
54
VMware, Inc.
To add an item to a catalog 1 2 BrowsethevDCsinanorganizationtofindResourceEntityelementsthatreferencetheitemyouwant toaddtothecatalog. CreateaCatalogItemelementthatcontainsareferencetotheitem. Example 34onpage 37listsanumberofResourceEntityelementsinavDC.TocreateaCatalogItem thatreferencesthisone:
<ResourceEntity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>
followtheseguidelines:
ThenameattributeoftheCatalogItemcanbethesameastheoneintheResourceEntity,oryou canmakeupanewvalueforname. TheDescriptionelementoftheCatalogItemcanbethesameastheDescriptionelementforthe objectreferencedbytheResourceEntity,oryoucanmakeupanewDescription. ThehrefattributeoftheEntityelementintheCatalogItemmusthavethesamevalueasthehref attributeoftheResourceEntitythattheCatalogItemreferences. PropertyelementsareoptionalinanyCatalogItem.Formoreinformationabouthowtheseelements canbeused,seePropertyonpage 161.
POSTtheCatalogItembodytotherel="add"URLincludedintheCatalogbody.
Example 422addsaCatalogItemtothecataloglistedinExample 32onpage 35. Example 4-22. Add an Item to a Catalog Request:
POST http://vcloud.example.com/api/v1.0/catalog/32/catalogItems Content-Type: application/vnd.vmware.vcloud.catalogItem+xml <CatalogItem name="Ubuntu Template with vsftpd" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Approved template for public FTP sites</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Property key="Owner">Tech Ops</Property> </CatalogItem>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem name="Ubuntu Template with vsftpd" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Description>Approved template for public FTP sites</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Property key="Owner">Tech Ops</Property> </CatalogItem>
VMware, Inc.
55
Remove an Item from a Catalog

AorganizationadministratororauserwithadequatepermissionscanremoveaCatalogItembymakinga DELETErequesttotheitsrel="remove"link.Example 423removestheCatalogItemcreatedin Example 422. Example 4-23. Remove a CatalogItem Request:
DELETE http://vcloud.example.com/api/v1.0/catalogItem/221
Response:
204 No Content
Catalog Links in a VApp Template or Media Image

EveryvAppTemplateandMediaelementthathasbeenaddedtoacatalogcontainsarel="catalogItem" linkwhosehrefvalueistheURLoftheCatalogItemthatreferencesthetemplateormediaimage(seethe responseinExample 36onpage 39).AclientcanGETthatURLandexaminetheresponsetofindthe rel="up"linkintheCatalogItem(seetheresponseinExample 422).Thislinkisareferencetothecatalog thatcontainstheCatalogItem.
Controlling Access
AnorganizationadministratorcanusecontrolAccesslinkstocontrolaccesstocatalogsandvApps.
Control Access to Catalogs

Whenyoulistthecontentsofanorganization,eachcatalogincludesaccesscontrollinks,asshownin Example 424,whichisanexcerptfromExample 31onpage 34. Example 4-24. Access Control Links for a Catalog
<Org ... > <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess/"/> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/37" name="Shared Catalog"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/37/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/37/action/controlAccess/"/> ... </Org>
Foreachofthecatalogslistedinthisexcerpt,threelinksareprovided:

ALinkwithrel="down"thatprovidestheURLforthecatalogitself AnotherLinkwithrel="down"thataclientcanusetoretrievethecatalogsaccesscontrolsettings ALinkwithrel="controlAccess"thataclientcanusetomodifythecatalogsaccesscontrolsetting
Anorganizationadministratororprivilegedusercanusetheselinkstoviewormodifyaccesscontrolsona catalog.Example 425showstherequesttoviewtheaccesscontrolsettingsforacatalog.
56
VMware, Inc.
Example 4-25. Viewing Access Control Settings for a Catalog Request:

GET http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.controlAccess+xml ... <ControlAccessParams ...> <IsSharedToEveryone>false</IsSharedToEveryone> </ControlAccessParams>
BecausethevalueofIsSharedToEveryoneisfalse,theadministratormustgrantaccesstoindividualusers orgroups,specifiedbyreference.InExample 426,theadministratorPOSTsamodifiedversionofthe ControlAccessParamselementreceivedinExample 425tothecatalogsaccesscontrolURL.The modificationspopulatetheAccessSettingscontainerwithtwoAccessSettingelements,eachofwhich assignsanaccessleveltoaspecificuser. Example 4-26. Granting Catalog Access to Users Request:
POST http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess Content-Type: application/vnd.vmware.vcloud.controlAccess+xml <ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1"> <IsSharedToEveryone>false</IsSharedToEveryone> <AccessSettings> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/1"/> <AccessLevel>FullControl</AccessLevel> </AccessSetting> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/6"/> <AccessLevel>ReadOnly</AccessLevel> </AccessSetting> </AccessSettings> </ControlAccessParams>
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.controlaccess+xml ... <ControlAccessParams ...> <IsSharedToEveryone>false</IsSharedToEveryone> <AccessSettings> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/1"/> <AccessLevel>FullControl</AccessLevel> </AccessSetting> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/6"/> <AccessLevel>ReadOnly</AccessLevel> </AccessSetting> </AccessSettings> </ControlAccessParams>
VMware, Inc.
57
Tospecifyglobalaccesscontrolsthatapplytoallmembersofanorganization,anorganizationadministrator cansetIsSharedToEveryonetotrueandspecifyanaccesslevelintheEveryoneAccessLevelelement,as showninExample 427. Example 4-27. Granting Catalog Access to Everyone Request:
POST http://vcloud.example.com/api/v1.0/catalog/32/controlAccess Content-Type: application/vnd.vmware.vcloud.controlAccess+xml ... <ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1"> <IsSharedToEveryone>true</IsSharedToEveryone> <EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel> </ControlAccessParams>
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.controlaccess+xml ... <ControlAccessParams ...> <IsSharedToEveryone>true</IsSharedToEveryone> <EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel> </ControlAccessParams>
AccesscontrolforvAppsisimplementedinasimilarway.SeeExample 536onpage 89.
58
VMware, Inc.
Datacenter Operations
ThevCloudAPIsupportsprogrammaticaccesstoarangeofselfservicedatacenteroperationsthatallowusers tocreate,configure,operate,andconnecttovApps. Thischapterincludesthefollowingtopics:

SummaryofDatacenterOperationsRequestsonpage 59 vAppLifecycleonpage 60 InstantiateavAppTemplateonpage 61 ComposeavApponpage 65 RecomposeavApptoAddorRemoveVirtualMachinesonpage 67 CaptureavApptoCreateavAppTemplateonpage 68 ReconfiguringvAppsandVirtualMachinesonpage 69 DeployingandControllingvAppsandVirtualMachinesonpage 80 ControlAccesstovAppsonpage 89 RetrieveaTaskonpage 89
Summary of Datacenter Operations Requests

Table 51summarizesdatacenteroperationsrequestssupportedinthisrelease.Thetableusesthefollowing conventions:

APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0 idisaninteger vApporVmURLisaURLoftheformAPIURL/vApp/vappid(foravAppobject)or APIURL/vApp/vmid(foraVmobject)
Table 5-1. Summary of Datacenter Operations Requests

Operation InstantiateavAppTemplate RetrievevAppTemplate CustomizationSection ModifyvAppTemplate CustomizationSection ComposeavApp Request POSTAPIURL/vdc/id/action/ instantiateVAppTemplate GETAPIURL/vAppTemplate/ vappTemplateid/ customizationSection PUTAPIURL/vAppTemplate/ vappTemplateid/ customizationSection POSTAPIURL/vdc/id/action/ composeVApp Request Body InstantiateVAppTemplateParams None Response VApp CustomizationSection
CustomizationSection
Task
ComposeVAppParams
VApp
VMware, Inc.
59
Table 5-1. Summary of Datacenter Operations Requests (Continued)

Operation RecomposeavApptoAddor RemoveVirtualMachines CaptureavApptoCreatea vAppTemplate DeployavApporVirtual Machine UndeployavApporVirtual Machine PowerOnavApporVirtual Machine PowerOffavApporVirtual Machine ResetavApporVirtual Machine SuspendavApporVirtual Machine DiscardtheSuspendedState ofavApporVirtualMachine ShutDownavApporVirtual Machine RebootavApporVirtual Machine InsertMediaIntoaVirtual Machine EjectMediafromaVirtual Machine ListMediaDevicesofa VirtualMachine GetaRequestforUserInput ProvideRequestedUser Input GetaScreenThumbnailfora VirtualMachine GetaScreenTicketfora VirtualMachine ControlAccesstovApps Request POST APIURL/vApp/vappid/action/ recomposeVApp POSTAPIURL/vdc/id/action/ captureVApp POSTvApporVmURL/action/ deploy POSTvApporVmURL/action/ undeploy POSTvApporVmURL/ power/action/powerOn POSTvApporVmURL/ power/action/powerOff POSTvApporVmURL/ power/action/reset POSTvApporVmURL/ power/action/suspend POSTvApporVmURL/action/ discardSuspendedState POSTvApporVmURL/ power/action/shutdown POSTvApporVmURL/ power/action/reboot POSTAPIURL/vApp/vmid/ media/action/insertMedia POSTAPIURL/vApp/vmid/ media/action/ejectMedia GETAPIURL/vApp/vmid/ virtualHardwareSection/media GETAPIURL/vApp/vmid/ question POSTAPIURL/vApp/vmid/ question/action/answer GETAPIURL/vApp/vmid/ screen POSTAPIURL/vApp/vmid/ screen/action/acquireTicket POST APIURL/vApp/vappid/action/ controlAccess GETAPIURL/task/id Request Body RecomposeVAppParams Response Task
CaptureVAppParams DeployVAppParams UndeployVAppParams None None None None None None None MediaInsertOrEjectParams MediaInsertOrEjectParams None None VmQuestionAnswer None None ControlAccessParams
VAppTemplate Task Task Task Task Task Task Task 204NoContent 204NoContent Task Task RasdItemsList VmPendingQuestion 204NoContent screenthumbnail (Contenttype:image/png) ScreenTicket ControlAccessParams
RetrieveaTask
None
Task
vApp Lifecycle
AvAppcontainsoneormoreVmelements,whichrepresentindividualvirtualmachines.Italsocontains informationthatdefinesoperationaldetailsforthevAppandthevirtualmachinesitcontains.ThevApp lifecycleincludesseveraldistinctstates:

AnOVFpackage,theforminwhichvAppsaretypicallymadeavailablefordownloadanddistribution AvApptemplate,createdwhenaclientuploadsanOVFpackagetoavDC
60
VMware, Inc.
Chapter 5 Datacenter Operations
AnundeployedvApp,createdwhenavApptemplateisinstantiatedoradeployedvAppisundeployed. AdeployedvApp,readytobepoweredonandoperated.Youcanspecifythatinstantiationinclude deployment,poweron,orboth.
Figure 51illustratesthesestatetransitions. Figure 5-1. vApp State Transitions
OVF package
descriptor.ovf
disk0.vmdk upload
vApp template
<VApp Template...status=8 href=http://.../vapp Template-3> ... ... </VApp Template>
instantiate vApp
<VApp...status=8 deployed=false href=http://.../vapp-9> ... <Link rel=deploy...> ... </VApp>
deploy vApp
<VApp...status=8 deployed=true href=http://.../vapp-9> ... <Link rel=power:powerOn...> ... </VApp>
OVFuploadandthecreationofvApptemplatesiscoveredinUploadOVFtoCreateavAppTemplateon page 42.
Instantiate a vApp Template

AvApptemplatespecifiesasetoffiles,suchasvirtualdisks,thatthevApprequires,andasetofabstract resources,suchasCPU,memory,andnetworkconnections,thatmustbeallocatedtothevAppbythevDCin whichitisdeployed.InstantiationcreatesavAppfromthefilesspecifiedinthetemplate,andallocates vDCspecificbindingsfornetworksandotherresources.(Thesebindingsareadvisory;theydonotguarantee thattheresourceswillbeavailablewhenthevAppisdeployed.)Instantiationisaprerequisitetodeployment. Inthemostcommonusecase,aclientinstantiatesavApptemplateandimmediatelydeploysit.
VMware, Inc.
61
About Instantiation Parameters

InstantiationparametersallowyoutospecifycertainpropertiesofavApp,including:

DetailsofitsvAppnetwork(required). LeasesettingsforthevApp(optional,ifyouwanttooverrideyourorganizationsdefaults) StartupandshutdownparametersforthevApp(applicableonlyifthevApphasmultiplechildren)
Instantiationparametersalsoincludeawaytoindicatethatanytermsandconditions(suchaslicense agreements)containedinthevApphavebeenaccepted. InstantiationparameterscannotbeusedtomodifyaVmthatappearsinthevAppsChldrencontainer.To changethepropertiesofaVm,usethereconfigurationlinksinitsItemelements.(SeeReconfiguringvApps andVirtualMachinesonpage 69.)
About vApp Networks

AvAppnetworkisalogicalnetworkthatdefineshowthevAppconnectstoanorganizationnetworkinthe targetvDC.ItisspecifiedaspartofaninstantiateVAppTemplateorcomposeVApprequest,createdwhen thevAppisdeployed,anddeletedwhenthevAppisundeployed.Virtualmachines(Vmelements)inthe vAppsChildrencollectionallconnecttothisnetwork,asspecifiedintheirNetworkConnectionelements. ThedetailsofavAppnetworkarespecifiedintheNetworkConfigelementofthe InstantiateVAppTemplateParamsrequestbody,andincludethefollowing:
AnameforthevAppnetwork,specifiedinthenetworkNameattributeoftheNetworkConfigelement.If thetemplatethatyouareinstantiatingincludesanovf:NetworkSectionelement,thevalueofthe networkNameattributeoftheNetworkConfigelementmustmatchthevalueoftheovf:nameattributeof theovf:Networkelementinthetemplate.Ifthetemplatedefinesmultiplenetworks,thenyoumustdo thesameintheInstantiateVAppTemplateParamsrequest. AConfigurationelementthatspecifiestheorganizationnetworktowhichthevAppnetworkconnects andaFenceModevaluethatcontrolshowthosetwonetworksareconnected.
Instantiating a vAppTemplate Using Default Parameters

AninstantiationrequestcansupplyaminimalInstantiateVAppTemplateParamselementtospecifythat instantiationshouldusethetargetvDCsdefaultbindings(seeInstantiatingtheTemplateinthevDCon page 24).ThistypeofrequestcanbeappropriateforavAppthathassimplerequirementsforstorage, network,andcomputeresources.AvAppinstantiatedinthiswaycanbereconfiguredifnecessarytocorrect problemscausedbyadefaultinstantiation.Formoreinformation,seeReconfiguringvAppsandVirtual Machinesonpage 69.
Instantiating a vApp Template Using Additional Parameters

IfaclientwantstospecifyvAppinstantiationparametersindetail,ratherthanrelyingonvDCdefaults,itcan includethedetailsinthebodyoftheinstantiateVAppTemplaterequest. TheinstantiationrequesttakestheformofaPOSTtoavDCsinstantiateVAppTemplateURL.Therequest bodyisanInstantiateVAppTemplateParamselement. ToobtaintheinformationrequiredinanInstantiateVAppTemplateParamselement,theclientmusttake severalsteps:
ExaminethetemplatesOVFtodiscoveranyEULAsectionsthatitincludes.The InstantiateVAppTemplateParamselementcanincludeanAllEULAsAcceptedelementwhosevalue indicateswhetherallEULAtermsincludedinthetemplatewereaccepted.IfavApptemplateincludes anyEULAsections,AllEULAsAcceptedmustbesettoavalueoftrue.Otherwise,instantiationfails. Examinethetemplatesovf:StartupSectionelementtoverifythattheprescribedstartuporderfor childrendoesnotneedtobemodified.
62
VMware, Inc.
Examinethetemplatesovf:NetworkSectionelementtoseewhetheranynetworksaredefinedthere.If thevApptemplateincludesanovf:Networkelement,thenameyouspecifyforthevAppnetworkmust matchthenamespecifiedinthatelementsovf:nameattribute. SeeAboutInstantiationParametersonpage 62. VerifythatyourorganizationsdefaultleasesettingsareappropriateforthisvApp.Iftheyarenot,youcan specifycustomleasesettingsaspartofinstantiation.
Example 51showsaninstantiationrequestsimilartotheoneshowninExample 26onpage 25,butincludes anAllEULAsAcceptedelementthatdenotesacceptanceoftermsandconditionsembeddedinthechildVm elements,andaLeaseSettingsSectionelementthatspecifiescustomdeploymentandstorageleaseterms forthisvApp.ItalsospecifiesthatthevAppshouldbedeployedandpoweredonafteritisinstantiated.(If youomitthedeployandpowerOnattributes,thedefaultvalueoffalseisassumed.) Example 5-1. Instantiating a vApp Template wIth Custom Lease Settings Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml ... <InstantiateVAppTemplateParams name="Linux FTP server" deploy=true powerOn=true xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Example FTP Server</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> <LeaseSettingsSection type="application/vnd.vmware.vcloud.leaseSettingsSection+xml"> <ovf:Info>Lease Settings</ovf:Info> <StorageLeaseInSeconds>172800</StorageLeaseInSeconds> <StorageLeaseExpiration>2010-04-11T08:08:16.438-07:00</StorageLeaseExpiration> </LeaseSettingsSection> </InstantiationParams> <Source href=http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111/> <AllEULAsAccepted>true</AllEULAsAccepted> </InstantiateVAppTemplateParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp name="Linux FTP server" deployed=false status="0" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Description>Example FTP Server</Description> ... <Tasks> <Task ... operation="Creating Virtual Application Linux FTP server(7)" ... > ... </Task> </Tasks> </VApp>
VMware, Inc.
63
TheresponseisasparselypopulatedvAppbodythatcontainsaTaskelementThestatusofthevAppisinitially 0.WheninstantiationiscompleteandthevAppispoweredon,theTasknolongerappearsinthevAppbody, andthevAppstatuschangesto4,indicatingthatallofitschildrenarepoweredon.Youcancheckthestatus ofthetaskbyissuingaGETrequesttothetaskURLoryoucancheckthestatusofthevAppbyissuingaGET requesttothevAppURL.TheseURLsarereturnedinthevalueoftheobjectshrefattribute.
Retrieve or Modify the CustomizationSection of a vApp Template

AvApptemplatecanincludeaCustomizationSectionelementthatspecifieswhetherornotthevirtual machinesinthevAppshouldbecustomizedwhenthevAppisinstantiated.Example 52retrievesthissection fromavApptemplate. Example 5-2. Retrieve vApp Template CustomizationSection Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection
Response:
200 OK Content-type: application/vnd.vmware.vcloud.customizationSection+xml ... <CustomizationSection xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ovf:required="false" vcloud:href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/ customizationSection/" vcloud:type="application/vnd.vmware.vcloud.customizationSection+xml" ...> <ovf:Info>VApp template customization section</ovf:Info> <CustomizeOnInstantiate>true</CustomizeOnInstantiate> <Link rel="edit" type="application/vnd.vmware.vcloud.customizationSection+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/ customizationSection/"/> </CustomizationSection>
TochangethevalueofCustomizeOnInstantiate,PUTaCustomizationSectionbodythathasthechanged valuetothesectionsrel="edit"URL,asshowninExample 53. Example 5-3. Modify vApp Template CustomizationSection Request:
PUT http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection Content-type: application/vnd.vmware.vcloud.customizationSection+xml ... <CustomizationSection xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ovf:required="false" vcloud:href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/ customizationSection/" vcloud:type="application/vnd.vmware.vcloud.customizationSection+xml"> <ovf:Info>VApp template customization section</ovf:Info> <CustomizeOnInstantiate>false</CustomizeOnInstantiate> </CustomizationSection>
Response:
64
VMware, Inc.
Compose a vApp
ThevCloudAPIsupportscomposingavAppfromanycombinationofvApptemplates,vApps,orvirtual machines.WhenyoucomposeavApp,allchildrenofeachcompositionsourcebecomepeersintheChildren collectionofthecomposedvApp. TocomposeavApp,aclientmakesacomposeVApprequestwhosebody,aComposeVAppParamselement, includesthefollowinginformation:
AnInstantiationParamselementthatappliestothecomposedvAppitselfandanyvApptemplates referencedinItemelements.Formoreinformation,seeAboutInstantiationParametersonpage 62. AnItemelementforeachvirtualmachine,vApp,orvAppTemplatetoincludeinthecomposition.Each Itemcancontainthefollowingelements:
ArequiredSourceelementwhosehrefattributevalueisareferencetoavApptemplate,vApp,or Vmtoincludeinthecomposition.IftheSourceelementreferencesaVm,theItemmustalsoinclude anInstantiationParamselementspecifictothatVm. AnoptionalNetworkAssignmentelementthatspecifieshowthenetworkconnectionsofchildVm elementsaremappedtovAppnetworksintheparent.
IfanyofthecompositionitemsissubjecttoaEULA,theComposeVAppParamselementmustincludean AllEULAsAcceptedelementthathasavalueoftrue,indicatingthatyouaccepttheEULA.Otherwise, compositionfails.
ThecomposedvAppmustbedeployedandpoweredonbeforeitcanbeused. Example 54showsacomposeVApprequestthatspecifiestwovAppTemplatesourcesandoneVmsource.The VmsourcerequiresInstantiationParamsthatmodifyitsNetworkConnectionSectiontospecifythevApp networkcreatedforthisvApp.ThevAppTemplatesourcesinheritthissettingfromthebase InstantiationParamselement(theonethatappearsbeforethefirstItemisspecified). Example 5-4. Compose a vApp Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/composeVApp Content-Type: application/vnd.vmware.vcloud.composeVAppParams+xml ... <ComposeVAppParams name="Example Corps CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> </InstantiationParams> <Item> <Source href="http://vcloud.example.com/api/v1.0/vApp/vm-4"/> <InstantiationParams> <NetworkConnectionSection type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ networkConnectionSection/" ovf:required="false"> <ovf:Info/> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="CRMApplianceNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IsConnected>true</IsConnected> <IpAddressAllocationMode>DHCP</IpAddressAllocationMode> </NetworkConnection>
VMware, Inc.
65
</NetworkConnectionSection> </InstantiationParams> </Item> <Item> <Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-114"/> </Item> <Item> <Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-190"/> </Item> <AllEULAsAccepted>true</AllEULAsAccepted> </ComposeVAppParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Example Corps CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Composed CRM Appliance</Description> ... <Tasks> <Task ...> ... </Task> </Tasks> </VApp>
TheresponseissimilartotheoneshowninExample 51,asparselypopulatedvAppbodythatcontainsaTask element.ThestatusofthevAppisinitially0.Whencompositioniscomplete,thestatuschangesto1.
Finding Virtual Machine URLs to Use in a Composition Item

Virtualmachines(Vmobjects)arenotlistedincatalogsorvDCs.TofindtheURLofaVmURLtoincludeina compositionitemSource,GETavApporvApptemplatethatincludesit,andexaminetheChildren containeroftheVAppelement.EachVminthiscontainerhasanhrefattributewhosevalueyoucanuseto referencetheVmforthis(oranyother)purpose. NOTETobeincludedinacompositionrequest,aVmmustbepoweredoff(status="8"). TheVmURLusedinExample 54appearsintheChildrenelementofExample 55. Example 5-5. Vm URL in a vApp Body Request:
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> ... <Children> <Vm status="8" href="http://vcloud.example.com/api/v1.0/vApp/vm-4" ...> ... </Children> </VApp>
66
VMware, Inc.
Recompose a vApp to Add or Remove Virtual Machines

ThevCloudAPIsupportsrecompositionofavApptoaddorremovevirtualmachines(Vmelements).To recomposeavApp,aclientmakesarecomposeVApprequest,supplyingaRecomposeVAppParamselementas therequestbody.TheRecomposeVAppParamselementallowsanarbitrarynumberofDeleteItemelements, butisotherwiseidenticaltoComposeVAppParams.Thismeansthatinadditiontoaddingorremovingvirtual machines,arecomposeVApprequestcanalsochangethenameanddescriptionofthevApp,andcansupply newInstantiationParamstochangevarioussectionsofthecomposedvApporanyoftheaddedvirtual machines. Example 5-6. vApp Before Recomposition Request:
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Example Corps CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Composed CRM Appliance</Description> ... <Children> <Vm status="8" name="CRM-DB" href="http://vcloud.example.com/api/v1.0/vApp/vm-7" ...> ... </Vm> <Vm status="8" name="CRM-CRM" href="http://vcloud.example.com/api/v1.0/vApp/vm-44" ...> ... </Vm> <Vm status="8" name="CRM-HTTP" href="http://vcloud.example.com/api/v1.0/vApp/vm-45" ...> ... </Vm> </Children> ... </VApp>
Example 57showsarecomposeVApprequestthatmodifiesthevAppshowninExample 56byremovingone ofthevirtualmachinesitcontainsandcreatinganewStartupSectionthatspecifiesastartuporderforthe twovirtualmachinesthatremaininthevApp. Example 5-7. Recompose a vApp Request:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-33/action/recomposeVApp Content-Type: application/vnd.vmware.vcloud.recomposeVAppParams+xml ... <RecomposeVAppParams name="Example Corps CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection>
VMware, Inc.
67
<ovf:StartupSection xmlns:vcloud="http://www.vmware.com/vcloud/v1" vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vapp-33/ startupSection/" vcloud:type="application/vnd.vmware.vcloud.startupSection+xml"> <ovf:Info>VApp startup section</ovf:Info> <ovf:Item ovf:order="0" ovf:id="CRM-DB"/> <ovf:Item ovf:order="1" ovf:id="CRM-CRM"/> </ovf:StartupSection> </InstantiationParams> <AllEULAsAccepted>true</AllEULAsAccepted> <DeleteItem href="http://vcloud.example.com/api/v1.0/vApp/vm-45" /> </RecomposeVAppParams>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Example Corps CRM Appliance (33)" ...> ... </Task>
Capture a vApp to Create a vApp Template

ThecaptureVApprequestcreatesavApptemplatefromaninstantiatedvApp.Therequestbody,shownin Example 58,isacaptureVAppParamselementthatspecifiesthehrefofthevApptocapture,alongwitha nameandoptionaldescriptionforthetemplatethatthecapturecreates. NOTEBeforeitcanbecaptured,avAppmustbeundeployed(deployed="false"). Example 5-8. Capture a vApp Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/captureVApp Content-Type: application/vnd.vmware.vcloud.captureVAppParams+xml ... <CaptureVAppParams name="Linux Server Template" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Template captured from Ubuntu vApp</Description> <Source href=http://vcloud.example.com/api/v1.0/vApp/vApp-201/> </CaptureVAppParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate name="Linux Server Template"" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-20" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Template captured from Ubuntu vApp</Description> <Tasks> <Task ... operation="Capturing Virtual Application Template CaturedTemplate (20)" ... > ... </Task> </Tasks> ... </VAppTemplate>
TheresponseisavAppTemplatedocumentthatcontainsaTask.ThestatusofthevAppTemplateisinitially 0.Whenthecaptureoperationiscomplete,thestatuschangesto8.
68
VMware, Inc.
Reconfiguring vApps and Virtual Machines

ConfigurationdetailsforvAppsandthevirtualmachinestheycontainarespecifiedinovf:SectionType elementssuchasLeaseSettingsSection,NetworkConfigSection,andOperatingSystemSection.These sectionscanbespecifiedintheInstantiationParamsforthevApporVm,andcanalsobeeditedinplaceusing reconfigurationlinks(Linkelementswhererel="edit")thattheserveraddstothesesectionsduring instantiation.FormoreinformationaboutthesectionsthatcanbeincludedinInstantiationParams,see InstantiationParamsonpage 172. ThereconfigurationprocessforvAppsandvirtualmachinesissimilar,butthesetofsectionsthatcanbeedited duringreconfigurationdependsontheobjectbeingreconfigured.
Reconfigure a vApp
Table 52summarizesvAppreconfigurationrequestssupportedinthisrelease.Thetableusesthefollowing conventions:

Table 5-2. Summary of vApp Reconfiguration Requests

Operation RetrievevAppLeaseSettings ModifyvAppLeaseSettings RetrievevAppStartupSection ModifyvAppStartupSection RetrievevAppNetworkSection RetrievevAppNetworkConfiguration ModifyvAppNetworkConfiguration Request GETAPIURL/vApp/vappid/ leaseSettingsSection/ PUTAPIURL/vApp/vappid/ leaseSettingsSection/ GETAPIURL/vApp/vappid/ startupSection/ PUTAPIURL/vApp/vappid/ startupSection/ GETAPIURL/vApp/vappid/ networkSection/ GETAPIURL/vApp/vappid/ networkConfigSection/ PUTAPIURL/vApp/vappid/ networkConfigSection/ Request Body None LeaseSettingsSection None StartupSection None None NetworkConfigSection Response LeaseSettingsSection Task StartupSection Task ovf:NetworkSection NetworkConfigSection Task
YoucanreconfigureavAppbymakingchangestoanyofthefollowingsections:

LeaseSettingsSection StartupSection NetworkConfigSection
Modifiedsectionsmustcontainallrequiredelements,evenifyouarenotchangingtheirvalues.Some elementsinsomesectionsarereadonly.Seetheschemareferencesfordetails. NOTEEachVminthevAppsChildrencollectionincludesadditionallinksforconfiguringitsguestoperating system,virtualhardware,andotherproperties.Forclarity,theChildrenarenotshowninExample 59.Tosee them,refertoExample 512onpage 75.
VMware, Inc.
69
Example 5-9. Configuration Links for a vApp Request:

Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Description>Example FTP Server</Description> ... <LeaseSettingsSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/leaseSettingsSection/" ovf:required="false"> <ovf:Info>VApp lease settings</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.leaseSettingsSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/ leaseSettingsSection/"/> <DeploymentLeaseInSeconds>3600</DeploymentLeaseInSeconds> <StorageLeaseInSeconds>3600</StorageLeaseInSeconds> <DeploymentLeaseExpiration>2010-01-21T13:50:59.764-08:00</DeploymentLeaseExpiration> </LeaseSettingsSection> <ovf:StartupSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/startupSection/"> <ovf:Info>VApp startup section</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.startupSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/startupSection/"/> </ovf:StartupSection> <ovf:NetworkSection ... > ... </ovf:NetworkSection> <NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/ networkConfigSection/"/> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig ... > ... <Configuration> ... </Configuration> <IsDeployed>false</IsDeployed> </NetworkConfig> </NetworkConfigSection> <Children> ... </Children> </VApp>
70
VMware, Inc.
To modify a section 1 2 3 4 RetrievethevApporvApptemplateandexaminetheresponsetofindthesectionthatyouwantto modify. RetrievethesectionbymakingaGETrequesttothesectionseditlink(aLinkelementinthesection whererel="edit"). Modifythesectionasneeded. PUTthemodifiedsectiontothesectionseditlink.NotethatsectioneditURLs,unlikemostotherURLs presentedbythevCloudAPI,endwitha/character.
NOTESectionsthatdonothaveaLinkwhererel="edit"cannotbemodified.
Retrieve or Modify the NetworkConfigSection of a vApp Template

Example 510retrievesavAppsnetworkconfiguration(NetworkConfigSection).Example 511modifiesthe sectionandappliesthechanges.ChangestotheStartupSectionorLeaseSettingsSectioncanusethe sameprocedure. Example 5-10. Retrieve vApp Network Configuration Request:
GET http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/
Response:
200 OK Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml ... <NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/"/> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> <IsInherited>true</IsInherited> <Gateway>10.147.56.253</Gateway> <Netmask>255.255.255.0</Netmask> <Dns1>10.147.115.1</Dns1> <Dns2>10.147.115.2</Dns2> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.56.1</StartAddress> <EndAddress>10.147.56.255</EndAddress> </IpRange> </IpRanges> </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> <IsDeployed>false</IsDeployed> </NetworkConfig> </NetworkConfigSection>
ThemodifiedNetworkConfigSectionintherequestbodyinExample 511changestheFenceModevalueto natRoutedandaddsaFeatureselementthatdefinesseveralnetworkfeaturesusefultoanFTPserverthat mustbereachablefromthepublicInternet,butonlyattheFTPportandtheSSHport.
VMware, Inc.
71
AsetofFirewallRulesthatallowTCPtraffictoports21and22.Becausetheserulesrequireyouto specifyasingleIPaddressontheinsideofthefirewall,theIpScopeelementismodifiedtolimittherange ofIPaddressesavailableonthevAppnetworktoasingleaddress.AnyVmthatconnectstothevApp networkdefinedinthisNetworkConfigSectionisgiventhisaddress. ANatServiceelementthatmapsaroutableexternalIPaddresstotheinternalIPaddressallocatedtothe VmbythevAppnetwork.TheVAppScopedVmIdvalueinthiselementistakenfromthe VAppScopedLocalIdelementoftheVmandtheVmNicIdvalueistakenfromits PrimaryNetworkConnectionIndex.SeeExample 512onpage 75.
WheneveryoumodifyavAppnetwork,aswedointhisexample,youmustbesurethatthemodificationsare consistentwiththenetworkconnectionrequirementsofthevirtualmachinesthatconnecttothenetwork.The vAppinthisexamplecontainsasingleVm.AsshowninExample 512onpage 75,thatvirtualmachines NetworkConnectionelementspecifiesanIPaddressthatwillnotbeavailableafterthevAppnetworkhas beenreconfiguredasshowninExample 511.Example 514onpage 77correctsthisproblem.While Example 511usestheIpScopeelementtorestricttheIPaddressesavailableonavAppnetwork,itisusually morepracticaltokeeptherangeofaddressesavailableonavAppnetworksomewhatwider,andapplyany firewallrelatedIPaddressrestrictionsbymodifyingtheNetworkConnection oftheVmtowhichthe FirewallRulesapply,aswedoinExample 514.AwiderrangeofIPaddresseswouldallowthisvApptobe modifiedtoincludeadditionalvirtualmachines,andtheIPaddressrestrictionappliedinExample 514would allowtheFirewallRulesinExample 514toremainvalid. Thisrequest,likeallrequestbodiesderivedfromaresponse,omitstheLinkelementsandhrefattributesthat werepartoftheresponse.ItalsoomitstheIsDeployedelementoftheNetworkConfig.Theseelementsand attributesarecreatedbytheserverandarereadonly.Theyareignoredifyouincludetheminarequest. Example 5-11. Modify vApp Network Configuration Request:
PUT http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/ Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml ... <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> <IsInherited>false</IsInherited> <Gateway>10.147.56.253</Gateway> <Netmask>255.255.255.0</Netmask> <Dns1>10.147.115.1</Dns1> <Dns2>10.147.115.2</Dns2> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.56.1</StartAddress> <EndAddress>10.147.56.1</EndAddress> </IpRange> </IpRanges> </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>natRouted</FenceMode> <Features> <FirewallService> <IsEnabled>true</IsEnabled> <FirewallRule> <IsEnabled>true</IsEnabled> <Description>FTP Rule</Description> <Policy>allow</Policy> <Protocols> <Tcp>true</Tcp> </Protocols> <Port>21</Port>
72
VMware, Inc.
<DestinationIp>10.147.115.1</DestinationIp> </FirewallRule> <FirewallRule> <IsEnabled>true</IsEnabled> <Description>SSH Rule</Description> <Policy>allow</Policy> <Protocols> <Tcp>true</Tcp> </Protocols> <Port>22</Port> <DestinationIp>10.147.115.1</DestinationIp> </FirewallRule> </FirewallService> <NatService> <IsEnabled>true</IsEnabled> <NatType>ipTranslation</NatType> <Policy>allowTraffic</Policy> <NatRule> <OneToOneVmRule> <MappingMode>manual</MappingMode> <ExternalIp>64.100.10.1</ExternalIp> <VAppScopedVmId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedVmId> <VmNicId>0</VmNicId> </OneToOneVmRule> </NatRule> </NatService> </Features> </Configuration> </NetworkConfig> </NetworkConfigSection>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Linux FTP server (7)" ...> ... </Task>
TheresponseisaTaskelement.
View or Modify vApp Lease Settings

LeasesettingsapplytobothvAppsandvApptemplates,althoughvApptemplatesdonotincludedeployment leaseinformation(DeploymentLeaseInSecondsandDeploymentLeaseExpiration).DefaultvApplease settingsareinheritedfromtheorganizationthatownsthevDCinwhichthevAppisdeployed.Youcan overridethesedefaultsintheInstantiateVAppTemplateParamsrequestbody(seeInstantiatingavApp TemplateUsingAdditionalParametersonpage 62).YoucanviewtheleasesettingsbyretrievingthevAppor vAppTemplaterepresentation.Tomodifythem,usetheeditlinkintheLeaseSettingsSection,as describedinReconfigureavApponpage 69.
Reconfigure a Virtual Machine

Table 52summarizesvirtualmachinereconfigurationrequestssupportedinthisrelease.Thetableusesthe followingconventions:

VMware, Inc.
73
Table 5-3. Summary of Virtual Machine Reconfiguration Requests

Operation Request Request Body None NetworkConnectionSection None GuestCustomizationSection None OperatingSystemSection None VirtualHardwareSection None ovf:Item None Response NetworkConnectionSection Task GuestCustomizationSection Task OperatingSystemSection Task VirtualHardwareSection Task ovf:Item Task ovf:Item
RetrievetheNetworkConnection GETAPIURL/vApp/vmid/ ofaVirtualMachine networkConnectionSection/ ModifytheNetworkConnection ofaVirtualMachine PUTAPIURL/vApp/vmid/ networkConnectionSection/
RetrievetheGuestCustomization GETAPIURL/vApp/vmid/ SectionofaVirtualMachine guestCustomizationSection/ ModifytheGuestCustomization PUTAPIURL/vApp/vmid/ SectionofaVirtualMachine guestCustomizationSection/ RetrievetheOperatingSystem SectionofaVirtualMachine ModifytheOperatingSystem SectionofaVirtualMachine RetrievetheVirtualHardware SectionofaVirtualMachine ModifytheVirtualHardware SectionofaVirtualMachine GETAPIURL/vApp/vmid/ operatingSystemSection/ PUTAPIURL/vApp/vmid/ operatingSystemSection/ GETAPIURL/vApp/vmid/ virtualHardwareSection/ PUTAPIURL/vApp/vmid/ virtualHardwareSection/
RetrievetheCPUConfigurationof GETAPIURL/vApp/vmid/ aVirtualMachine virtualHardwareSection/cpu ModifytheCPUConfigurationof PUTAPIURL/vApp/vmid/ aVirtualMachine virtualHardwareSection/cpu RetrievetheMemoryItemfrom GETAPIURL/vApp/vmid/ theVirtualHardwareSectionofa virtualHardwareSection/memory VirtualMachine ModifytheMemoryItemofthe VirtualHardwareSectionofa VirtualMachine PUTAPIURL/vApp/vmid/ virtualHardwareSection/memory
ovf:Item
Task
RetrieveVirtualDiskItemsfrom GETAPIURL/vApp/vmid/ theVirtualHardwareSectionofa virtualHardwareSection/disks VirtualMachine ModifyVirtualDiskItemsofthe VirtualHardwareSectionofa VirtualMachine PUTAPIURL/vApp/vmid/ virtualHardwareSection/disks
None
RasdItemsList
RasdItemsList
Task
GETAPIURL/vApp/vmid/ RetrieveNetworkCardItems fromtheVirtualHardwareSection virtualHardwareSection/ networkCards ofaVirtualMachine ModifyNetworkCardItemsofthe PUTAPIURL/vApp/vmid/ virtualHardwareSection/ VirtualHardwareSectionofa networkCards VirtualMachine RetrieveRemovableMediaDrive GETAPIURL/vApp/vmid/ ItemsfromtheVirtualHardware virtualHardwareSection/media SectionofaVirtualMachine
None
RasdItemsList
RasdItemsList
Task
None
RasdItemsList
Youcanreconfigureavirtualmachine(Vmelement)bymakingchangestoanyofthefollowingsections:

VirtualHardwareSection OperatingSystemSection NetworkConnectionSection GuestCustomizationSection
Modifiedsectionsmustcontainallrequiredelements,evenifyouarenotchangingtheirvalues.Some elementsinsomesectionsarereadonly.Seetheschemareferencesfordetails.
74
VMware, Inc.
Example 512showsarepresentativecollectionoftheselinks.(Thisexampledoesnotshowtheconfiguration linksfortheparentvApp.Toseethem,refertoExample 59onpage 70.) Example 5-12. Configuration Links for a Vm Request:
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Description>Example FTP Server</Description> ... <Children> <Vm status="8" name="ubuntu10-x86" href="http://vcloud.example.com/api/v1.0/vApp/vm-4" ...> <Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/reboot"/> ... <Link rel="media:ejectMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/ action/ejectMedia"/> <Description/> <ovf:VirtualHardwareSection ... "> <ovf:System> ... </ovf:System> <ovf:Item vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/cpu" ... > ... <rasd:Description>Number of Virtual CPUs</rasd:Description> <rasd:ResourceType>3</rasd:ResourceType> ... <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/cpu"/> </ovf:Item> <ovf:Item vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/memory" ...> ... <rasd:Description>Memory Size</rasd:Description> <rasd:ResourceType>4</rasd:ResourceType> ... <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/memory"/> </ovf:Item> <ovf:Item> ... <rasd:Description>SCSI Controller</rasd:Description> <rasd:ResourceType>6</rasd:ResourceType> ... </ovf:Item> <ovf:Item> ... <rasd:Description>Hard disk</rasd:Description> <rasd:ElementName>Hard disk 1</rasd:ElementName> <rasd:ResourceType>17</rasd:ResourceType> ... </ovf:Item>
VMware, Inc.
75
<Link rel="edit" type="application/vnd.vmware.vcloud.virtualHardwareSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/"/> <Link type="application/vnd.vmware.vcloud.rasdItemsList+xml" rel="edit href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/disks"/> ... <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/networkCards"/> ... </ovf:VirtualHardwareSection> <ovf:OperatingSystemSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ operatingSystemSection/"> ... <Link rel="edit" type="application/vnd.vmware.vcloud.operatingSystemSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ operatingSystemSection/"/> </ovf:OperatingSystemSection> <NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ networkConnectionSection/" ...> <ovf:Info>Specifies the available VM network connections</ovf:Info> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.122.134</IpAddress> <IsConnected>false</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ networkConnectionSection/"/> </NetworkConnectionSection> <GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ guestCustomizationSection/" ovf:required="false"> <ovf:Info>Specifies Guest OS Customization Settings</ovf:Info> <Enabled>false</Enabled> <ChangeSid>false</ChangeSid> <VirtualMachineId>4</VirtualMachineId> <JoinDomainEnabled>false</JoinDomainEnabled> <UseOrgSettings>false</UseOrgSettings> <AdminPasswordEnabled>false</AdminPasswordEnabled> <AdminPasswordAuto>true</AdminPasswordAuto> <ResetPasswordRequired>false</ResetPasswordRequired> <CustomizationScript/> <ComputerName>ubuntu10-x86</ComputerName> <Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml " href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ guestCustomizationSection/"/> </GuestCustomizationSection> <VAppScopedLocalId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedLocalId> </Vm> </Children> </VApp>
76
VMware, Inc.
ReconfigurationlinksinthebodyofaVmcanappearintwoplaces:
IndividualLinkelementsintheovf:Itemelementsdefiningcpuandmemory.Theselinksappearinthe ovf:Itemitself,andhavetype="application/vnd.vmware.vcloud.rasdItem+xml". Linkstogroupsofrelatedovf:Itemelements(disks,networkcards,andmediadevices).Theselinks appearattheendoftheovf:VirtualHardwareSection,andhave type="application/vnd.vmware.vcloud.rasdItemsList+xml".
Retrieve or Modify the Network Connection of a Virtual Machine

Example 513retrievestheNetworkConnectionSectionconfigurationoftheVmshowninExample 512. Example 514modifiesthesectionandusestheURLintheeditlinkfromthatsectiontoapplythechangesto theVm. Example 5-13. Retrieve the Network Connection of a Virtual Machine Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.networkconnectionsection+xml ... <NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ...> <ovf:Info>Specifies the available VM network connections</ovf:Info> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.122.134</IpAddress> <IsConnected>false</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4 networkConnectionSection/"/> </NetworkConnectionSection>
ThemodifiedNetworkConnectionSectionintherequestbodychangesthevalueintheIpAddresselement. Example 5-14. Modify the Network Connection of a Virtual Machine Request:
PUT "http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/ Content-type: application/vnd.vmware.vcloud.networkConnectionSection+xml ... <NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ...> <ovf:Info>Specifies the available VM network connections</ovf:Info> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.115.1</IpAddress> <IsConnected>false</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> </NetworkConnectionSection>
VMware, Inc.
77
Response:
Retrieve or Modify the CPU Configuration of a Virtual Machine

Example 515retrievestheCPUconfigurationoftheVmshowninExample 512. Example 516modifiesthe sectionandusestheURLintheeditlinkfromthatsectiontoapplythechangestotheVm. Example 5-15. Retrieve the CPU Configuration of a Virtual Machine Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/cpu
Response:
200 OK Content-type: application/vnd.vmware.vcloud.rasdItem+xml ... <Item xmlns="http://www.vmware.com/vcloud/v1" xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/ CIM_ResourceAllocationSettingData" ... > <rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits> <rasd:Description>Number of Virtual CPUs</rasd:Description> <rasd:ElementName>1 virtual CPU(s)</rasd:ElementName> <rasd:InstanceID>1</rasd:InstanceID> <rasd:ResourceType>3</rasd:ResourceType> <rasd:VirtualQuantity>1</rasd:VirtualQuantity> </Item>
ThemodifiedItemintherequestbodyaddsasecondCPUtotheVmbychangingtherasd:VirtualQuantity valueoftheItemto2. Example 5-16. Modify the CPU Configuration of a Virtual Machine Request:
PUT http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/cpu Content-type: application/vnd.vmware.vcloud.rasdItem+xml ... <Item xmlns="http://www.vmware.com/vcloud/v1" xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/ CIM_ResourceAllocationSettingData"> <rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits> <rasd:Description>Number of Virtual CPUs</rasd:Description> <rasd:ElementName>1 virtual CPU(s)</rasd:ElementName> <rasd:InstanceID>1</rasd:InstanceID> <rasd:ResourceType>3</rasd:ResourceType> <rasd:VirtualQuantity>2</rasd:VirtualQuantity> </Item>
Response:
78
VMware, Inc.
Retrieve or Modify the Guest Customization Section of a Virtual Machine

Example 517retrievestheGuestCustomizationSectionofaWindowsVm. Example 518modifiesthe sectionandusestheURLintheeditlinkfromthatsectiontoapplythechangestotheVm. Example 5-17. Retrieve the Guest Customization Section of a Virtual Machine Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection
Response:
200 OK Content-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml ... <GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/" ovf:required="false"> <ovf:Info>Specifies Guest OS Customization Settings</ovf:Info> <Enabled>false</Enabled> <ChangeSid>false</ChangeSid> <VirtualMachineId>4</VirtualMachineId> <JoinDomainEnabled>false</JoinDomainEnabled> <UseOrgSettings>false</UseOrgSettings> <AdminPasswordEnabled>false</AdminPasswordEnabled> <AdminPasswordAuto>true</AdminPasswordAuto> <ResetPasswordRequired>false</ResetPasswordRequired> <CustomizationScript/> <ComputerName>ubuntu10-x86</ComputerName> <Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/ guestCustomizationSection/"/> </GuestCustomizationSection>
ThemodifiedGuestCustomizationSectionintherequestbodychangesthevalueofthe JoinDomainEnabledelementtotrue.Thischangerequiresyoutospecifyadomaintojoin,alongwiththe nameandpasswordofadomainadministrator,sotherequestbodyincludesDomainName,DomainUserName, andDomainUserPasswordelements. Example 5-18. Modify the Guest Customization Section of a Virtual Machine Request:
PUT http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection Content-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml ... <GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/" ovf:required="false"> <ovf:Info>Specifies Guest OS Customization Settings</ovf:Info> <Enabled>false</Enabled> <ChangeSid>false</ChangeSid> <VirtualMachineId>4</VirtualMachineId> <JoinDomainEnabled>true</JoinDomainEnabled> <UseOrgSettings>false</UseOrgSettings> <DomainName>EXAMPLE</DomainName> <DomainUserName>admin</DomainUserName> <DomainUserPassword>Pa55w0rd</DomainUserPassword> <AdminPasswordEnabled>false</AdminPasswordEnabled> <AdminPasswordAuto>true</AdminPasswordAuto> <ResetPasswordRequired>false</ResetPasswordRequired> <CustomizationScript/> <ComputerName>ubuntu10-x86</ComputerName>
VMware, Inc.
79
<Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/ guestCustomizationSection/"/> </GuestCustomizationSection>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Win2K3 (12)" ...> ... </Task>
NOTEYoucannotincludeaGuestCustomizationSectionintheInstantiationParamspassedtoaVm duringinstantiation,composition,orrecomposition.Tochangethissection,youmustretrieveitfromaVmand updateit.
View or Modify Groups of Related Sections in a Vm

AsshowninExample 512onpage 75,Linkelementsfordisks,mediadevices,andnetworkcardsaregrouped attheendoftheVirtualHardwareSection.Theselinkshavecontenttype application/vnd.vmware.vcloud.rasdItemsList+xml,andreferenceaRasdItemsListelementinthe VirtualHardwareSectionofaVm.ThevCloudAPIusestheRasdItemsListelementtoaggregaterelated elementsinaVirtualHardwareSection.ThissimplifiesretrievalandmodificationofItemelementsthatare typicallyviewedormodifiedasagroup.Toretrieveoneoftheseelements,usethelinkwhererel="down".To modifyit,usethelinkwhererel="edit". NOTEMediadevicesarereadonly,sotheyhavenorel="edit"link.Formoreinformation,seeListMedia DevicesofaVirtualMachineonpage 85.
Deploying and Controlling vApps and Virtual Machines

AvApporVmbodyreturnedinresponsetoaGET,PUT,orPOSTrequestincludesanumberofactionlinks, whichhavetheformvApporVmURL/action/actionname.Aclientcanuseactionlinkstorequestvarious actionsonthevApp.OnlythoseactionlinksthatarevalidforthevApporvirtualmachineinitscurrentstate arereturned.Forexample,ifavAppisinstantiatedbutnotdeployed,onlythelinksfordeployandremove arereturned.ForavAppthatispoweredon,linksforallactionsexceptpowerOnarereturned(seeExample 28 onpage 27). SomeoftherequestsdocumentedinthissectionapplyonlytovApps,othersapplyonlytovirtualmachines (Vmobjects),andothersapplytoboth.
ArequestmadetoavAppURLinvokestherequestedoperationoneachofthevirtualmachinesinthe ChildrenelementofthevApp,intheorderspecifiedinitsovf:StartupSectionelement.Thiselement, ifpresent,specifiesastartorderandrelatedpropertiesforeachmemberofaVirtualSystemCollection (eachVmintheChildrencollection).Iftheelementisnotpresent,allmembersarestartedupatthesame time.Thesamelogicappliestoshutdown,reboot,andsimilaroperations.Formoreinformation,seethe OVFspecification,availableat http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf. ArequestmadetoaVmURLaffectsonlythatvirtualmachine.
Deploy a vApp or Virtual Machine

TodeployavApp,theclientmakesarequesttoitsaction/deployURL.DeployingavAppautomatically deploysallofthevirtualmachinesitcontains. Todeployavirtualmachine,theclientmakesarequesttoitsaction/deployURL.DeployingaVmimplicitly deploystheparentvAppifthatvAppisnotalreadydeployed. TherequestbodyineachcaseisaDeployVAppParamselement.
80 VMware, Inc.
Example 5-19. Deploy and Power On a vApp or Virtual Machine Request:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deploy Content-type: application/vnd.vmware.vcloud.deployVAppParams+xml ... <DeployVAppParams powerOn="true" xmlns="http://www.vmware.com/vcloud/v1"/>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Starting Virtual Application Linux FTP server (7) ...> ... </Task>
Undeploy a vApp or Virtual Machine

UndeployingavApppowersofforsuspendsanyrunningvirtualmachinesitcontains,thenfreesthe resourcesreservedforthevAppandsetsthevAppsdeployedattributetoavalueoffalsetoindicatethatit isnotdeployed. Undeployingavirtualmachinepowersofforsuspendsthevirtualmachine,thenfreestheresourcesreserved foritandsetstheitsdeployedattributetoavalueoffalsetoindicatethatitisnotdeployed.Thisoperation hasnoeffectonthecontainingvApp. ThesaveStateattributespecifieswhethertheundeployedvirtualmachinesaresuspendedandtheirsuspend statesaved,orsimplypoweredoff. TherequestbodyineachcaseisanUndeployVAppParamselement. Example 5-20. Undeploy a vApp or Virtual Machine RequesttoundeployavApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/undeploy Content-type: application/vnd.vmware.vcloud.undeployVAppParams+xml ... <UndeployVAppParams saveState="true" xmlns="http://www.vmware.com/vcloud/v1"/>
RequesttoundeployaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/action/undeploy Content-type: application/vnd.vmware.vcloud.undeployVAppParams+xml ... <UndeployVAppParams saveState="true" xmlns="http://www.vmware.com/vcloud/v1"/>
Response:
Power On a vApp or Virtual Machine

ApowerOnrequesttoavAppURLpowersonallofthevirtualmachinesinthevApp,asspecifiedinthevApps ovf:StartupSectionelement. ApowerOnrequesttoavirtualmachineURLpowersonthespecifiedvirtualmachineandforcesdeployment oftheparentvApp.
VMware, Inc.
81
ApowerOnrequesttoavApporvirtualmachinethatisundeployedforcesdeployment. Example 5-21. Power On a vApp or Virtual Machine RequesttopoweronavApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOn
Requesttopoweronavirtualmachine:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOn
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Starting Virtual Application Linux FTP server (7) ...> ... </Task>
Power Off a vApp or Virtual Machine

ApowerOffrequesttoavAppURLpowersoffallofthevirtualmachinesinthevApp,asspecifiedinits ovf:StartupSectionelement. ApowerOffrequesttoavirtualmachineURLpowersoffthespecifiedvirtualmachine. Example 5-22. Power Off a vApp or Virtual Machine RequesttopoweroffavApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOff
Requesttopoweroffavirtualmachine:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOff
Response:
202 Accepted ... Content-Type: application/vnd.vmware.vcloud.task+xml <Task ...> ... </Task>
Reset a vApp or Virtual Machine

AresetrequesttoavAppURLresetsallofthevirtualmachinesinthevApp,asspecifiedinits ovf:StartupSectionelement. AresetrequesttoavirtualmachineURLresetsthespecifiedvirtualmachine. Example 5-23. Reset a vApp or Virtual Machine RequesttoresetavApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reset
RequesttoresetaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/reset
82
VMware, Inc.
Response:
Suspend a vApp or Virtual Machine

AsuspendrequesttoavAppURLsuspendsallofthevirtualmachinesinthevApp,asspecifiedinits ovf:StartupSectionelement. AsuspendrequesttoavirtualmachineURLsuspendsthespecifiedvirtualmachine. Example 5-24. Suspend a vApp or Virtual Machine RequesttosuspendavApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/suspend
RequesttosuspendaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/suspend
Response:
Discard the Suspended State of a vApp or Virtual Machine

AdiscardSuspendedStaterequesttoavAppURLdiscardsthesuspendedstateofallofthevirtualmachines inthevApp,asspecifiedinitsovf:StartupSectionelement. AdiscardSuspendedStaterequesttoavirtualmachineURLdiscardsthesuspendedstateofthespecified virtualmachine. YoucannotresumeasuspendedvAppafteritssuspendedstatehasbeendiscarded. Example 5-25. Discard the Suspended State of a vApp or Virtual Machine RequesttodiscardthesuspendedstateofavApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/discardSuspendedState
RequesttodiscardthesuspendedstateofaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/action/discardSuspendedState
Response:
VMware, Inc.
83
Shut Down a vApp or Virtual Machine

AshutdownrequesttoavAppURLshutsdownallofthevirtualmachinesinthevApp,asspecifiedinits ovf:StartupSectionelement. AshutdownrequesttoavirtualmachineURLshutsdownthespecifiedvirtualmachine. NOTEBecausethisrequestsendsasignaltotheguestOS,thevCloudAPIcannottracktheprogressorverify theresultoftherequestedoperation. Example 5-26. Shut Down a vApp or Virtual Machine RequesttoshutdownavApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/shutdown
RequesttoshutdownaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/shutdown
Response:
204 No Content
Reboot a vApp or Virtual Machine

ArebootrequesttoavAppURLrebootsallofthevirtualmachinesinthevApp,asspecifiedinits ovf:StartupSectionelement. ArebootrequesttoavirtualmachineURLrebootsthespecifiedvirtualmachine. NOTEBecausethisrequestsendsasignaltotheguestOS,thevCloudAPIcannottracktheprogressorverify theresultoftherequestedoperation. Example 5-27. Reboot a vApp or Virtual Machine RequesttorebootavApp:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reboot
RequesttorebootaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/reboot
Response:
204 No Content
84
VMware, Inc.
List Media Devices of a Virtual Machine

YoucanmakeaGETrequesttothemediaURLofaVmtoreturnalistofallmediadevicesattachedtoit. Example 5-28. List Media Devices Attached to a Vm Request:
GET http://vcloud.example.com/api/v1.0/vapp/vm-5/virtualHardwareSection/media
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.rasditemslist+xml ... <RasdItemsList xmlns="http://www.vmware.com/vcloud/v1" ... href="http://vcloud.example.com/api/v1.0/vApp/vm-5/virtualHardwareSection/media" ... > <Item> <rasd:Address>0</rasd:Address> <rasd:Description>IDE Controller</rasd:Description> <rasd:ElementName>IDE Controller 0</rasd:ElementName> <rasd:InstanceID>1</rasd:InstanceID> <rasd:ResourceType>5</rasd:ResourceType> </Item> <Item> <rasd:AddressOnParent>0</rasd:AddressOnParent> <rasd:Description>CD/DVD Drive</rasd:Description> <rasd:ElementName>CD/DVD Drive 1</rasd:ElementName> <rasd:HostResource xmlns:vcloud="http://www.vmware.com/vcloud/v1" vcloud:connected="false"></rasd:HostResource> <rasd:InstanceID>3000</rasd:InstanceID> <rasd:Parent>1</rasd:Parent> <rasd:ResourceType>15</rasd:ResourceType> </Item> <Item> <rasd:AddressOnParent>0</rasd:AddressOnParent> <rasd:Description>Floppy Drive</rasd:Description> <rasd:ElementName>Floppy Drive 1</rasd:ElementName> <rasd:HostResource xmlns:vcloud="http://www.vmware.com/vcloud/v1" vcloud:connected="false"></rasd:HostResource> <rasd:InstanceID>8000</rasd:InstanceID> <rasd:ResourceType>14</rasd:ResourceType> </Item> </RasdItemsList>
Insert Media Into a Virtual Machine

AninsertMediarequestmakesavirtualmediaimagereadablebyaVm.Therequestmustspecifythe insertMediaURLofaVm.TheMediaelementintherequestbodymustspecifythehrefofthemediaimage toinsert.WhenprocessinganinsertMediarequest,theserverexaminesthetypeofthemediaspecifiedinthe requestandthenattemptstoinsertitinadeviceoftheappropriatetype,startingwiththedevicethathasthe lowestbusnumberandlowestaddressonthatbus. Example 5-29. Insert Media Into a Virtual Machine Request:
POST http://vcloud.example.com/api/v1.0/vapp/vm-5/media/action/insertMedia Content-Type: application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml <MediaInsertOrEjectParams xmlns="http://www.vmware.com/vcloud/v1"> <Media href="http://vcloud.example.com/api/v1.0/media/3"/> </MediaInsertOrEjectParams>
VMware, Inc.
85
Response:
Eject Media from a Virtual Machine

AnejectMediarequestreversesaspecificinsertMedia request.TherequestmustspecifytheejectMedia URLofaVmthatwaspreviouslythetargetofaninsertMedia request.TheMediaelementintherequestbody mustspecifythehrefofthemediaimagethatwasinsertedbythatrequest. Example 5-30. Eject Media from a Virtual Machine Request:
POST http://vcloud.example.com/api/v1.0/vapp/vm-5/media/action/ejectMedia Content-Type: application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml <MediaInsertOrEjectParams xmlns="http://www.vmware.com/vcloud/v1"> <Media href="http://vcloud.example.com/api/v1.0/media/3"/> </MediaInsertOrEjectParams>
Response:
Get a Screen Thumbnail for a Virtual Machine

Ascreenrequestreturnsathumbnailviewofavirtualmachinesconsoleencodedinpngformat. Example 5-31. Get a Screen Thumbnail for a Virtual Machine Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-4/screen
Response:
200 OK Content-type image/png ...
...serializedcontentsofthumbnailinpngformat... EOF
86
VMware, Inc.
Get a Screen Ticket for a Virtual Machine

AnacquireTicketrequestreturnsaticketthataclientcanusetogainaccesstotheconsoleofavirtual machine. Example 5-32. Get a Screen Ticket for a Virtual Machine Request:
POST http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/action/acquireTicket
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.screenTicket+xml ... <ScreenTicket xmlns="http://www.vmware.com/vcloud/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...> mks://10.147.43.171/vm-61?ticket=Pznh4HMb7k%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3 SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O </ScreenTicket>
Provide User Input Requested by a Virtual Machine

Arequestforavirtualmachinetochangestate(poweron,suspend,reconfigure,andsoon)mightcausethe virtualmachinetoaskforadditionaluserinputbeforeitcancomplete.AvAppthatcontainsaVmawaitinga userresponsehasstatus="5",andincludesalinkwithrel="down"and type="application/vnd.vmware.vcloud.vmPendingQuestion+xml"thataclientcanGETtodiscover whatinputisneeded.Inthisseriesofexamples,avirtualmachinethatwasrecentlyreconfiguredinvCenter toaddanewparallelportdeviceandthenpoweredonisrequestinguserinputaboutwheretosendoutput fromthedevice.ThepowerOnrequestcannotcompleteuntilthisinputissupplied. Example 533showsthelinktothequestion,inthebodyofthevApp. Example 5-33. vApp Requesting Input Request:
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Linux FTP server" status="5" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> ... <Link rel="down" type="application/vnd.vmware.vcloud.vmPendingQuestion+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-5/question"/> ... <Description>Example FTP Server</Description> ... <Children> ... </Children> </vApp>
VMware, Inc.
87
Get a Request for User Input

InExample 534,theclientusesthevmPendingQuestionlinkreturnedinExample 533togeta VmPendingQuestiondocumentthatincludesthequestionandthesetofchoicesallowedintheresponse. Example 5-34. Get a Vm Pending Question Request:
GET http://vcloud.example.com/api/v1.0/vApp/vm-5/question
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vmPendingQuestion+xml ... <VmPendingQuestion xmlns="http://www.vmware.com/vcloud/v1" ... > <Link type="application/vnd.vmware.vcloud.vmPendingAnswer+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-5/question/action/answer"/> <Question>msg.parallel.file.open:Parallel port output file "/vmfs/volumes/d6162a46-58e50cab/linuxftp/vm-mgi.log" already exists. Do you want to replace it with any newly created content, or append new content to the end of the file? </Question> <QuestionId>50</QuestionId> <Choices> <Id>0</Id> <Text>Append</Text> </Choices> <Choices> <Id>1</Id> <Text>Replace</Text> </Choices> <Choices> <Id>2</Id> <Text>Cancel</Text> </Choices> </VmPendingQuestion>
Provide Requested User Input

Example 535showsthearesponse,deliveredbyaPOSTtothequestion/answerlinkoftheVm. Example 5-35. Answer a Vm Pending Question Request:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/question/action/answer Content-type: application/vnd.vmware.vcloud.vmPendingAnswer+xml ... <VmQuestionAnswer xmlns="http://www.vmware.com/vcloud/v1"> <ChoiceId>2</ChoiceId> <QuestionId>50</QuestionId> </VmQuestionAnswer>
Response:
204 No Content
88
VMware, Inc.
Control Access to vApps

AccesscontrollinksforvAppsareincludedinthevAppbody.Example 536,anexcerptfromExample 28on page 27,showstheselinks. Example 5-36. Access Control Links for a vApp
<vApp ... > ... <Link rel="down" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/controlAccess/"/> <Link rel="controlAccess" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/controlAccess/"/> ... </vApp>
AnorganizationadministratorcanusetheselinksinthesamekindsofrequestsshowninControlAccessto Catalogsonpage 56.
Retrieve a Task
Whenevertheresultofarequestcannotbereturnedimmediately,theservercreatesaTaskobjectandincludes itintheresponse,asamemberoftheTaskscontainerintheresponsebody.EachTaskhasanhrefvalue, whichisaURLthattheclientcanusetoretrievetheTaskelementalone,withouttherestoftheresponsein whichitwascontained.AllinformationaboutthetaskisincludedintheTaskelementwhenitisreturnedin theresponsesTaskscontainer,soaclientdoesnotneedtomakeanadditionalrequesttotheTaskURLunless itwantstofollowtheprogressofataskthatwasincomplete. Example 537retrievesthattaskthatwasreturnedintheresponseinExample 26onpage 25. Example 5-37. Retrieve a Task Request:
GET http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task status="running" startTime="2010-06-25T08:00:55.402-07:00" operation="Creating Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey"> <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/> </Task>
Tasksexpireafteraconfigurableinterval.Thedefaultintervalis24hours.
VMware, Inc.
89
90
VMware, Inc.
Administrative Operations
TheVMwarevCloudAPIsupportsavarietyofobjectsandoperationsthatanorganizationadministratoror otherprivilegedusercanusetoautomatetasksassociatedwithprovisioningorganizationsandusers,and withallocationofresourcestoorganizationvDCs. Thischapterincludesthefollowingtopics:

SummaryofAdministrativeRequestsonpage 91 AdministratorCredentialsandPrivilegesonpage 93 AdministrativeObjectsandURLsonpage 93 GetanAdministrativeViewofaCloudonpage 93 OrganizationAdministrationonpage 94 NetworkAdministrationonpage 99 vDCAdministrationonpage 102 CatalogAdministrationonpage 107 UserAdministrationonpage 110 GroupAdministrationonpage 113 RoleAdministrationonpage 114
Summary of Administrative Requests

Table 61summarizesadministrativerequestssupportedinthisrelease.Thetableusesthefollowing conventions:

Table 6-1. Summary of Administrative Requests

Operation GetanAdministrativeViewofa Cloud CreateanOrganization GetanAdministrativeViewofan Organization ModifyanOrganization ListAllTasksOwnedbyan Organization Request GETAPIURL/admin POSTAPIURL/admin/orgs GETAPIURL/admin/org/id PUTAPIURL/admin/org/id GETAPIURL/tasksList/id Request Body None AdminOrg None AdminOrg None Response VCloud AdminOrg AdminOrg AdminOrg TasksList
VMware, Inc.
91
Table 6-1. Summary of Administrative Requests (Continued)

Operation AddaNetworktoanOrganization GetanAdministrativeViewofan OrganizationNetwork ModifyanOrganizationNetwork RemoveanOrganizationNetwork EnableorDisableanOrganization Request POSTAPIURL/admin/org/id/networks GETAPIURL/admin/network/id PUTAPIURL/admin/network/id DELETEAPIURL/admin/network/id POSTAPIURL/admin/org/id/ action/enable POSTAPIURL/admin/org/id/ action/disable DELETEAPIURL/admin/org/id GETAPIURL/admin/providervdc/id POSTAPIURL/admin/org/id/vdcs GETAPIURL/admin/providervdc/id/ vdcReferences GETAPIURL/admin/vdc/id PUTAPIURL/admin/vdc/id POSTAPIURL/admin/vdc/id/ action/enable POSTAPIURL/admin/vdc/id/ action/disable DELETEAPIURL/admin/vdc/id POSTAPIURL/admin/org/id/catalogs GETAPIURL/admin/catalog/id POSTAPIURL/admin/catalog/id/ action/publish PUTAPIURL/admin/catalog/id DELETEAPIURL/admin/catalog/id POSTAPIURL/admin/org/id/users GETAPIURL/admin/user/id PUTAPIURL/admin/user/id DELETEAPIURL/admin/user/id POSTAPIURL/admin/org/id/groups GETAPIURL/admin/groupid PUTAPIURL/admin/group/id DELETEAPIURL/admin/group/id POSTAPIURL/admin/roles GETAPIURL/admin/role/id PUTAPIURL/admin/role/id DELETEAPIURL/admin/role/id GETAPIURL/admin/right/id Request Body OrgNetwork None OrgNetwork None None Response OrgNetwork OrgNetwork Task Task 204NoContent
RemoveanOrganization ExaminetheContentsofaProvider vDC AllocateavDCtoanOrganization ListtheOrganizationvDCs SupportedbyaProvidervDC GetanAdministrativeViewofavDC ModifyavDC EnableorDisableavDC
None None AdminVdc None None AdminVdc None
None ProviderVdc AdminVdc VdcReferences AdminVdc AdminVdc 204NoContent
RemoveavDC CreateaCatalog GetanAdministrativeViewofa Catalog PublishaCatalog ModifyCatalogMetadata RemoveaCatalog CreateorImportaUser GetanAdministrativeViewofaUser ModifyUserMetadata RemoveaUser ImportaGroup ViewGroupMetadata ModifyGroupMetadata RemoveaGroup CreateaRole ViewRoleMetadata ModifyaRole RemoveaRole ViewaRight
None Catalog None PublishCatalogParams Catalog None User None User None Group None Group None Role None Role None None
Task Catalog Catalog 204NoContent Catalog 204NoContent User User User 204NoContent Group Group Group 204NoContent Role Role Role 204NoContent Right
92
VMware, Inc.
Chapter 6 Administrative Operations
Administrator Credentials and Privileges

ThevCloudAPIdefinestwolevelsofadministrativeprivilege:

Organizationadministrators,whohaveadministrativeprivilegesinaspecificorganization. Systemadministrators,whohavesuperuserprivilegesthroughoutthesystem.Systemadministratorscan create,read,update,anddeleteallobjectsinavCloud,andhaveorganizationadministratorrightsinall organizationsinavCloud,andcanoperatedirectlyonvSphereresourcestocreateandmodifyprovider vDCs.
Someadministrativeoperations(andallvSphereplatformoperations)arerestrictedtothesystem administrator.Beforeattemptinganyoftheseoperations,logintotheSystemorganizationwiththeusername andpasswordofthesystemadministratoraccountthatwascreatedwhenvCloudServiceDirectorwas installed.Forexample,ifthesystemadministratorsnameandpasswordhadbeendefinedasadministrator andPa55w0rd,thesystemadministratorlogincredentialswouldbetheMIMEBase64encodingofthestring administrator@System:Pa55w0rd. TheSystemorganizationiscreatedautomaticallywhenvCloudServiceDirectorisinstalled,andalwayshasa URLoftheformAPIURL/org/1.ItisnotlistedinanOrgList,butcanberetrievedwithanexplicitGET request,asshowninExample 61. Example 6-1. The System Organization Request:
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... <Org xmlns="http://www.vmware.com/vcloud/v1" name="System" ...> ... </Org>
Administrative Objects and URLs

ThevCloudAPIdefinesseveralobjectsthatareusedonlyinadministrativeoperations.Theseobjectsarelisted inChapter 11,AdministrativeAPIReference,onpage 179.Some,likeUser,Group,andRoleareuniqueto administrativeoperations.OthersextendcommonvCloudAPIobjectstoaddelementsandattributesthat enableadministrativecontrol.AnAdminOrg,forexample,supportstheadministrativeviewofanOrg,andan AdminVdcdoesthesamethingforaVdc.
Get an Administrative View of a Cloud

AnadministratorcanaccessacloudwidenamespaceofadministrativeobjectsatAPIURL/admin,where APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0.Theprimaryadministrativeobjectsina vCloudincludeorganizations,providervDCs,rights,roles,andexternalnetworks.Eachobjecttypeis representedinaVCloudelementbyzeroormorereferences,asillustratedinExample 62.Asystem administratorcanobtainmoreinformationaboutanyoftheseobjectsbymakingaGETrequesttotheobject reference(thevalueofitshrefattribute). ThevCloudresponsedocumentincludeslinksthatenableasystemadministratortoaddrolesand organizations.Subordinateobjectssuchasusers,catalogs,andvDCs,arecontainedbyindividual organizationsandarenotlistedatthislevel.Otherobjects,suchasrights,canbelistedbutcannotbemodified usingthevCloudAPI.
VMware, Inc.
93
Example 6-2. List the Top-Level Administrative Objects in a vCloud Request:

GET http://vcloud.example.com/api/v1.0/admin
Response:
200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml ... <VCloud name="vCloud" href="http://vcloud.example.com/api/v1.0/admin" ...> <Link rel="add" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/roles"/> <Link rel="add" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/orgs"/> <Description>Example Corporations vCloud</Description> <OrganizationReferences> <OrganizationReference type="application/vnd.vmware.admin.organization+xml" name="Engineering" href="http://vcloud.example.com/api/v1.0/admin/org/44"/> <OrganizationReference ... /> ... </OrganizationReferences> <ProviderVdcReferences> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <ProviderVdcReference ... /> ... </ProviderVdcReferences> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml name="vApp_Deploy" href="http://vcloud.example.com/api/v1.0/admin/right/3"/> <RightReference type="application/vnd.vmware.admin.right+xml name="Catalog: Sharing" href="http://vcloud.example.com/api/v1.0/admin/right/7"/> <RightReference ... /> ... </RightReferences> <RoleReferences> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Organization Administrator" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Catalog Creator" href="http://vcloud.example.com/api/v1.0/admin/role/103"/> <RoleReference ... /> ... </RoleReferences> <Networks> <Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC2" href="http://vcloud.example.com/api/v1.0/admin/network/33"/> <Network ... /> ... </Networks> </VCloud>
Organization Administration
AnAdminOrgisanextendedrepresentationofanOrgobject,andisaccessedatAPIURL/admin/org/id, ratherthanAPIURL/org/id.AlthoughsystemadministratorsworkwithAdminOrgelementstocreateand modifyorganizations,mostmodificationstoanAdminOrgalsomodifysomeuservisiblepropertyofthe correspondingOrg.
94
VMware, Inc.
Create an Organization
Tocreateanorganization,asystemadministratorPOSTsanAdminOrgbodytothevCloudsorgsURL,as showninExample 63. Theresponseechoestherequest,withseveralimportantadditions:
ItincludesboththeadministrativeanduserURLsfortheneworganization.TheadministrativeURLis thevalueofthehrefelementoftheAdminOrgbody,andtheuserURListhevalueoftheLinkwhere rel="alternate". Itincludeslinksthatanadministratorcanusetomodifyorremovetheneworganization.Forexample, anadministratorcouldusethisLinktoaddacatalog.

<Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/>
Example 6-3. Create an Organization Request:

POST http://vcloud.example.com/api/v1.0/admin/orgs Content-Type: application/vnd.vmware.admin.organization+xml ... <AdminOrg xmlns="http://www.vmware.com/vcloud/v1" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml"> <Description>Example Corporations Finance Organization</Description> <FullName>Finance</FullName> <Settings> <CanPublishCatalogs>true</CanPublishCatalogs> <DeployedVMQuota>0</DeployedVMQuota> <StoredVmQuota>0</StoredVmQuota> <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>false</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>604800</DeploymentLeaseSeconds> <StorageLeaseSeconds>2592000</StorageLeaseSeconds> </OrgLeaseSettings> <OrgLdapMode>SYSTEM</OrgLdapMode> <OrgEmailSettings> <IsDefaultSmtpServer>true</IsDefaultSmtpServer> <IsDefaultOrgEmail>true</IsDefaultOrgEmail> <FromEmailAddress>Admin@example.com</FromEmailAddress> <DefaultSubjectPrefix>Attention</DefaultSubjectPrefix> <IsAlertEmailToAllAdmins>true</IsAlertEmailToAllAdmins> <SmtpServerSettings> <IsUseAuthentication>true</IsUseAuthentication> <Host>smtp.example.com</Host> <Username>admin@smtp.example.com</Username> </SmtpServerSettings> </OrgEmailSettings> </Settings> </AdminOrg>
Response:
201 Created Content-Type: application/vnd.vmware.admin.organization+xml ... <AdminOrg xmlns="http://www.vmware.com/vcloud/v1" href="http://vcloud.example.com/api/v1.0/admin/org/26" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml"> <Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/26"/> <Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/> <Link rel="add" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/users"/> <Link rel="add" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/groups"/>
VMware, Inc.
95
<Link rel="add" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/vdcs"/> <Link rel="add" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/networks"/> <Link rel="edit" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/org/26/action/disable"/> <Link rel="alternate" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/26"/> <Description>Example Corporations Finance Organization</Description> <FullName>Finance</FullName> <Settings> <IsEnabled>false</IsEnabled> <CanPublishCatalogs>true</CanPublishCatalogs> <DeployedVMQuota>0</DeployedVMQuota> <StoredVmQuota>0</StoredVmQuota> <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>false</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>604800</DeploymentLeaseSeconds> <StorageLeaseSeconds>2592000</StorageLeaseSeconds> </OrgLeaseSettings> <OrgLdapMode>SYSTEM</OrgLdapMode> <OrgEmailSettings> <IsDefaultSmtpServer>true</IsDefaultSmtpServer> <IsDefaultOrgEmail>true</IsDefaultOrgEmail> <FromEmailAddress>Admin@example.com</FromEmailAddress> <DefaultSubjectPrefix>Attention</DefaultSubjectPrefix> <IsAlertEmailToAllAdmins>true</IsAlertEmailToAllAdmins> <SmtpServerSettings> <IsUseAuthentication>true</IsUseAuthentication> <Host>smtp.example.com</Host> <Username>admin@smtp.example.com</Username> </SmtpServerSettings> </OrgEmailSettings> </Settings> </AdminOrg>
Get an Administrative View of an Organization

Toseeanadministrativeviewofanorganization,anadministratorcanmakeaGETrequesttothe organizationsadminURL(thehrefelementoftheAdminOrgbody),asshowninExample 64.Withthe exceptionoftheHTTPresponsecode(200OKinsteadof201Created),theresponsetothisrequestisidentical totheonereturnedinExample 63,soweomitmostofitfromtheexample. Example 6-4. Get an Administrative View of an Organization Request:
GET http://vcloud.example.com/api/v1.0/admin/org/26
Response:
200 OK Content-Type:application/vnd.vmware.admin.organization+xml ... <AdminOrg xmlns="http://www.vmware.com/vcloud/v1" href="http://vcloud.example.com/api/v1.0/admin/org/26" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml"> <Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/26"/> <Description>Example Corporations Finance Organization</Description>
96
VMware, Inc.
<FullName>Finance</FullName> ... <Settings> ... </Settings> </AdminOrg>
List All Tasks Owned by an Organization

AnadministrativeviewofanorganizationincludesaLinkwitharel="down"attributethattheadministrator canusetoretrievealistofalltasksownedbyauserorobjectinanorganization.TherequestinExample 65 usesthetasksListURLreturnedinExample 64toreturnaTasksListelementthatcontainsseveralTask elements. Example 6-5. List All Tasks Owned by an Organization Request:
GET http://vcloud.example.com/api/v1.0/tasksList/26
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.tasksList+xml ... <TasksList name="Tasks Lists" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/18" ...> <Task... status="success" ... operation="Deleted Virtual Application Template (21)" ... > ... </Task> <Task... status="error" ... operation="Powered On Virtual Machine WIn2K8 (15)" ... > <Error stackTrace="com.vmware.ssdc.library.exceptions.VimInvalidStateException The operation could not be performed because the object is in an invalid state. Current state of the the VM is VMOn. at com.vmware.vcloud.val.internal.impl.VC20VirtualServer.throwVimInvalidStateE xception(VC20VirtualServer.java:292) at ..."> ... </Task> <Task... status="running" ... operation="Deleting Virtual Application (44)" ... > ... </Task> ... </TasksList>
Modify an Organization
AsshowninExample 63,anAdminOrgbodyincludesrel="add"linksfornetworks,vDCs,users,groups, andcatalogs.Anorganizationadministratorcanusetheselinkstoaddobjectsofthosetypestothe organization.TomodifyotherattributesorelementsofanAdminOrg,anorganizationadministratorcanmake aPUTrequesttoitsrel="edit"linkandsupplyamodifiedversionoftheAdminOrgbody.Therequestin Example 66modifiesthedefaultleasesettingsoftheorganizationcreatedinExample 63. NOTEIfyoumodifyanorganizationscatalogpublishingpolicyorLDAPoptionsormodifyarole,the changesdonottakeeffectforloggedinusersuntilthecacheforthecurrentsessionexpiresortheuserlogs outandlogsinagain.
VMware, Inc.
97
Example 6-6. Modify an Organization Request:

PUT http://vcloud.example.com/api/v1.0/admin/org/26 Content-Type: application/vnd.vmware.admin.organization+xml ... <AdminOrg xmlns="http://www.vmware.com/vcloud/v1" name="ExampleFinance"> <Description>Example Corporations Finance Organization</Description> <FullName>Finance</FullName> <Settings> <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>true</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>1209600</DeploymentLeaseSeconds> <StorageLeaseSeconds>7776000</StorageLeaseSeconds> </OrgLeaseSettings> <OrgLdapMode>SYSTEM</OrgLdapMode> </Settings> </AdminOrg>
Response:
200 OK Content-Type: application/vnd.vmware.admin.organization+xml ... <AdminOrg name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml" ...> <Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/> <Link rel="add" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/users"/> ... <Settings> ... <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>true</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>1209600</DeploymentLeaseSeconds> <StorageLeaseSeconds>7776000</StorageLeaseSeconds> </OrgLeaseSettings> </Settings> ... </AdminOrg>
Enable or Disable an Organization

AnadministratorcanusetheenableordisableactionlinksinanAdminOrgbodytoenableordisablean organization,asshowninExample 67.TheenablementstateoftheAdminOrgisshowninitsIsEnabled element. Example 6-7. Disable an Organization Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/action/disable
Response:
204 No Content
98
VMware, Inc.
Remove an Organization
AnorganizationadministratorcanusetheremovelinkinanAdminOrgbodytoremovetheorganizationfrom thevCloud.Example 68doesthis,makingaDELETErequesttotheremovelinkreturnedinExample 64. NOTEBeforeyoucanremoveanorganization,youmustdisableitanddeleteorchangeownershipofall objectsthattheorganizationusersown. Example 6-8. Remove an Organization Request:
DELETE http://vcloud.example.com/api/v1.0/admin/org/26
Response:
204 No Content
Network Administration
Anewlycreatedorganizationhasnonetworksinit.Anorganizationadministratormustcreatean organizationnetworkfromresourcesprovidedbyoneoftheexternalnetworkslistedintheNetworkselement oftheVCloudresponse(seeExample 62onpage 94).
View the Properties of an External Network

Tocreateanorganizationnetwork,andorganizationadministratormustchooseaparentnetworkfromoneof thenetworksgroupedintheNetworkselementofthecloud.Togetmoreinformationaboutanyofthese networks,anadministratorcanmakeaGETrequesttothenetworksURL(thehrefelementoftheNetwork element).Example 69makessucharequesttothehrefofaNetworkelementreturnedinExample 62on page 94.TheresponseisanExternalNetworkelementthatshowstheConfigurationandotherproperties ofthenetwork,includingaProviderInfoelementthatspecifiesdetailsoftheunderlyingvSpherenetwork. TheExternalNetworkelementisreadonly. Example 6-9. View the Properties of an External Network Request:
GET http://vcloud.example.com/api/v1.0/admin/network/7
Response:
200 OK Content-Type:pplication/vnd.vmware.admin.network+xm ... <ExternalNetwork xmlns="http://www.vmware.com/vcloud/v1" href="http://vcloud.example.com/api/v1.0/admin/network/7" name="ExternalNetwork-VC1" ...> <Description>VLAN 7</Description> <Configuration> ... </Configuration> <ProviderInfo> NETWORK:dvportgroup-1587 on com.vmware.vcloud.entity.vimserver:1043863313 </ProviderInfo> </ExternalNetwork>
VMware, Inc.
99
Add a Network to an Organization

Anadministratorcanusetherel="add"linkfornetworksinanAdminOrgbodytoaddanetworktothe organization.Example 610doesthisbymakingaPOSTrequesttothenetworkslinkreturnedinExample 64. ThecontentoftheFenceModeelementintherequestbodyspecifiesthatorganizationnetworkisbridgedto itsParentNetwork,whosehrefvaluewasretrievedfromoneoftheNetworkelementsintheresponsein Example 62. NOTEANetworkPoolelementmustbeincludedintherequestwhencreatingnetworkwhoseFenceModeis natRoutedorisolated. Example 6-10. Add a Network to an Organization Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/networks Content-Type: application/vnd.vmware.admin.network+xml ... <OrgNetwork name="Internet" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Bridged to the public Internet</Description> <Configuration> <ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <FenceMode>bridged</FenceMode> </Configuration> </OrgNetwork>
Response:
201 Created Content-Type: application/vnd.vmware.admin.network+xm ... <OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54" ...> <Link rel="alternate" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54"/> <Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0//org/26"/> <Description>Bridged to the public Internet</Description> <Tasks> <Task ... operation="Creating Network Internet (2)" ... > ... </Task> </Tasks> <Configuration> <IpScope> <IsInherited>true</IsInherited> <Gateway>10.147.122.190</Gateway> <Netmask>255.255.255.192</Netmask> <Dns1>10.115.120.71</Dns1> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.122.129</StartAddress> <EndAddress>10.147.122.189</EndAddress> </IpRange> </IpRanges> <AllocatedIpAddresses/> </IpScope>
100
VMware, Inc.
<ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <FenceMode>bridged</FenceMode> </Configuration> </OrgNetwork>
Theresponseechoestherequest,andcontainssomeadditionalelements:

ATaskthattrackscreationofthenetwork. AdditionalmembersoftheConfigurationelementthatareinheritedfromtheorganizationsdefaults, becausetheywerenotspecifiedintherequest.
ThesamerequestwithadifferentvalueforFenceModecontentswouldcreateanetworkwithadifferenttype ofconnectiontotheparent.Formoreinformation,seeFenceModeonpage 155.
Get an Administrative View of an Organization Network

Toseeanadministrativeviewofanorganizationnetwork,anadministratorcanmakeaGETrequesttothe networksadminURL(thehrefelementoftheOrgNetworkbody),asshowninExample 611.Theresponse, mostofwhichisnotshownhere,wouldbeidenticaltotheoneshowninExample 610,butwithouttheTasks element. Example 6-11. Get an Administrative View of an Organization Network Request:
GET http://vcloud.example.com/api/v1.0/admin/network/54
Response:
200 OK Content-Type: application/vnd.vmware.admin.network+xm ... <OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet" type="application/vnd.vmware.admin.network+xml" ref="http://vcloud.example.com/api/v1.0/admin/network/54" ...> ... <Description>Bridged to the public Internet</Description> ... </OrgNetwork>
Modify an Organization Network

Anadministratorcanusetherel="edit"linkinanOrgNetworkbodytomodifythenetworksname, description,orconfiguration.Example 612doesthisbymakingaPUTrequesttotherel="edit"link returnedinExample 610.TherequestmodifiesthenetworksFenceModeelementandaddselementstothe ConfigurationtodefinetheNATservicebeingaddedtothenetwork. Example 6-12. Modify a Network Request:
PUT http://vcloud.example.com/api/v1.0/admin/network/54 Content-Type: application/vnd.vmware.admin.network+xml ... <OrgNetwork name="Internet" xmlns="http://www.vmware.com/vcloud/v1"> <Description>NAT-ed to the public Internet</Description> <Configuration> <ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <FenceMode>natRouted</FenceMode> <Features> <DhcpService>
VMware, Inc.
101
<IsEnabled>false</IsEnabled> <DefaultLeaseTime>3600</DefaultLeaseTime> <MaxLeaseTime>7200</MaxLeaseTime> <IpRange> <StartAddress>10.6.35.3</StartAddress> <EndAddress>10.6.255.254</EndAddress> </IpRange> </DhcpService> <FirewallService> <IsEnabled>true</IsEnabled> </FirewallService> <NatService> <IsEnabled>false</IsEnabled> <NatType>portForwarding</NatType> <Policy>allowTraffic</Policy> </NatService> </Features> </Configuration> </OrgNetwork>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Network Internet (2)" ...> ... </Task>
Remove an Organization Network

AnorganizationadministratorcanusetheremovelinkinanOrgNetworkbodytoremovethenetworkfrom theorganization.Example 613doesthis,makingaDELETErequesttotheremovelinkreturnedin Example 611. Example 6-13. Remove a Network from an Organization Request:
DELETE http://vcloud.example.com/api/v1.0/admin/network/54
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Removing Network Internet (2)" ...> ... </Task>
vDC Administration
AnewlycreatedorganizationhasnovDCsinit.vDCadministrationinvolvesthefollowingobjects:
AProviderVdc,whichasystemadministratorcreatesfromvSphereplatformresources(seeCreatea ProvidervDConpage 127). AnAdminVdc,whichasystemadministratorcreatestoallocateasubsetofProviderVdcresourcestoa vDCinaspecificorganization.OrganizationmembersseeanAdminVdcasavDC.
102
VMware, Inc.
Examine the Contents of a Provider vDC

ProviderVdcobjectsarelistedamongthetoplevelobjectsinavCloud.inExample 62onpage 94illustrates suchalisting,whichincludesaProviderVdcReferenceselementthatcontainsreferencestotheprovider vDCsregisteredtothisvCloud.
<ProviderVdcReferences> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <ProviderVdcReference ... /> ... </ProviderVdcReferences>
AnadministratorcanusethevalueofthehrefattributeinanyProviderVdcReferenceasthetargetofaGET request.TheresponseisaProviderVdcbody,asshowninExample 614. Example 6-14. Examine the Contents of a Provider vDC Request:
GET http://vcloud.example.com/api/v1.0/admin/providervdc/2
Response:
200 OK Content-Type: application/vnd.vmware.admin.providervdc+xml ... <ProviderVdc xmlns="http://www.vmware.com/vcloud/v1" status="1" name="PVDC_VC2" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2" ... > <Link rel="up" href="http://vcloud.example.com/api/v1.0/admin/"/> <Link rel="down" type="application/vnd.vmware.admin.vdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences"/> <Description>PVDC_VC2</Description> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocation>21929</Allocation> <Total>24675</Total> <Used>10053</Used> <Overhead>384</Overhead> </Cpu> <Memory> <Units>MB</Units> <Allocation>16207</Allocation> <Total>24475</Total> <Used>15771</Used> <Overhead>977</Overhead> </Memory> </ComputeCapacity> <StorageCapacity> <Units>MB</Units> <Allocation>1311368</Allocation> <Total>2097152</Total> <Used>489361</Used> <Overhead>2436</Overhead> </StorageCapacity> <AvailableNetworks> <Network type="application/vnd.vmware.admin.network+xml" name="External Network VC2" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> </AvailableNetworks> <IsEnabled>true</IsEnabled> <NetworkPoolReferences> <NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="VC2-Direct" href="http://vcloud.example.com/api/v1.0/admin/extension/ networkPool/22"/>
VMware, Inc.
103
<NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="VC2_VLAN_Backed" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/2"/> </NetworkPoolReferences> </ProviderVdc>
List the Organization vDCs Supported by a Provider vDC

AnadministratorcanusethehrefvaluefromanyProviderVdcReferenceelementinaVCloudasthetarget ofarequestthatreturnsalistoforganizationvDCsthattheprovidervDCsupports. Example 615showsarequestofthistype,madeusingthehrefoftheprovidervDCshowninExample 62 onpage 94.Theresponse,aVdcReferenceselement,indicatesthattheprovidervDCat http://vcloud.example.com/api/v1.0/admin/providervdc/2issupportingtheorganizationvDC, http://vcloud.example.com/api/v1.0/admin/vdc/44,createdinExample 616. Example 6-15. List the Organization vDCs Supported by a Provider vDC Request:
GET http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences
Response:
<VdcReferences xmlns="http://www.vmware.com/vcloud/v1" ... > <Link rel="up" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <VdcReference type="application/vnd.vmware.admin.vdc+xml" name="org3vdc1" href="http://vcloud.example.com/api/v1.0/admin/vdc/44"/> </VdcReferences>
Allocate a vDC to an Organization

AnorganizationadministratorcanallocateresourcesfromaprovidervDCtoavDCinanorganizationby POSTinganAdminVdcbodytoanorganizationsaddURLforvDCs.Example 64includessuchaURL:
<Link rel="add" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/vdcs"/>
Example 616usesthatURLtoaddanewvDCtotheorganization.ThenewvDCallocatesresourcesfromthe providervDCspecifiedintheProviderVdcReferenceelementintherequestbody.Thecontentsofthat elementwereobtainedfromthiselement,shownintheresponseinExample 62.

<ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="MainProvider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <ProviderVdcReference ... />
Example 6-16. Allocate a vDC to an Organization Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/vdcs Content-Type: application/vnd.vmware.admin.vdc+xml ... <AdminVdc name="org26vdc1" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Example vDC</Description> <AllocationModel>AllocationPool</AllocationModel> <StorageCapacity> <Units>MB</Units> <Allocated>3072</Allocated> <Limit>4096</Limit> </StorageCapacity> <ComputeCapacity> <Cpu>
104
VMware, Inc.
<Units>MHz</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Cpu> <Memory> <Units>MB</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Memory> </ComputeCapacity> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> </AdminVdc>
Response:
201 Created Content-Type: application/vnd.vmware.admin.vdc+xm ... <AdminVdc name="org26vdc1" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/vdc/44" ...> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="edit" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/vdc/44"/> <Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/vdc/44/action/disable"/> <Link rel="alternate" href="http://vcloud.example.com/api/v1.0/vdc/44"/> <Description>Example vDC</Description> <Tasks> <Task status="running" ... operation="Creating Virtual Datacenter (44)" ...> ... </Task> </Tasks> <AllocationModel>AllocationPool</AllocationModel> <StorageCapacity> <Units>MB</Units> <Allocated>3072</Allocated> <Limit>4096</Limit> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Cpu> <Memory> <Units>MB</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Memory> </ComputeCapacity> <ResourceEntities/> <AvailableNetworks> <Network type="application/vnd.vmware.admin.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> </AvailableNetworks> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> </AdminVdc>
VMware, Inc.
105
Theresponseechoestherequest,andincludesaTaskelementthattrackscreationofthevDC.Thenetwork createdinExample 610appearsintheAvailableNetworkselement.Ifyouaddedmorenetworkstothe organizationthatcontainsthisvDC,theywouldalsoappearinthatelement.
Get an Administrative View of a vDC

ReferencestoanorganizationsvDCsarecontainedintheVdcselementoftheOrgorAdminOrgbody.Toget anadministrativeviewofavDC,anadministratorcanmakeaGETrequesttoitsadminURL.Therequest returnsanAdminVdcbody,similartotheoneshownintheresponsesectionofExample 63.
Modify a vDC
TomodifyavDC,makeaPUTrequesttoitseditlink,andsupplyamodifiedversionoftheVdcbody.In Example 617,theclientmodifiesthevDCcreatedinExample 63tochangethevaluesintheCpuelement,then includesthemodifiedbodyinaPUTrequesttotheeditlinkthatwasreturnedwhenthevDCwascreated. Theresponse,onlypartofwhichisshownintheexample,isanAdminVdcbodycontainingthemodified values. Example 6-17. Modify a vDC Request:
PUT http://vcloud.example.com/api/v1.0/admin/vdc/44 Content-Type: application/vnd.vmware.admin.vdc+xm <AdminVdc name="org3vdc1" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Example vDC</Description> <AllocationModel>AllocationPool</AllocationModel> <StorageCapacity> <Units>MB</Units> <Allocated>4096</Allocated> <Limit>8192</Limit> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>4096</Allocated> <Limit>4096</Limit> </Cpu> <Memory> <Units>MB</Units> <Allocated>2048</Allocated> <Limit>4096</Limit> </Memory> </ComputeCapacity> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> </AdminVdc>
Response:
200 OK Content-Type: application/vnd.vmware.admin.vdc+xm ... <AdminVdc name="org26vdc1" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/vdc/44" ...> ... <Tasks> <Task status="running" ... operation="Updating Virtual Datacenter (44)"...> ... </Task> </Tasks>
106
VMware, Inc.
<ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>4096</Allocated> <Limit>4096</Limit> </Cpu> ... </ComputeCapacity> ... </AdminVdc>
Enable or Disable a vDC

AnadministratorcanusetheenableordisableactionlinksinanAdminVdcbodytoenableordisableavDC. TherequestandresponsearesimilartothoseshowninExample 67onpage 98.Theenablementstateofthe vDCisshowninitsIsEnabledelement.
Remove a vDC
BeforeyoucanremoveavDC,youmustdisableit.AfterthevDChasbeendisabled,itsrepresentationincludes arel="remove"link.AnadministratorcanmakeaDELETErequesttothatlinktoremoveavDCfroman organization. Example 6-18. Remove a vDC Request:
DELETE http://vcloud.example.com/api/v1.0/admin/vdc/6
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Deleted Virtual Datacenter (6)" ...> ... </Task>
Catalog Administration
Anewlycreatedorganizationhasnocatalogsinit.Anorganizationadministratormustcreatethemand specifytheirscopebeforeitemscanbecatalogued.Youdonothavetobeanadministratortoaddorremove CatalogItemelements.SeeCatalogingvAppTemplatesandMediaImagesonpage 54.
Create a Catalog
EveryorganizationhasanaddURLforcatalogs.AnadministratorcancreateacatalogbyPOSTingaCatalog bodytothisURL.Example 619doesthis,usingtheURLinthisLinkshowninExample 63.
<Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/>
Theresponseechoestherequest,andincludestheseadditionscreatedbytheserver.

AURL(thevalueofthehrefattributeoftheresponsebody)thatreferencesthenewcatalog. Linksthataclientcanusetorequestoperationslikeaddanitemtothecatalog,editcatalogproperties,or removethecatalog. Alinktothealternate(user)viewofthiscatalog AnemptyCatalogItemselement
VMware, Inc.
107
ATaskthattracksthecreationofthecatalog AnIsPublishedelementwhosecontentisthestringfalse.
Example 6-19. Create a Catalog Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/catalogs Content-Type: application/vnd.vmware.admin.catalog+xml <Catalog name="Custom Catalog" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Custom Catalog</Description> </Catalog>
Response:
201 Created Content-Type: application/vnd.vmware.admin.catalog+xml ... <Catalog href="http://vcloud.example.com/api/v1.0/catalog/32" name="Custom Catalog" ...> <Description>Custom Catalog</Description> <Tasks> <Task ...> ... <Task> <Tasks> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="alternate" href="http://vcloud.example.com/api/v1.0/catalog/32"/> <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/> <Link rel="edit" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalog/32"/> <Link rel="publish" href="http://vcloud.example.com/api/v1.0/catalog/32/action/publish"/> <CatalogItems/> <IsPublished>false</IsPublished> </Catalog>
Get an Administrative View of a Catalog

Anadministrativeviewofacatalogisnearlyidenticaltoauserviewbutcontainsadditionalactionlinksthat supportadministrativeoperationssuchaseditandremove.Toseeanadministrativeviewofacatalog,an administratorcanmakeaGETrequesttoitsadminURL,asshowninExample 620.Forauserviewofthe samecatalog,seeExample 32onpage 35. Example 6-20. Get an Administrative View of a Catalog Request:
GET http://vcloud.example.com/api/v1.0/admin/catalog/32
Response:
200 OK Content-Type: application/vnd.vmware.admin.catalog+xml ... <Catalog .... > ... <Link rel="edit" href="http://vcloud.example.com/api/v1.0/admin/catalog/32"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/catalog/32"/>
108
VMware, Inc.
<Description>Custom Catalog</Description> <CatalogItems> ... </CatalogItems> ... </Catalog>
Publish a Catalog
PublishingacatalogmakesthecatalogvisibletoallorganizationsinavCloud.Anadministratorofan organizationthatcanpublishcatalogs(onewhoseCanPublishCatalogselementhasavalueoftrue)can publishacatalogbymakingaPOSTrequesttothecatalogspublishURLandsupplyinga PublishCatalogParamsbodythatsetsthevalueofthecatalogsIsPublishedelementtotrue.Example 621 publishesthecatalogcreatedinExample 619. Example 6-21. Publish a Catalog Request:
POST http://vcloud.example.com/api/v1.0/admin/catalog/32/action/publish Content-Type: application/vnd.vmware.admin.publishCatalogParams+xml ... <PublishCatalogParams xmlns="http://www.vmware.com/vcloud/v1"> <IsPublished>true</IsPublished> </PublishCatalogParams>
Response:
204 No Content
Modify Catalog Metadata

Anadministratorcanmodifycatalogmetadatasuchasitsnameanddescriptionbycreatingamodified CatalogbodyandPUTtingittothecatalogseditlink.TherequestinExample 622changesthenameand descriptionofthecatalogcreatedinExample 619.TheresponsecontainsthemodifiedCatalogbody, includingtheCatalogItemselement,whichwasunchangedby,andnotincludedin,therequest. Example 6-22. Modify Catalog Metadata Request:
PUT http://vcloud.example.com/api/v1.0/admin/catalog/32 Content-Type: application/vnd.vmware.admin.catalog+xml <Catalog name="TechOps Catalog 01" xmlns="http://www.vmware.com/vcloud/v1"> <Description>TechOps Approved Templates Catalog</Description> </Catalog>
Response:
200 OK Content-Type: application/vnd.vmware.admin.catalog+xml <Catalog href="http://vcloud.example.com/api/v1.0/catalog/32" name="TechOps Catalog 01" ...> <Description>TechOps Approved Templates Catalog</Description> <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/>
VMware, Inc.
109
<CatalogItems> <CatalogItem name="Ubuntu Template with vsftpd" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"> <Description>Approved template for public FTP sites</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Property key="Owner">Tech Ops</Property> </CatalogItem> </CatalogItems> </Catalog>
NOTEModifyingcatalogmetadatadoesnotaffectCatalogItemelements.Youcannotcreateacatalogthat hasCatalogItemelementsinit.Theymustbeaddedinaseparateoperation.Forinformationaboutadding andremovingtheseelements,seeCatalogingvAppTemplatesandMediaImagesonpage 54.
Remove a Catalog
AnadministratorcanremoveacatalogbymakingaDELETErequesttothecatalogsrel="remove"URL. Example 623removesthecatalogcreatedinExample 619. Example 6-23. Remove a Catalog Request:
DELETE http://vcloud.example.com/api/v1.0/admin/catalog/32
Response:
204 No Content
User Administration
UserscanbecreatedinanorganizationorimportedintotheorganizationfromanLDAPdirectoryservice.
Create or Import a User

Everyuserexistswithinthecontextofanorganization.Anadministratorcanaddausertoanorganizationby POSTingaUserbodytotheorganizationsaddURLforusers,asshowninExample 624,whichaddstheuser totheorganizationcreatedinExample 63.TheresponseisaUserelement,mostofwhichisnotshowninthe example.Theelementincludesalinkthatanadministratorcanusetoedittheuser,andadditionalelements, suchasIsDefaultCachedandStoredVmQuota,inheritedfromorganizationdefaults. Example 6-24. Create a User Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/users Content-Type: application/vnd.vmware.admin.user+xml <User name="ExampleUser" xmlns="http://www.vmware.com/vcloud/v1"> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <IsEnabled>true</IsEnabled> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <Password>Pa55w0rd</Password> </User>
110
VMware, Inc.
Response:
201 Created Content-Type: application/vnd.vmware.admin.user+xml ... <User name="ExampleUser" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <IsEnabled>true</IsEnabled> <IsAlertEnabled>false</IsAlertEnabled> <IsDefaultCached>false</IsDefaultCached> <StoredVmQuota>0</StoredVmQuota> <DeployedVmQuota>0</DeployedVmQuota> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <GroupReferences/> </User>
ToimportauserfromanLDAPdirectoryservice,POSTaUserbodywhosenameattributespecifiestheusers nameintheLDAPdirectory,andincludesanIsExternalelementwithavalueoftrue.Theservermatches thevalueofthenameattributeintherequestbodywiththevalueoftheLDAPattributethattheorganization hasspecifiedfortheusername(thevalueoftheUserNameelementinUserAttributes),andimportsthatuser fromLDAP.SeeUserAttributesonpage 184. Example 625illustratesthissortofrequest. Example 6-25. Import a User from LDAP Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/users Content-Type: application/vnd.vmware.admin.user+xml ... <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" xmlns="http://www.vmware.com/vcloud/v1"> <IsExternal>true</IsExternal> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> </User>
Response:
201 Created Content-Type: application/vnd.vmware.admin.user+xml ... <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User</FullName> <EmailAddress>user@example.com</EmailAddress> <IsEnabled>false</IsEnabled> <IM/> <NameInSource>\F4\D3\42\8E\6A\BC\D3</NameInSource> <IsAlertEnabled>false</IsAlertEnabled> <IsDefaultCached>false</IsDefaultCached> <StoredVmQuota>0</StoredVmQuota> <DeployedVmQuota>0</DeployedVmQuota> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <GroupReferences/> </User>
VMware, Inc.
111
FullNameandEmailAddressareretrievedfromLDAP.ValuesforIsEnabled,Description,andother elementscanbespecifiedintherequestbodyoraddlater.SeeModifyUserMetadataonpage 112.
Get an Administrative View of a User

EachuserinanorganizationisrepresentedbyaUserReferenceelement.AGETrequesttotheURLinthe hrefattributeofaUserReferencereturnsaUserelementintheresponse,asshowninExample 626. Example 6-26. Get an Administrative View of a User Request:
GET http://vcloud.example.com/api/v1.0/admin/user/85
Response:
200 OK Content-Type: application/vnd.vmware.admin.user+xml ... <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <Telephone/> <IsEnabled>true</IsEnabled> <IM/> <NameInSource>user@example.com</NameInSource> <IsAlertEnabled>false</IsAlertEnabled> <IsDefaultCached>false</IsDefaultCached> <StoredVmQuota>1000</StoredVmQuota> <DeployedVmQuota>100</DeployedVmQuota> <Role type="application/vnd.vmware.admin.role+xml" name="User" href="http://vcloud.example.com/api/v1.0/admin/role/1"/> <GroupReferences/> </User>
Modify User Metadata

AnadministratorcanusetheeditlinkinaUserelementtomodifyusermetadata.Therequestin Example 627disablestheUserobjectbysettingvalueofitsIsEnabledelementtofalse.Asisthecasewith allrequests,therequestbodymustincludeallrequiredelements,whetherornotyouarechangingthem.The responseisthefullUserelement,includingthechangedmetadata,andincludesthelinksandothermetadata typicallysuppliedbytheserver. Example 6-27. Modify User Metadata Request:
PUT http://vcloud.example.com/api/v1.0/admin/user/85 Content-Type: application/vnd.vmware.admin.user+xml ... <User name="ExampleUser" xmlns="http://www.vmware.com/vcloud/v1"> <IsEnabled>false</IsEnabled> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> </User>
112
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.admin.user+xml ... <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <IsEnabled>false</IsEnabled> </User>
Remove a User
Beforeyoucanremoveauser,youmustdisabletheUserobjectbychangingthevalueofitsIsEnabled elementtofalse,asshowninExample 627.Afterithasbeendisabled,theUserelementcontainsalink whererel="remove".Anadministratorcanusethislinkremovetheuserfromtheorganization,asshownin Example 628. Example 6-28. Remove a User Request:
DELETE http://vcloud.example.com/api/v1.0/admin/user/85
Response:
204 No Content
Group Administration
GroupsmustbeimportedfromLDAP.YoucannotusethevCloudAPItoaddorremovegroupmembers,or changethenameofthegroup.Instead,youmustmakethechangesinthesourceLDAPdatabaseandthen importthegroupagain.
Import a Group
ToimportagroupfromanLDAPdirectoryservice,POSTanemptyGroupbodytotheorganizationsaddURL forgroups.Thevalueofthenameattributeintherequestbodymustmatchthevalueofthegroupsname attributeinLDAP. Example 6-29. Import a Group from LDAP Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/groups Content-Type: application/vnd.vmware.admin.group+xml <Group name="Engineering" xmlns="http://www.vmware.com/vcloud/v1"> <Role type="application/vnd.vmware.admin.role+xml" name="vApp Wrangler" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> </Group>
VMware, Inc.
113
Response:
201 Created Content-Type: application/vnd.vmware.admin.user+xml ... <Group name="Engineering" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/group/44" ...> <Link rel="edit" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/group/44"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/group/44"/> <Description>Research and development</Description> ... <UsersList/> <Role type="application/vnd.vmware.admin.role+xml" name="vApp Wrangler" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> </Group>
View Group Metadata

EachgroupinanorganizationcanbereferencedbytheURLcontainedinoneofitsGroupReference elements.TheseelementsarecontainedbytheGroupselementofanAdminOrgbody.AgroupsURLalso appearsintheresponsetotherequestthatimportsthegroup.AnadministratorcanGETagroupURLtoview theGroupbody.
Modify Group Metadata

AnadministratorcanmodifyaGroupbodytochangeitsDescriptionorRolebyPUTtingamodifiedGroup bodytotheeditURLforthegroup.SeeExample 627foranexampleoftheworkflowforthistypeofrequest.
Remove a Group
AnadministratorcanusetheremovelinkinaGroupbodytoremoveagroupfromavCloud.Example 630 removesthegroupimportedinExample 629. Example 6-30. Remove a Group Request:
DELETE http://vcloud.example.com/api/v1.0/admin/group/44
Response:
204 No Content
Role Administration
Aroleassociatesthenameofauserorgroupwithasetofrights.RolenamesmustbeuniqueinavCloud instance.
Create a Role
AsystemadministratorcancreatearolebyaggregatingasetofrightsinaRolebody,andthenPOSTingthe bodytotheaddURLforroles.Example 631createsanewrolenamedvAppWranglerandaddsittothe vCloudshowninExample 62.Theresponse,likeotherresponsestorequeststhatcreateanobject,includes thePOSTedcontent,alinktothenewobject,andlinksoftypeeditandremovethatanadministratorcanuse tomanagethisrole.
114
VMware, Inc.
Example 6-31. Create a Role Request:

POST http://vcloud.example.com/api/v1.0/admin/roles Content-Type: application/vnd.vmware.admin.role+xml <Role name="vAppWrangler" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Create and manage vApps</Description> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: View" href="http://vcloud.example.com/api/v1.0/admin/right/16"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Power Operations" href="http://vcloud.example.com/api/v1.0/admin/right/9"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Download" href="http://vcloud.example.com/api/v1.0/admin/right/11"/> <RightReference ... /> ... </RightReferences> </Role>
Response:
201 Created Content-Type: application/vnd.vmware.admin.role+xml ... <Role name="vAppWrangler" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102" ...> <Link rel="edit" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Description>Create and manage vApps</Description> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: View" href="http://vcloud.example.com/api/v1.0/admin/right/16"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Power Operations" href="http://vcloud.example.com/api/v1.0/admin/right/9"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Download" href="http://vcloud.example.com/api/v1.0/admin/right/11"/> <RightReference ... /> ... </RightReferences> </Role>
View Role Metadata

URLsforallrolesinavCloudappearasRoleReferenceelementsinavCloudbody.AnindividualrolesURL isalsodisplayedintheresponsetoarequestthatcreatestheroleAsystemadministratorcanGETaroleURL toviewtheRolebody.Example 632doesthisfortherolecreatedinExample 631. Example 6-32. View Role Metadata Request:
GET http://vcloud.example.com/api/v1.0/admin/role/102
Response:
200 OK Content-Type: application/vnd.vmware.admin.role+xml ... <Role name="vApp Wrangler" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102" ...>
VMware, Inc.
115
<Link rel="edit" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Description>Create and manage vApps</Description> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: View" href="http://vcloud.example.com/api/v1.0/admin/right/16"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Power Operations" href="http://vcloud.example.com/api/v1.0/admin/right/9"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Download" href="http://vcloud.example.com/api/v1.0/admin/right/11"/> <RightReference ... /> ... </RightReferences> </Role>
Modify a Role
AsystemadministratorcanmodifyaroletoaddorremoverightsorchangethenameoftherolebyPUTting amodifiedRolebodytotheeditURLoftheRole.SeeExample 627foranexampleoftheworkflowforthis typeofrequest.
Remove a Role
AsystemadministratorcanusetheremovelinkinaRoleelementtoremovearolefromavCloud. Example 633removestherolecreatedinExample 631. Example 6-33. Remove a Role Request:
DELETE http://vcloud.example.com/api/v1.0/admin/role/102
Response:
204 No Content
View a Right
Asystemadministratorcanview,butnotmodify,thecontentsofaRightelement,asshowninExample 634, whichprovidesaviewofoneoftheRightReferencesshowninExample 62. Example 6-34. View a Right Request:
GET http://vcloud.example.com/api/v1.0/admin/right/7
Response:
200 OK Content-Type: application/vnd.vmware.admin.right+xml ... <Right xmlns="http://www.vmware.com/vcloud/v1" name="Catalog: Sharing" type="application/vnd.vmware.admin.right+xml" href="http://vcloud.example.com/api/v1.0/admin/right/7" ... > <Description>Share a Catalog</Description> <Category>catalog</Category> </Right>
116
VMware, Inc.
VMware vSphere Platform Operations
TheVMwarevCloudAPIincludesextensionsthatsupportavarietyofoperationsonthevSpherePlatform, whichprovidesresourcestoaVMwarevCloud. NOTEAllvSphereplatformoperationsarerestrictedtothesystemadministrator.Beforeattemptinganyof theseoperations,logintotheSystemorganizationwiththeusernameandpasswordofthesystem administratoraccountthatwascreatedwhenCloudDirectorwasinstalled.Formoreinformation,see AdministratorCredentialsandPrivilegesonpage 93. Thischapterincludesthefollowingtopics:

SummaryofvSpherePlatformOperationsRequestsonpage 117 ListvSpherePlatformOperationsandObjectsforavCloudonpage 119 ListProvidervDCsinavCloudonpage 120 ListNetworkPoolsinavCloudonpage 120 ListvCenterServersRegisteredtoavCloudonpage 120 ListESX/ESXiHostsinavCloudonpage 124 CreateaProvidervDConpage 127 CreateanExternalNetworkonpage 133 CreateaNetworkPoolonpage 136 ImportaVirtualMachinefromvCenteronpage 138
Summary of vSphere Platform Operations Requests

Table 71summarizesvSphereplatformoperationsrequestssupportedinthisrelease.Thetableusesthe followingconventions:

APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0. idisaninteger.
Table 7-1. Summary of vSphere Platform Operations Requests

Operation Request Request Body None Response VMWExtension
ListvSpherePlatform GETAPIURL/admin/extension OperationsandObjects foravCloud ListProvidervDCsina GETAPIURL/admin/extension/ vCloud providerVdcReferences ListExternalNetworks GETAPIURL/admin/extension/ inavCloud externalNetworkReferences
None None
VMWProviderVdcReferences VMWExternalNetworkReferences
VMware, Inc.
117
Table 7-1. Summary of vSphere Platform Operations Requests (Continued)

Operation Request Request Body None None None None Response VMWNetworkPoolReferences VMWVimServerReferences VimServer ResourcePoolList
ListNetworkPoolsina GETAPIURL/admin/extension/ vCloud networkPoolReferences ListvCenterServers RegisteredtoavCloud GETAPIURL/admin/extension/ vimServerReferences
GetInformationAbout GETAPIURL/admin/extension/ avCenterServer vimServer/id ListAvailableResource GETAPIURL/admin/extension/ vimServer/id/resourcePoolList PoolsonavCenter Server ModifyvCenterServer PUTAPIURL/admin/extension/ Settings vimServer/id/ RegisteravCenter ServerandvShield Manager UnregisteravCenter ServerandvShield Manager POSTAPIURL/admin/extension/ action/registervimserver POSTAPIURL/admin/extension/ vimServer/id/action/unregister
VimServer RegisterVimServerParams
Task RegisterVimServerParams
None
Task
ForceReconnectiontoa POSTAPIURL/admin/extension/ vCenterServer vimServer/id/ forcevimserverreconnect ListESX/ESXiHostsin avCloud GETAPIURL/admin/extension/ hostReferences
None
204NoContent
None None PrepareHostParams None None
VMWHostReferences Host Task Task 204NoContent
GetInformationAbout GETAPIURL/admin/extension/ aHost host/id PrepareaHost UnprepareaHost EnableorDisablea Host POSTAPIURL/admin/extension/ host/id/action/prepare POSTAPIURL/admin/extension/ host/id/action/unprepare POSTAPIURL/admin/extension/ host/id/action/enable POSTAPIURL/admin/extension/ host/id/action/disable RepairaHost UpgradeaHostAgent CreateaProvidervDC ExaminethevSphere ObjectsinaProvider vDC ModifyaProvidervDC EnableorDisablea ProvidervDC POSTAPIURL/admin/extension/ host/id/action/repair POSTAPIURL/admin/extension/ host/id/action/upgrade POSTAPIURL/admin/extension/ providervdcs GETAPIURL/admin/extension/ providervdc/id PUTAPIURL/admin/extension/ providervdcs POSTAPIURL/admin/extension/ providervdc/id/action/enable POSTAPIURL/admin/extension/ providervdc/id/action/disable DELETE APIURL/admin/extension/ providervdc/id POSTAPIURL/admin/extension/ externalnets
None None VMWProviderVdc None
204NoContent Task VMWProviderVdc VMWProviderVdc
VMWProviderVdc None
VMWProviderVdc 204NoContent
RemoveaProvider vDC CreateanExternal Network
None
Task
VMWExternalNetwork
VMWExternalNetwork
118
VMware, Inc.
Chapter 7 VMware vSphere Platform Operations
Table 7-1. Summary of vSphere Platform Operations Requests (Continued)

Operation Request Request Body none VMWExternalNetwork none Response VMWExternalNetwork VMWExternalNetwork Task
GetInformationAbout GETAPIURL/admin/extension/ anExternalNetwork externalnet/id ModifyanExternal Network RemoveanExternal Network CreateaNetworkPool PUTAPIURL/admin/extension/ externalnet/id DELETE APIURL/admin/extension/ externalnet/id POSTAPIURL/admin/extension/ networkPools
VMWNetworkPool None VMWNetworkPool None ImportVmAsVAppParams ImportVmAsVAppTemplate Params
VMWNetworkPool VMWExternalNetwork VMWNetworkPool 204NoContent VApp VAppTemplate
GetInformationAbout GETAPIURL/admin/extension/ aNetworkPool networkPool/id ModifyaNetworkPool RemoveaNetwork Pool ImportaVirtual MachineasavApp ImportaVirtual MachineasavApp Template PUTAPIURL/admin/extension/ networkPool/id PUTAPIURL/admin/extension/ networkPool/id POSTAPIURL/admin/extension/ vimServer/id/importVmAsVapp POSTAPIURL/admin/extension/ vimServer/id/ importVmAsVappTemplate
List vSphere Platform Operations and Objects for a vCloud

AllresourcesexposedtovCloudtenantsthroughprovidervDCsoriginateinvCenterinstancesregisteredto thevCloudservice.AsystemadministratorcanrequestalistofvSphereobjectscurrentlyregisteredforuse withavCloud.Theresponsealsoincludelinkstoactionsthatallowthesystemadministratortoaddorregister newvSphereobjects.Example 71showsanexampleofsucharequest. Example 7-1. List All vSphere Platform Operations and Objects for a vCloud Request:
GET http://vcloud.example.com/api/v1.0/admin/extension
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwextension+xml ... <vmext:VMWExtension xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... > <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwProviderVdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/ providerVdcReferences"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwExternalNetworkReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/ externalNetworkReferences"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwNetworkPoolReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/ networkPoolReferences"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwVimServerReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/ vimServerReferences"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwHostReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/hostReferences"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdcs"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwexternalnet+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnets"/>
VMware, Inc.
119
<vcloud:Link rel="add" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPools"/> <vcloud:Link rel="register" type="application/vnd.vmware.admin.registerVimServerParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/action/ registervimserver"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.licensingReportList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/licensing/reports"/> </vmext:VMWExtension>
List Provider vDCs in a vCloud

AsystemadministratorcanusetheproviderVdcReferenceslinkreturnedinaVMWExtensionresponseto requestalistofallprovidervDCsinthevCloud.Example 72makessucharequest,usingthe providerVdcReferenceslinkreturnedinExample 71. Example 7-2. List Provider vDCs in a vCloud Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/providerVdcReferences
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwprovidervdcreferences+xml ... <vmext:VMWProviderVdcReferences xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... > <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwExtension+xml" href="http://vcloud.example.com/api/v1.0/admin/extension"/> <vmext:ProviderVdcReference type="application/vnd.vmware.admin.vmwprovidervdc+xml" name="PVDC-VC3" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/1"/> <vmext:ProviderVdcReference ... > <vmext:ProviderVdcReference ... > </vmext:VVMWProviderVdcReferences>
List External Networks in a vCloud

ThisoperationfollowsthemodelshowninExample 72,butusestheexternalNetworkReferenceslink fromtheVMWExtensionresponseasthetargetoftherequest.Theresponseisa VMWExternalNetworkReferenceselement.
List Network Pools in a vCloud

ThisoperationfollowsthemodelshowninExample 72,butusesthenetworkPoolReferenceslinkfromthe VMWExtensionresponseasthetargetoftherequest.TheresponseisaNetworkPoolReferenceselement.
List vCenter Servers Registered to a vCloud

ThisoperationfollowsthemodelshowninExample 72,butusesthevimServerReferenceslinkfromthe VMWExtensionresponseasthetargetoftherequest.TheresponseisaVMWVimServerReferenceselement.
Get Information About a vCenter Server

AsystemadministratorcanusethehrefattributevalueofanyVimServerReferenceina VMWVimServerReferenceselementtogetmoreinformationaboutaspecificvCenterserver,asshownin Example 73.
120
VMware, Inc.
Example 7-3. Get Information About a vCenter Server Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml ... <vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC-02" ... > <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmsObjectRefsList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ vmsList"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.resourcePoolList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ resourcePoolList"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ importVmAsVApp"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ importVmAsVAppTemplate"/> <vcloud:Link rel="unregister" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/ unregister"/> <vcloud:Description>vCenter created by the Configuration Wizard</vcloud:Description> <vmext:Username>administrator</vmext:Username> <vmext:Url>http://10.147.40.234:443</vmext:Url> <vmext:IsEnabled>true</vmext:IsEnabled> <vmext:ShieldManagerIP>10.147.44.59</vmext:ShieldManagerIP> <vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName> </vmext:VimServer>
List Available Resource Pools on a vCenter Server

TheVimServerelementreturnedinresponsetoaGETrequesttoavimServerURLcontainsarel="down" linkwhosehrefvalueisaURLthatreturnsalistofavailableresourcepoolshostedonthatserver.Apoolis consideredavailableifitisnotinuseinavDC.AsystemadministratorcanmakeaGETrequesttothatURL tolisttheavailablepools.Example 74makessucharequestusingtheresourcePoolListURLfrom Example 73. Example 7-4. List Available Resource Pools on a vCenter Server Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/resourcePoolList
Response:
200 OK Content-Type: application/vnd.vmware.admin.resourcepoollist+xml ... <vmext:ResourcePoolList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ...> <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:ResourcePool name="Cluster-1"> <vmext:MoRef>resgroup-1159</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> <vmext:DataStoreRefs/> </vmext:ResourcePool> <vmext:ResourcePool name="Cluster-2"> <vmext:MoRef>resgroup-1064</vmext:MoRef>
VMware, Inc.
121
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:MoRef>datastore-10</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef> <vmext:MoRef>datastore-11</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef> <vmext:MoRef>datastore-12</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> </vmext:ResourcePool> </vmext:ResourcePoolList>
Modify vCenter Server Settings

Asystemadministratorcanchangethevaluesofname,Description,andIsEnabledforavCenterserverby makingaPUTrequesttotheserverseditURL.Asystemadministratormustalsomodifythevaluesof Username,Password,andURLwhenanyofthosearechangedontheserverhost.Youcannotchangethose valuesforthevCenterserverbymodifyingitsVimServerelement,butyoumustupdatetheelementifyou makethesechangestotheserver. Example 75disablesthevCenterservershowninExample 73andalsochangesitsDescription. Example 7-5. Modify vCenter Server Settings Request:
PUT http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100 Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml ... <vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC-02" type="application/vnd.vmware.admin.vmwvirtualcenter+xml"> <vcloud:Description>Temporarily disabled for maintenance</vcloud:Description> <vmext:Username>administrator</vmext:Username> <vmext:Url>http://10.147.40.234:443</vmext:Url> <vmext:IsEnabled>false</vmext:IsEnabled> </vmext:VimServer>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating VirtualCenter (100)" ...> ... </Task>
Register a vCenter Server and vShield Manager

AsystemadministratorcanregisteravCenterserverandacompanionvShieldmanagerserverforusewitha vCloudbymakingaPOSTrequesttothevCloudsaction/registervimserverURLandsupplyinga RegisterVimServerParamsrequestbody,asshowninExample 76.
122
VMware, Inc.
Example 7-6. Register a vCenter Server and vShield Manager Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/action/registervimserver Content-Type: application/vnd.vmware.admin.registerVimServerParams+xml ... <vmext:RegisterVimServerParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1"> <vmext:VimServer name="VC-22"> <vmext:Username>Administrator</vmext:Username> <vmext:Password>Pa55w0rd</vmext:Password> <vmext:Url>https://10.100.121.123:443</vmext:Url> <vmext:IsEnabled>false</vmext:IsEnabled> </vmext:VimServer> <vmext:ShieldManager name="VSM-VC-22"> <vmext:Username>Administrator</vmext:Username> <vmext:Password>Pa55w0rd</vmext:Password> <vmext:Url>https://10.100.121.66</vmext:Url> </vmext:ShieldManager> </vmext:RegisterVimServerParams>
Response:
200 OK Content-Type: application/vnd.vmware.admin.registerVimServerParams+xml ... <vmext:RegisterVimServerParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml"> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC-22" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"> <vmext:Username>Administrator</vmext:Username> <vmext:Url>https://10.100.121.123:443</vmext:Url> <vmext:IsEnabled>false</vmext:IsEnabled> </vmext:VimServer> <vmext:ShieldManager> <vmext:AssociatedVimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VSM-VC-22" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:Username>Administrator</vmext:Username> <vmext:Url>https://10.100.121.66</vmext:Url> </vmext:ShieldManager> </vmext:RegisterVimServerParams>
Unregister a vCenter Server and vShield Manager

UnregisteringavCenterservermakesitanditsvShieldManagerserverunavailableforuseintheCloud Directorenvironment.AsystemadministratorcanunregisteravCenterserverandvShieldmanagerby makingaPOSTrequesttothevCenterserversaction/unregisterURL.Example 77unregistersthe vCenterserverreferencedbyhttp://vcloud.example.com/api/v1.0/admin/extension/vimServer/100. NOTEYoumustdisablethevCenterserverbeforeyouunregisterit.
VMware, Inc.
123
Example 7-7. Unregister a vCenter Server and vShield Manager Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/unregister
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... > ... </Task>
Force Reconnection to a vCenter Server

IfCloudDirectorlosesitconnectiontoavCenterServer,orifyouchangetheconnectionsettings,asystem administratorcanmakeaPOSTrequesttotheserversaction/forcevimserverreconnectlinktotryforcing areconnection,asshowninExample 78. Example 7-8. Force Reconnection to a vCenter Server Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/ forcevimserverreconnect
Response:
204 No Content
List ESX/ESXi Hosts in a vCloud

AsystemadministratorcanusethehostReferenceslinkreturnedinaVMWExtensionresponsetorequesta listofallESX/ESXihostsinthevCloud.Example 79makessucharequest,usingthehostReferenceslink returnedinExample 71. Example 7-9. List ESX/ESXi Hosts in a vCloud Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/hostReferences
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwhostreferences+xml ... <vmext:VMWHostReferences xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... > <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwExtension+xml" href="http://vcloud.example.com/api/v1.0/admin/extension"/> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.12" href="http://vcloud.example.com/api/v1.0/admin/extension/host/180"/> <vmext:HostReference ... > <vmext:HostReference ... > </vmext:VMWHostReferences>
Get Information About a Host

AsystemadministratorcanusethehrefattributevalueofanyHostReferenceinaVMWHostReferences elementtogetdetailedinformationaboutaspecifichost,asshowninExample 710.
124
VMware, Inc.
Example 7-10. Get Information About a Host Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/host/22
Response:
200 OK Content-Type: application/vnd.vmware.admin.host+xml ... <vmext:Host xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="10.115.121.14" href="http://vcloud.example.com/api/v1.0/admin/extension/host/22" ... > <vcloud:Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/extension/host/22/action/disable"/> <vcloud:Description/> <vmext:Ready>true</vmext:Ready> <vmext:Available>true</vmext:Available> <vmext:Enabled>true</vmext:Enabled> <vmext:Busy>false</vmext:Busy> <vmext:EnableHostForHostSpanning>true</vmext:EnableHostForHostSpanning> <vmext:CpuType>Intel(R) Xeon(R) CPU E5310 @ 1.60GHz</vmext:CpuType> <vmext:NumOfCpusPackages>2</vmext:NumOfCpusPackages> <vmext:NumOfCpusLogical>8</vmext:NumOfCpusLogical> <vmext:CpuTotal>1600</vmext:CpuTotal> <vmext:MemUsed>0.0</vmext:MemUsed> <vmext:MemTotal>8187.5546875</vmext:MemTotal> <vmext:HostOsName>VMware ESXi</vmext:HostOsName> <vmext:HostOsVersion>4.0.0</vmext:HostOsVersion> <vmext:VimPropertyPageUrl> vpxclient://7416E531-05B9-4C1F-854D-97EF7C546CB0::HostSystem:host-20/ </vmext:VimPropertyPageUrl> <vmext:VmMoRef>host-20</vmext:VmMoRef> </vmext:Host>
Prepare a Host
WhenyouaddahosttoavSphereclusterthatCloudDirectoruses,youmustpreparethehostbeforea providervDCcanusethehostsresources. Youcannotprepareahostthatisinlockdownmode.Afteryouprepareahost,youcanenablelockdownmode. AsystemadministratorcanprepareahostbymakingaPOSTrequesttothehostsaction/prepareURLand supplyingaPrepareHostParamsrequestbodythatincludestheusernameandpasswordofahost administrator,asshowninExample 711. Example 7-11. Prepare a Host Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/prepare Content-Type: application/vnd.vmware.admin.prepareHostParams+xml ... <vmext:PrepareHostParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml"> <vmext:Username>Administrator</vmext:Username> <vmext:Password>Pa55w0rd</vmext:Password> </vmext:PrepareHostParams>
VMware, Inc.
125
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Preparing Host (1)" ...> ... </Task>
Unprepare a Host
UnprepareahosttomakeitunavailableforuseintheCloudDirectorenvironment.Asystemadministrator canunprepareahostbymakingaPOSTrequesttothehostsaction/unprepareURL.Example 712 unpreparesthehostreferencebyhttp://vcloud.example.com/api/v1.0/admin/extension/host/1. Example 7-12. Unprepare a Host Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/unprepare
Response:
Enable or Disable a Host

YoucandisableahosttopreventvAppsfromstartinguponthehost.Virtualmachinesthatarealready runningonthehostarenotaffected.Toperformmaintenanceonahost,migrateallvAppsoffofthehostor stopallvAppsandthendisablethehost. AsystemadministratorcanenableordisableahostforuseinavCloudbymakingaPOSTrequesttothehosts action/enableoraction/disableURL.Example 713disablesthehostreferencedby http://vcloud.example.com/api/v1.0/admin/extension/host/1. Example 7-13. Disable a Host Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/disable
Response:
204 No Content
Repair a Host
IftheCloudDirectoragentonahostcannotbecontacted,asystemadministratorcantrytorepairthehost POSTrequesttothehostsaction/repairURL.Example 714upgradesthehostagentforthehostreferenced byhttp://vcloud.example.com/api/v1.0/admin/extension/host/1.
126
VMware, Inc.
Example 7-14. Repair a Host Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/repair
Response:
Upgrade a Host Agent

NewreleasesofvCenterCloudDirectormayincludeanewversionofthehostagent.Asystemadministrator canupgradethehostagentonahosttotheversionincludedinthecurrentinstallationofCloudDirectorby makingaPOSTrequesttothehostsaction/upgradeURL.Example 715upgradesthehostagentforthehost referencedbyhttp://vcloud.example.com/api/v1.0/admin/extension/host/1. Example 7-15. Upgrade a Host Agent Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/upgrade
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Upgrading Host (1)" ...> ... </Task>
Create a Provider vDC

AnVMWProviderVdcisanextendedrepresentationofaProviderVdcobject.Itincludeselementsthatallow asystemadministratortospecifyresourcessuchasdatastoresandresourcepoolsprovidedbyavCenter instanceregisteredtothevCloud.OnlyasystemadministratorcanviewormodifyaVMWProviderVdc.An organizationadministratororotherprivilegedusercanexamineallotherpropertiesofaprovidervDC(see ExaminetheContentsofaProvidervDConpage 103). AfterasystemadministratorcreatesaVMWProviderVdc,itbecomesvisibleasamemberofthe ProviderVdcReferenceselementofaVCloud.SeeGetanAdministrativeViewofaCloudonpage 93. Asystemadministratorcanusetherel="add"linkforprovidervdcsinaVMWExtensionbodytoadda providervDCtoavCloud.Example 718doesthisbymakingaPOSTrequesttotheprovidervdcslink returnedinExample 71. ToretrievethevaluesyouneedfortheDataStoreRefsandResourcePoolRefelementsintherequestbody, startbylistingthevCenterServersregisteredtothisvCloud(seeListvCenterServersRegisteredtoavCloud onpage 120),thenGEToneofthevCenterServerURLslistedintheresponse.TheresultisaVimServer element,asshowninExample 716.
VMware, Inc.
127
Example 7-16. VimServer Element Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml ... <vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101" ...> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmsObjectRefsList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ vmsList"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.resourcePoolList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ resourcePoolList"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ importVmAsVApp"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ importVmAsVAppTemplate"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vcloud:Link rel="unregister" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/action/ unregister"/> <vcloud:Link rel="reconnect" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/action/ forcevimserverreconnect"/> <vmext:Username>administrator</vmext:Username> <vmext:Url>https://10.147.20.155:443</vmext:Url> <vmext:IsEnabled>true</vmext:IsEnabled> <vmext:ShieldManagerIP>10.147.41.67</vmext:ShieldManagerIP> <vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName> </vmext:VimServer>
TheresourcePoolListfromaVimServerelement(seeExample 717)includestheMoRefand VimObjectTypevaluesforallaccessibledatastoresandresourcepoolsassociatedwiththatvCenterserver. Example 7-17. Resource Pool List Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/resourcePoolList
Response:
200 OK Content-Type: application/vnd.vmware.admin.resourcepoollist+xml ... <vmext:ResourcePoolList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ... > <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:ResourcePool name="gasare-vc2-rp"> <vmext:MoRef>resgroup-3582</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef>
128
VMware, Inc.
<vmext:MoRef>datastore-322</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef> <vmext:MoRef>datastore-350</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> </vmext:ResourcePool> </vmext:ResourcePoolList>
YoucanusethisinformationtogetvaluesfortheDataStoreRefsandResourcePoolRefelementsinthe VMWProviderVdc,thenPOSTtheVMWProviderVdcbodytotherel="add"linkforprovidervdcsinthe VMWExtensionelement,asshowninExample 718. Example 7-18. Create a Provider vDC Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/providervdcs Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml ... <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml"> <vcloud:Description>New Provider vDC</vcloud:Description> <vcloud:ComputeCapacity> <vcloud:Cpu> <vcloud:Units>MHz</vcloud:Units> <vcloud:Allocation>2241</vcloud:Allocation> <vcloud:Total>24675</vcloud:Total> </vcloud:Cpu> <vcloud:Memory> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>1319056</vcloud:Allocation> <vcloud:Total>2097152</vcloud:Total> </vcloud:Memory> </vcloud:ComputeCapacity> <vcloud:StorageCapacity> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>18944</vcloud:Allocation> <vcloud:Total>2260224</vcloud:Total> </vcloud:StorageCapacity> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/ 101"/> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> <vmext:ResourcePoolRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:MoRef>resgroup-220</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> </vmext:ResourcePoolRef> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> </vmext:VMWProviderVdc>
Response:
201 Created Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml
VMware, Inc.
129
... <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" status="0" name="PvDC-VC2" xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"> <vcloud:Link rel="enable" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2/action/ enable"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"/> <vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"/> <vcloud:Link rel="alternate" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences"/> <vcloud:Description>New Provider vDC</vcloud:Description> <vcloud:Tasks> <vcloud:Task ... operation="Creating Provider Virtual Datacenter PvDC-VC2(2)" ... > ... </vcloud:Task> </vcloud:Tasks> <vcloud:Description>PVDC_VC2</vcloud:Description> <vcloud:ComputeCapacity> <vcloud:Cpu> <vcloud:Units>MHz</vcloud:Units> <vcloud:Allocation>21929</vcloud:Allocation> <vcloud:Total>24675</vcloud:Total> <vcloud:Used>10053</vcloud:Used> <vcloud:Overhead>384</vcloud:Overhead> </vcloud:Cpu> <vcloud:Memory> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>16207</vcloud:Allocation> <vcloud:Total>24475</vcloud:Total> <vcloud:Used>15771</vcloud:Used> <vcloud:Overhead>977</vcloud:Overhead> </vcloud:Memory> </vcloud:ComputeCapacity> <vcloud:StorageCapacity> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>1311368</vcloud:Allocation> <vcloud:Total>2097152</vcloud:Total> <vcloud:Used>489361</vcloud:Used> <vcloud:Overhead>2436</vcloud:Overhead> </vcloud:StorageCapacity> <vcloud:AvailableNetworks> <vcloud:Network type="application/vnd.vmware.admin.network+xml" name="External Network VC2" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> </vcloud:AvailableNetworks> <vcloud:IsEnabled>false</vcloud:IsEnabled> <vcloud:NetworkPoolReferences> <vcloud:NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="s-org-vdc-vc2-DirectNET" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/ 22"/> <vcloud:NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="Netpool_VC2_VLAN_Backed" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/2"/> </vcloud:NetworkPoolReferences> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/ 101"/> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
130
VMware, Inc.
</vmext:VimObjectRef> </vmext:DataStoreRefs> <vmext:ResourcePoolRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:MoRef>resgroup-220</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> </vmext:ResourcePoolRef> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:HostReferences> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.11" href="http:// vcloud.example.com/api/v1.0/admin/extension/host/1"/> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.9" href="http:// vcloud.example.com/api/v1.0/admin/extension/host/2"/> </vmext:HostReferences> </vmext:VMWProviderVdc>
Theresponseechoestherequestbutnowhasastatusattributewhosevalueisinitially0andanhref attributewhosevalueistheURLofthenewprovidervDC.Italsoincludessomeadditionalelementscreated bytheserver:

Linkelementsforactionsandrelatedreferences ATaskelementthattrackscreationoftheprovidervDC.Whenthetaskcompletes,thevalueofthe providervDCsstatusattributechangesto1. AHostReferenceselementthatcontainsreferencestotheESX/ESXihostsregisteredtothevCenter serverbackingthisprovidervDC.
Examine the vSphere Objects in a Provider vDC

AsystemadministratorcanretrievealistofProviderVdcReferences(seeListProvidervDCsinavCloud onpage 120),thenusethevalueofthehrefattributeinanyProviderVdcReferenceasthetargetofaGET request.TheresponseisaVMWProviderVdcbodysimilartotheoneshownintheresponseinExample 718.
Modify a Provider vDC

TomodifyaprovidervDC,makeaPUTrequesttoitseditlink,andsupplyamodifiedversionofthe VMWProviderVdcelementintherequestbody.InExample 719,theclientmodifiestheCpu Allocationof theprovidervDCcreatedinExample 718,thenincludesthemodifiedelementinaPUTrequesttotheedit linkintheVMWProviderVdcelement. Youmustincludeallrequiredelementsandattributesintherequest,eventhosethatyouarenotchanging. Example 7-19. Modify a Provider vDC Request:
PUT http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2 Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml ... <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml"> <vcloud:ComputeCapacity> <vcloud:Cpu> <vcloud:Units>MHz</vcloud:Units> <vcloud:Allocation>4096</vcloud:Allocation> <vcloud:Total>24675</vcloud:Total> </vcloud:Cpu> <vcloud:Memory> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>1319056</vcloud:Allocation> <vcloud:Total>2097152</vcloud:Total>
VMware, Inc.
131
</vcloud:Memory> </vcloud:ComputeCapacity> <vcloud:StorageCapacity> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>18944</vcloud:Allocation> <vcloud:Total>2260224</vcloud:Total> </vcloud:StorageCapacity> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/ 101"/> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> <vmext:ResourcePoolRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:MoRef>resgroup-220</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> </vmext:ResourcePoolRef> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> </vmext:VMWProviderVdc>
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml ... <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml" ... > ... </vmext:VMWProviderVdc>
Theresponse,mostofwhichisnotshownhere,echoestherequest.
Enable or Disable a Provider vDC

AsystemadministratorcanusetheenableordisableactionlinksinaVMWProviderVdcelementtoenable ordisableaprovidervDC,asshowninExample 720.TheenablementstateoftheVMWProviderVdcisshown initsIsEnabledelement. Example 7-20. Disable a Provider vDC Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/providervdc/43/action/disable
Response:
204 No Content
Remove a Provider vDC

BeforeyoucanremoveaprovidervDC,youmustdisableit.AftertheprovidervDChasbeendisabled,its representationincludesarel="remove"link.AsystemadministratorcanmakeaDELETErequesttothatlink toremoveaprovidervDCfromavCloud.TheresponsecontainsaTaskthattracksthedeleteoperation.
132
VMware, Inc.
Example 7-21. Remove a vDC Request:

DELETE http://vcloud.example.com/api/v1.0/admin/extension/providervdc/43
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Deleting Provider Virtual Datacenter (43)" ...> ... </Task>
Create an External Network

Asystemadministratorcanusetherel="add"linkforexternalnetsinaVMWExtensionelementtoaddan externalnetworktoavCloud.Example 722doesthisbymakingaPOSTrequesttotheexternalnetslink returnedinExample 71.ThecontentoftheVimPortGroupRefelementintherequestbodyspecifiesthat vCenterportgroupthatsupportsthenewexternalnetwork. NOTEYoumustusetheVMwarevSphereAPItoobtainthevaluesyouneedtopopulatethe VimPortGroupRefelement. Example 7-22. Create an External Network Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/externalnets Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100"> <vcloud:Description>Portgroup-25 on VC-100</vcloud:Description> <vcloud:Configuration> <vcloud:IpScope> <vcloud:IsInherited>false</vcloud:IsInherited> <vcloud:Gateway>10.147.58.253</vcloud:Gateway> <vcloud:Netmask>255.255.255.0</vcloud:Netmask> <vcloud:Dns1>10.147.115.1</vcloud:Dns1> <vcloud:Dns2>10.147.115.2</vcloud:Dns2> <vcloud:DnsSuffix>eng.vmware.com</vcloud:DnsSuffix> <vcloud:IpRanges> <vcloud:IpRange> <vcloud:StartAddress>10.147.58.1</vcloud:StartAddress> <vcloud:EndAddress>10.147.58.100</vcloud:EndAddress> </vcloud:IpRange> </vcloud:IpRanges> </vcloud:IpScope> <vcloud:FenceMode>isolated</vcloud:FenceMode> </vcloud:Configuration> <vmext:VimPortGroupRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvportgroup-25</vmext:MoRef> <vmext:VimObjectType>NETWORK</vmext:VimObjectType> </vmext:VimPortGroupRef> </vmext:VMWExternalNetwork>
VMware, Inc.
133
Response:
201 Created Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="alternate" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/27"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Description>Portgroup-25 on VC-100</vcloud:Description> <vcloud:Tasks> <vcloud:Task status="running"... operation="Creating External Network ExternalNet-VC100(27)" href="http:// vcloud.example.com/api/v1.0/task/579"/> </vcloud:Tasks> ... </vmext:VMWExternalNetwork>
TheresponseechoestherequestandincludesLinkelementsforactionsandrelatedreferences,andaTask elementthattrackscreationoftheexternalnetwork.
Get Information About an External Network

AsystemadministratorcanusethehrefattributevalueofanyExternalNetworkReferenceelementtoget moreinformationaboutaspecificexternalnetwork.Example 723retrievesinformationabouttheexternal networkcreatedinExample 722.TheentireVMWExternalNetworkbodyisreturnedintheresponse,butonly partoftheresponseisshownintheexample Example 7-23. Get Information About an External Network Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="alternate" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/27"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Description>Portgroup-25 on VC-100</vcloud:Description> <vcloud:Configuration> ... </vcloud:Configuration> <vmext:VimPortGroupRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvportgroup-25</vmext:MoRef> <vmext:VimObjectType>NETWORK</vmext:VimObjectType> </vmext:VimPortGroupRef> </vmext:VMWExternalNetwork>
134
VMware, Inc.
Modify an External Network

Tomodifyanexternalnetwork,makeaPUTrequesttoitseditlink,andsupplyamodifiedversionofthe VMWExternalNetworkelementintherequestbody.InExample 724,theclientmodifiestheIpRange EndAddressoftheexternalnetworkcreatedinExample 722,thenincludesthemodifiedbodyinaPUT requesttotheeditlinkthatwasreturnedwhentheexternalnetworkwascreated. Example 7-24. Modify an External Network Request:
PUT http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27 Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Description>Description>Portgroup-25 on VC-100</vcloud:Description> <vcloud:Configuration> <vcloud:IpScope> <vcloud:IsInherited>false</vcloud:IsInherited> <vcloud:Gateway>10.147.58.253</vcloud:Gateway> <vcloud:Netmask>255.255.255.0</vcloud:Netmask> <vcloud:Dns1>10.147.115.1</vcloud:Dns1> <vcloud:Dns2>10.147.115.2</vcloud:Dns2> <vcloud:DnsSuffix>eng.vmware.com</vcloud:DnsSuffix> <vcloud:IpRanges> <vcloud:IpRange> <vcloud:StartAddress>10.147.58.1</vcloud:StartAddress> <vcloud:EndAddress>10.147.58.201</vcloud:EndAddress> </vcloud:IpRange> </vcloud:IpRanges> </vcloud:IpScope> <vcloud:FenceMode>isolated</vcloud:FenceMode> </vcloud:Configuration> <vmext:VimPortGroupRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvportgroup-25</vmext:MoRef> <vmext:VimObjectType>NETWORK</vmext:VimObjectType> </vmext:VimPortGroupRef> </vmext:VMWExternalNetwork>
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100"> ... </vmext:VMWExternalNetwork>
Remove an External Network

Toremoveanexternalnetwork,asystemadministratorcanmakeaDELETErequesttoitsrel="remove"link. TheresponseisaTaskthattracksthedeleteoperation.
VMware, Inc.
135
Example 7-25. Remove an External Network Request:

DELETE http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Deleting External Network (27)" ...> ... </Task>
Create a Network Pool

Asystemadministratorcanusetherel="add"linkfornetworkPoolsinaVMWExtensionbodytoadda networkpooltoavCloud.Example 726createsanetworkpooloftheVlanPoolTypebymakingaPOST requesttothenetworkPoolslinkreturnedinExample 71.Requeststocreatenetworkpoolsofothertypes (FencePoolTypeandPortGroupPoolType)followasimilarpattern. NOTEYoumustusetheVMwarevSphereAPItoobtainthevaluesyouneedtopopulatetheVimSwitchRef element. Example 7-26. Create a Network Pool Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/networkPools Content-Type: application/vnd.vmware.admin.networkPool+xml ... <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance xsi:type="vmext:VlanPoolType" name="NewVlanPool"> <vcloud:Description>Extra pool for new Orgs</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>120</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvs-28</vmext:MoRef> <vmext:VimObjectType>DV_SWITCH</vmext:VimObjectType> </vmext:VimSwitchRef> </vmext:VMWNetworkPool>
Response:
201 Created Content-Type: application/vnd.vmware.admin.networkPool+xml ... <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41" ... > <vcloud:Description>Extra pool for new Orgs</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>120</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef>
136
VMware, Inc.
<vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvs-28</vmext:MoRef> <vmext:VimObjectType>DV_SWITCH</vmext:VimObjectType> </vmext:VimSwitchRef> </vmext:VMWNetworkPool>
Get Information About a Network Pool

AsystemadministratorcanusethehrefattributevalueofanyNetworkPoolReferenceorVMWNetworkPool elementtogetmoreinformationaboutthenetworkpool.Example 727retrievesinformationaboutthe networkpoolcreatedinExample 726.TheentireVMWNetworkPoolbodyisreturnedintheresponse,butonly partoftheresponseisshownintheexample Example 7-27. Get Information About a Network Pool Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41
Response:
200 OK ... <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41" ... > <vcloud:Description>Extra pool for new Org Nets</vcloud:Description> ... </vmext:VMWNetworkPool>
Modify a Network Pool

Tomodifyanetworkpool,makeaPUTrequesttoitseditlink,andsupplyamodifiedversionofthe VMWNetworkPoolbody.InExample 728,theclientmodifiestheVlanRange Endofthenetworkpoolcreated inExample 726,thenincludesthemodifiedbodyinaPUTrequesttotheeditlinkthatwasreturnedwhen thenetworkpoolwascreated. Example 7-28. Modify a Network Pool Request:
PUT http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41 Content-Type: application/vnd.vmware.admin.networkPool+xml ... <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool"> <vcloud:Description>Extra pool for new Org Nets</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>150</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvs-28</vmext:MoRef> <vmext:VimObjectType>DV_SWITCH</vmext:VimObjectType> </vmext:VimSwitchRef> </vmext:VMWNetworkPool>
VMware, Inc.
137
Response:
200 OK ... <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool"> ... <vmext:VMWNetworkPool>
Theresponse,mostofwhichisnotshownhere,echoestherequest.
Remove a Network Pool

Toremoveanetworkpool,asystemadministratorcanmakeaDELETErequesttoitshrefattributevalue.The responsecontainsaTaskthattracksthedeleteoperation. Example 7-29. Remove a Network Pool Request:
DELETE http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41
Response:
204 No Content
Import a Virtual Machine from vCenter

AsystemadministratorcanimportvirtualmachinesfromanyvCenterregisteredtoavCloud.Thevirtual machinescanbeimportedtoanyvDCinthevCloud,andcanbeimportedinvApporvApptemplateform.
Discover the Virtual Machines in a vCenter

AGETrequesttothevmsListURLinaVimServerresponsebodyreturnsalistofvirtualmachinesregistered tothatvCenterserver.Example 730retrievesthelistofvirtualmachinesfromthevmsListURLshownin Example 73onpage 121. Example 7-30. Discover the Virtual Machines in a vCenter Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/vmsList
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmsobjectrefslist+xml ... <vmext:VmObjectRefsList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ...> <vmext:VmObjectRef name="Win2K8"> <vcloud:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="vCenter-PA-001" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vcloud:MoRef>vm-642</vcloud:MoRef> <vcloud:VimObjectType>VIRTUAL_MACHINE</vcloud:VimObjectType> </vmext:VmObjectRef> <vmext:VmObjectRef ...> ... </vmext:VmObjectRef> </vmext:VmObjectRefsList>
138
VMware, Inc.
BecausethelistofvirtualmachinesregisteredtoavCenterservercanbeverylong,responsestoaGET .../vmslistrequestpresentthelistasaseriesofpages.Thedefaultpagesizeis100VmObjectRefelements,each representingasinglevirtualmachine.ThedefaultresponsetoaGET.../vmslistrequestreturnsthefirstpage ofthelist.Youcanaddqueryparameterstotherequesttospecifyapagesizeandapagenumber.Thesyntax forthequeryspecificationis:

GET API-URL/admin/extension/vimServer/id/vmsList?page=p&pageSize=s
where prepresentsanintegerpagenumber(startingwith1)andsrepresentsanintegerpagesize.Therequest showninExample 730couldberewrittenasshowninExample 731toreturnthefirsttenentriesinthe vmsList. Example 7-31. vmsList with Page Number and Page Size Query Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/vmsList?page=1&pageSize=10
Toreturnthecompletelistofvirtualmachines,makeadditionalrequeststhatincrementthevalueofpage.
Import a Virtual Machine as a vApp

ToimportavirtualmachineasavApp,asystemadministratorcanmakearequesttotheimportVmAsVApp linkintheVimServerresponsebodywhosevmslistcontainedtheVmObjectRefthatrepresentsthevirtual machine.Example 732importsthevirtualmachineshowninExample 730fromthevCenterserver representedbytheVimServerelementshowninExample 73onpage 121.Therequestbodyisan ImportVmAsVAppParamselementwhosesourceMoveattributespecifieswhetherornotthesourcevirtual machineshouldberemovedfromvCenteraftertheimportiscomplete.Therequestbodyalsospecifiesthe managedobjectreferenceofthevirtualmachinetoimport,andthehrefofthevDCtowhichtheimportgoes. TheresponseisanunresolvedvAppbodycontainingataskthattrackstheimport. Example 7-32. Import a Virtual Machine as a vApp Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVapp Content-type: application/vnd.vmware.admin.importVmAsVAppParams+xml ... <ImportVmAsVAppParams xmlns="http://www.vmware.com/vcloud/extension/v1" name="ImportedWin2K8" sourceMove="false"> <VmMoRef>vm-642</VmMoRef> <Vdc href="http://vcloud.example.com/api/v1.0/vdc/2"/> </ImportVmAsVAppParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp status="0" name="ImportedWin2K8" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-102" ...> ... <Description/> <Tasks> <Task ... operation=Busy Virtual Application Win2K8 ...> ... </Task> </Tasks> </VApp>
VMware, Inc.
139
Import a Virtual Machine as a vApp Template

TheworkflowtoimportavirtualmachineasavApptemplateissimilar.AsshowninExample 733,the requestURListheimportVmAsVAppTemplatelinkintheVimServerresponsebody.Therequestbodyisan ImportVmAsVAppTemplateParamselementthatcancontainanoptionalreferencetoacataloginwhichthe templatewillbeenteredaftertheimportiscomplete.TheresponseisanunresolvedvAppTemplatebody containingataskthattrackstheimport. Example 7-33. Import a Virtual Machine as a vApp Template Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVappTemplate Content-type: application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml ... <ImportVmAsVAppTemplateParams xmlns="http://www.vmware.com/vcloud/extension/v1" name="ImportedWin2K8-Template" sourceMove="false"> <VmMoRef>vm-642</VmMoRef> <Vdc href="http://vcloud.example.com/api/v1.0/vdc/2"/> <Catalog href="http://vcloud.example.com/api/v1.0/catalog/32"/> </ImportVmAsVAppTemplateParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate status="0" name="ImportedWin2K8-Template" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-64" ...> ... <Description/> <Tasks> <Task ... operation=Busy Virtual Application Template Win2K8 ...> ... </Task> </Tasks> </VApp>
140
VMware, Inc.
XML Representations in the vCloud API
ThevCloud APIrepresentsobjectsinavCloudasXMLdocumentsinwhichobjectpropertiesareencodedas elementsandattributeswithtypedvaluesandanexplicitobjecthierarchydefinedbyanXMLschema.This chapterprovidesreferenceinformationabouthowthevCloud APIusesXMLtorepresentvCloudobjects. Thischapterincludesthefollowingtopics:

AboutObjectRepresentationsonpage 141 CommonDatatypesonpage 142 CommonAttributesonpage 143 CommonElementsonpage 146 APIVersioningonpage 147 Extensibilityonpage 148
About Object Representations

ClientprogramsofRESTfulWebservicesmustbeabletorequestobjectrepresentationsfromtheserver,parse theserversresponsestoextracttheinformationtheycontain,andcomposerequeststhat,inmanycases,are basedontheinformationextractedfromaresponse.Developersofsuchclientsmustunderstandthestructure ofeachrepresentationthatmightbepartofarequestorresponse,aswellasanyrequirementsthatthenetwork protocol(HTTP)placesonclientserverinteraction.Inthisguide,referenceinformationoneachobject representationincludestheXMLschemaoftheelementthatrepresentstheobject,theobjecttype(encodedas theMIMEcontenttypeoftherequestorresponse),andaprototypeoftheobjectreference(aURL).
Schema
EachvCloud APIobjectisdefinedinanXMLschemadocument.Someobjectsaredefinedintheirownschema documents.Othersaredefinedinthecontextofthelargerschemainwhichtheyareused.Stillothersare definedinacommonschemadocument,fromwhichotherschemasinherit.Thisguidepresentsreference informationaboutXMLschemasintabularform,asshowninTable 81. Table 8-1. Schema Reference Table Columns
Name Nameofanelementor attributecontained. Elementnamesbegin withanuppercase character.Attribute namesbeginwitha lowercasecharacter. Min Minimumnumberof thisattributeor elementrequiredby theschema. Max Maximumnumberof thisattributeor elementallowedbythe schema.Avalueofn meansthatthe maximumnumberis unlimited. Type Typeoftheattributeor element,eithera primitiveXML datatypeoracomplex typedefinedbythe vCloud API. Description Descriptionofthe attributeorelement
VMware, Inc.
141
NOTEInthereferencematerial,elementsthataresimplycontainersarelistedbyname,alongwithan explanationofthepurposeofthecontainer,butdonotincludeaschemareference.
Schema Validation
ThisreleaseofCloudDirectorusesavalidatingXMLparserthatrequireselementsinXMLdocumentstoagree inbothorderandnumberwiththeschema.Requiredelementsmustappearinrequestbodies.Allelements thatappearinrequestbodiesmustappearintheorderestablishedbytheschema,andwithcontentthat conformstothetypeconstraintspecifiedintheschema.Defaultvalues,wheredefined,aresuppliedfor elementsthatareempty. IfarequestcontainselementsfrommultipleXMLnamespaces,namespaceidentifiersmustbesuppliedin requestbodiesandprependedtoelementnames.SeeXMLNamespaceIdentifiersonpage 145.
Content Type
AllrequeststhathaveabodymustincludeanHTTPContentTypeheaderthatspecifiesthecontenttypeof thebody.Contenttypeshavebeendefinedforanyelementthatcanbeusedasarequestbody,andareshown alongwiththeschemaandotherreferenceinformationfortheelement.
Object Reference Prototype

EveryobjectinavCloudisuniquelyidentifiedbyaURL.ThisURLisconstructedbytheserverandreturned inthevalueofthehrefattributeoftheXMLelementthatrepresentstheobject.ItalsoappearsinvariousLink andReferenceTypeelementsthatprovidereferencestotheobject.ThisURLservesasauniqueidentifierthat persistsforthelifeoftheobjectandisneverreused.WhenaclientmakesanHTTPGETrequesttoanobject href,theserverreturnsthecurrentXMLrepresentationofthatobject. AlthoughURLshaveawellknownsyntaxandawellunderstoodinterpretation,aclientshouldtreateach hrefasanopaquestring.Therulesthatgovernconstructionofhrefstringsbytheserverarenotguaranteed toremainineffectinfuturereleases.Inthisrelease,theyyieldpredictablecontentthatconformstooneoftwo prototypes:
Objectssuchasorganizations,vDCs,networks,andcatalogshavehrefvaluesoftheform APIURL/objecttype/id ObjectssuchasvApptemplates,vApps,andVmshavehrefvaluesoftheformAPIURL/xxxxxx/yyyid
Foreachprototype,APIURLhastheformhttp://vcloud.example.com/api/v1.0,andidisaninteger.An objecthrefprototypeisincludedinthereferenceinformationforeachobjecttypethathasanhrefattribute.
Common Datatypes
ThevCloud APIusesanumberofprimitiveXMLdatatypes,asdefinedinW3CRecommendation28 (http://www.w3.org/TR/xmlschema2/).Italsodefinesanumberofcomplextypes,ofwhichvCloud API elementsareinstances.
Primitive XML Datatypes

AttributesandsomeelementcontentarerepresentedbyprimitiveXMLdatatypes,whichareshownin Table 82. Table 8-2. Primitive XML Data Types Used by the vCloud API
Value xs:boolean xs:date xs:dateTime xs:double Description Alogicalvalue,includingtrue,false,0,and1. Datevalues. Date/timevalues(timestamps). NumericvaluethatcorrespondstotheIEEEdoubleprecision64bitfloatingpointtype definedinIEEE7541985.
142
VMware, Inc.
Chapter 8 XML Representations in the vCloud API
Table 8-2. Primitive XML Data Types Used by the vCloud API (Continued)
Value xs:long xs:int xs:string Description Numericvalueintherange9223372036854775808to9223372036854775807. Numericvalueintherange2147483648to2147483647. Anycharacterdata.
Complex Types
XMLelementsdefinedbythevCloud APIareinstancesofcomplextypes.Formostelements,thecomplextype nameistheelementnameconcatenatedwiththestringType(forexample,theOrgelementisaninstanceof OrgType,thevDCelementisaninstanceofVdcType,andsoon).Inmostofthesecases,theschema representationoftheelementprovidesanadequatereferencefortheunderlyingcomplextype. Therearealsoafewgenerictypesofwhichmanydifferentkindsofelementcanbeaninstance.Becausethese typesarenotassociatedwithaparticularkindofelement,weprovideschemainformationforthemhere.
EntityType
ThisisthebasecomplextypeforelementssuchasOrg,vDC,andvApp. Schema
Name name Description Tasks Min 1 0 0 Max 1 1 1 Type xs:string xs:string TasksInProgressType Description Nameoftheobject Optionaldescriptionoftheobject ReadonlycontainerforTaskelements.Eachelementin thecontainerrepresentsaqueued,running,orfailedtask ownedbythisobject.Successfullycompletedtasksarenot listed.
IpAddressType
TheIpAddressTypeimposesapatternontheprimitivexs:stringtype.ThepatterndefinesanIPv4address:
<xs:pattern value = "((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0 -9][0-9]|[1-9][0-9]|[0-9])"/>
Attributesofthistypeareinvalidunlesstheyconformtothepattern
ReferenceType
Manycontainerelementsarepopulatedwithreferencestocontainedobjects.Eachreferenceconsistsofa hyperlink,anoptionalmediatype,andaname. Schema
Name href type name Min 1 0 0 Max 1 1 1 Type xs:anyURI xs:string xs:string Description Hyperlinktothereferencedobject Objecttype,expressedasthemediatypeoftheXML representingoftheobject Nameofthereferencedobject.
Common Attributes
ElementssuchasOrg,Catalog,andvDChaveanumberofcommonattributes.Withtheexceptionofname, noneoftheseattributesarerequiredinrequestbodies,andareignoredifincluded.Allofthemareincluded inresponsebodies.
VMware, Inc.
143
name
Everyobjectrequiresanameattributewhosestringvalueprovidesthedisplaynamefortheobject.Thevalue ofnamemustbeuniquewithinagivenscope,asshowninTable 83. Table 8-3. Requirements for Unique Object Names
Object Type ProviderVdc Org,AdminOrg Vdc Catalog CatalogItem vAppTemplate vApp Vm Media Network Name Scope vCloud vCloud Containingorganization Containingorganization Containingcatalog Notconstrained Containingorganization ContainingvApp Notconstrained Container(Org,vApp,orvCloud)
href
EveryobjecthasuniquereferenceencodedinthehrefattributeofitsXMLrepresentation.SeeObject ReferencePrototypeonpage 142.
type
EveryobjectallowsatypeattributeinitsXMLrepresentation.Thevalueofthisattributeistheobjecttype expressedasastring,whichclientsshouldinterpretasthemediatype(HTTPContentType)ofthe representation.Thisstringiscaseinsensitiveinrequests,andcanbereturnedineithermixedcaseorlowercase charactersinresponses.Formoreinformation,seeContentTypeonpage 142.
status
ObjectssuchasvAppTemplate,vApp,andVm,thatextendtheResourceEntitytypehaveastatusattribute whosevalueindicatesthestateoftheobject,asshowninTable 84,whereYESindicatesthatastatusvalueis allowedfortheobjectlistedinthecolumnheader.Statusforanobject,suchasavAppTemplateorvApp,whose Children(Vmobjects)eachhaveastatusoftheirown,iscomputedfromthestatusoftheChildren. NOTEThedeploymentstatusofanobjectisindicatedbythevalueofitsdeployedattribute. Table 8-4. vAppTemplate, vApp, and Vm status Attribute Values
Value 1 0 1 2 3 4 5 6 7 Description Theobjectcouldnotbecreated. Theobjectisunresolved. Theobjectisresolved. Theobjectisdeployed. Theobjectissuspended. Theobjectispoweredon. Theobjectiswaitingforuserinput. Theobjectisinanunknownstate. Theobjectisinanunrecognizedstate. vAppTemplate YES YES YES No No No No YES YES vApp YES YES YES No YES YES
Vm YES YES YES No YES YES YES YES YES
YES YES YES
144
VMware, Inc.
Table 8-4. vAppTemplate, vApp, and Vm status Attribute Values (Continued)

Value 8 9 10 11 12 13 14 15 Description Theobjectispoweredoff. Theobjectisinaninconsistentstate. Childrendonotallhavethesamestatus. Uploadinitiated,OVFdescriptorpending Uploadinitiated,copyingcontents Uploadinitiated,diskcontentspending Uploadhasbeenquarantined Uploadquarantineperiodhasexpired vAppTemplate YES No YES YES YES YES YES YES vApp YES YES YES No No No No No
Vm YES YES No No No No No No
IndicatesthatallChildrenhavethisstatus
XML Namespace Identifiers

ElementsusedasrequestorresponsebodiescontainasetofattributesthatenableXMLvalidation.Thebody ofaPUTorPOSTrequestmustcontainallXMLnamespaceidentifiersrequiredtovalidatetheXMLit contains.AresponsebodytypicallyincludesalltheXMLnamespaceidentifiersthattheserverusedtovalidate it,inadditiontootherattributesthatspecifytheschemalocationssearchedduringvalidation.Table 85 summarizestheseattributesandshowsthenamespaceidentifiersandprefixesusedintheexamplesinthis guide. Table 8-5. XML Namespace Identifiers
Name xmlns xmlns:vmext Value http://www.vmware.com/vcloud/v1.0 http://www.vmware.com/vcloud/extension/v1 Requirement Requiredinallrequestbodies. Requiredinrequestbodiesthat includeelementsfromthevSphere PlatformExtensions Requiredinrequestbodiesthat includeelementsprefixedwithovf: Requiredinrequestbodiesthat includeelementsprefixedwithrasd: Notrequiredinrequestbodies. Notrequiredinrequestbodies.
xmlns:ovf xmlns:rasd xmlns:vssd xsi:schemaLocation
http://schemas.dmtf.org/ovf/envelope/1 http://schemas.dmtf.org/wbem/wscim/1/cimschema/2/ CIM_ResourceAllocationSettingData http://schemas.dmtf.org/wbem/wscim/1/cimschema/2/ CIM_VirtualSystemSettingData Aninstallationdependentschemalocationsearchpath. Formoreinformation,see http://www.w3.org/TR/xmlschema0/#schemaLocation http://www.w3.org/2001/XMLSchemainstance
xmlns:xsi
Notrequiredinrequestbodies.
XMLnamespaceidentifiersareomittedfrommostoftheexampleresponses(seeAbouttheExampleson page 19).Example 81showshowtheyappearinatypicalresponsebody. Example 8-1. Response Body Showing XML Namespace Identifiers
<VApp xmlns="http://www.vmware.com/vcloud/v1" status="8" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 http://vcloud.example.com/api/v1.0/schema/master.xsd"> ... </vApp>
VMware, Inc.
145
XML Namespace Prefixes in Request and Response Bodies

WhenarequestorresponseincludeselementsfrommultipleXMLnamespaces,eachelementnameisprefixed withanamespaceidentifier.UnlessallelementsinarequestorresponseoriginateinthesameXML namespace,theseprefixesarerequiredinrequestbodies,andarealwaysincludedinresponsebodies. Example 516onpage 78andExample 722onpage 133showhownamespaceprefixesappearinelement names.
Common Elements
ThevCloud APIdefinesanumberofelementsthatcanbecontainedbytherepresentationsofmanykindsof objects.
Description
TheDescriptionelementcontainsastringthatdescribestheobject.Thiselementisalwaysoptional.
Error
Errorelementsareusedtotransmitreadonlyerrorinformationinaresponse. Content-Type application/vnd.vmware.vcloud.error+xml Schema
Name message majorErrorCode minorErrorCode vendorSpecificErrorCode stackTrace Min 1 1 1 0 0 Max 1 1 1 1 1 Type xs:string xs:int xs:string xs:string xs:string Description Messagedescribingtheerror MatchestheHTTPstatuscode.SeeStatusCodesonpage 18. Errorcodespecifictothefailedoperation Emptyinthisrelease Stacktraceoftheerror,ifavailable.Thisattributeisreturned onlytoasystemadministrator.
Table 86liststheminorerrorcodevaluesdefinedinthisreleaseofthevCloud API. Table 8-6. Minor Error Codes

Error Code ACCESS_TO_RESOURCE_IS_FORBIDDEN BAD_REQUEST CONFLICT EULA_NOT_ACCEPTED Description of Error Therequestwasmadebyauserwhohadinsufficientrightstotheobject oroperation. TherequestcouldnotbevalidatedorcontainedinvalidXML. AconflictwasdetectedbetweensectionsofanOVFdescriptor. AnattempttoinstantiateavAppTemplateoruseavAppTemplateora VminacompositiondidnotincludeanAllEULAsAcceptedelement withavalueoftrue. Returnedforanyfailurethatcannotbematchedtoanotherminorerror code. Oneormorereferences(hrefattributevalues)suppliedintherequest couldnotberesolvedtoanobject. TheHTTPmethod(GET,PUT,POST,DELETE)isnotallowedforthe request. Oneormorereferences(hrefattributevalues)suppliedintherequest couldnotberesolvedtoanobject,ortheContenttypeoftherequest wasincorrect.
INTERNAL_SERVER_ERROR INVALID_REFERENCE METHOD_NOT_ALLOWED RESOURCE_NOT_FOUND
146
VMware, Inc.
Table 8-6. Minor Error Codes (Continued)

Error Code UNKNOWN UNSUPPORTED_MEDIA_TYPE Description of Error TherequestraisedanexceptionthatdidnotmatchanyHTTPstatus code. Thewrongcontenttypewasspecifiedfortherequest.
Link
ALinkelementdefinesahyperlinkwitharelationship,URI,andanoptionalnameandmediatype.Formore informationabouthowLinkelementsareusedandalistofthevaluesallowedfortherelattribute,seeLinks andLinkRelationsonpage 15. Thiselementisreadonly. Schema
Name rel href type name Min 1 1 0 0 Max 1 1 1 1 Type RelationType xs:anyURI xs:string xs:string Description Relationofthelinktothereferencedobject Hyperlinktothereferencedobject Mediatypeofthereferencedobject.Linkstoactionsdonot haveamediatype. Nameofthereferencedobject.LinkstoTasksandactions donothavenames.
API Versioning
vCloud APIschemaversioninformationappearsinthevaluesofthexsi:schemaLocationandxmlns attributesinaresponsedocument.Forexample,aresponsebodythatusedschemaversion1.0wouldinclude thefollowingattributes:
xsi:schemaLocation="http://vcloud.example.com/api/v1.0/schema/master.xsd" xmlns="http://www.vmware.com/vcloud/v1"
Todiscovertheschemaversionssupportedbyaserver,aclientcanmakeanunauthenticatedGETrequestto awellknownURLontheserver,asshowninExample 82.Theresponsetothiskindofrequestisa SupportedVersionsdocument,fromwhichtheclientcanderiveinformationaboutthemediatypesand schemalocationsusedbytheversionoftheAPIthattheserversupports.Theresponsecontainsa MediaTypeMappingelementforeachmediatypedefinedbytheAPI.(Theexampleshowsonlyafewofthese elements.)TheresponsealsoincludesaLoginUrlelement,whichcontainsaURLthataclientcanusetoobtain anauthenticationtoken.FormoreinformationaboutusingtheLoginUrl,seeAuthenticationonpage 18. Example 8-2. API Version Request Request:
GET http://vcloud.example.com/api/versions
Response:
200 OK Content-Type: text/xml ... <SupportedVersions ...> <VersionInfo> <Version>1</Version> <LoginUrl>http://vcloud.example.com/api/v1/login</LoginUrl> <MediaTypeMapping> <MediaType>application/vnd.vmware.vcloud.org+xml</MediaType> <ComplexTypeName>CatalogType</ComplexTypeName> <SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation> </MediaTypeMapping> <MediaTypeMapping>
VMware, Inc.
147
<MediaType>application/vnd.vmware.vcloud.vdc+xml</MediaType> <ComplexTypeName>CatalogItemType</ComplexTypeName> <SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation> </MediaTypeMapping> <MediaTypeMapping> ... </MediaTypeMapping> </VersionInfo> </SupportedVersions>
SupportedVersions
ASupportedVersionselementisacontainerforVersionInfoelements.
VersionInfo
AVersionInfoelementdefinestheloginURLandmediatypessupportedbyaversionofthevCloud API. Thiselementisreadonly. Schema
Name Version LoginUrl MediaTypeMapping Min 1 1 0 Max 1 1 n Type xs:string xs:string MediaTypeMappingType Description Versionnumber URLforloggingintothisversion Mediatypeofthereferencedobject.Linksto actionsdonothaveamediatype.
MediaTypeMapping
AMediaTypeMappingelementdefinesthename,MIMEcontenttype,andschemalocationofacomplextype supportedbythisversionofthevCloud API. Thiselementisreadonly. Schema
Name MediaType ComplexTypeName SchemaLocation Min 1 1 1 Max 1 1 1 Type xs:string xs:string xs:anyURI Description MIMEcontenttypeofthiscomplextype Nameofthiscomplextype URLfortheXMLschemadefinitiondocumentthatdefines thiscomplextype
Extensibility
ThevCloud APIisdesignedtobeextensible.AllcomplextypesdefinedbytheAPIextendasingleabstract complextype.Thiscomplextypeandalltypesbasedonitcanincludezeroormoreinstancesofanextension elementthatcancontainanarbitrarynumberofelementsandattributes. VCloudExtensibleTypeisanabstracttypethatallcomplextypesdefinedinthevCloud APInamespace (http://www.vmware.com/vcloud/v1)extend.Thistypeallowscustomattributestobeaddedtoanytypeand supportsdefinitionofcustomelementswithintheVCloudExtensionelement. TheVCloudExtensionelementhasanattributenamedrequiredthatspecifieshowclientsandservers proceedwhentheyseeunknownextension.Therequiredattributeisoptionalbutifomittedisassumedto bepresentwithavalueoftrue.Thatistosay,allVCloudExtensionelementsareassumedtorequireaserver thatunderstandsthem.
148
VMware, Inc.
Thisextensibilitymechanism,whichisnotusedinthisreleaseofthevCloud API,allowsnewserverstoextend theXMLrepresentationsnativetothisreleaseofthevCloud APIwithoutrequiringexistingclientsto understandthoseextensions.
VCloudExtension
AclientshouldbepreparedtoencounteraVCloudExtensionelementinanyresponse.Iftheelementdeclares required=trueandclientdoesnotknowhowtointerpretthecontentsoftheelement,theclientcanignore it,butitmustincludetheVCloudExtensioninanyrequesttomodifytheelementthatcontainsit.Aserver mustreturnafailurewhenarequestincludesaVCloudExtensionelementthatdeclaresrequired=true buttheserverdoesnotunderstandtheextension. Schema
Name required anyattributename anyelementname Min 0 0 0 Max 1 n n Type xs:boolean xs:any xs:any Description Trueifthisextensionmustbeunderstoodbytheserver Anarbitrarynumberofattributesofanytype Anarbitrarynumberofelementsofanytype
VMware, Inc.
149
150
VMware, Inc.
User API Reference
ThischapterprovidesreferenceinformationabouttheXMLelementsthatrepresenttheobjectmodeldefined forgeneraluseinthisreleaseofthevCloudAPI.Elementsdocumentedinthischapteraretypicallyreadable byallusers,andcanbemodifiedbyuserswithappropriaterights.Formoreinformationabouthowthe vCloudAPIusesXMLtorepresentobjects,andhowthisreferencematerialisorganized,seeXML RepresentationsinthevCloud APIonpage 141. Thischapterprovidesreferencematerialonthefollowingelementsandtheelementstheycontain:

OrgListonpage 151 Orgonpage 151 Vdconpage 152 OrgNetworkonpage 154 Catalogonpage 160 Mediaonpage 161 VAppTemplateonpage 161 VApponpage 162 Vmonpage 163 Sectiononpage 163 ScreenTicketonpage 168 TasksListonpage 168
OrgList
AnOrgListelementisacontainerforreferencestoorganizations.Itisreturnedintheresponsetoasuccessful loginoraGETAPIURL/orgrequest,andcontainsareferencetoeachorganizationtowhichtheloggedinuser hasaccess. Thiselementisreadonly. Content-Type application/vnd.vmware.vcloud.orgList+xml Object href prototype APIURL/org
Org
TheOrgelementrepresentstheuserviewofavCloudorganizationobject,whichisacontainerandunitof administrationforresourcesandusers. Content-Type application/vnd.vmware.vcloud.org+xml
VMware, Inc.
151
Object href prototype APIURL/org/id Schema

Name name anyattributename Link Description Tasks Min 1 0 0 0 0 Max 1 n n 1 1 Type xs:string any LinkType xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Linkstoactionsandcontainedobjects Optionaldescription ReadonlycontainerforTaskelements.Eachelement inthecontainerrepresentsaqueued,running,or failedtaskownedbythisobject. Fullnameoftheorganization
FullName
xs:string
Vdc
AvDCisadeploymentenvironmentforvApps.AVdcelementprovidesauserviewofavDC. Content-Type application/vnd.vmware.vcloud.vdc+xml Object href prototype APIURL/vdc/id Schema
Name name anyattributename status Min 1 0 0 Max 1 n 1 Type xs:string any xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers ThecreationstatusofthevDC:

-1 creationfailed 0 notready 1 ready 2 unknown 3 unrecognizedstatus
Description Tasks
0 0
1 1
xs:string TasksInProgressType
Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedtaskownedbythisobject. DefineshowresourcesareallocatedbythevDC. Thevalueofthiselementissetbytheadministrator whocreatedthevDC.Itisreadonlytousers. DefinesthestoragecapacityavailableinthevDC DefinesthecomputecapacityavailableinthevDC ReadonlycontainerforResourceEntity elements ReadonlycontainerforOrgNetworkelementsthat representorganizationnetworkscontainedbythe vDC MaximumnumberofvirtualNICsallowedinthis vDC.Defaultsto0,whichspecifiesanunlimited number. MaximumnumberofOrgNetworkobjectsthatcan bedeployedinthisvDC.Defaultsto0,which specifiesanunlimitednumber.
AllocationModel
AllocationModelType
StorageCapacity ComputeCapacity ResourceEntities AvailableNetworks
1 1 0 0
1 1 1 1
CapacityWithUsageType ComputeCapacityType ResourceEntitiesType AvailableNetworksType
NicQuota
xs:int
NetworkQuota
xs:int
152
VMware, Inc.
Chapter 9 User API Reference
Schema (Continued)
Name VmQuota Min 0 Max 1 Type xs:int Description Maximumnumberofvirtualmachinesthatcanbe deployedinthisvDC.Defaultsto0,whichspecifies anunlimitednumber. TrueifthisvDCisenabled
IsEnabled
xs:boolean
StorageCapacity
TheStorageCapacityelementreportsstorageresourceconsumptioninavDC. Schema
Name Used Overhead Min 0 0 Max 1 1 Type xs:long xs:long Description Percentageoftheallocationinuse.Thisvalueisreadonly. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisvDC.Thisvalueisreadonly.
ComputeCapacity
TheComputeCapacityelementreportsCPUandmemoryresourceconsumptioninavDC. Schema
Name Cpu Memory Min 1 1 Max 1 1 Type CapacityWithUsageType CapacityWithUsageType Description ReportsCPUresourceconsumptioninavDC ReportsmemoryresourceconsumptioninavDC
Cpu
TheCpuelementreportsCPUresourceconsumptioninavDC. Schema
Memory
TheMemoryelementreportsmemoryresourceconsumptioninavDC. Schema
AvailableNetworks
TheAvailableNetworkselementisareadonlycontainerforOrgNetworkelements.
Network
EachNetworkelementcontainsareferencetoanOrgNetworkobjectinthesameorganizationasthisvDC.
VMware, Inc.
153
ResourceEntities
TheResourceEntitieselementisareadonlycontainerforResourceEntityelements.
ResourceEntity
TheResourceEntityelementisareadonlyreferencetoavAppTemplateorMediaobjectcontainedbya vDC. Schema
Name name status anyattributename Files Min 1 0 0 0 Max 1 1 n 1 Type xs:string xs:int any FilesListType Description Commonobjectnameattribute Creationstatusofthereferencedobject. Includestype,href,XMLnamespaceidentifiers ReadonlycontainerforFileelements
Files
TheFileselementisacontainerforFileelements.
File
Fileelementsareconstructedbytheserverinresponsetoanuploadordownloadrequest. Schema
Name name size bytesTransferred Min 1 0 0 Max 1 1 1 Type xs:string xs:long xs:long Description Commonobjectnameattribute Sizeofthefileinbytes Ifanuploadordownloadofthisfileisinprogress,this attributeindicatesthenumberofbytesthathavebeen transferredbytheuploadordownload Ignoredinthisrelease Optionaldescription ReadonlycontainerforTaskelements.Eachelementin thecontainerrepresentsaqueued,running,orfailed taskownedbythisobject.
checksum Description Tasks
0 0 0
1 1 1
xs:normalizedString xs:string TasksInProgressType
OrgNetwork
AnOrgNetworkelementdefinesanetworkthathasbeenallocatedtoanorganizationbythesystem administrator. Content-Type application/vnd.vmware.vcloud.network+xml Object href prototype APIURL/network/id Schema
Name name anyattributename Description Min 1 0 0 Max 1 n 1 Type xs:string any xs:string Description Commonobjectnameattribute Includestype,href,XMLnamespace identifiers Optionaldescription
154
VMware, Inc.
Schema (Continued)
Name Tasks Min 0 Max 1 Type TasksInProgressType Description ReadonlycontainerforTaskelements. Eachelementinthecontainer representsaqueued,running,orfailed taskownedbythisobject. Propertiesofthenetwork Areferencetothenetworkpoolfrom whichthisnetworkisprovisioned.This element,whichisrequiredwhen creatinganatRoutedorisolated network,isreturnedinresponsetoa creationrequestbutnotshownin subsequentGETrequests. ListofexternalIPaddressesthatthis networkcanuseforNAT.
Configuration NetworkPool
0 0
1 1
NetworkConfigurationType ReferenceType
AllowedExternalIpAddresses
IpAddressesType
Configuration
TheConfigurationelementspecifiespropertiesofanetwork. Schema
Name IpScope ParentNetwork FenceMode Features Min 0 0 1 0 Max 1 1 1 1 Type IpScopeType ReferenceType FenceModeValuesType NetworkFeaturesType Description Definestheaddressrange,gateway,netmask,andother propertiesofthenetwork Referencetoanetworktowhichthisnetworkconnects Defineshowthisnetworkisconnectedtoits ParentNetwork Definesasetofnetworkfeatures.
FenceMode
TheFenceModeelementdefineshowthisnetworkisconnectedtoitsParentNetwork.Table 91shows permittedvaluesforelementcontentandtheresultstheyproduce. Table 9-1. FenceMode Element Values
Value bridged isolated natRouted Result Thetwonetworksarebridged Thetwonetworksarenotconnected. ThetwonetworksareconnectedasspecifiedintheirNatServiceelements.
IpScope
TheIpScopeelementdefinestheaddressrange,gateway,netmask,andotherpropertiesofthenetwork. Schema
Name IsInherited Min 1 Max 1 Type xs:boolean Description TrueifthevaluesinthisIpScopeelementare inheritedfromtheParentNetworkofthe containingConfiguration IPaddressofthenetworkgateway Netmasktoapplytoaddressesonthenetwork IPaddressoftheprimaryDNSserverforthis network
Gateway Netmask Dns1
0 0 0
1 1 1
IpAddressType IpAddressType IpAddressType
VMware, Inc.
155
Schema (Continued)
Name Dns2 DnsSuffix IpRanges AllocatedIpAddresses Min 0 0 0 0 Max 1 1 1 1 Type IpAddressType xs:string IpRangesType IpAddressesType Description IPaddressofthesecondaryDNSserverforthis network Suffixtobeappliedwhenresolvinghostnamesthat arenotfullyqualified. ReadonlycontainerforIpRangeelements. Listofaddressesallocatedtoconnectionstothis network.MustfallwithinanyspecifiedIpRanges.
IpRange
TheIpRangeelementdefinesarangeofIPaddressesavailableonanetwork. Schema
Name StartAddress EndAddress Min 1 1 Max 1 1 Type IpAddressType IpAddressType Description LowestIPaddressintherange HighestIPaddressintherange
Features
TheFeatureselementdefinestheDHCPandfirewallfeaturesofanetwork. Schema
Name DhcpService FirewallService NatService Min 0 0 0 Max 1 1 1 Type DhcpServiceType FirewallServiceType NatServiceType Description SpecifiesthepropertiesofthenetworksDHCPservice Definesthefirewallservicecapabilitiesofthenetwork DefinestheNATservicecapabilitiesofthenetwork
DhcpService
TheDhcpServiceelementspecifiesthepropertiesofthenetworksDHCPservice. Schema
Name IsEnabled DefaultLeaseTime MaxLeaseTime IpRange Min 0 0 0 0 Max 1 1 1 1 Type xs:boolean xs:int xs:int IpRangeType Description Trueiftheserviceisenabled DefaultdurationofaDCHPaddresslease MaximumdurationofaDCHPaddresslease. RangeofIPaddressesavailabletoDHCPclients
FirewallService
TheFirewallServiceelementdefinesthefirewallservicecapabilitiesofanetwork. Schema
Name IsEnabled FirewallRule Min 0 0 Max 1 n Type xs:boolean FirewallRuleType Description Trueiftheserviceisenabled Definesasinglefirewallrule
156
VMware, Inc.
FirewallRule
TheFirewallRuleelementdefinesasinglefirewallrule. Schema
Name IsEnabled Description Policy Protocols Port DestinationIp Min 0 0 0 0 1 1 Max 1 1 1 1 1 1 Type xs:boolean xs:string FirewallPolicyType ProtocolsType xs:int IpAddressType Description Trueiftheruleisenabled descriptionoftherule Specifieshowpacketsarehandledbythefirewall Specifiestheprotocolstowhichthisfirewallruleapplies Specifiesthenetworkporttowhichthisfirewallruleapplies. Avalueof1matchesanyport. SpecifiesthedestinationIPaddress,insidethefirewall,to whichthisfirewallruleapplies
Policy
ThePolicyelementofaFirewallRulespecifieshowpacketsarehandledbythefirewall.Table 92shows permittedvaluesforelementcontentandtheresultstheyproduce. Table 9-2. FirewallRule Policy Element Values
Value drop allow Result Droppacketsofthistype Allowpacketsofthistypetopassthroughthefirewall
Protocols
TheProtocolselementspecifiestheprotocolstowhichfirewallrulesapply. Schema
Name Tcp Udp Min 0 0 Max 1 1 Type xs:boolean xs:boolean Description TrueifthefirewallrulesapplytotheTCPprotocol TrueifthefirewallrulesapplytotheUDPprotocol
NatService
TheNatServiceelementdefinesthenetworkaddresstranslationcapabilitiesofanetwork. Schema
Name IsEnabled NatType Policy NatRule Min 0 0 0 0 Max 1 1 1 n Type xs:boolean NatTypeType NatPolicyType NatRuleType Description Trueiftheserviceisenabled SpecifieshowNetworkAddressTranslationis implementedbytheNATservice SpecifieshowpacketsarehandledbytheNATservice SpecifiesasingleNATrule
VMware, Inc.
157
NatType
TheNatTypeelementspecifieshownetworkaddresstranslationisimplementedbytheNATservice.Table 93 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-3. NatType Element Values
Value ipTranslation portForwarding Result NATserviceimplementedbyIPaddresstranslation NATserviceimplementedbynetworkportforwarding
Policy
ThePolicyelementofaNatServiceelementspecifieshowpacketsarehandledbytheNATservice.Table 94 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-4. NatService Policy Element Values
Value allowTraffic allowTrafficIn Result Packetsofthistypepassthroughthefirewallinbothdirections Onlyinboundpacketsofthistypepassthroughthefirewall
NatRule
TheNatRuleelementspecifiesasinglenetworkaddresstranslationrule. Schema
Name Description OneToOneBasicRule OneToOneVmRule PortForwardingRule VmRule Min 0 0 0 0 0 Max 1 1 1 1 1 Type xs:string NatOneToOneBasicRuleType NatOneToOneVmRuleType NatPortForwardingRuleType NatVmRuleType Description Optionaldescriptionoftherule Ignoredinthisrelease Specifiesnetworkaddresstranslationdetailsfor asinglevirtualmachine MapsanIPaddressandportinanorganization networktoanexternalIPaddressandport MapsanIPaddressandportinavAppnetwork toanexternalIPaddressandport
OneToOneVmRule
TheOneToOneVmRuleelementdescribesaNATrulethatspecifiesnetworkaddresstranslationdetailsfora singlevirtualmachine.TheexternalIPaddresscanbespecifiedmanuallyorassignedautomaticallyat deploymenttime.TheinternalIPaddressisdiscoveredbylookingupthespecifiedVmReferenceandNICID. Schema
Name MappingMode ExternalIP VAppScopedVmId VmNicId Min 1 0 1 1 Max 1 1 1 1 Type NatMappingModeType IpAddressType xs:string xs:int Description SpecifieshowIPaddressmappingisimplementedby theNATservice IfMappingModeismanual,specifiestheexternalIP addressofthisVm Readonlyidentifiercreatedonimport DevicenumberoftheNIConthereferencedvirtual machine
158
VMware, Inc.
MappingMode
TheMappingModeelementspecifieshowIPaddressmappingisimplementedbytheNATservice.Table 95 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-5. MappingMode Element Values
Value manual automatic Result TheexternalIPaddressisspecifiedintheExternalIPelement TheexternalIPaddressisassignedautomatically
PortForwardingRule
ThePortForwardingRuleelementdescribesaNATrulethatmapsanIPaddressandportinanorganization networktoanexternalIPaddressandport. Schema
Name ExternalIP ExternalPort InternalIP InternalPort Protocol Min 1 1 1 1 1 Max 1 1 1 1 1 Type IpAddressType xs:int IpAddressType xs:int Layer4ProtocolType Description IPaddresstowhichthisNATrulemapstheIPaddress specifiedintheInternalIPelement NetworkporttowhichthisNATrulemapstheportnumber specifiedintheInternalPortelement IPaddresstowhichthisNATrulemapstheIPaddress specifiedintheExternalIpelement. NetworkporttowhichthisNATrulemapstheportnumber specifiedintheExternalPortelement. Specifiesthenetworkprotocoltowhichthisruleapplies
VmRule
TheVmRuleelementdescribesaNATrulethatmapsanIPaddressandportinavAppnetworktoanexternal IPaddressandport.TheexternalIPaddress,externalport,andinternalportarespecifiedintheelement.The internalIPaddressisdiscoveredbylookingupthespecifiedVmReferenceandVmNicId. Schema
Name ExternalIP ExternalPort VAppScopedVmId VmNicId InternalPort Protocol Min 0 1 1 1 1 1 Max 1 1 1 1 1 1 Type IpAddressType xs:int xs:string xs:int xs:int Layer4ProtocolType Description IPaddresstowhichthisNATrulemapstheIPaddress specifiedintheInternalIPelement. ThenetworkporttowhichthisNATrulemapstheport numberspecifiedintheInternalPortelement. Readonlyidentifiercreatedonimport ThedevicenumberoftheNIConthereferencedvirtual machine. ThenetworkporttowhichthisNATrulemapstheport numberspecifiedintheExternalPortelement. Specifiesthenetworkprotocoltowhichthisruleapplies
VMware, Inc.
159
Protocol
TheProtocolelementofaVmRuleelementspecifiesthenetworkprotocoltowhichthisruleapplies.Table 96 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-6. VmRule Protocol Element Values
Value TCP UDP TCP_UDP Result TheruleappliestotheTCPprotocol TheruleappliestotheUDPprotocol TheruleappliestotheTCPandUDPprotocols
Catalog
ACatalogelementisacontainerforCatalogItems.Anorganizationcancontainzeroormorecatalogs.Users withappropriateprivilegescanaddorremoveCatalogItemelementsfromacatalog. Content-Type application/vnd.vmware.vcloud.catalog+xml Object href prototype APIURL/catalog/id Schema
Name name anyattributename Link Description Tasks Min 1 0 0 0 0 Max 1 n n 1 1 Type xs:string any LinkType xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Linkstoactionsandcontainedobjects Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedtaskownedbythisobject. ReadonlycontainerforCatalogItemelements. Readonlyelement,trueifthecatalogispublished
CatalogItems IsPublished
0 0
1 1
CatalogItemsType xs:boolean
CatalogItems
TheCatalogItemselementisareadonlycontainerforindividualCatalogItemelements.
CatalogItem
TheCatalogItemelementcontainsareferencetoamediaimageorvApptemplateandoptionalrelated metadata. Content-Type application/vnd.vmware.vcloud.catalogItem+xml Object href prototype APIURL/catalogItem/id Schema
Name Entity Property Min 1 0 Max 1 n Type ReferenceType PropertyType Description Referencetothecataloguedobject Expressesakey=valuerelationship.(Inthisrelease, themaximumnumberoftheseelementsina CatalogItemislimitedtoten).
160
VMware, Inc.
Property
EachCatalogItemcanhaveuptotenPropertyelements,eachofwhichexpressesakey=valuerelationship. Thekeyisanattributevalue,andthevalueisthecontentofthePropertyelementitself.Thiselementcanbe usedtoholdarbitrarymetadataattachedtoaCatalogItem.ThevCloudAPIitselfmakesnouseofthis information. Schema
Name key Min 1 Max 1 Type xs:string Description Keyassociatedwiththestringvaluecontainedinthe element.Thelengthofthekeycannotexceed80 characters.Thelengthofthevaluecannotexceed256 characters.
Example 91illustratestheuseofthePropertyelementinaCatalogItem. Example 9-1. CatalogItem With Property Elements

<CatalogItem ... <Property key="Originator">Example Corp.</Property> <Property key="Project">Redwood</Property> </CatalogItem>
Media
TheMediaelementrepresentsvirtualmedia,suchasanISOorfloppyimage. Content-Type application/vnd.vmware.vcloud.media+xml Object href prototype APIURL/media/id Schema
Name name anyattributename status imageType Min 1 0 0 1 Max 1 n 1 1 Type xs:string any xs:int ImageType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Creationstatusoftheobject Oneof:

iso SpecifiesISO9660mediatype floppy Specifies3.5floppymediatype
size Description Files
1 0 0
1 1 1
xs:long xs:string FilesListType
Sizeofthemediafileinbytes Optionaldescription ReadonlycontainerforFileelements
VAppTemplate
AVAppTemplateisanabstractdescriptionofavApp.ItiscreatedwhenyouuploadanOVFpackagetoavDC. Content-Type application/vnd.vmware.vcloud.vAppTemplate+xml Object href prototype APIURL/vAppTemplate/vAppTemplateid Schema
Name status name Min 0 1 Max 1 1 Type xs:int xs:string Description CreationstatusoftheVAppTemplate. Commonobjectnameattribute
VMware, Inc.
161
Schema (Continued)
Name ovfDescriptorUploaded anyattributename Link Description Tasks Min 0 0 0 0 0 Max 1 n n 1 1 Type xs:boolean any LinkType xs:string TasksInProgressType Description TrueiftheOVFdescriptorforthetemplatehasbeen uploadedtothecontainingvDC. Includestype,href,XMLnamespaceidentifiers Linkstoactionsandcontainedobjects Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedtaskownedbythisobject. Filesthatarepartofthetemplate ReadonlycontainerforVmelementsrepresenting virtualmachines Anyofthefollowingovf:Section_Typeelements:

Files Children Section
0 0 0
n 1 n
FilesListType VAppChildrenType ovf:Section_Type
LeaseSettingsSection StartupSection NetworkConfigSection CustomizationSection
VAppScopedLocalId
xs:string
Readonlyidentifiercreatedonimport
Children
TheChildrenelementisareadonlycontainerforthevirtualmachines(Vmelements)thataremembersofa vApporvAppTemplate.
VApp
AVAppelementrepresentsavApp,whichistheresultofinstantiationofavApptemplate. Content-Type application/vnd.vmware.vcloud.vApp+xml Object href prototype APIURL/vApp/vappid Schema
Name deployed status name ovfDescriptorUploaded anyattributename Link Description Tasks Min 0 0 1 0 0 0 0 0 Max 1 1 1 1 n n 0 1 Type xs:boolean xs:int xs:string xs:boolean any LinkType xs:string TasksInProgressType Description TrueifthevAppisdeployed CreationstatusofthevApp Commonobjectnameattribute TrueiftheassociatedOVFdescriptorhasbeen uploaded Includestype,href,XMLnamespaceidentifiers ActionlinkstovAppoperations Optionaldescription ReadonlycontainerforTaskelements.Eachelement inthecontainerrepresentsaqueued,running,or failedtaskownedbythisobject. Unsupportedinthisrelease
VAppParent
ReferenceType
162
VMware, Inc.
Schema (Continued)
Name Section Min 0 Max n Type ovf:Section_Type Description Anyofthefollowingovf:Section_Typeelements:

Children
VAppChildrenType
ReadonlycontainerforVmelementsrepresenting virtualmachines
Vm
AVmrepresentsavirtualmachine,amemberofavAppsChildrencontainer. Content-Type application/vnd.vmware.vcloud.vApp+xml Object href prototype APIURL/vAppTemplate/vmidorAPIURL/vApp/vmid Schema
Name deployed status name anyattributename Link Description Tasks Min 0 0 1 0 0 0 0 Max 1 1 1 n n 1 1 Type xs:boolean xs:int xs:string any LinkType xs:string TasksInProgressType Description TrueiftheVmisdeployed CreationstatusoftheVm Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Actionlinkstooperations Optionaldescription ReadonlycontainerforTaskelements.Eachelement inthecontainerrepresentsaqueued,running,or failedtaskownedbythisobject. Unsupportedinthisrelease Anyofthefollowingovf:Section_Typeelements:

VAppParent Section
0 0
1 n
ReferenceType ovf:Section_Type
VAppScopedLocalId
xs:string
Readonlyidentifiercreatedonimportorcomposition
Section
AVAppTemplate,VApp,andVmcancontainanarbitrarynumberofovf:SectionTypeelements.InavAppor Vm,someoftheseelementscanbespecifiedasinstantiationparameters.Theothersarecopiedfromthesource OVFEnvelopeandtreatedasreadonlybythevCloudAPI. ThefollowingsectiontypesareallowedinavApporvAppTemplate:

VMware, Inc.
163
ThefollowingsectiontypesareallowedinaVm:

LeaseSettingsSection
TheLeaseSettingsSectionelementdefinesthetermsofstorageanddeploymentleasesforavApp. Content-Type application/vnd.vmware.vcloud.leaseSettingsSection+xml Schema
Name ovf:required type href ovf:Info Min 0 0 0 1 Max 1 1 1 1 Type xs:boolean xs:string xs:anyURI ovf: Msg_Type LinkType xs:string xs:string xs:dateTime xs:dateTime Description Optionalindicationofwhetherthiselementisrequired Mediatypeofthissection URLtoaccessthissection Requiredbythebaseovf:Section_Type.Itcancontain xs:stringinformationaboutthecontainingelement,or canbeempty Configurationlinks Durationofthedeploymentlease,inseconds Durationofthestoragelease,inseconds Dateandtimewhenthedeploymentleaseexpires Dateandtimewhenthestorageleaseexpires
Link DeploymentLeaseInSeconds StorageLeaseInSeconds DeploymentLeaseExpiration StorageLeaseExpiration
0 0 0 0 0
n 1 1 1 1
StartupSection
InanOVFpackageorVAppthatcontainsmultiplevirtualmachines,theStartupSectionspecifiestheorder inwhichthevirtualmachines(VirtualSystemsinanOVFVirtualSystemCollectionorthe VAppChildrenofaVApp)arepoweredon. Content-Type application/vnd.vmware.vcloud.startupSection+xml
CustomizationSection
TheCustomizationSectionelementofaVAppcontainsinformationabouthowcustomizationistobe appliedtothevirtualmachinesinthevApp. Content-Type application/vnd.vmware.vcloud.customizationSection+xml Schema
Name ovf:required type href ovf:Info Min 0 0 0 1 Max 1 1 1 1 Type xs:boolean xs:string xs:anyURI ovf:Msg_Type Description Optionalindicationofwhetherthiselementisrequired Mediatypeofthissection URLtoaccessthissection Requiredbythebaseovf:Section_Type.Itcancontain xs:stringinformationaboutthecontainingelement,or canbeempty
164
VMware, Inc.
Schema (Continued)
Name CustomizeOnInstantiate Min 1 Max 1 Type xs:boolean Description Iftrue,thencustomizationisexecutedforallchildrenthat includeaGuestCustomizationSection.Defaultvalueis false. Configurationlinks
Link
LinkType
NetworkConfigSection
TheNetworkConfigSectionelementspecifiestheconfigurationofavAppnetwork. Content-Type application/vnd.vmware.vcloud.networkConfigSection+xml Schema
Name ovf:required type href ovf:Info Min 0 0 0 1 Max 1 1 1 1 Type xs:boolean xs:string xs:anyURI ovf:Msg_Type Description Optionalindicationofwhetherthiselementis required Mediatypeofthissection URLtoaccessthissection Requiredbythebaseovf:Section_Type.Itcan containxs:stringinformationaboutthe containingelement,orcanbeempty Configurationlinks DefinestheconfigurationofaVAppnetwork
Link NetworkConfig
0 0
n n
LinkType VAppNetworkConfigurationType
NetworkConfig
TheNetworkConfigelementdefinestheconfigurationofavAppnetwork. Schema
Name networkName Description Configuration IsDeployed Min 1 0 1 0 Max 1 1 1 1 Type xs:string xs:string NetworkConfigurationType xs:boolean Description NameofthevAppNetwork Optionaldescriptionofthenetwork Propertiesofthenetwork Trueifthenetworkhasbeendeployed (readonly)
NetworkConnectionSection
TheNetworkConnectionSectionelementspecifieshowaVmisconnectedtoavAppnetwork.Itextendsthe ovf:NetworkConnectionelement. NOTETheOVFNetworkSectionelementandthevCloudAPINetworkConnectionSectionelement specifymanyofthesameparametersforanetworkconnection.IfbotharepresentinaVmbody,thevalues specifiedintheNetworkConnectionSectionoverridethosespecifiedintheNetworkSection. Content-Type application/vnd.vmware.vcloud.networkConnectionSection+xml Schema
Name ovf:required type Min 0 0 Max 1 1 Type xs:boolean xs:string Description Optionalindicationofwhetherthis elementisrequired Mediatypeofthissection
VMware, Inc.
165
Schema (Continued)
Name href ovf:Info Min 0 1 Max 1 1 Type xs:anyURI ovf:Msg_Type Description URLtoaccessthissection Requiredbythebase ovf:Section_Type.Itcancontain xs:stringinformationaboutthe containingelement,orcanbeempty Thevalueofthe rasd:AddressOnParentelementof thedevice(NIC)supportingthe primarynetworkconnectiontothe containingvirtualmachine. Describesasinglenetworkconnection Configurationlinks
PrimaryNetworkConnectionIndex
xs:int
NetworkConnection Link
0 0
n n
NetworkConnectionType LinkType
NetworkConnection
TheNetworkConnectionelementdescribesasinglenetworkconnection. Schema
Name anyattributename network NetworkConnectionIndex Min 0 1 1 Max n 1 1 Type any xs:string xs:int Description Includestype,href,XMLnamespace identifiers Thenameofthenetworktowhichthis connectionconnects. Thevalueinthe rasd:AddressOnParentelementofthe devicesupportingthisconnection. IPaddressofthisconnection IfthenetworkthattheNICisconnected tohasNATorportmapping,the externaladdressispopulatedinthis element. IfthevAppisdeployed,specifiesthe currentstateofitsconnection.Ifthe vAppisundeployed,specifieswhether thisconnectionshouldbeconnectedat deploymenttime. MACaddressofthisconnection SpecifieshowanIPaddressisallocated tothisconnection
IpAddress ExternalIpAddress
0 0
1 1
IpAddressType IpAddressType
IsConnected
xs:boolean
MACAddress IpAddressAllocationMode
0 1
1 1
xs:string IpAddressAllocationModeType
IpAddressAllocationMode
TheIpAddressAllocationModeelementspecifieshowanIPaddressisallocatedtothisconnection.Table 97 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-7. IpAddressAllocationMode Element Values
Value NONE MANUAL POOL DHCP Result NoIPaddressingmodespecified StaticIPaddressassignedmanually StaticIPaddressallocatedfromapool IPaddressassignedbyDHCP
166
VMware, Inc.
VirtualHardwareSection
TheVirtualHardwareSectionelementofanovf:VirtualSystemorVmcontainsadescriptionofthevirtual hardwaresupportedbyavirtualmachine. Content-Type application/vnd.vmware.vcloud.virtualHardwareSection+xml
OperatingSystemSection
TheOperatingSystemSectionelementofanovf:VirtualSystemorVmspecifiestheguestoperatingsystem installedonthevirtualmachine. Content-Type application/vnd.vmware.vcloud.operatingSystemSection+xml
GuestCustomizationSection
TheGuestCustomizationSectionelementofaVmcontainscustomizationparametersfortheguest operatingsystemofthevirtualmachine. Content-Type application/vnd.vmware.vcloud.guestCustomizationSection+xm Schema
Name ovf:required type href ovf:Info Min 0 0 0 1 Max 1 1 1 1 Type xs:boolean xs:string xs:anyURI ovf:Msg_Type Description Optionalindicationofwhetherthiselementisrequired Mediatypeofthissection URLtoaccessthissection Requiredbythebaseovf:Section_Type.Itcancontain xs:stringinformationaboutthecontainingelement,or canbeempty Configurationlinks Iftrue,toenableguestcustomizationatpoweron Iftrue,customizationwillrunsyspreptochangethe WindowsSIDforthisvirtualmachine Uniqueidentifierforthisvirtualmachine(readonly) Iftrue,thisvirtualmachinecanjoinaWindowsdomain Iftrue,thisvirtualmachineusesthecontaining organizationsdefaultvaluesforWindowsdomainname, domainusername,anddomainuserpassword IfUseOrgSettingsisfalse,specifiestheWindows domaintojoin.RequiredifJoinDomainEnabledistrue. IfUseOrgSettingsisfalse,specifiestheWindows domainusername.RequiredifJoinDomainEnabledis true. IfUseOrgSettingsisfalse,specifiestheWindows domainuserspassword.Requiredif JoinDomainEnabledistrue. Trueiftheadministratorpasswordshouldbereset. Trueifthelocaladministratorpasswordshouldbe automaticallygenerated Localadministratorpasswordforthisvirtualmachine Iftrue,thelocaladministratormustresethispasswordon firstuse Thiselementcontainsthecustomizationscripttorun NameofthisvirtualmachineinDNSorWindowsdomain
Link Enabled ChangeSid VirtualMachineId JoinDomainEnabled UseOrgSettings
0 0 0 0 0 0
n 1 1 1 1 1
LinkType xs:boolean xs:boolean xs:int xs:boolean xs:boolean
DomainName DomainUserName
0 0
1 1
xs:string xs:string
DomainUserPassword
xs:string
AdminPasswordEnabled AdminPasswordAuto AdminPassword ResetPasswordRequired CustomizationScript ComputerName
0 0 0 0 0 0
1 1 1 1 1 1
xs:boolean xs:boolean xs:string xs:boolean xs:string xs:string
VMware, Inc.
167
RasdItemsList
ARasdItemsListelementisareadonlycontainerforgroupsofrelatedovf:Itemelementssuchashard disks,networkcards,andmediadevices.VmelementstypicallycontainseveralLinkelementsthatreference elementsofthistype. Content-Type application/vnd.vmware.vcloud.rasdItemsList+xml
ScreenTicket
AScreenTicketelementcontainsastringthatrepresentsascreenticket(requiredtoaccessavirtual machinesconsole). Content-Type application/vnd.vmware.vcloud.screenTicket+xml
TasksList
TheTasksListelementisareadonlycontainerforTaskelementsthatrepresentqueued,running,orrecently completedtasksownedbyamemberoftheorganizationthatcontainstheTasksList. Content-Type application/vnd.vmware.vcloud.tasksList+xml
Tasks
TheTaskselementisareadonlycontainerforTaskelementsownedbythecontainingobject.Tasksshown inthiselementalsoappearintheTasksListoftheorganizationthatcontainstheobject.
Task
Whenevertheresultofarequestcannotbereturnedimmediately,theservercreatesaTaskobject.Tasks ownedbyanobjectsuchasavApporvDCarecontainedintheTaskselementoftheobjectsXML representation.EachTaskinaTasksorTasksListelementcontainsalltheinformationaboutthetask.AGET requesttoanindividualtaskshrefdoesnotreturnanyadditionalinformationaboutthetask. Thiselementisreadonly. Content-Type application/vnd.vmware.vcloud.taskt+xml Schema
Name status Min 1 Max 1 Type TaskStatusType Description Thecurrentstatusofthetask.Oneof:

queued Thetaskhasbeenqueuedforexecution. running Thetaskisrunning. success Thetaskhascompletedandreturnedavalueindicating success. error Thetaskhascompletedandreturnedavalueindicatingan error.
operation startTime endTime expiryTime href
0 0 0 0 0
1 1 1 1 1
xs:string xs:dateTime xs:dateTime xs:dateTime xs:anyURI
Descriptionoftheoperationbeingtrackedbythetask Dateandtimewhenthetaskwasstarted. Dateandtimewhenthetaskcompleted.Doesnotappearforrunning tasks. Dateandtimeatwhichthetaskexpires.Bydefault,tasksexpire24 hoursaftertheirstarttime.Expiredtaskscannotbequeried. Linktothetask
168
VMware, Inc.
Schema (Continued)
Name Owner Min 0 Max 1 Type ReferenceType Description Alinktotheobjectthatownsthetask.Forcopyoperations,theowner isthecopythatisbeingcreated.Fordeleteoperations,theowneristhe deletedobject,sothiselementisnotincluded.Forallotheroperations, theowneristheobjecttowhichtherequestwasmade. Errormessageorrelatedinformationreturnedbythetask
Error
ErrorType
VMware, Inc.
169
170
VMware, Inc.
10
Request Parameters Reference
10
ThischapterprovidesreferenceinformationabouttherequestparametersdefinedinthisreleaseofthevCloud API.Elementsdocumentedinthischapterprovideparameterstorequeststhatcreate,delete,modify,or changethestateofanobject.FormoreinformationabouthowthevCloudAPIusesXMLtorepresentobjects, andhowthisreferencematerialisorganized,seeXMLRepresentationsinthevCloud APIonpage 141 Thischapterprovidesreferencematerialonthefollowingelementsandtheelementstheycontain:

UploadVAppTemplateParamsonpage 171 InstantiateVAppTemplateParamsonpage 172 InstantiationParamsonpage 172 ComposeVAppParamsonpage 173 RecomposeVAppParamsonpage 174 DeployVAppParamsonpage 175 UndeployVAppParamsonpage 175 CaptureVAppParamsonpage 175 CloneMediaParamsonpage 176 CloneVAppTemplateParamsonpage 176 CloneVAppParamsonpage 176 MediaInsertOrEjectParamsonpage 177 VmPendingQuestiononpage 177 VmQuestionAnsweronpage 177 ControlAccessParamsonpage 177
UploadVAppTemplateParams
TheUploadVAppTemplateParamselementformsthebodyofanuploadVappTemplaterequest. Content-Type application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml Schema
Name name Description transferFormat manifestRequired Min 1 0 0 0 Max 1 1 1 1 Type xs:string xs:string xs:string xs:boolean Description Specifiesthenamegiventothetemplate Descriptionofthetemplate Ignoredinthisrelease Trueiftheuploadincludesamanifestfile
VMware, Inc.
171
InstantiateVAppTemplateParams
TheInstantiateVAppTemplateParamselementformsthebodyofaninstantiateVappTemplaterequest. Content-Type application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml Schema
Name name linkedClone deploy powerOn Description VAppParent Source IsSourceDelete InstantiationParams Min 1 0 0 0 0 0 1 0 0 Max 1 1 1 1 1 1 1 1 1 Type xs:string xs:boolean xs:boolean xs:boolean xs:string ReferenceType ReferenceType xs:boolean InstantiationParamsType Description SpecifiesthenameofthevAppcreatedbythis instantiation Ignoredinthisrelease TrueifthevAppshouldbedeployedafter instantiation.Defaultstofalse. TrueifthevAppshouldbedeployedandpoweredon afterinstantiation.Defaultstofalse. Optionaldescription.UsedfortheDescriptionofthe vAppcreatedbythisinstantiation. Unsupportedinthisrelease AreferencetothevApptemplatetoinstantiate TrueiftheobjectreferencedbySourceshouldbe deletedafterthecopyismade Containerforanyofthefollowing ovf:Section_Typeelements:

AllEULAsAccepted
xs:boolean
Trueifyouacceptthetermsandconditionsinthe templatesEULAsections.Instantiationfailsiffalse.
InstantiationParams
TheInstantiationParamselementcontainszeroormoreovf:Section_Typeelementsthatspecifythe configurationofavApporvirtualmachine. Schema
Name Section Min 0 Max n Type ovf:Section_Type Description AnypermittedOVFSectiontype
AnInstantiationParamselementcanappearinanumberofrequestbodies,including InstantiateVAppTemplateParams,ComposeVAppParams,RecomposeVAppParams,andCloneVAppParams. ThecontaineroftheInstantiationParamselementdetermineswhatsectiontypesitcancontain.
InstantiationParamscontainedbyanItemelementthatspecifiesaVmasitsSourcecancontainthe followingsectiontypes:

VirtualHardwareSection OperatingSystemSection NetworkConnectionSection
172
VMware, Inc.
Chapter 10 Request Parameters Reference
InstantiationParamscontainedbyanyotherelementapplytoavAppandcancontainthefollowing sectiontypes:

ComposeVAppParams
TheComposeVAppParamselementformsthebodyofacomposeVapprequest. Content-Type application/vnd.vmware.vcloud.composeVAppParams+xml Schema
Name name Description deploy powerOn Min 1 0 0 0 Max 1 1 1 1 Type xs:string xs:string xs:boolean xs:boolean Description SpecifiesthenameofthevAppcreatedbythis composition Optionaldescription.Usedforthe DescriptionofthecomposedvApp TrueifthevAppshouldbedeployedafter composition.Defaultstofalse. TrueifthevAppshouldbedeployedand poweredonaftercomposition.Defaultsto false. Ignoredinthisrelease. Unsupportedinthisrelease. Containerforanyofthefollowing ovf:Section_Typeelements:

linkedClone VAppParent InstantiationParams
0 0 0
1 1 1
xs:boolean ReferenceType InstantiationParamsType
Item AllEULAsAccepted
0 0
n 1
CompositionItemParamsType xs:boolean
SpecifiesasourcevAppTemplate,vApp,orVm toincludeinthecomposition Trueifyouacceptthetermsandconditionsin thetemplatesEULAsections.Composition failsiffalse.
Item
AnItemelementisacontainerforinformationaboutavApptemplate,vApp,orvirtualmachinetobeused whencomposingorrecomposingavApp. Schema
Name sourceDelete Min 0 Max 1 Type xs:boolean Description IftheobjectreferencedinSourceisaVm,this attributespecifieswhethertheVmshouldbe removedfromitsparentvApporcopied. IgnorediftheobjectreferencedinSourceisnot aVm. AreferencetoavAppTemplate,vApp,orVmto includeinthecomposition
Source
ReferenceType
VMware, Inc.
173
Schema (Continued)
Name VAppScopedLocalId Min 0 Max 1 Type xs:string Description IftheobjectreferencedinSourceisaVm,this elementcanbeusedtoprovideaunique identifierforthisVminthecomposedvApp. RequiredifSourceisaVm,andcancontainfor anyofthefollowingovf:Section_Type elements:

InstantiationParams
InstantiationParamsType
VirtualHardwareSection OperatingSystemSection NetworkConnectionSection
NetworkAssignment
NetworkAssignmentType
MapslogicalnetworksintheSourcetological networksinthecomposedvApp
Formoreinformation,seeComposeavApponpage 65.
NetworkAssignment
WhenavAppincludesVmelementsthatconnecttonetworkswithdifferentnames,youcanusea NetworkAssignmentelementtoassignthenetworkconnectionforeachVmtoaspecificnetworkintheparent vApp. Schema
Name innerNetwork containerNetwork Min 1 1 Max 1 1 Type xs:string xs:string Description NameofthenetworkintheVm NameofthevAppnetworktowhichinnerNetworkismapped
RecomposeVAppParams
TheRecomposeVAppParamselementformsthebodyofarecomposeVapprequest.Thiselementallowsan arbitrarynumberofDeleteItemelements,butisotherwiseidenticaltoComposeVAppParams. Content-Type application/vnd.vmware.vcloud.recomposeVAppParams+xml Schema
Name name Description deploy powerOn Min 1 0 0 0 Max 1 1 1 1 Type xs:string xs:string xs:boolean xs:boolean Description SpecifiesthenameofthevAppcreatedbythis composition Optionaldescription.Usedforthe DescriptionofthecomposedvApp TrueifthevAppshouldbedeployedafter composition.Defaultstofalse. TrueifthevAppshouldbedeployedand poweredonaftercomposition.Defaultsto false. Ignoredinthisrelease. Unsupportedinthisrelease containerforanyofthefollowing ovf:Section_Typeelements:

linkedClone VAppParent InstantiationParams
0 0 0
1 1 1
xs:boolean ReferenceType InstantiationParamsType
174
VMware, Inc.
Schema (Continued)
Name Item DeleteItem AllEULAsAccepted Min 0 0 0 Max n n 1 Type CompositionItemParamsType ReferenceType xs:boolean Description SpecifiesasourcevAppTemplate,vApp,orVm toincludeinthecomposition ReferencetoaVmtoremovefromthevApp Trueifyouacceptthetermsandconditionsin thetemplatesEULAsections.Composition failsiffalse.
DeployVAppParams
TheDeployVAppParamselementformsthebodyofadeployrequest. Content-Type application/vnd.vmware.vcloud.deployVAppParams+xml Schema
Name powerOn deploymentLeaseSeconds Min 0 0 Max 1 1 Type xs:boolean xs:int Description TrueifthevAppshouldbepoweredonafterdeployment Durationofthedeploymentlease,inseconds
UndeployVAppParams
TheUndeployVAppParamselementformsthebodyofanundeployrequest. Content-Type application/vnd.vmware.vcloud.undeployVAppParams+xml Schema
Name saveState Min 0 Max 1 Type xs:boolean Description Trueifpoweredonchildrenshouldbesuspendedandtheirstatesaved beforeundeployment.Defaultisfalse,specifyingthatchildrenarepowered off.
CaptureVAppParams
TheCaptureVAppParamselementformsthebodyofacaptureVapprequest. Content-Type application/vnd.vmware.vcloud.captureVAppParams+xml Schema
Name name Description Source Min 1 0 1 Max 1 1 1 Type xs:string xs:string ReferenceType Description SpecifiesthenameofthevAppTemplatecreatedbythisoperation Optionaldescription.UsedfortheDescriptionofthevAppTemplate createdbythisoperation. ReferencetothevApptocapture.
VMware, Inc.
175
CloneMediaParams
TheCloneMediaParamselementformsthebodyofacloneMedia request. Content-Type application/vnd.vmware.vcloud.cloneMediaParams+xml Schema
Name name Description Source IsSourceDelete Min 1 0 1 0 Max 1 1 1 1 Type xs:string xs:string ReferenceType xs:boolean Description Specifiesthenameofthenewmediaimagecreatedbytheclone operation Optionaldescription.UsedfortheDescriptionofthecloned Mediaimage. Referencetothemediaimagetoclone(copy) TrueiftheobjectreferencedbySourceshouldbedeletedafter thecopyismade
CloneVAppTemplateParams
TheCloneVAppTemplateParamselementformsthebodyofacloneVAppTemplaterequest. Content-Type application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml Schema
Name name Description Source IsSourceDelete Min 1 0 1 0 Max 1 1 1 1 Type xs:string xs:string ReferenceType xs:boolean Description SpecifiesthenameofthenewvApptemplate createdbythecloneoperation Optionaldescription.UsedfortheDescriptionof theclonedvApptemplate ReferencetothevAppTemplatetoclone(copy) TrueiftheobjectreferencedbySourceshould bedeletedafterthecopyismade
CloneVAppParams
TheCloneVAppParamselementformsthebodyofacloneVapprequest. Content-Type application/vnd.vmware.vcloud.cloneVAppParams+xml Schema
Name name Description deploy powerOn linkedClone VAppParent InstantiationParams Min 1 0 0 0 0 0 0 Max 1 1 1 1 1 1 1 Type xs:string xs:string xs:boolean xs:boolean xs:boolean ReferenceType InstantiationParamsType Description SpecifiesthenameoftheclonedvApp CommonDescriptionelement.Usedforthe Descriptionoftheclone Trueifthecloneshouldbedeployed.Defaultsto false. Trueifthecloneshouldbedeployedand poweredon.Defaultstofalse. Ignoredinthisrelease Unsupportedinthisrelease Containerforanyofthefollowing ovf:Section_Typeelements:

176
VMware, Inc.
Schema (Continued)
Name Source IsSourceDelete Min 1 0 Max 1 1 Type ReferenceType xs:boolean Description ReferencetothevApptoclone(copy) TrueiftheobjectreferencedbySourceshould bedeletedafterthecopyismade
MediaInsertOrEjectParams
AMediaInsertOrEjectParamselementformsthebodyofaninsertMediaorejectMediarequest. Content-Type application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml Schema
Name Media Min 1 Max 1 Type ReferenceType Description Referencetoamediaimagetoinsertoreject
VmPendingQuestion
TheVmPendingQuestionelementcontainsarequestfromavirtualmachineforuserinput. Content-Type application/vnd.vmware.vcloud.vmPendingQuestion+xml Schema
Name Question QuestionId Choices Min 1 1 1 Max 1 1 n Type xs:string xs:int VmQuestionAnswerChoiceType Description Thequestionrequiringuseinput. Questionidentifier Allowableanswers
VmQuestionAnswer
TheVmQuestionAnswerelementcontainsuserinputtoaspecificVmPendingQuestionrequest. Content-Type application/vnd.vmware.vcloud.vmPendingAnswer+xml Schema
Name ChoiceId QuestionId Min 1 1 Max 1 1 Type xs:int xs:int Description Theanswertoprovide Questionidentifier
ControlAccessParams
TheControlAccessParamselementappearsinCatalogsandvApps.Thiselementcanbereadbyallusersbut canbemodifiedonlybyadministratorsandprivilegedusers. Content-Type application/vnd.vmware.vcloud.controlAccess+xml Schema
Name IsSharedToEveryone EveryoneAccessLevel AccessSettings Min 1 0 0 Max 1 1 1 Type xs:boolean AccessLevelType AccessSettingsType Description Trueifthisobjectissharedwitheveryoneinthe organization.Defaultstofalse. IfIsSharedToEveryoneistrue,thiselementmustbe presentanddeterminestheaccesslevel AcontainerforAccessSettingelements.Thiselement mustbepresentandnotemptyifIsSharedToEveryone isfalse.
VMware, Inc.
177
AccessSettings
TheAccessSettingselementisacontainerforAccessSettingelements.Thiscontainermustbepresentand notemptyifthevalueofIsSharedToEveryoneinthecontainingControlAccessParamselementissetto false.
AccessSetting
AnAccessSettingelementdefinesthelevelofaccessgrantedtotheuserorgroupreferencedintheSubject element. Schema
Name Subject AccessLevel Min 1 1 Max 1 1 Type ReferenceType AccessLevelType Description ReferencetotheuserorgrouptowhichthespecifiedAccessLevel applies. Specifiestheaccesslevelallowedfortheuserorgroupsspecifiedin Subject
AccessLevel
TheAccessLevelelementspecifiestheaccesslevelallowedfortheuserorgroupspecifiedinSubject. Table 101showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 10-1. AccessLevel Element Values
Value FullControl Change ReadOnly Result Subjecthasfullcontrolofthisobject Subjectcanchangethisobject Subjecthasreadaccesstothisobject
178
VMware, Inc.
11
Administrative API Reference
11
ThischapterprovidesreferenceinformationabouttheXMLelementsthatsupportadministrativeoperations inthevCloudAPI.Elementsdocumentedinthischapteraregenerallyreadablebyallusers,butcanbecreated andmodifiedonlybyasystemadministrator,organizationadministratororotherprivilegeduser.Manyof theschemasshownhereextendelementsandcomplextypesthataredefinedintheuserAPI.Formore informationabouthowthevCloudAPIusesXMLtorepresentobjects,andhowthisreferencematerialis organized,seeXMLRepresentationsinthevCloud APIonpage 141. Thischapterprovidesreferencematerialonthefollowingelementsandtheelementstheycontain:

VCloudonpage 179 ExternalNetworkonpage 180 AdminOrgonpage 180 ProviderVdconpage 186 Useronpage 190 Grouponpage 191 Roleonpage 191
VCloud
ThevCloudelementisareadonlycontainerforreferencestotoplevelobjectsinavCloudinstance. Content-Type application/vnd.vmware.admin.vcloud+xml Object href prototype APIURL/admin Schema
Name OrganizationReferences ProviderVdcReferences RightReferences RoleReferences Networks Min 0 0 0 0 0 Max 1 1 1 1 1 Type OrganizationReferencesType ProviderVdcReferencesType RightReferencesType RoleReferencesType NetworksType Description AcontainerforreferencestoAdminOrgobjects inthevCloud AcontainerforreferencestoProviderVdc objectsinthevCloud AcontainerforreferencestoRightobjectsin thevCloud AcontainerforreferencestoRoleobjectsin thevCloud Acontainerforreferencesto ExternalNetworkobjectsinthevCloud.
VMware, Inc.
179
OrganizationReferences
TheOrganizationReferenceselementisareadonlycontainerforReferenceTypeelementsthatreference AdminOrgobjectsavCloud.Tocreateaneworganization,seeCreateanOrganizationonpage 95.
ProviderVdcReferences
TheProviderVdcReferenceselementisareadonlycontainerforReferenceTypeelementsthatreference ProviderVdcobjectsavCloud.TocreateaProviderVdc,seeCreateaProvidervDConpage 127.
RightReferences
TheRightReferenceselementisareadonlycontainerforReferenceTypeelementsthatreferencethe predefinedRightobjectsinavCloud.
RoleReferences
TheRoleReferenceselementisareadonlycontainerforReferenceTypeelementsthatreferenceRole objectsinavCloud.Tocreatearole,seeCreateaRoleonpage 114.
Networks
TheNetworkselementisareadonlycontainerforReferenceTypeelementsthatreferenceExternalNetwork objectsinavCloud.ToaddanetworktoanAdminOrg,seeAddaNetworktoanOrganizationonpage 100.
ExternalNetwork
AExternalNetworkelementdefinesanetworkthathasbeenallocatedtoanorganizationbythesystem administrator. Content-Type application/vnd.vmware.vcloud.admin.network+xml Object href prototype APIURL/admin/network/id Schema
Name name anyattributename Description Configuration ProviderInfo Min 1 0 0 0 1 Max 1 n 1 1 1 Type xs:string any xs:string NetworkConfigurationType xs:string Description Commonobjectnameattribute Includestype,href,XMLnamespace identifiers Optionaldescription Propertiesofthenetwork Readonlyinformationaboutthe underlyingvCenternetwork
AdminOrg
TheAdminOrgelementprovidesanadministrativeviewofanorganization.ItincludesallmembersoftheOrg element,andaddsseveralelementsthatcanbeviewedandmodifiedonlybysystemadministrators. Content-Type application/vnd.vmware.admin.organization+xml Object href prototype APIURL/admin/organization/id Schema
Name name anyattributename Min 1 0 Max 1 n Type xs:string any Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers
180
VMware, Inc.
Chapter 11 Administrative API Reference
Schema (Continued)
Name Description Tasks Min 0 0 Max 1 1 Type xs:string TasksInProgressType Description Optionaldescription ReadonlycontainerforTaskelements.Eachelementinthe containerrepresentsaqueued,running,orfailedtask ownedbythisobject. Fullnameoftheorganization Establishesquotasandpolicies,specifieshowthe organizationconnectstoLDAPandemailservices ContainerforReferenceTypeelementsthatreference usersintheorganization. ContainerforReferenceTypeelementsthatreference groupsintheorganization. ContainerforReferenceTypeelementsthatreference catalogsintheorganization. ContainerforReferenceTypeelementsthatreference vDCsintheorganization. ContainerforReferenceTypeelementsthatreference networksintheorganization.
FullName Settings Users Groups Catalogs Vdcs Networks
1 1 0 0 0 0 0
1 1 1 1 1 1 1
xs:string OrgSettingsType UsersListType GroupsListType CatalogsListType VdcsType NetworksType
Settings
TheSettingselementestablishesquotasandpoliciesfortheorganization.Italsocontainselementsthat specifythedetailsofhowtheorganizationconnectstoLDAPandemailservices. Schema
Name IsEnabled Min 0 Max 1 Type xs:boolean Description Trueifthisorganizationisenabled.Ifenabled, theorganizationallowsloginandallother operations. Trueifthisorganizationisallowedtopublish catalogs Maximumnumberofvirtualmachinesthatcan bedeployedsimultaneouslybyamemberof thisorganization MaximumnumberofvAppsorvApptemplates thatcanbestored(inanundeployedstate)bya memberofthisorganization Definesdefaultleasedurationsandrelated policies Defineswhetherthisorganizationisconnected toanLDAPservice,andwhetheritusesthe systemdefaultLDAPserviceoracustomLDAP service.Cannotbechangedafterthe organizationhasbeencreated. IfOrgLdapModeisSYSTEM,specifiesanLDAP attribute=valuepairtouseforOU (organizationalunit) Definesthehostnameandconnectiondetailsfor theorganizationsprimaryLDAPservice Definestheemailsettingsforthisorganization
CanPublishCatalogs DeployedVmQuota
0 0
1 1
xs:boolean xs:int
StoredVmQuota
xs:int
OrgLeaseSettings OrgLdapMode
0 0
1 1
OrgLeaseSettingsType LdapModeType
CustomUsersOu
xs:string
OrgLdapSettings OrgEmailSettings
0 0
1 1
OrgLdapSettingsType OrgEmailSettingsType
VMware, Inc.
181
Schema (Continued)
Name UseServerBootSequence DelayAfterPowerOnSeconds Min 0 0 Max 1 1 Type xs:boolean xs:int Description Trueifvirtualmachinesinthisorganizationuse theserverbootsequencebydefault Specifiesanorganizationdefaultforvirtual machinebootdelayafterpoweron
OrgLeaseSettings
TheOrgLeaseSettingselementdefinesdefaultleasedurationsandpoliciesfortheorganization. Schema
Name DeleteOnStorageLeaseExpiration Min 0 Max 1 Type xs:boolean Description Iftrue,storageforavAppisdeletedwhenthevApps leaseexpires.Iffalse,thestorageisflaggedfor deletion,butnotdeleted. DefaultdurationofavAppdeploymentlease,in seconds. Defaultdurationofastoragelease,inseconds.
DeploymentLeaseSeconds StorageLeaseSeconds
0 0
1 1
xs:int xs:int
OrgLdapMode
TheOrgLdapModeelementdefineswhetherthisorganizationisconnectedtoanLDAPservice,andwhetherit usesthesystemdefaultLDAPserviceoracustomLDAPservice.Table 111showspermittedvaluesfor elementcontentandtheresultstheyproduce. NOTEThevalueofOrgLdapModecannotbechangedaftertheorganizationhasbeencreated. Table 11-1. OrgLdapMode Element Values
Value NONE SYSTEM CUSTOM Result OrganizationdoesnotuseanLDAPservice. OrganizationusesthesystemdefaultLDAPservice. OrganizationusesacustomLDAPservicedefinedinOrgLdapSettings
OrgLdapSettings
IfOrgLdapModeisCUSTOM,theOrgLdapSettingselementdefinesthehostnameandconnectiondetailsforthe organizationsLDAPservice. Schema
Name HostName Port IsSsl IsSslAcceptAll Realm SearchBase Min 1 1 0 0 0 0 Max 1 1 1 1 1 1 Type xs:string xs:int xs:boolean xs:boolean xs:string xs:string Description HostnameoftheLDAPserver. PortatwhichtoconnecttotheLDAP service TrueiftheLDAPservicerequiresan SSLconnection TrueiftheLDAPserviceacceptsallSSL certificates LDAPrealmtousewhenlookingup users LDAPsearchbase
182
VMware, Inc.
Schema (Continued)
Name UserName Min 0 Max 1 Type xs:string Description Usernametousewhenlogginginto LDAP,specifiedusingLDAP attribute=valuepairs(forexample: cn="ldap-admin", dc="example", dc="com") Passwordfortheuseridentifiedby UserName.Thisvalueisnever returnedbyGET.Itisinspectedon createandmodify.Onmodify,the absenceofthiselementindicatesthat thepasswordshouldnotbechanged. Definestheauthenticationmechanism usedbytheLDAPservice LDAPgroupsearchbase Trueifthegroupsearchbaseisenabled DefinesthetypeoftheLDAPservice DefineshowLDAPattributesareused whenimportingauser DefineshowLDAPattributesareused whenimportingagroup
Password
xs:string
AuthenticationMechanism GroupSearchBase IsGroupSearchBaseEnabled ConnectorType UserAttributes GroupAttributes
1 0 1 1 1 1
1 1 1 1 1 1
LdapAuthentication MechanismType xs:string xs:boolean LdapConnectorType OrgLdapUserAttributesType OrgLdapGroupAttributesType
AuthenticationMechanism
TheAuthenticationMechanismelementdefinestheauthenticationmechanismusedbytheLDAPservice. Table 112showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 11-2. AuthenticationMechanism Element Values
Value SIMPLE KERBEROS MD5DIGEST NTLM Result LDAPconnectionusessimpleauthenticationasspecifiedinRFC2251andRFC2829. LDAPconnectionusesKerberosauthentication. LDAPconnectionusesDigestMD5authenticationasspecifiedinRFC2831. LDAPconnectionusesWindowsNTLMauthentication.
ConnectorType
TheConnectorTypeelementdefinesthetypeofanLDAPservice.Table 113showspermittedvaluesfor elementcontentandtheresultstheyproduce. Table 11-3. ConnectorType Element Values
Value ACTIVE_DIRECTORY OPEN_LDAP Result LDAPserviceisprovidedbyWindowsActiveDirectory LDAPserviceisprovidedbyOpenLDAP(seehttp://www.openldap.org).
VMware, Inc.
183
UserAttributes
IfOrgLdapModeisCUSTOM,theUserAttributeselementdefineshowLDAPattributesareusedwhen importingauser. Schema
Name ObjectClass ObjectIdentifier UserName Min 1 1 1 Max 1 1 1 Type xs:string xs:string xs:string Description LDAPobjectClassofwhichimportedusersare members.Forexample,userorperson LDAPattributetouseastheuniqueidentifierfora user.Forexample,objectGuid LDAPattributetousewhenlookingupausername toimport.Forexample,userPrincipalNameor samAccountName LDAPattributetousefortheusersemailaddress. Forexamplemail LDAPattributetousefortheusersfullname.For exampledisplayName LDAPattributetousefortheusersgivenname.For example,givenName LDAPattributetousefortheuserssurname.For examplesn LDAPattributetousefortheuserstelephone number.ForexampletelephoneNumber LDAPattributethatidentifiesauserasamemberof agroup.Forexample,dn LDAPattributethatreturnstheidentifiersofallthe groupsofwhichtheuserisamember
Email FullName GivenName Surname Telephone GroupMembershipIdentifier GroupBackLink
1 1 1 1 1 1 0
1 1 1 1 1 1 1
xs:string xs:string xs:string xs:string xs:string xs:string xs:string
GroupAttributes
IfOrgLdapModeisCUSTOM,theGroupAttributeselementdefineshowagroupisimportedfromLDAP. Schema
Name ObjectClass ObjectIdentifier GroupName Membership MembershipIdentifier BackLinkIdentifier Min 1 1 1 1 1 0 Max 1 1 1 1 1 1 Type xs:string xs:string xs:string xs:string xs:string xs:string Description LDAPobjectClassofwhichimportedgroupsaremembers.For example,group LDAPattributetouseastheuniqueidentifierforagroup.For example,objectGuid LDAPattributetouseforthegroupname.Forexample,cn LDAPattributetousewhengettingthemembersofagroup.For example,member LDAPattributethatidentifiesagroupasamemberofanother group.Forexample,dn LDAPgroupattributeusedtoidentifyagroupmember
184
VMware, Inc.
OrgEmailSettings
TheOrgEmailSettingselementdefinestheemailsettingsforanorganization. Schema
Name IsDefaultSmtpServer IsDefaultOrgEmail FromEmailAddress Min 1 1 1 Max 1 1 1 Type xs:boolean xs:boolean xs:string Description Trueifthisorganizationusesthesystemdefault SMTPserver Trueifthisorganizationusesthesystemdefault emailproperties. IfIsDefaultOrgEmailisfalse,specifiesthe sendersemailaddressthatappearsinemail notifications. IfIsDefaultOrgEmailisfalse,specifiesaprefix forsystememailnotifications. Trueifsystememailnotificationsshouldbesent toalluserswhohavetheAdministratorrole IfIsAlertEmailToAllAdminsisfalse,specifies alistofuserstoreceivesystememail notifications. IfIsDefaultSmtpServerisFalse,thiselement specifiesconnectiondetailsforanSMTPserver touse.
DefaultSubjectPrefix IsAlertEmailToAllAdmins AlertEmailTo
1 1 0
1 1 n
xs:string xs:boolean xs:string
SmtpServerSettings
SmtpServerSettingsType
SmtpServerSettings
IfIsDefaultSmtpServer(inOrgEmailSettings)isfalse,theSmtpServerSettingselementspecifies connectiondetailsfortheorganizationsSMTPserver. Schema
Name IsUseAuthentication Host Username Password Min 1 1 1 0 Max 1 1 1 1 Type xs:boolean xs:string xs:string xs:string Description TrueiftheSMTPserverrequiresauthentication HostnameoftheSMTPserver. UsernametousewhenloggingintotheSMTPservice. (RequiredifIsUseAuthenticationisTrue). PasswordfortheuseridentifiedbyUsername.Thisvalue isneverreturnedbyGET.Itisinspectedoncreateand modify.Onmodify,theabsenceofthiselementindicates thatthepasswordshouldnotbechanged.Requiredif IsUseAuthenticationistrue.
Users
TheUserselementisareadonlycontainerforReferenceTypeelementsthatreferenceusersinan organization.Toadduserstoanorganization,seeCreateorImportaUseronpage 110.
Groups
TheGroupselementisareadonlycontainerforReferenceTypeelementsthatreferencegroupsinan organization.Toaddgroupstoanorganization,seeImportaGrouponpage 113.
Catalogs
TheCatalogselementisareadonlycontainerforReferenceTypeelementsthatreferencethecatalogsinan organization.Toaddcatalogstoanorganization,seeCreateaCatalogonpage 107.
VMware, Inc.
185
Catalog
ACatalogelementisacontainerforCatalogItems.AnOrgorAdminOrgmaycontainzeroormoreCatalog elements.Tocreate,delete,ormodifyacatalog,anadministratormustaccessitusingtheadminURLand contenttypeshownhere. Content-Type application/vnd.vmware.vcloud.admin.catalog+xml Object href prototype vCloudURL/admin/catalog/catalogid FormoreinformationabouttheCatalogelementschema,seeCatalogonpage 160.Forinformationabout useroperationsonCatalogs,seeCatalogingvAppTemplatesandMediaImagesonpage 54.
PublishCatalogParams
ThePublishCatalogParamselementformsthebodyofapublishrequestforacatalog. Schema
Name IsPublished Min 1 Max 1 Type xs:boolean Description Settotruetopublishacatalog(makeitvisibletoallorganizations).Setto falsetounpublishacatalog.Thiselementcanbechangedonlyinapublish request.ItisReadonlyinaCatalogbody.
Vdcs
TheVdcselementisareadonlycontainerforReferenceTypeelementsthatreferencevDCsinan organization.ToaddavDCtoanorganization,seeAllocateavDCtoanOrganizationonpage 104.
ProviderVdc
AProviderVdcelementrepresentsaprovidervDCobject. Content-Type application/vnd.vmware.admin.providervdc+xml Object href prototype APIURL/admin/providervdc/id Schema
Name name anyattributename status Min 1 0 0 Max 1 n 1 Type xs:string any xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespace identifiers creationstatusoftheProviderVdc:

-1 Creationfailed 0 Notready 1 Ready 2 Unknown 3 Unrecognized
Description Tasks
0 0
1 1
Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsa queued,running,orfailedtaskownedby thisobject Definesthecomputecapacityavailablein thisprovidervDC Definesthestoragecapacityavailableinthis providervDC Containerforreferencesto ExternalNetworkobjectsprovisionedfrom thisprovidervDC.
ComputeCapacity StorageCapacity AvailableNetworks
0 0 0
1 1 1
RootComputeCapacityType ProviderVdcCapacityType AvailableNetworksType
186
VMware, Inc.
Schema (Continued)
Name Vdcs IsEnabled NetworkPoolReferences Min 0 0 0 Max 1 1 1 Type VdcsType xs:boolean NetworkPoolReferencesType Description ContainerforVdcobjectsthatare provisionedfromthisprovidervDC. TrueifthisprovidervDCisenabled ContainerforNetworkPoolReference objectsthatareprovisionedfromthis providervDC
ComputeCapacity
TheadministrativeviewofaComputeCapacityelementincludestwoelements:IsElasticandIsHa,thatan administratorcanchange.Theseelementsarenotvisibleintheuserview. Schema
Name Cpu Memory IsElastic IsHA Min 1 1 0 0 Max 1 1 1 1 Type ProviderVdcCapacityType ProviderVdcCapacityType xs:boolean xs:boolean Description DefinesCPUcapacityavailableintheprovidervDC DefinesmemorycapacityavailableintheprovidervDC Trueifcomputecapacitycangroworshrinkbasedondemand Trueifcomputecapacityishighlyavailable.
Cpu
UnliketheCpuelementthatappearsintheComputeCapacityofaVdc,theCpuelementthatappearsinthe ComputeCapacityofaProviderVdcisaninstanceofProviderVdcCapacityType.ItdefinestheCPU capacitythatcanbeallocatedfromavDCandoptionallyreportshowmuchofthatcapacityisinuse. Schema
Name Units Allocation Total Used Overhead Min 1 0 1 0 0 Max 1 1 1 1 1 Type xs:string xs:long xs:long xs:long xs:long Description Unitsinwhichthecapacityismeasured.ForCPUdevices,thisisalways Megahertz,representedbythestringMHz. NumberofUnitsthathavebeenallocatedtoconsumers MaximumnumberofUnitsthatcanbeallocatedtoallconsumers Percentageoftheallocationinuse.Thisvalueisreadonly,andisalways0if AllocationModelisAllocationVApp. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisvDC.Thisvalueisreadonly,andisalways0ifAllocationModelis AllocationVApp.
Memory
UnliketheMemoryelementthatappearsintheComputeCapacityofaVdc,theMemoryelementthatappears intheComputeCapacityofaProviderVdcisaninstanceofProviderVdcCapacityType.Itdefinesthe memorycapacitythatcanbeallocatedfromavDCandoptionallyreportshowmuchofthatcapacityisinuse. Schema
Name Units Allocation Total Min 1 0 1 Max 1 1 1 Type xs:string xs:long xs:long Description Specifiestheunitsinwhichthecapacityismeasured.Forstoragedevices,thisis alwaysMegabytes,representedbythestringMB. NumberofUnitsthathavebeenallocatedtoconsumers.Thisvalueisreadonly, andisalways0ifAllocationModelisAllocationVApp. MaximumnumberofUnitsthatcanbeallocatedtoallconsumers.Thisvalueis readonly,andisalways0ifAllocationModelisAllocationVApp.
VMware, Inc.
187
Schema
StorageCapacity
TheadministrativeviewofaStorageCapacitydefinestheamountofstorageavailableinaProvidervDCand optionallyreportshowmuchofthatcapacityisinuse. Schema
Name Units Allocation Total Used Overhead Min 1 0 1 0 0 Max 1 1 1 1 1 Type xs:string xs:long xs:long xs:long xs:long Description Unitsinwhichthecapacityismeasured.ForCPUdevices,thisisalways Megahertz,representedbythestringMHz. NumberofUnitsthathavebeenallocatedtoconsumers TotalnumberofUnitsthatcanbeallocatedtoallconsumers Percentageoftheallocationinuse.Thisvalueisreadonly. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisprovidervDC.Thisvalueisreadonly.
NetworkPoolReferences
TheNetworkPoolReferenceselementisareadonlycontainerforNetworkPoolReferenceelements.
NetworkPoolReference
ANetworkPoolReferenceelementisaReferenceTypeelementthatreferencesanetworkpoolinaprovider vDC.Thiselementisreadonly.
VdcReferences
TheVdcReferenceselementisareadonlycontainerforVdcReferenceelementsthatreferenceorganization vDCssupportedbythisprovidervDC. Content-Type application/vnd.vmware.vcloud.admin.vdcreferences+xml Schema
Name anyattributename Link VdcReference Min 0 0 0 Max n n n Type any LinkType ReferenceType Description Includestype,href,XMLnamespace identifiers LinktocontainingprovidervDC ReferencetoanorganizationvDCs supportedbythisprovidervDC
AdminVdc
TheAdminVdcelementprovidesanadministrativeviewofavDC.ItincludesallmembersoftheVdcelement, andaddsseveralelementsthatcanbeviewedandmodifiedonlybyadministrators. Content-Type application/vnd.vmware.admin.vdc+xml Object href prototype APIURL/admin/vdc/id
188
VMware, Inc.
Schema
Name name anyattributename status Min 1 0 0 Max 1 n 1 Type xs:string any xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespace identifiers ThecreationstatusofthevDC:

-1 creationfailed 0 notready 1 ready 2 unknown 3 unrecognizedstatus
Description Tasks
0 0
1 1
Optionaldescription ReadonlycontainerforTaskelements. Eachelementinthecontainerrepresents aqueued,running,orfailedtaskowned bythisobject. Defineshowresourcesareallocatedby thevDC Definesthestoragecapacityavailablein thevDC Definesthecomputecapacityavailable inthevDC ContainerforResourceEntityelements ContainerforNetworkelementsthat referenceOrgNetworkobjectscontained bythevDC MaximumnumberofvirtualNICs allowedinthisvDC.Defaultsto0,which specifiesanunlimitednumber. MaximumnumberofOrgNetwork objectsthatcanbedeployedinthisvDC. Defaultsto0,whichspecifiesan unlimitednumber. Maximumnumberofvirtualmachines thatcanbedeployedinthisvDC. Defaultsto0,whichspecifiesan unlimitednumber. TrueifthisvDCisenabled Percentageofallocatedmemory resourcesguaranteedtovApps deployedinthisvDC.Forexample,if thisvalueis0.75,then75%ofallocated resourcesareguaranteed.Required whenAllocationModelis AllocationVApporAllocationPool. Valuedefaultsto1.0iftheelementis empty. PercentageofallocatedCPUresources guaranteedtovAppsdeployedinthis vDC.Forexample,ifthisvalueis0.75, then75%ofallocatedresourcesare guaranteed.Requiredwhen AllocationModelisAllocationVApp orAllocationPool.Valuedefaultsto 1.0iftheelementisempty.
AllocationModel StorageCapacity ComputeCapacity ResourceEntities AvailableNetworks
1 1 1 0 0
1 1 1 1 1
AllocationModelType StorageCapacityType ComputeCapacityType ResourceEntitiesType AvailableNetworksType
NicQuota
xs:int
NetworkQuota
xs:int
VmQuota
xs:int
IsEnabled ResourceGuaranteedMemory
0 0
1 1
xs:boolean xs:double
ResourceGuaranteedCpu
xs:double
VMware, Inc.
189
Schema (Continued)
Name VCpuRatingMHz Min 0 Max 1 Type xs:long Description Specifiesaclockfrequency,in Megahertz,foreachvirtualCPUcore provisionedfromthisvDC Trueifthinprovisioninghasbeen enabledforthisvDC Referencetoanetworkpoolinthe providervDCreferencedby ProviderVdcReference ReferencetotheProviderVdcfrom whichthisvDCisprovisioned
IsThinProvision NetworkPoolReference
0 0
1 1
xs:boolean ReferenceType
ProviderVdcReference
ReferenceType
AllocationModel
TheAllocationModelelementdefineshowresourcesareallocatedinavDC.Table 114showspermitted valuesforelementcontentandtheresultstheyproduce. Table 11-4. AllocationModel Element Values
Value AllocationVApp AllocationPool ReservationPool Result ResourcesarecommittedtoavDConlywhenvAppsarecreatedinit OnlyapercentageoftheresourcesyouallocatearecommittedtotheorganizationvDC. AlltheresourcesyouallocatearecommittedasapooltotheorganizationvDC.vAppsinvDCs thatsupportthisallocationmodelcanspecifyvaluesforresourceandlimit.
User
AUserobjectdefinesamemberofanorganizationorgroup. Content-Type application/vnd.vmware.admin.user+xml Object href prototype APIURL/admin/user/id Schema
Name name anyattributename Description FullName EmailAddress Telephone IsEnabled IM NameInSource IsAlertEnabled AlertEmailPrefix AlertEmail isExternal IsDefaultCached IsGroupRole Min 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Max 1 n 1 1 1 1 1 1 1 1 1 1 1 1 1 Type xs:string any xs:string xs:string xs:string xs:string xs:boolean xs:string xs:string xs:boolean xs:string xs:string xs:boolean xs:boolean xs:boolean Description Commonobjectnameattribute.Thenameoftheuser. Includestype,href,XMLnamespaceidentifiers Optionaldescription Usersfullname. Usersemailaddress Userstelephonenumber Trueiftheusercanlogin Usersinstantmessagingaddress Usernameasretrievedfrom,andintheencodingused by,LDAP Trueifalertsareenabledfortheuser StringtoprependtoalertmessageSubjectline Alertemailaddress TrueifthisuserwasimportedfromLDAP Trueifthisuseriscached Trueifthisuserhasagrouprole
190
VMware, Inc.
Schema (Continued)
Name StoredVmQuota DeployedVmQuota Role Min 0 0 0 Max 1 1 1 Type xs:int xs:int ReferenceType Description QuotaofvAppsthatthisusercanstore.Avalueof0 specifiesanunlimitedquota. QuotaofvAppsthatthisusercandeployconcurrently. Avalueof0specifiesanunlimitedquota Areferencetotheusersrole.Whenyouarecreatinga User,therequestbodymustcontainexactlyoneRole element. Theuserspassword.Thisvalueisneverreturnedby GET.Itisinspectedoncreateandmodify.Onmodify, theabsenceofthiselementindicatesthatthepassword shouldnotbechanged. ContainerforReferenceTypeelementsthatreference groupsofwhichthisuserisamember
Password
xs:string
GroupReferences
GroupsListType
Group
AGroupobjectdefinesagroup. Content-Type application/vnd.vmware.admin.group+xml Object href prototype APIURL/admin/group/id Schema
Name name anyattributename Description NameInSource UsersList Role Min 1 0 0 0 0 0 Max 1 n 1 1 1 1 Type xs:string any xs:string xs:string UsersListType ReferenceType Description Commonobjectnameattribute.TheGroupsname. Includestype,href,XMLnamespaceidentifiers Optionaldescription Groupnameasretrievedfrom,andintheencoding usedby,LDAP Alistofreferencestousersinthegroup Referencetothegroupsrole.
Role
TheRoleelementcontainsasingleRightReferenceselement,whichisacontainerforRightReference elements. Content-Type application/vnd.vmware.admin.role+xml Object href prototype APIURL/admin/role/id
RightReferences
TheRightReferenceselementisacontainerforzeroormoreRightReferenceelements.
RightReference
TheRightReferenceelementcontainsareferencetoaRight. Schema
Name Right Min 1 Max 1 Type ReferenceType Description AreferencetoarightdefinedinthevCloud.
VMware, Inc.
191
Right
RightelementsarepredefinedbyServiceManager.Theyarereadonlytousersandadministrators,andcan beretrievedwithaGEToperationthatspecifiestheURLinaRightReference.Formoreinformation,see GetanAdministrativeViewofaCloudonpage 93. Content-Type application/vnd.vmware.admin.right+xml Object href prototype APIURL/admin/right/id Schema
Name name Description Category Min 1 0 1 Max 1 1 1 Type xs:string xs:string xs:string Description Nameoftheright Optionaldescriptionoftheright. Optionalcategoryname
192
VMware, Inc.
12
vSphere Platform Extensions Reference
12
ThischapterprovidesreferenceinformationabouttheelementsdefinedinthevSpherePlatformextensionsto thisreleaseofthevCloudAPI.Elementsdocumentedinthischaptercanbecreatedandmodifiedonlybya systemadministrator.FormoreinformationabouthowthevCloudAPIusesXMLtorepresentobjects,and howthisreferencematerialisorganized,seeXMLRepresentationsinthevCloud APIonpage 141. Thischapterprovidesreferencematerialonthefollowingelementsandtheelementstheycontain:

VMWExtensiononpage 193 VimServeronpage 194 VmObjectRefsListonpage 195 ResourcePoolListonpage 196 ShieldManageronpage 196 VMWProviderVdconpage 197 VMWNetworkPoolonpage 198 VMWExternalNetworkonpage 199 VMWHostReferencesonpage 199 RequestParametersonpage 200
VMWExtension
TheVMWExtensionelementisareadonlycontainerforlinkstovCenterserversregisteredtoCloudDirector andvSphereobjectssuchasESX/ESXihosts,resourcepoolsandnetworks. Content-Type application/vnd.vmware.admin.vmwExtension+xml Object href prototype APIURL/admin/extension Schema
Name href type anyattributename Link Min 1 0 0 0 Max 1 1 n n Type xs:anyURI xs:string any LinkType Description Objectreference Mediatypeoftheelement (application/vnd.vmware.admin.vmwExtension+xml) IncludesXMLNamespaceIdentifiers. Linkstoactionsandcontainedobjects.
VMware, Inc.
193
VMWProviderVdcReferences
TheVMWProviderVdcReferenceselementisareadonlycontainerforProviderVdcReferenceelements. Content-Type application/vnd.vmware.admin.vmwProviderVdcReferences+xml Object href prototype APIURL/admin/extension/providerVdcReferences
VMWExternalNetworkReferences
TheVMWExternalNetworkReferenceselementisareadonlycontainerforExternalNetworkReference elements. Content-Type application/vnd.vmware.admin.vmwExternalNetworkReferences+xml Object href prototype APIURL/admin/extension/externalNetworkReferences
VMWNetworkPoolReferences
TheVMWNetworkPoolReferenceselementisareadonlycontainerforNetworkPoolReferenceelements. Content-Type application/vnd.vmware.admin.vmwNetworkPoolReferences+xml Object href prototype APIURL/admin/extension/networkPoolReferences
VMWVimServerReferences
TheVMWVimServerReferenceselementisareadonlycontainerforVimServerReferenceelements. Content-Type application/vnd.vmware.admin.vmwVimServerReferences+xml Object href prototype APIURL/admin/extension/vimServerReferences
VMWHostReferences
TheVMWHostReferenceselementisareadonlycontainerforHostReferenceelements. Content-Type application/vnd.vmware.admin.vmwHostReferences+xml Object href prototype APIURL/admin/extension/hostReferences
VimServer
AVimServerobjectrepresentsavCenterserver. Content-Type application/vnd.vmware.admin.vmwvirtualcenter+xml Object href prototype APIURL/admin/extension/vimServer/id Schema
Name name anyattributename Description Tasks Min 1 0 0 0 Max 1 n 1 1 Type xs:string any xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLNamespaceIdentifiers Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedtaskownedbythisobject. UsernameoftheadministratorofthisvCenter server
Username
xs:string
194
VMware, Inc.
Chapter 12 vSphere Platform Extensions Reference
Schema (Continued)
Name Password Min 0 Max 1 Type xs:string Description PasswordfortheuseridentifiedbyUsername.This valueisneverreturnedbyGET.Itisinspectedon createandmodify.Onmodify,theabsenceofthis elementindicatesthatthepasswordshouldnotbe changed. URL,includingport,tousewhenconnectingtothis vCenterserverwithavSphereclient TrueiftheserverisenabledforusewithCloud Director TrueifthisvCenterisreadytobeusedbythe vCloud IPaddressoftheassociatedvShieldManager UsernameofvShieldManageradministrator
Url IsEnabled IsConnected ShieldManagerIP ShieldManagerUserName
1 1 0 0 0
1 1 1 1 1
xs:anyURI xs:boolean xs:boolean xs:anyURI xs:string
VmObjectRefsList
TheVmObjectRefsListelementisareadonlycontainerforVmObjectRefelements. Content-Type application/vnd.vmware.admin.vmsobjectrefslist+xml Object href prototype APIURL/admin/extension/vimServer/id/vmsList
VimObjectRef
TheVimObjectRefelementisareferencetoaVirtualInfrastructureManagementobject. Schema
Name VimServerRef MoRef VimObjectType Min 1 1 1 Max 1 1 1 Type ReferenceType xs:string VimObjectTypeEnum Description Referencetotheserverhostingthisobject ManagedobjectIDofthisobject Typeofthisobject
VimObjectType
TheVimObjectTypeelementdefinesthetypeofaVirtualInfrastructureManagementobject.Table 121shows permittedvaluesforelementcontent.Thesevaluesarereadonly. Table 12-1. VimObjectType Element Values
Value RESOURCE_POOL DATASTORE HOST VIRTUAL_MACHINE VIRTUAL_APP NETWORK DV_PORTGROUP DV_SWITCH Object Type Theobjectisaresourcepool. TheobjectisavSpheredatastore. TheobjectisanESXhost. Theobjectisavirtualmachine. TheobjectisavApp. Theobjectisanexternalnetwork. Theobjectisadistributedvirtualportgroup Theobjectisadistributedvirtualswitch.
VMware, Inc.
195
ResourcePoolList
TheResourcePoolListelementisareadonlycontainerforResourcePoolelements. Content-Type application/vnd.vmware.admin.resourcepoollist+xml Object href prototype APIURL/admin/extension/vimServer/id/resourcePoolList
ResourcePool
TheResourcePoolelementincludestheMoRef(managedobjectID)ofthepoolitselfandadditional DataStoreRefsforeachdatastoreinapool. Schema
Name MoRef VimObjectType DataStoreRefs Min 1 1 0 Max 1 1 1 Type xs:string VimObjectTypeEnum VimObjectRefsType Description ManagedobjectIDofthisobject Typeofthisobject Readonlycontainerforreferencestodatastoresin thisresourcepool
ShieldManager
TheShieldManagerobjectrepresentsavShieldManagerserver. Content-Type application/vnd.vmware.admin.vmwvirtualcenter+xml Object href prototype APIURL/admin/extension/shieldmanager/id Schema
Name name anyattributename Description Tasks Min 1 0 0 0 Max 1 n 1 1 Type xs:string any xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLNamespaceIdentifiers Optionaldescription ReadonlycontainerforTaskelements.Eachelement inthecontainerrepresentsaqueued,running,or recentlycompletedTaskownedbythisorganization. UsernameoftheadministratorofthisvShield Managerserver PasswordfortheuseridentifiedbyUsername.This valueisneverreturnedbyGET.Itisinspectedon createandmodify.Onmodify,theabsenceofthis elementindicatesthatthepasswordshouldnotbe changed. URL,includingport,tousewhenconnectingtothis vShieldManagerserverwithavSphereclient ReferencetothevCenterserverassociatedwiththis vShieldManagerserver
Username Password
1 0
1 1
xs:string xs:string
Url AssociatedVimServer
1 0
1 1
xs:anyURI ReferenceType
196
VMware, Inc.
VMWProviderVdc
AVMWProviderVdcobjectrepresentsaprovidervDC. Content-Type application/vnd.vmware.admin.vmwprovidervdc+xml Object href prototype APIURL/admin/extension/providervdc/id Schema
Name name anyattributename status Min 1 0 0 Max 1 n 1 Type xs:string any xs:int Description Commonobjectnameattribute Includestype,href,XMLNamespace Identifiers ThecreationstatusoftheProviderVdc:

1 Creationfailed 0 Notready 1 Ready 2 Unknown 3 Unrecognized
Description Tasks
0 0
1 1
Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsa queued,running,orrecentlycompletedTask ownedbythisorganization. Definesthecomputecapacityavailablein thisprovidervDC Definesthestoragecapacityavailableinthis providervDC ReadonlycontainerforNetworkelements thatreferenceexternalnetworkscontained bytheprovidervDC ReadonlycontainerforreferencestoVdc objectsthatareprovisionedfromthis providervDC. TrueifthisprovidervDCisenabled ContainerforNetworkPoolReference elements ContainerforVimObjectRefelementsof typeDATASTORE Referencetotheresourcepoolbackingthis providervDC(VimObjectRefelementof typeRESOURCE_POOL) ReferencetothevCenterserverhostingthe datastorescontainedinDataStoreRefsand theresourcepoolcontainedin ResourcePoolRef ReadonlycontainerforHostobjects
ComputeCapacity StorageCapacity AvailableNetworks
0 0 0
1 1 1
RootComputeCapacityType ProviderVdcCapacityType AvailableNetworksType
Vdcs
VdcsType
IsEnabled NetworkPoolReferences DataStoreRefs ResourcePoolRef
0 0 1 1
1 1 1 1
xs:boolean NetworkPoolReferencesType VimObjectRefsType VimObjectRefType
VimServer
ReferenceType
HostReferences
HostsType
VMware, Inc.
197
VMWNetworkPool
TheVMWNetworkPoolelementrepresentsanetworkpool.Therearethreedifferenttypesofthiselement,allof whichhavethesamename,VMWNetworkPool,andaredistinguishedinrequestbodiesbythevalueofthe HTTPContentTypeheader.
FencePoolType
AVMWNetworkPooloftheFencePoolTyperepresentsanetworkpoolbackedbyoneormorevSphereisolated networks. Content-Type application/vnd.vmware.admin.fencePool+xml Schema
Name name anyattributename Description FenceIdCount VlanId VimSwitchRef UsedNetworksCount Min 1 0 0 1 1 1 0 Max 1 n 1 1 1 1 1 Type xs:string any xs:string xs:int xs:int VimObjectRefType xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Optionaldescription NumberoffenceIDsinthispool Setto0fornoVLAN ReferencetotheswitchthatsupportsthisVLAN Readonlyindicationofhowmanynetworksinthis poolareinuse
PortGroupPoolType
AVMWNetworkPoolofthePortGroupPoolTyperepresentsanetworkpoolbackedbyoneormorevSphere portgroups. Content-Type application/vnd.vmware.admin.portGroupPool+xml Schema
Name name anyattributename Description PortGroupRefs VimServer UsedNetworksCount Min 1 0 0 1 1 0 Max 1 n 1 1 1 1 Type xs:string any xs:string VimObjectRefsType ReferenceType xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Optionaldescription ReferencestotheportgroupsthatsupportthisVLAN Referencetotheserverhostingthisobject Readonlyindicationofhowmanynetworksinthis poolareinuse
VlanPoolType
AVMWNetworkPooloftheVlanPoolTyperepresentsanetworkpoolbackedbyoneormorevSphereVLANs. Content-Type application/vnd.vmware.admin.vlanPool+xml Schema
Name name anyattributename Description VlanRange Min 1 0 0 1 Max 1 n 1 n Type xs:string any xs:string NumericRangeType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Optionaldescription DefinesarangeofVLANIDs
198
VMware, Inc.
Schema (Continued)
Name VimSwitchRef UsedNetworksCount Min 1 0 Max 1 1 Type VimObjectRefType xs:int Description ReferencetotheswitchthatsupportsthisVLAN Readonlyindicationofhowmanynetworksinthis poolareinuse
VMWExternalNetwork
TheVMWExternalNetworkelementdefinesanexternalnetwork. Content-Type application/vnd.vmware.vcloud.admin.network+xml Object href prototype APIURL/admin/extension/externalnet/id Schema
Name name anyattributename Description Configuration VimPortGroupRef Min 1 0 0 0 1 Max 1 n 1 1 1 Type xs:string any xs:string NetworkConfigurationType VimObjectRefType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Optionaldescription Propertiesofthenetwork Referencetotheportgroupthatsupportsthis network
VlanRange
TheVlanpRangeelementdefinesarangeofVLANIDs. Schema
Name Start End Min 1 1 Max 1 1 Type xs:int xs:int Description LowestVLANIDintherange HighestVLANIDintherange
VMWHostReferences
TheVMWHostReferenceselementisareadonlycontainerforHostelementsrepresentingthehostsina specificprovidervDC.
Host
AHostobjectrepresentsanESX/ESXihostinaprovidervDC. Content-Type application/vnd.vmware.admin.+xml Object href prototype APIURL/admin/extension/host/id Schema
Name name anyattributename Description Tasks Min 1 0 0 0 Max 1 n 1 1 Type xs:string any xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLNamespaceIdentifiers. Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedTaskownedbythisobject. Linkstocontainedobjects.
Link
LinkType
VMware, Inc.
199
Schema (Continued)
Name Ready Available Enabled Busy EnableHostForHostSpanning Min 1 1 1 1 1 Max 1 1 1 1 1 Type xs:boolean xs:boolean xs:boolean xs:boolean xs:boolean Description Trueifthehostisready Trueifthehostisavailable TrueifthehostisenabledforusewithCloud Director Trueifthehostisbusy Trueifthehostisenabledforhostspanning.If true,thehostcannotbeputinstandbyor maintenancemode. CPUtypeofthehost NumberoflogicalCPUs NumberofCPUpackages TotalCPUcapabilityofthishost Memoryreserved Totalmemory Hostoperatingsystemname Hostoperatingsystemversion vCentermessagesforthishost URLforhostpropertypageinvSphere vSpheremanagedobjectreferenceforthisobject
CpuType NumOfCpusLogical NumOfCpusPackages CpuTotal MemUsed MemTotal HostOsName HostOsVersion SystemMessages VimPropertyPageUrl VmMoRef
0 1 1 1 1 1 0 0 0 0 0
1 1 1 1 1 1 1 1 1 1 1
xs:string xs:int xs:int xs:long xs:double xs:double xs:string xs:string xs:string xs:string xs:string
Request Parameters
ThevSpherePlatformextensionsdefinedseveralelementsthatprovideparameterstorequeststhatcreate, delete,modify,orchangethestateofavSpherePlatformobject.
PrepareHostParams
ThePrepareHostParamselementformsthebodyofaprepareorunpreparerequestforanESXhost. Schema
Name Username Password Min 1 1 Max 1 1 Type xs:string xs:string Description Usernameofahostadministrator PasswordforspecifiedUsername
RegisterVimServerParams
TheRegisterVimServerParamselementformsthebodyofaregistervimserverrequest. Schema
Name VimServer ShieldManager Min 1 1 Max 1 1 Type VimServerType ShieldManagerType Description vCenterservertoregister vShieldManagerassociatedwiththevCenterservertoregister
200
VMware, Inc.
ImportVmAsVAppParams
TheImportVmAsVAppParamselementformsthebodyofanimportVmAsVApprequest. Schema
Name name sourceMove deploy powerOn Description InstantiationParams Min 1 0 0 0 0 0 Max 1 1 1 1 1 1 Type xs:string xs:boolean xs:boolean xs:boolean xs:string InstantiationParamsType Description SpecifiesthenameofthevAppcreatedbythis operation TrueiftheimportedVMshouldberemovedfrom thesourcevCenter Notsupportedinthisrelease Notsupportedinthisrelease Optionaldescription Containerforanyofthefollowing ovf:Section_Typeelements:

VmName VAppScopedLocalId ComputerName VmMoRef Vdc
0 0 0 1 1
1 1 1 1 1
xs:string xs:string xs:string xs:string ReferenceType
Virtualmachinename Readonlyidentifiercreatedonimport Displaynameofthisvirtualmachine ManagedobjectreferenceoftheVMtoimport URLofthetargetvDC
ImportVmAsVAppTemplateParams
TheImportVmAsVAppTemplateParamselementformsthebodyofanimportVmAsVAppTemplaterequest. Schema
Name name sourceMove Description VmMoRef Vdc Catalog Min 1 0 0 1 1 Max 1 1 1 1 1 Type xs:string xs:boolean xs:string xs:string ReferenceType ReferenceType Description SpecifiesthenameofthevAppcreatedbythis operation TrueiftheimportedVMshouldberemovedfromthe sourcevCenter Optionaldescription ManagedobjectreferenceoftheVMtoimport URLofthetargetvDC Referencetoacataloginwhichthetemplatewillbe included.Ifthiselementisomittedorempty,the templateisimportedintothetargetvDCbutnot referencesinanycatalog. Virtualmachinename Readonlyidentifiercreatedonimport Displaynameofthisvirtualmachine
VmName VAppScopedLocalId ComputerName
0 0 0
1 1 1
xs:string xs:string xs:string
VMware, Inc.
201
202
VMware, Inc.
OVF and the vCloud API
TheOpenVirtualizationFormat(OVF)isanopen,portable,efficientandextensibleformatforpackagingand distributingvirtualsystems.OVFwasdevelopedbytheDistributedManagementTaskForce(DMTF),a notforprofitassociationofindustrymembersdedicatedtopromotingenterpriseandsystemsmanagement andinteroperability.FormoreinformationabouttheDMTFandOVF,visithttp://www.dmtf.org. ThevCloudAPIsupportsVersion1oftheOVFstandard.Inparticular,itsupportsuploadingand downloadingvApptemplatesasOVFpackages.Inaddition,vApp,Vm,andvAppTemplateelements incorporateanumberofovf:Section_Typeelementsintheirdefinitionsofvirtualmachines(seeSection onpage 163fordetailsonhowthesesectionsareused). NOTEThevCloudAPIsupportsuploadingOVF1.0andOVF1.1,anddownloadingOVF1.0.OVF1.1 packagesareconvertedtoOVF1.0fordownload. Thisappendixincludesthefollowingtopics:

AboutOVFonpage 203 HowthevCloudAPIUsesOVFonpage 204
About OVF
Becauseitisawidelyacceptedstandardformat,OVFprovidesconsiderableflexibilityinaccommodatingthe needsofadiversecollectionofvirtualizationtechnologies.Whilethisflexibilityentailsmorecomplexitythan avendorspecificformatmightrequire,italsoprovidesmanyadvantages.

VirtualmachinesandappliancesaredistributedasOVFpackagesbymanyvendors. Manyvendors,includingVMware,offertoolsthatsimplifycreatingandcustomizingOVFvirtual machines,supportconvertingvirtualmachinesonexistingvirtualizationplatformstoOVF,orboth. OVFhasthepowertoexpressthecomplexrelationshipsbetweenvirtualappliancesinenterprise applications.Mostofthecomplexitycanbehandledbytheauthoroftheapplianceratherthantheuser deployingit. OVFisextensible,allowingnewpoliciesandrequirementstobeinsertedbyISVsandimplementedby thevirtualizationplatformsthatsupportthemwithoutrequiringchangestootherclients,otherplatforms, orthevCloudAPIitself.
WhilemostusersdonotneedtointeractdirectlywiththeOVFderivedelementsofthevCloudAPI, administratorsandadvancedusersshouldbecomefamiliarwiththedetailsoftheOVFstandardbefore developingapplicationswiththevCloudAPI.ThischapterprovidesanoverviewofOVF,onethat concentratesontheaspectsofthestandardthatareofspecialinteresttousersofthevCloudAPI.Thecomplete OVFspecificationdocumentisavailableat http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf.Aninformativewhitepaperon OVFisavailableathttp://www.dmtf.org/standards/published_documents/DSP2017_1.0.0.pdf.
VMware, Inc.
203
Avirtualapplicationorvirtualmachineistypicallymadeupofoneormorevirtualdiskfilesthatcontainthe operatingsystemandapplicationsthatrunonthevirtualmachine,andaconfigurationfilecontaining metadatathatdescribehowthevirtualmachineisconfiguredanddeployed.AnOVFpackageincludesthese components,aswellasoptionalcertificateandmanifestfiles.Thepackagecanbedistributedandstoredasa collectionofindividualfiles,orasasinglearchive(OVA)file.
About OVF Packages

AnOVFpackageincludesfourkindsoffiles:
AnOVFdescriptor,anXMLfilethatcontainsmetadatathatdescribeavirtualmachineorcollectionof relatedvirtualmachinesandthedeploymentenvironmenttheyrequire.Byconvention,thisfilehasthe suffix.ovf. Virtualdiskfiles.Thedescriptorliststhesefilesandincludesinformationabouttheirformat. Anoptionalcertificationfile,whichcanbeusedtocertifytheauthenticityofthepackage. Anoptionalmanifestfile,whichcontainsaSHA1digestofeachofthefilesinthepackage.
About OVA Files

AnOVAfilecollectsallthefilesinanOVFpackageintoasinglearchive.Byconvention,thisfilehasthe suffix .ova.ThisreleaseofthevCloudAPIdoesnotsupportuploadordownloadofOVAfiles.
How the vCloud API Uses OVF

ThevCloudAPIusestheOVFpackageasaunitofdistributionandstorageforvApptemplates.Becausethese artifactsareuploaded,downloaded,andstoredinOVFpackageform,thevCloudAPIsupportsaccesstoand deploymentofthewidestpossiblevarietyofvirtualapplications.ThevCloudAPIimplementsaninstantiation mechanismthattransformsanOVFpackageintoavAppbybindingthepackagesabstractresource requirementstospecificresourcesinadeploymentenvironmentdefinedbyavDC. Becauseofitsgenerality,theOVFincludesagreatdealofinformation,nearlyallofwhichisreusedinVApp elements.Someofthisinformationisreusedinunalteredform,withentireovf:Section_Typeelements includedintheVAppbody.Othersectionsaretransformedorextendedbyinstantiation.Whileitisnot necessaryforauserofthevCloudAPItohaveadetailedknowledgeofalltheelementsofanOVFpackage,a basicunderstandingofafewkeypartsthepackageandhowtheyrelatetovApptemplatesandvAppscanbe useful.
Virtual Machines
AnOVFEnvelopecollectsallofthemetadatathatdescribesasinglevirtualmachineintoaVirtualSystem element.AnEnvelopethatcontainsmorethanoneVirtualSystemcollectsthemintoa VirtualSystemCollectionelement.Thisarrangementsupportspackagingagroupofrelatedvirtual machinesasasingleobject,andincludesprovisionsforspecifyingglobalparameterssuchasvirtualmachine startuporder,networkconnections,andarangeofresourceconfigurations(suchasprocessingpowerand memory)towhichthevirtualmachinescanbedeployed. ThevCloudAPIalsosupportsthiskindofpackagingofmultiplevirtualmachines.Whenyouinstantiatea VAppTemplate,informationfromitsVirtualSystemandVirtualSystemCollectionelementsis propagatedtothecreatedVApp.VirtualSystemelementsinaVirtualSystemCollectionbecomeVm elementscontainedbytheChildrenelementofaVApp. Formoreinformationaboutinstantiation,seeInstantiateavAppTemplateonpage 61.Foradetailed exampleofanEnvelopeanditssections,seeReconfiguringvAppsandVirtualMachinesonpage 69.For moreinformationaboutthepurposeandcontentsoftheOVFSectionsincludedinavApporVm,seeVApp onpage 162.
204
VMware, Inc.
Appendix A OVF and the vCloud API
Virtual Disk Files

VirtualdiskfileinformationextractedfromtheReferencessectionoftheOVFpackageisusedtopopulate theFileselementoftheVAppTemplate.AnOVFpackagecanincludeexactlyoneReferencessection.Itlists allthefilesrequiredbyalltheVirtualSystemsdefinedinthepackage,includingvirtualdisksand localespecificresourcefiles.VirtualdiskfilesareenumeratedagainintheDiskSectionelementofthe package,onefileperDiskelement.Diskelementsincludeadditionalinformationaboutthecapacityand formatofeachdisk.(Diskelementscanalsospecifyemptyvirtualdisk,inwhichcasetheyarenotassociated withavirtualdiskfile.) Example A1showshowavirtualdiskreferenceappearsinanEnvelope.(Inthisexample,attributesand otherelementsintheEnvelopehavebeenomittedforclarity.)ThehrefvalueoftheFileelementinthe ReferencessectionspecifiesthefilepathnamerelativetothelocationoftheOVFdescriptorfileinwhichthe Envelopeappears.(Inthiscase,thediskfile,SimpleVM-disk1.vmdk,isinthesamefolderastheOVF descriptor.)TheDiskelementisthenassociatedwithavirtualmachine,asaHostResourceofa VirtualSystem,referencedbyitsovf:diskIdattributevalue. Example A-1. Virtual Disks in an OVF Envelope
<Envelope ... ... <References> <File ovf:href="SimpleVM-disk1.vmdk" ovf:id="file1" ovf:size="68096"/> </References> ... <DiskSection> <Info>Virtual disk information</Info> <Disk ovf:capacity="8589934593" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/vmdk.html#str eamOptimized"/> </DiskSection> ... <VirtualHardwareSection> <VirtualSystem> ... <Item> ... <rasd:ElementName>Hard Disk 1</rasd:ElementName> <rasd:HostResource>ovf:/disk/vmdisk1</rasd:HostResource> ... </Item> ... </VirtualHardwareSection> </VirtualSystem> </Envelope>
Networks
TheNetworkSectionelementofanOVFEnvelopelistsallthelogicalnetworksrequiredbythepackage.Each networkisdefinedinthissectionbyanameandcanhaveanoptionaldescription.Logicalnetworknamesare usedwhenspecifyingconnectiondetailsforavirtualNIC. TheOVFisextensible,andthevCloudAPIhasimplementedextensionsthatenableamorecomprehensive specificationofnetworkfeatures,suchasfirewallandNATrules,thanwhatiscurrentlysupportedbytheOVF standard.SeeNetworkConfigonpage 165. Example A2illustratesasubsetofEnvelopeelementsthatspecifyvAppnetworkingconfiguration.

TheOVFNetworkSectionelementspecifiesthenameofthenetwork ThevCloudAPINetworkConfigSectiondefinesvariousnetworkfeaturessuchasDHCPandfirewall services.
VMware, Inc.
205
ThevCloudAPINetworkConnectionSectionisareadonlysectionthatliststhenetworkconnections andIPaddressesthatavApphasacquiredorbeenassignedatdeployment.Thissectionispresentonly inadeployedvAppthathasanetworkconnection. TheOVFItemelement,oneofmanythatapplytotheEnvelopesVirtualHardwareSection,specifies thatthevirtualmachinesNIC(resourcetype10)isconnectedtoInternet.Italsospecifiesmanyother detailsaboutthedevice.FormoreinformationaboutDMTFresourcetypes,visithttp://www.dmtf.org.
Example A-2. Network Information in an OVF Envelope

<Envelope ... ... <NetworkSection> <ovf:Info>The list of logical networks</ovf:Info> <Network ovf:name="Internet"/> </NetworkSection> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="Internet"> <Features> <Dhcp>true</Dhcp> <Nat></Nat> <Firewall></Firewall> </Features> </NetworkConfig> </NetworkConfigSection> <NetworkConnectionSection> <NetworkConnection network="Internet"> <IPAddress>192.168.1.100</IPAddress> </NetworkConnection> </NetworkConnectionSection> ... <VirtualSystem> <VirtualHardwareSection> ... <Item> ... <rasd:Connection>Internet</rasd:Connection> <rasd:Description>PCNet32 ethernet adapter on "Internet" network</rasd:Description> <rasd:ElementName>Network Adapter 1</rasd:ElementName> ... </Item> ... </VirtualSystem> <VirtualHardwareSection> </Envelope>
206
VMware, Inc.
An Introduction to REST for vCloud API Users
REST,anacronymforRepresentationalStateTransfer,isatermthathasbeenwidelyemployedtodescribean architecturalstylecharacteristicofprogramsthatrelyontheinherentpropertiesofhypermediatocreateand modifythestateofanobjectthatisaccessibleataURL. Thisappendixincludesthefollowingtopics:

HowRESTWorksonpage 207 UsingthevCloudRESTAPIonpage 207 ForMoreInformationAboutRESTonpage 208
How REST Works

IfaURLofsuchanobjectisknowntoaclient,theclientcanuseanHTTPGETrequesttodiscoverthe propertiesoftheobject.ThesepropertiesaretypicallycommunicatedinastructureddocumentwithanHTTP ContentTypeofXMLorJSON,thatprovidesarepresentationofthestateoftheobject.InaRESTfulworkflow, documents(representationsofobjectstate)arepassedbackandforth(transferred)betweenaclientanda servicewiththeexplicitassumptionthatneitherpartyneedknowanythingaboutanobjectotherthanwhatis presentedinasinglerequestorresponse.TheURLsatwhichthesedocumentsareavailableareoftensticky, inthattheypersistbeyondthelifetimeoftherequestorresponsethatincludesthem.Theothercontentofthe documentsisnominallyvaliduntiltheexpirationdatenotedintheHTTPExpiresheader.
Using the vCloud REST API

ARESTAPIisinsomewaysanunfortunateterm,sincetheapplicationprogramswrittentoaRESTAPI actuallyuseHTTPrequests(whichareoftenexecutedbyascriptorotherhigherlevellanguage)asawayof makingwhatareessentiallyremoteprocedurecallsthatcreate,modify,ordeletetheobjectsdefinedbythe API.ThisRESTAPI(andothers)isdefinedbyacollectionofXMLdocumentsthatrepresenttheobjectson whichtheAPIoperates.Theoperationsthemselves(HTTPrequests)aregenerictoallHTTPclients. TowriteaRESTfulclient,youneedtounderstandonlytheHTTPprotocolandthesemanticsofstandard HTMLmarkup.TousethevCloudAPIeffectivelyinsuchaclient,youneedtoknowthreethings
thesetofobjectsthattheAPIsupports,andwhattheyrepresent(WhatisavDC?Howdoesitrelatetoan organizationorcatalog?) howtheAPIrepresentstheseobjects(WhatdoestheXMLschemaforanOrglooklike?Whatdothe individualelementsandattributesrepresent?) howtheclientreferstoanobjectonwhichitwantstooperate(WherearethelinkstoobjectsinavDC? Howdoesaclientobtainandusethem?)
Toanswerthesequestions,youneedtounderstandthevCloudAPIXMLschemas.Theseschemasdefinea numberofXMLtypes,manyofwhichareextendedbyothertypes.ThevCloudAPIschemasalsouseand extendtypesdefinedbytheOpenVirtualizationFormat.TheXMLelementsdefinedintheseschemas,along withtheirattributesandcompositionrules(minimumandmaximumnumberofelementsorattributes,for

VMware, Inc. 207
example,ortheprescribedhierarchywithwhichelementscanbenested)representthedatastructuresof objectsinthecloud.AclientcanreadanobjectbymakinganHTTPGETrequesttotheobjectsURL.Aclient canwrite(createormodify)anobjectwithanHTTPPUTorPOSTrequestthatincludesaneworchanged XMLbodydocumentfortheobject.AndaclientcanusuallydeleteanobjectwithanHTTPDELETErequest. Inthisdocument,wepresentexamplerequestsandresponses,andalsoprovidereferenceinformationonthe XMLschemasthatdefinetherequestandresponsebodies.
RESTful Workflow Patterns

AllRESTfulworkflowsfallintoapatternthatincludesonlytwofundamentaloperations:
MakeanHTTPrequest(typicallyGET,PUT,POST,orDELETE).Thetargetofthisrequestiseithera wellknownURL(suchastherootofavCloudserviceoranorganizationhostedonsuchaservice)ora linkobtainedfromtheresponsetoapreviousrequest.(Forexample,aGETrequesttoanorganization URLreturnslinkstocatalogandvDCobjectscontainedbytheorganization.) Examinetheresponse,whichalwaysincludesanHTTPresponsecodeandoftenincludesabody(anXML document,inthevCloudAPI).Theresponsebodymaycontainlinksorotherinformationaboutthestate ofanobject.(Forexample,aresponsethatincludesavAppbodycontainsthedetailsofthevAppscurrent virtualhardwareconfigurations,aswellaslinksthatyoucanusetoeditthatconfiguration).Ifthe responseisanHTTPresponsecode,itindicateswhethertherequestsucceededorfailed,andmaybe accompaniedbyaURLthatpointstoalocationfromwhichadditionalinformationcanberetrieved.
Thesetwooperationscanrepeat,inthisorder,foraslongasnecessary.
For More Information About REST

ForacomprehensivediscussionofRESTfromboththeclientandserverperspectives,see: Richardson,Leonard,andSamRuby.RESTfulWebServices.NorthMankato:OReillyMedia,Inc.,2007. TherearealsomanysourcesofinformationaboutRESTontheWeb,including:

http://www.infoq.com/articles/restintroduction http://www.infoq.com/articles/subbuallamarajurest http://www.stucharlton.com/blog/archives/000141.html
208
VMware, Inc.
Index
A
AccessLevel element example of use 57 schema reference 178 AccessSetting element example of use 56, 57 schema reference 178 AccessSettings element example of use 56 schema reference 178 AdminVdc element example of use 104 AllEULAsAccepted description 172 AllEULAsAccepted element example of use 63, 65 authentication about 18 example request 21 AvailableNetworks element example of use 103, 104, 129 schema reference 153
schema reference 176 ComposeVAppParams element example of use 65 schema reference 173 Configuration element schema reference 155 ControlAccessParams element example of use 56 schema reference 177
D
DeployVAppParams example of use 26, 81 DeployVAppParams element schema reference 175
E
Error codes 146 Error element schema reference 146 examples about 19 ExternalNetwork element example of use 99 schema reference 180
C
CaptureVAppParams element example of use 68 schema reference 175 Catalog element example of use 35 schema reference 160 CatalogItem element example of use 36 schema reference 160 CatalogItems element schema reference 160 Catalogs about 14 controlling access to 56 CloneMediaParams element example of use 51 schema reference 176 CloneVAppParams element example of use 52 schema reference 176 CloneVAppTemplateParams element example of use 51
F
File element schema reference 154 Firewall rules to create or modify 72 FirewallRule element example of use 72 FirewallService element example of use 72 schema reference 156
G
Group element example of use 113 schema reference 191 GuestCustomizationSection element cannot be passed in InstantiationParams 80
H
Host element example of use 124
209
VMware, Inc.
schema reference 199 HTTP headers Content-Type 142 HTTP status codes 18
I
InstantiateVAppTemplateParams element example of use 25, 63 schema reference 172 Instantiation Parameters about 62 InstantiationParams element example of use 25, 63 schema reference 172 IpRange element example of use 72 schema reference 156
example of use 21 OrgNetwork element schema definition 154 OVF to create vApp template from 42 to download vApp template as 47 to upload 171
P
Property element example of use 36, 161 schema reference 161
R
rel attribute about 15 ResourceEntity element about 38 example of use 37, 55 schema reference 154 responses contents of 18 Role element example of use 114 schema reference 191
L
Link element about 15 rel attribute 15 login example of 21 logout example of 30
S M
Media element example of use 50 schema reference 161 MediaInsertOrEjectParams element example of use 85 schema reference 177 ScreenTicket element example of use 30, 87 Source element example of use 63, 65, 67
T
Task element example of use 89 schema reference 168 Tasks about 14 TasksList element example of use 97 technical support resources 12
N
NAT rules to create or modify 72 NatRule element example of use 72 schema reference 158 network vApp 62 NetworkConfigSection element example of use 71
U
UndeployVAppParams element schema reference 175 UploadVAppTemplateParams element example of use 43 schema reference 171 User element example of use 110 schema reference 190
O
Org element example of use 22 schema reference 151 Org entity to retrieve 34 OrgList element
210
VMware, Inc.
Index
V
vApp to compose from templates and virtual machines 65 to create from template 24, 61 to deploy and power-on 26 to instantiate 24 VApp element example of use 65, 66, 67, 69 schema reference 162 vApp networks about 62 vApp template add to catalog 54 to create from OVF 42 to create from vApp 68 VAppScopedVmId element example of use 72 VAppTemplate element example of use 61 schema reference 161 to create 42 vDC about 14 Vdc element example of use 24, 37 schema reference 152 VimServer example of use 120 schema reference 194 Vm element example of use 65, 66, 73 schema reference 163 searching for 66 VmQuestionAnswer schema reference 177 VMWExtension example of use 119 schema reference 193 VMWExternalNetwork example of use 133 schema reference 199 VMWNetworkPool example of use 136 schema reference 198 VMWProviderVdc example of use 127 schema reference 197
VMware, Inc.
211
212
VMware, Inc.

VCD 10 API Guide

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

VCD 10 API Guide

Caricato da

Copyright:

Formati disponibili

vCloud API Programming Guide

vCloud API 1.0

vCloud API Programming Guide

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

vCloud API Programming Guide

GetaScreenTicketforaVirtualMachine 87 ProvideUserInputRequestedbyaVirtualMachine 87 ControlAccesstovApps 89 RetrieveaTask 89

vCloud API Programming Guide

8 XMLRepresentationsinthevCloud API 141

vCloud API Programming Guide

vCloud API Programming Guide

About This Book

VMware Technical Publications Glossary

vCloud API Programming Guide

Technical Support and Education Resources

Online and Telephone Support

VMware Professional Services

Introducing the VMware vCloud API

vCloudObjectTaxonomyonpage 13 Objects,References,andRepresentationsonpage 15 LinksandLinkRelationsonpage 15 vCloudClientWorkflowOverviewonpage 17 AbouttheExamplesonpage 19

vCloud Object Taxonomy

vCloud Users and Groups

vCloud API Programming Guide

Figure 1-1. vCloud Object Taxonomy

vCloud Virtual Datacenters

Chapter 1 Introducing the VMware vCloud API

Virtual Systems and Media Images in a vCloud

Objects, References, and Representations

Links and Link Relations

vCloud API Programming Guide

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

Chapter 1 Introducing the VMware vCloud API

vCloud Client Workflow Overview

WhenitappearsasthevalueofaContentTypeheaderorthetypeattributeofanelementinthevCloudAPI, thisstringiscaseinsensitiveinrequests,andcanbereturnedineithermixedcaseorlowercasecharactersin responses. Formoreinformation,seeContentTypeonpage 142.

vCloud API Programming Guide

Allrequiredelementsmustappearinrequestbodies.Allelementsthatappearinrequestbodiesmust appearintheorderestablishedbytheschema,andwithcontentthatconformstothetypeconstraint specifiedintheschema.SeeSchemaValidationonpage 142.

Iftheauthenticationheaderismissing,theserverreturnsHTTPresponsecode401. Ifthecredentialssuppliedintheauthenticationheaderareinvalid,theserverreturnsHTTPresponse code401. Iftherequestissuccessful,theserverreturnsHTTPresponsecode200(OK)andheadersthatinclude anauthorizationheaderoftheform:

Chapter 1 Introducing the VMware vCloud API

Configuring the vCloud API URL

About the Examples

UnsecuredURLs(http://)areusedintheexamples.Inpractice,mostsiteswillrequiretheuseofSSL (https://). ObjectIDsshowninhrefattributevaluesappearassmallintegers(forexamplevapp-7ororg/3).Inthe vCloudAPIsupportedbyCloudDirector,objectIDsare10digitdecimalintegers(forexample vapp-124237959ororg/5738592905).

vCloud API Programming Guide

Hello vCloud: A Structured REST Workflow Example

ThischapterpresentsasimpleexampleofastructuredRESTworkflowfordiscoveringanddeployinga particularvApp(inthiscase,anFTPserverwithaconnectiontothepublicInternet). Thischapterincludesthefollowingtopics:

Logging In and Getting an Organization List

vCloud API Programming Guide

<Org .../> <Org .../> </OrgList>

Linksintheresponsewhoserelattributehasavalueofdownarereferencestoobjectsthattheorganization contains.Example 22showsthesubsetofthoseitemsthatyouwillneedforthisexercise:

Chapter 2 Hello vCloud: A Structured REST Workflow Example

Finding a vApp Template

vCloud API Programming Guide

Getting Information About a vDC

Instantiating the Template in the vDC

AnameforthevAppthattherequestcreates TheURLofthetemplatetoinstantiate.Inthiscase,theURL(retrievedinExample 24)is http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate111.

Chapter 2 Hello vCloud: A Structured REST Workflow Example

CreationparametersforavAppnetwork.AvAppnetworkdefineshowthevAppconnectstoan organizationnetworkavailableinthetargetvDC.Formoreinformation,seeAboutvAppNetworkson page 62.

ThenameissuppliedinthenameattributeoftheInstantiateVAppTemplateParamsrequest.(This requestalsoprovidesadescription,whichisoptionalbutagoodpractice.) ThetemplateURLissuppledintheSourceelement ThevAppnetworkisspecifiedintheNetworkConfigSectionelement.Thisspecificationincludesthree parameters:

ThetargetoftherequestistheinstantiateVAppTemplateURLofthisvDC(seeExample 25).Becausethe operationcreatesanewobject(avApp),theHTTPrequesttypeisPOST. Example 2-6. Instantiating a vApp Template Request:

vCloud API Programming Guide

Deploying and Powering On the vApp

Chapter 2 Hello vCloud: A Structured REST Workflow Example

Getting Information About the vApp

Example 2-8. Get Information About the vApp Request:

vCloud API Programming Guide

Chapter 2 Hello vCloud: A Structured REST Workflow Example