本文介绍了错误码和调用接口的说明示例。

错误代码表

客户端错误
ErrorCode错误代码 Message错误信息 HTTP状态码
OperationDenied Your account does not open SCDN service yet. 403
InsufficientBalance Your account does not have enough balance. 400
Forbidden.NotVerified Your account is not verified yet. 403
UnsupportedOperation The specified action is not supported. 400
NoSuchVersion The specified version does not exist. 400
UnsupportedParameter The parameter <parameter name> is not supported. 400
MissingParameter The input parameter <parameter name> that is mandatory for processing this request is not supplied. 400
InvalidParameter The specified parameter <parameter name> is not valid.Or The specified image does not support the specified instance type. 400
Throttling Request was denied due to request throttling. 400
InvalidAccessKeyId.NotFound The Access Key ID provided does not exist in our records. 404
Forbidden User not authorized to operate on the specified resource. 403
Forbidden.RiskControl This operation is forbidden by Aliyun Risk Control system. 403
Forbidden.AccessTooManyOthersResource This operator is forbidden because too many other one’s resource to be accessed. 403
SignatureDoesNotMatch The signature we calculated does not match the one you provided. Please refer to the API reference about authentication for details. 403
SignatureNonceUsed The request signature nonce has been used. 400
IdempotentParameterMismatch Request uses a client token in a previous request but is not identical to that request. 400
ChargeTypeViolation Operations on this kind of resources are not permitted. 403
InsufficientBalance Your account does not have enough balance. 400
QuotaExceeded Living instances quota exceeded. 400
OperationDenied Specified operation is denied as your resource is locked for security reasons. 403
RiskControl.Refused Your action was.refused by RiskControl. 400
QuotaExceeded.Snapshot Snapshot quota exceeded. 400
QuotaExceeded.Image Image quota exceeded. 400
服务器端错误
错误代码 错误信息 HTTP状态码
InternalError The request processing has failed due to some unknown error, exception or failure. 500
ServiceUnAvailable The request has failed due to a temporary failure of the server. 503

如何调用接口

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

请求组成

请求由以下几个部分组成:
  • HTTP方法——目前SCDN服务的所有接口只支持GET方法的调用。
  • 请求URL——请求的服务地址、要执行的操作名称、操作参数和公共请求参数都包含在请求的URL中。
  • 服务端地址:SCDN服务的域名是http://scdn.aliyuncs.com/https://scdn.aliyuncs.com/。为了保证请求的安全性,强烈推荐您使用HTTPS通道。 (HTTPS加入了SSL层对通信进行了加密,可以防止通信被截获而导致敏感信息泄露。)
  • 操作名称:每个接口都需要指定要执行的操作名称,即Action参数。
  • 操作参数:根据要执行的操作不同,需要传入不同的操作参数,详见每个接口的说明。
  • 公共请求参数:包含时间戳、签名信息等每个请求都要包含的参数。

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

在服务端对请求处理完成后,会返回响应结果。响应结果分为成功结果和错误消息,格式描述参见JSON返回示例:
{
    "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行为

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

账户欠费时

接口 行为
OpenScdnService 正常