Ver Enterprise Cloud. User s Guide for. API Function. ver1.03

Transcription

1 Enterprise Cloud User s Guide for API Function ver1.03 1

2 Index Index Use of this document Common Information... 5 API use flow...5 Preparation...5 API Workflow...5 API Endpoint API Users Management Viewing API User Adding API User vcloud Native API Supported API List Enterprise Cloud Unique Expansion API Managing Compute Resource Pools Create Compute Resource Pool View Compute Resource Pool Edit Compute Resource Pool Delete Compute Resource Pool Enterprise Cloud Unique Extension API Schema Operation Summary Syntax Type Reference Pages Operations API Operation API Operation API Operation API Operation 4 PUT API Operation 5 DELETE Types

3 6.4.1 EcVMWProviderVdcReferencesType EcProviderVdcReferenceType EcCreateVdcParamsType EcContractComputeType EcComputeCapacityType EcCapacityWithUsageType EcVdcType EcStorageCapacityType Error Code Reference Revision history

4 1 Use of this document This document summarizes operation API function procedure on Enterprise Cloud. 4

5 2 Common Information API use flow Preparation is needed to start using API function. Preparation Login to Customer Portal. Refer to Enterprise Cloud User s Guide for Customer Portal ver2.0 Customer Portal Login Add Manage API Users permission to Portal User account. Add API user. Refer to API User Management section. Link the Enterprise Cloud API user account above to API Gateway account. For more information, refer to the site of NTT Communications API Gateway Developers Portal. (Home > API & Docs > Enterprise Cloud > Enterprise Cloud API) API Workflow There are two kinds of API functions. 1) 2) vcloud Native API Refer to vcloud Native API section. vcloud API clients and vcloud Director servers communicate over HTTPS, exchanging XML representations of vcloud API objects. Please refer to following site for details about a workflow. vcloud: A Simplified RESTful Workflow < Enterprise Cloud Unique Extension API Refer to Enterprise Cloud Unique Expansion API section in this document. vcloud API 5.5 and Enterprise Cloud Unique Extension API have the following points in common. - API User Account - API End Point - Available characters for API (refer to Reference 1) 5

6 API Endpoint As for the information of API Gateway Endpoint, refer to the site of NTT Communications API Gateway Developers Portal. OVF upload is not supported via API Gateway. When executing this operation via API, it is necessary to operate directly with original Enterprise Cloud API FQDNs, not those of API Gateway. Please refer to 3.1 Viewing API User section for more details on the FQDNs. In case operating directly with original Enterprise Cloud API user account and FQDN, you cannot enjoy the benefit of API Gateway such as correcting API log. For more details, please refer 6

7 3 API Users Management 3.1 Viewing API User This section explains API user viewing procedure. Manage API Users Permission is needed to use API function. So please add Manage API Users permission to Portal User account beforehand. 1) Put cursor on [1] and click on [2] on EC Management Screen. 7

8 2) API user list will be displayed. Please confirm the following table about displayed contents of each item. Referable Information on API user management window Item a Contents The Organization to which the API User belongs to b Enterprise Cloud Original API Endpoint * ** c d API User Name API User Status (valid / invalid) *This Endpoint is different from those of API Gateway. In case you would like to utilize API Gateway and its benefit, it is necessary to operate with API Gateway Endpoint with API Gateway Account. For more details, please refer * When executing ova upload operation via API, it is necessary to operate directly with this FQDN. 8

9 3.2 Adding API User This section explains API user adding procedure. 1) Click on [1] from API Users management window. 2) Add API User window will be displayed. Click [2] after input parameters. Please confirm the following table about input rules. 9

10 Input rules in adding API user item Entry Field Contents Mandatory/Optional Rule a text box Input API User Name Mandatory One-byte alphanumeric (128 characters) b text box Input login password Mandatory more than 6 character c text box Confirm password Mandatory more than 6 character d text box Enable API User when check is put in Optional none 3) To confirm that API User has been added, click [3]. 4) Management Task window will be displayed. If the task is accepted, adding API User is completed. Click on [4]. 10

11 5) If you want to confirm detailed task information, click on [5]. 6) If you use API Gateway, activating the API Gateway and Account Registration of Enterprise Cloud API is needed. Refer to NTT Communications Developers Site. 11

12 4 vcloud Native API This section explains vcloud Native API. 4.1 Supported API List The list in this section describes supported API. Note that the API list is based on vcloud API Schema Reference. For more detailed of each API, see the vcloud API Programming Guide and vcloud Director REST API Reference Documentation. The URL is written in Enterprise Cloud Functional Description for API Function (Reference 1). The URLs in the below table should follow " Point URL}/api/". Method PUT DELETE DELETE URL /catalog/{id} /catalog/{id}/action/capturevapp /catalog/{id}/action/upload /catalogitem/{id} /catalogitem/{id} /catalogitem/{id} /catalogs/query /network/{id} /network/{id}/allocatedaddresses /org /org/{id} /query /session /session /sessions /task/{id} 12

13 13 Method URL /taskslist/{id} /vapp/vm-{id}/action/reconfigurevm /vapp/{id} PUT /vapp/{id} DELETE /vapp/{id} /vapp/{id}/action/deploy /vapp/{id}/action/installvmwaretools /vapp/{id}/action/undeploy /vapp/{id}/action/upgradehardwareversion /vapp/{id}/guestcustomizationsection PUT /vapp/{id}/guestcustomizationsection /vapp/{id}/networkconfigsection PUT /vapp/{id}/networkconfigsection /vapp/{id}/networkconnectionsection PUT /vapp/{id}/networkconnectionsection /vapp/{id}/networksection /vapp/{id}/power/action/poweroff /vapp/{id}/power/action/poweron /vapp/{id}/power/action/reboot /vapp/{id}/power/action/reset /vapp/{id}/power/action/shutdown /vapp/{id}/power/action/suspend /vapp/{id}/virtualhardwaresection PUT /vapp/{id}/virtualhardwaresection /vapp/{id}/virtualhardwaresection/cpu PUT /vapp/{id}/virtualhardwaresection/cpu

14 Method PUT PUT PUT PUT DELETE URL /vapp/{id}/virtualhardwaresection/disks /vapp/{id}/virtualhardwaresection/disks /vapp/{id}/virtualhardwaresection/memory /vapp/{id}/virtualhardwaresection/memory /vapp/{id}/virtualhardwaresection/networkcards /vapp/{id}/virtualhardwaresection/networkcards /vapptemplate/{id} /vapptemplate/{id} /vapptemplate/{id} /vapptemplate/{id}/action/disabledownload /vapptemplate/{id}/action/enabledownload /vapptemplates/query /vapps/query /vapp/{id}/action/createsnapshot *1 /vapp/{id}/action/removeallsnapshots *1 /vapp/{id}/action/reverttocurrentsnapshot *1 /vapp/{id}/snapshotsection *1 /vdc/{id} /vdc/{id}/action/composevapp /vdc/{id}/action/instantiatevapptemplate /vdcstorageprofile/{id} /vms/query /admin/orgs/query /admin/vdcs/query *1 Only it is provided by some of the data center. For more information Enterprise Cloud Functional Description for API Function 14

15 The URL follows Point URL}. Method PUT URL /transfer/{id}/{filename} /transfer/{id}/{filename} 15

16 5 Enterprise Cloud Unique Expansion API Enterprise Cloud Unique Extension defines unique API operations and API types as "API Schema", detailed information is written in Enterprise Cloud Unique Expansion API Schema section. It is not included in the vcloud API Programming Guide or vcloud Director REST API Reference Documentation, it is necessary to read this document carefully and understand their contents when using the Enterprise Cloud Unique Extension API. 5.1 Managing Compute Resource Pools By utilizing Enterprise Cloud Unique Extension API, the following operations can be performed for Compute Resource Pools. - Create Compute Resource Pool - View Compute Resource Pool - Edit Compute Resource Pool - Delete Compute Resource Pool This section discusses concepts necessary to understand beforehand in order perform Compute Resource Pool operations. OrgVDC A Compute Resource Pool within the Enterprise Cloud service is handled as an "Organization Virtual Data Center (OrgVDC)" according to VMware terminology. As such, performing Compute Resource Pool operations is synonymous with performing OrgVDC operations. For details on OrgVDC, please refer to the vcloud Director User's Guide etc. released by VMware. As a note, there are API functions for vcloud API 5.5 to perform OrgVDC operations, but API user accounts provided by the Enterprise Cloud service do not have permissions to utilize these API functions. As such, when operating the OrgVDC via API, it is absolutely necessary to utilize Enterprise Cloud Unique Extension API. 16

17 PvDC OrgVDC is released on a parent resource called "Provider Virtual Data Center (PvDC)." As such, when creating an OrgVDC, it is necessary to designate the target PvDC for creation. As a note, the PvDC is managed by the service provider, and API users cannot perform operations on the PvDC. Additionally, PvDC <name> information is controlled and differs according to the Compute Resource service contract type. Shared Compute Cases For Shared Compute, <name> information is maintained as one string that ties together the Compute Class, Storage Class, and Zone information with a "/" (forward slash). For example, the value for <name> could be set as "Guaranteed Compute/Premium Storage/Zone B" in one string. Possible values for Compute Class, Storage Class, and Zone, as well as their meanings, are described below. Compute Class Value Guaranteed Compute Premium Compute Standard Compute Description Value that indicates that the Compute Resource Pool Compute Class is "Guaranteed Compute." Value that indicates that the Compute Resource Pool Compute Class is "Premium Compute." Value that indicates that the Compute Resource Pool Compute Class is "Standard Compute." Storage Class Value Premium Storage Standard Storage Description Value that indicates that the Compute Resource Pool Storage Class is "Premium Storage." Value that indicates that the Compute Resource Pool Storage Class is "Standard Storage." 17

18 Zone Value Zone A Zone B Description Value that indicates that the Compute Resource Pool storage zone is "Zone A." Value that indicates that the Compute Resource Pool storage zone is "Zone B." Dedicated Compute Cases For Dedicated Compute, the Dedicated Cluster name designated on the service application is maintained as the <name> value Create Compute Resource Pool In order to create a Compute Resource Pool (OrgVDC) the following steps must be performed. 1) Retrieve list of available PvDCs. 2) Select target PvDC for Compute Resource Pool (OrgVDC) creation. 3) Create a Compute Resource Pool (OrgVDC) on the selected PvDC. 18

19 Retrieve List of Available PvDCs Using " /ext/admin/extension/providervdcreferences", the PvDC list will be retrieved. The <ProviderVdcReference> type included within the response body indicates the PvDCs available for OrgVDC creation. <vmext:providervdcreference name="guaranteed Compute/Premium Storage/Zone B" href=" Point URL}/api/providervdc/2e6f3356-c f-9740-b6a04eb6a21b" type="application/vnd.vmware.admin.vmwprovidervdc+xml"/> <vmext:providervdcreference name="pvdc_dedicated02" href=" Point URL}/api/providervdc/a109e065-cb87-45f5-ad2e-8603c065b3f1" type="application/vnd.vmware.admin.vmwprovidervdc+xml"/> Select Target PvDC for Compute Resource Pool (OrgVDC) Creation Scan each PvDC <name> attribute from the PvDC list that was retrieved, and select a target PvDC for OrgVDC creation. For this step, the <href> attribute must be obtained for the selected PvDC. 19

20 Create a Compute Resource Pool (OrgVDC) on the Selected PvDC Using " /ext/admin/org/{org ID}/vdcsparams", the OrgVDC will be created on the target PvDC. The PvDC can be designated by setting the <href> attribute of the <ProviderVdcReference> type to the <href> attribute obtained previously. Along with this, the contract amounts for CPU resource, Memory resource, and Storage resource, as well as the OrgVDC name, can be designated. Below is an example request body where the CPU resource is 10GHz, Memory resource is 20GB, Storage resource is 50GB, and the name is designated as "Pool-0045." <?xml version="1.0" encoding="utf-8"?><createvdcparams name="pool-0045" xmlns=" <ContractCompute> <ContractCpuGHZ>10</ContractCpuGHZ> <ContractMemoryGB>20</ContractMemoryGB> </ContractCompute> <ContractStorageGB>50</ContractStorageGB> <ProviderVdcReference href=" Point URL}/api/admin/providervdc/2e6f3356-c f-9740-b6a04eb6a21b"/> </CreateVdcParams> This operation is asynchronous and returns a task that can be monitored to track the progress of the request. When using the Compute Resource (Dedicated Device) service, the values for <CpuGuaranteedRatio> and <MemoryGuaranteedRatio> must be designated. 20

21 5.1.2 View Compute Resource Pool In order to view a Compute Resource Pool (OrgVDC) the following steps must be performed. 1) Select the OrgVDC to be viewed. 2) View the selected OrgVDC. Select the OrgVDC to be Viewed Using " /admin/vdcs/query", the OrgVDC list will be retrieved. Next, select the OrgVDC to be viewed from the list. Here, the <href> attribute must be obtained for the selected OrgVDC. View the Selected OrgVDC Using " /ext/admin/vdc/{orgvdc ID}", the OrgVDC information will be retrieved. The object ID contained within the <href> obtained previously should be designated inside {OrgVDC ID}. Below is an example response message. The contract amounts for CPU resource, Memory resource, and Storage resource, as well as usage amount, can be viewed. <?xml version= 1.0 encoding= UTF-8?><Vdc name= Pool-0048 href= Point URL}/api/vdc/* id= urn:vcloud:vdc:*** status= 1 type= application/vnd.vmware.vcloud.vdc+xml xmlns= xmlns:vmext= xsi:schemalocation=" Point URL}/api/v1.5/schema/vmwextensions.xsd Point URL}/api/v1.5/schema/master.xsd""> <ComputeCapacity> <Cpu> 21

22 <Contract>10</Contract> <Units>GHz</Units> <Used>5</Used> </Cpu> <Memory> <Contract>20</Contract> <Units>GB</Units> <Used>3</Used> </Memory> </ComputeCapacity> <ProviderVdcReference name="pvdc_for_vapp_for_mig" href=" Point URL}/api/admin/providervdc/*" type="application/vnd.vmware.admin.providervdc+xml"/> <StorageCapacity> <Contract>550</Contract> <Units>GB</Units> <Used>162</Used> </StorageCapacity> </Vdc> Edit Compute Resource Pool In order to edit a Compute Resource Pool (OrgVDC) the following steps must be performed. 1) View target OrgVDC. 2) Edit target OrgVDC. 22

23 View Target OrgVDC By following the steps described in "View Compute Resource Pool", the OrgVDC contract amounts for CPU resource, Memory resource, and Storage resource, as well as name information, can be retrieved. For this step, the changes necessary for each item should be determined. Edit Target OrgVDC Using "PUT /ext/admin/vdc/{orgvdc ID}", the target OrgVDC information can be edited. Below is an example request body where CPU resource is set to 2GHz, Memory resource is set to 10GB, Storage resource is set to 100GB, and the name is set to "new name." <?xml version="1.0" encoding="utf-8"?> <CreateVdcParams name="new name" xmlns=" <ContractCompute> <ContractCpuGHZ>2</CpuGHZ> <ContractMemoryGB>10</ContractMemoryGB> </ContractCompute> <ContractStorageGB>100</ContractStorageGB> </CreateVdcParams> 23

24 This operation is asynchronous and returns a task that can be monitored to track the progress of the request. When no change is necessary for certain settings, the value should be set to the current value. If all attributes or elements are not specified, an error will occur. The contract amounts for CPU resource, Memory resource and Storage resource cannot be changed to a value smaller than the value currently in use by vapps/vms. When using the Compute Resource (Dedicated Device) service, the values for <CpuGuaranteedRatio> and <MemoryGuaranteedRatio> must be designated Delete Compute Resource Pool In order to delete a Compute Resource Pool (OrgVDC) the following steps must be performed. 1) Select the OrgVDC to be deleted. 2) Deleted the selected OrgVDC. Select the OrgVDC to be Deleted Using " /admin/vdcs/query", the OrgVDC list will be retrieved. Next, select the OrgVDC to be deleted from the list. Here, the <href> attribute must be obtained for the selected OrgVDC. 24

25 Delete the Selected OrgVDC Using "DELETE /ext/admin/vdc/{orgvdc ID}", the target OrgVDC will be deleted. The value included within the <href> obtained previously should be designated inside {OrgVDC ID}. As this operation is asynchronous, a task will be returned as a response. The return task cannot be retrieved using the " /task/{id}" API. If the status of the returned task is "success", then the task has successfully completed. In other cases, please check the presence of the OrgVDC by using the " /vdc/{id}" API. If the OrgVDC remains, it is possible that the delete request may have failed. In this case, please retry the delete request, or contact our support team. Should objects such as vapps or VMs remain in the target OrgVDC for deletion, an error will occur. When deleting OrgVDCs, related objects must be deleted beforehand. 25

26 6 Enterprise Cloud Unique Extension API Schema This section explains Enterprise Cloud Unique Extension API Schema. 6.1 Operation Summary Syntax Operations consist of an HTTP verb and a request URL. The reference documentation represents the verb and the URL using the following syntax: HTTP_VERB / object_type /{id}[/action/ action_name ] In this syntax, the initial/character is assumed to follow a site-specific API URL. The following strings represent variables in the remainder of the URL. Description HTTP_VERB The HTTP verb used to request the operation. object_type {id} An abbreviation of the MIME type of the object referenced by the operation. This abbreviation is constructed from the final component of the object's media type, between the. (dot) and the + xml designation. The unique identifier for the object of the operation. action_name The name of an action. Required only when the operation request URL includes the string /action/. 26

27 6.2 Type Reference Pages For each element or complex type, the reference documentation provides a page that lists the following items. Description Element Description Attributes Attribute Type Required The name of the element. The type of the element. The name of the attribute. The primitive XML type of the attribute. "Yes" for attributes that are required. "No" for attributes that are optional. Description A description of the purpose and contents of the attribute. Elements Element Type The name of the element. A link to the definition of the complex type on which the element is based. Required "Yes" for elements that are required. "No" for elements that are optional. Description A description of the purpose and contents of the element. 6.3 Operations The URLs in the below table should follow " Point URL}/api...". No Method URL Description 1 /ext/admin/extension/providervdcreferences Get available PvDCs. 2 /ext/admin/org/{org ID}/vdcsparams Add a new OvDC. 3 /ext/admin/vdc/{orgvdc ID} Get OvDC info. 4 PUT /ext/admin/vdc/{orgvdc ID} Edit an existing OvDC. 5 DELETE /ext/admin/vdc/{orgvdc ID} Delete an existing OvDC. 27

28 6.3.1 API Operation 1 Input Parameters Consumed Media Type(s) (None) Input Type (None) Output Parameters Produced Media Type(s) application/vnd.vmware.admin.vmwprovidervdcreferences+xml Output Type EcVMWProviderVdcReferencesType Request Exsample HTTP 1.1 /api/ext/admin/extension/providervdcreferences Headers x-vcloud-authorization: M69zc2o7Ol7AuYVBAslGYbnTluZZVZKIYa1HPe8MzEk= Body (None) Reponse Exsample HTTP/ OK Body <?xml version="1.0" encoding="utf-8"?><vmext:vmwprovidervdcreferences type="application/vnd.vmware.admin.vmwprovidervdcreferences+ xml" xmlns:vcloud=" 28

29 xmlns:vmext=" xmlns:xsi=" xsi:schemalocation=" Point URL}/api/v1.5/schema/vmwextensions.xsd Point URL}/api/v1.5/schema/master.xsd"> <vmext:providervdcreference name="guaranteed Compute/Premium Storage/Zone B" href=" Point type="application/vnd.vmware.admin.vmwprovidervdc+xml"/> <vmext:providervdcreference name="pvdc_dedicated02" href=" Point type="application/vnd.vmware.admin.vmwprovidervdc+xml"/> </vmext:vmwprovidervdcreferences> API Operation 2 Input Parameters Consumed Media Type(s) application/vnd.vmware.admin.createvdcparams+xml Input Type EcCreateVdcParamsType Output Parameters This operation is asynchronous and returns a task that can be monitored to track the progress of the request. 29

30 Produced Media Type(s) application/vnd.vmware.vcloud.task+xml Output Type TaskType Request Examples HTTP Point URL}/api/ext/admin/{Org ID}/vdcsparams Headers x-vcloud-authorization: ytl8fupmy9lrmxcfsncdrjaahpn2ur/osxwliztqhuk= Body <?xml version="1.0" encoding="utf-8"?><createvdcparams name="pool-0045" xmlns=" <ContractCompute> <ContractCpuGHZ>10</ContractCpuGHZ> <ContractMemoryGB>20</ContractMemoryGB> </ContractCompute> <ContractStorageGB>50</ContractStorageGB> <ProviderVdcReference href=" Point URL}/api/admin/providervdc/*"/> </CreateVdcParams> Response Exsample HTTP/ OK Body <?xml version="1.0" encoding="utf-8"?><task 30

31 name="task" expirytime=" t12:16:38.523z" href=" Point URL}/api/task/*" id="urn:vcloud:task:*" operation="created Virtual Datacenter Pool-0048(*)" operationname="vdccreatevdc" starttime=" t12:16:38.523z" status="success" xmlns=" xmlns:vcloud=" xmlns:xsi=" xsi:schemalocation=" Point URL}/api/v1.5/schema/master.xsd"> <Organization name="org-name" href=" Point URL}/api/org/*" type="application/vnd.vmware.vcloud.org+xml"/> <Owner name="pool-0048" href=" Point URL}/api/vdc/*" type="application/vnd.vmware.vcloud.vdc+xml"/> <Progress>0</Progress> </Task> API Operation 3 Input Parameters Consumed Media Type(s) 31

32 (None) Input Type (None) Output Parameters Produced Media Type(s) application/vnd.vmware.admin.vdc+xml Output Type EcVdcType Request Exsample HTTP Point URL}/api/ext/admin/vdc/eea382ad-9efe-42c6-a31e-fdc55c3c1b2a Headers x-vcloud-authorization: evbkzn2wahpau+ivburo7ekslpuohermb2dzefljuhs= Body (None) Response Exsample HTTP/ OK Body <?xml version= 1.0 encoding= UTF-8?><Vdc name= Pool-0048 href= Point URL}/api/vdc/* id= urn:vcloud:vdc:*** status= 1 type= application/vnd.vmware.vcloud.vdc+xml 32

33 xmlns= xmlns:vmext= xsi:schemalocation=" Point URL}/api/v1.5/schema/vmwextensions.xsd Point URL}/api/v1.5/schema/master.xsd""> <ComputeCapacity> <Cpu> <Contract>10</Contract> <Units>GHz</Units> <Used>5</Used> <Guaranteed Ratio>80</Guaranteed Ratio> </Cpu> <Memory> <Contract>20</Contract> <Units>GB</Units> <Used>3</Used> <Guaranteed Ratio>90</Guaranteed Ratio> </Memory> </ComputeCapacity> <ProviderVdcReference name="pvdc_for_vapp_for_mig" href=" Point URL}/api/admin/providervdc/*" type="application/vnd.vmware.admin.providervdc+xml"/> <StorageCapacity> <Contract>550</Contract> <Units>GB</Units> <Used>162</Used> </StorageCapacity> 33

34 </Vdc> API Operation 4 PUT Input Parameters Consumed Media Type(s) application/vnd.vmware.admin.vdc+xml Input Type EcCreateVdcParamsType Output Parameters This operation is asynchronous and returns a task that can be monitored to track the progress of the request. Produced Media Type(s) application/vnd.vmware.vcloud.task+xml Output Type TaskType Request Exsample HTTP 1.1 PUT Point URL}/api/ext/admin/vdc/eea382ad-9efe-42c6-a31e-fdc55c3c1b2a Headers x-vcloud-authorization: ytl8fupmy9lrmxcfsncdrjaahpn2ur/osxwliztqhuk= Body <?xml version="1.0" encoding="utf-8"?> <CreateVdcParams 34

35 name="new name" xmlns=" <ContractCompute> <ContractCpuGHZ>2</CpuGHZ> <ContractMemoryGB>10</ContractMemoryGB> </ContractCompute> <ContractStorageGB>100</ContractStorageGB> </CreateVdcParams> Response Exsample HTTP/ OK Body <?xml version="1.0" encoding="utf-8"?><task name="task" expirytime=" t12:16:38.523z" href=" Point URL}/api/task/*" id="urn:vcloud:task:*" operation="created Virtual Datacenter Pool-0048(*)" operationname="vdccreatevdc" starttime=" t12:16:38.523z" status="success" xmlns=" xmlns:vcloud=" xmlns:xsi=" xsi:schemalocation=" Point URL}/api/v1.5/schema/master.xsd"> 35

36 <Organization name="org-name" href=" Point URL}/api/org/*" type="application/vnd.vmware.vcloud.org+xml"/> <Owner name="pool-0048" href=" Point URL}/api/vdc/*" type="application/vnd.vmware.vcloud.vdc+xml"/> <Progress>0</Progress> </Task> API Operation 5 DELETE Input Parameters Consumed Media Type(s) (None) Input Type (None) Output Parameters This operation is asynchronous. Produced Media Type(s) application/vnd.vmware.vcloud.task+xml Output Type TaskType The return task cannot be retrieved using the " /task/{id}" API. If the status of the returned task is "success", then the task has successfully completed. In other cases, please check the presence of the OrgVDC by using the " /vdc/{id}" 36

37 API. If the OrgVDC remains, it is possible that the delete request may have failed. In this case, please retry the delete request, or contact our support team. Request Exsample HTTP 1.1 DELETE Point URL}/api/ext/admin/vdc/eea382ad-9efe-42c6-a31e-fdc55c3c1b2a Headers x-vcloud-authorization: ytl8fupmy9lrmxcfsncdrjaahpn2ur/osxwliztqhuk= Body (None) Response Exsample HTTP/ OK Body <?xml version="1.0" encoding="utf-8"?><task Error="" expirytime=" t11:14:40.403z" href=" Point URL}/api/task/*" id="urn:vcloud:task:*" name="task" operation="deleted Virtual Datacenter Pool-0048(*)" operationname="vdcdeletevdc" starttime=" t11:14:40.403z" status="success" xmlns=" xmlns:vcloud=" 37

38 xmlns:xsi=" <Progress>100</Progress> </Task> 6.4 Types API types for Enterprise Cloud Unique Extension API are defined according to the table below. No Type Description 1 EcVMWProviderVdcReferencesType Represents a list of available Provider vdcs. 2 EcProviderVdcReferenceType Container for references to the Provider vdc. 3 EcCreateVdcParamsType Parameters for creating an Organization vdc. 4 EcContractComputeType Container for contract resource amount of CPU and Memory of an Organization vdc. 5 EcComputeCapacityType Represents the capacity and usage of a given resource. 6 EcCapacityWithUsageType Represents the capacity and usage of a given resource. 7 EcVdcType Represents the user view of an Organization vdc. 8 EcStorageCapacityType Represents vdc storage capacity. 38

39 6.4.1 EcVMWProviderVdcReferencesType Attributes Attribute Type Required Description type string Yes The MIME type of the entity. Elements Element Type Required Description ProviderVdcReference EcProviderVdcReferenceType Yes Only the available Provider vdcs where new OrgVDCs can be created are listed. 39

40 6.4.2 EcProviderVdcReferenceType Attribute Attribute Type Required Description name string No The name of the Provider vdc. The name includes Compute Class, Storage Class, Zone, and optimized service information as follows. o "Guaranteed Compute/Premium Storage/Zone A/Oracle SE RAC" When using " /ext/admin/org/{org ID}/vdcsparams", this attribute is not required. href anyuri Yes The URI of the Provider vdc. type string No The MIME type of the entity. When using " /ext/admin/org/{org ID}/vdcsparams", this attribute is not required. 40

41 6.4.3 EcCreateVdcParamsType Attributes Attribute Type Required Description name string Yes The name of the OrgVDC. Elements Element Type Required Description ContractCompute EcContractComputeType Yes The CPU and Memory contract values for the OrgVDC. ContractStorageGB int Yes The contract Storage resource amount for the OrgVDC. The unit is always in GB. ProviderVdcReference EcProviderVdcReferenceType No A container for references to the Provider vdc. When using " /ext/admin/org/{org ID}/vdcsparams", this element is required. When using "PUT /ext/admin/vdc/{orgvdc ID}", this element is not required. 41

42 6.4.4 EcContractComputeType Elements Element Type Required Description ContractCpuGHZ int Yes Contract resource amount of CPU for the OrgVDC. The unit is always in GHz. CpuGuaranteedRatio int No CPU resource guaranteed ratio. The unit is always in %. For the Compute Resource (Shared Device) service, this element must be null. Otherwise, an error will occur. For the Compute Resource (Dedicated Device) service, this element muse be set. Otherwise, an error will occur. ContractMemoryGB int Yes Contract resource amount of Memory for the OrgVDC. The unit is always in GB. MemoryGuaranteedRatio int No Memory resource guaranteed ratio. The unit is always in %. For the Compute Resource (Shared Device) service, this element must be null. Otherwise, an error will occur. For the Compute Resource (Dedicated Device) service, this element muse be set. Otherwise, an error will occur. 42

43 6.4.5 EcComputeCapacityType Elements Element Type Required Description Cpu EcCapacityWithUsageType Yes CPU capacity and usage. Memory EcCapacityWithUsageType Yes Memory capacity and usage EcCapacityWithUsageType Elements Element Type Required Description Contract int Yes For the Compute Resource (Shared Device) service, the following value is set. o o For "Guaranteed" or "Standard" Compute Class, the limit value is set. For "Premium" Compute Class, the reservation value is set. For the Compute Resource (Dedicated Device) service, the limit value is set. Units string Yes For CPU resource, "GHz" is always set. For Memory resource, "GB" is always set. Used int Yes This value is set according to the performance DB based on the vcenter. For CPU resource, the unit is in GHz. 43

44 Element Type Required Description For Memory resource, the unit is in GB. Guaranteed Ratio int No The guaranteed percentage value is set. For the Compute Resource (Dedicated Device) service, this element is required. o Equal to "(reservation value / limit value) * 100". For the Compute Resource (Shared Device) service, this element is not required EcVdcType Attribute Attribute Type Required Description name string Yes The name of the OrgVDC. href anyuri Yes The URI of the OrgVDC. id string No The entity identifier expressed in URN format. The value of this attribute uniquely identifies the entity, persists for the life of the entity, and is never reused. status int No Creation status of the vdc represented as one of the following values: 0 (The vdc is being created.) 44

45 Attribute Type Required Description 1 (The vdc is ready.) -1 (An error occurred while creating the vdc.) type string No The MIME type of the entity. Elements Element Type Required Description ComputeCapacity EcComputeCapacityType Yes The CPU and Memory configuration for the OrgVDC ProviderVdcReference EcProviderVdcReferenceType Yes A container for references to the Provider vdc. StorageCapacity EcStorageCapacityType Yes This type represents vdc storage capacity. 45

46 6.4.8 EcStorageCapacityType Elements Element Type Required Description Contract int Yes Contract resource amount for an Org VDC. Units string Yes The Storage resource unit. "GB" is always set. Used int Yes This value is set according to the performance DB based on the vcenter. The unit is in GB. 46

47 6.5 Error Code The followings are major error codes within the Enterprise Cloud Unique Extension API. Method URL Error Scenario Response Error Code Response Message Description (Any) - Timeout due to some issue. 504 GATEWAY _TIMEOUT External service 'AddOvdc' failed to respond in the specified timeout (100 SECONDS) /ext/admin Attempt to create an 500 gcv-steps: Compute CreareOvdc /org/{org OvDC with a name ERROR_T pool CO01 is the ID}/vdcsp that is already in YPE_OPER CreareOvdcCO01 OvCD name arams use. ATION already exists was that attempted to be created. /ext/admin Attempt to create an 500 gcv-steps: Web /org/{org OvDC with a name ERROR_T service method ID}/vdcsp longer than 127 YPE_OPER add_org_vdc(): arams characters. ATION XMLRPC Fault: Internal Server Error - org.hibernate.excep tion.dateexception: could not insert: [com.vmware.vclou d.common.model.ev ent.auditevent] - could not insert: [com.vmware.vclou 47

48 Method URL Error Scenario Response Error Code Response Message d.common.model.ev ent.auditevent] Description /ext/admin Attempt to create an must be integer 2.3 is the /org/{org OvDC with number BAD_REQ value that ID}/vdcsp of CPU set to a UEST was arams decimal number. attempted to be assigned to CPU Resource. /ext/admin Attempt to create an is less then 1 is the /org/{org OvDC with number BAD_REQ minimum CPU:2 value that ID}/vdcsp of CPU set below UEST was arams the minumum value. attempted to be assigned to CPU Resource, and 2 is the minimum value. /ext/admin Attempt to create an is exceed 5 is the /org/{org OvDC with number BAD_REQ maximum CPU:4 value that ID}/vdcsp of CPU set above UEST was arams the maximum value. attempted to be assigned to CPU Resource, and 4 is the maximum value. 48

49 Method URL Error Scenario Response Error Code Response Message Description /ext/admin Attempt to create an must be integer 2.3 is the /org/{org OvDC with Memory BAD_REQ value that ID}/vdcsp set to a decimal UEST was arams number. attempted to be assigned to Memory Resource. /ext/admin Attempt to create an is less then 1 is the /org/{org OvDC with Memory BAD_REQ minimum value that ID}/vdcsp set below the UEST MEMORY:2 was arams minimum value. attempted to be assigned to Memory Resource, and 2 is the minimum value. /ext/admin Attempt to create an is exceed 5 is the /org/{org OvDC with Memory BAD_REQ maximum value that ID}/vdcsp set above the UEST MEMORY:4 was arams maximum settings attempted to value. be assigned to Memory Resource, and 4 is the maximum value. /ext/admin Attempt to create an must be integer 49.3 is the /org/{org OvDC with Storage BAD_REQ value that 49

50 Method URL Error Scenario Response Error Code Response Message Description ID}/vdcsp set to a decimal UEST was arams number. attempted to be assigned to Storage Resource. /ext/admin Attempt to create an is less then 20 is the /org/{org OvDC with Storage BAD_REQ minimum value that ID}/vdcsp set below the UEST STORAGE:30 was arams minimum value. attempted to be assigned to Storage Resource, and 30 is the minimum value. /ext/admin Attempt to create an is exceed 101 is the /org/{org OvDC with Storage BAD_REQ maximum value that ID}/vdcsp set above the UEST STORAGE:100 was arams maximum value. attempted to be assigned to Storage Resource, and 100 is the maximum value. /ext/admin Attempt to create an 400 Cannot add VDC in unavailable /org/{org OvDC within a BAD_REQ unavailable state is the string ID}/vdcsp PvDC with UEST PVDC. that 50

51 Method URL Error Scenario Response Error Code Response Message Description arams unavailable status. indicates the detailed status info such as at-capacity. /ext/admin Attempt to edit an 400 Cannot edit VDC in unavailable /org/{org OvDC within a BAD_REQ unavailable state is the string ID}/vdcsp PvDC with UEST PVDC. that arams unavailable status. indicates the detailed status info such as at-capacity. PUT /ext/admin Attempt to assign a 500 gcv-steps: Compute UpdateOvdc /vdc/{org name already in use ERROR_T pool CO01 is the VDC ID} when editing an YPE_OPER UpdateOvdcCO01 OvCD name OvDC. ATION already exists was that attempted to be updated. PUT /ext/admin Attempt to set a 500 gcv-steps: Web /vdc/{org name longer than ERROR_T service method VDC ID} 127 characters YPE_OPER add_org_vdc(): when editing an ATION XMLRPC Fault: OvDC. Internal Server Error - org.hibernate.excep tion.dateexception: could not insert: [com.vmware.vclou 51

52 Method URL Error Scenario Response Error Code Response Message d.common.model.ev ent.auditevent] - could not insert: [com.vmware.vclou d.common.model.ev ent.auditevent] Description PUT /ext/admin Attempt to set must be integer 2.3 is the /vdc/{org number of CPU to a BAD_REQ value that VDC ID} decimal number UEST was when editing an attempted to OvDC. be assigned to CPU Resource. PUT /ext/admin Attempt to set is less then 1 is the /vdc/{org number of CPU BAD_REQ minimum CPU:2 value that VDC ID} below the minimum UEST was value when editing attempted to an OvDC. be assigned to CPU Resource, and 2 is the minimum value. PUT /ext/admin Attempt to set is exceed 5 is the /vdc/{org number of CPU BAD_REQ maximum CPU:4 value that VDC ID} above the maximum UEST was value when editing attempted to an OvDC. be assigned to CPU 52

53 Method URL Error Scenario Response Error Code Response Message Description Resource, and 4 is the maximum value. PUT /ext/admin Attempt to set must be integer 2.3 is the /vdc/{org Memory to a BAD_REQ value that VDC ID} decimal number UEST was when editing an attempted to OvDC. be assigned to Memory Resource. PUT /ext/admin Attempt to set is less then 1 is the /vdc/{org Memory below the BAD_REQ minimum value that VDC ID} minimum value UEST MEMORY:2 was when editing an attempted to OvDC. be assigned to Memory Resource, and 2 is the minimum value. PUT /ext/admin Attempt to set is exceed 5 is the /vdc/{org Memory above the BAD_REQ maximum value that VDC ID} maximum value UEST MEMORY:4 was when editing an attempted to OvDC. be assigned to Memory Resource, and 4 is the 53

54 Method URL Error Scenario Response Error Code Response Message Description maximum value. PUT /ext/admin Attempt to set must be integer 49.3 is the /vdc/{org Storage to a decimal BAD_REQ value that VDC ID} number when UEST was editing an OvDC. attempted to be assigned to Storage Resource. PUT /ext/admin Attempt to set is less then 20 is the /vdc/{org Storage below the BAD_REQ minimum value that VDC ID} minimum value UEST STORAGE:30 was when editing an attempted to OvDC. be assigned to Storage Resource, and 30 is the minimum value. PUT /ext/admin Attempt to set is exceed 101 is the /vdc/{org Storage above the BAD_REQ maximum value that VDC ID} maximum value UEST STORAGE:100 was when editing an attempted to OvDC. be assigned to Storage Resource, and 100 is the maximum 54

55 Method URL Error Scenario Response Error Code Response Message Description value. PUT /ext/admin Attempt to set 400 There are /vdc/{org resources above the BAD_REQ insufficient VDC ID} available value UEST resources to when editing an complete the OvDC. operation. Please contact the System Administrator DELET /ext/admin Attempt to delete an 400 Vapp(s) still exists in E /vdc/{org OvDC on which a BAD_REQ this VDC. VDC ID} vapp still exists. UEST 55

56 7 Reference 1 The conditions for available characters which could be used as variables for API are based on RFC882 Appendix 1 - Domain Name Syntax Specification listed below. Mockapetris [Page 29] RFC 882 November 1983 Domain Names - Concepts and Facilities Appendix 1 - Domain Name Syntax Specification The preferred syntax of domain names is given by the following BNF rules. Adherence to this syntax will result in fewer problems with many applications that use domain names (e.g., mail, TELNET). Note that some applications described in [14] use domain names containing binary information and hence do not follow this syntax. <domain> ::= <subdomain> " " <subdomain> ::= <label> <subdomain> "." <label> <label> ::= <letter> [ [ <ldh-str> ] <let-dig> ] <ldh-str> ::= <let-dig-hyp> <let-dig-hyp> <ldh-str> <let-dig-hyp> ::= <let-dig> "-" <let-dig> ::= <letter> <digit> <letter> ::= any one of the 52 alphabetic characters A through Z in upper case and a through z in lower case <digit> ::= any one of the ten digits 0 through 9 Note that while upper and lower case letters are allowed in domain names no significance is attached to the case. That is, two names with the same spelling but different case are to be treated as if identical. The labels must follow the rules for ARPANET host names. They must start with a letter, end with a letter or digit, and have as interior characters only letters, digits, and hyphen. There are also some restrictions on the length. Labels must be 63 characters or less. For example, the following strings identify hosts in the ARPA Internet: F.ISI.ARPA LINKABIT-DCN5.ARPA UCL-TAC.ARPA 56

57 8 Revision history Date Version Note 2015/05/15 Ver.1.0 Release version /06/05 Ver.1.01 Updated API user preparation procedure 2015/12/01 Ver.1.02 Added workflow for utilizing via API Gateway with Business Portal Account. 2016/04/01 Ver.1.03 Add to "4.1 Supported API List" 57