VMware VCLOUD API 1.0 - TECHNICAL NOTE Programming Manual Download Page 10

Page: 10 / 212

vCloud API Programming Guide

VMware, Inc.

Summary of Contents for VCLOUD API 1.0 - TECHNICAL NOTE

Page 1: ...This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition To check for more recent editions of this document see ht...

Page 2: ...t this documentation submit your feedback to docfeedback vmware com Copyright 2009 2010 VMware Inc All rights reserved This product is protected by U S and international copyright and intellectual pro...

Page 3: ...ate in the vDC 24 Deploying and Powering On the vApp 26 Getting Information About the vApp 27 Displaying the Console 29 Retrieve a Screen Ticket 29 Use the Ticket with vmware vmrc 30 Deleting the vApp...

Page 4: ...ess 56 Control Access to Catalogs 56 5 Datacenter Operations 59 Summary of Datacenter Operations Requests 59 vApp Lifecycle 60 Instantiate a vApp Template 61 About Instantiation Parameters 62 About vA...

Page 5: ...9 Network Administration 99 View the Properties of an External Network 99 Add a Network to an Organization 100 Get an Administrative View of an Organization Network 101 Modify an Organization Network...

Page 6: ...ts in a vCloud 124 Get Information About a Host 124 Prepare a Host 125 Unprepare a Host 126 Enable or Disable a Host 126 Repair a Host 126 Upgrade a Host Agent 127 Create a Provider vDC 127 Examine th...

Page 7: ...ourceEntities 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 LeaseSettingsSect...

Page 8: ...es 180 ProviderVdcReferences 180 RightReferences 180 RoleReferences 180 Networks 180 ExternalNetwork 180 AdminOrg 180 Settings 181 Users 185 Groups 185 Catalogs 185 Catalog 186 Vdcs 186 ProviderVdc 18...

Page 9: ...equest Parameters 200 PrepareHostParams 200 RegisterVimServerParams 200 ImportVmAsVAppParams 201 ImportVmAsVAppTemplateParams 201 A OVF and the vCloud API 203 About OVF 203 About OVF Packages 204 Abou...

Page 10: ...vCloud API Programming Guide 10 VMware Inc...

Page 11: ...ended for software developers who are building VMware Ready Cloud Services including interactive clients of VMware Cloud Director This guide assumes you are familiar with Representational State Transf...

Page 12: ...s To find out how VMware support offerings can help meet your business needs go to http www vmware com support services VMware Professional Services VMware Education Services courses offer extensive h...

Page 13: ...y The vCloud API defines a set of objects common to cloud computing environments Figure 1 1 illustrates the principal object types vCloud Organizations A vCloud contains one or more organizations A vC...

Page 14: ...loppy disks and CD ROMs An organization administrator specifies how resources from a provider vDC are distributed to the vDCs in an organization vCloud Catalogs Catalogs contain references to virtual...

Page 15: ...ject It also appears in various elements of LinkType and ReferenceType This URL serves as a unique identifier that persists for the life of the object and is never re used Although URLs have a well kn...

Page 16: ...l device POST media insertMedia insert virtual media in a virtual device POST move not supported in this release N A ova not supported in this release N A ovf the OVF representation of this vAppTempla...

Page 17: ...ents must include an authentication header See Authentication on page 18 Requests that include a document body must start with the appropriate HTTP Content Type header The type attribute of a response...

Page 18: ...t be included in each subsequent vCloud API request The response body is an OrgList element which is a list of all organizations that the user can access The authentication token expires after a confi...

Page 19: ...that are not fragments of some larger example that includes this header Although the examples show these strings using the character case in which they are defined by the implementation these strings...

Page 20: ...vCloud API Programming Guide 20 VMware Inc...

Page 21: ...ns URL as shown in Example 8 2 on page 147 Because all other vCloud API requests must be authenticated any vCloud API workflow has to begin with a login request that supplies user credentials in the f...

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

Page 23: ...m element When a client browses a catalog it can read only the name type and href of each CatalogItem To retrieve an item from the catalog more information is required In Example 2 4 the client makes...

Page 24: ...d example com api v1 0 network 54 type application vnd vmware vcloud network xml name Internet AvailableNetworks Vdc The information you need is available here in two places An Link element containing...

Page 25: ...ndicates that the vApp network is connected directly to the organization network The target of the request is the instantiateVAppTemplate URL of this vDC see Example 2 5 Because the operation creates...

Page 26: ...deploy and operate the vApp Example 2 7 shows a request and response for a deploy action The request URL is the rel deploy link returned in the vApp body see Example 2 8 The request body is a DeployV...

Page 27: ...reboot can be applied to either object See Deploying and Controlling vApps and Virtual Machines on page 80 Much additional information is available though most of it is not shown here The example doe...

Page 28: ...tp 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 v...

Page 29: ...to open a VMware Remote Console for the virtual machine represented by that Vm element Example 2 9 makes such a request using the acquireTicket link returned in Example 2 8 Example 2 9 Get a Screen T...

Page 30: ...you delete it The response is a Task body Because the task tracks a deletion it does not include an Owner element The owner is the object being deleted Example 2 10 Delete a vApp Request DELETE http...

Page 31: ...add or remove virtual hardware modify network connections and change other vApp properties Reconfiguring vApps and Virtual Machines on page 69 Administrative operations to create vDCs and Catalogs and...

Page 32: ...vCloud API Programming Guide 32 VMware Inc...

Page 33: ...ts Table 3 1 summarizes browsing requests supported in this release The table uses the following conventions API URL is a URL of the form http vcloud example com api v1 0 id is an integer Browsing 3 T...

Page 34: ...page 18 This lists includes only those organizations to which the logged in user has access The client can use a URL from this list to make an HTTP GET request that returns an Org document in the resp...

Page 35: ...Contents of a Catalog A client can use the href value from any of the rel down links in an Org body to get more information about the object to which the link refers as shown in Example 3 2 which requ...

Page 36: ...ia object Requests to get more information about a CatalogItem return a CatalogItem document that includes The URL of the referenced object Link elements that enable an authorized user to modify or re...

Page 37: ...nd 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...

Page 38: ...C Catalogs provide a level of indirection for references to media images and vApp templates A vApp template or media image can be referenced by a CatalogItem in a catalog or a ResourceEntity in a vDC...

Page 39: ...ResourceEntity element that references the template After client has the template s URL it can use it as the target of a GET request as shown in Example 3 6 which uses the href of the CatalogItem retu...

Page 40: ...esponse 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...

Page 41: ...ages can be added to catalogs as needed This chapter includes the following topics Summary of Provisioning Requests on page 41 Upload OVF to Create a vApp Template on page 42 View the OVF Descriptor o...

Page 42: ...gainst the contents of the manifest file Enable a vApp Template for Download POST API URL vAppTemplate vAppTemplate id action enableDownload None Task Disable a vApp Template for Download POST API URL...

Page 43: ...ree digits For example NewVirtualMachine1 and NewVirtualMachine2 become NewVirtualMa001 and NewVirtualMa002 Initiate the Upload To initiate the upload a client makes an HTTP POST request specifying a...

Page 44: ...4 3 Example 4 3 Upload OVF Descriptor Request PUT http vcloud example com transfer descriptor ovf Content Type text xml Envelope Envelope Response 200 OK After the descriptor is uploaded the server va...

Page 45: ...ading a package that includes a manifest file add a manifestRequired true attribute to the request body as shown in Example 4 5 Example 4 5 uploadVappTemplate Request for an OVF Package That Includes...

Page 46: ...ate vappTemplate 268 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 50000000...

Page 47: ...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 stream...

Page 48: ...descriptor can be downloaded as shown in Example 4 11 Example 4 11 vApp Template with DownloadURL for OVF Descriptor Request GET http vcloud example com api vAppTemplate vappTemplate 268 Response 200...

Page 49: ...ttribute of the File in the downloaded OVF descriptor The result of this process using the responses in Example 4 11 and Example 4 12 is the request URL shown in Example 4 13 Example 4 13 Downloading...

Page 50: ...alized file data to the File element s upload default URL Example 4 6 shows a similar request Example 4 16 Server Response to Request to Upload an ISO Image Content Type application vnd vmware vcloud...

Page 51: ...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...

Page 52: ...e copy The request can optionally include an IsSourceDelete element whose value specifies whether the source vApp is deleted after the copy is complete If IsSourceDelete is missing from the request bo...

Page 53: ...u are not changing Change the Name or Description of a vAppTemplate Example 4 20 changes the description of the vApp template shown in Example 3 6 on page 39 Example 4 20 Change the Name and Descripti...

Page 54: ...late is in use if it is being instantiated After instantiation is complete the template is no longer in use A vApp is in use if it is deployed A media image is in use if it is inserted in a Vm Catalog...

Page 55: ...used see Property on page 161 3 POST the CatalogItem body to the rel add URL included in the Catalog body Example 4 22 adds a CatalogItem to the catalog listed in Example 3 2 on page 35 Example 4 22 A...

Page 56: ...e 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 applicat...

Page 57: ...controlAccess Content Type application vnd vmware vcloud controlAccess xml ControlAccessParams xmlns http www vmware com vcloud v1 IsSharedToEveryone false IsSharedToEveryone AccessSettings AccessSet...

Page 58: ...m 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 Ever...

Page 59: ...equests Table 5 1 summarizes datacenter operations requests supported in this release The table uses the following conventions API URL is a URL of the form http vcloud example com api v1 0 id is an in...

Page 60: ...POST vApp or Vm URL power action suspend None Task Discard the Suspended State of a vApp or Virtual Machine POST vApp or Vm URL action discardSuspendedState None Task Shut Down a vApp or Virtual Mach...

Page 61: ...es such as CPU memory and network connections that must be allocated to the vApp by the vDC in which it is deployed Instantiation creates a vApp from the files specified in the template and allocates...

Page 62: ...plate If the template defines multiple networks then you must do the same in the InstantiateVAppTemplateParams request A Configuration element that specifies the organization network to which the vApp...

Page 63: ...ction instantiateVAppTemplate Content Type application vnd vmware vcloud instantiateVAppTemplateParams xml InstantiateVAppTemplateParams name Linux FTP server deploy true powerOn true xmlns http www v...

Page 64: ...d 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 customization...

Page 65: ...e deployed and powered on before it can be used Example 5 4 shows a composeVApp request that specifies two vAppTemplate sources and one Vm source The Vm source requires InstantiationParams that modify...

Page 66: ...ins a Task element The status of the vApp is initially 0 When composition is complete the status changes to 1 Finding Virtual Machine URLs to Use in a Composition Item Virtual machines Vm objects are...

Page 67: ...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...

Page 68: ...e that the capture creates 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 CaptureVAp...

Page 69: ...owing sections LeaseSettingsSection StartupSection NetworkConfigSection Modified sections must contain all required elements even if you are not changing their values Some elements in some sections ar...

Page 70: ...aseInSeconds 3600 StorageLeaseInSeconds DeploymentLeaseExpiration 2010 01 21T13 50 59 764 08 00 DeploymentLeaseExpiration LeaseSettingsSection ovf StartupSection href http vcloud example com api v1 0...

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

Page 72: ...pply any firewall related IP address restrictions by modifying the NetworkConnection of the Vm to which the FirewallRules apply as we do in Example 5 14 A wider range of IP addresses would allow this...

Page 73: ...lication Linux FTP server 7 Task The response is a Task element View or Modify vApp Lease Settings Lease settings apply to both vApps and vApp templates although vApp templates do not include deployme...

Page 74: ...Hardware Section of a Virtual Machine GET API URL vApp vm id virtualHardwareSection None VirtualHardwareSection Modify the Virtual Hardware Section of a Virtual Machine PUT API URL vApp vm id virtualH...

Page 75: ...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...

Page 76: ...tionIndex 0 NetworkConnectionIndex IpAddress 10 147 122 134 IpAddress IsConnected false IsConnected MACAddress 00 50 56 01 01 49 MACAddress IpAddressAllocationMode POOL IpAddressAllocationMode Network...

Page 77: ...connections ovf Info PrimaryNetworkConnectionIndex 0 PrimaryNetworkConnectionIndex NetworkConnection network vAppNetwork NetworkConnectionIndex 0 NetworkConnectionIndex IpAddress 10 147 122 134 IpAdd...

Page 78: ...al 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 The...

Page 79: ...cloud guestCustomizationSection xml href http vcloud example com api v1 0 vApp vm 12 guestCustomizationSection GuestCustomizationSection The modified GuestCustomizationSection in the request body chan...

Page 80: ...state are returned For example if a vApp is instantiated but not deployed only the links for deploy and remove are returned For a vApp that is powered on links for all actions except powerOn are retu...

Page 81: ...tion has no effect on the containing vApp The saveState attribute specifies whether the undeployed virtual machines are suspended and their suspend state saved or simply powered off The request body i...

Page 82: ...A powerOff request to a virtual machine URL powers off the specified virtual machine Example 5 22 Power Off a vApp or Virtual Machine Request to power off a vApp POST http vcloud example com api v1 0...

Page 83: ...vmware vcloud task xml Task Task Discard the Suspended State of a vApp or Virtual Machine A discardSuspendedState request to a vApp URL discards the suspended state of all of the virtual machines in...

Page 84: ...pp or Virtual Machine A reboot request to a vApp URL reboots all of the virtual machines in the vApp as specified in its ovf StartupSection element A reboot request to a virtual machine URL reboots th...

Page 85: ...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 ras...

Page 86: ...tp 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 Me...

Page 87: ...might cause the virtual machine to ask for additional user input before it can complete A vApp that contains a Vm awaiting a user response has status 5 and includes a link with rel down and type appli...

Page 88: ...ion 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...

Page 89: ...ement alone without the rest of the response in which it was contained All information about the task is included in the Task element when it is returned in the response s Tasks container so a client...

Page 90: ...vCloud API Programming Guide 90 VMware Inc...

Page 91: ...inistration on page 107 User Administration on page 110 Group Administration on page 113 Role Administration on page 114 Summary of Administrative Requests Table 6 1 summarizes administrative requests...

Page 92: ...No Content Remove a vDC DELETE API URL admin vdc id None Task Create a Catalog POST API URL admin org id catalogs Catalog Catalog Get an Administrative View of a Catalog GET API URL admin catalog id N...

Page 93: ...n Request GET http vcloud example com api v1 0 org 1 Response 200 OK Content Type application vnd vmware vcloud org xml Org xmlns http www vmware com vcloud v1 name System Org Administrative Objects a...

Page 94: ...ation 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 e...

Page 95: ...a 0 StoredVmQuota OrgLeaseSettings DeleteOnStorageLeaseExpiration false DeleteOnStorageLeaseExpiration DeploymentLeaseSeconds 604800 DeploymentLeaseSeconds StorageLeaseSeconds 2592000 StorageLeaseSeco...

Page 96: ...efaultSmtpServer IsDefaultOrgEmail true IsDefaultOrgEmail FromEmailAddress Admin example com FromEmailAddress DefaultSubjectPrefix Attention DefaultSubjectPrefix IsAlertEmailToAllAdmins true IsAlertEm...

Page 97: ...ackTrace 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 vc...

Page 98: ...ampleFinance 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...

Page 99: ...ion about any of these networks an administrator can make a GET request to the network s URL the href element of the Network element Example 6 9 makes such a request to the href of a Network element r...

Page 100: ...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 ex...

Page 101: ...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 xmln...

Page 102: ...the remove link in an OrgNetwork body to remove the network from the organization Example 6 13 does this making a DELETE request to the remove link returned in Example 6 11 Example 6 13 Remove a Netw...

Page 103: ...mware 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...

Page 104: ...vdc 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 An organization administra...

Page 105: ...xample 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...

Page 106: ...was returned when the vDC was created The response only part of which is shown in the example is an AdminVdc body containing the modified values Example 6 17 Modify a vDC Request PUT http vcloud examp...

Page 107: ...Virtual Datacenter 6 Task Catalog Administration A newly created organization has no catalogs in it An organization administrator must create them and specify their scope before items can be catalogue...

Page 108: ...d 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 co...

Page 109: ...Response 204 No Content Modify Catalog Metadata An administrator can modify catalog metadata such as its name and description by creating a modified Catalog body and PUTting it to the catalog s edit l...

Page 110: ...organization by POSTing a User body to the organization s add URL for users as shown in Example 6 24 which adds the user to the organization created in Example 6 3 The response is a User element most...

Page 111: ...e the value of the UserName element in UserAttributes and imports that user from LDAP See UserAttributes on page 184 Example 6 25 illustrates this sort of request Example 6 25 Import a User from LDAP...

Page 112: ...Telephone IsEnabled true IsEnabled IM NameInSource user example com NameInSource IsAlertEnabled false IsAlertEnabled IsDefaultCached false IsDefaultCached StoredVmQuota 1000 StoredVmQuota DeployedVmQ...

Page 113: ...here rel remove An administrator can use this link remove the user from the organization as shown in Example 6 28 Example 6 28 Remove a User Request DELETE http vcloud example com api v1 0 admin user...

Page 114: ...o view the Group body Modify Group Metadata An administrator can modify a Group body to change its Description or Role by PUTting a modified Group body to the edit URL for the group See Example 6 27 f...

Page 115: ...loud 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 applic...

Page 116: ...the name of the role by PUTting a modified Role body to the edit URL of the Role See Example 6 27 for an example of the workflow for this type of request Remove a Role A system administrator can use...

Page 117: ...equests supported in this release The table uses the following conventions API URL is a URL of the form http vcloud example com api v1 0 id is an integer VMware vSphere Platform Operations 7 NOTE All...

Page 118: ...Host GET API URL admin extension host id None Host Prepare a Host POST API URL admin extension host id action prepare PrepareHostParams Task Unprepare a Host POST API URL admin extension host id actio...

Page 119: ...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 e...

Page 120: ...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...

Page 121: ...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...

Page 122: ...must update the element if you make these changes to the server Example 7 5 disables the vCenter server shown in Example 7 3 and also changes its Description Example 7 5 Modify vCenter Server Setting...

Page 123: ...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...

Page 124: ...e hostReferences link returned in a VMWExtension response to request a list of all ESX ESXi hosts in the vCloud Example 7 9 makes such a request using the hostReferences link returned in Example 7 1 E...

Page 125: ...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 VimPropert...

Page 126: ...host to prevent vApps from starting up on the host Virtual machines that are already running on the host are not affected To perform maintenance on a host migrate all vApps off of the host or stop all...

Page 127: ...ProviderVdc object It includes elements that allow a system administrator to specify resources such as datastores and resource pools provided by a vCenter instance registered to the vCloud Only a sys...

Page 128: ...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 fo...

Page 129: ...loud 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 20971...

Page 130: ...675 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 vc...

Page 131: ...ferences to the ESX ESXi hosts registered to the vCenter server backing this provider vDC Examine the vSphere Objects in a Provider vDC A system administrator can retrieve a list of ProviderVdcReferen...

Page 132: ...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 extens...

Page 133: ...ttp 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 IpScop...

Page 134: ...to get more information about a specific external network Example 7 23 retrieves information about the external network created in Example 7 22 The entire VMWExternalNetwork body is returned in the r...

Page 135: ...oud 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 v...

Page 136: ...1 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 Sta...

Page 137: ...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 To modify a network pool m...

Page 138: ...can be imported in vApp or vApp template form Discover the Virtual Machines in a vCenter A GET request to the vmsList URL in a VimServer response body returns a list of virtual machines registered to...

Page 139: ...the importVmAsVApp link in the VimServer response body whose vmslist contained the VmObjectRef that represents the virtual machine Example 7 32 imports the virtual machine shown in Example 7 30 from...

Page 140: ...equest POST http vcloud example com api v1 0 admin extension vimServer 100 importVmAsVappTemplate Content type application vnd vmware admin importVmAsVAppTemplateParams xml ImportVmAsVAppTemplateParam...

Page 141: ...t server interaction In this guide reference information on each object representation includes the XML schema of the element that represents the object the object type encoded as the MIME content typ...

Page 142: ...server returns the current XML representation of that object Although URLs have a well known syntax and a well understood interpretation a client should treat each href as an opaque string The rules t...

Page 143: ...attern ReferenceType Many container elements are populated with references to contained objects Each reference consists of a hyperlink an optional media type and a name Common Attributes Elements such...

Page 144: ...indicates that a status value is allowed for the object listed in the column header Status for an object such as a vAppTemplate or vApp whose Children Vm objects each have a status of their own is com...

Page 145: ...wered off YES YES YES 9 The object is in an inconsistent state No YES YES 10 Children do not all have the same status YES YES No 11 Upload initiated OVF descriptor pending YES No No 12 Upload initiate...

Page 146: ...t Matches the HTTP status code See Status Codes on page 18 minorErrorCode 1 1 xs string Error code specific to the failed operation vendorSpecificErrorCode 0 1 xs string Empty in this release stackTra...

Page 147: ...each media type defined by the API The example shows only a few of these elements The response also includes a LoginUrl element which contains a URL that a client can use to obtain an authentication t...

Page 148: ...ntain an arbitrary number of elements and attributes VCloudExtensibleType is an abstract type that all complex types defined in the vCloud API namespace http www vmware com vcloud v1 extend This type...

Page 149: ...required true and client does not know how to interpret the contents of the element the client can ignore it but it must include the VCloudExtension in any request to modify the element that contains...

Page 150: ...vCloud API Programming Guide 150 VMware Inc...

Page 151: ...rg on page 151 Vdc on page 152 OrgNetwork on page 154 Catalog on page 160 Media on page 161 VAppTemplate on page 161 VApp on page 162 Vm on page 163 Section on page 163 ScreenTicket on page 168 TasksL...

Page 152: ...creation failed 0 not ready 1 ready 2 unknown 3 unrecognized status Description 0 1 xs string Optional description Tasks 0 1 TasksInProgressType Read only container for Task elements Each element in t...

Page 153: ...Continued Name Min Max Type Description Schema Name Min Max Type Description Used 0 1 xs long Percentage of the allocation in use This value is read only Overhead 0 1 xs long Number of Units allocate...

Page 154: ...status of the referenced object any attribute name 0 n any Includes type href XML namespace identifiers Files 0 1 FilesListType Read only container for File elements Schema Name Min Max Type Descripti...

Page 155: ...ses 0 1 IpAddressesType List of external IP addresses that this network can use for NAT Schema Continued Name Min Max Type Description Schema Name Min Max Type Description IpScope 0 1 IpScopeType Defi...

Page 156: ...IpRanges Schema Name Min Max Type Description StartAddress 1 1 IpAddressType Lowest IP address in the range EndAddress 1 1 IpAddressType Highest IP address in the range Schema Name Min Max Type Descri...

Page 157: ...protocols to which this firewall rule applies Port 1 1 xs int Specifies the network port to which this firewall rule applies A value of 1 matches any port DestinationIp 1 1 IpAddressType Specifies th...

Page 158: ...mplemented by network port forwarding Table 9 4 NatService Policy Element Values Value Result allowTraffic Packets of this type pass through the firewall in both directions allowTrafficIn Only inbound...

Page 159: ...hich this NAT rule maps the IP address specified in the InternalIP element ExternalPort 1 1 xs int Network port to which this NAT rule maps the port number specified in the InternalPort element Intern...

Page 160: ...L catalogItem id Table 9 6 VmRule Protocol Element Values Value Result TCP The rule applies to the TCP protocol UDP The rule applies to the UDP protocol TCP_UDP The rule applies to the TCP and UDP pro...

Page 161: ...description of a vApp It is created when you upload an OVF package to a vDC Content Type application vnd vmware vcloud vAppTemplate xml Object href prototype API URL vAppTemplate vAppTemplate id Sche...

Page 162: ...t are part of the template Children 0 1 VAppChildrenType Read only container for Vm elements representing virtual machines Section 0 n ovf Section_Type Any of the following ovf Section_Type elements L...

Page 163: ...ion CustomizationSection Children 0 n VAppChildrenType Read only container for Vm elements representing virtual machines Schema Continued Name Min Max Type Description Schema Name Min Max Type Descrip...

Page 164: ...ction xml Schema Name Min Max Type Description ovf required 0 1 xs boolean Optional indication of whether this element is required type 0 1 xs string Media type of this section href 0 1 xs anyURI URL...

Page 165: ...s string Media type of this section href 0 1 xs anyURI URL to access this section ovf Info 1 1 ovf Msg_Type Required by the base ovf Section_Type It can contain xs string information about the contain...

Page 166: ...cludes type href XML namespace identifiers network 1 1 xs string The name of the network to which this connection connects NetworkConnectionIndex 1 1 xs int The value in the rasd AddressOnParent eleme...

Page 167: ...0 1 xs boolean If true customization will run sysprep to change the Windows SID for this virtual machine VirtualMachineId 0 1 xs int Unique identifier for this virtual machine read only JoinDomainEna...

Page 168: ...result of a request cannot be returned immediately the server creates a Task object Tasks owned by an object such as a vApp or vDC are contained in the Tasks element of the object s XML representation...

Page 169: ...owner is the copy that is being created For delete operations the owner is the deleted object so this element is not included For all other operations the owner is the object to which the request was...

Page 170: ...vCloud API Programming Guide 170 VMware Inc...

Page 171: ...arams on page 173 RecomposeVAppParams on page 174 DeployVAppParams on page 175 UndeployVAppParams on page 175 CaptureVAppParams on page 175 CloneMediaParams on page 176 CloneVAppTemplateParams on page...

Page 172: ...ption name 1 1 xs string Specifies the name of the vApp created by this instantiation linkedClone 0 1 xs boolean Ignored in this release deploy 0 1 xs boolean True if the vApp should be deployed after...

Page 173: ...sition Defaults to false powerOn 0 1 xs boolean True if the vApp should be deployed and powered on after composition Defaults to false linkedClone 0 1 xs boolean Ignored in this release VAppParent 0 1...

Page 174: ...ingSystemSection NetworkConnectionSection GuestCustomizationSection NetworkAssignment 0 n NetworkAssignmentType Maps logical networks in the Source to logical networks in the composed vApp Schema Cont...

Page 175: ...p AllEULAsAccepted 0 1 xs boolean True if you accept the terms and conditions in the template s EULA sections Composition fails if false Schema Continued Name Min Max Type Description Schema Name Min...

Page 176: ...eleted after the copy is made Schema Name Min Max Type Description name 1 1 xs string Specifies the name of the new vApp template created by the clone operation Description 0 1 xs string Optional desc...

Page 177: ...Reference to the vApp to clone copy IsSourceDelete 0 1 xs boolean True if the object referenced by Source should be deleted after the copy is made Schema Continued Name Min Max Type Description Schem...

Page 178: ...ccessLevel element specifies the access level allowed for the user or group specified in Subject Table 10 1 shows permitted values for element content and the results they produce Schema Name Min Max...

Page 179: ...179 ExternalNetwork on page 180 AdminOrg on page 180 ProviderVdc on page 186 User on page 190 Group on page 191 Role on page 191 VCloud The vCloud element is a read only container for references to t...

Page 180: ...network to an AdminOrg see Add a Network to an Organization on page 100 ExternalNetwork A ExternalNetwork element defines a network that has been allocated to an organization by the system administra...

Page 181: ...ype elements that reference networks in the organization Schema Continued Name Min Max Type Description Schema Name Min Max Type Description IsEnabled 0 1 xs boolean True if this organization is enabl...

Page 182: ...xs boolean If true storage for a vApp is deleted when the vApp s lease expires If false the storage is flagged for deletion but not deleted DeploymentLeaseSeconds 0 1 xs int Default duration of a vApp...

Page 183: ...fines the authentication mechanism used by the LDAP service GroupSearchBase 0 1 xs string LDAP group search base IsGroupSearchBaseEnabled 1 1 xs boolean True if the group search base is enabled Connec...

Page 184: ...he user s given name For example givenName Surname 1 1 xs string LDAP attribute to use for the user s surname For example sn Telephone 1 1 xs string LDAP attribute to use for the user s telephone numb...

Page 185: ...organization uses the system default email properties FromEmailAddress 1 1 xs string If IsDefaultOrgEmail is false specifies the sender s email address that appears in email notifications DefaultSubj...

Page 186: ...cation vnd vmware admin providervdc xml Object href prototype API URL admin providervdc id Schema Name Min Max Type Description IsPublished 1 1 xs boolean Set to true to publish a catalog make it visi...

Page 187: ...Description Cpu 1 1 ProviderVdcCapacityType Defines CPU capacity available in the provider vDC Memory 1 1 ProviderVdcCapacityType Defines memory capacity available in the provider vDC IsElastic 0 1 x...

Page 188: ...ified only by administrators Content Type application vnd vmware admin vdc xml Object href prototype API URL admin vdc id Schema Name Min Max Type Description Units 1 1 xs string Units in which the ca...

Page 189: ...1 1 xs int Maximum number of OrgNetwork objects that can be deployed in this vDC Defaults to 0 which specifies an unlimited number VmQuota 0 1 xs int Maximum number of virtual machines that can be dep...

Page 190: ...ation model can specify values for resource and limit Schema Name Min Max Type Description name 1 1 xs string Common object name attribute The name of the user any attribute name 0 n any Includes type...

Page 191: ...sword 0 1 xs string The user s password This value is never returned by GET It is inspected on create and modify On modify the absence of this element indicates that the password should not be changed...

Page 192: ...t specifies the URL in a RightReference For more information see Get an Administrative View of a Cloud on page 93 Content Type application vnd vmware admin right xml Object href prototype API URL admi...

Page 193: ...olList on page 196 ShieldManager on page 196 VMWProviderVdc on page 197 VMWNetworkPool on page 198 VMWExternalNetwork on page 199 VMWHostReferences on page 199 Request Parameters on page 200 VMWExtens...

Page 194: ...VMWVimServerReferences element is a read only container for VimServerReference elements Content Type application vnd vmware admin vmwVimServerReferences xml Object href prototype API URL admin extens...

Page 195: ...onnecting to this vCenter server with a vSphere client IsEnabled 1 1 xs boolean True if the server is enabled for use with Cloud Director IsConnected 0 1 xs boolean True if this vCenter is ready to be...

Page 196: ...tRefsType Read only container for references to datastores in this resource pool Schema Name Min Max Type Description name 1 1 xs string Common object name attribute any attribute name 0 n any Include...

Page 197: ...e capacity available in this provider vDC StorageCapacity 0 1 ProviderVdcCapacityType Defines the storage capacity available in this provider vDC AvailableNetworks 0 1 AvailableNetworksType Read only...

Page 198: ...any attribute name 0 n any Includes type href XML namespace identifiers Description 0 1 xs string Optional description FenceIdCount 1 1 xs int Number of fence IDs in this pool VlanId 1 1 xs int Set to...

Page 199: ...works in this pool are in use Schema Continued Name Min Max Type Description Schema Name Min Max Type Description name 1 1 xs string Common object name attribute any attribute name 0 n any Includes ty...

Page 200: ...andby or maintenance mode CpuType 0 1 xs string CPU type of the host NumOfCpusLogical 1 1 xs int Number of logical CPUs NumOfCpusPackages 1 1 xs int Number of CPU packages CpuTotal 1 1 xs long Total C...

Page 201: ...VmName 0 1 xs string Virtual machine name VAppScopedLocalId 0 1 xs string Read only identifier created on import ComputerName 0 1 xs string Display name of this virtual machine VmMoRef 1 1 xs string...

Page 202: ...vCloud API Programming Guide 202 VMware Inc...

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

Page 204: ...ckage into a vApp by binding the package s abstract resource requirements to specific resources in a deployment environment defined by a vDC Because of its generality the OVF includes a great deal of...

Page 205: ...tualSystem referenced by its ovf diskId attribute value Example A 1 Virtual Disks in an OVF Envelope Envelope References File ovf href SimpleVM disk1 vmdk ovf id file1 ovf size 68096 References DiskSe...

Page 206: ...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 Con...

Page 207: ...me ways an unfortunate term since the application programs written to a REST API actually use HTTP requests which are often executed by a script or other higher level language as a way of making what...

Page 208: ...quest to an organization URL returns links to catalog and vDC objects contained by the organization Examine the response which always includes an HTTP response code and often includes a body an XML do...

Page 209: ...talogs 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...

Page 210: ...e 158 network vApp 62 NetworkConfigSection element example of use 71 O Org element example of use 22 schema reference 151 Org entity to retrieve 34 OrgList element example of use 21 OrgNetwork element...

Page 211: ...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...

Page 212: ...vCloud API Programming Guide 212 VMware Inc...

Search results

Summary of Contents for VCLOUD API 1.0 - TECHNICAL NOTE

Reviews:

Related manuals for VCLOUD API 1.0 - TECHNICAL NOTE

Brands by name

Popular brands

VMware VCLOUD API 1.0 - TECHNICAL NOTE, Programming Manual

Search results

Summary of Contents for VCLOUD API 1.0 - TECHNICAL NOTE

Reviews:

Related manuals for VCLOUD API 1.0 - TECHNICAL NOTE

Brands by name

Popular brands