构造请求
请求URI
请求URI由如下部分组成:
{URI-scheme}://{Endpoint}/{resource-path}?{query-string}
URI-scheme: 表示用于传输请求的协议,当前所有API均采用HTTPS协议。
Endpoint: 指定承载REST服务端点的服务器域名或IP,不同服务不同区域的Endpoint不同。
resource-path:资源路径,也即API访问路径。从具体API的URI模块获取。
query-string:查询参数,是可选部分,并不是每个API都有查询参数。查询参数前面需要带一个“?”,形式为“参数名=参数取值”,例如“?regionID=xxx-xxx-yyyzzz”,表示查询特定区域的数据。
请求URI示例:
https://cbi-global.ctapi.ctyun.cn/v4/cwai/dataset/list?regionID=xxx-xxx-yyzz
请求方法
一般读操作采用GET方法,写操作采用POST方法,删除操作采用DELETE方法,具体请求方法请参见各API接口说明。
请求消息头
附加请求头字段,主要是用于鉴权的公共字段。
字段 | 类型 | 描述 |
---|---|---|
Content-Type | String | 消息体的类型(格式),统一为:application/json |
Eop-Authorization | String | 公钥,为ctyun-eop-ak的值 |
Header | String | 待签名的header参数列表,以分号分割,如:Header=eop-date;host |
Signature | String | 计算得到的用于鉴权的签名,生成方式参见认证鉴权章节 |
请求消息体
请求消息体可选,格式统一为JSON,具体内容参见各API接口说明。
认证鉴权
本产品(云骁智算平台CloudWarrior for AI/2023-10-30)的OpenAPI的签名采用AK/SK认证鉴权。AK/SK认证就是使用AK/SK对请求进行签名,在请求时将签名信息添加到消息头,以便通过身份认证。
AK(Access Key ID):访问密钥ID。与私有访问密钥关联的唯一标识符;访问密钥ID和私有访问密钥一起使用,对请求进行加密签名。
SK(Secret Access Key):私有访问密钥。与访问密钥ID结合使用,对请求进行加密签名,可标识发送方,并防止请求被修改。
获取AK/SK
1.天翼云注册账号:于天翼云门户(https://www.ctyun.cn/)注册账号,并通过实名认证。
2.获取AK/SK信息:登录天翼云门户,进入管理中心->个人中心->第三方账号绑定,找到【用户AccessKey】,获取ak/sk,作为调用CTAPI的秘钥。
基本签名流程
1、创建待签字符串:使用规范请求和其他信息创建待签字符串;
2、计算密钥:使用Header、ak/sk来创建Hmac算法的密钥;
3、计算签名:使用第二步的密钥和待签字符串在通过hmacsha256来计算签名。
4、签名应用:将生成的签名信息作为请求消息头添加到HTTP请求中。
创建待签名字符串
待签名字符串的构造规则如下:
待签名字符串string_signature= 需要进行签名的Header排序后的组合列表+ "\n" + 排序的query + "\n" + toHex(sha256(原封的body))
需要进行签名的Header排序后的组合列表(排序的header) | header 以 header_name:header_value来一个一个通过\n拼接起来,EOP是强制要求ctyun-eop-request-id和eop-date这个头作为Header中的一部分,并且必须是待签名Header里的一个。需要进行签名算法的Header需要进行排序(将它们的header_name以26个英文字母的顺序来排序),将排序后得到的列表进行遍历组装成待签名的header。eop-date字段的格式是“yyyymmddTHHMMSSZ”,即“年月日T时分秒Z”,示例“eop-date:20211221T163614Z”。ctyun-eop-request-id字段是uuid,32位随机数。 |
---|---|
排序的query | query以&作为拼接,key和值以=连接,排序规则使用26个英文字母的顺序来排序,Query参数全部都需要进行签名 |
toHex(sha256(原封的body)) | 传进来的body参数进行sha256摘要,对摘要出来的结果转十六进制 |
排序的header例子:
假设你需要将ctyun-eop-request-id、eop-date、host都要签名,则待签名的header构造出来是:
ctyun-eop-request-id:123456789\neop-date:20210531T100101Z\nhost:1.1.1.1:9080\n
ctyun-eop-request-id、eop-date和host的排序就是这个顺序。
构造动态秘钥
发起请求时,需要构造一个eop-date的时间,这个时间的格式是yyyymmddTHHMMSSZ;也就是年月日T时分秒Z
1、使用eop-date作为数据,sk作为密钥,算出ktime;
2、使用ak作为数据,ktime作为密钥,算出kAk;
3、拿kAk作为密钥,eop-date的年月日值作为数据,算出kdate,即为构造出的动态秘钥。
eop-date | yyyymmddTHHMMSSZ(20211221T163614Z)(年月日T时分秒Z) |
---|---|
Ktime | 使用sk作为密钥,eop-date作为数据,算出Ktime;Ktime = hmacSha256(ctyun-eop-sk, eop-date) |
kAk | 使用ktime作为密钥,申请来的ak数据,算出kAk;kAk = hmacsha256(ktime,ak) |
kdate | 使用kAk作为密钥,eop-date的年月日值作为数据,算出kdate;kdate = hmacsha256(kAk, eop-date) |
构造签名
由“构造动态秘钥”和“创建待签名字符串”分别得出来的待签名字符串string_signature、kdate生成出Signature;
Signature | 待签名字符串string_signature、kdate;hmacsha256(kdate,string_signature)得出的结果,再将结果进行base64编码得出Signature |
---|---|
Eop-Authorization | ak Header=你构造待签名字符串时的header排序 Signature(注意中间有空格)header排序以分号”;”拼接例子所述:你待签名的字符串header顺序是 eop-date和host;那么你加到header里的值就是Eop-Authorization: ak Header=eop-date;host Signature=xad01/ada注意,ak、Header、Signature之间以空格隔开。 |
由上得到Eop-Authorization,然后将数据整合成HEADER放在http_client内,发出即可。
http_client所需请求头部如下:
Eop-Authorization: ak Header= ctyun-eop-request-id;eop-date Signature=xad01/ada
eop-date:20211221T163614Z
ctyun-eop-request-id: 123456789
(注:若需要进行签名的Header不止默认的ctyun-eop-request-id和eop-date,需要在http_client的请求头部中加上,并且在Eop-Authorization中也需要增加)