# 创建 Canary 版本部署
在部署具有 [Canary 设置](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings)的 API 作为对[部署创建](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html)操作的额外输入时，您可以创建 Canary 版本部署。
您还可以通过发出 [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) 请求在阶段上添加 Canary 版本设置，从现有非 Canary 版本部署创建 Canary 版本。
创建非 Canary 版本部署时，您可以指定非现有阶段名称。如果指定的阶段不存在，API Gateway 将创建一个。但是，在创建 Canary 版本部署时，您无法指定任何非现有阶段名称。您会收到错误，并且 API Gateway 不创建任何 Canary 版本部署。
您可以使用 API Gateway 控制台、AWS CLI 或AWS开发工具包在 API Gateway 中创建 Canary 版本部署。
**Topics**
+ [使用 API Gateway 控制台创建 Canary 版本部署](#create-canary-deployment-using-console)
+ [使用 AWS CLI 创建 Canary 版本部署](#create-canary-deployment-using-cli)
## 使用 API Gateway 控制台创建 Canary 版本部署
要使用 API Gateway 控制台创建 Canary 版本部署，请按照以下说明操作：
**创建初始 Canary 版本部署**
1. 登录 API Gateway 控制台。
1. 选择现有 REST API 或创建新的 REST API。
1. 在主导航窗格中，选择**资源**，然后选择**部署 API**。按照 **Deploy API (部署 API)** 中屏幕上的说明操作，将 API 部署到新阶段。
到目前为止，您已将 API 部署到生产版本阶段。接下来，您需要在阶段上配置 Canary 设置，并且在需要时还要启用缓存、设置阶段变量或者配置 API 执行或访问日志。
1. 要启用 API 缓存或将 AWS WAF Web ACL 与阶段关联，请在**阶段详细信息**部分中选择**编辑**。有关更多信息，请参阅 [API Gateway 中针对 REST API 的缓存设置](api-gateway-caching.md) 或 [使用 API Gateway 控制台将 AWS WAF Web ACL 与 API Gateway API 阶段相关联](apigateway-control-access-aws-waf.md#apigateway-control-access-aws-waf-console)。
1. 要配置执行或访问日志记录，请在**日志和跟踪**部分中选择**编辑**，并按照屏幕上的说明操作。有关更多信息，请参阅 [为 API Gateway 中的 REST API 设置 CloudWatch 日志记录](set-up-logging.md)。
1. 要设置阶段变量，请选择**阶段变量**选项卡，并按照屏幕上的说明添加或修改阶段变量。有关更多信息，请参阅 [在 API Gateway 中对 REST API 使用阶段变量](stage-variables.md)。
1. 选择**金丝雀**选项卡，然后选择**创建金丝雀**。您可能需要选择右箭头按钮以显示**金丝雀**选项卡。
1. 在**金丝雀设置**下，对于**金丝雀**，输入要转移到金丝雀的请求的百分比。
1. 如果需要，请选择**阶段缓存**以便为金丝雀版本开启缓存。除非启用 API 缓存，否则缓存对 Canary 版本不可用。
1. 要覆盖现有的阶段变量，对于**金丝雀覆盖**，请输入新的阶段变量值。
在部署阶段上初始化 Canary 版本之后，您更改了 API 并希望测试更改。您可以将 API 重新部署到相同阶段，这样可以通过同一个阶段访问更新后的版本和基础版本。以下步骤说明了如何完成此操作。
**将最新 API 版本部署到 Canary**
1. 每次更新 API 时，请选择**部署 API**。
1. 在**部署 API** 中，从**部署阶段**下拉列表中选择包含金丝雀的阶段。
1. （可选）为**部署描述**输入描述。
1. 选择 **Deploy (部署)** 将最新 API 版本推送到 Canary 版本。
1. 如果需要，可重新配置阶段设置、日志或 Canary 设置，如[创建初始 Canary 版本部署](#to-create-canary-release-on-new-deployment)中所述。
此时，Canary 版本指向最新版本，而生产版本仍指向 API 的初始版本。[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) 现在具有新的 **deploymentId** 值，而阶段仍具有最初的 [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) 值。在后台，控制台调用 [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html)。
## 使用 AWS CLI 创建 Canary 版本部署
**为新阶段创建金丝雀部署**
1. 使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令创建具有两个阶段变量但没有金丝雀的部署：
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'prod'
```
输出将与以下内容类似：
```
{
"id": "du4ot1",
"createdDate": 1511379050
}
```
1. 使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令，在 `prod` 阶段上创建金丝雀部署：
```
aws apigateway create-deployment \
--rest-api-id abcd1234 \
--canary-settings percentTraffic=10.5,stageVariableOverrides={sv1='val2',sv2='val3'},useStageCache=false \
--stage-name 'prod'
```
输出将与以下内容类似：
```
{
"id": "a6rox0",
"createdDate": 1511379433
}
```
生成的部署 `id` 标识 Canary 版本的 API 测试版本。此时关联的阶段启用了 Canary。
1. （可选）使用以下 [get-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-stage.html) 命令查看阶段表示：
```
aws apigateway get-stage --rest-api-id acbd1234 --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"}`。生产版本和 Canary 版本均使用相同的阶段变量 `sv1`，但分别具有不同值 `val1` 和 `val2`。阶段变量 `sv0` 仅用于生产版本中，阶段变量 `sv2` 仅用于 Canary 版本中。
您还可通过更新阶段来启用金丝雀，从现有常规部署创建金丝雀版本部署。
**从现有部署创建金丝雀版本部署**
1. 使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令创建没有金丝雀的部署：
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'beta'
```
1. 使用 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令更新阶段以启用金丝雀：
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name 'beta' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
输出将与以下内容类似：
```
{
"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 并将其再次部署到此阶段之后，新版本将为 Canary 版本，而基础版本保持为生产版本。在阶段演变中，Canary 的 `deploymentId` 更新为新部署 `id`，而生产版本的 `deploymentId` 保持不变，证明了这一点。