首页 > 代码库 > 握手API网关（3）調用 API 网关 暴露的 开放 API

握手API网关（3）調用 API 网关 暴露的 开放 API

2024-10-31 21:46:02   205人阅读

调用 API 的三个前置条件：

  • API：您即将要调用的API，明确API参数定义。
  • 应用 app：作为您调用API时的身份，有 AppKey 和 AppSecret 用于验证您的身份。
  • API 和 App 的权限关系：App 想调用某个 API 需要具有该 API 的权限，这个权限通过授权的功能来建立。

以下会详细说如何具备三个条件，并提供 API 调用 Demo 供参考。

步骤1：获取 API 文档

从数据市场购买的 API 服务

您购买 API 服务时，如果还没有开通 API 网关服务，那么会同时帮助您开通 API 网关服务，让您使用的更流畅。

  1. 购买成功之后您进入云市场的 管理控制台，就会看见您购买的所有 API 服务。您可以在当前控制台查看 API 接口的定义。

  2. 您还可以跳转到 API 网关的控制台，在 已购买 API 页面，展示您购买的所有 API 服务列表，以及使用情况概况。

  3. 选择一个服务点击 查看 API ，页面会展示该服务的基本信息和 API 接口列表。注意在基本信息处关键的信息是 访问域名。

  4. 选择一个 API 接口，点击 详情，就会出现详细的接口定义了。

不经过购买，由提供方主动授权

提供 API 的一方需要在控制台主动操作授权，这时您需要已经创建过应用 APP，并且将 AppId告知提供方，由他们搜索您的 APP 然后操作授权。APP 的相关内容在 创建 APP 中介绍。这里先假设您已经创建了 APP，并且提供 API 的一方已经为您的 APP 授权。

  1. 您进入 API 网关的控制台应用管理页面，这里是您创建的所有应用APP。

  2. 点击 APP 的名称进入 APP 详情，此处会展示 APP 的基本信息以及两个最重要的信息。AppKey 和 已授权的 API 。

  3. AppKey 是您这个 APP 的 Key 和 Secret。您请求的时候需要带上这对密钥，网关会根据这对密钥对您进行身份验证。后面会详细解释。

  4. 已授权的 API 是您该 APP 已经被授权的 API ，如果提供方已经操作了授权，那么您会在这里看见 API 接口。点击 详情 就可以查看详细的接口定义

以上是两种 API 渠道的获取 API 定义的方式。后一种其实就涵盖了提供方自测的情形。

步骤 2：创建应用

应用（APP）是调用 API 服务时的身份。每个 APP 有一组 Key 和 Secret，您可以理解为账号密码，您调用 API 的时候需要将 AppKey 做参数传入，AppSecret 用于签名计算，网关会校验这对密钥对您进行身份认证。

调用 API 需要这个 APP 具备调用该API的权限，这个授权和鉴权也是面向 APP 的。

您可以在 API 网关控制台 应用管理 页面创建您的 APP。

创建成功后，系统会为 APP 分配一对 AppKey 和 AppSecret。您需要使用 AppSecret 完成签名计算，您请求时需要携带签名信息，网关会通过签名信息对您做身份验证。

在 应用管理 页面，点击应用名称进入详情，就能看见 AppKey 和 AppSecret 信息了，如果密钥丢失还可以操作重置。

APP 更多说明参见 用户指南（调用API）

步骤 3：获得授权

授权，是指授予 APP 调用某个 API 的权限。您的 APP 需要获得 API 的授权才能调用该API。

根据获取 API 的渠道不同，建立授权的方式也不同。

从数据市场购买的 API 服务

您购买了 API 服务就意味着您已经获得了授权。

但是为了更精确的权限控制，您的账号获得了授权，不代表您的每个 APP 都获得了授权。

您需要手动操作将已购买的API授权给哪些 APP，然后这些 APP 才能调用该API。

不经过购买，由提供方主动授权

您需要向 API 服务商提供您的 应用 ID (AppID) 或者阿里云邮箱账户，使 API 服务商能够搜索到您的 APP，并完成授权。完成授权后您可以在控制台看到该 APP 被授权的 API。

由提供方操作授权的 API 会出现在应用详情的 已授权 API 子页面。

提供方授权时就已经将 API 授权给准确的 APP 了，所以不需要您不需要也没有权限来操作授权。

步骤 4：调用 API

您可以直接用 API 网关控制台为您提供的多语言调用示例来测试调用，可以自行编辑 HTTP(s) 请求来调用 API。关于签名方式，您可以参照控制台的 SDK示例下载 。

通过上述步骤，您已经获取了 API 定义文档、创建了 APP、建立了授权关系。

您可以调用 API 了。API 的请求步骤说明如下：

第一部分：请求

请求地址

  1. http://e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com/demo/post

请求方法

  1. POST

请求体

  1. FormParam1=FormParamValue1&FormParam2=FormParamValue2
  2. //HTTP Request Body

请求头部

  1. Host: e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com
  2. Date: Mon, 22 Aug 2016 11:21:04 GMT
  3. User-Agent: Apache-HttpClient/4.1.2 (java 1.6)
  4. Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  5. //请求体类型，请根据实际请求体内容设置。
  7. Accept: application/json
  8. //请求响应体类型，部分 API 可以根据指定的响应类型来返回对应数据格式，建议手动指定此请求头，如果不设置，部分 HTTP 客户端会设置默认值 */*，导致签名错误。
  10. X-Ca-Request-Mode: debug
  11. //是否开启 Debug 模式，大小写不敏感，不设置默认关闭，一般 API 调试阶段可以打开此设置。
  13. X-Ca-Version: 1
  14. // API版本号，目前所有 API 仅支持版本号『1』，可以不设置此请求头，默认版本号为『1』。
  16. X-Ca-Signature-Headers: X-Ca-Request-Mode,X-Ca-Version,X-Ca-Stage,X-Ca-Key,X-Ca-Timestamp
  17. //参与签名的自定义请求头，服务端将根据此配置读取请求头进行签名，此处设置不包含 Content-Type、Accept、Content-MD5、Date 请求头，这些请求头已经包含在了基础的签名结构中，详情参照请求签名说明文档。
  19. X-Ca-Stage: RELEASE
  20. //请求 API的Stage，目前支持 TEST、PRE、RELEASE 三个 Stage，大小写不敏感，API 提供者可以选择发布到哪个 Stage，只有发布到指定 Stage 后 API 才可以调用，否则会提示 API 找不到或 Invalid Url。
  22. X-Ca-Key: 60022326
  23. //请求的 AppKey，请到 API 网关控制台生成，只有获得 API 授权后才可以调用，通过云市场等渠道购买的 API 默认已经给APP授过权，阿里云所有云产品共用一套 AppKey 体系，删除 ApppKey 请谨慎，避免影响到其他已经开通服务的云产品。
  25. X-Ca-Timestamp: 1471864864235
  26. //请求的时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟。
  28. X-Ca-Nonce:b931bc77-645a-4299-b24b-f3669be577ac
  29. //请求唯一标识，15分钟内 AppKey+API+Nonce 不能重复，与时间戳结合使用才能起到防重放作用。
  31. X-Ca-Signature: FJleSrCYPGCU7dMlLTG+UD3Bc5Elh3TV3CWHtSKh1Ys=
  32. //请求签名。
  34. CustomHeader: CustomHeaderValue
  35. //自定义请求头，此处仅作为示例，实际请求中根据 API定义可以设置多个自定义请求头。

第二部分：响应

状态码

  1. 400
  2. //响应状态码，大于等于200小于300表示成功；大于等于400小于500为客户端错误；大于500为服务端错误。

响应头

  1. X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
  2. //请求唯一 ID，请求一旦进入 API 网关应用后，API 网关就会生成请求 ID 并通过响应头返回给客户端，建议客户端与后端服务都记录此请求 ID，可用于问题排查与跟踪。
  4. X-Ca-Error-Message: Invalid Url
  5. // API网关返回的错误消息，当请求出现错误时 API 网关会通过响应头将错误消息返回给客户端。
  7. X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}
  8. //当打开 Debug 模式后会返回 Debug 信息，此信息后期可能会有变更，仅用做联调阶段参考。

您调用 API 时，无论使用 HTTP 还是 HTTPS 协议提交请求，都需要在请求中包含签名信息。详细加密签名的计算传递方式，请查看文档 请求签名说明文档。

签名的计算 demo 请参照 API 网关控制台 SDK下载 页面的 SDK 示例。

若需要了解更多详情，请您查看 使用手册（调用 API）。

握手API网关（3）調用 API 网关 暴露的 开放 API


联系
我们