本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 建立 Canary Release 部署
<a name="create-canary-deployment"></a>

部署將 [Canary 設定](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings)做為[部署建立](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html)操作額外輸入的 API 時，請建立 Canary Release 部署。

您也可以提出在階段上新增 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 Release 部署。

建立非 Canary Release 部署時，您可以指定非現有階段名稱。如果指定的階段不存在，則 API Gateway 會建立階段。不過，建立 Canary Release 部署時，您無法指定任何非現有階段名稱。您將會收到錯誤，而且 API Gateway 不會建立 Canary Release 部署。

 您可以使用 API Gateway 主控台 AWS CLI、 或 AWS SDK 在 API Gateway 中建立 Canary Release 部署。

**Topics**
+ [使用 API Gateway 主控台建立 Canary 部署](#create-canary-deployment-using-console)
+ [使用 建立 Canary 部署 AWS CLI](#create-canary-deployment-using-cli)

## 使用 API Gateway 主控台建立 Canary 部署
<a name="create-canary-deployment-using-console"></a>

若要使用 API Gateway 主控台來建立 Canary Release 部署，請遵循下面的說明：<a name="to-create-canary-release-on-new-deployment"></a>

**建立初始 Canary Release 部署**

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.  選擇 **Canary** 索引標籤，然後選擇**建立 Canary**。您可能需要選擇向右箭頭按鈕才能顯示 **Canary** 索引標籤。

1.  在 **Canary 設定**下，針對 **Canary** 輸入要轉移至 Canary 的請求百分比。

1. 如有需要，請選取**階段快取**以開啟 Canary 版本的快取功能。除非啟用 API 快取，否則快取不適用於 Canary Release。

1. 若要覆寫現有的階段變數，請針對 **Canary 覆寫**輸入新的階段變數值。

在部署階段初始化 Canary Release 之後，您變更 API 而且想要測試變更。您可以將 API 重新部署至相同階段，以透過相同的階段存取更新過的版本和基本版本。下列步驟說明如何執行這項操作。<a name="to-deploy-latest-api-to-canary-release"></a>

**將最新的 API 版本部署至 Canary**

1.  每次 API 更新時，選擇**部署 API**。

1.  在**部署 API** 中，從**部署階段**下拉式清單中選擇包含 Canary 的階段。

1.  (選用) 在**部署描述**中輸入描述。

1.  選擇 **Deploy (部署)**，將最新的 API 版本推送至 Canary Release。

1.  如有需要，請重新設定階段設定、日誌或 Canary 設定，如「[建立初始 Canary Release 部署](#to-create-canary-release-on-new-deployment)」中所述。

 因此，Canary Release 會指向最新版本，而生產版本仍然指向 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)。

## 使用 建立 Canary 部署 AWS CLI
<a name="create-canary-deployment-using-cli"></a>

**為新階段建立 Canary 部署**

1. 使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令建立包含兩個階段變數但沒有 Canary 的部署：

   ```
   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` 階段上建立 Canary 部署：

   ```
   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 Release 的 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 Release 使用相同的階段變數 `sv1`，但分別具有不同的值 `val1` 和 `val2`。階段變數 `sv0` 單獨用於生產版本，而階段變數 `sv2` 用於 Canary Release 中。

您也可以更新階段以啟用 Canary，藉此從現有的一般部署建立 Canary 發行部署。

**從現有部署建立 Canary 發行部署**

1. 使用 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令建立沒有 Canary 的部署：

   ```
   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) 命令更新階段以啟用 Canary：

   ```
   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 版本上啟用 Canary，所以生產發行 (`Stage`) 和 Canary 發行 (`canarySettings`) 會指向相同的部署。在您變更 API 並將它再次部署至此階段之後，新的版本將會在 Canary Release 中，而基本版本仍然在生產版本中。Canary Release 中的 `deploymentId` 更新為新部署 `id` 而生產版本中的 `deploymentId` 保持不變時，這是在階段發展中體現。