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

创建金丝雀版本部署

在部署具有金丝雀版本设置的 API 作为对部署创建操作的额外输入时,您可以创建金丝雀版本部署。

您还可以通过发出 stage:update 请求在阶段上添加金丝雀版本设置,从现有非金丝雀版本部署创建金丝雀版本。

在创建非金丝雀版本部署时,您可以指定一个不存在的阶段名称。如果指定的阶段不存在,则 API Gateway 会创建一个。但是,在创建金丝雀版本部署时,您无法指定任何非现有阶段名称。您会收到错误,并且 API Gateway 不创建任何金丝雀版本部署。

您可以在 API Gateway 中使用 API Gateway 控制台、AWS CLI、AWS 开发工具包创建 Canary 版本部署。

使用 API Gateway 控制台创建 Canary 部署

要使用 API Gateway 控制台创建金丝雀版本部署,请按照以下说明操作:

创建初始金丝雀版本部署

  1. 登录到 API Gateway 控制台。

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

  3. 如果需要,更改 API 或者设置所需 API 方法和集成。

  4. Actions (操作) 下拉菜单中选择 Deploy API (部署 API)。按照 Deploy API (部署 API) 中屏幕上的说明操作,将 API 部署到新阶段。

    到目前为止,您已将 API 部署到生产版本阶段。接下来,您需要在阶段上配置金丝雀版本设置,并且在需要时还要启用缓存、设置阶段变量或者配置 API 执行或访问日志。

  5. 要启用 API 缓存,请在 Stage Editor (阶段编辑器) 中选择设置选项卡,然后按照屏幕上的说明操作。有关更多信息,请参阅 启用 API 缓存以增强响应能力

  6. 要设置阶段变量,请在 Stage Editor (阶段编辑器) 中选择 Stage Variables (阶段变量) 选项卡,并按照屏幕上的说明添加或修改阶段变量。有关更多信息,请参阅 为 REST API 部署设置阶段变量

  7. 要配置执行或访问日志记录,请在 Stage Editor (阶段编辑器) 中选择 Logs (日志) 选项卡并按照屏幕上的说明操作。有关更多信息,请参阅 在 API Gateway 中设置 CloudWatch API 日志记录

  8. Stage Editor (阶段编辑器) 中,选择 Canary (金丝雀版本) 选项卡,然后选择 Create Canary (创建金丝雀版本)

  9. Stage's Request Distribution (阶段的请求分配) 部分下,选择 Percentage of requests to Canary (向金丝雀版本提出请求的百分比) 旁边的铅笔图标,并在输入字段中键入数字(例如 5.0)。选择对勾图标以保存设置。

  10. 要将 AWS WAF Web ACL 与阶段关联,请从 Web ACL 下拉列表中选择一个 Web ACL。

    注意

    如果需要,请选择 Create Web ACL (创建 Web ACL) 以在新的浏览器选项卡中打开 AWS WAF 控制台,创建 Web ACL,并返回到 API Gateway 控制台将 Web ACL 与阶段关联。

  11. 如果需要,请选择 Block API Request if WebACL cannot be evaluated (Fail- Close) (如果无法评估 WebACL,则阻止 API 请求 (失败 - 关闭))

  12. 如果需要,选择 Add Stage Variables (添加阶段变量) 以在 Canary Stage Variables (金丝雀版本阶段变量) 部分下添加变量,或者为金丝雀版本覆盖现有阶段变量或添加新阶段变量。

  13. 如果需要,选择 Enable use of stage cache (启用对阶段缓存的使用) 为金丝雀版本启用缓存并保存您的选择。除非启用 API 缓存,否则缓存对金丝雀版本不可用。

在部署阶段上初始化金丝雀版本之后,您更改了 API 并希望测试更改。您可以将 API 重新部署到相同阶段,这样可以通过同一个阶段访问更新后的版本和基础版本。以下步骤说明了如何完成此操作。

将最新 API 版本部署到金丝雀版本

  1. 对于 API 的每次更新,从资源列表旁的操作下拉菜单,选择 Deploy API (部署 API)

  2. Deploy API (部署 API) 中,从 Deployment stage (部署阶段) 下拉列表选择现已启用金丝雀版本的阶段。

  3. (可选)在 Deployment description (部署描述) 中键入说明。

  4. 选择部署将最新 API 版本推送到金丝雀版本。

  5. 如果需要,可重新配置阶段设置、日志或金丝雀版本设置,如创建初始金丝雀版本部署中所述。

此时,金丝雀版本指向最新版本,而生产版本仍指向 API 的初始版本。canarySettings 现在具有新的 deploymentId 值,而阶段仍具有最初的 deploymentId 值。在后台,控制台调用 stage:update

使用 AWS CLI 创建金丝雀版本部署

首先创建具有两个阶段变量但没有任何金丝雀版本的基准部署:

aws apigateway create-deployment --variables sv0=val0,sv1=val1 --rest-api-id 4wk1k4onj3 --stage-name prod

该命令返回生成的 Deployment 的表示,与以下类似:

{ "id": "du4ot1", "createdDate": 1511379050 }

生成的部署 id 标识 API 的一个快照 (或版本)。

现在,在 prod 阶段上创建金丝雀版本部署:

aws apigateway create-deployment --canary-settings '{ \ "percentTraffic":10.5, \ "useStageCache":false, \ "stageVariableOverrides":{ \ "sv1":"val2", \ "sv2":"val3" \ } \ }' \ --rest-api-id 4wk1k4onj3 \ --stage-name prod

如果指定的阶段 (prod) 不存在,则之前的命令返回错误。否则,它会返回新创建的部署资源表示,与以下内容类似:

{ "id": "a6rox0", "createdDate": 1511379433 }

生成的部署 id 标识金丝雀版本的 API 测试版本。此时关联的阶段启用了金丝雀版本。您可以通过调用 get-stage 命令来查看此阶段,与以下类似:

aws apigateway get-stage --rest-api-id 4wk1k4onj3 --stage-name prod

下面说明了以命令输出表示的 Stage

{ "stageName": "prod", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "du4ot1", "lastUpdatedDate": 1511379433, "createdDate": 1511379050, "canarySettings": { "percentTraffic": 10.5, "deploymentId": "a6rox0", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" } }, "methodSettings": {} }

在本例中,API 的基础版本将使用阶段变量 {"sv0":val0", "sv1":val1"},而测试版本使用阶段变量 {"sv1":val2", "sv2":val3"}。生产版本和金丝雀版本均使用相同的阶段变量 sv1,但分别具有不同值 val1val2。阶段变量 sv0 仅用于生产版本中,阶段变量 sv2 仅用于金丝雀版本中。

您可通过更新阶段来启用金丝雀版本,从现有常规部署创建金丝雀版本部署。为了演示此操作,首先创建一个常规部署:

aws apigateway create-deployment \ --variables sv0=val0,sv1=val1 \ --rest-api-id 4wk1k4onj3 \ --stage-name beta

该命令返回基础版本部署的表示:

{ "id": "cifeiw", "createdDate": 1511380879 }

关联的测试版阶段没有任何金丝雀版本设置:

{ "stageName": "beta", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "cifeiw", "lastUpdatedDate": 1511380879, "createdDate": 1511380879, "methodSettings": {} }

现在,通过在阶段上连接金丝雀版本创建新的金丝雀版本部署:

aws apigateway update-stage \ --patch-operations '[{ \ "op":"replace", \ "path":"/canarySettings/percentTraffic", \ "value":"10.5" \ },{ \ "op":"replace", \ "path":"/canarySettings/useStageCache", \ "value":"false" \ },{ \ "op":"replace", \ "path":"/canarySettings/stageVariableOverrides/sv1", \ "value":"val2" \ },{ \ "op":"replace", \ "path":"/canarySettings/stageVariableOverrides/sv2", \ "value":"val3" \ }]' \ --rest-api-id 4wk1k4onj3 \ --stage-name beta

更新后阶段的表示如下所示:

{ "stageName": "beta", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "cifeiw", "lastUpdatedDate": 1511381930, "createdDate": 1511380879, "canarySettings": { "percentTraffic": 10.5, "deploymentId": "cifeiw", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" } }, "methodSettings": {} }

由于我们刚刚在 API 的现有版本上启用了金丝雀版本,生产版本 (Stage) 和金丝雀版本 (canarySettings) 指向相同的部署,即 API 的相同版本 (deploymentId)。在您更改 API 并将其再次部署到此阶段之后,新版本将为金丝雀版本,而基础版本保持为生产版本。在阶段演变中,Canary 的 deploymentId 更新为新部署 id,而生产版本的 deploymentId 保持不变,证明了这一点。