Aliun Server Load Balancer API Reference Version

Transcription

1 Aliun Server Load Balancer API Reference Version

2 Content 1 Introduction SLB API Concept Diagram Terms Limitations How to Call SLB API Structure of an API Request Host Name Communication Protocol Request Method Request Parameters Character Encoding Common Parameters Common Request Parameters Common Response Elements Response Results Successful Response Unsuccessful Response Signature Mechanism Cross-account Resource Access via RAM How to do Cross-account Resource Access Authorizable Resource Types in RAM Authorizable Actions for Resource in RAM Authentication rules in API Cross-account Resource Access Example of Cross-account Resource Access Interface Abstract LoadBalancer Listener BackendServer Interface Description LoadBalancer CreateLoadBalancer ModifyLoadBalancerInternetSpec DeleteLoadBalancer SetLoadBalancerStatus SetLoadBalancerName DescribeLoadBalancers DescribeLoadBalancerAttribute DescribeRegions Listener CreateLoadBalancerHTTPListener

3 5.2.2 CreateLoadBalancerTCPListener DeleteLoadBalancerListener StartLoadBalancerListener StopLoadBalancerListener SetLoadBalancerHTTPListenerAttribute SetLoadBalancerTCPListenerAttribute DescribeLoadBalancerHTTPListenerAttribute DescribeLoadBalancerTCPListenerAttribute BackendServer AddBackendServers RemoveBackendServers DescribeHealthStatus Appendix Error Code Table Client Side Errors Server Side Errors SLB Listener Status Machine How to Follow the Law of Idempotence Update History

4 1 Introduction Welcome to use Aliyun Server Load Blancer (SLB) service! By setting the virtual service IP address, SLB integrates multiple ECS instances in one region into a high-performance and high-availability server pool. It makes it easy for you to distribute application loads between two or more ECS instances. To avoid the single point failure, load balancer continuously checks the health status of ECS instances within its pool, and automatically isolates the abnormal ones. Another remarkable feature of SLB is DDoS protection, both TCP and HTTP protocols are supported to prevent DDoS attacks. 1.1 SLB API Concept Diagram SLB API is mainly made up of 3 basic concepts. LoadBalancer represents a SLB instance, Listener represents the load balancing strategies and forwarding rules set by the user. The external requests are sent to the backend servers via SLB instance according to related strategies and forwarding rules. 3

5 1.2 Terms Term Full Name Description SLB Server Load Balancer The network load balancing service provided by Aliyun. Region Region represents a separate geographic location. A region has a number of data centers. LoadBalancer Load Balancer LoadBalancer is a running instance of SLB service. If a user intends to use SLB, it should create a load balancer first. LoadBalancerId is the identity of each load balancer. Listener Listener SLB listener is load distributer and server health monitor. BackendServer Backend Server A group of ECS Instances within load balancer pool which actually process requests. Load balancer forwards the external requests to the backend servers for further processing according to the rules set by a user. 1.3 Explanations on business 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 mf When you found conflicts between this document and the reference URL, the reference URL shall prevail. 4

6 2 How to Call SLB API The SLB API interface calls are implemented by sending HTTP GET requests to the SLB 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 Host Name SLB API service host name is slb.aliyuncs.com Communication Protocol Both HTTP and HTTPS requests are supported in request communication. But we strongly recommend you to use the more secured way HTTPS Request Method Aliyun supports both GET and POST methods with the RPC-style API 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 request must have some action-specific request parameters Character Encoding The contents of requests and responses contents are encoded in UTF-8. 5

7 2.2 Common Parameters Common Request Parameters Common parameters are the request parameters that need to be included in every interface. Name Type Required Description Format String No The format of response data. JSON and XML are supported, and XML is default. Version String Yes The version number of the API. It is represented in all-numeric date notation in most-to-least-significant order YYYY-MM-DD. The latest version is 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 aglorithm. Please refer to Signature Mechanism. SignatureMe thod String Yes The 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, T12:00:00Z represents 12:00:00, January 1 st, 2013, Beijing Time. SignatureVer sion String Yes The version of the signature algorithm. The current version is 1.0. Value: 1.0 SignatureNo nce String Yes SignatureNonce is a unique random number to prevent network replay attacks. Users must use different random numbers in different requests. ResourceOw neraccount String No The owner of the account of the 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 6

8 &Format=xml &AccessKeyId=testid &Action=DescribeLoadBalancerAttribute &SignatureMethod=Hmac-SHA1 &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &SignatureNonce=NwDAxvLU6tFE0DVb &Version= &SignatureVersion=1.0 &Signature=FZnIrdNSLax4lnWf6NkKDc7mp54%3D Common Response Elements In every interface call request, the system returns a unique identification code RequestId to a user whether the request is successful or not. Examples <?xml version="1.0" encoding="utf-8"?> <! Response Root Node --> <Interface Name +Response> <! Request Label of the response--> <RequestId>4C467B D-87BC-AC049166F216</RequestId> <! Response Data--> </Interface Name+Response> 2.3 Response Results The responses of API calls are is in a uniform format. The HTTP response code 2XX stands for successful calls, while the response code 4XX or 5XX stands for failed calls. The successful data formats are XML and JSON, which can be specified in the request parameters by the external system. The default format is XML. The examples in this document are formatted to facilitate user browsing, but the actual response results have no line breaks or indentation Successful Response XML Format The XML response contains the information to identify whether the request is successful and 7

9 detailed business data. The example is as follows. <?xml version="1.0" encoding="utf-8"?> <! Response Root Node --> <Interface Name +Response> <! Request Label of the response--> <RequestId>4C467B D-87BC-AC049166F216</RequestId> <! Response Data--> </Interface Name+Response> JSON Format { "RequestId": "4C467B D-87BC-AC049166F216", /* Response Data */ } Error Response If there is something wrong with the interface call, the response data will not be returned. The interface caller can refer to the Error Code Table to locate the error position. 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 advised to provide the HostId and RequestId for a prompt problem settlement. XML Format <?xml version="1.0" encoding="utf-8"?> <Error> <RequestId> E A-A6C4-0E7863B733A5</RequestId> <HostId> slb.aliyuncs.com</hostid> <Code>UnsupportedOperation</Code> <Message>The specified action is not supported.</message> </Error> JSON Format 8

10 { "RequestId": ""7463B73D-35CC-4D19-A010-6B8D65D242EF"", "HostId": "slb.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. ECS 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. The user can apply and manage them from the official website of Aliyun. Access Key ID indicates the identity of the 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 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, -, _,., ~. 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 marks 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 9

11 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, and then use & to connect the strings 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 of the submitted 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 a user s 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: Before submitting the signature value as the parameter value to the ECS server, it should be encoded in the URL according to RFC3986 as other parameters. Take the action DescribeRegions for example. The request URL should be like this: &AccessKeyId=testid&Action=DescribeLoadBalancerAttribute&LoadBalancerId=1 39a00604ad-cn-east-hangzhou-01&SignatureMethod=Hmac-SHA1&SignatureNonc e=nwdaxvlu6tfe0dvb&version= &signatureversion=1.0 Therefore, StringToSign is: GET&%2F&AccessKeyID%3Dtestid%26Action%3DDescribeLoadBalancerAttribut e%26format%3dxml%26signaturemethod%3dhmac-sha1%26signaturenonce% 3DNwDAxvLU6tFE0DVb%26SignatureVersion%3D1.0%26Timestamp%3D T10%253A33%253A56Z%26Version%3D %26loadBalancerId%3D 139a00604ad-cn-east-hangzhou-01 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: 10

12 FZnIrdNSLax4lnWf6NkKDc7mp54= Then the URL request should be like this below. Please note that the Signature parameter is added. ttp://slb.aliyuncs.com/?timestamp= t10%3a33%3a56z&format= xml&accesskeyid=testid&action=describeloadbalancerattribute&signaturemeth od=hmac-sha1&loadbalancerid=139a00604ad-cn-east-hangzhou-01&signaturen once=nwdaxvlu6tfe0dvb&version= &signatureversion=1.0&signat ure=fznirdnslax4lnwf6nkkdc7mp54%3d You can refer to the Appendix How to Call Interface about the detailed example on signature and request submitting. 11

13 3 Cross-account Resource Access via RAM Aliyun SLB API Reference The SLB 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 APIs listed in this document to operate his resources. However, the user has no permissions on the resources owned by other users. Any API operated on other user s resources will be denied. With the help of Aliyun RAM (Resource Access Management), a user can operate resources not belonged to him. Before understanding how to use RAM to authorize and access SLB resources, 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 the parameter of ResourceOwnerAccount. Skipping this part will not hamper the understanding and usage of the other parts in the document. 3.1 How to do Cross-account Resource Access If you need to use SLB API to access other user s resources, please make sure that the target user has authorized the resources and permissions to you. Please refer to RAM product document and API document for authorization operation. Compared with access one s own resources, access the resources of other user via SLB API must specify one additional common parameter, ResourceOwnerAccount, to identify the owner of the resource. The example is as follows. &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &[email protected] &AccessKeyId=user_Y_keyid &<Other Common RequestParameters> In this example, user_y submits an API request to perform, StartInstance action on an ECS instance of user_x. The instance id is 139a00604ad-cn-east-hangzhou-01. If the request does not contain the parameter ResourceOwnerAccount, or the declared resource owner disaccords is different fromwith the actual resource owner, or [email protected] have not granted the permission to user_y, this request will be declined because the caller has no access to the target resource. 12

14 3.2 Authorizable SLB Resource Types in RAM Currently, the authorizable SLBresource only has one type. Resource Type LoadBalancer Aliyun Resource Naming (ARN) acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/* acs:slb:*:loadbalancer/* In this table, $regionid represents the id of certain region and $loadbalancerid represents the id of a certain loadbalancer. * is a wildcard character standing for all. 3.3 Authorizable Actions for SLB Resources in RAM In RAM, the user can authorize the following Actions on SLB resources. CreateLoadBalancer ModifyLoadBalancerInternetSpec DeleteLoadBalancer SetLoadBalancerStatus SetLoadBalancerName DescribeLoadBalancers DescribeLoadBalancerAttribute DescribeRegions CreateLoadBalancerHTTPListener CreateLoadBalancerTCPListener DeleteLoadBalancerListener StopLoadBalancerListener StartLoadBalancerListener SetLoadBalancerHTTPListenerAttribute SetLoadBalancerTCPListenerAttribute DescribeLoadBalancerHTTPListenerAttribute DescribeLoadBalancerTCPListenerAttribute AddBackendServers RemoveBackendServers DescribeHealthStatus 3.4 Authentication rules in API Cross-account Resource Access When a user uses SLB Open API to access cross-account resources, the SLB server checks the permission to make sure that the resource owner had authorized related permissions to the resource requester. Each SLB API action decides which resources to check according to the resource type and API semantics. Specifically, the authentication rules are as follows. 13

15 Action CreateLoadBalancer acs:slb:$regionid:loadbalancer/* ModifyLoadBalancerInternetSpec acs:slb:$regionid:loadbalancer/$loadbalanceri d SetLoadBalancerName DescribeLoadBalancers DescribeLoadBalancerAttribute DescribeRegions CreateLoadBalancerHTTPListener CreateLoadBalancerTCPListener DeleteLoadBalancerListener StopLoadBalancerListener StartLoadBalancerListener SetLoadBalancerHTTPListenerAttribute SetLoadBalancerTCPListenerAttribute DescribeLoadBalancerHTTPListenerAttribute DescribeLoadBalancerTCPListenerAttribute AddBackendServers RemoveBackendServers DescribeHealthStatus Authentication Rules CreateLoadBalancer acs:slb:$regionid:loadbalancer/* ModifyLoadBalancerInternetSpec acs:slb:$regionid:loadbalancer/$loadbalanceri d acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid acs:slb:$regionid:loadbalancer/$loadbalancerid and acs:ecs:$regionid:instance/$instanceid acs:slb:$regionid:loadbalancer/$loadbalancerid and acs:ecs:$regionid:instance/$instanceid acs:slb:$regionid:loadbalancer/$loadbalancerid 3.5 Examples of Cross-account Resource Access We assume that [email protected] has created an SLB instance, the LoadBalancerId is 139a00604ad-cn-east-hangzhou-01. Now [email protected] wants to authorize [email protected] to manage this instance via SLB API, but only allows four actions, SetLoadBalancerStatus, DescribeLoadBalancerAttribute, AddBackendServers, RemoveBackendServers. To achieve this, xiaoming needs to follow these steps. 1. Xiaoming should add Beibei to the RAM user space. He must call the AddUser action of RAM with xiaoming s account. The parameter UserName= [email protected] 14

16 &<Other Common RequestParameters > 2. Prepare authorization Policy. Policy is a JsonString, and it should contain the following elements. { "Version": "1", "Statusment": [ { "Effect": "Allow", "Action": ["slb:setloadbalancerstatus","slb:describeloadbalancerattribute", "slb: AddBackendServers","slb:RemoveBackendServers"], "Resource": ["acs:slb:*:loadbalancerid/139a00604ad-cn-east-hangzhou-01"] }] } 3. Xiaoming calls the PutPolicy action of RAM, and configures RAM policy for Beibei. The value of the PolicyName parameter is web_slb _policy, which is the name of the policy created by xiaoming. &[email protected] &PolicyName=web_slb_policy &PolicyDocument=$ The Policy prepared in Step 2 &<Other Common Request Parameters > 4. Beibei invokes API calls on this SLB instance, such as SetLoadBalancerStatus. In API call, Beibei must assign the parameter ResourceOwnerAccount to illustrate that this API call is operating on xiaoming s resource. &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &[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. 15

17 &PolicyName=web_slb_policy &<Other Common Request Parameters > 6. Now that the policy is deleted, Beibei will be denied when accessing this ECS instance. The response should be as follows. { } "RequestId": "7463B73D-35CC-4D19-A010-6B8D65D242EF", "HostId": "slb.aliyuncs.com", "Code": Forbidden", "Message": User not authorized to operate on the specified resource." 16

18 4 Interface Abstract 4.1 LoadBalancer CreateLoadBalancer: Create a load balancer. ModifyLoadBalancerInternetSpec: Modify the specification of a load balancer, including the charging types and resource types. DeleteLoadBalancer: Delete a load balancer and remove related configurations. SetLoadBalancerStatus: Set the status of load balancer. Start or stop a SLB instance. SetLoadBalancerName: Set the name of a load balancer. DescribeLoadBalancers: Query all SLB instances created by the user. DescribeLoadBalancerAttribute: Query SLB instance information. DescribeRegions: Query accessible regions. 4.2 Listener CreateLoadBalancerHTTPListener: Create a listener based on HTTP protocol for SLB instance. CreateLoadBalancerTCPListener: Create a listener based on TCP protocol for SLB instance. DeleteLoadBalancerListener: Delete the listener associated with a specific port. StartLoadBalancerListener: Start the specified Listener. StopLoadBalancerListener: Stop the specified Listener. SetLoadBalancerHTTPListenerAttribute: Configure the strategies and rules for HTTP protocol. SetLoadBalancerTCPListenerAttribute: Configure the strategies and rules for TCP protocol. DescribeLoadBalancerHTTPListenerAttribute: Query the current strategies and rules used by its 17

19 SLB instance. DescribeLoadBalancerTCPListenerAttribute: Query the current strategies and rules used by its SLB instance. 4.3 BackendServer AddBackendServers: Add a set of backend servers into a SLB instance. RemoveBackendServers: Delete a set of backend servers from into a SLB instance. DescribeHealthStatus: Check the health status of the backend servers of the SLB instance, and return their health status. 18

20 5 Interface Description 5.1 LoadBalancer CreateLoadBalancer Description Create a load balancer. Aliyun creates a SLB instance, assigns an IP address and a LoadBalancerId according to your specified paremeters. AddressType specifies whether the server address is public IP or internal IP. Request Parameters Name Type Required Description Action String Yes The name of the action. It is mandatory. Its value must be CreateLoadBalancer. RegionId String Yes Which Region to create your instance. Its value must be chosed from the return values of DescribeRegions. LoadBalancerName String No Mark name of the SLB instance. Its value is set by the user. The length should be between 1 to 80 characters. The valid characters are numbers,alphabets, -, /,., _. It doesn t have a default value. If this parameter is not specified, the system will return a name by default. AddressType String No The type of IP Address Optional value: internet intranet Default value:internet InternetChargeType String No The charging type of the Internet type instances. Optional value: paybybandwidth paybytraffic Default value:paybytraffic Bandwidth Integer No The peak burst speed of the Internet type instances which are charged by bandwidth. For the Internet type instances that are charged by constant bandwidth, the Bandwidth parameter of the Listener must be set first before this 19

21 parameter can take effect. For the Internet type instances that are charged by traffic peek speed, please directly set the Bandwidth parameter and ignore this parameter. Value: (Mbps) Default value:1 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 Ensure Idempotence. Response Elements Name Type Description <Common Response Elements> Refer <Common Request Parameters > LoadbalancerId String The unique identification of the SLB instance. Address String The server address assigned by the system. The user can determine whether to open the address to the public. LoadBalancerName String The mark name of the SLB instance. Examples Example Request &Action=CreateLoadBalancer &RegionId=cn-east-hangzhou-01 &LoadBalancerName=abc &AddressType=internet &InternetChargeType=paybytraffic &<Common Request Parameters > Example Response XML Format 20

22 <?xml version="1.0" encoding="utf-8"?> <CreateLoadBalancerResponse> <RequestId>365F F6-4AE4-92F8-7FF34B540710</RequestId> <LoadBalancerId>139a00604ad-cn-east-hangzhou-01</LoadBalancerId> <Address> </Address> <LoadBalancerName>abc</LoadBalancerName> </CreateLoadBalancerResponse> Json Format { "RequestId":"365F F6-4AE4-92F8-7FF34B540710", "LoadBalancerId":"139a00604ad-cn-east-hangzhou-01", "Address":" ", "LoadBalancerName":"abc" } ModifyLoadBalancerInternetSpec Description Modify the specification of the load balancer, including the charging types and resource types. Request parameters Name Type Required Description Action String Yes The name of the action. It is mandatory. Its value must be ModifyLoadBalancerInternetSpec. LoadBalancerId String Yes The unique identification of the SLB instance. InternetChargeType String Yes The charging type of the Internet type instances. Optional value: paybybandwidth paybytraffic Bandwidth Integer No The peak burst speed of the Internet type instances which are charged by bandwidth. For the Internet type instances that are charged by constant bandwidth, the Bandwidth parameter of the Listener must be set first before this parameter can take effect. For the Internet type instances that are charged by traffic peek speed, please directly set the Bandwidth parameter and ignore this parameter. Value: (Mbps) Default value:1 21

23 Response Elements All Response Elements are common Response Elements. Please refer to Common Request Parameters. Examples Example Request &Action=ModifyLoadBalancerInternetSpec &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &InternetChargeType=paybybandwidth &Bandwidth=10 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <DeleteLoadBalancerResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </ ModifyLoadBalancerInternetSpec > Json Format { } "RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" DeleteLoadBalancer Description Delete a SLB instance and remove related configurations. If the SLB instance has a Listener, the Listener will be deleted together. Request Parameters Name Request Required Description Action String Yes The name of the action. It is mandatory. Its value must be DeleteLoadBalancer. LoadBalancerId String Yes The unique identification of the SLB instance. Response Elements All Response Elements are common Response Elements. Please refer to common Response Elements. 22

24 Examples Example Request &Action=DeleteLoadBalancer &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <DeleteLoadBalancerResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </DeleteLoadBalancerResponse> Json Format { "RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" } SetLoadBalancerStatus Description Set the status of a load balancer. The default status of a newly created instance is active. If SetLoadBalancerStatus is active, the configurations of all Listeners of this SLB instance will be active, and take effect in the system. If SetLoadBalancerStatus is inactive, the configurations of all Listeners of this SLB instance will be inactive, and take effect in the system. Request Parameters Name Request Required Description Action String Yes The name of the action. It is mandatory. Its value must be SetLoadBalancerStatus. LoadBalancerId String Yes The unique identification of the SLB instance. LoadBalancerStatus String Yes The status of the LoadBalancer. Optional values: inactive active Response Elements All Response Elements are common Response Elements. Please refer to common Response Elements. 23

25 Examples Example Request &Action=SetLoadBalancerStatus &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &LoadBalancerStatus=active &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <SetLoadBalancerStatusResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </SetLoadBalancerStatusResponse> Json Format { "RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" } SetLoadBalancerName Description Set the mark name of the load balancer. Request Parameters Name Request Required Description Action String Yes The name of the action. It is mandatory. Its value must be SetLoadBalancerName. LoadBalancerId String Yes The unique identification of the SLB instance. LoadBalancerName String Yes The mark name of the SLB instance. Its value is set by the user. The length should be between 1 to 80 characters. The valid characters are numbers,alphabets, -, /,., _. Response Elements All Response Elements are common Response Elements. Please refer to common Response Elements. 24

26 Examples Example Request &Action=SetLoadBalancerName &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &LoadBalancerName=abc &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <SetLoadBalancerStatusResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </SetLoadBalancerStatusResponse> Json Format { "RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" } DescribeLoadBalancers Description Query all load balancers created by a user. In the query, LoadBalancerId AddressType InternetChargeType ServerId can be used as query parameters. If none of those parameters are used, all LoadBalance owned by the user will be returned. Name Request Required Description Action String Yes The name of the action. It is mandatory. Its value must be DescribeLoadBalancers. RegionId String Yes The region that the SLB instance belongs to. LoadBalancerId String No The unique identification of the SLB instance. AddressType String No Use the IP Address type as a filter. Optional values: internet intranet Default value: none If this parameter is not specified, it will not be a filter. InternetChargeType String No Use Internet charge type as a filter. Optional values: paybybandwidth paybytraffic 25

27 Default value: none If this parameter is not specified, it will not be a filter. ServerId String No Use the backend server ID (ECS instance ID) as a filter. If this parameter is specified, only the SLB instance that mounted this server will be returned. Value: ECS instance ID Default value: none If this parameter is not specified, it will not be a filter. Response Elements Name Type Description <Common Response Elements> Please refer to <Common Request Parameters >. LoadBalancers List A list of SLB instances. SLB Instance List Name Type Description LoadBalancerId String The unique identification of the SLB instance. LoadBalancerName String The mark name of the SLB instance. LoadBalancerStatus String The status of the SLB instance. It can be inactive, active or locked. Locked status represents that the instance is in arrearage, or locked by Aliyun. It is needed to renew the fees or contact Aliyun to unlock the instance. Examples Example Request &Action=DescribeLoadBalancers &RegionId=cn-east-hangzhou-01 &LoadBalancerId=139a00604ad-cn-east-hangzhou-01, 282b00102ac-cn-east-hangzhou-01 &<Common Request Parameters> Example Response XML Format 26

28 <?xml version="1.0" encoding="utf-8"?> <DescribeLoadBalancersResponse> <RequestId>365F F6-4AE4-92F8-7FF34B540710</RequestId> <LoadBalancers> <LoadBalancer> <LoadBalancerId>139a00604ad-cn-east-hangzhou-01</LoadBalancerId> <LoadBalancerName>abc</LoadBalancerName> <LoadBalancerStatus>active</LoadBalancerStatus> </LoadBalancer> <LoadBalancer> <LoadBalancerId>282b00102ac-cn-east-hangzhou-01</LoadBalancerId> <LoadBalancerName>def</LoadBalancerName> <LoadBalancerStatus>active</LoadBalancerStatus> </LoadBalancer> </LoadBalancers> </DescribeLoadBalancersResponse> Json Format {"RequestId":"365F F6-4AE4-92F8-7FF34B540710", "LoadBalancers":{ "LoadBalancer":[ {"LoadBalancerId":"139a00604ad-cn-east-hangzhou-01" "LoadBalancerName":"abc", "LoadBalancerStatus ":"active"}, {"LoadBalancerId":"282b00102ac-cn-east-hangzhou-01" "LoadBalancerName":"def", "LoadBalancerStatus ":"active"} ]}} DescribeLoadBalancerAttribute Description Query the information of a load balancer by LoadBalancerId. The response information includes SLB instance server address, server address type, SLB instance frontend port list and backend server list. Request Parameters Name Request Required Description Action String Yes The name of the action. It is mandatory. Its value 27

29 must be DescribeLoadBalancerAttribute. LoadBalancerId String No The unique identification of the SLB instance. Response Elements Name Type Description <Common Response Please refer to Common Response Elements. Elements > LoadBalancerId String The unique identification of the SLB instance. RegionId String The region that the SLB instance belongs to. LoadBalancerName String The mark name of the instance. If this value is not specified, the value is void. LoadBalancerStatus String The status of the SLB instance. It can be inactive, active or locked. Locked status represents that the instance is in arrearage, or locked by Aliyun. It is needed to renew the fees or contact Aliyun to unlock the instance. Address String SLB instance server address. AddressType String The address type, internet or intranet. InternetChargeType String The charging type of internet type instance, paybybandwidth or paybytraffic. Bandwidth Integer The peak burst speed of paybybandwidth instance. CreateTime String The SLB instance created time. ListenerPorts List A list of frontend ListenerPorts used by SLB instance. BackendServers List A list of backend servers used by SLB instance. ListenerPort : Frontend Listener ports used by SLB instance Name Type Description ListenerPort Integer Frontend Listener port numbers used by SLB instance. BackendServers: Backend servers used by SLB instance Name Type Description ServerId String The ID of the backend server (ECS instance ID). Weight Integer The weight of the backend server. Examples Example Request &Action=DescribeLoadBalancerAttribute &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &<Common Request Parameters> Example Response XML Format 28

30 <?xml version="1.0" encoding="utf-8"?> <DescribeLoadBalancerAttributeResponse> <RequestId>365F F6-4AE4-92F8-7FF34B540710</RequestId> <LoadBalancerId>139a00604ad-cn-east-hangzhou-01</LoadBalancerId> <RegionId>cn-east-hangzhou-01</RegionId> <LoadBalancerName>abc</LoadBalancerName> <LoadBalancerStatus>active</LoadBalancerStatus> <Address> </Address> <AddressType>internet</AddressType> <InternetChargeType>paybybandwidth</InternetChargeType> <Bandwidth>5</Bandwidth> <CreateTime> :00:00</CreateTime> <ListenerPorts> <ListenerPort>80</ListenerPort> <ListenerPort>443</ListenerPort> </ListenerPorts> <BackendServers> <BackendServer> <ServerId>vm-233</ServerId> <Weight>100</Weight> </BackendServer> <BackendServer> <ServerId>vm-234</ServerId> <Weight>90</Weight> </BackendServer> </BackendServers> </DescribeLoadBalancerAttributeResponse> Json Format 29

31 { "RequestId":"365F F6-4AE4-92F8-7FF34B540710", "LoadBalancerId":"139a00604ad-cn-east-hangzhou-01", "RegionId":"cn-east-hangzhou-01", "LoadBalancerName":"abc", "LoadBalancerStatus ":"active", "Address":" ", "AddressType":"internet", "InternetChargeType":"paybybandwidth", "Bandwidth":"5", "CreateTime":" :00:00", "ListenerPorts": { ListenerPort: [80,443]}, "BackendServers":{ BackendServer: [ {"ServerId": "vm-233", "Weight:100}, { ServerId": "vm-234", "Weight:90} ] }} DescribeRegions Description Query the information of accessible data centers. Request Parameters Name Request Required Description Action String Yes The name of the action. It is mandatory. Its value must be DescribeRegions. Response Elements Name Type Description <Common Response Elements > Please refer to Common Response Elements. Regions List A list of Regions. Regions Name Type Description RegionId String The ID of the region. Examples 30

32 Example Request &Action=DescribeRegions &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <DescribeRegionsResponse> <RequestId>1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6</RequestId> <Regions> <Region> <RegionId>cn-east-hangzhou-01</RegionId> </Region> <Region> <RegionId>cn-beijing</RegionId> </Region> </Regions> </DescribeRegionsResponse> Json Format { ]}} "RequestId":"1651FBB6-4FBF-49FF-A9F5-DF5D696C7EC6"}, "Regions":{ Region: [ {"RegionId":"cn-east-hangzhou-01"}, {"RegionId":"cn-beijing"} 5.2 Listener CreateLoadBalancerHTTPListener Description Create a HTTP protocol based Listener for SLB instance, including the HTTP protocol strategies and health status configurations. A newly created Listener is in the Stopped status. You should call CreateLoadBalancerHTTPListener to make it start. Please refer to SLB Listener Status Machine. Request Parameters 31

33 Name Reque Required Description st Action String Yes The name of the action. It is mandatory. Its value must be CreateLoadBalancerHTTPListener. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: BackendServerPort Integer Yes The port of SLS instance backend server. Optional values: Bandwidth Integer Yes The peak burst speed of the network. Optional values: Mbps For the paybybandwidth intances, the peak burst speed of all Listeners should not exceed the Bandwidth value in SLB instance creation, and the Bandwidth value must not be set to -1. For paybytraffic instances, this value can be set to -1, meaning there is no restriction on bandwidth peak speed. XForwardedFor String No Whether to get the real IP address of requests via X-Forwarded-For. Optional values: on off Default value: off Scheduler String No The scheduling algorithm. Optional values: wrr wlc Default value:wrr StickySession String Yes Whether to keep sessions alive. Optional values: on off StickySessionType String Conditional The processing method of cookie. If StickySession is on, this parameter is required. If StickySession is off, this parameter will be ignored. Optional values: insert server The value insert means to insert from SLB. The value server means to learn from SLB backend servers. CookieTimeout Integer Conditional Cookie timeout value. If StickySession is on and StickySessionType is insert, this parameter is required. In other cases, this parameter will be ignored. Optional values: (s) Cookie String Conditional The cookie configured by the server. If StickySession is on and StickySessionType is 32

34 server, this parameter is required. In other cases, this parameter will be ignored. Value: abide by RFC 2965, and its length is characters. It can only include ASCII English alphabets or numbers. Commons, semicolons and spaces are not allowed. And it cannot start with dollar sign( $ ). HealthCheck String Yes Whether to open health check. Optional values: on off HealthCheckDomain String Conditional The host name for health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Value: $_ip User custom string User Custom value: The length should be between 1 to 80 characters. The valid characters are numbers, alphabets, -, /,., _. If user set this parameter to $_ip, SLBwill use the intranet IP of backend servers as Domain for the health check. HealthCheckURI String Conditional The URI for health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Value: The length should be between 1 to 80 characters. The valid characters are numbers, alphabets, -, /,., _. It must start with /. HealthCheckConnect Port Integer Conditional The port number for health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: ,or If this parameter is -520, it represents using BackendServerPort. HealthyThreshold Integer Conditional The threshold to judge the health status to be healthy, i.e., the times of continuous successful checks. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values:1-10 UnhealthyThreshold Integer Conditional The threshold to judge the health status to be unhealthy, i.e., the times of continuous unsuccessful checks. 33

35 If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values:1-10 HealthCheckTimeout Integer Conditional The maximum response time of each health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-50(S) Note:if HealthCHeckTimeout < HealthCheckInterval, HCTimeout is invalid. The timeout is HealthCheckInterval. HealthCheckInterval Integer Conditional The time interval for health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-5(S) Response Elements All Response Elements are common Response Elements. Please refer to Common Response Elements. Examples Example Request &Action=CreateLoadBalancerHTTPListener &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=80 &BackendServerPort=80 &Bandwidth=-1 &HealthCheck=on &HealthCheckDomain=$_ip &HealthCheckURI=/test/index.html &HealthCheckConnectPort=8080 &HealthyThreshold=4 &UnhealthyThreshold=4 &HealthCheckTimeout=3 &HealthCheckInterval=5 &<Common Request Parameters > Example Response XML Format 34

36 <?xml version="1.0" encoding="utf-8"?> <CreateLoadBalancerHTTPListenerResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </CreateLoadBalancerHTTPListenerResponse> Json Format { } RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" CreateLoadBalancerTCPListener Description Create a TCP protocol based Listener for SLB instance, including the TCP protocol strategies and health status configurations. A newly created Listener is in the Stopped status. You should call CreateLoadBalancerHTTPListener to make it start. Please refer to SLB Listener Status Machine. The status of TCP Listener health check is always on. A user can set all parameters, but cannot close the health check. Request Parameters Name Request Require Description d Action String Yes The name of the action. It is mandatory. Its value must be CreateLoadBalancerTCPListener. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: BackendServerPort Integer Yes The port of SLS instance backend server. Optional values: Bandwidth Integer Yes The peak burst speed of the network. Optional values: Mbps For the paybybandwidth intances, the peak burst speed of all Listeners should not exceed the Bandwidth value in SLB instance creation, and the Bandwidth value must not be set to -1. For paybytraffic instances, this value can be set to -1, meaning there is no restriction on bandwidth 35

37 peak speed. Scheduler String No The scheduling algorithm. Optional values: wrr wlc Default value:wrr PersistenceTimeout Integer No The persistence connection timeout. HealthCheckConnect Integer Conditio The port number for health check. Port nal Optional values: Default value: none. If this parameter is not set, it represents using BackendServerPort. HealthyThreshold Integer Conditio The threshold to judge the health status to be nal healthy, i.e., the times of continuous successful checks. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-10 Default value: 3 UnhealthyThreshold Integer Conditio The threshold to judge the health status to be nal unhealthy, i.e., the times of continuous unsuccessful checks. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-10 Default value: 3 HealthCheckTimeout Integer Conditio The maximum response time of each health nal check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-50(S) Note:if HealthCHeckTimeout < HealthCheckInterval, HCTimeout is invalid. The timeout is HealthCheckInterval. HealthCheckInterval Integer Conditio The time interval for health check. nal Optional values: 1-5(S) Default value: 2 Response Elements All Response Elements are common Response Elements. Please refer to Common Response Elements. Examples 36

38 Example Request &Action=CreateLoadBalancerTCPListener &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=443 &BackendServerPort=443 &Bandwidth=-1 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <CreateLoadBalancerTCPListenerResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </CreateLoadBalancerTCPListenerResponse> Json Format { } RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" DeleteLoadBalancerListener Description Delete a LoadBalancer Listener corresponding to a ListenerPort. This action can only be taken when the status of the listener is stopped or running. Please refer to SLB Listener Status Machine. Request Parameters Name Value Required Description Action String Yes The name of the action. It is mandatory. Its value must be DeleteLoadBalancerTCPListener. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: Response Elements All Response Elements are common Response Elements. Please refer to Common Response Elements. 37

39 Examples Example Request &Action=DeleteLoadBalancerListener &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=80 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <DeleteLoadBalancerListenerResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </DeleteLoadBalancerListenerResponse> Json Format { } RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" StartLoadBalancerListener Description Start the specified Listener. After the action is called, the Listener will turn to starting status. This action can only be called when the Listener status is stopped. If the LoadBalancer which the Listener belongs to is in locked status, this action call will fail. Please refer to SLB Listener Status Machine. Request Parameters Name Value Required Description Action String Yes The name of the action. It is mandatory. Its value must be StartLoadBalancerListener. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: Response Elements All Response Elements are common Response Elements. Please refer to Common Response Elements. 38

40 Examples Example Request &Action= StartLoadBalancerListener &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=80 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <SetLoadBanancerListenerStatusResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </SetLoadBanancerListenerStatusResponse> Json Format { } RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" StopLoadBalancerListener Description Stop the specified Listener. After the action is called, the Listener will turn to stopped status. This action can only be called when the Listener status is running. If the LoadBalancer which the Listener belongs to is in locked status, this action call will fail. Please refer to SLB Listener Status Machine. Request Parameters Name Value Required Description Action String Yes The name of the action. It is mandatory. Its value must be StopLoadBalancerListener. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: Response Elements All Response Elements are common Response Elements. Please refer to Common Response 39

41 Elements. Examples Example Request &Action=StopLoadBalancerListener &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=80 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <SetLoadBanancerListenerStatusResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </SetLoadBanancerListenerStatusResponse> Json Format { } RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" SetLoadBalancerHTTPListenerAttribute Description Configure the HTTP Listener, including Scheduler, ticysession, HealthCheck, etc. Request Parameters Name Request Required Description Action String Yes The name of the action. It is mandatory. Its value must be SetLoadBalancerHTTPListenerAttribute. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: BackendServerPort Integer Yes The port of SLS instance backend server. Optional values: Bandwidth Integer Yes The peak burst speed of the network. Optional values: Mbps 40

42 For the paybybandwidth intances, the peak burst speed of all Listeners should not exceed the Bandwidth value in SLB instance creation, and the Bandwidth value must not be set to -1. For paybytraffic instances, this value can be set to -1, meaning there is no restriction on bandwidth peak speed. XForwardedFor String No Whether to get the real IP address of requests via X-Forwarded-For. Optional values: on off Default value: off Scheduler String No The scheduling algorithm. Optional values: wrr wlc Default value:wrr StickySession String Yes Whether to keep sessions alive. Optional values: on off StickySessionType String Conditional The processing method of cookie. If StickySession is on, this parameter is required. If StickySession is off, this parameter will be ignored. Optional values: insert server The value insert means to insert from SLB. The value server means to learn from SLB backend servers. CookieTimeout Integer Conditional Cookie timeout value. If StickySession is on and StickySessionType is insert, this parameter is required. In other cases, this parameter will be ignored. Optional values: (s) Cookie String Conditional The cookie configured by the server. If StickySession is on and StickySessionType is server, this parameter is required. In other cases, this parameter will be ignored. Value: abide by RFC 2965, and its length is characters. It can only include ASCII English alphabets or numbers. Commons, semicolons and spaces are not allowed. And it cannot start with dollar sign( $ ). HealthCheck String Yes Whether to open health check. Optional values: on off HealthCheckDomain String Conditional The host name for health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. 41

43 Value: $_ip User custom string User Custom value: The length should be between 1 to 80 characters. The valid characters are numbers, alphabets, -, /,., _. If user set this parameter to $_ip, SLBwill use the intranet IP of backend servers as Domain for the health check. HealthCheckURI String Conditional The URI for health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Value: The length should be between 1 to 80 characters. The valid characters are numbers, alphabets, -, /,., _. It must start with /. HealthCheckConnect Port Integer Conditional The port number for health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: ,or If this parameter is -520, it represents using BackendServerPort. HealthyThreshold Integer Conditional The threshold to judge the health status to be healthy, i.e., the times of continuous successful checks. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values:1-10 UnhealthyThreshold Integer Conditional The threshold to judge the health status to be unhealthy, i.e., the times of continuous unsuccessful checks. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values:1-10 HealthCheckTimeout Integer Conditional The maximum response time of each health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-50(S) Note:if HealthCHeckTimeout < HealthCheckInterval, HCTimeout is invalid. The timeout is HealthCheckInterval. 42

44 HealthCheckInterval Integer Conditional The time interval for health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-5(S) Response Elements All Response Elements are common Response Elements. Please refer to Common Response Elements. Examples Example Request &Action=SetLoadBalancerHTTPListenerAttribute &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=-520 &Bandwidth=-1 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <SetLoadBalancerHTTPListenerAttributeResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </SetLoadBalancerHTTPListenerAttributeResponse> Json Format { } RequestId":" CEF72CEB-54B6-4AE8-B225-F876FF7BA984" SetLoadBalancerTCPListenerAttribute Description Configure the TCP Listener, including Scheduler, HealthCheck, etc. Request Parameters Name Request Required Description Action String Yes The name of the action. It is mandatory. Its value must be 43

45 CreateLoadBalancerTCPListener. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: Bandwidth Integer Yes The peak burst speed of the network. Optional values: Mbps For the paybybandwidth intances, the peak burst speed of all Listeners should not exceed the Bandwidth value in SLB instance creation, and the Bandwidth value must not be set to -1. For paybytraffic instances, this value can be set to -1, meaning there is no restriction on bandwidth peak speed. Scheduler String No The scheduling algorithm. Optional values: wrr wlc Default value:wrr PersistenceTimeout Integer No The persistence connection timeout. HealthCheckConnect Port Integer Conditional The port number for health check. Optional values: Default value: none. If this parameter is not set, it represents using BackendServerPort. HealthyThreshold Integer Conditional The threshold to judge the health status to be healthy, i.e., the times of continuous successful checks. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-10 Default value: 3 UnhealthyThreshold Integer Conditional The threshold to judge the health status to be unhealthy, i.e., the times of continuous unsuccessful checks. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. Optional values: 1-10 Default value: 3 HealthCheckTimeout Integer Conditional The maximum response time of each health check. If HealthCheck is on, this parameter is required. If HealthCheck is off, this parameter will be ignored. 44

46 Optional values: 1-50(S) Note:if HealthCHeckTimeout < HealthCheckInterval, HCTimeout is invalid. The timeout is HealthCheckInterval. HealthCheckInterval Integer Conditional The time interval for health check. Optional values: 1-5(S) Default value: 2 Response Elements All Response Elements are common Response Elements. Please refer to Common Response Elements. Examples Example Request &Action=SetLoadBalancerTCPListenerAttribute &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=443 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <SetLoadBalancerTCPListenerAttributeResponse> <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId> </SetLoadBalancerTCPListenerAttributeResponse> Json Format { } "RequestId":"C0FD0EED-F90D D-DD E" DescribeLoadBalancerHTTPListenerAttribute Description Query the information of HTTP Listener. There are 5 Listener statuses: starting, running, configuring, stopping, stopped. As for the transformation between the statuses, and the detailed information of the statuses, please refer to SLB Listener Status Machine. Request Parameters 45

47 Name Value Required Description Action String Yes The name of the action. It is mandatory. Its value must be DescribeLoadBalancerHTTPListenerAttribute. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: Response Elements Name Request Description <Common Please refer to Common Response Elements. Response Elements> ListenerPort Integer The Listener port number used by the SLB instance frontend server. BackendServerPort Integer The Listener port number used by the SLB instance backend server. Bandwidth Integer The peak burst speed of the network. Status String The status of the Listener. There are 5 Listener statuses: starting, running, configuring, stopping, stopped. XForwardedFor String Whether to get the real IP address of requests via X-Forwarded-For. Optional values: on off Scheduler String The scheduling algorithm. Optional values: wrr wlc StickySession String Whether to keep sessions alive. Optional values: on off StickySessionType String The processing method of cookie. The value insert means to insert from SLB. The value server means to learn from SLB backend servers. CookieTimeout Integer Cookie timeout value. Cookie String The cookie configured by the server. It is only valid when Type is server. HealthCheck String Whether to open health check. Optional values: on off HealthCheckDomai String The host name for health check. n HealthCheckURI String The URI for health check. HealthyThreshold Integer The times of continuous successful checks to set the backend server status from fail to success. UnhealthyThreshol d Integer The times of continuous unsuccessful checks to set the backend server status from success to fail. 46

48 HealthCheckTimeo ut HealthCheckInterva l Integer Integer Aliyun SLB API Reference The maximum response time of each health check. The unit is second. The time interval for health check. The unit is second. Examples Example Request &Action=DescribeLoadBalancerHTTPListenerAttribute &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=80 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <DescribeLoadBalancerHTTPListenerAttributeResponse> <RequestId>365F F6-4AE4-92F8-7FF34B540710</RequestId> <ListenerPort>80</ListenerPort> <BackendServerPort>80</BackendServerPort> <Bandwidth>-1</Bandwidth> <Status>stopped</Status> <Schedule>wrr</Schedule> <XForwardedFor>on</XForwardedFor> </DescribeLoadBalancerHTTPListenerAttributeResponse> Json Format { } "RequestId":"365F F6-4AE4-92F8-7FF34B540710", "ListenerPort":80, "BackendServerPort":80, "Bandwidth":-1, "Status":"stopped", "Schedule":"wrr", "XForwardedFor":"on" DescribeLoadBalancerTCPListenerAttribute Description 47

49 Query the information of TCP Listener. There are 5 Listener statuses: starting, running, configuring, stopping, stopped. As for the transformation between the statuses, and the detailed information of the statuses, please refer to SLB Listener Status Machine. Request Parameters Name Value Required Description Action String Yes The name of the action. It is mandatory. Its value must be DescribeLoadBalancerTCPListenerAttribute. LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance. Optional values: Response Elements Name Request Description <Common Response Please refer to common Response Elements. Elements> ListenerPort Integer The port number used by the SLB instance frontend server. Optional values: BackendServerPort Integer The port number of SLS instance backend server. Optional values: Bandwidth Integer The peak burst speed of the network. Optional values: Mbps Status String The status of the Listener. There are 5 Listener statuses: starting, running, configuring, stopping, stopped. Scheduler String The scheduling algorithm. Optional values: wrr wlc PersistenceTimeout Integer The persistence connection timeout. 0 represents closed. HealthCheck String Whether to open the health check. Option values: on off. HealthyThreshold Integer The times of continuous successful checks to set the backend server status from fail to success. UnhealthyThreshold Integer The times of continuous unsuccessful checks to set the backend server status from success to fail. HealthCheckConnect Integer The port number for health check. Port HealthCheckTimeout Integer The maximum response time of each health check. HealthCheckInterval Integer The time interval for health check. The unit is second. Examples Example Request 48

50 &Action=DescribeLoadBalancerTCPListenerAttribute &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=80 &<Common Request Parameters > Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <DescribeLoadBalancerTCPListenerAttributeResponse> <RequestId>365F F6-4AE4-92F8-7FF34B540710</RequestId> <ListenerPort>443</ListenerPort> <BackendServerPort>443</BackendServerPort> <Bandwidth>-1</Bandwidth> <Status>stopped</Status> <Schedule>wrr</Schedule> <StickySession>on</StickySession> <PersistenceTimeout>0</PersistenceTimeout> </DescribeLoadBalancerTCPListenerAttributeResponse> Json Format { } "RequestId":"365F F6-4AE4-92F8-7FF34B540710", "ListenerPort":443, "BackendServerPort":443, "Bandwidth":-1, "Status":"stopped", "Schedule":"wrr", "StickySession":"on", "PersistenceTimeout":0 5.3 BackendServer AddBackendServers Description Add a group of backend servers (ECS instances) to a SLB instance, returning the backend server list. 49

51 Note: If this SLB server has already had a group of ECS instances, this action will be ignored. If you add some identical ECS instances in one request, only the first one will be added successfully, and the other instances will be ignored. Request Parameters Name Value Required Description Action String Yes The name of the action. It is mandatory. Its value must be AddBackendServers. LoadBalanerId String Yes The unique identification of a SLB instance. BackendServers String Yes The backend server list to be added. Value: a Json string. Its structure is a list. In one request, the maximum size of the list is 20. The structure of a list element is as follows. BackendServers Name Type Description ServerId String The ID of backend server. (The id of an ECS instance.) Weight Integer The weight of backend server. Option values: Default value: 100 Response Elements Name Request Description <Common Response Please refer to Common Response Elements. Elements> LoadBalancerId String The unique identification of SLB instance. BackendServers List A list of the information of the SLB instance s backend servers. BackendServers Name Type Description ServerId String The ID of backend server. (The id of an ECS instance.) Weight Integer The weight of backend server. Option values: Default value: 100 Examples Example Request &Action=AddBackendServers &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &BackendServers=[{"ServerId":"vm-233","Weight":"100"},{"ServerId":"vm-234","Weight" :"100"}] &<Common Request Parameters > 50

52 Example Response XML Format <?xml version="1.0" encoding="utf-8"?> <AddBackendServersResponse> <RequestId>365F F6-4AE4-92F8-7FF34B540710</RequestId> <LoadBalancerId>139a00604ad-cn-east-hangzhou-01</LoadBalancerId> <BackendServers> <BackendServer> <ServerId>vm-233</ServerId> <Weight>100</Weight> </BackendServer> <BackendServer> <ServerId>vm-234</ServerId> <Weight>100</Weight> </BackendServer> </BackendServers> </AddBackendServersResponse> Json Format { } "RequestId":"365F F6-4AE4-92F8-7FF34B540710", "LoadBalancerId":"139a00604ad-cn-east-hangzhou-01", "BackendServers":{ BackendServer : [ {"ServerId":"vm-233", "Weight":100}, {"ServerId":"vm-234", "Weight":100}] } RemoveBackendServers Description Delete a group of backend servers from a SLB instance, returning the backend server list. Note: If some of the BackendServers in the list does not belong to the SLB instance, this action will be ignored. Request Parameters Name Value Required Description 51

53 Action String Yes The name of the action. It is mandatory. Its value must be RemoveBackendServers. LoadBalanerId String Yes The unique identification of a SLB instance. BackendServers String Yes The backend server list to be removed. Value: a Json string. Its structure is a list. In one request, the maximum size of the list is 20. Response Elements Name Request Description <Common Response Please refer to Common Response Elements. Elements> LoadBalancerId String The unique identification of SLB instance. BackendServers List A list of the information of the SLB instance s backend servers. BackendServers Name Type Description ServerId String The ID of backend server. (The id of an ECS instance.) Weight Integer The weight of backend server. Option values: Default value: 100 Examples Example Request &Action=RemoveBackendServers &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &BackendServers=[" vm-233"," vm-234"] &<Common Request Parameters > Example Response XML Format 52

54 <?xml version="1.0" encoding="utf-8"?> <RemoveBackendServersResponse> <RequestId>365F F6-4AE4-92F8-7FF34B540710</RequestId> <LoadBalancerId>139a00604ad-cn-east-hangzhou-01</LoadBalancerId> <BackendServers> <BackendServer> <ServerId>vm-231</ServerId> <Weight>100</Weight> </BackendServer> <BackendServer> <ServerId>vm-232</ServerId> <Weight>100</Weight> </BackendServer> </BackendServers> </RemoveBackendServersResponse> Json Format { } "RequestId":"365F F6-4AE4-92F8-7FF34B540710", "LoadBalancerId":"139a00604ad-cn-east-hangzhou-01", "BackendServers":{ BackendServer : [ {"ServerId":"vm-231", "Weight":100}, {"ServerId":"vm-232", "Weight":100}] } DescribeHealthStatus Description Do health check to the backend servers of the SLB instance, returning the health status of the instances. There are 3 kind of health status: normal, abnormal and unavailable. Unavailable means that the SLB instance is not configured with health check, therefore its health status cannot be acquired. Request Parameters Name Type Required Description Action String Yes The name of the action. It is mandatory. Its value must be DescribeHealthStatus. 53

55 LoadBalanerId String Yes The unique identification of a SLB instance. ListenerPort Integer Yes The Listener port number used by the SLB instance frontend. Optional values: Default value: none Not setting this parameter means to acquire the health status of all ports. Response Elements Name Request Description <Common Response Please refer to Common Response Elements. Elements> BackendServers List A list of the information of the SLB instance s backend servers. BackendServers Name Type Description ServerId String The ID of backend server. (The id of an ECS instance.) ServerHealthStatus Integer The health status of backend servers. The status normal means healthy. The status abnormal means unhealthy. The status unavailable means the health check is not completed. The possible reasons are: the health check is not open, or the health check is not successfully triggered due to some trouble. As for the latter condition, please contact us to confirm the reason. Examples Example Request &Action=DescribeHealthStatus &LoadBalancerId=139a00604ad-cn-east-hangzhou-01 &ListenerPort=80 &<Common Request Parameters > Example Response XML Format 54

56 <?xml version="1.0" encoding="utf-8"?> <DescribeBackendServersResponse> <RequestId>365F F6-4AE4-92F8-7FF34B540710</RequestId> <BackendServers> <BackendServer> <ServerId>vm-233</ServerId> <ServerHealthStatus>normal</ServerHealthStatus> </BackendServer> <BackendServer> <ServerId>vm-234</ServerId> <ServerHealthStatus>abnormal</ServerHealthStatus> </BackendServer> </BackendServers> </DescribeBackendServersResponse> Json Format { } "RequestId":"365F F6-4AE4-92F8-7FF34B540710", "LoadBalancerId":"139a00604ad-cn-east-hangzhou-01", "BackendServers":{ BackendServer : [ {"ServerId": "vm-233", "ServerHealthStatus:"normal"}, { ServerId": "vm-234", "ServerHealthStatus:"abnormal"}] } 6 Appendix 6.1 Error Code Table Client Side Errors Error Code Description HTTP Status Code SignatureDoesNotMatch The signature we calculated does not match 400 the one you provided. Please refer to the API reference about authentication for details. UnsupportedOperation The specified action is not supported

57 MissingParameter The input parameter <parameter name> 400 that is mandatory for processing the request is not supplied. InvalidParameter The specified parameter <parameter name> 400 is not valid. Throttling Request was denied due to request throttling. 400 InvalidAccessKeyId.NotFound The Access Key ID provided does not exist in 404 our records. Forbidden User not authorized to operate on the 403 specified resource. InvalidRegionId.NotFound Specified region does not exist. 400 InvalidLoadBalancerId.Malformed LoadBalancerId is Invalid. 400 InvalidLoadBalancerId.NotFound LoadBalancerId does not exist. 404 NoAvailableAddress No more available address to allocate. 400 IdempotentParameterMismatch Request uses a client token in a previous 400 request but is not identical to that request. BackendServerPort.Malformed Specified backend server port is not valid. 400 ListenerAlreadyExists There is already a listener bound to the port 400 on the specified load balancer. ListenerPotocolMismatch The listener protocol on the specified port 400 does not match. TooManyBackendServers The backend server parameter has too many 400 entries. InvalidServerId.Malformed A specified server ID is not valid. 400 InvalidWeight.Malformed A specified weight is not valid. 400 BackendServerInOtherRegion The backend server in other region. 400 InvalidServerId.NotFound The specified server is not found Server Side Errors Error Code Description HTTP Status Code InternalError The request processing has failed due 500 to some unknown error, exception or failure. ServiceUnavailable The request has failed due to a temporary failure of the server

58 6.2 SLB Listener Status Machine The Listener has 5 possible status: starting running configuring stopping stopped. When an SLB Listener is just created, its status is stopped. After taking the action StartLoadBalancerListener, the Listener status is starting. At this time you cannot modify the Listener via API. When the service has successfully started, the Listener status is running. At this time you can modify the Listener via API. After taking the action StopLoadBalancerListener, the Listener status is stopping. After the service has successfully stopped, the Listener status is stopped. 6.3 How to Follow the Law of Idempotence When the client calls the interface to create SLB instance, 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 the system only create one instance. 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. 57

59 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 a retry operation cannot succeed. 6.4 Update History API Version: Latest Update Time: Publish Update Time The first subversion of version is published. Description Compared with version : (1) Broke up the hidden function of CreateLoadBalancer and turn it into an open interface. (2) Generized the format of parameter description. (3) Added the content about RAM. (4) Added the content about Listener status transtormation. 58