概述您可以通过 API 网关, 调用由其他阿里云用户或者第三方服务商开放的 API 服务 API 网关将为您提供一系列管理服务与支撑调用 API 您可以直接用 API 网关控制台为您提供的多语言调用示例来测试调用您也可以自行编辑 HTTP(s) 请求调用 API 签名方式您可以参照控制台的

Size: px

Start display at page:

Download "概述您可以通过 API 网关, 调用由其他阿里云用户或者第三方服务商开放的 API 服务 API 网关将为您提供一系列管理服务与支撑调用 API 您可以直接用 API 网关控制台为您提供的多语言调用示例来测试调用您也可以自行编辑 HTTP(s) 请求调用 API 签名方式您可以参照控制台的"

娴誉杜
6 years ago
Views:

2 概述您可以通过 API 网关, 调用由其他阿里云用户或者第三方服务商开放的 API 服务 API 网关将为您提供一系列管理服务与支撑调用 API 您可以直接用 API 网关控制台为您提供的多语言调用示例来测试调用您也可以自行编辑 HTTP(s) 请求调用 API 签名方式您可以参照控制台的 SDK 示例下载 API 调用方式说明及示例如下 :( 调用 API 前期流程请参照快速入门 ( 调用 API)) 1. 请求请求地址请求方法 POST 请求体 FormParam1=FormParamValue1&FormParam2=FormParamValue2 //HTTP Request Body 请求头部 Host: e710888d3ccb4638a723ff8d cn-qingdao.aliapi.com Date: Mon, 22 Aug :21:04 GMT User-Agent: Apache-HttpClient/4.1.2 (java 1.6) Content-Type: application/x-www-form-urlencoded; charset=utf-8 // 请求体类型, 请根据实际请求体内容设置 1

3 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: // 请求的 AppKey, 请到 API 网关控制台生成, 只有获得 API 授权后才可以调用, 通过云市场等渠道购买的 API 默认已经给 APP 授过权, 阿里云所有云产品共用一套 AppKey 体系, 删除 ApppKey 请谨慎, 避免影响到其他已经开通服务的云产品 X-Ca-Timestamp: // 请求的时间戳, 值为当前时间的毫秒数, 也就是从 1970 年 1 月 1 日起至今的时间转换为毫秒, 时间戳有效时间为 15 分钟 X-Ca-Nonce:b931bc77-645a-4299-b24b-f3669be577ac // 请求唯一标识,15 分钟内 AppKey+API+Nonce 不能重复, 与时间戳结合使用才能起到防重放作用 X-Ca-Signature: FJleSrCYPGCU7dMlLTG+UD3Bc5Elh3TV3CWHtSKh1Ys= // 请求签名 CustomHeader: CustomHeaderValue // 自定义请求头, 此处仅作为示例, 实际请求中根据 API 定义可以设置多个自定义请求头 2. 响应状态码 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 信息, 此信息后期可能会有变更, 仅用做联调阶段参考 2

4 您调用 API 时, 无论使用 HTTP 还是 HTTPS 协议提交请求, 都需要在请求中包含签名信息 AppKey 用于标识您的身份,AppSecret 是用于加密签名字符串和服务器端验证签名字符串的密钥详细加密签名的计算传递方式, 请查看文档请求签名说明文档签名的计算 demo 请参照 API 网关控制台 SDK 下载页面的 SDK 示例若需要了解更多详情, 请您查看您需要创建应用 (APP) 作为您调用 API 的身份, 每个 APP 有一对 AppKey 和 AppSecret 密钥对,AppKey 需要在请求时作为参数在 Header 传入,AppSecret 需要用于计算请求签名 1. 在 API 网关, 您需要创建应用 (APP) 作为请求者的身份 APP 创建时, 系统会自动分配一对 AppKey 和 AppSecret 在您请求 API 时, 需要用到密钥详细加密签名的计算传递方式, 请查看文档请求签名说明文档 2. AppKey 和 AppSecret 密钥对, 具备该 APP 的全部权限, 需要妥善保管如果发生泄漏, 您可以在 API 网关的控制台进行重置 3. 您可以拥有多个 APP, 可以根据您的业务需求分别被授权不同的 API 注意,API 的授权对象是 APP 而不是阿里云用户账号 4. 您可以在 API 网关控制台完成对 APP 的创建修改删除查看详情密钥管理查看已授权等管理操作授权, 是指授予某个 APP 调用某个 API 的权限您的 APP 需要获得 API 的授权才能调用该 API - 如果您在市场购买了 API, 那么您有权操作已购买的 API 授权给您的 APP; 如果您没有 APP, 购买时云市场会为您创建一个 APP, 并且授权, 具体请前往云市场的控制台查看 - 如果您想要使用合作伙伴提供的 API, 并无购买行为, 是线下协议那么需要 API 的提供者主动操作授权您需要自行创建 APP, 并且向 API 的提供者提供您的 AppId 您调用 API 时, 需要拼接签名字符串, 并将签名计算后的字符串放在请求的 Header 传入, 网关会通过对称计算签名来验证请求者的身份 1. 在请求的 Header 需要传入一个计算后的签名字符串 2. 您需要将入参信息按照请求签名说明文档组织成为 String to sign, 再用 SDK 样例中的算法计算签名计算结果就是上面提到的计算后的签名字符串 3. HTTP 和 HTTPS 请求, 都需要加入请求签名请求签名 String to sign 的组织方法详见请求签名说明文档, 您只需要在 SDK 样例中, 将 AppKey AppSecret 换成您自己的真实密钥值, 再根据实际 API 文档按照签名文档组织 String to sign, 您就可以成功发起请求了 - 每个账号下 app 个数上限为 10 个,app 名称应为账号下唯一 - 调用 API 的流控限制为, 单个 IP,QPS 不超过您有权操作购买的 API 与 app 的授权和解除授权由服务提供方授权给您 app 的 API, 您无权操作解除授权 3

5 - 您的请求需要包含签名信息, 请参照文档请求签名说明文档域名 - 每个 API 服务都属于一个 API 分组, 每个 API 分组有不同的域名域名是由服务端绑定的独立域名,API 网关通过域名来寻址定位 API 分组 - 域名的格式为独立域名 ].com/[path]?[httpmethod] - API 网关通过域名定位到一个唯一的分组, 通过 Path+HTTPMethod 确定该分组下唯一的 API - 您购买后在控制台已购买的 API 可以获得 API 文档说明, 若无购买行为, 则可以联系 API 提供者操作授权, 授权后您就可以在控制台已授权的 API 获得 API 文档说明系统级 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 错误签名校验组织参与签名计算的字符串 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 如果为空不需 4

6 要添加 \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 + "=" + Value "&" + KeyN + "=" + ValueN 注意这里 Query 或 Form 参数的 Value 可能有多个, 多个的时候只取第一个 Value 参与签名计算 5

7 计算签名 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(hmacSha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8")); secret 为 APP 的密钥传递签名将计算的签名结果放到 Request 的 Header 中,Key 为 :X-Ca-Signature 签名错误排查方法当签名校验失败时,API 网关会将服务端的 StringToSign 放到 HTTP Response 的 Header 中返回到客户端,Key 为 :X-Ca-Error-Message, 只需要将本地计算的 StringToSign 与服务端返回的 StringToSign 进行对比即可找到问题 ; 如果服务端与客户端的 StringToSign 一致请检查用于签名计算的密钥是否正确 ; 因为 HTTP Header 中无法表示换行, 因此 StringToSign 中的换行符都被过滤掉了, 对比时请忽略换行符签名 demo 签名计算的详细 demo(java) 请参照链接 : 在 API 网关控制台, 调用 API SDK 下载处还有更多语种的调用 demo 6

上述字符串的 MD5 值即为签名的值 (32 位小写 ) 将签名值放在请求的参数中例如 sign=md5_sign 服务端 SDK 调用 API 的应用的私钥 Secret Key 为 appsecret /** parammap 请求参数 secret 密钥 *

上述字符串的 MD5 值即为签名的值 (32 位小写 ) 将签名值放在请求的参数中例如 sign=md5_sign 服务端 SDK 调用 API 的应用的私钥 Secret Key 为 appsecret /** parammap 请求参数 secret 密钥 * 集成推送平台接口说明 API 接口规范接口响应规范 HTTP 接口遵循魅族 API 协议规范返回数据格式统一如下 : code :, // 必选, 返回码 message :, // 可选, 返回消息, 网页端接口出现错误时使用此消息展示给用户, 手机端可忽略此消息, 甚至服务端不传输此消息 value :,// 必选, 返回结果 Api returncode 定义 code value 200