錯誤代碼表

如何調用接口

對SCDN服務接口的調用是通過向SCDN服務端發送HTTP請求（可以通過HTTP或HTTPS通道發送），并獲取SCDN服務對該請求響應結果的過程。SCDN服務端在接收到用戶請求后，對請求做必要的身份驗證和參數驗證，在所有驗證成功后根據請求的指定參數提交或完成相應操作，并把處理的結果以HTTP響應地形式返回給調用者。

請求組成

為了使服務端能夠正確地驗證用戶的身份并授權請求執行，請求在提交前要進行簽名處理。簽名的規則參見簽名機制一節。

{
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
    /* 返回結果數據 */
}

返回結果：客戶端可以解析響應的消息體，得到執行結果。

調用示例

以DescribeScdnService接口為例：

對應的Action是DescribeScdnService。在添加了所有公共請求參數（除Signature）后，請求的URL是（為了便于閱讀，這里是進行URL編碼前的URL）：

http://scdn.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&AccessKeyId=testid&Action= DescribeScdnService &SignatureMethod=HMAC-SHA1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2013-01-10&SignatureVersion=1.0

按照簽名計算規則，先構造出規范化請求字符串（Canonicalized Query String），如下：

http://scdn.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&AccessKeyId=testid&Action= DescribeScdnService &SignatureMethod=HMAC-SHA1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2013-01-10&SignatureVersion=1.0

再構造出用于簽名的字符串StringToSign值為：

GET&%2F&AccessKeyId%3Dtestid&Action% DescribeScdnService &Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3DNwDAxvLU6tFE0DVb&SignatureVersion%3D1.0&TimeStamp%3D2012-12-26T10%253A33%253A56Z&Version%3D2013-01-10

以下Java示例代碼演示了如何添加公共請求參數、如何構造用請求參數構造規范化請求字符串，以及如何構造StringToSign字符串。示例假定所有請求參數放在一個Map <String, String>對象里，使用的Access Key ID是“testid”。

final String HTTP_METHOD = "GET";
……………………………………

其中需要注意的是，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變量），以及stringToSign時，都需要進行必要的編碼。編碼的規則在簽名機制一節中有詳細描述。下面的示例代碼演示了如何用java.net.URLEncoder類完成編碼：

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&”，最終計算得到的簽名值為：

SDFQNvyH5rtkc9T5Fwo8DOjw5hc=

計算簽名的示例代碼（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編碼后得到的

http://scdn.aliyuncs.com/?TimeStamp=2012-12-26T10%3A33%3A56Z&Format=XML&AccessKeyId=testid&Action= DescribeScdnService &SignatureMethod=HMAC-SHA1&RegionId=region1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2012-09-13&SignatureVersion=1.0&Signature=SDFQNvyH5rtkc9T5Fwo8DOjw5hc%3d

接下來，通過HTTP請求的方式向上面的URL地址發送HTTP請求，并得到SCDN服務端的響應結果（示例）：

none

通過解析這個XML結果即可以得到所有可用的地域ID和LocalName的列表。如果在提交請求時，指定Format參數為JSON，那么返回結果的格式為JSON格式。

如何保證冪等性

當通過調用創建實例接口在SCDN中創建云服務器時，如果遇到了請求超時或服務器內部錯誤時，客戶端可能會嘗試重發請求，這時客戶端可以通過提供可選參數ClientToken避免服務器創建出比預期要多的實例，也就是通過提供ClientToken參數保證請求的冪等性。ClientToken是一個由客戶端生成的唯一的、大小寫敏感、不超過64個ASCII字符的字符串。

如果用戶使用同一個ClientToken值調用創建實例接口，則服務端會返回相同的請求結果，包含相同的InstanceId。因此用戶在遇到錯誤進行重試的時候，可以通過提供相同的ClientToken值，來確保SCDN只創建一個實例，并得到這個實例的InstanceId。

如果用戶提供了一個已經使用過的ClientToken，但其他請求參數不同，則SCDN會返回IdempotentParameterMismatch的錯誤代碼。但需要注意的是，SignatureNonce、Timestamp和Signature參數在重試時是需要變化的，因為scdn使用SignatureNonce來防止重放攻擊，使用Timestamp來標記每次請求時間，所以再次請求必須提供不同的SignatureNonce和Timestamp參數值，這同時也會導致Signature值的變化。

通常客戶端只需要在500（InternetError）或503（ServiceUnAvailable）錯誤、或者無法得到響應結果的情況下進行重試操作。返回結果是200時，重試可以得到上次相同的結果，但不會對服務端狀態帶來任何影響。而對4xx的返回錯誤，除非提示信息里明確出現“try it later”，通常重試也是不能成功的。

欠費狀態下的API行為

下列表中“-”表示無關，“正常邏輯”表示按照接口的正常邏輯執行并返回結果。

賬戶欠費時