# Usar variáveis de estágio para uma API REST no API Gateway
Variáveis de estágio são pares de chave-valor que você pode definir como atributos de configuração associados a um estágio de implantação de uma API REST. Elas atuam como variáveis de ambiente e podem ser usadas em seus modelos de configuração e mapeamento de API. Com estágios de implantação no API Gateway, é possível gerenciar vários estágios de versão para cada API e usar variáveis de estágio. Você pode configurar um estágio de implantação da API para interagir com diferentes endpoints de backend.
As variáveis de estágio não se destinam a ser usadas para dados confidenciais, como credenciais. Para transmitir dados confidenciais para integrações, use um autorizador do AWS Lambda. Você pode passar dados confidenciais para integrações na saída do autorizador do Lambda. Para saber mais, consulte [Saída de um autorizador do Lambda para o API Gateway](api-gateway-lambda-authorizer-output.md).
## Casos de uso de variáveis de estágio
Veja a seguir casos de uso para suas variáveis de estágio.
**Especificar um endpoint de backend diferente**
Sua API pode transmitir uma solicitação `GET` como um proxy HTTP ao host da web de backend. É possível usar uma variável de estágio de forma que, quando chamadores da API invocarem seu endpoint de produção, o API Gateway chame `example.com`. Então, quando os chamadores da API invocam o estágio beta, o API Gateway chama um host da web diferente, como `beta.example.com`. Da mesma forma, variáveis de estágio podem ser usadas para especificar um nome de função AWS Lambda para cada estágio da sua API. Não é possível usar uma variável de estágio para definir um endpoint de integração diferente, como apontar a solicitação `GET` para uma integração de proxy HTTP em um estágio e uma integração de proxy do Lambda em outro estágio.
Ao especificar um nome de função do Lambda como um valor de variável de estágio, você deve configurar as permissões nessa função do Lambda manualmente. Quando você especifica uma função do Lambda no console do API Gateway, um comando AWS CLI é exibido para configurar as permissões adequadas. Também é possível usar o comando AWS CLI a seguir para fazer isso.
```
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
```
**Transmitir informações usando modelos de mapeamento**
É possível acessar variáveis de estágio em modelos de mapeamento ou transmitir parâmetros de configuração ao backend HTTP ou AWS Lambda. Por exemplo, talvez você queira reutilizar a mesma função do Lambda para vários estágios na sua API, mas a função deve ler dados de outra tabela do Amazon DynamoDB, dependendo do estágio. Nos modelos de mapeamento que geram a solicitação para a função do Lambda, você pode usar variáveis de estágio para transmitir o nome da tabela ao Lambda.
Para usar uma variável de estágio, primeiro você deve configurar uma variável de estágio e, depois, atribuir a ela um valor. Por exemplo, para personalizar o endpoint de integração HTTP, primeiro crie a variável de estágio `url` e, depois, na solicitação de integração da sua API, insira o valor da variável de estágio, **http://\$1\$1stageVariables.url\$1**. Esse valor instrui o API Gateway a substituir sua variável de estágio `${}` em tempo de execução, dependendo de qual estágio sua API está executando. Para ter mais informações, consulte [Configurar variáveis de estágio para APIs REST no API Gateway](how-to-set-stage-variables-aws-console.md).
# Configurar variáveis de estágio para APIs REST no API Gateway
Esta seção mostra como configurar diversas variáveis de estágio para dois estágios de implantação de uma API de exemplo usando o console do Amazon API Gateway. Para entender como usar variáveis de estágio no API Gateway, recomendamos seguir todos os procedimentos desta seção.
## Pré-requisitos
Antes de começar, certifique-se de que os seguintes pré-requisitos são atendidos:
+ Você deve ter uma API disponível no API Gateway. Siga as instruções em [Desenvolver APIs REST no API Gateway](rest-api-develop.md).
+ Você deve ter implantado a API pelo menos uma vez. Siga as instruções em [Implantar APIs REST no API Gateway](how-to-deploy-api.md).
+ Você deve ter criado o primeiro estágio para uma API implantada. Siga as instruções em [Criar um novo estágio](set-up-stages.md#how-to-create-stage-console).
## Invocar um endpoint HTTP por meio de uma API com uma variável de estágio
Este procedimento descreve como criar uma variável de estágio para um endpoint HTTP e dois estágios para sua API. Além disso, você precisa criar as variáveis de estágio `url`, `stageName` e `function` que são usadas nos procedimentos a seguir nesta seção.
**Como invocar um endpoint HTTP por meio de uma API com uma variável de estágio**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Crie uma API e, depois, crie um método `GET` no recurso raiz da API. Defina o tipo de integração como **HTTP** e o **URL do endpoint ** como **http://\$1\$1stageVariables.url\$1**.
1. Implante a API em um novo estágio denominado **beta**.
1. No painel de navegação principal, selecione **Estágios** e, depois, escolha um estágio **beta**.
1. Na guia **Variáveis de estágio**, selecione **Editar**.
1. Selecione **Adicionar variável de estágio**.
1. Em **Nome**, digite **url**. Em **valor**, insira **httpbin.org/get**.
1. Selecione **Adicionar variável de estágio** e, depois, faça o seguinte:
Em **Nome**, digite **stageName**. Em **valor**, insira **beta**.
1. Selecione **Adicionar variável de estágio** e, depois, faça o seguinte:
Em **Nome**, digite **function**. Em **valor**, insira **HelloWorld**.
1. Escolha **Salvar**.
1. Agora crie um segundo estágio. No painel de navegação **Estágios**, selecione **Criar estágio**. Em **Stage name (Nome do estágio)**, insira **prod**. Selecione uma implantação recente em **Implantação** e escolha **Criar estágio**.
1. Assim como no estágio **beta**, defina as mesmas três variáveis de estágio (**url**, **stageName** e **function**) como valores diferentes (**petstore-demo-endpoint.execute-api.com/petstore/pets**, **prod** e **HelloEveryone**), respectivamente.
1. No painel de navegação **Stages (Estágios)**, escolha o estágio **beta**. Em **Detalhes do estágio**, selecione o ícone de cópia para copiar o URL de invocação da API e insira o URL de invocação da API em um navegador da web. Isso inicia a solicitação `GET` de estágio **beta** no recurso raiz da API.
**nota**
O link **Invocar URL** aponta para o recurso raiz da API em seu estágio **beta**. Digitar o URL em um navegador da web chama o método `GET` de estágio **beta** no recurso raiz. Se houver métodos definidos em recursos filho, e não no próprio recurso raiz, inserir o URL em um navegador da web gerará uma resposta de erro `{"message":"Missing Authentication Token"}`. Nesse caso, você deve acrescentar o nome de um recurso filho específico ao link **Invoke URL (Invocar URL)**.
1. A resposta que você obteve da solicitação `GET` de estágio **beta** é mostrada a seguir. Você também pode verificar o resultado usando um navegador para navegar até **http://httpbin.org/get**. Esse valor foi atribuído à variável `url` no estágio **beta**. As duas respostas são idênticas.
1. No painel de navegação **Stages (Estágios)**, escolha o nome do estágio **prod**. Em **Detalhes do estágio**, selecione o ícone de cópia para copiar o URL de invocação da API e insira o URL de invocação da API em um navegador da web. Isso inicia a solicitação `GET` de estágio **prod** no recurso raiz da API.
1. A resposta que você obteve da solicitação `GET` de estágio **prod** é mostrada a seguir. Você pode verificar o resultado usando um navegador para navegar para **http://petstore-demo-endpoint.execute-api.com/petstore/pets**. Esse valor foi atribuído à variável `url` no estágio **prod**. As duas respostas são idênticas.
## Transmitir metadados específicos do estágio para um backend HTTP
Este procedimento descreve como usar um valor de variável de estágio em uma expressão de parâmetro de consulta para transmitir metadados específicos de estágio para um backend HTTP. Usaremos a variável de estágio `stageName` declarada no procedimento anterior.
**Como transmitir metadados específicos do estágio para um backend HTTP**
1. No painel de navegação **Resource (Recurso)**, escolha o método **GET**.
Para adicionar um parâmetro de string de consulta ao URL do método, selecione a guia **Solicitação de método** e, na seção **Configurações de solicitação de método**, escolha **Editar**.
1. Selecione **Parâmetros de string de consulta de URL** e faça o seguinte:
1. Escolha **Add query string** (Adicionar string de consulta).
1. Em **Nome**, digite **stageName**.
1. Mantenha **Obrigatório** e **Armazenamento em cache** desativados.
1. Escolha **Salvar**.
1. Escolha a guia **Solicitação de integração** e, na seção **Configurações de solicitação de integração**, selecione **Editar**.
1. Em **URL do endpoint**, acrescente **?stageName=\$1\$1stageVariables.stageName\$1** ao valor do URL definido anteriormente, de forma que todo o **URL do endpoint** seja **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1**.
1. Selecione **Implantar API** e o estágio **beta**.
1. No painel de navegação principal, selecione **Estágios**. No painel de navegação **Stages (Estágios)**, escolha o estágio **beta**. Em **Detalhes do estágio**, selecione o ícone de cópia para copiar o URL de invocação da API e insira o URL de invocação da API em um navegador da web.
**nota**
Usamos o estágio beta aqui porque o endpoint HTTP (conforme especificado pela variável `url`, "http://httpbin.org/get") aceita expressões de parâmetro de consulta e retorna-os como o objeto `args` em sua resposta.
1. Você receberá a seguinte resposta. Observe que `beta`, atribuído à variável de estágio `stageName`, é passado para o backend como o argumento `stageName`.
![\[Resposta do método GET da API com um endpoint HTTP que usa a variável de estágio url.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)
## Invocar uma função do Lambda por meio de uma API com uma variável de estágio
Este procedimento descreve como usar uma variável de estágio para chamar uma função do Lambda como um backend da sua API. Você usará a variável de estágio `function` declarada em [Invocar um endpoint HTTP por meio de uma API com uma variável de estágio](#how-to-set-stage-variables-aws-console-http-endpoint).
Ao definir uma função do Lambda como o valor de uma variável de estágio, use o nome local da função, possivelmente incluindo seu alias ou sua especificação de versão, como em **HelloWorld**, **HelloWorld:1** ou **HelloWorld:alpha**. Não use o ARN da função (por exemplo, **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**). O console do API Gateway pressupõe o valor da variável de estágio de uma função do Lambda como o nome de função não qualificado e expande a variável de estágio especificada em um ARN.
**Como invocar uma função do Lambda por meio de uma API com uma variável de estágio**
1. Crie uma função do Lambda chamada **HelloWorld** usando o runtime Node.js padrão. O código deve conter o seguinte:
```
export const handler = function(event, context, callback) {
if (event.stageName)
callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
else
callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
};
```
Para obter mais informações sobre como criar uma função do Lambda, consulte [Conceitos básicos do console da API REST](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function).
1. No painel **Recursos**, selecione **Criar recurso** e faça o seguinte:
1. Em **Caminho do recurso**, selecione**/**.
1. Em **Resource Name (Nome do recurso)**, insira **lambdav1**.
1. Selecione **Criar recurso**.
1. Selecione o recurso **/lambdav1** e escolha **Criar método**.
Faça o seguinte:
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Função do Lambda**.
1. Mantenha a opção **Integração do proxy do Lambda** desativada.
1. Em **Lambda function** (Função do Lambda), insira `${stageVariables.function}`.
![\[Crie um método GET integrado com uma função do Lambda conforme especificado pela variável de estágio function.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**dica**
Quando for solicitado para **Adicionar comando de permissão**, copie o comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Execute o comando em cada função do Lambda que será atribuída à variável de estágio `function`. Por exemplo, se o valor `$stageVariables.function` for `HelloWorld`, execute o seguinte comando da AWS CLI:
```
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
```
Se isso não for feito, uma resposta `500 Internal Server Error` será gerada ao invocar o método. Substitua `${stageVariables.function}` pelo nome da função do Lambda atribuída à variável de estágio.
![\[Comando da AWS CLI para adicionar permissão à função do Lambda para que seja invocada pelo método que você criou.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)
1. Escolha **Criar método**.
1. Implante a API nos estágios **prod** e **beta**.
1. No painel de navegação principal, selecione **Estágios**. No painel de navegação **Stages (Estágios)**, escolha o estágio **beta**. Em **Detalhes do estágio**, selecione o ícone de cópia para copiar o URL de invocação da API e insira o URL de invocação da API em um navegador da web. Anexe **/lambdav1** ao URL antes de pressionar enter.
Você receberá a seguinte resposta.
```
"Hello, World! I'm not sure where I'm calling from..."
```
## Transmitir metadados específicos ao estágio para uma função do Lambda por meio de uma variável de estágio
Este procedimento descreve como usar uma variável de estágio para transmitir metadados de configuração específicos de estágio para uma função do Lambda. Você criará um método `POST` e um modelo de mapeamento de entrada para gerar a carga útil usando a variável de estágio `stageName` declarada anteriormente.
**Como transmitir metadados específicos ao estágio para uma função do Lambda por meio de uma variável de estágio**
1. Selecione o recurso **/lambdav1** e escolha **Criar método**.
Faça o seguinte:
1. Em **Tipo de método**, selecione **POST**.
1. Em **Tipo de integração**, selecione **Função do Lambda**.
1. Mantenha a opção **Integração do proxy do Lambda** desativada.
1. Em **Lambda function** (Função do Lambda), insira `${stageVariables.function}`.
1. Quando for solicitado para **Adicionar comando de permissão**, copie o comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Execute o comando em cada função do Lambda que será atribuída à variável de estágio `function`.
1. Escolha **Criar método**.
1. Escolha a guia **Solicitação de integração** e, na seção **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Modelos de mapeamento** e, depois, **Adicionar modelo de mapeamento**.
1. Em **Tipo de conteúdo**, insira **application/json**.
1. Em **Corpo do modelo**, insira o seguinte modelo:
```
#set($inputRoot = $input.path('$'))
{
"stageName" : "$stageVariables.stageName"
}
```
**nota**
Em um modelo de mapeamento, uma variável de estágio deve ser referenciada entre aspas (como em `"$stageVariables.stageName"` ou `"${stageVariables.stageName}"`). Em outros lugares, ela deve ser referenciada sem aspas (como em `${stageVariables.function}`).
1. Escolha **Salvar**.
1. Implante a API nos estágios **beta** e **prod**.
1. Para usar um cliente da API REST para transmitir metadados específicos do estágio, faça o seguinte:
1. No painel de navegação **Stages (Estágios)**, escolha o estágio **beta**. Em **Detalhes do estágio**, selecione o ícone de cópia para copiar o URL de invocação da API e, depois, insira o URL de invocação da API no campo de entrada de um cliente da API REST. Anexe **/lambdav1** antes de enviar a solicitação.
Você receberá a seguinte resposta.
```
"Hello, World! I'm calling from the beta stage."
```
1. No painel de navegação **Estágios**, selecione o estágio **prod**. Em **Detalhes do estágio**, selecione o ícone de cópia para copiar o URL de invocação da API e, depois, insira o URL de invocação da API no campo de entrada de um cliente da API REST. Anexe **/lambdav1** antes de enviar a solicitação.
Você receberá a seguinte resposta.
```
"Hello, World! I'm calling from the prod stage."
```
1. Para usar o recurso **Testar** para transmitir metadados específicos do estágio, faça o seguinte:
1. No painel de navegação **Recursos**, selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **função**, insira **HelloWorld**.
1. Em **stageName**, insira **beta**.
1. Escolha **Testar**. Não é necessário adicionar um corpo à solicitação `POST`.
Você receberá a seguinte resposta.
```
"Hello, World! I'm calling from the beta stage."
```
1. É possível repetir as etapas anteriores para testar o estágio **Prod**. Em **stageName**, insira **Prod**.
Você receberá a seguinte resposta.
```
"Hello, World! I'm calling from the prod stage."
```
# Referência de variáveis de estágio do API Gateway para APIs REST no API Gateway
Você pode usar variáveis de estágio do API Gateway nos seguintes casos.
## Expressões de mapeamento de parâmetros
Uma variável de estágio pode ser usada em uma expressão de mapeamento de parâmetros para o parâmetro de cabeçalho de solicitação ou resposta de um método de API, sem substituição parcial. No exemplo a seguir, a variável de estágio é referenciada sem o `$` e o delimitador `{...}`.
+ `stageVariables.`
## Modelos de mapeamento
Uma variável de estágio pode ser usada em qualquer lugar de um modelo de mapeamento, conforme mostrado nos exemplos a seguir.
+ `{ "name" : "$stageVariables."}`
+ `{ "name" : "${stageVariables.}"}`
## URIs de integração HTTP
Uma variável de estágio pode ser usada como parte de um URL de integração HTTP, como mostram os exemplos a seguir:
+ Um URI completo sem protocol – `http://${stageVariables.}`
+ Um domínio complet – `http://${stageVariables.}/resource/operation`
+ Um subdomíni – `http://${stageVariables.}.example.com/resource/operation`
+ Um caminh – `http://example.com/${stageVariables.}/bar`
+ Uma string de consult – `http://example.com/foo?q=${stageVariables.}`
## AWSURIs de integração da
Uma variável de estágio pode ser usada como parte de componentes de caminho ou ação de URI da AWS, como mostra o exemplo a seguir.
+ `arn:aws:apigateway:::${stageVariables.}`
## AWSURIs de integração da (funções do Lambda)
Uma variável de estágio pode ser usada no lugar de um nome de função do Lambda, ou de uma versão/alias, como mostram os exemplos a seguir.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**nota**
Para usar uma variável de estágio para uma função do Lambda, a função deve estar na mesma conta que a API. As variáveis de estágio não suportam funções do Lambda entre contas.
## Grupo de usuários do Amazon Cognito
Uma variável de estágio pode ser usada no lugar de um grupo de usuários do Amazon Cognito para um autorizador `COGNITO_USER_POOLS`.
+ `arn:aws:cognito-idp:::userpool/${stageVariables.}`
## AWSCredenciais de integração da
Uma variável de estágio pode ser usada como parte do ARN de credencial de usuário/função da AWS, como mostra o exemplo a seguir.
+ `arn:aws:iam:::${stageVariables.}`