阿里云提供的所有API接口支持HTTP或者HTTPS请求,允许GET和POST两种请求方法,部分接口不允许GET请求。
API URL请求需要使用AccessKey进行签名及URL编码。
1. 请求结构
阿里云支持基于URL发起的HTTP/HTTPS GET请求,请求参数需要包含在URL中
(1)通信协议
支持HTTP或HTTPS协议请求通信。为了获得更高的安全性,推荐您使用HTTPS协议发送请求。
涉及敏感数据时,如用户密码和SSH密钥对,推荐使用HTTPS协议。例如,在Login中指定Password参数时。
(2)接入网关
当前访问需要接入阿里云中国大陆的API服务时,请使用
(3)请求参数
阿里云提供命令模式和RESTful两种模式的API接口,其中命令模式的API接口主要是IaaS类产品和部分PaaS类产品,而RESTful接口主要是SaaS类产品和部分PaaS类产品。
1)命令模式
通过Action参数指定目标操作,例如Action=RunInstance。还需要指定接口的其他参数以及公共请求参数
2)RESTful模式
在RESTful风格的API接口中,每个URL代表一种资源(resource),所以url中不能有动词,只能有名词
对于资源的具体操作类型,由HTTP动词表示,常用的HTTP动词有下面四个:
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
DELETE(DELETE):从服务器删除资源。
(4)字符编码
阿里云API约定请求及返回结果都使用UTF-8字符集编码。
2. 公共参数
参数名称 |
参数类型 |
是否必须 |
参数描述 |
格式/备注 |
accessKeyId |
String |
true |
Access Key Id |
|
signatureMethod |
String |
true |
签名方法 |
HMAC-SHA1 |
signatureNonce |
String |
true |
请求随机数 |
|
signatureVersion |
String |
true |
签名版本 |
1.0 |
timestamp |
String |
true |
请求时间戳 |
|
version |
String |
true |
Api版本 |
2017-01-01 |
signature |
String |
true |
请求签名 |
|
公共返回参数
参数名称 |
参数类型 |
参数描述 |
格式/备注 |
requestId |
String |
请求Id |
Trace ID, 每一次请求会产生新的ID |
code |
String |
请求结果状态 |
HTTP状态 |
message |
String |
请求结果国际化描述 |
国际化之后的消息 |
resultCode |
String |
请求结果状态码 |
A00000~Z99999 |
3. 签名机制
(1)签名机制简介
通过AccessKey的方式访问后台接口,主要是通过签名校验的方式,鉴定用户请求的url是否在传输过程中被篡改过,若签名校验通过,则认为请求没有被篡改过,后台会将请求转发到具体的服务。若签名校验失败,则被认为由于一些原因,导致当前请求是不安全的,例如用户请求的url被篡改过,用户请求过期等,后台将拒绝提供服务。在云门户注册主用户或创建子用户后,可以为每个用户生成一对AccessKey,AccessKey由AccessKeyId与AccessKeySecret组成。通过AccessKeyId,可以在后台查出唯一对应的用户的详细信息;AccessKeySecret则作为秘钥,用于对请求进行签名。AccessKeySecret需要用户严格保密,来防止被盗用后用于冒充用户进行签名。
目前,使用签名校验的方式访问后台接口,请求的url参数由以下几个部分组成:
参数名称 |
参数是否参与计算签名 |
accessKeyId |
是 |
signature |
否 |
signatureMethod |
是 |
signatureNonce |
是 |
signatureVersion |
是 |
timestamp |
是 |
version |
是 |
具体业务接口参数 |
是 |
(2)签名生成过程
以查询地域ListZones接口为例,调用该接口,需要传入的业务参数为action=ListZones,regionId=Region-southChina。
必传的其他参数如公共请求参数部分所述,包括:
accessKeyId=xKJSFaxRfWT_7H0vSzkXLj5gzuS5HDzOkepNGbHWPtDj3mqlg_9nXf4XR23zSm1J_VPlTcXCFMx3JV0UTUDBeA,
signatureMethod=HMAC-SHA1,
signatureNonce=3378010751426913252,
signatureVersion=1.0,
timestamp= 1534159280463,
version=2017-01-01
以上参数是需要参与计算签名的请求参数。
1)首先要对这些参数,根据参数名称按照字母序进行排序,得到的请求参数为:accessKeyId=xKJSFaxRfWT_7H0vSzkXLj5gzuS5HDzOkepNGbHWPtDj3mqlg_9nXf4XR23zSm1J_VPlTcXCFMx3JV0UTUDBeA&action=ListZones®ionId=Region-southChina&signatureMethod=HMAC-SHA1&signatureNonce=3378010751426913252&signatureVersion=1.0×tamp=1534159280463&version=2017-01-01。
2)然后对请求参数,利用HmacSHA1算法进行签名计算,计算签名需要使用AccessKeySecret,用户的AccessKeySecret是存储在客户端的,因此用户可以自行设置,利用AccessKeySecret和其他签名过程中必须的参数,可以计算得到最终的签名signature的值。通常,我们会通过SDK等方式,在用户端集成或提供生成签名或生成请求url的便捷方法。
3)客户端利用签名和其他请求参数,生成请求url,开始请求服务端。
4. 访问验证
请求进入后端服务时,后台会根据请求的url,进入不同的认证逻辑。使用签名的方式访问后端服务,后端将会进入到校验签名的逻辑。
后端接到请求时,会获取到所有的请求参数,以下仅为示例,后端获取的请求参数可能是无序的:
accessKeyId=xKJSFaxRfWT_7H0vSzkXLj5gzuS5HDzOkepNGbHWPtDj3mqlg_9nXf4XR23zSm1J_VPlTcXCFMx3JV0UTUDBeA
action=ListZones
regionId=Region-southChina
signatureMethod=HMAC-SHA1
signatureNonce=3378010751426913252
signatureVersion=1.0
timestamp=1534159280463
version=2017-01-01&signature
(1)首先后端会取出所有请求参数和请求参数值,但会将signature参数排除,然后对排除signanture参数的其他参数,按照参数名称,以字母序进行排序。
(2)后端会根据AccessKeyId,在数据库中查找到AccessKeySecret,然后利用AccessKeySecret,对已经进行过排序的请求参数,进行签名的计算
(3)后端得到签名计算结果后,与请求传入的签名结果进行比较,若签名结果一致,则认为请求合法,将请求转发到具体服务,否则拒绝服务。
签名校验过程中,将依次对下面几个条件进行单独校验(见下表),任何一个环节校验失败,请求都将不会被执行,只有所有校验项都校验通过后,本次请求才被认为是一次合法请求。
校验项解释
重复提交
AccessKey的请求方式,每个签名只能使用一次,每次请求都会生成新的签名,因此当一个签名已经被使用过一次时,15分钟内相同签名的请求会被提示重复提交
API版本错误
目前固定取值2017-01-01
签名版本错误
目前固定取值1.0
签名时效性
生成的签名必须在15分钟内完成请求,15分钟后签名会失效
签名一致性
请求中传入的签名和后端服务计算出来的签名必须一致,否则认为请求是不安全的
5. 返回结果
阿里云API接口返回结果主要是JSON 格式。更多详情,请参阅公共参数。为了便于查看和美观,API 文档返回示例均有换行和缩进等处理,实际返回结果无换行和缩进处理。