在 API Gateway 中為 WebSocket API 建立階段

API 階段是 API 生命週期狀態的邏輯參考 (例如，dev、prod、beta 或 v2)。API 階段是由其 API ID 及階段名稱來識別，而且它們會包含在您用來呼叫 API 的 URL 中。每個階段都是 API 部署的具名參考，且可供用戶端應用程式呼叫。

部署是 API 組態的快照。將 API 部署到階段之後，用戶端就可以叫用它。您必須部署 API 才能讓變更生效。

階段變數

階段變數是您可以針對 WebSocket API 階段定義的索引鍵值配對。它們的作用如同環境變數，而且可用於 API 設定。

例如，您可以定義階段變數，然後將其值設定為 HTTP Proxy 整合的 HTTP 端點。稍後，您可以使用相關聯的階段變數名稱來參照端點。如此，您可以在每個階段使用不同的端點來使用相同的 API 設定。同樣地，您可以使用階段變數，為 API 的每個階段指定不同的 AWS Lambda 函數整合。

注意

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

範例

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

您可以使用類似的方式參考階段變數，以指定 Lambda 函數名稱或 AWS 角色 ARN。

將 Lambda 函數名稱指定為階段變數值時，您必須在 Lambda 函數中手動設定許可。您可以使用 AWS Command Line Interface (AWS CLI) 來執行此操作。

aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction

API Gateway 階段變數參考

HTTP 整合 URI

您可以使用階段變數作為 HTTP 整合 URI 的一部分，如下例範例所示。

• 不含通訊協定的完整 URI – http://${stageVariables.<variable_name>}

• 完整的網域 – http://${stageVariables.<variable_name>}/resource/operation

• 子網域 – http://${stageVariables.<variable_name>}.example.com/resource/operation

• 路徑 – http://example.com/${stageVariables.<variable_name>}/bar

• 查詢字串 – http://example.com/foo?q=${stageVariables.<variable_name>}

Lambda 函數

您可以使用階段變數取代 Lambda 函數名稱或別名，如下列範例所示。

• arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:${stageVariables.<function_variable_name>}/invocations

• arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:<function_name>:${stageVariables.<version_variable_name>}/invocations

注意

若要使用 Lambda 函數的階段變數，函數必須與 API 位於相同的帳戶中。階段變數不支援跨帳戶 Lambda 函數。

AWS 整合認證

您可以使用階段變數做為使用 AWS 者或角色認證 ARN 的一部分，如下列範例所示。

• arn:aws:iam::<account_id>:${stageVariables.<variable_name>}