# Configurar variáveis de estágio para APIs REST no API Gateway
<a name="how-to-set-stage-variables-aws-console"></a>

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
<a name="how-to-set-stage-variables-aws-console-prerequisites"></a>

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
<a name="how-to-set-stage-variables-aws-console-http-endpoint"></a>

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
<a name="how-to-set-stage-variables-aws-console-stage-metadata"></a>

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
<a name="how-to-set-stage-variables-aws-console-lambda-function"></a>

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
<a name="pass-version-info-to-lambda-backend-with-stage-variable"></a>

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."
      ```