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-阿裏雲