本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 API Gateway 中為 REST API 設定階段
階段是部署的具名參考，而這是 API 快照。您使用[階段](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)來管理和最佳化特定部署。例如，您可以設定階段設定來啟用快取、自訂請求調節、設定記錄、定義階段變數，或連線 Canary 版本以進行測試。下一節顯示如何建立和設定階段。
## 建立新的階段
初次部署之後，您可以新增更多階段並與現有的部署相關聯。您可以使用 API Gateway 主控台建立新的階段，或在部署 API 時選擇現有的階段。一般而言，您可以先為 API 部署新增新階段，再重新部署 API。若要使用 API Gateway 主控台建立新階段，請依照下列步驟執行：
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 在主導覽窗格中，於 API 底下選擇**階段**。
1. 從**階段**導覽窗格選擇**建立**。
1. 在**階段名稱**中輸入名稱，例如 **prod**。
**注意**
階段名稱僅可含有英數字元、連字號與底線。長度上限為 128 字元。
1. (選用)。在**描述**中，輸入階段描述。
1. 在**部署**中，選取要與此階段相關聯的現有 API 部署的日期與時間。
1. 在**其他設定**下，您可以指定階段的其他設定。
1. 選擇**建立階段**。
## 修改階段設定。
成功部署 API 之後，會使用預設設定填入階段。您可以使用主控台或 API Gateway REST API 來變更階段設定，包括 API 快取和記錄日誌。如果您已修改 REST API 的預設端點，當您更新階段時，修改會傳播到 API 的所有階段。下列步驟示範如何使用 API Gateway 主控台的**階段編輯器**來執行此操作。
1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 選擇 REST API。
1. 在主導覽窗格中，於 API 底下選擇**階段**。
1. 在 **Stages (階段)** 窗格中，選擇階段的名稱。
1. 在**階段詳細資訊**區段中，選擇**編輯**。
1. (選用) 針對**階段描述**，編輯描述。
1. 針對**其他設定**，請修改下列設定：
**快取設定**
若要針對階段啟用 API 快取，請開啟 **佈建 API 快取**。然後，設定**預設方法層級快取**、**快取容量**、**加密快取資料**、**快取存活期 (TTL)**，以及每個金鑰快取失效的任何要求。
快取在您針對特定方法開啟預設方法層級快取，或開啟方法層級快取之前，不會處於作用中狀態。
如需快取設定的詳細資訊，請參閱 [API Gateway 中 REST API 的快取設定](api-gateway-caching.md)。
如果您為 API 階段啟用 API 快取，您的帳戶 AWS 可能需要支付 API 快取的費用。快取不符合 AWS 免費方案的資格。
**限流設定**
若要為與此 API 相關聯的所有方法設定階段層級限流目標，請開啟**限流**。
在 **Rate** (速率) 欄位，輸入目標速率。這是會將字符新增到字符儲存貯體的速率 (以每秒請求數計)。階段層級速率不得超過 [在 API Gateway 中設定和執行 REST API 的配額](api-gateway-execution-service-limits-table.md) 所指定的[帳戶層級](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits)速率。
在 **Burst** (爆量) 欄位，輸入目標爆量率。暴量率是字符儲存貯體的容量。這可允許請求量在一段期間內超過目標速率。此階段層級爆量率不得超過 [在 API Gateway 中設定和執行 REST API 的配額](api-gateway-execution-service-limits-table.md) 所指定的[帳戶層級](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits)爆量率。
調節率並非硬性限制，會依最佳作法來套用。在某些情況下，用戶端可能超出設定的目標。請勿依靠調節功能來控制成本或封鎖對 API 的存取。請考慮使用 [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) 來監控成本，使用 [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) 來管理 API 請求量。
**防火牆和憑證設定**
若要將 AWS WAF Web ACL 與階段建立關聯，請從 Web ACL 下拉式清單中選取 **Web ACL**。如有需要，選擇 **Block API Request if WebACL cannot be evaluated (Fail- Close) (如果無法評估 WebACL，則阻擋 API 請求 (失敗 - 關閉))**。
若要為您的階段選取用戶端憑證，請從**用戶端憑證**下拉式選單中選取憑證。
1. 選擇**繼續**。
1. 檢閱變更，然後選擇**儲存變更**。
1. 若要為與此 API Gateway API 階段相關聯的所有方法啟用 Amazon CloudWatch Logs，請在**日誌和追蹤**區段中選擇**編輯**。
**注意**
若要啟用 CloudWatch Logs，您必須同時指定 IAM 角色的 ARN，讓 API Gateway 代表您的使用者將資訊寫入 CloudWatch Logs。若要執行此作業，請從 **APIs** 主導覽窗格選擇 **Settings (設定)**。然後在 **CloudWatch 日誌角色**中，輸入 IAM 角色的 ARN。
對於常見的應用程式案例，IAM 角色可以連接 [AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) 的受管政策。
IAM 角色也必須包含下列信任關係陳述式：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
如需有關 CloudWatch 的詳細資訊，請參閱 [Amazon CloudWatch 使用者指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)**。
1. 從 **CloudWatch Logs** 下拉式選單中選取記錄層級。記錄層級如下：
+ **關閉** – 此階段未開啟記錄。
+ **僅限錯誤** – 僅針對錯誤啟用記錄。
+ **錯誤和資訊日誌** – 針對所有事件啟用記錄。
1. 選取**資料追蹤**，讓 API Gateway 向 CloudWatch 報告針對您階段所記錄的資料追蹤。這對於故障排除 API 很有用，但可能會導致記錄機密資料。
**注意**
建議您不要針對生產 API 使用**資料追蹤**。
1. 若要讓 API Gateway 向 CloudWatch 回報 `API calls`、`Latency`、`Integration latency`、`400 errors` 和 `500 errors` 的 API 指標，請選取**詳細指標**。如需 CloudWatch 的詳細資訊，請參閱《Amazon CloudWatch 使用者指南》中的[基本監控和詳細監控](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html)。
**重要**
您的帳戶需要支付存取方法層級 CloudWatch 指標的費用，但不需要支付 API 層級或階段層級指標的費用。
1. 若要啟用目的地的存取記錄，請開啟**自訂存取記錄**。
1. 針對**存取日誌目的地 ARN**，輸入日誌群組或 Firehose 串流的 ARN。
Firehose 的 ARN 格式為 `arn:aws:firehose:{{{region}}}:{{{account-id}}}:deliverystream/amazon-apigateway-{{{your-stream-name}}}`。Firehose 串流的名稱必須是 `amazon-apigateway-{{{your-stream-name}}}`。
1. 在**日誌格式**中，輸入日誌格式。若要進一步了解範例日誌格式，請參閱 [適用於 API Gateway 的 CloudWatch 日誌格式](set-up-logging.md#apigateway-cloudwatch-log-formats)。
1. 若要為 API 階段啟用 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) 追蹤，請選取 **X-Ray 追蹤**。如需詳細資訊，請參閱[在 API Gateway 中使用 X-Ray 追蹤使用者對 REST API 的請求](apigateway-xray.md)。
1. 選擇 **Save changes** (儲存變更)。重新部署 API 以使新設定生效。
## 覆寫階段層級設定
自訂階段層級設定之後，您可以針對每個 API 方法覆寫這些設定。其中一些選項可能會對您的 產生額外費用 AWS 帳戶。
1. 若要設定方法覆寫，請展開次要導覽窗格下的階段，然後選擇方法。
1. 針對**方法覆寫**，選擇**編輯**。
1. 若要開啟方法層級 CloudWatch 設定，請針對 **CloudWatch Logs** 選取記錄層級。
1. 若要開啟方法的資料追蹤記錄，請選取**資料追蹤**。
**注意**
建議您不要針對生產 API 使用**資料追蹤**。
1. 若要開啟方法層級詳細指標，請選取**詳細指標**。您的帳戶需要支付存取方法層級 CloudWatch 指標的費用，但不需要支付 API 層級或階段層級指標的費用。
1. 若要開啟方法層級限流，請選取**限流**。輸入適當的方法層級選項。若要進一步了解調節，請參閱 [調節對 REST API 的請求，以提高 API Gateway 的輸送量](api-gateway-request-throttling.md)。
1. 若要設定方法層級快取，請選取**啟用方法快取**。如果您在**階段詳細資訊**中變更預設方法層級快取設定，則不會影響此設定。
1. 選擇**儲存**。