阿里云API网关（7）开发指南-API参考

时间：2024-07-25 09:38:02

网关指南： https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl

网关控制台： https://apigateway.console.aliyun.com/?spm=5176.doc42740.2.2.Q4z5ws#/cn-hangzhou/apis/list

一、简介

用户可以使用开发指南介绍的 API 对 API 网关服务进行相关操作。

术语表

术语 全称 中文 说明
Region   地域 用户开放API，需选择API在API网关的部署地域，建议选择与后端服务相同的Region。
API   应用程序编程接口 用户开放API，在API网关录入API，以提供接口的方式对外提供服务或者数据。
Group API Group API分组 一组API。
  • 用户开放API，首先需要创建API分组
  • 每个API分组拥有一个二级域名，两个Stage
  • 用户需要将已经备案且解析至分组二级域名的独立域名绑定到API分组上
  • 同分组下的API均可通过已绑定的独立域名访问
SubDomain   分组二级域名 用户开放API，创建的每个API分组都有一个二级域名，独立域名需要解析到该二级域名上，直接访问该域名可以调用测试环境的API。
CustomDomain Custom Domain 域名 用户开放API，需要绑定自己的独立域名，该域名需要CNAME解析到分组二级域名上且在阿里云备案或备案接入。且若支持HTTPS协议，还需为域名上传SSL合规证书。
Stage   环境 用户开放API，创建的每个API分组目前有两个环境，测试和线上。用户操作API发布到某个环境后，API才能被调用。区别在于，直接访问分组二级域名调用API，默认是调用测试环境。
Signature Backend Signature 后端签名密钥 用于开放API的用户给API网关颁发身份验证密钥。后端签名密钥绑定到API后对绑定的API即时生效。网关接收到这些API的请求，再去请求后端服务的时候就会带上签名信息，供后端服务对API网关做身份校验。
TrafficControl   流量控制策略（简称“流控策略”） 用于开放API的用户对API做访问流控。流控策略与API绑定后对绑定的API即时生效。流控策略可以从Api、App、User三个维度管控API的调用。流控策略下还可以配置特殊流控，如某App/User在调用绑定的API时，可以按照特殊的值来流控。
Special Special Traffic Control 特殊流量控制（简称“特殊流控”） 是流控策略的一个配置，可以指定某App/User，针对流控策略绑定的API，按照单独的值进行流控。
APP   应用 调用其他用户开放的API时，需要创建一个APP作为调用者的身份。请求到达网关时，会对AppKey和AppSecret进行签名校验。

业务限制资源规格限制说明

在 API 网关中，对每个用户可创建的API分组、API个数都有限制，对用户经过API网关调用开放的API也有限制。详情请参考官网文档对使用限制的说明《开放API使用限制》和《调用API使用限制》。

在接口说明部分，凡出现与官网上给出的限制发生矛盾时，均以官网的限制说明为准。

三、API概览

API分组相关接口

API 描述
CreateApiGroup 创建API分组
ModifyApiGroup 修改API分组
DeleteApiGroup 删除API分组
CreateApiStageVariable 创建环境变量
DeleteApiStageVariable 删除环境变量
DescribeApiStage 查询指定环境详情
DescribeApiGroup 查询指定API分组详情
DescribeApiGroups 查询API分组列表

域名相关接口

API 描述
SetDomain 绑定自定义域名
SetDomainCertificate 给指定自定义域名上传SSL证书
DescribeDomain 查询指定自定义域名详情信息
DeleteDomain 删除指定自定义域名
DeleteDomainCertificate 删除指定域名的证书

API管理相关接口

API 描述
CreateApi 创建API
ModifyApi 修改API
DeployApi 发布指定API到指定环境
SwitchApi 切换指定API在指定环境运行中的定义
AbolishApi 将指定环境的指定API下线
DeleteApi 删除指定Api定义
DescribeApi 查询指定API定义中的详情
DescribeApis 查询定义中的API列表
DescribeApiDoc 查询指定API在指定环境中的调用说明（运行的定义）
DescribeDeployedApi 查询指定API在指定环境中的运行定义
DescribeDeployedApis 查询指定环境中正在运行的API列表
DescribeApiHistory 查询指定API指定历史版本的定义
DescribeApiHistories 查询指定API指定历史版本列表
DescribeApiErrorData 查询指定API的错误监控数据
DescribeApiLatencyData 查询指定API的响应时间监控数据
DescribeApiQpsData 查询指定API的Qps监控数据
DescribeApiTrafficData 查询指定API的流量监控数据

API流量控制相关接口

API 描述
CreateTrafficControl 创建流量控制策略
ModifyTrafficControl 修改流量控制策略
DeleteTrafficControl 删除指定流控策略
AddTrafficSpecialControl 在指定流控策略下添加特殊流控策略
DeleteAllTrafficSpecialControl 删除指定流控策略下所有的特殊流控
DeleteTrafficSpecialControl 删除指定流控策略下的指定特殊流控
SetTrafficControlApis 添加API与流控策略的绑定关系
RemoveTrafficControlApis 解除API与流控策略的绑定关系
DescribeTrafficControls 条件查询流控策略列表及详情信息
DescribeApisByTrafficControl 查询指定策略下已绑定的API
DescribeApiTrafficControls 查询指定分组指定环境下所有API的流控策略绑定概况
DescribeTrafficControlsByApi 查询指定API已绑定的流控策略

后端签名相关接口

API 描述
CreateSignature 创建后端签名密钥
ModifySignature 修改后端签名密钥
DeleteSignature 删除后端签名密钥
SetSignatureApis 添加API与后端签名密钥的绑定关系
RemoveSignatureApis 解除API与后端签名密钥的绑定关系
DescribeSignatures 查询后端签名密钥列表
DescribeApisBySignature 查询指定签名密钥所绑定的API
DescribeApiSignatures 查询指定分组指定环境下所有API的签名密钥绑定概况
DescribeSignaturesByApi 查询指定API已绑定的后端签名密钥

APP相关接口

API 描述
CreateApp 创建应用
ModifyApp 修改应用
ResetAppSecret 重置指定APP密钥
DescribeAppAttributes 查询APP列表及基本属性
DescribeAppSecurity 查询指定APP密钥信息
DeleteApp 删除应用

授权相关接口

API 描述
DescribeApps 查询可授权的APP列表
DescribeAuthorizedApis 查询指定APP已授权的API列表
DescribeAuthorizedApps 查询API的应用授权列表
SetApisAuthorities 给指定APP添加多个API的访问权限
SetAppsAuthorities 给多个APP添加指定API的访问权限
RemoveApisAuthorities 批量撤销指定APP对多个API的访问权限
RemoveAppsAuthorities 批量撤销多个APP对指定API的访问权限

其他接口

API 描述
DescribeRegions 查询支持的区域列表
DescribeSystemParameters 查询系统参数列表

四、调用方式

调用方式

更新时间：2017-06-07 13:26:11   分享：

对 API 网关 API 接口调用是通过向 API 网关 API 的服务端地址发送HTTP GET请求，并按照接口说明在请求中加入相应请求参数来完成的；根据请求的处理情况，系统会返回处理结果。

请求结构

服务地址

API网关 API的服务接入地址为：apigateway.[RegionId].aliyuncs.com.

如：apigateway.cn-hangzhou.aliyuncs.com

通信协议

支持通过HTTP或HTTPS通道进行请求通信。为了获得更高的安全性，推荐您使用HTTPS通道发送请求。

请求方法

支持HTTP GET方法发送请求，这种方式下请求参数需要包含在请求的URL中。

请求参数

每个请求都需要指定要执行的操作，即Action参数（例如CreateApi），以及每个操作都需要包含的公共请求参数和指定操作所特有的请求参数。

字符编码

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

公共参数

公共请求参数

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

名称 类型 是否必填 描述
Format String 否 返回值的类型，支持JSON与XML。默认为XML
Version String 是 API版本号，为日期形式：YYYY-MM-DD，本版本对应为2016-07-14
AccessKeyId String 是 阿里云颁发给用户的访问服务所用的密钥ID
Signature String 是 签名结果串，关于签名的计算方法，请参见签名机制。
SignatureMethod String 是 签名方式，目前支持HMAC-SHA1
TimeStamp String 是 请求的时间戳。日期格式按照ISO8601标准表示，并需要使用UTC时间。格式为：YYYY-MM-DDThh:mm:ssZ。例如，2014-11-11T12:00:00Z（为北京时间2014年11月11日20点0分0秒）
SignatureVersion String 是 签名算法版本，目前版本是1.0
SignatureNonce String 是 唯一随机数，用于防止网络重放攻击。用户在不同请求间要使用不同的随机数值

请求示例：

  1. https://apigateway.cn-hangzhou.aliyuncs.com/?Format=xml
  2. &Version=2016-07-14
  3. &Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
  4. &SignatureMethod=HMACSHA1
  5. &SignatureNonce=15215528852396
  6. &SignatureVersion=1.0
  7. &AccessKeyId=key-test
  8. &TimeStamp=2016-08-08T08:00:00Z

公共返回参数

用户发送的每次接口调用请求，无论成功与否，系统都会返回一个唯一识别码RequestId给用户。

XML返回示例：

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!—结果的根结点-->
  3. <接口名称+Response>
  4. <!—返回请求标签-->
  5. <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
  6. <!—返回结果数据-->
  7. </接口名称+Response>

JSON返回示例：

  1. {
  2. "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
  3. /* 返回结果数据 */
  4. }

返回结果

调用API服务后返回数据采用统一格式，返回的HTTP状态码为2xx，代表调用成功。返回4xx或5xx的HTTP状态码代表调用失败。

调用成功返回的数据格式主要有XML和JSON两种，外部系统可以在请求时传入参数来制定返回的数据格式，默认为XML格式。

本文档中的返回示例为了便于用户查看，做了格式化处理，实际返回结果是没有进行换行、缩进等处理的。

成功结果

XML返回示例：

（XML返回结果包括请求是否成功信息和具体的业务数据）

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!—结果的根结点-->
  3. <接口名称+Response>
  4. <!—返回请求标签-->
  5. <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
  6. <!—返回结果数据-->
  7. </接口名称+Response>

JSON示例：

  1. {
  2. "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
  3. /* 返回结果数据 */
  4. }

错误结果

调用接口出错后，将不会返回结果数据。调用方可根据附表<错误查询表>来定位错误原因。

当调用出错时，HTTP请求返回一个4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。另外还包含一个全局唯一的请求ID：RequestId和一个您该次请求访问的站点ID：HostId。在调用方找不到错误原因时，可以联系阿里云客服，并提供该HostId和RequestId，以便我们尽快帮您解决问题。

XML示例：

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <Error>
  3. <RequestId>8906582E-6722-409A-A6C4-0E7863B733A5</RequestId>
  4. <HostId>apigateway.cn-hangzhou.aliyuncs.com</HostId>
  5. <Code>InternalError</Code>
  6. <Message>The request processing has failed due to some unknown error.</Message>
  7. </Error>

JSON示例：

  1. {
  2. "RequestId": "8906582E-6722-409A-A6C4-0E7863B733A5",
  3. "HostId": "apigateway.cn-hangzhou.aliyuncs.com",
  4. "Code": "InternalError",
  5. "Message": "The request processing has failed due to some unknown error."
  6. }

五、签名机制

详细说明

API网关服务会对每个访问的请求进行身份验证，所以无论使用HTTP还是HTTPS协议提交请求，都需要在请求中包含签名（Signature）信息。

API网关通过使用Access Key ID和Access Key Secret进行对称加密的方法来验证请求者身份。Access Key ID和Access Key Secret由阿里云官方颁发给访问者（可以通过阿里云官方网站申请和管理），其中

Access Key ID用于标识访问者的身份

Access Key Secret是用于加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密，只有阿里云和用户知道。

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

a. 使用请求参数构造规范化的请求字符串（Canonicalized Query String）

  • 按照参数名称的字典顺序对请求中所有的请求参数（包括文档中描述的“公共请求参数”和给定了的请求接口的自定义参数，但不能包括“公共请求参数”中提到Signature参数本身）进行排序。

注：当使用GET方法提交请求时，这些参数就是请求URI中的参数部分（即URI中“?”之后由“&”连接的部分）。

  • 对每个请求参数的名称和值进行编码。名称和值要使用UTF-8字符集进行URL编码，URL编码的编码规则是：
  1. 对于字符 A-Z、a-z、0-9以及字符“-”、“_”、“.”、“~”不编码;
  2. 对于其他字符编码成“%XY”的格式，其中XY是字符对应ASCII码的16进制表示。比如英文的双引号（”）对应的编码就是%22
  3. 对于扩展的UTF-8字符，编码成“%XY%ZA…”的格式；
  4. 需要说明的是英文空格（ ）要被编码是%20，而不是加号（+）。
  1. 注：一般支持URL编码的库（比如Java中的java.net.URLEncoder）都是按照“application/x-www-form-urlencoded”的MIME类型的规则进行编码的。
  3. 实现时可以直接使用这类方式进行编码，把编码后的字符串中加号（+）替换成%20、星号（*）替换成%2A、%7E替换回波浪号（~），即可得到上述规则描述的编码字符串。
  • 对编码后的参数名称和值使用英文等号（=）进行连接。
  • 再把英文等号连接得到的字符串按参数名称的字典顺序依次使用&符号连接，即得到规范化请求字符串。

b. 使用上一步构造的规范化字符串按照下面的规则构造用于计算签名的字符串：

  1. StringToSign=
  2. HTTPMethod + “&” +
  3. percentEncode(“/”) + ”&” +
  4. percentEncode(CanonicalizedQueryString)

其中HTTPMethod是提交请求用的HTTP方法，比GET。

percentEncode(“/”)是按照1.b中描述的URL编码规则对字符“/”进行编码得到的值，即“%2F”。

percentEncode(CanonicalizedQueryString)是对第1步中构造的规范化请求字符串按1.b中描述的URL编码规则编码后得到的字符串。

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

d. 按照Base64编码规则把上面的HMAC值编码成字符串，即得到签名值（Signature）。

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

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

以DescribeRegions为例，签名前的请求URL为：

  1. http://apigateway.cn-qingdao.aliyuncs.com?Format=json&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=Hmac-SHA1&SignatureNonce=d48e931b-90c9-49c7-ac86-a70dd3607c88&SignatureVersion=1.0&Version=2016-07-14&Timestamp=2016-09-27T09%3A08%3A30Z

那么StringToSign就是：

  1. GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeRegions%26Format%3Djson%26SignatureMethod%3DHmac-SHA1%26SignatureNonce%3Dd48e931b-90c9-49c7-ac86-a70dd3607c88%26SignatureVersion%3D1.0%26Timestamp%3D2016-09-27T09%253A08%253A30Z%26Version%3D2016-07-14

假如使用的Access Key Id是“testid”，Access Key Secret是“testsecret”，用于计算HMAC的Key就是“testsecret&”，则计算得到的签名值是：

  1. DRdMb%2F1m7PeToGRBApTl3wThyOg%3D

签名后的请求URL为（注意增加了Signature参数）：

  1. http://apigateway.cn-qingdao.aliyuncs.com?Signature=DRdMb%2F1m7PeToGRBApTl3wThyOg%3D&Format=json&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=Hmac-SHA1&SignatureNonce=d48e931b-90c9-49c7-ac86-a70dd3607c88&SignatureVersion=1.0&Version=2016-07-14&Timestamp=2016-09-27T09%3A08%3A30Z

相关文章