# 提升 Canary 版本
<a name="promote-canary-deployment"></a>

当您提升金丝雀版本时，金丝雀版本会取代当前的阶段设置。提升 Canary 版本不会在阶段上禁用 Canary。要禁用 Canary，您必须在阶段上删除 Canary 设置。要提升金丝雀版本，请执行以下操作：
+ 使用 Canary 的[部署 ID](https://docs.amazonaws.cn/apigateway/latest/api/API_Stage.html#canarySettings) 设置重置阶段的[部署 ID](https://docs.amazonaws.cn/apigateway/latest/api/API_Stage.html#deploymentId)。这会使用 Canary 的快照更新阶段的 API 快照，使得测试版本也成为生产版本。
+ 使用 Canary 阶段变量更新阶段变量（如有）。这会使用 Canary 的内容更新阶段的 API 执行上下文。没有此更新时，如果测试版本使用不同的阶段变量或者现有阶段变量的不同值，新 API 版本可能会造成意外的结果。
+ 将 Canary 流量的百分比设置为 0.0%。

**Topics**
+ [使用 API Gateway 控制台提升 Canary 版本](#promote-canary-release-deployment-console)
+ [使用 Amazon CLI 提升 Canary 版本](#promote-canary-release-cli)

## 使用 API Gateway 控制台提升 Canary 版本
<a name="promote-canary-release-deployment-console"></a>

要使用 API Gateway 控制台提升 Canary 版本部署，请执行以下步骤：

**提升金丝雀版本部署**

1.  登录 API Gateway 控制台并在主导航窗格中选择现有 API。

1.  在主导航窗格中，选择**阶段**，然后选择一个现有阶段。

1.  选择**金丝雀**选项卡。

1.  选择**提升金丝雀**。

1.  确认所做的更改，然后选择**提升金丝雀**。

提升之后，生产版本引用相同的 API 版本 (**deploymentId**) 作为 Canary 版本。您可以使用 Amazon CLI 验证此项。有关示例，请查看[使用 Amazon CLI 提升 Canary 版本](#promote-canary-release-cli)。

## 使用 Amazon CLI 提升 Canary 版本
<a name="promote-canary-release-cli"></a>

要使用 Amazon CLI 命令将 Canary 版本提升到生产版本，请调用 `update-stage` 命令以将与 Canary 版本关联的 `deploymentId` 复制到与阶段关联的 `deploymentId`，将 Canary 版本流量百分比重置为零 (`0.0`)，并且将任意 Canary 版本绑定阶段变量复制到对应的阶段绑定变量。

假设我们有一个 Canary 版本部署，由类似于以下内容的阶段描述：

```
{
    "_links": {
        ...
    },
    "accessLogSettings": {
        ...
    },
    "cacheClusterEnabled": false,
    "cacheClusterStatus": "NOT_AVAILABLE",
    "canarySettings": {
        "deploymentId": "eh1sby",
        "useStageCache": false,
        "stageVariableOverrides": {
            "sv2": "val3",
            "sv1": "val2"
        },
        "percentTraffic": 10.5
    },
    "createdDate": "2017-11-20T04:42:19Z",
    "deploymentId": "nfcn0x",
    "lastUpdatedDate": "2017-11-22T00:54:28Z",
    "methodSettings": {
        ...
    },
    "stageName": "prod",
    "variables": {
        "sv1": "val1"
    }
}
```

使用以下 [update-stage](https://docs.amazonaws.cn/cli/latest/reference/apigateway/update-stage.html) 命令提升金丝雀：

```
aws apigateway update-stage  \
    --rest-api-id {rest-api-id}  \
    --stage-name '{stage-name}'  \
    --patch-operations '[{                                
        "op": "replace",                                  
        "value": "0.0",                                    
        "path": "/canarySettings/percentTraffic"         
      }, {                                                
        "op": "copy",                                     
        "from": "/canarySettings/stageVariableOverrides", 
        "path": "/variables"                             
      }, {                                                
        "op": "copy",                                     
        "from": "/canarySettings/deploymentId",           
        "path": "/deploymentId"                           
      }]'
```

输出将与以下内容类似：

```
{
    "_links": {
        ...
    },
    "accessLogSettings": {
        ...
    },
    "cacheClusterEnabled": false,
    "cacheClusterStatus": "NOT_AVAILABLE",
    "canarySettings": {
        "deploymentId": "eh1sby",
        "useStageCache": false,
        "stageVariableOverrides": {
            "sv2": "val3",
            "sv1": "val2"
        },
        "percentTraffic": 0
    },
    "createdDate": "2017-11-20T04:42:19Z",
    "deploymentId": "eh1sby",
    "lastUpdatedDate": "2017-11-22T05:29:47Z",
    "methodSettings": {
        ...
    },
    "stageName": "prod",
    "variables": {
        "sv2": "val3",
        "sv1": "val2"
    }
}
```

将金丝雀版本提升到阶段并不会禁用该金丝雀版本，部署仍然是金丝雀版本部署。要使其成为常规生产版本部署，您必须禁用 Canary 设置。有关如何禁用 Canary 版本部署的更多信息，请参阅 [关闭金丝雀版本](delete-canary-deployment.md)。