为 API Gateway 中的 WebSocket API 创建阶段 - Amazon API Gateway
阶段变量阶段变量引用

为 API Gateway 中的 WebSocket API 创建阶段

一个 API 阶段是对您 API 生命周期状态（例如，dev、prod、beta 或 v2）的一次逻辑引用。API 阶段通过 API ID 和阶段名称标识，包含在您用于调用 API 的 URL 中。每个阶段都是一个对 API 部署的命名引用，可供客户端应用程序调用。

部署是 API 配置的快照。将 API 部署到阶段后，客户端可以调用该 API。您必须部署 API 才能使更改生效。

阶段变量

阶段变量是您可以为 WebSocket API 的阶段定义的键/值对。它们与环境变量的功能类似，可用于 API 设置。

例如，您可以定义阶段变量，然后将其值设置为某个 HTTP 代理集成的 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>}