Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

创建和使用 API Gateway 使用计划

创建、测试和部署 API 后,您可以实施 API Gateway 使用计划,将它们扩展为面向客户的产品/服务。您可以提供使用计划,以允许指定的客户按照商定的可满足其业务需求和预算限制的请求速率和配额来访问选定 API。

什么是使用计划?

使用计划规定谁可以访问一个或多个部署的 API 阶段,以及调用方访问 API 的数量和速度如何。该计划使用 API 密钥,通过在单独客户端 API 密钥上实施的可配置限制和配额限制,确定 API 客户端并计量对 API 阶段的访问。

该限制规定应用于每个 API 密钥的请求速率限制。配额是在指定的时间间隔内提交的包含给定 API 密钥的最大请求数。您可以配置单独的 API 方法,要求根据使用计划配置进行 API 密钥授权。API 阶段由 API 标识符和阶段名称进行标识。

注意

限制和配额限制适用于跨一个使用计划内的所有 API 阶段聚合的各个 API 密钥的请求。

您可以在 API Gateway 中生成 API 密钥或者从外部来源将其导入到 API Gateway 中。有关更多信息,请参阅 使用 API Gateway 控制台设置 API 密钥

公开 API 密钥源

当您为 API 制定使用计划并在 API 方法上启用 API 密钥时,传入请求必须具有合适的 API 密钥。API Gateway 从传入请求读取此 API 密钥并通过使用计划中的密钥进行验证。如果密钥匹配,API Gateway 将根据计划的请求限制和配额限制请求。否则,将引发 InvalidKeyParameter 异常。作为结果,调用方将收到 403 Forbidden 响应。

API Gateway 可以从两种资源中接收 API 密钥。您可以将密钥分发到客户端开发人员,在您需要 API 方法上的 API 密钥时,要求客户端将 API 密钥作为传入请求的 X-API-Key 标头传递。这称为 HEADER 源,因为 API Gateway 从标头中读取它。或者,您可以让自定义授权方将 API 密钥作为自定义授权响应的一部分返回。有关自定义授权响应的更多信息,请参阅 来自 Amazon API Gateway 自定义授权方的输出。这称为 AUTHORIZER 源,因为 API Gateway 从授权方输出中读取它。

要使用 API Gateway 控制台选择 API 密钥源,请按照以下说明操作:

使用 API Gateway 控制台为 API 选择 API 密钥源:

  1. 登录 API Gateway 控制台。

  2. 选择现有 API 或者创建新 API。

  3. 在主导航窗格中选定的或新创建的 API 下,选择 Settings

  4. Settings 窗格中的 API Key Source 部分下方,从下拉列表中选择 HEADERAUTHORIZER

  5. 选择 Save Changes

要使用 AWS CLI 为 API 选择 API 密钥源,请按以下所示调用 update-rest-api 命令:

aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER

要让客户端提交 API 密钥,请在以上 CLI 命令中将 value 设置为 HEADER

要使用 API Gateway REST API 为 API 选择 API 密钥源,请按以下所示调用 restapi:update

PATCH /restapis/fugvjdxtri/ HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20160603T205348Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash} { "patchOperations" : [ { "op" : "replace", "path" : "/apKeySource", "value" : "HEADER" } ] }

要让授权方返回 API 密钥,请在之前的 patchOperations 输入中将 value 设置为 AUTHORIZER

请使用以下过程之一使用以标头为源的 API 密钥,或返回授权的 API 密钥进行方法调用,具体取决于您选择的 API 密钥源类型:

使用以标头为源的 API 密钥进行方法调用:

  1. 使用所需的 API 方法创建 API。将 API 部署到相关的阶段。

  2. 新建使用计划,或选择现有使用计划。将部署的 API 阶段添加到使用计划。为使用计划附加 API 密钥,或在计划中选择现有 API 密钥。请记下所选的 API 密钥值。

  3. 设置 API 方法以获得 API 密钥。

  4. 将此 API 重新部署到同一阶段。如果将此 API 部署到新阶段,请确保更新使用计划,附加新的 API 阶段。

客户端现在可以调用 API 方法,同时为 x-api-key 标头提供所选的 API 密钥作为标头值。

使用返回授权的 API 密钥进行方法调用:

  1. 使用所需的 API 方法创建 API。将 API 部署到相关的阶段。

  2. 新建使用计划,或选择现有使用计划。将部署的 API 阶段添加到使用计划。为使用计划附加 API 密钥,或在计划中选择现有 API 密钥。请记下所选的 API 密钥值。

  3. 创建令牌类型的自定义 Lambda 授权方。包括 usageIdentifierKey:{api-key} (作为授权响应的根级属性),其中 {api-key} 代表上一步中提到的 API 密钥值。

  4. 设置 API 方法,以获得 API 密钥,并针对这些方法启用自定义令牌授权方。

  5. 将此 API 重新部署到同一阶段。如果将此 API 部署到新阶段,请确保更新使用计划,附加新的 API 阶段。

客户端现在可以调用获得了 API 密钥的方法,而无需明确提供 API 密钥。返回授权方的 API 密钥将自动使用。

如何配置使用计划?

以下步骤概述了作为 API 所有者,您如何为客户配置使用计划。

配置使用计划

  1. 创建一个或多个 API,将方法配置为需要 API 密钥,并在各阶段部署 API。

  2. 使用您的 API 生成 API 密钥并将密钥分发给应用程序开发人员 (您的客户)。

  3. 创建具有所需限制和配额限制的使用计划。

  4. 将选定 API 阶段和 API 密钥与使用计划进行关联。

API 调用方必须在 API 请求的 x-api-key 标头中提供一个已分配的 API 密钥。

注意

要在使用计划中包括 API 方法,您必须将单独的 API 方法配置为需要 API 密钥。对于用户身份验证和授权,请勿使用 API 密钥。使用 IAM 角色、自定义授权方Amazon Cognito 用户池

下面几节提供了关于这些任务的详细说明。

使用 API Gateway 控制台设置 API 密钥

要设置 API 键,请执行以下操作:

  • 将 API 方法配置为需要 API 键。

  • 为区域的 API 创建或导入 API 键。

在设置 API 键之前,您必须先创建一个 API 并将其部署到某个阶段。

有关如何使用 API Gateway 控制台创建和部署 API 的说明,请分别参阅在 Amazon API Gateway 中创建 API在 Amazon API Gateway 中部署 API

要求方法使用 API

以下过程介绍如何将 API 方法配置为需要 API 密钥。

将 API 方法配置为需要 API 密钥

  1. 登录 AWS 管理控制台 并通过 https://console.amazonaws.cn/apigateway/ 打开 API Gateway 控制台。

  2. 在 API Gateway 主导航窗格中,选择 Resources

  3. Resources 下,创建新方法或选择现有方法。

  4. 选择 Method Request

  5. Authorization Settings 部分下,为 API Key Required 选择 true

  6. 选择对勾图标以保存设置。

  7. 部署或重新部署 API 以使该要求生效。

如果 API Key Required 选项设置为 false 并且您没有执行上述步骤,则与 API 阶段关联的任何 API 密钥都不会用于该方法。

创建 API 密钥

如果您已创建或导入 API 密钥以用于使用计划,则可跳过此过程和下一过程。

创建 API 密钥

  1. 登录 AWS 管理控制台 并通过 https://console.amazonaws.cn/apigateway/ 打开 API Gateway 控制台。

  2. 在 API Gateway 主导航窗格中,选择 API Keys

  3. Actions 下拉菜单中,选择 Create API key

     为使用计划创建 API 密钥
  4. Create API Key 中,执行以下操作:

    1. Name 输入字段中,键入一个 API 密钥名称 (例如 MyFirstKey)。

    2. 选择 Auto Generate 可让 API Gateway 生成密钥值,或选择 Custom 可手动输入密钥。

    3. 选择 Save

     为使用计划创建 API 密钥
  5. 如果需要,重复上述步骤以创建多个 API 密钥。

导入 API 密钥

以下过程介绍如何导入 API 密钥以用于使用计划。

导入 API 密钥

  1. 在主导航窗格中,选择 API Keys

  2. Actions 下拉菜单中,选择 Import API keys

  3. 要加载逗号分隔的密钥文件,请选择 Select CSV File。您也可以手动键入密钥。有关文件格式的信息,请参阅 API Gateway API 密钥文件格式

     API 使用计划实体
  4. 选择 Fail on warnings 以在出现错误时停止导入,或选择 Ignore warnings 以在出现错误时继续导入有效的密钥条目。

  5. 要开始导入选定的 API 密钥,请选择 Import

您已设置 API 密钥,现在可以继续创建和实施使用计划