淡人日记

落花无言,人淡如菊,书之岁华,其曰可读

开放接口请求说明

说明

网关服务会对每个访问的请求进行身份验证,所以无论使用HTTP还是HTTPS协议提交请求,都需要在请求中包含签名(Signature)信息。网关服务通过使用Access Key IDAccess Key Secret进行对称加密的方法来验证请求的发送者身份。

Access Key IDAccess Key Secret由网关服务颁发给访问者(可以通过https://account.getlove.cn/login/网站申请和管理),其中Access Key ID用于标识访问者的身份;Access Key Secret是用于加密签名字符串和服务器端验证签名字符串的密钥,必须严格保密,只有网关服务和用户知道。

公共请求参数

公共请求参数是指每个接口都需要使用到的请求参数

名称 类型 是否必需 描述
AccessKeyId String 用户的访问服务所用的密钥 ID
Timestamp String 请求的时间戳。日期格式按照 ISO8601 标准表示,并需要使用 UTC 时间。格式为YYYY-MM-DDThh:mm:ssZ,例如,2015-01-09T12:00:00Z(为 UTC 时间 2015 年 1 月 9 日 12 点 0 分 0 秒。)
SignatureNonce String 唯一随机数,用于防止网络重放攻击。用户在不同请求间要使用不同的随机数值。
Signature String 签名结果串,关于签名的计算方法,请参见签名机制。

签名规范

用户在访问时,按照下面的方法对请求进行签名处理:

一、 使用请求参数构造规范化的请求字符串(Canonicalized Query String)

  • 1-1、 参数排序。 按照参数名称的字典顺序对请求中所有的请求参数(包括“公共请求参数”和接口的自定义参数,但不能包括“公共请求参数”中提到的Signature 参数本身)进行排序。注:当使用 GET 方法提交请求时,这些参数就是请求 URI 中的参数部分(即 URI 中“?”之后由“&”连接的部分),使用POST,PUT方法提交请求时,这些参数就是请求体部分,即body部分。
  • 1-2、 参数编码。 对排序之后的请求参数的名称和值分别用UTF-8字符集进行URL编码。
  • 1-3、 将编码后的参数名称和值用英文等号(=)进行连接。
  • 1-4、 再把英文等号连接得到的字符串按参数名称的字典顺序依次使用&符号连接,即得到规范化请求字符串。

二、 将上一步构造的规范化字符串按照下面的规则构造成待签名的字符串:

method + "&" + encodeURIComponent(path) + "&" + queryString

参数 说明
method 请求方式,PUT,POST,GET(请使用大写)
path 请求路径
queryString 排序后的参数 字符串

代码示例

https://github.com/liuyinglong/api_get_way_demo/blob/master/tools/ApiGetwaySign.js

三、 按照 RFC2104 的定义,计算待签名字符串StringToSign的 HMAC 值。注意:计算签名时使用的 Key 就是用户持有的Access Key Secret并加上一个 “&” 字符(ASCII:38),使用的哈希算法是 SHA1。

四、 按照 Base64 编码规则把上面的 HMAC 值编码成字符串,即得到签名值(Signature)。

五、将得到的签名值作为Signature参数添加到请求参数中,即完成对请求签名的过程。

注意:得到的签名值在作为最后的请求参数值提交给网关服务器的时候,要和其他参数一样,按照RFC3986的规则进行 URL 编码。

请求示例

以诗词API中 根据关键词搜索内容为例,假设使用的Access Key Id5ceffbb0abbe632b648316c6Access Key Secret91df9d44659ae913d7ce6ddaa2f96e5b。 那么签名前的请求 URL 为:

https://account.getlove.cn/apiGetWay/5b010c7445657b2b64ada7a2/api/v1/poetry/search?AccessKeyId=5ceffbb0abbe632b648316c6&SignatureNonce=1559232409259&Timestamp=2019-05-30T16:06:49Z&keywords=李白&page=1&size=2&type=author

签名字符串为

GET&%2Fapi%2Fv1%2Fpoetry%2Fsearch&AccessKeyId=5ceffbb0abbe632b648316c6&SignatureNonce=1559232409259&Timestamp=2019-05-30T16%3A06%3A49Z&keywords=%E6%9D%8E%E7%99%BD&page=1&size=2&type=author

假如使用的Access Key Id是5ceffbb0abbe632b648316c6,Access Key Secret是91df9d44659ae913d7ce6ddaa2f96e5b,用于计算HMAC的Key就是&91df9d44659ae913d7ce6ddaa2f96e5b,则计算得到的签名值是: 80565fab122c799ffdd8e69fc81d7ebcaa883398

最后请求的链接为

https://account.getlove.cn/apiGetWay/5b010c7445657b2b64ada7a2/api/v1/poetry/search?AccessKeyId=5ceffbb0abbe632b648316c6&SignatureNonce=1559232409259&Timestamp=2019-05-30T16:06:49Z&keywords=%E6%9D%8E%E7%99%BD&page=1&size=2&type=author&Signature=80565fab122c799ffdd8e69fc81d7ebcaa883398

目录