為 REST API 部署設定階段變數

階段變數是名稱/值對，您可以定義為與 REST API 部署階段相關聯的組態屬性。它們的作用如同環境變數，可用於 API 設定和對應範本。

例如，您可以在階段組態中定義階段變數，然後將其值設為您 REST API 方法之 HTTP 整合的 URL 字串。之後，您可以從 API 設定使用相關聯的階段變數名稱參考 URL 字串。如此一來，您可以將階段變數值重設為對應的 URL，在每個階段的不同端點使用相同的 API 設定。

您也可以存取對應範本中的階段變數，或將組態參數傳送到 AWS Lambda 或 HTTP 後端。

如需映射範本的詳細資訊，請參閱「API Gateway 映射範本和存取記錄變數參考」。

注意

階段變數並非用於敏感資料，例如登入資料。若要將敏感資料傳遞給整合，請使用 AWS Lambda 授權者。您可以將敏感資料傳遞至 Lambda 授權方輸出中的整合。如需進一步了解，請參閱來自 API Gateway Lambda 授權者的輸出。

使用案例

透過 API Gateway 中的部署階段，您可以管理每個 API 的多個發行階段，像是 alpha、beta 和生產。使用階段變數，您可以設定 API 部署階段與不同的後端端點互動。

例如，您的 API 可將 GET 請求當做 HTTP 代理傳送到後端 Web 主機 (例如，http://example.com)。在這種情況下，後端 Web 主機是以階段變數設定，所以當開發人員呼叫您的生產端點時，API Gateway 會呼叫 example.com。當您呼叫您的 beta 端點時，API Gateway 會在 beta 階段使用階段變數中設定的值，並呼叫不同的 Web 主機 (例如 beta.example.com)。同樣地，階段變數也可用來為 API 中的每個階段指定不同的 AWS Lambda 函數名稱。

您也可以使用階段變數，透過您的對應範本將組態參數傳送到 Lambda 函數。例如，您可能希望在您 API 的多個階段中重複使用相同的 Lambda 函數，但此函數應該從不同的 Amazon DynamoDB 資料表讀取資料，視呼叫的階段而定。在產生 Lambda 函數請求的對應範本中，您可以使用階段變數將資料表名稱傳送給 Lambda。

範例

若要使用階段變數來自訂 HTTP 整合端點，您必須先設定指定名稱的階段變數 (例如 url)，然後為它指派值 (例如 example.com)。之後，從您的方法組態設定一個 HTTP 代理整合。您可以告訴 API Gateway 使用階段變數值 http://${stageVariables.url}，而不需要輸入端點的 URL。此值會指示 API Gateway 在執行時間替換您的階段變數 ${}，視您 API 執行的階段而定。

您可以使用類似的方式參考階段變數，在認證欄位中指定 Lambda 函數名稱、 AWS 服務代理路徑或 AWS 角色 ARN。

將 Lambda 函數名稱指定為階段變數值時，您必須在 Lambda 函數中手動設定許可。當您在 API Gateway 主控台中指定 Lambda 函數時，會彈出一個指 AWS CLI 令以設定適當的權限。您也可以使用 AWS Command Line Interface （AWS CLI）來執行此操作。

aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction