CDN加速

调用方式

更新时间:2021-08-31 11:00:17

目录

请求结构

客户调用网宿科技的openAPI接口,是通过向指定服务地址发送请求,并需满足网宿科技签名信息和具体接口的业务信息来完成的。网宿科技的openAPI的请求结构组织如下:

服务地址

网宿科技的openAPI的通用服务接入地址为:api.elive.wangsu.com

通信协议

支持通过 HTTP 或 HTTPS 两种方式进行请求通信,推荐使用安全性更高的 HTTPS方式发送请求。

请求方法

请求方法详见各个接口具体的需求。在网宿科技中的openAPI大多数支持Get或Post请求。

注意:
1.Get与Post请求都支持将公共信息放置在header中的模式。
2.Get请求还支持将公共信息放置在query string中的模式。

请求参数

网宿科技的openAPI请求包含两类参数:公共请求参数和接口请求参数。其中,公共请求参数是每一个接口需要包含的,具体可参见公共参数小节。接口请求参数是各个接口特有的,详见各个接口描述。

字符编码

请求及返回结果使用UTF-8的字符集进行编码。

公共参数

公共请求参数是每个接口都需要使用的请求参数,开发者每次使用网宿科技API发送请求时都需要携带这些公共请求参数,否则会导致请求失败。公共请求参数首字母均为大写,以此区分接口请求参数。

公共参数如下表

Action&Version

Action和Version必须放在query当中

名称 类型 是否必填 参数格式 描述
Action String [a-zA-Z]+ 接口的名字,与具体的接口相关。
Version String YYYY-MM-DD 接口的版本信息
X-Expires Int 300 签名的有效时间,单位秒,默认不填是900秒

签名参数

签名参数是请求必不可少的部分,既可以在query当中,又可以在header当中。

在Header中的场景

名称 类型 是否必填 描述
X-Date String 20201103T104027Z, 使用UTC时间,精确到秒
Authorization String HMAC-SHA256 Credential={AccessKey}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}

Authorization中的信息含义

名称 类型 备注
AccessKey String 请求的AK
ShortDate String 请求的短时间,精确到日。使用UTC时间,例如:20180201
Region String 请求的Region,例如:cn-north-1
Service String 请求的服务,例如:iam
SignedHeaders String 参与签名的Header,用分号分隔
Signature String 计算完毕的签名。签名计算方式见签名办法

在Query中的场景
X-Date与Authorization的信息可以直接存在在Query当中

名称 类型 是否必填 描述
X-Date String 20201103T104027Z, 使用UTC时间,精确到秒
X-Algorithm String 固定值, HMAC-SHA256;为将来扩展做准备
X-Credential String 由{AccessKey}/{ShortDate}/{Region}/{Service}/request组成。
X-SignedHeaders String 参与签名的Header,用分号分隔
X-Signature String 计算完毕的签名。签名计算方式见签名办法

返回结果

调用成功

调用成功时,返回业务的Result,包括请求的业务相关数据。
示例:

{
    "ResponseMetadata": {
        "RequestId": "201806041104200100100232280022D30",
        "Action": "CreateAccessKey",
        "Version": "2018-01-01",
        "Service": "iam",
        "Region": "cn-langfang-1"
    },
    "Result":{
        "AccessKey": {
            "AccessKeyId": "AKIAIYVIC525SYQ3W45A",
            "CreateDate": "20180614T131357Z"
            "SecretAccessKey": "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",
            "Status": "active",
            "UserName": "Alice"
            }
  	}
}

调用失败

调用失败时,返回Error,包括错误码和错误信息,可据此定位错误原因。
示例:

{
    "ResponseMetadata": {
        "RequestId": "201806041104200100100232280022D30",
        "Action": "CreateAccessKey",
        "Version": "2018-01-01",
        "Service": "iam",
        "Region": "cn-langfang-1",
        "Error": {
            "Code": "NoSuchEntity",
            "Message": "The user with name Alice2 cannot be found."
        }
    }
}

签名机制

创建一个正规化请求

Hash代指SHA256算法
HexEncode代指转16进制编码

CanonicalRequest = HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload))

在签名之前,首先要将请求正规化,目的是让签名计算过程无异议,其主要过程及伪代码如下:

HTTPRequestMethod:
指代http请求的method,例如:GET、POST等。

CanonicalURI:
指代正规化后的URI。如果URI为空,那么使用"/“作为绝对路径。在网宿科技中绝大多数接口的URI都为”/"。

CanonicalQueryString:
指代正规化后的Query String。对于Query String的正规化大致的过程如下:
• URI编码每一个querystring参数名称和参数值。
• 按照ASCII网宿顺序对参数名称严格排序。
• 将排序好的参数名称和参数值用=连接,按照排序结果将“参数对”用&连接。
• 例如:

CanonicalQueryString = "Action=ListUsers&Version=2018-01-01"

CanonicalHeaders:
指代正规化后的Header。其中伪代码如下:

CanonicalHeaders = CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + ... + CanonicalHeadersEntryN

其中

CanonicalHeadersEntry = Lowercase(HeaderName) + ':' + Trimall(HeaderValue) + '\n'

Lowcase代表将Header的名称全部转化成小写,Trimall表示去掉Header的值的前后多余的空格。

特别注意:最后需要添加"\n"的换行符。

SignedHeaders:

代指参与签名的header名称。签名header是包含在正规化headers中名称列表,其目的是指明哪些header参与签名计算,从而忽略请求被proxy添加的额外header,其中host、x-date两个header如果存在则必须添加进来,伪代码如下:

SignedHeaders = Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ";" + ... + Lowercase(HeaderNameN)

RequestPayload:
指代完整的请求的body。

  • URI编码(注:同RFC3986方法)每一个querystring参数名称和参数值(注:GET方式需要包含哈希算法、信任状、签名日期和签名header等全部参数)。
  • 按照ASCII网宿顺序对参数名称严格排序。
  • 将排序好的参数名称和参数值用=连接,按照排序结果将“参数对”用&连接。

创建签名字符串

签名字符串主要包含请求以及正规化请求的元数据信息,由签名算法、请求日期、信任状和正规化请求哈希值连接组成,伪代码如下:

StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest))

Algorithm
指代签名的算法,目前网宿科技仅支持HMAC-SHA256的签名算法。

RequestDate
指代请求UTC时间,请使用如下格式:YYYYMMDD’T’HHMMSS’Z’ 。

CredentialScope
指代信任状,格式为:AccessKeyId/YYYYMMDD/region/service/request。

CanonicalRequest
指代上一小节正规化请求的结果。

计算签名秘钥(signing-key)

在计算签名前,首先从私有访问密钥(secret AccessKey)派生出签名密钥(signing key),而不是直接使用私有访问密钥。具体计算过程如下:

kSecret = *Your Secret Access Key*
kDate = HMAC(kSecret, Date)
kRegion = HMAC(kDate, Region)
kService = HMAC(kRegion, Service)
kSigning = HMAC(kService, "request")

计算签名

Signature = HexEncode(HMAC(kSigning, StringToSign))

然后构建header

Authorization: HMAC-SHA256 Credential={CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}

表达式中用{}括起来的代表上文计算出的中间过程。