Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

设置 API Gateway Canary 版本部署

Canary 版本是一种软件开发战略，部署新版本的 API（以及其他软件）用于测试，而在相同阶段基础版本仍部署为生产版本用于正常运营。在本文档中，为了方便讨论，我们将基础版本称为生产版本。虽然这样做是合理的，您也可以随意在任意非生产版本上应用 Canary 版本进行测试。

在 Canary 版本部署中，全部 API 流量按照预配置的比率，随机拆分到生产版本和 Canary 版本中。通常，Canary 版本接收少量百分比的 API 流量，生产版本接受剩余部分。更新后的 API 特征仅对流经 Canary 的 API 流量可见。您可以调整 Canary 流量百分比来优化测试覆盖范围或性能。

通过将 Canary 流量保持在较小的比例并随机进行选择，大部分用户在任何时间都不会受到新版本中潜在错误的不利影响，而且没有任何一个用户会始终受到不利影响。

在测试指标满足您的要求之后，可以将金丝雀版本提升为生产版本，并在部署中禁用 Canary 版本。这使得新特征在生产阶段中可用。

API Gateway 中的 Canary 版本部署

在 API Gateway 中，Canary 版本部署将部署阶段用于 API 基础版本的生产版本，并将 Canary 版本连接到阶段，用于提供 API 相对于基础版本的新版本。该阶段与初始部署关联，Canary 与后续部署关联。在一开始，阶段和 Canary 均指向相同的 API 版本。在这一部分中，我们所说的阶段和生产版本是可以互换的，Canary 和 Canary 版本也是可以互换的。

要部署带有 Canary 版本的 API，您必须将 Canary 设置添加到常规部署的阶段。Canary 设置描述基本金丝雀版本，阶段表示此部署中 API 的生产版本。要添加 Canary 设置，请在部署阶段上设置 canarySettings 并指定以下内容：

启用 Canary 版本之后，除非禁用 Canary 版本并从阶段中删除 Canary 设置，否则部署阶段无法与其他非 Canary 版本部署关联。

当您启用 API 执行日志记录时，Canary 版本为所有 Canary 请求生成自己的日志和指标。它们报告给生产阶段 CloudWatch Logs 日志组，以及 Canary 版本特定的 CloudWatch Logs 日志组。访问日志记录也是如此。单独的 Canary 特定日志非常有用，可用于验证新 API 更改以及决定是否接受更改并将 Canary 版本提升为生产版本，或者放弃更改并从生产阶段还原 Canary 版本。

生产阶段执行日志组名为 API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}，Canary 版本执行日志组名为 API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary。对于访问日志记录，您必须创建新日志组或者选择现有日志组。Canary 版本访问日志组名称具有 /Canary 后缀，附加到选定的日志组名中。

Canary 发布可以使用阶段缓存（如果启用），并在预定义的生存时间 (TTL) 周期内，使用缓存的条目将结果返回到下一个 Canary 发布请求。

在 Canary 版本部署中，API 的生产版本和 Canary 版本可以关联到同一个版本，也可以关联到不同版本。当它们与不同版本关联时，来自生产和 Canary 请求的响应单独缓存，阶段缓存返回生产和 Canary 请求的对应结果。当生产版本和 Canary 版本关联到同一个部署时，阶段缓存为两种类型的请求使用单个缓存键，并为来自生产版本和 Canary 版本的相同请求返回相同响应。