握手API网关(7)开发指南-API参考

一、简介

用户可以使用开发指南介绍的 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 IDAccess Key Secret进行对称加密的方法来验证请求者身份。Access Key IDAccess 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类型的规则进行编码的。
  2. 实现时可以直接使用这类方式进行编码,把编码后的字符串中加号(+)替换成%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
时间: 07-19

握手API网关(7)开发指南-API参考的相关文章

握手API网关(3)調用 API 网关 暴露的 开放 API

调用 API 的三个前置条件: API:您即将要调用的API,明确API参数定义. 应用 app:作为您调用API时的身份,有 AppKey 和 AppSecret 用于验证您的身份. API 和 App 的权限关系:App 想调用某个 API 需要具有该 API 的权限,这个权限通过授权的功能来建立. 以下会详细说如何具备三个条件,并提供 API 调用 Demo 供参考. 步骤1:获取 API 文档 从数据市场购买的 API 服务 您购买 API 服务时,如果还没有开通 API 网关服务,那么

SIA-GateWay之API网关安装部署指南

SIA-GATEWAY是基于SpringCloud微服务生态体系下开发的一个分布式微服务网关系统.具备简单易用.可视化.高可扩展.高可用性等特征,提供云原生.完整及成熟的接入服务解决方案.本文介绍API网关的安装部署. 一.环境 1.1 编译环境 Maven3+ nodejs Jdk1.8+ 1.2 运行时第三方依赖 Mysql5.6+ elasticsearch 5.5.2 kibana-5.5.2 kafka 2.12-2.0.0 redis 3.2.11 eureka-server 1.3

.NET微服务架构及API网关

一.MSA简介 1.1.MSA是什么 微服务架构MSA是Microservice Architecture的简称,它是一种架构模式,它提倡将单一应用程序划分成一组小的服务,服务之间互相通讯.互相配合,为用户提供最终价值.它与SOA之间的区别如下: SOA实现 微服务架构实现   企业级,自顶向下开展实施 团队级,自底向上开展实施   粒度大:服务由多个子系统组成 粒度细:一个系统被拆分成多个服务,且服务的定义更加清晰   重ESB:企业服务总线,集中式的服务架构 轻网关:无集中式总线,松散的服务

API网关从入门到放弃

假设你正在开发一个电商网站,那么这里会涉及到很多后端的微服务,比如会员.商品.推荐服务等等. 那么这里就会遇到一个问题,APP/Browser怎么去访问这些后端的服务? 如果业务比较简单的话,可以给每个业务都分配一个独立的域名(https://service.api.company.com),但这种方式会有几个问题: 每个业务都会需要鉴权.限流.权限校验等逻辑,如果每个业务都各自为战,自己造轮子实现一遍,会很蛋疼,完全可以抽出来,放到一个统一的地方去做. 如果业务量比较简单的话,这种方式前期不会

Net分布式系统之六:微服务之API网关

本人建立了个人技术.工作经验的分享微信号,计划后续公众号同步更新分享,比在此更多具体.欢迎有兴趣的同学一起加入相互学习.基于上篇微服务架构分享,今天分享其中一个重要的基础组件“API网关”. 一.引言 随着互联网的快速发展,当前以步入移动互联.物联网时代.用户访问系统入口也变得多种方式,由原来单一的PC客户端,变化到PC客户端.各种浏览器.手机移动端及智能终端等.同时系统之间大部分都不是单独运行,经常会涉及与其他系统对接.共享数据的需求.所以系统需要升级框架满足日新月异需求变化,支持业务发展,并

API网关

微服务之API网关 一.引言 随着互联网的快速发展,当前以步入移动互联.物联网时代.用户访问系统入口也变得多种方式,由原来单一的PC客户端,变化到PC客户端.各种浏览器.手机移动端及智能终端等.同时系统之间大部分都不是单独运行,经常会涉及与其他系统对接.共享数据的需求.所以系统需要升级框架满足日新月异需求变化,支持业务发展,并将框架升级为微服务架构."API网关"核心组件是架构用于满足此些需求. 很多互联网平台已基于网关的设计思路,构建自身平台的API网关,国内主要有京东.携程.唯品会

谈谈微服务中的 API 网关(API Gateway)

转载至:http://www.cnblogs.com/savorboard/p/api-gateway.html 背景 我们知道在微服务架构风格中,一个大应用被拆分成为了多个小的服务系统提供出来,这些小的系统他们可以自成体系,也就是说这些小系统可以拥有自己的数据库,框架甚至语言等,这些小系统通常以提供 Rest Api 风格的接口来被 H5, Android, IOS 以及第三方应用程序调用. 但是在UI上进行展示的时候,我们通常需要在一个界面上展示很多数据,这些数据可能来自于不同的微服务中,举

API网关模式

什么是网关 网关一词来源于计算机网络中的定义,网关(Gateway)又称网间连接器.协议转换器.网关的准确定义是: 两个计算机程序或系统之间的连接,网关作为两个程序之间的门户,允许它们通过不同计算机之间的协议通信来共享信息.顾名思义API网关就是API之间相互调用的关卡和屏障. API之间为什么需要网关 试想一下我们在实现一个非常庞大的业务系统,分为不同的业务domain和子系统,各个domain和子系统提供处理业务的API,不同系统之间以API的方式进行数据交互.通常情况下我们可能会将所有实现

.Net微服务架构:API网关

本人建立了个人技术.工作经验的分享×××号,计划后续公众号同步更新分享,比在此更多具体.欢迎有兴趣的同学一起加入相互学习.基于上篇微服务架构分享,今天分享其中一个重要的基础组件"API网关". 一.引言 随着互联网的快速发展,当前以步入移动互联.物联网时代.用户访问系统入口也变得多种方式,由原来单一的PC客户端,变化到PC客户端.各种浏览器.手机移动端及智能终端等.同时系统之间大部分都不是单独运行,经常会涉及与其他系统对接.共享数据的需求.所以系统需要升级框架满足日新月异需求变化,支持