使用 HTTP API 的阶段 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

使用 HTTP API 的阶段

一个 API 阶段是对您 API 生命周期状态(例如,devprodbetav2)的一次逻辑引用。API 阶段通过 API ID 和阶段名称标识,包含在您用于调用 API 的 URL 中。每个阶段都是一个对 API 部署的命名引用,可供客户端应用程序调用。

您可以创建一个 $default 阶段,该阶段可以从 API 的 URL 的基本部分得出 — 例如 https://{api_id}.execute-api.{region}.amazonaws.com/。您可以使用此 URL 调用 API 阶段。

部署是 API 配置的快照。将 API 部署到阶段后,客户端可以调用该 API。您必须部署 API 才能使更改生效。如果启用自动部署,则会自动为您发布对 API 的更改。

阶段变量

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

例如,您可以定义阶段变量,然后将其值设置为某个 HTTP 代理集成的 HTTP 终端节点。稍后,您可以使用关联的阶段变量名称引用终端节点。通过执行此操作,您可以在各个阶段对不同终端节点使用相同的 API 设置。同样,您可以使用阶段变量,为 API 的各个阶段指定不同的 Amazon Lambda 函数集成。

注意

阶段变量不适用于敏感数据,例如凭证。要将敏感数据传递给集成,请使用 Amazon Lambda 授权方。您可以在 Lambda 授权方的输出中将敏感数据传递给集成。要了解更多信息,请参阅“Lambda 授权方响应格式”。

示例

要使用阶段变量自定义 HTTP 集成终端节点,您必须首先设置阶段变量的名称和值(例如 url,值为 example.com)。接下来,设置 HTTP 代理集成。您可以告知 API Gateway 使用阶段变量值 http://${stageVariables.url},而不是输入终端节点的 URL。此值将指示 API Gateway 在运行时替换您的阶段变量 ${},具体取决于 API 所处的阶段。

您可以通过类似的方式引用阶段变量,用于指定 Lambda 函数名称或Amazon角色 ARN。

将 Lambda 函数名称指定为阶段变量值时,您必须手动配置对 Lambda 函数的权限。您可以使用 Amazon Command Line Interface (Amazon 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 函数。

Amazon 集成凭证

您可以在 Amazon 用户或角色凭证 ARN 中使用阶段变量,如以下示例所示。

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