Aliyun Elastic Compute Service API Reference

(API Version 2013-01-10)

Aliyun ECS API Reference

Content 1

2

Introduction ....................................................................................................................... 6 1.1

Terms .................................................................................................................. 6

1.2

Explanations on Business Limitations and Resource Type Limitations .............. 7

How to Call ECS API ........................................................................................................... 8 2.1 2.1.1

Host Name .......................................................................................................... 8

2.1.2

Communication Protocol .................................................................................... 8

2.1.3

Request Method ................................................................................................. 8

2.1.4

Request Parameters ........................................................................................... 8

2.1.5

Character Encoding............................................................................................. 8

2.2

Common Parameters .......................................................................................... 9

2.2.1

Common Request Parameters............................................................................ 9

2.2.2

Common Response Elements ........................................................................... 10

2.3

Response Codes ................................................................................................ 11

2.3.1

Successful Response ......................................................................................... 11

2.3.2

Error Response ................................................................................................. 11

2.4 3

Structure of an API Request ............................................................................... 8

Signature Mechanism ....................................................................................... 12

Cross-account Resource Access via RAM ........................................................................ 15 3.1

How to Do Cross-account ECS Resource Access ............................................... 15

3.2

Authorizable ECS Resource Types in RAM ........................................................ 16

3.3

Authorizable Actions for ECS Resource in RAM................................................ 16

3.4

Authentication rules in ECS API Cross-account Resource Access ..................... 17

3.5

Example of Cross-account ECS Resource Access .............................................. 18

4 Interface Descriptions .......................................................................................................... 21 4.1

Instance Interfaces ........................................................................................... 21

4.1.1

CreateInstance .................................................................................................. 21

4.1.2

StartInstance..................................................................................................... 25

4.1.3

StopInstance ..................................................................................................... 26

1

Aliyun ECS API Reference

4.1.4

RebootInstance................................................................................................. 27

4.1.5

ModifyInstanceAttributes................................................................................. 29

4.1.6

QueryInstanceStatus (QueryInstanceList) ........................................................ 30

4.1.7

QueryInstanceInformation ............................................................................... 32

4.1.8

DeleteInstance .................................................................................................. 35

4.1.9

JoinSecurityGroup ............................................................................................ 36

4.1.10

LeaveSecurityGroup.......................................................................................... 37

4.2

Disk Interfaces .................................................................................................. 38

4.2.1

AddDisk ............................................................................................................. 38

4.2.2

DeleteDisk ......................................................................................................... 40

4.2.3

ResetDisk .......................................................................................................... 41

4.2.4

DescribeInstanceDisks ...................................................................................... 42

4.3

Snapshot Interfaces .......................................................................................... 44

4.3.1

CreateSnapshot ................................................................................................ 44

4.3.2

DeleteSnapshot ................................................................................................ 45

4.3.3

DescribeSnapshots ........................................................................................... 46

4.3.4

DescribeSnapshotAttribute .............................................................................. 48

4.4

Image Interfaces ............................................................................................... 49

4.4.1

DescribeImages................................................................................................. 49

4.4.2

CreateImage ..................................................................................................... 52

4.4.3

DeleteImage ..................................................................................................... 54

4.5 4.5.1 4.6

Network Interfaces ........................................................................................... 55 AllocatePublicIpAddress ................................................................................... 55 Security Group Interfaces ................................................................................. 56

4.6.1

CreateSecurityGroup ........................................................................................ 56

4.6.2

AuthorizeSecurityGroup ................................................................................... 58

4.6.3

DescribeSecurityGroupAttribute ...................................................................... 60

4.6.4

DescribeSecurityGroups ................................................................................... 63

4.6.5

RevokeSecurityGroup ....................................................................................... 66

4.6.6

DeleteSecurityGroup ........................................................................................ 68 2

Aliyun ECS API Reference

4.7 4.7.1 4.8 4.8.1 5

Region Interfaces .............................................................................................. 69 DescribeRegions ............................................................................................... 69 Other Interfaces................................................................................................ 71 DescribeInstanceTypes ..................................................................................... 71

Data Types ....................................................................................................................... 73 DiskItemType ....................................................................................................................... 73 Description ...................................................................................................................... 73 Node Name...................................................................................................................... 73 Child Nodes...................................................................................................................... 73 DiskSetType ......................................................................................................................... 73 Description ...................................................................................................................... 73 Node Name...................................................................................................................... 74 Child Nodes...................................................................................................................... 74 ImageType ........................................................................................................................... 74 Description ...................................................................................................................... 74 Node Name...................................................................................................................... 74 Child Nodes...................................................................................................................... 74 InstanceMonitorDataType .................................................................................................. 75 Description ...................................................................................................................... 75 Node Name...................................................................................................................... 75 Child Nodes...................................................................................................................... 75 InstanceStatusItemType ...................................................................................................... 76 Description ...................................................................................................................... 76 Node Name...................................................................................................................... 76 Child Nodes...................................................................................................................... 76 InstanceStatusSetType ........................................................................................................ 76 Description ...................................................................................................................... 76 Node Name...................................................................................................................... 76 Child Nodes...................................................................................................................... 76 InstanceTypeItemType ........................................................................................................ 77 3

Aliyun ECS API Reference

Description ...................................................................................................................... 77 Node Name...................................................................................................................... 77 Child Nodes...................................................................................................................... 77 IpAddressSetType ................................................................................................................ 77 Description ...................................................................................................................... 77 Node Name...................................................................................................................... 77 Child Nodes...................................................................................................................... 77 PermissionSetType .............................................................................................................. 78 Description ...................................................................................................................... 78 Node Type ....................................................................................................................... 78 Child Nodes...................................................................................................................... 78 PermissionType ................................................................................................................... 78 Description ...................................................................................................................... 78 Node Name...................................................................................................................... 78 Child Nodes...................................................................................................................... 78 RegionType .......................................................................................................................... 79 Description ...................................................................................................................... 79 Node Name...................................................................................................................... 79 Child Nodes...................................................................................................................... 79 SnapshotType ...................................................................................................................... 79 Description ...................................................................................................................... 79 Node Name...................................................................................................................... 79 Child Nodes...................................................................................................................... 79 SecurityGroupIdSetType...................................................................................................... 80 Description ...................................................................................................................... 80 Node Name...................................................................................................................... 80 Child Nodes...................................................................................................................... 80 SecurityGroupSetType ......................................................................................................... 80 Description ...................................................................................................................... 80 Node Name...................................................................................................................... 80 4

Aliyun ECS API Reference

Child Nodes...................................................................................................................... 80 SecurityGroupItemType ...................................................................................................... 81 Description ...................................................................................................................... 81 Node Name...................................................................................................................... 81 Child Nodes...................................................................................................................... 81 IPRangeSetType ................................................................................................................... 81 Description ...................................................................................................................... 81 Node Name...................................................................................................................... 81 Child Nodes...................................................................................................................... 81 6

Appendix .......................................................................................................................... 82 6.1

Instance Resource Type Comparison Table ...................................................... 82

6.2

Error Code Table ............................................................................................... 82

6.2.1

Client Side Error ................................................................................................ 82

6.2.2

Server Side Error ............................................................................................... 86

6.3

Instance Status Table ........................................................................................ 87

6.4

Instance State Machine .................................................................................... 87

6.5

Disk Categories ................................................................................................. 87

6.6

How to Call an Interface ................................................................................... 88

6.6.1

The Request Structure ...................................................................................... 88

6.6.2

Interface Call Example ...................................................................................... 89

6.7

How to follow the law of idempotence ............................................................ 92

Update History ........................................................................................................................ 94

5

Aliyun ECS API Reference

1 Introduction Welcome to use ECS (Aliyun Elastic Compute Service)! You can use the API introduced by this document to operate ECS. Please make sure that you have fully understood the ECS product descriptions, terms of use and charging methods before using the interfaces.

1.1

Terms

Term

Full Name

Description

Instance

ECS instance

A virtualized from server instance.

Region Image

Region represents a separate geographic location. A region has a number of data centers. An artifact providing information required to create an ECS instance.

Both the operating system and application software can be put into an image file. Users can choose one image file to initialize the cloud server instance. An image is required for an instance. In a newly created instance, the system disk is a complete copy of the image, including the operating system, application software configurations, etc. Therefore, we should choose different image files when creating instances that have different versions of operation systems.

Disk

The storage device used by the instance.

Snapshot

Snapshots are data restoration points that consist of the disk data at a specific time, and are used for restoring disk data or creating custom images.

IP

Internet protocol address.

SecurityGroup

Security Group

A security group acts as a virtual firewall for your instance to control inbound and outbound traffic. A security group must be related with an instance. It sets up the security policy for the instances in the group. Each instance can belong to a security control group, or multiple security groups. The instance inherits the security policy of the security group.

CIDR

Classless Inter-Domain Routing

CIDR is a method for allocating IP addresses and routing Internet Protocol packets. Compared with traditional class-ful network, CIDR is more efficient in address 6

Aliyun ECS API Reference assignment. Take the IP 125.203.96.0-125.203.127.255 for transferring it in CIDR format, we identical 19 bits: 125.203.0110 0000.0000 0000 125.203.0111 1111.1111 1111 Therefore, the address can 125.203.96.0/19.

1.2

address range example. When look for the first

be

written

as

Explanations on Business Limitations and Resource

Type Limitations

Aliyun imposes initial limits on several of its resources in order to discourage inappropriate consumption. Although each Aliyun account has several default resource limitations, you can make a request to increase these limits when necessary. Please refer to http://help.aliyun.com/view/11108189_13545434.html When you found conflicts between this document and the reference URL, the reference URL shall prevail.

7

Aliyun ECS API Reference

2 How to Call ECS API The ECS API interface calls are implemented by sending HTTP GET requests to the ECS API server. A request contains the parameters conforming to the specific interface description. Then the server returns the response of the request.

2.1

Structure of an API Request

2.1.1 Host Name ECS API host name is ecs.aliyuncs.com

2.1.2 Communication Protocol Both HTTP and HTTPS requests are supported in request communication. But we strongly recommend you to use the more secured way HTTPS.

2.1.3 Request Method Aliyun supports both GET and POST methods with the RPC-style API.

2.1.4 Request Parameters Aliyun devides request parameters into common parameters and action-specific parameters. Each request must have common parameters and a specified an action to be performed, i.e. the Action parameter (such as StartInstance). Additionally, each action must have some action-specific request parameters.

2.1.5 Character Encoding The contents of requests and the responses are encoded in UTF-8.

8

Aliyun ECS API Reference

2.2

Common Parameters

2.2.1 Common Request Parameters Common parameters are the request parameters that need to be included in each request. Name

Type

Required

Description

Format

String

No

The format of the response data. JSON and XML are supported, and XML is default.

Version

String

Yes

The version number of ECS API. It is represented in all-numeric date notation in most-to-least-significant order [YYYY]-[MM]-[DD]. The latest version is 2013-01-10.

AccessKeyId

String

Yes

The Access key ID issued by Aliyun for a user to access cloud computing services.

Signature

String

Yes

The signature is an alphanumeric string produced by a message-digest algorithm. Please refer to Signature Mechanism .

SignatureMethod

String

Yes

The signature algorithm used by signature calculation. Currently we only support HMAC-SHA1.

Timestamp

String

Yes

The time stamp of the request. The format conforms to ISO8601 standards and should be described in UTC. Its format looks like YYYY-MM-DDThh:mm:ssZ For example, 2013-01-10T12:00:00Z represents 12:00:00, January 1st, 2013, Beijing Time.

SignatureVersion

String

Yes

The version of the signature algorithm. The current version is 1.0.

SignatureNonce

String

Yes

SignatureNonce is a unique random number to prevent network replay attacks. Users must use different random numbers in different requests.

ResourceOwnerAccount

String

No

The owner of the account of the 9

Aliyun ECS API Reference requested resource. Please refer to Cross-account Resource Access via RAM. Please use this parameter only when you need to operate resources that don’t belong to you. And please make sure that the resource owner had authorized you to do this via RAM. Example https://ecs.aliyuncs.com/ ?Format=xml &Version=2013-01-10 &Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D &SignatureMethod=HMAC-SHA1 &SignatureNonce=15215528852396 &SignatureVersion=1.0 &AccessKeyId=key-test &Timestamp=2012-06-01T12:00:00Z

2.2.2 Common Response Elements In each request, Aliyun returns a unique identification code named “RequestId “to the user whether the request is successful or not. Examples XML Format 4C467B38-3910-447D-87BC-AC049166F216 JSON Format { "RequestId": "4C467B38-3910-447D-87BC-AC049166F216", /* Response Data */ }

10

Aliyun ECS API Reference

2.3

Response Codes

The responses of API calls are in a uniform format. HTTP response code 2XX stands for successful calls, while the response code 4XX or 5XX stands for failed calls. The data format of response data is either XML or JSON, which can be specified in the request parameters. The default format is XML. Examples in this document are formatted to facilitate user browsing, but the actual response results have no line breaks or indentation.

2.3.1 Successful Response XML Format 4C467B38-3910-447D-87BC-AC049166F216

JSON Format { "RequestId": "4C467B38-3910-447D-87BC-AC049166F216", /* Response Data */ }

2.3.2 Error Response If your request cannot be fulfilled, the response data will not be returned. Usually the response data contains some error code for illustration except the http status code . Please refer to Error Code Table. When an interface call fails, the server returns an HTTP status code of 4xx or 5xx. The response body contains the specific error code and error message. Besides, it also contains a global unique request id: RequestId, and the host id: HostId. If the interface caller cannot determine the cause of the error, please contact Aliyun customer service. It is recommended to provide the HostId and RequestId for prompt problem diagnostics. 11

Aliyun ECS API Reference XML Format 8906582E-6722-409A-A6C4-0E7863B733A5 ecs.aliyuncs.com UnsupportedOperation The specified action is not supported.

JSON Format { "RequestId": "8906582E-6722-409A-A6C4-0E7863B733A5", "HostId": "ecs.aliyuncs.com", "Code": "UnsupportedOperation", "Message": "The specified action is not supported." }

2.4

Signature Mechanism

Aliyun validates the identity of each request. Therefore, it is necessary to include the signature information in the request, no matter whether the request is submitted via HTTP or HTTPS. Aliyun uses Access Key ID and Access Key Secret in symmetrical encryption to verify the requester’s identity. Access Key ID and Access Key Secret are issued to a user by Aliyun. A user can apply and manage them from the official website of Aliyun. Access Key ID indicates the identity of a user, and Access Key Secret is a confidential secret key for signature encryption and server side signature verification, which is only known by Aliyun and its user. The signature processing procedure of user requests is as follows. 1. Generate Canonicalized Query String from request parameters a) Sort all request parameters by their names in alphabetic order. Those parameters include common request parameters and interface-specific parameters. Please do not include the “Signature” parameter itself. Notice: In HTTP GET request, parameters begin with a question mark (?) and connected by an ampersand (‘&’) in URI. Each parameter takes the form of name-value pair. b) Encode the name and value of each parameter. Each name-value pair must be converted into UTF-8 encoding and URL encoding. The URL encoding rules are as follows. i.

Do not encode the following characters: ‘A’-‘Z’, ‘a’-‘z’, ‘0’-‘9’, ‘-‘, ‘_’, ‘.’, ‘~’. 12

Aliyun ECS API Reference

ii. Other characters should be encoded in the format ‘%XY’. XY is the Hexadecimal representation of the character’s ASCII code. For example, the code for double quotation mark (“) is %22. iii. Extended UTF-8 characters should be encoded in the format ‘%XY%ZA…’. iv. The space character ( ) should be encoded as %20, not +. Notice: Generally speaking, libraries supporting URL encoding, such as java.net.URLEncoder in Java, follow the MIME type rule “application/x-www-form-urlencoded” encoding. To implement this, you can use these libraries first, and then replace + by 20%, * by %2A, %7E by ~. In this way you can get fully qualified encoded characters. c) Use = to connect the name and value of the parameter d) Use & to connect the strings in c) in the lexicographic order of the parameter name. 2. Use the Canonicalized Query String to generate the string to sign. StringToSign= HTTPMethod + “&” + percentEncode(“/”) + ”&” + percentEncode(CanonicalizedQueryString)

HTTPMethod stands for the HTTP method to submit your request, such as GET. percentEncode(“/”) encodes the character “/” as “%2F”, according to the URL encoding rules in 1.b. percentEncode(CanonicalizedQueryString) encodes the canonicalized query string generated in Step 1 according to the URL encoding rules in 1.b. 3. Use the above string to calculate the signature HMAC value according to RFC2104. Please notice that the key used to calculate the signature is your Access Key Secret plus an “&” character (ASCII: 38), and the hash algorithm is SHA1. 4. Use the base64 encoding rule to encode the HMAC value above into Signature. 5. Put the signature value into the request parameters. Notice: The signature itself should be URL encoded as other request parameters, according to RFC3986 . Take the interface DescribeRegions for example. The request URL before signature is: 13

Aliyun ECS API Reference http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&Access KeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&RegionId=r egion1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2013-01-10&SignatureVers ion=1.0 Therefore, StringToSign is: GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeRegions%26Format%3DX ML%26RegionId%3Dregion1%26SignatureMethod%3DHMAC-SHA1%26SignatureNo nce%3DNwDAxvLU6tFE0DVb%26SignatureVersion%3D1.0%26TimeStamp%3D201212-26T10%253A33%253A56Z%26Version%3D2013-01-10 If the Access Key Id is “testid” and Access Key Secret is “testsecret”, the key for HMAC calculation is “testsecret&”. The calculated signature value is: SDFQNvyH5rtkc9T5Fwo8DOjw5hc= The request URL after signature is as follows. Please note that the Signature parameter is added. http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10%3A33%3A56Z&Format=XML &AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&Re gionId=region1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2012-09-13&Signa tureVersion=1.0&Signature=SDFQNvyH5rtkc9T5Fwo8DOjw5hc%3d You can refer to the Appendix How to Make a Request about the detailed example on signature and request submitting.

14

Aliyun ECS API Reference

3 Cross-account Resource Access via RAM The ECS instances created by a user should be owned by the user himself. By default, the user has full operation permissions on his resources, and can use the API listed in this document to operate the resources. However, the user has no operation permissions on the resources owned by of other users. Any API operation on other users’ resources will be denied. With the help of Aliyun RAM (Resource Access Management), a user can realize cross-account ECS resource authorization and access. Before understanding how to use RAM to authorize and access ECS instances, please make sure that you have read RAM product document and API document in detail. If you do not need to use this function, you can skip this section, and ignore the explanations on ResourceOwnerAccount in the section of “Interface Description”. Skipping the part will not hamper the understanding and use of the other parts in the document.

3.1

How to Do Cross-account ECS Resource Access

If you need to use ECS API to access other user account’s resources, please make sure that the target account has authorized the resources and permissions to you. Please refer to RAM product document and API document for authorization operation. Compared to accessing one’s own resources, accessing resources of other users via ECS API must specify one addtional public parameter, ResourceOwnerAccount, to identify the owner of the resource. The example is as follows.

https://ecs.aliyuncs.com/?Action=StartInstance &InstanceId=Bc23xYm09 [email protected] &AccessKeyId=user_Y_keyid &

In the example, user_Y submits the API request to perform, StartInstance action on the ECS instance of user_X. The instance id is Bc23xYm09. If the request does not contain the parameter ResourceOwnerAccount, or the declared resource owner is different from the actual resource owner, or [email protected] has not granted the StartInstance action permission to user_Y, this API call will be declined because the caller has no access to the target resource.

15

Aliyun ECS API Reference

3.2

Authorizable ECS Resource Types in RAM

Currently, the authorizable ECS resources include 5 types. Instance; Disk; Snapshot; Image; SecurityGroup. In RAM authorization, the 5 kinds of resources are described as follows. Resource Type

Aliyun Resource Naming(ARN)

Instance

acs:ecs:$regionid:instance/$instanceid acs:ecs:$regionid:instance/* acs:ecs:*:instance/*

Disk

acs:ecs:$regionid:disk/$diskid acs:ecs:$regionid:disk/* acs:ecs:*:disk/*

Snapshot

acs:ecs:$regionid:snapshot/$snapshotid acs:ecs:$regionid:snapshot/* acs:ecs:*:snapshot/*

Image

acs:ecs:$regionid:image/$imageid acs:ecs:$regionid:image/* acs:ecs:*:image/*

SecurityGroup

acs:ecs:$regionid:securitygroup/$securitygroupid acs:ecs:$regionid:securitygroup/* acs:ecs:*:securitygroup/*

Special Expression on General Reference

acs:ecs:$regionid:* acs:ecs:*:*

In this table, $regionid represents the id of certain region, or “*”. $instanceid represents the id of certain instance, or “*”. And so on.

3.3

Authorizable Actions for ECS Resources in RAM

In RAM, a user can authorize the following Actions on ECS resources. AddDisk

DescribeInstanceStatus

AllocatePublicIpAddress

DescribeInstanceTypes

AuthorizeSecurityGroup

DescribeRegions

CreateImage

DescribeSecurityGroupAttribute

CreateInstance

DescribeSecurityGroups

CreateSecurityGroup

DescribeSnapshotAttribute 16

Aliyun ECS API Reference CreateSnapshot

DescribeSnapshots

DeleteDisk

JoinSecurityGroup

DeleteImage

LeaveSecurityGroup

DeleteInstance

ModifyInstanceAttribute

DeleteSecurityGroup

RebootInstance

DeleteSnapshot

ResetDisk

DescribeImages

RevokeSecurityGroup

DescribeInstanceAttribute

StartInstance

DescribeInstanceDisks

StopInstance

3.4

Authentication

rules

in

ECS API

Cross-account

Resource Access When a user uses ECS Open API to access cross-account ECS resources, the ECS server checks the permission of RAM to make sure that the resource owner has authorized the resource permissions to the resource requester. Each ECS API decides which resources to check according to the resource type and API semantics. Specifically, the authentication rules are as follows. Action

Authentication Rules

AddDisk

acs:ecs:$regionid:instance/$instanceid

AllocatePublicIpAddress

acs:ecs: $regionid:instance/$instanceid

AuthorizeSecurityGroup

acs:ecs:$regionid:securitygroup/$securitygroupid [and acs:ecs:$regionid:securitygroup/$sourcegroupid ( If SourceGroupId is specified) ]

CreateImage

acs:ecs:$regionid:image/* and acs:ecs:$regionid:snapshot/$snapshotid

CreateInstance

acs:ecs:$regionid:instance/* and acs:ecs:$regionid:securitygroup/$securitygroupid and acs:ecs:$regionid:image/$imageid [and acs:ecs:$regionid:snapshot/$snapshotid (If DataDisk.n.SnapshotId if specified)]

CreateSecurityGroup

acs:ecs:$regionid:securitygroup/*

CreateSnapshot

acs:ecs:$regionid:instance/$instanceid or acs:ecs:$regionid:disk/$diskid

DeleteDisk

acs:ecs:$regionid:instance/$instanceid 17

Aliyun ECS API Reference DeleteImage

acs:ecs:$regionid:image/$imageid

DeleteInstance

acs:ecs:$regionid:instance/$instanceid

DeleteSecurityGroup

acs:ecs:$regionid:securitygroup/$securitygroupid

DeleteSnapshot

acs:ecs:$regionid:snapshot/$snapshotid or acs:ecs:$regionid:disk/$diskid or acs:ecs:$regionid:instance/$instanceid

DescribeImages

acs:ecs:$regionid:image/$imageid

DescribeInstanceAttribute

acs:ecs:$regionid:instance/$instanceid

DescribeInstanceDisks

acs:ecs:$regionid:instance/$instanceid

DescribeInstanceStatus

acs:ecs:$regionid:instance/$instanceid

DescribeInstanceTypes

acs:ecs:*:*

DescribeRegions

acs:ecs:*:*

DescribeSecurityGroupAttribute

acs:ecs:$regionid:securitygroup/$securitygroupid

DescribeSecurityGroups

acs:ecs:$regionid:securitygroup/$securitygroupid

DescribeSnapshotAttribute

acs:ecs:$regionid:snapshot/$snapshotid

DescribeSnapshots

acs:ecs:$regionid:disk/$diskid or acs:ecs:$regionid:instance/$instanceid

JoinSecurityGroup

acs:ecs:$regionid:instance/$instanceid and acs:ecs:$regionid:securitygroup/$securitygroupid

LeaveSecurityGroup

acs:ecs:$regionid:instance/$instanceid and acs:ecs:$regionid:securitygroup/$securitygroupid

ModifyInstanceAttribute

acs:ecs:$regionid:instance/$instanceid

RebootInstance

acs:ecs:$regionid:instance/$instanceid

ResetDisk

acs:ecs:$regionid:instance/$instanceid or acs:ecs:$regionid:disk/$diskid

RevokeSecurityGroup

acs:ecs:$regionid:securitygroup/$securitygroupid [and acs:ecs:$regionid:securitygroup/$securitygroupid( If sourcegroupid is specified) ]

StartInstance

acs:ecs:$regionid:instance/$instanceid

StopInstance

acs:ecs:$regionid:instance/$instanceid

3.5

Examples of Cross-account ECS Resource Access

We assume that [email protected] has created an ECS instance, the InstanceId of which is Bc23xYm09. Now [email protected] wants to authorize [email protected] to manage this instance via ECS API, but only allows three actions, RebootInstance, StopInstance and DescribeInstanceAttribute. To achieve the above authorization, xiaoming needs to finish the following steps. 1. Xiaoming should add Beibei to the RAM user space. He must call the AddUser interface of RAM 18

Aliyun ECS API Reference with xiaoming’s account. The parameter UserName= [email protected] https://ram.aliyuncs.com/?Action=AddUser [email protected] &

2. Prepare authorization Policy. Policy is a JsonString, and it should contain the following elements. { "Version": "1", "Statement": [ { "Effect": "Allow", "Action": ["ecs:RebootInstance","ecs:StopInstance","ecs:DescribeInstanceAttribute"], "Resource": ["acs:ecs:*:instance/Bc23xYm09"] }] }

3. Xiaoming calls the interface PutPolicy of RAM, and configures Policy for Beibei. The value of the parameter PolicyName is web_front_server_policy, which is the name of the policy created by xiaoming. https://ram.aliyuncs.com/?Action=PutUserPolicy [email protected] &PolicyName=web_front_server_policy &PolicyDocument=$ The Policy prepared in Step 2 & After configuring Policy, Beibei has the permission to take some actions on this ECS instance, such as RebootInstance. In API call, Beibei must assign the parameter ResourceOwnerAccount to specify that this API call is operating on xiaoming’s resource. https://ecs.aliyuncs.com/?Action=RebootInstance &InstanceId=Bc23xYm09 [email protected] &< Other Common request Parameters >

5. If xiaoming wants to revoke Beibei’s permissions, he needs to call DeleteUserPolicy in RAM to delete the policy.

19

Aliyun ECS API Reference https://ram.aliyuncs.com/?Action=DeleteUserPolicy [email protected] &PolicyName=web_front_server_policy &< Other Common request Parameters >

6. Now that the policy is deleted, Beibei will be denied access to this ECS instance via ECS API. The response is as follows. { "RequestId": "7463B73D-35CC-4D19-A010-6B8D65D242EF", "HostId": "ecs.aliyuncs.com", "Code": “Forbidden", "Message": “User not authorized to operate on the specified resource." }

20

Aliyun ECS API Reference

4 Interface Descriptions 4.1

Instance Interfaces

4.1.1 CreateInstance Description Create instance according to the calling parameters. ·When creating an instance, it is required to choose an image to set up the system disk of this instance. The image contains the operating system and application software configurations. After the instance is created via the image, the system disk of the instance becomes a fully copy of the image. ·Each Instance should be assigned to a security group. The security group must be created in advance according to Create Security Group. The security group can be assigned when creating the instance, or be modified according to Modify Instance Attributes. The instances in the same security group can access each other in the intranet. Different security groups have firewalls to block access by default, but the firewall permissions can be set by security group authorization (by authorizing security group permissions). The instance number of a security group should not exceed 1000. If a user assigns an instance to a security group that will exceed instance number limit, the assignment will fail. ·When creating an instance, if the value of the parameter InternetChargeType is PayByBandwidth (pay the bill by constant bandwidth), the value of the parameter InternetMaxBandwidthOut will be the constant bandwidth. If the value of the parameter InternetChargeType is PayByTraffic (pay the bill by network traffic), the InternetMaxBandwidthOut only sets a bandwidth upper bound, but the billing will be based on network traffic. Please closely calculate the possible bandwidth expense before setting InternetChargeType and InternetMaxBandwidthOut. ·The value of InternetMaxBandwidthIn will not affect billing in any case. The incoming traffic of instances is free. ·When creating the instance, the system will assign a system disk according to the size of the image. The system can specify the kind of the system disk, such as the cloud disk and the ephemeral disk (Only if a user has the permission to create an ephemeral disk, by default new users do not have this permission).

21

Aliyun ECS API Reference ·After the instance is created, the cloud disks can be added via Adddisk action . But ephemeral disks must be specified during instance creation, and cannot be added after the instance is created. Please refer to Instance resource size comparison table to learn about the disk type and size limitation on different instances. ·At present, all disks (including the system disk and data disks) owned by one instance must be the same type. In other words, if the system disk is cloud disk or ephemeral disk, the data disks must be cloud disks or ephemeral disks accordingly. ·One instance can have 4 data disks at most. Total storage space owned by an instance should not exceed 8T (8192G). ·Each cloud disk capacity should not exceed 2T (2048G). Each ephemeral disk capacity should not exceed 1T (1024G). ·When buying an ephemeral disk as the system disk, you should buy at least one data disk along. ·If you choose the ephemeral disk when creating the instance, the instance size cannot be modified after creation. ·If the instance memory is 512M, the instance can’t choose Windows as the operating system. If the instance memory is equal to or larger than 4G, the instance can’t use 32 bit operating systems. Request Parameters Name

Type

Required

Description

Action

String

Yes

The name of the action interface. It is required by the system. Its value should be CreateInstance

RegionId

String

Yes

Region ID represents the region which the instance belongs to.

ImageId

String

Yes

Image file ID, represents the selected image resource in instance launch.

InstanceType

String

Yes

The resource rules of the instance. Please refer to instance resource size comparison table, or call query instance resource size list interface to get the

SecurityGroupId

String

Yes

InstanceName

String

Yes

latest size table。 Appoint the security group ID to the instance. The instances in the same security can access each other. Mark name of the instance.

22

Aliyun ECS API Reference InternetChargeT ype

String

No

The charge type of internet usage. This value specifies whether the bill is paid by bandwidth or traffic. The optional values are: ·PayByBandwidth ·PayByTraffic The default value is PayByBandwidth.

InternetMaxBan dwidthIn

Integer

No

The maximum incoming Internet bandwidth. The unit is Mbps(Mega bit per second), and the value range is [1,200]. If the user does not specify InternetMaxBandwidthIn, Aliyun API will set it as 200Mbps。

InternetMaxBan dwidthOut

Integer

No

The maximum outcoming Internet bandwidth. The unit is Mbps (Mega bit per second), and the value range is as follows. PayByBandwidth：[1,5] PayByTraffic：[1,100] If the user does not specify，API will set InternetMaxBandwidthOut as 0Mbps. If needed, InternetMaxBandwidthOut can be set as 1~200Mbps via Aliyun Work Order system.

HostName

String

No

HostName represents the name of the host, and should contain at least 2 characters. “.”and “-” cannot be set as the first or last character, and cannot appear in a sequence. In Windows platform, the maximum length of HostName is 15 characters, allowing alphabetic characters (uppercase and lowercase), numberic characters and “-”. “.” is not allowed. Besides, the name must not be pure numbers. In other platforms such as Linux, the maximum length of HostName is 30 characters, allowing multiple “.”, the characters between “.” make up one section, and each section allows alphabetic characters (uppercase and lowercase), numberic characters and “-”.

Password

String

No

The password of the instance. If a user choose to use API to pass the Password parameter, the password must be numbers or English characters, and the length is between 6~30 characters. When passing Password parameters, please use HTTPS protocol in API calling to prevent possible 23

Aliyun ECS API Reference password disclosure. SystemDisk.Cate gory

String

No

The category of the system disk. It can be cloud disk or ephemeral disk. Optional values： ·cloud ·ephemeral The default value is cloud.

DataDisk.n.Size

Integer

No

The capacity of data disk n (The disk are numbered starting from 1). The unit is GB, and the value range is 5~1024.

DataDisk.n.Cate gory

String

No

The category of disk n. Optional value: ·ephemeral Default value: ephemeral This parameter is specified as ephemeral only if the value of parameter SystemDisk.Category is ephemeral. If you need to add the data disk of the cloud disk, please call the interface add disk device to an instance.

DataDisk.n.Snap shotId

String

No

This parameter specifies the snapshot used in data disk creation. If this parameter is specified, the parameter DataDisk.n.Size will be ignored. The actual disk size is the same as the snapshot size. If the snapshot is created in or before July, 15th, 2013, this API call will be declined, and Response returns nvalidSnapshot.TooOld

ClientToken

String

No

To ensure the idempotence of the requests, the client generates the value of this parameter, which must be unique among different requests. The maximum length is 64 ASCII characters. Please refer to the appendix on How to follow the law of Idempotence.

Response Elements Name

Type

Description

InstanceId

String

The ID of the instance. It is generated by the system, and is global unique. InstanceId is the unique identification of an instance.

Examples Example Request

24

Aliyun ECS API Reference https://ecs.aliyuncs.com/?Action=CreateInstance &RegionId=cn-hangzhou-dg-a01 &ImageId=_32_23c472_20120822172155_aliguest.vhd &SecurityGroupId=C0003E8B-B930-4F59-ADC0-0E209A9012B0 &HostName=Bctest01 &InstanceType=ecs.t1.small &

Example Response XML Format 04F0F334-1335-436C-A1D7-6C044FE73368 Bc23xYm09 Json Format { "RequestId": "04F0F334-1335-436C-A1D7-6C044FE73368", "InstanceId": "Bc23xYm09", }

4.1.2 StartInstance Description Start a specific instance. ·The status of the instance will become Starting if the API call succeeds. ·This Interface can only be called when the status of the instance is Stopped. ·When the security control marks the instance as “locked” status, the instance cannot be started. Request parameters Name

Type

Required

Description

Action

String

Yes

The parameter is required by the system. Its value should be StartInstance.

InstanceId

String

Yes

Specify the ID of the instance to start.

25

Aliyun ECS API Reference

Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements. Examples Example Request https://ecs.aliyuncs.com/?Action=StartInstance &InstanceId=Bc23xYm09 &

Example Response XML Format C0003E8B-B930-4F59-ADC0-0E209A9012A8 JSON Format { “RequestId”: “C0003E8B-B930-4F59-ADC0-0E209A9012A8” }

4.1.3 StopInstance Description Stop a specific instance. ·This Interface can only be called when the status of the instance is Running. · The instance status will become Stopping if the API call succeeds. The system will change the instance status to Stopped when the instance is actually stopped. ·Force stop is allowed. This action can be regarded as power cut-off, and may cause data loss in the instance if the data has not been written into the disk. ·When the security control marks the instance as “locked” status, the instance cannot be stopped. Request Parameters

26

Aliyun ECS API Reference Name

Type

Required

Description

Action

String

Yes

The parameter is required by the system. Its value should be StopInstance.

InstanceId

String

Yes

Specify the ID of the instance to stop.

ForceStop

String

No

The parameter specifies the force stop strategy when restarting the instance. The optional values are: ·true ·false The default value is false. It the value is false, the instance is shut down normally. If the value is true, the instance is stopped by force.

Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements. Examples Example Request https://ecs.aliyuncs.com/?Action=StopInstance &InstanceId=Bc23xYm09 &

Example Response XML Format 1C488B66-B819-4D14-8711-C4EAAA13AC01 JSON Format { “RequestId”: “1C488B66-B819-4D14-8711-C4EAAA13AC01” }

4.1.4 RebootInstance Description Reboot a specific instance.

27

Aliyun ECS API Reference

·This Interface can only be called when the status of the instance is Running. ·The status of the instance will become Starting if the API call succeeds. ·Force reboot is allowed. This action can be regarded as power cut-off in traditional server, and may cause data loss in the instance if the data has not been written into the disk. ·When the security control marks the instance as “locked” status, the instance cannot be rebooted. Request parameters Name

Type

Required

Description

Action

String

Yes

The parameter is required by the system. Its value should be RebootInstance.

InstanceId

String

Yes

Specify the ID of the instance to reboot.

ForceStop

String

No

The parameter specifies the force stop strategy when restarting the instance. The optional values are: ·true ·false The default value is false. It the value is false, the instance is shut down normally. If the value is true, the instance is stopped by force.

Examples Example Request https://ecs.aliyuncs.com/?Action=RebootInstance &InstanceId=Bc23xYm09 &

Example Response XML Format F2E2C40D-AB09-45A1-B5C5-EB9F5C4E4E4A JSON Format

28

Aliyun ECS API Reference { “RequestId”: “F2E2C40D-AB09-45A1-B5C5-EB9F5C4E4E4A” }

4.1.5 ModifyInstanceAttributes Description Modify the instance attributes, including instance password, instance name, security group, etc. ·This operation only modifies explicit attributes. Unspecified attributes will not be modified. ·Instance password reset cannot be done if the instance status is Deleted or Starting. Password reset only becomes valid after rebooting the instance. ·When the security control marks the instance as “locked” status, the instance password cannot be reset. Request Parameters Name

Type

Required

Description

Action

String

Yes

The parameter is required by the system. Its value should be ModifyInstanceAttribute.

InstanceId

String

Yes

Specify the ID of the instance to modify.

InstanceName

String

No

The name of the instance.

Password

String

No

Password is reset by the user. The password can only consist of numeric or English characters. The length of the password is 6 to 30 English characters.

HostName

String

No

HostName represents the name of the host, and should contain at least 2 characters. “.”and “-” cannot be set as the first or last character, and cannot appear in a sequence. In Windows platform, the maximum length of HostName is 15 characters, allowing alphabetic characters (uppercase and lowercase), numberic characters and “-”. “.” is not allowed. Besides, the name must not be pure numbers. In other platforms such as Linux, the maximum length of HostName is 30 characters, allowing multiple “.”, the characters between “.” make up one section, and each section allows alphabetic characters (uppercase and lowercase), numberic characters and “-”.

29

Aliyun ECS API Reference SecurityGroupId

String

No

The security group ID of the instance. This interface adds the instance to a specified security group, and removes the instance from current security group.

Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements. Examples Example Request https://ecs.aliyuncs.com/?Action=ModifyInstanceAttribute &InstanceId=35F20777-0DFF-C152-41FA-BCE0EA0B2FD7 &Password=pwd &

Example Response XML Format 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E JSON Format { “RequestId”: “473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E” }

4.1.6 QueryInstanceStatus (QueryInstanceList) Description Get the instance status information of the current user in batches, or get the instance list. Please refer to Instance Status Table. Special Limitations on Cross-account Resource Operations via RAM Only the status of latest 100 instances can be queried. If the number of instances (calculated by PageNumber and PageSize) exceeds the limit, the request will be declined. The error code is Forbidden.AccessTooManyOthersResource. In the response, TotalCount represents the number of instances that authorize the caller to take the action. If the instance outnumbers 100, the value of TotalCount is 100. 30

Aliyun ECS API Reference

Request Parameters Name

Type

Required

Description

Action

String

Yes

The name of the action in the interface. This parameter is required by the system. Its value should be DescribeInstanceStatus.

RegionId

String

Yes

Region ID represents the region which the instance belongs to.

PageNumber

Integer

No

The page number of the instance status list. The start number is 1, and the default number is 1.

PageSize

Integer

No

The rows to be displayed per page in paging query. The maximum number is 50 and the default value is 10.

Response Elements Name

Value

Description

TotalCount

Integer

The total number of the instances.

PageNumber

Integer

The page number in the instance list.

PageSize

Integer

The rows per page that is set in the request.

InstanceStatuses

InstanceStatusSetType

InstanceStatuses is an array consisting of data in the format InstanceStatusSetType. It returns the status information of the instances. Please refer to InstanceStatusSetType.

Examples Example Request https://ecs.aliyuncs.com/?Action=DescribeInstanceStatus &RegionId=cn-hangzhou-dg-a01 &

Example Response XML Format

31

Aliyun ECS API Reference 6EF60BEC-0242-43AF-BB20-270359FB54A7 2 1 10 Bc23xYm09 Running Bc23xOmc0 Stopped JSON Format { “RequestId”: “6EF60BEC-0242-43AF-BB20-270359FB54A7”, “TotalCount”: 2, “PageNumber”: 1, “PageSize”: 10, “InstanceStatuses”: { “InstanceStatus”: [{ “InstanceId”: “Bc23xYm09”, “Status”: “Running” }, { “InstanceId”: “Bc23xOmc0”, “Status”: “Stopped” }] } }

4.1.7 QueryInstanceInformation Description Query detailed information of a specified instance. Request Parameters 32

Aliyun ECS API Reference Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DescribeInstanceAttribute.

InstanceId

String

Yes

The instance ID.

Response Elements Name

Type

Description

InstanceId

String

The instance ID

InstanceName

String

The instance name to display.

ImageId

String

The image ID

RegionId

String

The ID of the region which the instance belongs to.

InstanceType

String

The specifications resources.

HostName

String

The host name of the instance.

Status

String

The status of the instance.

SecurityGroupIds

SecurityGroupIdSetType

The security group set SecurityGroupIdSetType which the instance belongs to. At present, an instance can only belong to one security group.

PublicIpAddress

IpAddressSetType

The public network IP address of the instance. Please refer to IpAddressSetType.

InternetMaxBandwidthIn

Integer

The maximum bandwidth.

incoming

Internet

InternetMaxBandwidthOut

Integer

The maximum bandwidth.

outcoming

Internet

InternetChargeType

String

The charge type of internet usage. The optional values are PayByBandwidth and PayByTraffic. Pre-paid instances use PayByBandwidth. ·PayByBandwidth: paid by bandwidth ·PayByTraffic: paid by traffic.

CreationTime

String

The time that the instance is created。 The data format conforms to ISO8601 standards and should be described in UTC. The format looks like YYYY-MM-DDThh:mmZ

Examples Example Request

33

of

the

instance

Aliyun ECS API Reference https://ecs.aliyuncs.com/?Action=DescribeInstanceAttribute &InstanceId=Bc23xYm09 &

Example Response XML Format C330F17D-8395-4F7B-B78A-51BB3AE233D5 Bc23xYm09 rhel54.64.20110224.01.vhd cn-hangzhou-dg-a01 ecs.t1.xsmall VM-Test Starting 10.10.10.10 10.241.119.181 5 5 PayByBandwidth 0E209A9012B0 JSON Format

34

Aliyun ECS API Reference { "RequestId": " C330F17D-8395-4F7B-B78A-51BB3AE233D5", "InstanceId": "Bc23xYm09", "ImageId": "rhel54.64.20110224.01.vhd", "RegionId": "cn-hangzhou-dg-a01", "InstanceType": "ecs.t1.xsmall", "HostName": "VM-Test", "PublicIpAddress": { "IpAddress": ["10.10.10.10"] }, "InnerIpAddress": { "IpAddress": ["10.241.119.181"] }, "InternetMaxBandwidthOut": 5, "InternetMaxBandwidthIn": 5, "InternetChargeType":"PayByBandwidth", "Status": "Starting", "SecurityGroupIds": { "SecurityGroupId": ["C0003E8B-B930-4F59-ADC0-0E209A9012B0"] } }

4.1.8 DeleteInstance Description Release the instance resources according to instance name specified in the request. After an instance is released, all physical resources will be reclaimed, including disks, snapshots. Relevant data will be lost and cannot be recovered permanently. ·The instance can only be deleted when its status is Stopped. After deleting, the instance status is Deleted, representing that the resources are released and the deletion is finished. ·After an instance is deleted, the disks and snapshots mounted on the instance are also deleted. ·After an instance is deleted, relevant data are lost and cannot be recovered permanently. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DeleteInstance.

35

Aliyun ECS API Reference InstanceId

String

Yes

The instance ID.

Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements. Examples Example Request https://ecs.aliyuncs.com/?Action=DeleteInstance &InstanceId=Bc23xYm09 &

Example Response XML Format 928E2273-5715-46B9-A730-238DC996A533 JSON Format { "RequestId": "928E2273-5715-46B9-A730-238DC996A533" }

4.1.9 JoinSecurityGroup Description Add an instance to specified security group. ·This action can only be taken when the instance status is Stopped or Running. ·Each instance can belong to 5 security group at most. ·Each security group can have 1000 instance at most. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be JoinSecurityGroup.

InstanceId

String

Yes

The ID of the instance to be added to the security

36

Aliyun ECS API Reference group. SecurityGroupId

String

Yes

The ID of the security group.

Examples Example Request https://ecs.aliyuncs.com/?Action=JoinSecurityGroup &InstanceId=35F20777-0DFF-C152-41FA-BCE0EA0B2FD7 &SecurityGroupId=F876FF7BA984 &

Example Response XML Format 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E JSON Format { "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E" }

4.1.10 LeaveSecurityGroup Description Remove an instance from the specified security group. ·This action can only be taken when the instance status is Stopped or Running. ·Each instance must belong to at least one security group. If you try to remove an instance which belongs to only one security group, the request will fail. Request parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be LeaveSecurityGroup.

InstanceId

String

Yes

The ID of the instance to specify.

SecurityGroupId

String

Yes

The ID of the security group.

37

Aliyun ECS API Reference Examples Example Request https://ecs.aliyuncs.com/?Action=LeaveSecurityGroup &InstanceId=35F20777-0DFF-C152-41FA-BCE0EA0B2FD7 &SecurityGroupId=F876FF7BA984 &

Example Response XML Format 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E JSON Format { "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E" }

4.2

Disk Interfaces

4.2.1 AddDisk Description Add one disk device to an instance. You can either create a brand new disk, or create a disk from a snapshot. ·The instance status must be Running or Stopped. ·If the disk is created from a snapshot, its size should accord with the corresponding size of the snapshot. ·If the instance status is Running, there is no need to reboot the instance after disk mounting. The action takes effect immediately. ·Each instance can mount 4 data disk devices at most. The total capacity must be within 2T. If more capacity is needed, you can use the Aliyun work order system to expand the capacity. The maximum capacity is 8T. ·This interface only creates cloud disks for the instance. Ephemeral disks can only be 38

Aliyun ECS API Reference specified in instance creation. ·At present, this interface can only be called if the system disk is cloud disk. ·When the security control marks the instance as “locked” status, the disk cannot be added to the instance. ·The snapshot that is created on or before July, 15th, 2013 cannot be used in disk creation. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be AddDisk.

InstanceId

String

Yes

The ID of the instance.

Size

String

Yes

The size of the disk to create. The unit is GB, and the value range is 5~2048.

SnapshotId

String

No

If this parameter is not specified, an empty data disk will be added. If this parameter is specified, The disk size accords with the snapshot size. The snapshot can only be the snapshot of a data disk. If the snapshot is created on or before July, 15th, this interface call will be declined, and the response will return InvalidSnapshot.TooOld.

ClientToken

String

No

To ensure the idempotence of the requests, the client generates the value of this parameter, which must be unique among different requests. The maximum length is 64 ASCII characters. Please refer to the appendix on How to follow the law of Idempotence.

Response Elements Name

Type

Description

DiskId

String

The ID of the disk

Examples Example Request https://ecs.aliyuncs.com/?Action=AddDisk &InstanceId=Bc0102-23xYm09 &Size=20 &

Example Response 39

Aliyun ECS API Reference XML Format C8B26B44-0189-443E-9816-D951F59623A9 1033-60053321 JSON Format { "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9", "DiskId": "1033-60053321" }

4.2.2 DeleteDisk Description If a disk device is no longer used, it can be deleted from the instance. All of the disk devices mounted by the instance can be acquired by the interface query disk list of an instance. ·When deleting the disk, the instance status must be Running or Stopped. ·If the instance status is running, the deleted disk is no longer in the billing process only after instance rebooting. ·If the specified disk ID do not exists, the request will be ignored. ·If a disk is deleted, all snapshots created from the disk will be deleted automatically. ·Only cloud disks can be deleted. ·When the security control marks the instance as “locked” status, the disk cannot be deleted. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DeleteDisk.

InstanceId

String

Yes

The ID of the instance where the disk belongs to.

DiskId

String

Yes

The ID of the disk to remove.

Response Elements

40

Aliyun ECS API Reference All Response Elements are Common response Elements. Please refer to Common response Elements. Examples Example Request https://ecs.aliyuncs.com/?Action=DeleteDisk &DiskId=1033-60053321 &

Example Response XML Format CEF72CEB-54B6-4AE8-B225-F876FF7BA984 JSON Format { "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BA984" }

4.2.3 ResetDisk Description Reset the disk from a specified snapshot. ·The action can only be taken when the instance status is Stopped. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be ResetDisk.

InstanceId

String

Yes

The ID of the instance.

DiskId

String

Yes

The ID of the disk to reset.

SnapshotId

String

Yes

The ID of the snapthot used in disk reset.

Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements.

41

Aliyun ECS API Reference Examples Example Request https://ecs.aliyuncs.com/?Action=ResetDisk &InstanceId=Bc0102-23xYm09 &DiskId=1033-60053321 &SnapshotId=923FE2BF04C5 &

Example Response XML Format F3CD6886-D8D0-4FEE-B93E-1B73239673DE JSON Format { "RequestId":"F3CD6886-D8D0-4FEE-B93E-1B73239673DE” }

4.2.4 DescribeInstanceDisks Description List the disk devices’ ID and type in the instance. ·When taking this action, the instance status cannot be Starting or Deleted. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DescribeInstanceDisks.

InstanceId

String

Yes

The ID of the instance to describe.

Response Elements Name

Type

Description

Disks

DiskItemType

a disk information set consisting of DiskItemType

Examples Example Request

42

Aliyun ECS API Reference https://ecs.aliyuncs.com/?Action=DescribeInstanceDisks &InstanceId=Bc23xYm09 &

Example Response XML Format E4FFD20F-EC72-466A-9815-1CED3C88A863 1033-60053321 20 system ephemeral 1033-10056026 100 data ephemeral JSON Format { "RequestId": "E4FFD20F-EC72-466A-9815-1CED3C88A863", "Disks": { Disk: [{ "DiskId": "1033-60053321", "Size": 20, "Type": "system" }, { "DiskId": " 1033-10056026", "Size": 100, "Type": "data" }] } }

43

Aliyun ECS API Reference

4.3

Snapshot Interfaces

4.3.1 CreateSnapshot Description Create a snapshot for a disk device. ·The cloud server can create a snapshot when the instance status is Stopped or Running, but cannot create a snapshot if the instance is created but has not started once. ·For a newly created system disk from the cloud server, or a newly added data disk from a snapshot, the snapshot creation will fail because data load is still not finished. Generally, a snapshot can be created one hour after system disk is created. The snapshot creating time for the data disk is relevant to the size of the disk data. ·After a new disk is added, if the instance has not started once, the newly added disk cannot be used for snapshot creation. ·If the snapshot creation has not been finished (in other words, the process has not reached 100%), the snapshot cannot be used for custom image creation. ·If the snapshot creation has not been finished (in other words, the process has not reached 100%), you cannot create another snapshot from the same disk. ·The quota of the snapshots is up to the total disk number owned by the account. If the disk number is less than 3, the maximum snapshot number is 5; if the disk number is equal to or more than 3, the maximum snapshot number is the disk number times 2. Request Paramters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be CreateSnapshot.

InstanceId

String

Yes

The ID of the instance.

DiskId

String

Yes

The ID of the disk.

SnapshotName

String

No

The snapshot name to display. It consists of alphabets, numbers and “-”. The length range is [0, 300]

ClientToken

String

No

To ensure the idempotence of the requests, the client generates the value of this parameter, which must be unique among different requests. The maximum length is 64 ASCII characters.

44

Aliyun ECS API Reference Please refer to the appendix on How to follow the law of Idempotence. Response Elements Name

Type

Description

SnapshotId

String

The ID of the snapshot

Examples Example Request https://ecs.aliyuncs.com/?Action=CreateSnapshot &InstanceId=Bc23xYm09 &DiskId=1033-60053321 &

Example Response XML Format C8B26B44-0189-443E-9816-D951F59623A9 923FE2BF04C5 JSON Format { "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9", "SnapshotId": "923FE2BF04C5" }

4.3.2 DeleteSnapshot Description Delete the snapshot of the specified instance and specified disk device. If you want to cancel a snapshot being created (the creation process has not reached 100%), you can call this interface to delete the snapshot as well (i.e. cancel snapshot creation). ·A snapshot can only be deleted if the instance status is Stopped or Running. ·If the specified snapshot ID does not exist, the request will be ignored. ·If the snapshot has been used to create a custom image, this snapshot cannot be deleted

45

Aliyun ECS API Reference directly. It is needed to delete the relevant custom image first before deleting the snapshot. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DeleteSnapshot.

DiskId

String

Yes

The ID of the disk device.

InstanceId

String

Yes

The ID of the instance.

SnapshotId

String

Yes

The ID of the snapshot.

Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements. Examples Example Request https://ecs.aliyuncs.com/?Action=DeleteSnapshot &DiskId=1033-60053321 &InstanceId=Bc23xYm09 &SnapshotId=923FE2BF04C5 &

Example Response XML Format CEF72CEB-54B6-4AE8-B225-F876FF7BA984 JSON Format { "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BA984" }

4.3.3 DescribeSnapshots Description Query all snapshots related to a cloud server disk device. Request Parameters

46

Aliyun ECS API Reference Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DescribeSnapshots.

InstanceId

String

Yes

The ID of the instance to specify.

DiskId

String

Yes

The ID of the disk to specify.

Response Elements Name

Type

Description

Snapshots

SnapshotType

A snapshot information set consisting of SnapshotType.

Examples Example Request https://ecs.aliyuncs.com/?Action=DescribeSnapshots &InstanceId=Bc23xYm09 &DiskId=1033-60053321 &

Example Response XML Format 1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6 923FE2BF04C5 100 2012-06-01T12:03Z JSON Format

47

Aliyun ECS API Reference { "RequestId": "1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6", "Snapshots": { "Snapshot": [{ "SnapshotId": "923FE2BF04C5", "Progress": "100", "CreationTime": "2012-06-01T12:03Z" }] } }

4.3.4 DescribeSnapshotAttribute Description Query the detailed information of a specific snapshot. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DescribeSnapshotAttribute.

RegionId

String

Yes

The ID of the region where the snapshot belongs to.

SnapshotId

String

Yes

The ID of the snapshot.

Response Elements Name

Type

Description

SnapshotId

String

The ID of the snapshot.

SnapshotName

String

The name of the snapshot to display. This parameter is in the response only if it is specified in the snapshot creation.

Progress

Integer

The progress of the creation. The unit is percent. 100 represents that the snapshot creation is finished.

CreationTime

String

The time that the snapshot is created. It must conforms to ISO8601 standards and should be described in UTC. The format looks like YYYY-MM-DDThh:mmZ.

Examples Example Request

48

Aliyun ECS API Reference https://ecs.aliyuncs.com/?Action=DescribeSnapshotAttribute &RegionId=cn-hangzhou-dg-a01 &SnapshotId=923FE2BF04C5 &

Example Response XML Format C8B26B44-0189-443E-9816-D951F59623A9 923FE2BF04C5 100 2012-06-01T12:03Z JSON Format { "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9", "SnapshotId": "923FE2BF04C5", "Progress": "100", "CreationTime": 2012-06-01T12:03Z, }

4.4

Image Interfaces

4.4.1 DescribeImages Description Query all images that can be used. The displayed images include private image resources owned by a user, and other public image resources. This interface supports paging query. The query results include the total counts of usable image resources, and the image resources in current page. The number of image resources to display is 10 by default. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DescribeImages.

RegionId

String

Yes

The ID of the region which the instance belongs to.

PageNumber

Integer

No

The page number of the instance status page. 49

Aliyun ECS API Reference The start number is 1, and the default value is 1. PageSize

Integer

No

The rows to be displayed per page in paging query. The maximum number is 50 and the default value is 10.

ImageId

String

No

The ID of the image. There can be several images, separated by “,”.

ImageOwnerAlias

String

No

The alias of the image owner. There can be several alias, separated by “,”. The optional values are: ·system ·self ·others If this parameter is not specified, all images will be returned in the response.

Response Elements Name

Type

Description

RegionId

String

The ID of the region where the image belongs to.

TotalCount

Integer

The total number of the images.

PageNumber

Integer

The page number.

PageSize

Integer

The rows to be displayed per page in paging query. The maximum number is 50 and the default value is 10.

Images

ImageType

An image information set consisting of ImageType.

Architecture

String

The operation system of the image: i386 | x86_64

Examples Example Request https://ecs.aliyuncs.com/?Action=DescribeImages &RegionId=cn-hangzhou-dg-a01 &

Example Response XML Format

50

Aliyun ECS API Reference 63DFD5FB-294A-45C9-8206-1D82C9882D33 cn-hangzhou-dg-a01 12 1 3 windows2003stdcn.64.20110509.01.vhd 1 Windows Server 2003 windows2003stdcn.64.20110509.01.vhd 60 x86_64 system Windows Server 2003 64 位 windows2003.20101028.ww.01.vhd 1 Windows Server 2003 windows2003.20101028.ww.01.vhd 60 i386 system Windows Server 2003 rhel54.64.20110224.01.vhd 1 Red Hat rhel54.64.20110224.01.vhd 60 x86_64 self Red Hat 64 位 JSON Format 51

Aliyun ECS API Reference { "RequestId": "63DFD5FB-294A-45C9-8206-1D82C9882D33", "RegionId": "cn-hangzhou-dg-a01", "TotalCount": 12, "PageNumber": "1", "PageSize": "10", "Images": { "Image": [{ "ImageId": "windows2003stdcn.64.20110509.01.vhd", "ImageVersion": "1", "Platform": "Windows Server 2003", "Description": "windows2003stdcn.64.20110509.01.vhd", "Size": 60, "ImageOwnerAlias": "system", "OSName": "Windows Server 2003 64 位" }, { "ImageId": "rhel54.64.20110224.01.vhd", "ImageVersion": "1", "Platform": "Red Hat", "Description": "rhel54.64.20110224.01.vhd", "Size": 60, "ImageOwnerAlias": "system", "OSName": "Windows Server 2003" }, { "ImageId": "debian-603-64.rs.test.20120417.vhd", "ImageVersion": "1", "Platform": "Red Hat", "Description": "debian-603-64.rs.test.20120417.vhd", "Size": 60, "ImageOwnerAlias": "self", "OSName": "Red Hat 64 位" }] } }

4.4.2 CreateImage Description Create custom image based on snapshots. These images can be used to create new ECS 52

Aliyun ECS API Reference instances. ·Only the snapshot of the system disk can be used to create custom images. ·Only snapshots in completed status (the process has reached 100%) can be used to create custom images. ·When the security control marks the instance as “locked” status, the custom image cannot be created. ·The snapshot created on or before July 15th, 2013 cannot be used to create custom image. If the snapshot is created in or before July, 15th, 2013, this API call will be declined, and Response code is InvalidSnapshot.TooOld. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be CreateImage.

RegionId

String

Yes

The ID of the region where the image belongs to.

SnapshotId

String

Yes

The ID of the snapshot from which the image is created.

ImageVersion

String

No

The version number of the image. The length is 1~40 English characters.

Description

String

No

The description of the image. The length is 1~200 English characters.

OSName

String

No

The displayed name of the operating system.

ClientToken

String

No

To ensure the idempotence of the requests, the client generates the value of this parameter, which must be unique among different requests. The maximum length is 64 ASCII characters. Please refer to the appendix on How to follow the law of Idempotence.

Response Elements Name

Type

Description

ImageId

String

The ID of the image.

Examples Example Request

53

Aliyun ECS API Reference https://ecs.aliyuncs.com/?Action=CreateImage &RegionId=cn-hangzhou-dg-a01 &ImageVersion=img-2012-12-01-1300 &Description=demo_image &

Example Response XML Format C8B26B44-0189-443E-9816-D951F59623A9 63DFD5FB-294A-45C9-8206-1D82C9882D09 JSON Format { "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9", "ImageId": "63DFD5FB-294A-45C9-8206-1D82C9882D09" }

4.4.3 DeleteImage Description Delete the custom image specified by the user. After deletion, the image cannot be used in ECS instance creation and reset. ·If the specified image does not exist, the request will be ignored. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DeleteImage.

RegionId

String

Yes

The ID of the region where the image belongs to.

ImageId

String

Yes

The ID of the image.

Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements. Examples

54

Aliyun ECS API Reference Example Request https://ecs.aliyuncs.com/?Action=DeleteImage &RegionId=cn-hangzhou-dg-a01 &ImageId=63DFD5FB-294A-45C9-8206-1D82C9882D09 &

Example Response XML Format CEF72CEB-54B6-4AE8-B225-F876FF7BA984 JSON Format { "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BA984" }

4.5

Network Interfaces

4.5.1 AllocatePublicIpAddress Description Assign a usable public IP address to an instance. ·The instance status must be Running or Stopped. ·The assigned IP becomes valid after instance start or reboot. ·Only IP address can be assigned, not IP address range. ·As present, one instance can only have one IP address. If the instance has been assigned a public IP, the IP will be returned when this interface is called. ·When the security control marks the instance as “locked” status, the public IP cannot be assigned to the instance. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be AllocatePublicIpAddress. 55

Aliyun ECS API Reference InstanceId

String

Yes

The instance ID to assign IP address.

Response Elements Name

Type

Description

IpAddress

String

The public IP address assigned to the instance.

Examples Example Request https://ecs.aliyuncs.com/?Action=AllocatePublicIpAddress &InstanceId=Bc0102-23xYm09 &

Example Response XML Format F2EF6A3B-E345-46B9-931E-0EA094818567 10.1.149.159 JSON Format { "RequestId": "F2EF6A3B-E345-46B9-931E-0EA094818567", "IpAddress": "10.1.149.159" }

4.6

Security Group Interfaces

4.6.1 CreateSecurityGroup Description Create a new security group. Add firewall configurations to a group of instances by setting security group firewall rules. One security group consists of multiple instances. ·New security group only opens the intragroup access permission to the instances in the security group, and closes all other permissions. If there is a need to allow access from instances of other security groups or from the Internet, a user can modify the security group firewall rules by the interface authorize security group permissions. ·The firewall rule makes a distinction between the intranet and the internet. 56

Aliyun ECS API Reference

·Each user can create 100 security groups at most. Request parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be CreateSecurityGroup.

RegionId

String

Yes

The ID of the region which the security group belongs to.

Description

String

Yes

The description information for the security group. The length limit is 500 bytes, and Chinese characters are not supported.

ClientToken

String

No

To ensure the idempotence of the requests, the client generates the value of this parameter, which must be unique among different requests. The maximum length is 64 ASCII characters. Please refer to the appendix on How to follow the law of Idempotence.

Response Elements Name

Type

Description

SecurityGroupId

String

The ID of the security group

Examples Example Request https://ecs.aliyuncs.com/?Action=CreateSecurityGroup &RegionId=cn-hangzhou-dg-a01 &Description=for%20a%20demo &

Example Response XML Format CEF72CEB-54B6-4AE8-B225-F876FF7BA984 F876FF7BA984 JSON Format

57

Aliyun ECS API Reference { "RequestId":"CEF72CEB-54B6-4AE8-B225-F876FF7BA984", "SecurityGroupId":" F876FF7BA984" }

4.6.2 AuthorizeSecurityGroup Description Set the external access permission to the security group. Two authorization methods are supported: 1. Open the access permission from other security groups within the same region. 2. Open the access permission from a specified IP address range (in CIDR format). ·Supported authorization strategy: accept. ·Different network types are supported. For example, NicType can be chosen as internet or intranet, representing public network or inner network. ·The maximum number of authorization rules of each security group is 100. ·The priority of the security groups is in descending order according to creation time. ·The intergroup authorization must be within the intranet. That is to say, the parameter NicType must be intranet ·The security group rule consists of either of the two parameter sets: ：SourceGroupId、 IpProtocol、PortRange、NicType、Policy, or SourceCidrIp、IpProtocol、PortRange、NicType、 Policy. If the security rule exists, the response will return an error. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be AuthorizeSecurityGroup.

SecurityGroupId

String

Yes

The ID of the security group.

RegionId

String

Yes

The ID of the region where the security group belongs to.

IpProtocol

String

Yes

IP protocol. The optional values are tcp|udp|icmp|gre|all. The value “all” represents supporting all of the four protocols.

58

Aliyun ECS API Reference PortRange

String

Yes

The port number range related to the IP protocol. The default port number range of tcp and udp is 1~65535. For example, “1/200” represents that the port range is 1~200. If the value is “200/1”, the response will return an error. The port number range of icmp protocol is -1/-1. The port number range of gre protocol is -1/-1. If IpProtocol is all, the port number range is -1/-1.

SourceGroupId

String

No

The ID of the source security group which can have access to the destination security group in the same region. At least one of the parameters SourceGroupId or SourceCidrIp must be specified. If Both paramters are specified, the parameter SourceCidrIp will be authorized. If this parameter is specified, the parameter NicType must be intranet.

SourceCidrIp

String

No

The source IP range which can have access to the destination security group. The IP address range is specified by CIDR format, and the default value is 0.0.0.0/0(representing no limit on access). As another example, the supported format can be 10.159.6.18/12 or 10.159.6.186.

Policy

String

No

The authorization policy. The value is accept (allow access). The default value is accept.

NicType

String

No

The network type. The optional values are: ·internet ·internet the default value is internet. To create authoration cross the security group (SourceGroupId is specified), the NicType must be intranet.

Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements. Examples Example Request 59

Aliyun ECS API Reference 1. Open the access permission from other security groups within the same region. https://ecs.aliyuncs.com/?Action=AuthorizeSecurityGroup &SecurityGroupId=C0003E8B-B930-4F59-ADC0-0E209A9012B0 &SourceGroupId=1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6 &IpProtocol=tcp &PortRange=1/65535 &

2. Open the access permission from a specified IP address range (in CIDR format). https://ecs.aliyuncs.com/?Action=AuthorizeSecurityGroup &SecurityGroupId=C0003E8B-B930-4F59-ADC0-0E209A9012B0 &SourceCidrIp=0.0.0.0/0 &IpProtocol=tcp &PortRange=1/65535 &

Example Response XML Format CEF72CEB-54B6-4AE8-B225-F876FF7BA984 JSON Format { "RequestId":"CEF72CEB-54B6-4AE8-B225-F876FF7BA984" }

4.6.3 DescribeSecurityGroupAttribute Description Query the detailed information on security permission control of a security group. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DescribeSecurityGroupAttribute.

SecurityGroupId

String

Yes

The ID of the security group.

60

Aliyun ECS API Reference RegionId

String

Yes

The ID of the region where the security group belongs to.

NicType

String

Yes

The network type. The optional values are: ·internet ·internet The default value is internet.

Response Elements Name

Type

Description

SecurityGroupId

String

The ID of the security group.

RegionId

String

The ID of the region where the security group belongs to.

Description

String

The description information of the security group.

Permissions

PermissionType

A set consisting of Permission Type, representing the permission rules of the security group.

Examples Example Request https://ecs.aliyuncs.com/?Action=DescribeSecurityGroupAttribute &SecurityGroupId=C0003E8B-B930-4F59-ADC0-0E209A9012B0 &RegionId=cn-hangzhou-dg-a01 &

Example Response XML Format

61

Aliyun ECS API Reference 1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6 cn-hangzhou-dg-a01 C0003E8B-B930-4F59-ADC0-0E209A9012B0 for demo ALL -1/-1 8dsmf982 Accept intranet tcp 1/65535 0.0.0.0/0 accept internet JSON Format

62

Aliyun ECS API Reference { "RequestId": "1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6", "RegionId": "cn-hangzhou-dg-a01", "SecurityGroupId": "C0003E8B-B930-4F59-ADC0-0E209A9012B0", "Description": "for demo", "Permissions": { "Permission": [{ "IpProtocol": "ALL", "PortRange": "-1/-1", "SourceGroupId": "8dsmf982", "Policy": "Accept", "NicType": "intranet" }, { "IpProtocol": "tcp", "PortRange": "1/65535", "SourceCidrIp": "0.0.0.0/0", "Policy": "accept", "NicType": "internet" }] } }

4.6.4 DescribeSecurityGroups Description Query the basic information of all security groups defined by the user by page. The row number per page is 10 by default. The data are ordered in descending order according to security group ID. Request Parameters Name

Value

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DescribeSecurityGroups.

RegionId

String

Yes

The ID of the region where the security group belongs to.

PageNumber

Integer

No

The page number of the instance status list. The start number is 1, and the default number is 1.

PageSize

Integer

No

The rows to be displayed per page in paging query. The maximum number is 50 and the

63

Aliyun ECS API Reference default value is 10. Response paramters Name

Type

Description

TotalCount

Integer

The total number of the security group.

PageNumber

Integer

Current page number.

PageSize

Integer

The rows per page.

RegionId

String

The ID of the region where the security group belongs to.

SecurityGroups

SecurityGroupItemType

The security group information. It is a set consisting of SecurityGroupItemType.

Examples Example Request https://ecs.aliyuncs.com/?Action=DescribeSecurityGroups &RegionId=cn-hangzhou-dg-a01 &

Example Response XML Format

64

Aliyun ECS API Reference 94D38899-626D-434A-891F-7E1F77A81525 4 1 10 cn-hangzhou-dg-a01 63DFD5FB Test 086FFC27 test00212 BA4B7975 cn-hangzhou-dg-a01 test group 35F20777 cn-hangzhou-dg-a01 test group JSON Format

65

Aliyun ECS API Reference { "RequestId": "94D38899-626D-434A-891F-7E1F77A81525", "TotalCount": 4, "PageSize": "10", "RegionId": "cn-hangzhou-dg-a01", "PageNumber": "1", "SecurityGroups": { "SecurityGroup": [{ "SecurityGroupId": "63DFD5FB", "Description": "TestByXcf" }, { "SecurityGroupId": "086FFC27", "Description": "test00212" }, { "SecurityGroupId": "BA4B7975", "Description": "cn-hangzhou-dg-a01 test group" }, { "SecurityGroupId": "35F20777", "Description": "cn-hangzhou-dg-a01 test group" }] } }

4.6.5 RevokeSecurityGroup Description Revoke the access permissions the security group provides to the external entities. There are two ways to revoke the permissions. The first way is to revoke the access permission of other security groups within the same region, which uses specified protocols to access specified port of this security group. The second way is to cancel the access permission of an IP address range, which uses specified protocols to access specified port of this security group. Only permission items created by the authorization interface can be deleted (the parameter value should be the same as the value set in authorization). The security group rule consists of either of the two parameter sets: SourceGroupId、 IpProtocol、PortRange、NicType、Policy, or SourceCidrIp、IpProtocol、PortRange、NicType、 Policy. If the security rule not exists, the response will return an error.

66

Aliyun ECS API Reference Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be RevokeSecurityGroup.

SecurityGroupId

String

Yes

The ID of the security group.

RegionId

String

Yes

The ID of the region where the security group belongs to.

IpProtocol

String

Yes

IP protocol. The optional values are tcp|udp|icmp|gre|all. The value “all” represents supporting all of the four protocols.

PortRange

String

Yes

The port number range related to the IP protocol. The default port number range of tcp and udp is 1~65535. For example, “1/200” represents that the port range is 1~200. If the value is “200/1”, the response will return an error. The port number range of icmp protocol is -1/-1. The port number range of gre protocol is -1/-1. If IpProtocol is all, the port number range is -1/-1.

SourceGroupId

String

No

The ID of the source security group which can have access to the destination security group in the same region. At least one of the parameters SourceGroupId or SourceCidrIp must be specified. If Both paramters are specified, the parameter SourceCidrIp will be authorized. You can specify multiple groups (10 at most), and separate the groups by “,”.

SourceCidrIp

String

No

The source IP range which can have access to the destination security group. The IP address range is specified by CIDR format, and the default value is 0.0.0.0/0(representing no limit on access). As another example, the supported format can be 10.159.6.18/12 or 10.159.6.186.

Policy

String

No

The authorization policy. The optional values are accept (allow access), drop (drop package while accessing), reject (reject package while accessing). The default value is accept.

NicType

String

No

The network type. The optional values are: ·internet ·internet The default value is internet. 67

Aliyun ECS API Reference To revoke authoration cross the security groups (SourceGroupId is specified), the NicType must be intranet. Response Elements All Response Elements are Common response Elements. Please refer to Common response Elements. Examples Example Request https://ecs.aliyuncs.com/?Action=RevokeSecurityGroup &SecurityGroupId=C0003E8B-B930-4F59-ADC0-0E209A9012B0 &SourceGroupId=1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6 &IpProtocol=tcp &PortRange=1/65535 &

Example Response XML Format CEF72CEB-54B6-4AE8-B225-F876FF7BA984 JSON Format { "RequestId":"CEF72CEB-54B6-4AE8-B225-F876FF7BA984" }

4.6.6 DeleteSecurityGroup Description Delete a specified security group. ·A security group can only be deleted if there are no instances in the group, and it is not referred by the security rules of other groups. Request Parameters Name

Type

Required

Description

68

Aliyun ECS API Reference Action

String

Yes

This parameter is required by the system. Its value should be DeleteSecurityGroup.

SecurityGroupId

String

Yes

The ID of the security group.

RegionId

String

Yes

The ID of the region where the security group belongs to.

Response Elements Name

Type

Description

Regions

RegionType

A region information set consisting of RegionType.

Examples Example Request https://ecs.aliyuncs.com/?Action=DeleteSecurityGroup &SecurityGroupId=C0003E8B-B930-4F59-ADC0-0E209A9012B0 &RegionId=cn-hangzhou-dg-a01 &

Example Response XML Format CEF72CEB-54B6-4AE8-B225-F876FF7BA984 JSON Format { "RequestId":"CEF72CEB-54B6-4AE8-B225-F876FF7BA984" }

4.7

Region Interfaces

4.7.1 DescribeRegions Description Query usable region list. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value

69

Aliyun ECS API Reference should be DescribeRegions. Response Elements Name

Type

Description

Regions

RegionType

A region information set consisting of RegionType.

Examples Example Request https://ecs.aliyuncs.com/?Action=DescribeRegions &

Example Response XML Format 611CB80C-B6A9-43DB-9E38-0B0AC3D9B58F cn-hangzhou-dg-a01 cn-qingdao-cm5-a01 JSON Format { "RequestId": "611CB80C-B6A9-43DB-9E38-0B0AC3D9B58F", "Regions": { "Region": [{ "RegionId": "cn-hangzhou-dg-a01" }, { "RegionId": "cn-qingdao-cm5-a01" }] } }

70

Aliyun ECS API Reference

4.8

Other Interfaces

4.8.1 DescribeInstanceTypes Description Query instance resource types provided by ECS. ·The usable types are in accordance with the pay-by-volume types on the website. Please refer to http://help.aliyun.com/view/11108189_13545434.html ·If there is a need to use other types, a user can submit a capacity expansion request to the Aliyun work order system. Request Parameters Name

Type

Required

Description

Action

String

Yes

This parameter is required by the system. Its value should be DescribeInstanceTypes.

Response Elements Name

Type

Description

InstanceTypes

InstanceTypeItemType

A instance type item InstanceTypeItemType.

Examples Example Request https://ecs.aliyuncs.com/?Action=DescribeInstanceTypes &

Example Response XML Format

71

set

consisting

of

Aliyun ECS API Reference 1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6 ecs.t1.xsmall 1 0.5 ecs.t1.small 1 1 ecs.s1.xsmall 1 1.5 JSON Format { "RequestId": "1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6", "InstanceTypes": { "InstanceType": [{ "InstanceTypeId": "ecs.t1.xsmall", "CpuCoreCount": 1, "MemorySize": 0.5 }, { "InstanceTypeId": "ecs.t1.small", "CpuCoreCount": 1, "MemorySize": 1 }, { "InstanceTypeId": "ecs.s1.xsmall", "CpuCoreCount": 1, "MemorySize": 1.5 }] } }

72

Aliyun ECS API Reference

5 Data Types DiskItemType Description The type of the disk information item.

Node Name Disk

Child Nodes Name

Type

Description

DiskId

String

The ID of the disk

Type

String

The Type of the disk The optional values are: ·system: system disk ·data: data disk

Category

String

Size

Integer

The category of the disk The optional values are: ·cloud: cloud disk ·ephemeral: temporary disk The size of the disk. The unit is GB.

DiskSetType Description The type of disk information list.

73

Aliyun ECS API Reference

Node Name Disks

Child Nodes Name

Type

Description

Disk

DiskItemType

Disk information item

ImageType Description The type of image information.

Node Name Image

Child Nodes Name

Type

Description

ImageId

String

The ID of the image

ImageVersion

String

The version of the image

PlatForm

String

The operating system platform

Description

String

Description Information

Size

Integer

The size of the image

ImageOwnerAlias

String

OSName

String

The alias of the image owner The optional values are: ·system – system public image ·self – user custom image ·other- public image of other user The displayed name of the operating system

74

Aliyun ECS API Reference

InstanceMonitorDataType Description The type of instance monitor data

Node Name InstanceMonitorData

Child Nodes Name

Type

Description

InstanceId

String

The ID of the instance

CPU

Double

The CPU usage. Unit: percent (%)

Memory

Integer

The size of the memory. Unit: MB

IntranetRx

Integer

The data traffic received by the cloud server instance. Unit: kbytes

IntranetTx

Integer

The data traffic sent by the cloud server instance. Unit: kbytes

IntranetFlow

Integer

The network traffic of the cloud server instance. Unit: kbytes

IntranetBandwidth

Integer

The bandwidth (network traffic in unit time) of the cloud server instance. Unite: kbytes/s

InternetRX

Integer

The data traffic received by the cloud server instance. Unit: kbytes

InternetTX

Integer

The data traffic sent by the cloud server instance. Unit: kbytes

InternetFlow

Integer

The network traffic of the cloud server instance. Unit: kbytes

InternetBandwidth

Integer

The bandwidth (network traffic in unit time) of the cloud server instance. Unite: kbytes/s

IOPSRead

Integer

IO read operations per second. Unit: times/s

IOPSWrite

Integer

IO write operations per second. Unit: times/s

BPSRead

Integer

The disk read bandwidth. Unit: byte/s

BPSWrite

Integer

The disk write bandwidth. Unit: byte/s

TimeStamp

String

The time of the query. The format conforms to ISO8601 standards.

75

Aliyun ECS API Reference

InstanceStatusItemType Description The type of instance status.

Node Name InstanceStatus

Child Nodes Name

Type

Description

InstanceId

String

The ID of the Instance

Status

String

The status of the instance

InstanceStatusSetType Description An item set consisting of instance statuses.

Node Name InstanceStatuses

Child Nodes Name

Type

Description

InstanceStatus

InstanceStatusitemType[]

A set consisting of InstanceStatusItemType

76

Aliyun ECS API Reference

InstanceTypeItemType Description The type of instance type item.

Node Name Instance Type

Child Nodes Name

Type

Description

InstanceTypeId

String

The ID of the instance type

CpuCoreCount

Integer

The number of CPU cores

MemorySize

Double

The size of the memory. The unit is GB

IpAddressSetType Description A set consisting of IP address.

Node Name It is decided by the interface.

Child Nodes Name

Type

Description

IpAddress

String

IP address

77

Aliyun ECS API Reference

PermissionSetType Description A set of security group permission rules.

Node Type Permissions

Child Nodes Name

Type

Description

Permission

PermissionType

Security group rules

PermissionType Description The type of security group permissions.

Node Name Permission

Child Nodes Name

Node

Description

IpProtocol

String

The IP protocol specified in authorization

PortRange

String

The port number range specified in authorization

SourceCidrIp

String

The IP address range specified in authorization

SourceGroupId

String

The ID of the source security group

Policy

String

The authorization policy

NicType

String

The network type

78

Aliyun ECS API Reference

RegionType Description The type of Region information.

Node Name Region

Child Nodes Name

Type

Description

RegionId

String

Region ID

SnapshotType Description The Type of snapshot information.

Node Name It is decided by the interface.

Child Nodes Name

Type

Description

SnapshotId

String

The ID of the snapshot

SnapshotName

String

The displayed name of the snapshot. If SnapshotName is specified during snapshot creation, it will be returned in the response.

Progress

Integer

The rate of progress of snapshot creation. The unit is percent (the percent sign is not included in the response)

CreationTime

String

The time of snapshot creation. It conforms to ISO8601 standards, should be described in UTC. The format looks like: YYYY-MM-DDThh:mmZ 79

Aliyun ECS API Reference

SecurityGroupIdSetType Description The data type of security group ID set.

Node Name SecurityGroupIds

Child Nodes Name

Type

Description

SecurityGroupId

String

The ID of the security group

SecurityGroupSetType Description The type of security group set.

Node Name SecurityGroups

Child Nodes Name

Type

Description

SecurityGroup

SecurityGroupItemType

Security group

80

Aliyun ECS API Reference

SecurityGroupItemType Description The type of security group set.

Node Name SecurityGroups

Child Nodes Name

Type

Description

SecurityGroupId

String

The ID of the security group

Description

String

Description information

IPRangeSetType Description The type of IP address range set.

Node Name IpRanges

Child Nodes Name

Type

Description

IpAddress

String

The IP address range is specified in CIDR format.

NicType

String

The network type. The optional values: internet| intranet

81

Aliyun ECS API Reference

6 Appendix 6.1

Instance Resource Type Comparison Table

Type

Type Code

CPU (Core)

Memory (G)

Disk

Tiny

ecs.t1.xsmall

1

0.5

X

ecs.t1.small

1

1

X

ecs.s1.small

1

2

X

ecs.s1.medium

1

4

X

ecs.s2.small

2

2

X

ecs.s2.large

2

4

X

ecs.s2.xlarge

2

8

X

ecs.s3.medium

4

4

X

ecs.s3.large

4

8

X

ecs.m1.medium

4

16

X

ecs.m1.xlarge

8

32

X

ecs.c1.small

8

8

X

ecs.c1.large

8

16

X

ecs.c2.xlarge

16

64

X

Standard

High Memory High CPU

Disk Space (G)

6.2

60G~2048G, each 10G is an interval. One instance can have 5 disk devices at most (including the system disk).

Error Code Table

6.2.1 Client Side Error Error Code UnsupportedOperation

Description

HTTP Status Code

The specified action is not

400

supported. NoSuchVersion

The specified version does

400

not exist. UnsupportedParameter

The parameter”” is not supported. MissingParameter

The input parameter "" that is

82

400

Aliyun ECS API Reference mandatory for processing this request is not supplied. InvalidParameter

The specified parameter

400

"" is not valid. Or The specified image does not support the specified instance type. Throttling

Request was denied due to

400

request throttling. InvalidAccessKeyId.NotFound

The Access Key ID provided

400

does not exist in our records. Forbidden

User not authorized to

403

operate on the specified resource. Forbidden.RiskControl

This operation is forbidden

403

by Aliyun Risk Control system. Forbiden.NomoreSecurityGroup

This operation is forbidden

403

because an instance must be in 1 security group at least. Forbidden.AccessTooManyOthersReso urce

This operator is forbidden

403

because too many other one’s resource to be accessed.

SignatureDoesNotMatch

The signature we calculated

403

does not match the one you provided. Please refer to the API reference about authentication for details. SignatureNonceUsed

The request signature

400

nonce has been used. IdempotentParameterMismatch

Request uses a client token

400

in a previous request but is not identical to that request. IncorrectInstanceStatus

The current instance status

400

does not support this operation. InstanceMountedSnapshot

The current instance mounted snapshot. Please 83

400

Aliyun ECS API Reference uninstall first InvalidSecurityGroupStatus

The current security group

400

status does not support this operation. InvalidSecurityGroup.InUse

The current security group

400

is referenced by an instance or another security group and cannot be deleted. SecurityGroupLimitExceeded

Exceeding the allowed

400

amount of security groups. DiskNumberLimitExceeded

Exceeding the allowed

400

amount of disks. SecurityGroupRuleLimitExceeded

Exceeding the allowed

400

amount of rules of a security group. SecurityGroupInstanceLimitExceed

Exceeding the allowed

400

amount of instances of a security group. InstanceSecurityGroupLimitExceede d

Exceeding the allowed

400

amount of security groups that an instance can be in. InvalidSnapshot.InUse

Specified snapshot is

400

mounted and cannot be deleted InvalidInstanceId.NotFound

Specified instance does not

400

exist. InvalidInstanceId.Malformed

Specified instance ID is not

400

valid. InvalidInstanceType.NotFound

Specified instance type

400

does not exist. InvalidRegionId.NotFound

Specified region does not

400

exist. InvalidDiskId.NotFound

Specified disk does not

400

exist. InvalidDiskId.Malformed

Specified disk ID is not

400

valid. InvalidDisk.NotReady

The specified disk is not

400

ready for this operation. Please try it later. InvalidDiskType.NotFound

Disks of specified DiskType

400

do not exist. InvalidDiskCategory.NotSupported

The specified disk category is not supported 84

400

Aliyun ECS API Reference by this operation. InvalidSnapshotId.NotFound

Specified snapshot does not

400

exist. InvalidSnapshotId.Malformed

Specified snapshot ID is not

400

valid. InvalidSnapshot.Unbootable

Specified snapshot is not

400

bootable maybe because it was not created from a system disk. InvalidSnapshot.NotReady

The specified snapshot is

400

not ready for this operation. Please try it later. InvalidSnapshot.TooOld

This operation is forbidden

400

because the specified snapshot is created before 2013-07-15. InvalidPassword.Malformed

Specified password is not

400

valid. InvalidPublicIpAddress.NotFound

Specified public IP address

400

does not exist. InvalidPublicIpAddress.Malformed

Specified public IP address

400

is not valid. InvalidHostName.Malformed

Specified host name is not

400

valid. InvalidImageId.NotFound

Specified image does not

400

exist. InvalidImageId.Malformed

Specified image ID is not

400

valid. InvalidImageId.BasedSnapshotTooOl d

Specified image is based on

400

a snapshot created before 2013-07-15 InvalidSecurityGroupId.Malformed

Specified security group ID

400

is not valid. InvalidSecurityGroupId.NotFound

Specified security group

400

does not exist. InvalidSourceGroupId.NotFound

Specified source group

400

does not exist. InvalidSourceGroupId.Malformed

The source group ID can not

400

be the same with the destination group ID. InvalidSecurityGroupDescription

Specified description is not

400

valid. InvalidIpProtocol

Specified IP protocol is not 85

400

Aliyun ECS API Reference valid. InvalidDiskSize.Malformed

Specified disk size is not

400

valid. InvalidDiskSize.Exceeded

The total size of disks

400

exceeds its quota. InvalidInternetMaxBandwidth.Malfo rmed

Specified internet max

400

bandwidth is not valid.

InvalidSourceCidrIp.Malformed

Specified source CIDR IP is

400

not valid. InvalidPortRange.Malformed

Specified port range is not

400

valid. InvalidPolicy.Malformed

Specified policy is not valid.

400

InvalidNicType.Malformed

Specified nic type is not

400

valid. ChargeTypeViolation

Operations on this kind of

403

resources are not permitted. InsufficientBalance

Your account does not have

400

enough balance. QuotaExceeded

Living instances quota

400

exceeded. DiskNumberLimitExceeded

Exceeding the allowed

400

amount of disks. OperationDenied

Specified operation is

403

denied as your instance is locked for security reasons. RiskControl.Refused

Your action was.refused by

400

RiskControl. QuotaExceeded.Snapshot

Snapshot quota exceeded.

400

QuotaExceeded.Image

Image quota exceeded.

400

Forbidden.SystemDiskCannotBeDelet

This operation is forbidden

400

ed

because system disk cannot be deleted.

6.2.2 Server Side Error Error Code InsufficientInstanceCapa city

Description

HTTP Status Code

There is insufficient capacity

500

available for the requested instance.

InternalError

The request processing has failed due to some unknown 86

500

Aliyun ECS API Reference error, exception or failure. ServiceUnavailable

The request has failed due to

503

a temporary failure of the server.

6.3

Instance Status Table

Status Name

Description

Stopped

The instance has stopped.

Starting

The instance is starting.

Running

The instance is running.

Stopping

The instance is stopping

Deleted

The instance has been released.

6.4

Instance State Machine

6.5

Disk Categories

Disk Type

Category

Maximum Capacity per Disk

Maximum Data Disk Number per Instance

Maximum Capacity of the Same Type per Instance

Cloud Disk

cloud

2T

4

2T

Ephemeral Disk

ephemeral

1T

4

2T (system disk included)

87

Aliyun ECS API Reference

6.6

How to Make a Request

In an ECS interface call, the client sends a HTTP request (both HTTP and HTTPS channel are OK) to the ECS server, and receives the response of the request from the ECS server. After the ECS server receives a user’s request, it validates the user’s identify and parameters, submits the parameters or performs the actions specified by the request, and sends the result back to the user in the form of HTTP response.

6.6.1 The Request Structure A request has the following parts. HTTP method: Currently, all ECS interfaces only support GET method. Request URL: It includes the server address, the action name to be performed, the operation parameters and the Common request parameters. Server address: The domain https://ecs.aliyuncs.com/.

Name

of

ECS

is

http://ecs.aliyuncs.com/

and

To ensure the security of the request, we strongly recommend you to use HTTPS channel. (HTTPS encrypted the communication via SSL, which can prevent data leaks even if the communication is captured.) Action Name: Each interface must specify an action to perform, i.e. the Action parameter. Action Parameters: Different parameters should be handled in different actions. Please refer to the interface description. Common request Parameters: They are the parameters that each request must have, including timestamp, signature information. To make sure that the server can validate a user’s identity and authorize the permissions correctly, the request must add signature information. Please refer to the section Signature Mechanism. After the server has processed the request, it returns the response. The response result can be divided into successful information and failed information. The JSON format response is as follows.

88

Aliyun ECS API Reference { "RequestId": "4C467B38-3910-447D-87BC-AC049166F216", /* The response data*/ }

6.6.2 Interface Call Example Take the interface DescribeRegions as an example. (The following example is written in Java. As for the full version of the example program, please refer to Aliyun Developer Community http://dev.aliyun.com): The corresponding action is DescribeRegions. One parameter needed is Region. (All ECS RegionId can be acquired by the interface Query Usable Region List.) After adding all Common request paramters (excluding Signature), the request URL is as follows. (For easy reading, this is the URL before URL encoding.) http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&AccessKeyId=t estid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=NwDAxv LU6tFE0DVb&Version=2013-01-10&SignatureVersion=1.0

According to the signature algorithm, we construct the Canonicalized Query String as follows. http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&AccessKeyId=t estid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=NwDAxv LU6tFE0DVb&Version=2013-01-10&SignatureVersion=1.0

Then we construct the StringToSign, which is used for the signature. GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeRegions%26Format%3DXML%26S ignatureMethod%3DHMAC-SHA1%26SignatureNonce%3DNwDAxvLU6tFE0DVb%26Signatur eVersion%3D1.0%26TimeStamp%3D2012-12-26T10%253A33%253A56Z%26Version%3D20 13-01-10

The following Java sample code shows how to add Common request parameters, how to construct the Canonicalized Query String according to request paramters, and how to construct the StringToSign. The sample assumes that all parameters are put in a Map object, and Access Key ID is “testid”.

89

Aliyun ECS API Reference final String HTTP_METHOD = "GET"; Map parameters = new HashMap(); // Add request parameters parameters.put("Action", "DescribeRegions"); parameters.put("Version", "2013-01-10"); parameters.put("AccessKeyId", "testid"); parameters.put("TimeStamp", formatIso8601Date(new Date())); parameters.put("SignatureMethod", "HMAC-SHA1"); parameters.put("SignatureVersion", "1"); parameters.put("SignatureNonce", UUID.randomUUID().toString()); parameters.put("Format", "XML"); // Sort the parameters String[] sortedKeys = parameters.keySet().toArray(new String[]{}); Arrays.sort(sortedKeys); final String SEPARATOR = "&"; // Generate StringToSign StringBuilder stringToSign = new StringBuilder(); stringToSign.append(HTTP_METHOD).append(SEPARATOR); stringToSign.append(percentEncode("/")).append(SEPARATOR); StringBuilder canonicalizedQueryString = new StringBuilder(); for(String key : sortedKeys) { // Please notice the encoding to key and value canonicalizedQueryString.append("&") .append(percentEncode(key)).append("=") .append(percentEncode(parameters.get(key))); } //Please notice the encoding to canonicalizedQueryString stringToSign.append(percentEncode( canonicalizedQueryString.toString().substring(1)));

Please note that the parameter TimeStamp should conform to ISO8601 standards, and should use UTC. If not, an error will occur. The following sample code shows how to generate a TimeStamp.

90

Aliyun ECS API Reference private static final String ISO8601_DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'"; private static String formatIso8601Date(Date date) { SimpleDateFormat df = new SimpleDateFormat(ISO8601_DATE_FORMAT); df.setTimeZone(new SimpleTimeZone(0, "GMT")); return df.format(date); }

It is needed to encode the canonicalized query string (the variable canonicalizedQueryString in the sample code) and the stringToSign. The encoding rules are described in the section Signature mechanism. The following sample code shows how to use java.net.URLEncoder to complete encoding. private static final String ENCODING = "UTF-8"; private static String percentEncode(String value) throws UnsupportedEncodingException{ return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20") .replace("*", "%2A").replace("%7E", "~")

: null; }

Assume that the Access Key Id is “testid” and Access Key Secret is “testsecret”, the key to calculate HMAC is “testsecret&”. The signature value will be: SDFQNvyH5rtkc9T5Fwo8DOjw5hc= The sample code on how to calculate the signature is as follows (Java).

// how to calculate the signature final String ALGORITHM = "HmacSHA1"; final String ENCODING = "UTF-8"; key = "testsecret&"; Mac mac = Mac.getInstance(ALGORITHM); mac.init(new SecretKeySpec( key.getBytes(ENCODING), ALGORITHM)); byte[] signData = mac.doFinal( stringToSign.getBytes(ENCODING)); String signature = new String(Base64.encodeBase64(signData));

91

Aliyun ECS API Reference After the signature parameter is added, we ecode the URL according to RFC3986 rules. http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10%3A33%3A56Z&Format=XML&Access KeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&RegionId=region1 &SignatureNonce=NwDAxvLU6tFE0DVb&Version=2012-09-13&SignatureVersion=1.0&Signa ture=SDFQNvyH5rtkc9T5Fwo8DOjw5hc%3d

The the client sends the HTTP request to the URL address above, and receives response from the ECS server. The sample response is as follows. QingDao cn-qingdao Hangzhou cn-hangzhou 833C6B2C-E309-45D4-A5C3-03A7A7A48ACF

By parsing the XML result, we can get all usable RegionId and LocalName. If the parameter Format is specified as JSON, the response will be in JSON format.

6.7

How to follow the law of idempotence

When the client calls the interface to create ECS cloud server, if the request times out or encounters internal server error, the client may resend the request. The client can use the optional parameter ClientToken to prevent the server from creating more instances than expected. That is to say, the parameter ClientToken can ensure the idempotence of the request. ClientToken is a unique, case sensitive ASCII string generated by the client. Its length should be within 64 ASCII characters. If the client uses the same ClientToken to call the interface of creating an instance, the server will return the same request result, which contains the same InstanceId. Therefore, if a user needs to resend request when encountering errors, it is feasible to provide the same ClientToken to ensure that ECS only create one instance.

92

Aliyun ECS API Reference If the client provides a used ClientToken in a request, but the other parameters are different from those in the previous request, ECS will return the error code IdempotentParameterMismatch. However, please note that the parameter SignatureNonce, Timestamp and Signature must change in the retry. This is because SignatureNonce is used to prevent replay attack; Timestamp is used to mark the request time. So the second request must provide different value of SignatureNonce and Timestamp, which in consequence change the value of the parameter Signature. Generally, the client should only resend request when encounting 500 (InternetError), 503 (ServiceUnavailable) error, or cannot get response result. If the response result is 200, the retry operation will get the same result as the one, but cause no effect on the server status. If the response error is 4XX, generally the retry operation cannot succeed unless the there is a prompt “try it later”.

93

Aliyun ECS API Reference

Update History API version: 2013-01-10 Latest update time: 2014-3-22 Publish Time

Update

Description

2013-01-24

The first 2013-01-10 confirmed.

version is

There are interfaces about instance, disk, image, security group, public network IP, region and monitor.

2013-04-10

New functions are added, including resetting the instance, display snapshot name, and other monitor messages.

New interface ResetInstance is added. New parameter SnapshotName is added to the snapshot. New parameter InstanceId is added to the interface GetMonitorData, which is used to query specified monitor data. The interface description is improved.

2013-05-22

Interface descriptions on instance, disk and snapshot are improved.

The interface description on instance, disk and snapshot is improved.

2014-04-03

The contents are modified for Internet open service.

Some API are added or removed. Some error codes are added. The error codes for each API are specified. The same RequestId is used in the same interface. The limitation on the snapshots created on or before April 15th, 2013 is added. The limitation on CreateInstance is added. The instance which has a memory of 512M cannot use Windows operating system. The instance which has a memory larger than 4G cannot use 32-bit operation system. The sample code on DescribeMonitorData was modified, with the parameter InstanceId, Time added.

94