# 在 API Gateway 中对 REST API 使用阶段变量
<a name="stage-variables"></a>

阶段变量是可以定义为与 REST API 部署阶段关联的配置属性的键-值对。它们与环境变量的功能类似，可用于 API 设置和映射模板。利用 API Gateway 中的部署阶段，可以管理每个 API 的多个发布阶段；利用阶段变量，您可以将 API 部署阶段配置为与不同的后端端点进行交互。

阶段变量不适用于敏感数据，例如凭证。要将敏感数据传递给集成，请使用 AWS Lambda 授权方。您可以在 Lambda 授权方的输出中将敏感数据传递给集成。要了解更多信息，请参阅“[来自 API Gateway Lambda 授权方的输出](api-gateway-lambda-authorizer-output.md)”。

## 阶段变量的使用案例
<a name="use-cases"></a>

以下是阶段变量的使用案例。

**指定其他后端端点**  
您的 API 可以将 `GET` 请求作为 HTTP 代理传递给后端 Web 主机。您可以使用阶段变量，以使得在 API 调用方调用生产端点时，API Gateway 调用 `example.com`。之后，当 API 调用方调用 beta 阶段时，API Gateway 会调用其他 Web 主机，例如 `beta.example.com`。同样，阶段变量可用于为 API 中的每个阶段指定不同的 AWS Lambda 函数名称。您不能使用阶段变量来设置其他集成端点，例如，在一个阶段将 `GET` 请求指向 HTTP 代理集成，并在另一个阶段将该请求指向 Lambda 代理集成。  
将 Lambda 函数名称指定为阶段变量值时，您必须手动配置对 Lambda 函数的权限。当您在 API Gateway 控制台中指定 Lambda 函数时，将弹出一条 AWS CLI 命令，让您配置正确的权限。您也可以使用以下 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
```

**使用映射模板传递信息**  
您还可以访问映射模板中的阶段变量，或者将配置参数传递给 AWS Lambda 或 HTTP 后端。例如，您可能需要针对 API 中的多个阶段重复使用同一个 Lambda 函数，但是该函数应根据阶段，从不同的 Amazon DynamoDB 表中读取数据。在为 Lambda 函数生成请求的映射模板中，您可以使用阶段变量来将表的名称传递给 Lambda。

要使用阶段变量，首先要配置阶段变量，然后为其分配值。例如，要自定义 HTTP 集成端点，请先创建 `url` 阶段变量，然后在 API 的集成请求中输入阶段变量值 **http://\$1\$1stageVariables.url\$1**。此值将指示 API Gateway 在运行时替换您的阶段变量 `${}`，具体取决于 API 正在哪个阶段运行。有关更多信息，请参阅 [为 API Gateway 中的 REST API 设置阶段变量](how-to-set-stage-variables-aws-console.md)。