附录

错误代码表

如何调用接口

对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行为

下列表中“-”表示无关，“正常逻辑”表示按照接口的正常逻辑执行并返回结果。

账户欠费时