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

使用 API Gateway CLI 和 REST API 创建、配置和测试使用计划

配置使用计划之前,必须已执行以下操作:将选定 API 的方法设置为需要 API 密钥,将 API 部署或重新部署到某个阶段,并且创建或导入一个或多个 API 密钥。有关更多信息,请参阅 使用 API Gateway REST API 设置 API 密钥

要使用 API Gateway REST API 配置使用计划,请按照以下说明操作(假设您已创建要添加到使用计划的 API)。

迁移到默认使用计划

首次创建使用计划时,可通过调用包含以下正文的 account:update,将与选定 API 密钥关联的现有 API 阶段迁移到某个使用计划:

{ "patchOperations" : [ { "op" : "add", "path" : "/features", "value" : "UsagePlans" } ] }

有关迁移与 API 密钥关联的 API 阶段的更多信息,请参阅 迁移到 API Gateway 控制台中的默认使用计划

创建使用计划

以下过程介绍如何创建使用计划。

使用 REST API 创建使用计划

  1. 调用 usageplan:create 创建使用计划。在负载中指定该计划的名称和描述、关联的 API 阶段、速率限制和配额。

    记下生成的使用计划标识符。您在下一个步骤中需要用到它。

  2. 请执行下列操作之一:

    1. 调用 usageplankey:create 以向使用计划中添加 API 密钥。在负载中指定 keyIdkeyType

      要向使用计划添加更多 API 密钥,请重复之前的调用,每次添加一个 API 密钥。

    2. 调用 apikey:import 以直接向指定的使用计划添加一个或多个 API 密钥。请求负载应包含 API 密钥值、关联的使用计划标识符、布尔值标记 (用于表明已为使用计划启用密钥),还可能包含 API 密钥名称和描述。

      以下 apikey:import 请求示例将向一个使用计划 (用 key 进行标识) 添加三个 API 密钥 (用 namedescriptionusageplanIds 进行标识):

      POST /apikeys?mode=import&format=csv&failonwarnings=fase HTTP/1.1 Host: apigateway.us-east-1.amazonaws.com Content-Type: text/csv Authorization: ... key,name, description, enabled, usageplanIds abcdef1234ghijklmnop8901234567, importedKey_1, firstone, tRuE, n371pt abcdef1234ghijklmnop0123456789, importedKey_2, secondone, TRUE, n371pt abcdef1234ghijklmnop9012345678, importedKey_3, , true, n371pt

      因此,将创建三个 UsagePlanKey 资源并将其添加到 UsagePlan

      您也可以通过这种方式向多个使用计划添加 API 密钥。要执行此操作,请将每个 usageplanIds 列值更改为逗号分隔的字符串,其中包含选定的使用计划标识符并用引号引起来 ("n371pt,m282qs"'n371pt,m282qs')。

      注意

      一个 API 密钥可与多个使用计划关联。一个使用计划可与多个阶段关联。但是,对于 API 的每个阶段,给定 API 密钥只能与一个使用计划关联。

使用 AWS CLI 管理使用计划

以下代码示例说明如何通过调用 update-usage-plan 命令在使用计划中添加、删除或修改方法级别的限制设置。

注意

确保为您的 API 将 us-east-1 更改为相应的区域值。

要添加或替换用于限制单个资源和方法的速率限制,请执行以下操作:

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="replace",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>/rateLimit",value="0.1"

要添加或替换用于限制单个资源和方法的突增限制,请执行以下操作:

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="replace",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>/burstLimit",value="1"

要删除单个资源和方法的方法级别限制设置,请执行以下操作:

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="remove",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>",value=""

要删除 API 的所有方法级别限制设置,请执行以下操作:

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="remove",path="/apiStages/<apiId>:<stage>/throttle ",value=""

下面是使用 Pet Store 示例 API 的示例:

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="replace",path="/apiStages/<apiId>:<stage>/throttle",value='"{\"/pets/GET\":{\"rateLimit\":1.0,\"burstLimit\":1},\"//GET\":{\"rateLimit\":1.0,\"burstLimit\":1}}"'

测试使用计划

为了举例说明,我们将使用在教程:通过导入示例创建 REST API中创建的 PetStore API。假定 API 被配置为使用 API 密钥 Hiorr45VR...c4GJc。以下步骤介绍如何测试使用计划。

测试您的使用计划

  • 使用 GET 查询参数对使用计划中的 API (例如 /pets) 的 Pets 资源 (?type=...&page=...) 发出 xbvxlpijch 请求:

    GET /testStage/pets?type=dog&page=1 HTTP/1.1 x-api-key: Hiorr45VR...c4GJc Content-Type: application/x-www-form-urlencoded Host: xbvxlpijch.execute-api.ap-southeast-1.amazonaws.com X-Amz-Date: 20160803T001845Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160803/ap-southeast-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature={sigv4_hash}

    注意

    必须将此请求提交至 API Gateway 的 execute-api 组件,并在所需的 x-api-key 标头中提供所需的 API 密钥(例如Hiorr45VR...c4GJc)。

    成功的响应会返回 200 OK 状态代码以及包含来自后端的请求结果的负载。如果您忘记设置 x-api-key 标头或使用不正确的密钥进行设置,则会收到 403 Forbidden 响应。不过,如果您未将方法配置为需要 API 密钥,则可能会收到 200 OK 响应 (无论是否正确设置 x-api-key 标头),并且会绕过使用计划的限制和配额限制。

    有时,当出现使 API Gateway 无法对请求实施使用计划限制或配额的内部错误时,API Gateway 将处理该请求,而不会应用使用计划中指定的限制或配额。不过,它会在 CloudWatch 中记录 Usage Plan check failed due to an internal error 的错误信息。您可以忽略此类偶尔出现的错误。