阿里云API接口使用说明

阿里云提供的所有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. 公共参数

公共返回参数

 
 
3. 签名机制
 
（1）签名机制简介
 
通过AccessKey的方式访问后台接口，主要是通过签名校验的方式，鉴定用户请求的url是否在传输过程中被篡改过，若签名校验通过，则认为请求没有被篡改过，后台会将请求转发到具体的服务。若签名校验失败，则被认为由于一些原因，导致当前请求是不安全的，例如用户请求的url被篡改过，用户请求过期等，后台将拒绝提供服务。在云门户注册主用户或创建子用户后，可以为每个用户生成一对AccessKey，AccessKey由AccessKeyId与AccessKeySecret组成。通过AccessKeyId，可以在后台查出唯一对应的用户的详细信息；AccessKeySecret则作为秘钥，用于对请求进行签名。AccessKeySecret需要用户严格保密，来防止被盗用后用于冒充用户进行签名。
 
目前，使用签名校验的方式访问后台接口，请求的url参数由以下几个部分组成：
 

 
（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&regionId=Region-southChina&signatureMethod=HMAC-SHA1&signatureNonce=3378010751426913252&signatureVersion=1.0&timestamp=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 文档返回示例均有换行和缩进等处理，实际返回结果无换行和缩进处理。