353      阿里云

如何调用接口__附录_API 参考_云服务器 ECS-阿里云

对ECS服务接口的调用是通过向ECS服务端发送HTTP请求（可以通过HTTP或HTTPS协议发送），并获取ECS服务对该请求响应结果的过程。ECS服务端在接收到用户请求后，对请求做必要的身份验证和参数验证，在所有验证成功后根据请求的指定参数提交并完成相应操作，并把处理的结果以HTTP响应的形式返回给调用者。

请求组成

请求由以下几个部分组成：

HTTP方法——目前ECS服务的所有接口只支持GET方法的调用。

请求URL——请求的服务地址、要执行的操作名称、操作参数和公共请求参数都包含在请求的URL中。

服务端地址：ECS服务的域名是https://ecs.aliyuncs.com/和https://ecs.aliyuncs.com/。为了保证请求的安全性，强烈推荐您使用HTTPS通道。 （HTTPS加入了SSL层对通信进行了加密，可以防止通信被截获而导致敏感信息泄露。）

操作名称：每个接口都需要指定要执行的操作名称，即Action参数。

操作参数：根据要执行的操作不同，需要传入不同的操作参数，详见每个接口的说明。

公共请求参数：包含时间戳、签名信息等每个请求都要包含的参数。

为了使服务端能够正确地验证用户的身份并授权请求执行，请求在提交前要进行签名处理。签名的规则参见签名机制一节。

在服务端对请求处理完成后，会返回响应结果。响应结果分为成功结果和错误消息，格式描述参见返回结果一节。客户端可以解析响应的消息体，得到执行结果。

调用示例

以DescribeRegions接口为例：

对应的Action是DescribeRegions，该接口用于查询可用地域列表， 因为该接口没有自定义的参数，所以只需要添加公共请求参数（除了Signature, 该参数需要后面通过签名算法计算出来）。添加了参数之后，请求的URL是（为了便于阅读，这里展示的是进行URL编码前的URL）：

https://ecs.aliyuncs.com/?TimeStamp=2016-02-23T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&SignatureVersion=1.0

按照签名计算规则，先构造出规范化请求字符串（Canonicalized Query String），如下：

AccessKeyId=testid&Action=DescribeRegions&Format=XML&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion=1.0&TimeStamp=2016-02-23T12%3A46%3A24Z&Version=2014-05-26

再构造出用于签名的字符串StringToSign值为：

GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeRegions%26Format%3DXML%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf%26SignatureVersion%3D1.0%26TimeStamp%3D2016-02-23T12%253A46%253A24Z%26Version%3D2014-05-26

以下Java示例代码演示了如何添加公共请求参数、如何构造用请求参数构造规范化请求字符串，以及如何构造StringToSign字符串。示例假定所有请求参数放在一个Map<String, String>对象里，使用的Access Key ID是“testid”。

    final String HTTP_METHOD = "GET";

    Map<String, String> parameters = new HashMap<String, String>();
    // 加入请求参数
    parameters.put("Action", "DescribeRegions");
    parameters.put("Version", "2014-05-26");
    parameters.put("AccessKeyId", "testid");
    parameters.put("TimeStamp", formatIso8601Date(new Date()));
    parameters.put("SignatureMethod", "HMAC-SHA1");
    parameters.put("SignatureVersion", "1.0");
    parameters.put("SignatureNonce", UUID.randomUUID().toString());
    parameters.put("Format", "XML");

    // 对参数进行排序
    String[] sortedKeys = parameters.keySet().toArray(new String[]{});
    Arrays.sort(sortedKeys);

    final String SEPARATOR = "&";

    // 生成stringToSign字符串
    StringBuilder stringToSign = new StringBuilder();
    stringToSign.append(HTTP_METHOD).append(SEPARATOR);
    stringToSign.append(percentEncode("/")).append(SEPARATOR);

    StringBuilder canonicalizedQueryString = new StringBuilder();
    for(String key : sortedKeys) {
        // 这里注意对key和value进行编码
        canonicalizedQueryString.append("&")
        .append(percentEncode(key)).append("=")
        .append(percentEncode(parameters.get(key)));
    }

    // 这里注意对canonicalizedQueryString进行编码
    stringToSign.append(percentEncode(
        canonicalizedQueryString.toString().substring(1)));

其中需要注意的是，TimeStamp参数要求符合ISO8601规范，并注意使用UTC时间，否则会遇到错误。下面的示例代码演示了如何生成符合规范的TimeStamp字符串：

    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);
    }

生成规范化请求字符串（示例中的canonicalizedQueryString变量），以及SringToSign时，都需要进行必要的编码。编码的规则在签名机制一节中有详细描述。下面的示例代码演示了编码的算法：

    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;
    }

假设使用的Access Key Id是“testid”， Access Key Secret是“testsecret”，用于计算HMAC的Key就是“testsecret&”，最终计算得到的签名值为：

    CT9X0VtwR86fNWSnsc6v8YGOjuE=

计算签名的示例代码（Java）：

    // 以下是一段计算签名的示例代码
    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));

增加签名参数后，请按照RFC3986规则进行URL编码后得到的

https://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureMethod=HMAC-SHA1&TimeStamp=2016-02-23T12%3A46%3A24Z

接下来，通过HTTP请求的方式向上面的URL地址发送HTTP请求，并得到ECS服务端的响应结果（示例）：

<DescribeRegionsResponse>
    <Regions>
        <Region>
            <LocalName>青岛节点</LocalName>
            <RegionId>cn-qingdao</RegionId>
        </Region>
        <Region>
            <LocalName>杭州节点</LocalName>
            <RegionId>cn-hangzhou</RegionId>
        </Region>
    </Regions>
    <RequestId>833C6B2C-E309-45D4-A5C3-03A7A7A48ACF</RequestId>
</DescribeRegionsResponse>

通过解析这个XML结果即可以得到所有可用的地域Id和LocalName的列表。如果在提交请求时，指定Format参数为JSON，那么返回结果的格式为JSON格式。

最后更新：2016-11-23 16:03:51

  上一篇： 磁盘种类表__附录_API 参考_云服务器 ECS-阿里云

  下一篇： 如何保证幂等性__附录_API 参考_云服务器 ECS-阿里云