调用方式

• 请求结构

• 公共参数

• 返回结果

• 签名机制

请求结构

客户调用金山云金睛服务的openAPI接口是通过向指定服务地址发送请求，并按照openAPI文档说明在请求中添加相应的公共参数和接口参数来完成的。

金睛openAPI的请求结构组成如下：

服务地址

金睛的服务线上正式接入地址为：2016-10-18

通信协议

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

请求参数

金山云openAPI请求包含两类参数：公共请求参数和接口请求参数。其中，公共请求参数是每个接口都要用到的请求参数,请参考公共参数；接口请求参数是各个接口所特有的，如下表：

请求示例

GET http(s)://vcs[.cn-beijing-6].api.ksyun.com?UniqueName=xxx
Header x-action: ListApps
Header x-version: 2016-10-18
Header Content-Type: application/x-www-form-urlencoded
Header Host: vcs[.cn-beijing-6].api.ksyun.com
Header X-Amz-Date: 20161108T061800Z
Header Authorization: AWS4-HMAC-SHA256 Credential=AKLTfxbIWWr6S2KYWU19JuUOvQ/20161108/cn-beijing-1/vcs/aws4_request, SignedHeaders=content-type;host;x-action;x-amz-date;x-version, Signature=dffa0859631b3a104752eab015883b14c2dff6f8c3c4d9fde22a282632a8397a

字符编码

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

公共参数

• 参数说明

公共请求参数是每个OpenAPI调用都需要使用到的请求参数，包括API描述参数及权限验证参数。

接口参数请参考API概览

• 参数命名

当参数放在GET请求的URL中时，参数采用大驼峰命名法，每一个单字的首字母都采用大写字母；也可以通过Header方式传递。

• 示例

GET http(s)://vcs[.region].api.ksyun.com/?
Action=ListUniqueNames&Version=2016-10-18
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKLTGo0pHK-EQWiDZWTSBSll2Q%2F20160914%2Fcn-beijing-6%2Fiam%2Faws4_request
&X-Amz-Date=20160914T114902Z
&X-Amz-SignedHeaders=host
&X-Amz-Signature=88f6284257863dedfc350da05d19d07f76cca622e93b829f5ce26c1a75d3da39
&接口参数

GET http(s)://vcs[.cn-beijing-6].api.ksyun.com
Header x-action: ListUniqueNames
Header x-version: 2016-10-18
Header Content-Type: application/x-www-form-urlencoded
Header Host: vcs.cn-beijing-1.api.ksyun.com
Header X-Amz-Date: 20161108T061800Z
Header Authorization: AWS4-HMAC-SHA256 Credential=AKLTfxbIWWr6S2KYWU19JuUOvQ/20161108/cn-beijing-1/vcs/aws4_request, SignedHeaders=content-type;host;x-action;x-amz-date;x-version, Signature=dffa0859631b3a104752eab015883b14c2dff6f8c3c4d9fde22a282632a8397a

返回结果

调用金山云的openAPI服务，调用成功，返回的HTTP状态码（Status）为200；调用失败，返回4xx 或5xx的HTTP状态码（Status）。

金睛API基于金山云的OpenAPI服务，目前仅支持json格式。

调用失败

返回的HTTP消息体中包含具体的错误代码(code)及错误信息(message)。

关于金睛API无法定位问题时，可以提供请求ID（返回内容中的RequestId或Header中的x-live-request-id），以便快速定位并解决问题。

公共错误

接口错误

错误响应示例

{
"RequestId": "655401ba-dc91-444b-afc0-4e966b1e9624",
"Error": {
"Type": "Sender",
"Code": "MissingParameters",
"Message": "UniqueName is (are) required"
}
}

签名机制

金山云的openAPI采用AWS签名算法版本4，具体可以参考AWS文档，支持GET和POST等HTTP方法，POST方法将Signature以名为authorization header的形式放置在header中，GET等方法将请求参数包括signature放置在url中。

签名计算的主要流程如下：

1. 创建一个正规化请求

   在签名前，首先将请求进行正规化格式化，目的是让签名计算过程无二意，其主要过程伪代码如下：

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

   Hash指代计算哈希的算法，目前使用SHA-256，HexEncode是对哈希值进行用16进制编码（使用小写字母）。

具体步骤如下

1. 抽取HTTP请求方法（如GET、PUT、POST）结尾附加“换行符”

2. URI绝对路径进行URI编码得到正规化URI，如果绝对路径为空，那么使用前斜线"/"，结尾附加“换行符”

3. 构建正规化Querystring，结尾附加“换行符”

4. URI编码每一个querystring参数名称和参数值（注：GET方式需要包含哈希算法、信任状、签名日期和签名header等全部参数）

5. 按照ASCII字节顺序对参数名称严格排序

6. 将排序号的参数名称和参数值用=连接，按照排序结果将“参数对”用&连接

7. 构建正规化headers，结尾附加“换行符”，伪代码如下：

CanonicalHeaders = CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + ... + CanonicalHeadersEntryN

其中：

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

lowercase表示将header名字转为小写字母，trimall表示去掉header值前和值后的白空格，并将header值里面的连续白空格变成单空格，但是不去掉双引号中间的任何空格，且最后的正规化headers是按照header名称排序后的结果

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

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

然后处理请求body，如下

1. 对请求body使用哈希算法（SHA256）计算哈希值，并将二进制哈希值结果用16进制编码表示出来（且不使用大写字符），伪代码

HashedPayload = Lowercase(HexEncode(Hash(requestPayload)))

此时，

1. 将上述i-vi步骤的结果连接成一个字符串，即为正规化请求（Canonical Request）

2. 将vii步的正规化请求使用vi步的哈希算法计算哈希值

1. 创建签名字符串

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

StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HashedCanonicalRequest

其中，签名算法(Algorithm)为AWS4-HMAC-SHA256，请求日期(RequestDate)格式YYYYMMDD'T'HHMMSS'Z' ，信任状(CredentialScope)格式为YYYYMMDD/region/service/aws4_request（包括请求日期（ISO 8601 基本格式）），正规化请求哈希值为上述1中第viii步的结果（注意结尾不附加“换行符”）

1. 计算签名信息

在计算签名前，首先从私有访问密钥（secret AccessKey）派生出签名密钥（signing key），而不是直接使用私有访问密钥；之后使用签名密钥和2中计算的签名字符串来计算签名值，具体计算过程如下

1. 生成签名密钥，伪代码如下

kSecret = *Your KSC Secret Access Key*

kDate = HMAC("AWS4" + kSecret, Date)

kRegion = HMAC(kDate, Region)

kService = HMAC(kRegion, Service)

kSigning = HMAC(kService, "aws4_request")

其方式是通过HMAC算法依次生成下一个HMAC的key值（第一个为私有访问密钥字符串），而data值则依次为信任状中的各项内容（日期、region、服务、结尾字符串）；HMAC算法采用HMAC-SHA256，返回值为哈希值二进制形式（256bit，32字节），不需要做8/16进制编码显示。

1. 计算签名,伪代码如下：

signature = HexEncode(HMAC(derived-signing-key, string-to-sign))

使用HMAC-SHA256算法，以签名密钥作为key，签名字符串作为data计算签名，签名后的二进制哈希值结果以16进制编码输出。