登录控制台
Amazon API Gateway
开发人员指南
AWS 文档 » Amazon API Gateway » 开发人员指南 » 在 Amazon API Gateway 中创建、部署和调用 REST API » 在 API Gateway 中控制和管理对 REST API 的访问 » 创建和使用带 API 密钥的使用计划 » 使用 API Gateway CLI 和 REST API 创建、配置和测试使用计划
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 密钥。在负载中指定 keyId 和 keyType。

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

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

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

      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 的错误信息。您可以忽略此类偶尔出现的错误。