阿里云API网关(3)快速入门(调用 API)
网关指南: 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:即将要调用的API,明确API参数定义。
- 应用 app:作为调用API时的身份, AppKey 和 AppSecret 用于验证身份。
- API 和 App 的权限关系:App 想调用某个 API 需要具有该 API 的权限,这个权限通过授权的功能来建立。
以下会详细说如何具备三个条件,并提供 API 调用 Demo 供参考。
一、获取 API 文档
1、从数据市场购买的 API 服务
您购买 API 服务时,如果还没有开通 API 网关服务,那么会同时帮助您开通 API 网关服务,让您使用的更流畅。
购买成功之后您进入云市场的 管理控制台,就会看见您购买的所有 API 服务。您可以在当前控制台查看 API 接口的定义。
您还可以跳转到API 网关的控制台,在 已购买 API 页面,展示您购买的所有 API 服务列表,以及使用情况概况。
选择一个服务点击 查看 API ,页面会展示该服务的基本信息和 API 接口列表。注意在基本信息处关键的信息是 访问域名。
选择一个 API 接口,点击 详情,就会出现详细的接口定义了。
2、不经过购买,由提供方主动授权
提供 API 的一方需要在控制台主动操作授权,这时您需要已经创建过应用 APP,并且将 AppId告知提供方,由他们搜索您的 APP 然后操作授权。
APP 的相关内容在 创建 APP 中介绍。这里先假设您已经创建了 APP,并且提供 API 的一方已经为您的 APP 授权。
您进入 API 网关的控制台应用管理页面,这里是您创建的所有应用APP。
点击 APP 的名称进入 APP 详情,此处会展示 APP 的基本信息以及两个最重要的信息。AppKey 和 已授权的 API 。
AppKey 是您这个 APP 的 Key 和 Secret。您请求的时候需要带上这对密钥,网关会根据这对密钥对您进行身份验证。后面会详细解释。已授权的 API 是您该 APP 已经被授权的 API ,如果提供方已经操作了授权,那么您会在这里看见 API 接口。点击 详情 就可以查看详细的接口定义
以上是两种 API 渠道的获取 API 定义的方式。
二、创建应用
应用(APP)是调用 API 服务时的身份。
每个 APP 有一组 Key 和 Secret,调用 API 时这两个参数的用途如下:
- 将 AppKey 做参数传入
- AppSecret 用于签名计算,不能在请求中传递,
网关会校验这对密钥对您进行身份认证。
调用 API 需要这个 APP 具备调用该API的权限,这个授权和鉴权是面向 APP 的。您可以在 API 网关控制台 应用管理 页面创建您的 APP。
创建成功后,系统会为 APP 分配一对 AppKey 和 AppSecret。
调用服务时,客户端程序需要用 AppSecret 完成签名计算,请求时携带AppKey和签名信息1,
网关会根据AppKey找到服务器侧的AppSecret重新计算签名信息2和签名信息1比对,这就是身份验证。
在应用管理 页面,点击应用名称进入详情,就能看见 AppKey 和 AppSecret 信息了,如果密钥丢失还可以操作重置。
APP 更多说明参见 用户指南(调用API)
三、获得授权
授权,是指授予 APP 调用某个 API 的权限。您的 APP 需要获得 API 的授权才能调用该API。根据获取 API 的渠道不同,建立授权的方式也不同。
从数据市场购买的 API 服务
您购买了 API 服务就意味着您已经获得了授权。但是为了更精确的权限控制,您的账号获得了授权,不代表您的每个 APP 都获得了授权。您需要手动操作将已购买的API授权给哪些 APP,然后这些 APP 才能调用该API。
不经过购买,由提供方主动授权
您需要向 API 服务商提供您的 应用 ID (AppID) 或者阿里云邮箱账户,使 API 服务商能够搜索到您的 APP,并完成授权。完成授权后您可以在控制台看到该 APP 被授权的 API。
由提供方操作授权的 API 会出现在应用详情的 已授权 API 子页面。提供方授权时就已经将 API 授权给准确的 APP 了,所以不需要调用者来操作授权。
四、调用 API
您可以直接用 API 网关控制台为您提供的多语言调用示例来测试调用,可以自行编辑 HTTP(s) 请求来调用 API。关于签名方式,您可以参照控制台的 SDK示例下载 。
通过上述步骤,您已经获取了 API 定义文档、创建了 APP、建立了授权关系。
您可以调用 API 了。API 的请求步骤说明如下:
第一部分:请求
请求地址:http://e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com/demo/post
请求方法:POST
请求体:
FormParam1=FormParamValue1&FormParam2=FormParamValue2
//HTTP Request Body
请求头部
Host: e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com
Date: Mon, 22 Aug 2016 11:21:04 GMT
User-Agent: Apache-HttpClient/4.1.2 (java 1.6)
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
//请求体类型,请根据实际请求体内容设置。
Accept: application/json
//请求响应体类型,部分 API 可以根据指定的响应类型来返回对应数据格式,建议手动指定此请求头,如果不设置,部分 HTTP 客户端会设置默认值 */*,导致签名错误。
X-Ca-Request-Mode: debug
//是否开启 Debug 模式,大小写不敏感,不设置默认关闭,一般 API 调试阶段可以打开此设置。
X-Ca-Version: 1
// API版本号,目前所有 API 仅支持版本号『1』,可以不设置此请求头,默认版本号为『1』。
X-Ca-Signature-Headers: X-Ca-Request-Mode,X-Ca-Version,X-Ca-Stage,X-Ca-Key,X-Ca-Timestamp
//参与签名的自定义请求头,服务端将根据此配置读取请求头进行签名,此处设置不包含 Content-Type、Accept、Content-MD5、Date 请求头,这些请求头已经包含在了基础的签名结构中,详情参照请求签名说明文档。
X-Ca-Stage: RELEASE
//请求 API的Stage,目前支持 TEST、PRE、RELEASE 三个 Stage,大小写不敏感,API 提供者可以选择发布到哪个 Stage,只有发布到指定 Stage 后 API 才可以调用,否则会提示 API 找不到或 Invalid Url。
X-Ca-Key: 60022326
//请求的 AppKey,请到 API 网关控制台生成,只有获得 API 授权后才可以调用,通过云市场等渠道购买的 API 默认已经给APP授过权,阿里云所有云产品共用一套 AppKey 体系,删除 ApppKey 请谨慎,避免影响到其他已经开通服务的云产品。
X-Ca-Timestamp: 1471864864235
//请求的时间戳,值为当前时间的毫秒数,也就是从1970年1月1日起至今的时间转换为毫秒,时间戳有效时间为15分钟。
X-Ca-Nonce:b931bc77-645a-4299-b24b-f3669be577ac
//请求唯一标识,15分钟内 AppKey+API+Nonce 不能重复,与时间戳结合使用才能起到防重放作用。
X-Ca-Signature: FJleSrCYPGCU7dMlLTG+UD3Bc5Elh3TV3CWHtSKh1Ys=
//请求签名。
CustomHeader: CustomHeaderValue
//自定义请求头,此处仅作为示例,实际请求中根据 API定义可以设置多个自定义请求头。
第二部分:响应
状态码:400
//响应状态码,大于等于200小于300表示成功;大于等于400小于500为客户端错误;大于500为服务端错误。
响应头
X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
//请求唯一 ID,请求一旦进入 API 网关应用后,API 网关就会生成请求 ID 并通过响应头返回给客户端,建议客户端与后端服务都记录此请求 ID,可用于问题排查与跟踪。
X-Ca-Error-Message: Invalid Url
// API网关返回的错误消息,当请求出现错误时 API 网关会通过响应头将错误消息返回给客户端。
X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}
//当打开 Debug 模式后会返回 Debug 信息,此信息后期可能会有变更,仅用做联调阶段参考。
您调用 API 时,无论使用 HTTP 还是 HTTPS 协议提交请求,都需要在请求中包含签名信息。详细加密签名的计算传递方式,见下。
签名的计算 demo 请参照 API 网关控制台 SDK下载 页面的 SDK 示例。
五、请求签名说明文档
1、名词解释
1.1、域名
- 每个 API 服务都属于一个 API 分组,每个 API 分组有不同的域名。域名是由服务端绑定的独立域名,API 网关通过域名来寻址定位 API 分组。
- 域名的格式为 www.[独立域名].com/[Path]?[HTTPMethod]。
- API 网关通过域名定位到一个唯一的分组,通过 Path+HTTPMethod 确定该分组下唯一的 API。
- 您购买后在控制台 已购买的 API 可以获得 API 文档说明,若无购买行为,则可以联系 API 提供者操作授权,授权后您就可以在控制台 已授权的 API 获得 API 文档说明。
1.2、系统级 Header
- 【必选】X-Ca-Key:AppKey。
- 【必选】X-Ca-Signature:签名字符串。
- 【可选】X-Ca-Timestamp:API 调用者传递时间戳,值为当前时间的毫秒数,也就是从1970年1月1日起至今的时间转换为毫秒,时间戳有效时间为15分钟。
- 【可选】X-Ca-Nonce:API 调用者生成的 UUID,结合时间戳防重放。
- 【可选】Content-MD5 当请求 Body 非 Form 表单时,可以计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验。
- 【可选】X-Ca-Stage请求 API 所属 Stage,目前仅支持 TEST 、PRE 和 RELEASE,默认RELEASE,若您调用的 API 不在线上环境,请一定要指定该参数的值,否则会报 URL 错误。
2、签名校验
2.1、组织参与签名计算的字符串
String stringToSign=
HTTPMethod + "\n" +
Accept + "\n" + //建议显示设置 Accept Header。当 Accept 为空时,部分 Http 客户端会给 Accept 设置默认值为 */*,导致签名校验失败。
Content-MD5 + "\n"
Content-Type + "\n" +
Date + "\n" +
Headers +
Url
HTTPMethod 为全大写,如 POST。
Accept、Content-MD5、Content-Type、Date 如果为空也需要添加换行符”\n”,Headers如果为空不需要添加”\n”。
Content-MD5
Content-MD5 是指 Body 的 MD5 值,只有当 Body 非 Form 表单时才计算 MD5,计算方式为:
String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));
bodyStream 为字节数组。
Headers
Headers 是指参与 Headers 签名计算的 Header 的 Key、Value 拼接的字符串,建议对 X-Ca 开头以及自定义 Header 计算签名,注意如下参数不参与 Headers 签名计算:X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date。
- Headers 组织方法:
先对参与 Headers 签名计算的 Header的Key 按照字典排序后使用如下方式拼接,如果某个 Header 的 Value 为空,则使用 HeaderKey + “:” + “\n”参与签名,需要保留 Key 和英文冒号。
String headers =
HeaderKey1 + ":" + HeaderValue1 + "\n"\+
HeaderKey2 + ":" + HeaderValue2 + "\n"\+
...
HeaderKeyN + ":" + HeaderValueN + "\n"
将 Headers 签名中 Header 的 Key 使用英文逗号分割放到 Request 的 Header 中,Key为:X-Ca-Signature-Headers。
Url
Url 指 Path + Query + Body 中 Form 参数,组织方法:对 Query+Form 参数按照字典对 Key 进行排序后按照如下方法拼接,如果 Query 或 Form 参数为空,则 Url = Path,不需要添加 ?,如果某个参数的 Value 为空只保留 Key 参与签名,等号不需要再加入签名。
String url =
Path +
"?" +
Key1 + "=" + Value1 +
"&" + Key2 + "=" + Value2 +
...
"&" + KeyN + "=" + ValueN
注意这里 Query 或 Form 参数的 Value 可能有多个,多个的时候只取第一个 Value 参与签名计算。
2.2、计算签名
Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] keyBytes = secret.getBytes("UTF-8");
hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
String sign = new String(Base64.encodeBase64(Sha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));
secret 为 APP 的密钥。
2.3、传递签名
将计算的签名结果放到 Request 的 Header 中,Key为:X-Ca-Signature。
3、签名错误排查方法
当签名校验失败时,API网关会将服务端的 StringToSign 放到 HTTP Response 的 Header 中返回到客户端,Key为:X-Ca-Error-Message,
只需要将本地计算的 StringToSign 与服务端返回的 StringToSign 进行对比即可找到问题;
如果服务端与客户端的 StringToSign 一致请检查用于签名计算的密钥是否正确;
因为 HTTP Header 中无法表示换行,因此 StringToSign 中的换行符都被过滤掉了,对比时请忽略换行符。
4、签名 demo
签名计算的详细 demo(JAVA)请参照链接:https://github.com/aliyun/api-gateway-demo-sign-java。
在 API 网关控制台,调用 API—SDK 下载 处还有更多语种的调用 demo。
阿里云API网关(3)快速入门(调用 API)的更多相关文章
- 阿里云RDS for MySQL 快速入门——笔记
1初始化配置 1.1设置白名单 创建RDS实例后,需要设置RDS实例的白名单,以允许外部设备访问该RDS实例.默认的白名单只包含默认IP地址127.0.0.1,表示任何设备均无法访问该RDS实例. 设 ...
- 阿里云数据库MySQL版快速上手!
MySQL是全球最受欢迎的开源数据库,其在各Web应用中均有广泛部署.阿里云数据库MySQL版基于Alibaba的MySQL源码分支,经过双11高并发.大数据量的考验,拥有优良的性能和吞吐量.除此之外 ...
- 32位汇编第四讲,干货分享,汇编注入的实现,以及快速定位调用API的数量(OD查看)
32位汇编第四讲,干货分享,汇编注入的实现,以及快速定位调用API的数量(OD查看) 昨天,大家可能都看了代码了,不知道昨天有没有在汇编代码的基础上,实现注入计算器. 如果没有,今天则会讲解,不过建议 ...
- 微服务架构学习与思考(10):微服务网关和开源 API 网关01-以 Nginx 为基础的 API 网关详细介绍
微服务架构学习与思考(10):微服务网关和开源 API 网关01-以 Nginx 为基础的 API 网关详细介绍 一.为什么会有 API Gateway 网关 随着微服务架构的流行,很多公司把原有的单 ...
- 微服务架构学习与思考(11):开源 API 网关02-以 Java 为基础的 API 网关详细介绍
微服务架构学习与思考(11):开源 API 网关02-以 Java 为基础的 API 网关详细介绍 上一篇关于网关的文章: 微服务架构学习与思考(10):微服务网关和开源 API 网关01-以 Ngi ...
- 阿里云API网关(2)开放 API 并接入 API 网关
网关指南: https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl 网关控制台: https ...
- 15分钟在阿里云Kubernetes服务上快速建立Jenkins X Platform并运用GitOps管理应用发布
本文主要介绍如何在阿里云容器服务Kubernetes上快速安装部署Jenkins X Platform并结合demo实践演示GitOps的操作流程. 注意:本文中使用的jx工具.cloud-envir ...
- springcloud(十六):服务网关 zuul 快速入门
服务网关是微服务架构中一个不可或缺的部分.通过服务网关统一向外系统提供REST API的过程中,除了具备服务路由.均衡负载功能之外,它还具备了权限控制等功能.Spring Cloud Netflix中 ...
- Spring Cloud(六)服务网关 zuul 快速入门
服务网关是微服务架构中一个不可或缺的部分.通过服务网关统一向外系统提供REST API的过程中,除了具备服务路由.均衡负载功能之外,它还具备了权限控制等功能.Spring Cloud Netflix中 ...
- IPsecVPN:阿里云VPN网关和深信服防火墙打通公有云和公司内网
简介 目前许多公司网络环境为混合云(私有云,IDC,公司内网融合)的状态,通过内网ip的访问使得工作更加方便,需求也更为迫切,而本文介绍的即是实现私有云和公司内网互通的一种方法,希望对有此需求的小伙伴 ...
随机推荐
- windows7下django项目搭建
参考视频教程 http://study.163.com/course/ http://www.bilibili.com/video/av8915600/ http://www.bilibil ...
- 访问不了firefox附加组件页面怎么办
最近重新使用火狐浏览器的时候发现访问不了firefox附加组件页面了,一直是一个空白的页面,估计是被墙的原因,于是网上查了查,说是修改hosts即可,我修改后就可以正常访问了.现在分享出来: 在hos ...
- 用jquery实现日期控件
用jquery实现的日期控件,代码如下: <!DOCTYPE html> <html lang="en"> <head> <meta ch ...
- 智能合约语言 Solidity 教程系列7 - 以太单位及时间单位
这是Solidity教程系列文章第7篇介绍以太单位及时间单位,系列带你全面深入理解Solidity语言. 写在前面 Solidity 是以太坊智能合约编程语言,阅读本文前,你应该对以太坊.智能合约有所 ...
- kubernetes关键概念总结
service 每个service对应一个cluster IP,cluster IP对应的服务网段最初是在配置kube-apiserver.kube-controller-manager和kube-p ...
- Database operations of Mysql
update 表名 set 字段名=replace(同一个字段名,原字符串,新字符串); --修改记录. 一.初始化 # cd /usr/local/mysql # chown -R mysql:m ...
- 《Linux命令行与shell脚本编程大全》- 读书笔记2 - 更多的bash shell命令
更多的bash shell命令 想检测进程,需要熟悉ps命令的用法.ps命令好比工具中的瑞士军刀,它能输出运行在系统上的所有程序的许多信息.默认情况下,ps命令只会显示运行在当前控制台下的属于当前用户 ...
- 快速失败机制--fail-fast
fail-fast 机制是Java集合(Collection)中的一种错误机制.当多个线程对同一个集合的内容进行操作时,就可能会产生fail-fast(快速失败)事件.例如:当某一个线程A通过iter ...
- 【Flask】微型web框架flask大概介绍
Flask Flask是一个基于python的,微型web框架.之所以被称为微型是因为其核心非常简单,同时具有很强的扩展能力.它几乎不给使用者做任何技术决定. 安装flask时应该注意其必须的几个支持 ...
- 【Linux】 用户管理
Linux用户管理 ■ 查看用户整体情况 cat /etc/passwd可以查看用户的一些基本信息.用finger <user>似乎更加方便 查看某一个特定的用户的话就可以 grep &l ...