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.

• Você deve ter implantado a API pelo menos uma vez. Siga as instruções em Implantar APIs REST no API Gateway.

• Você deve ter criado o primeiro estágio para uma API implantada. Siga as instruções em Criar um novo estágio.

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.

2. 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://${stageVariables.url}.

3. Implante a API em um novo estágio denominado beta.

4. No painel de navegação principal, selecione Estágios e, depois, escolha um estágio beta.

5. Na guia Variáveis de estágio, selecione Editar.

6. Selecione Adicionar variável de estágio.

7. Em Nome, digite url. Em valor, insira httpbin.org/get.

8. Selecione Adicionar variável de estágio e, depois, faça o seguinte:

   Em Nome, digite stageName. Em valor, insira beta.

9. Selecione Adicionar variável de estágio e, depois, faça o seguinte:

   Em Nome, digite function. Em valor, insira HelloWorld.

10. Escolha Salvar.

11. 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.

12. 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.

13. 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).

14. 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.

15. 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.

16. 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.

2. Selecione Parâmetros de string de consulta de URL e faça o seguinte:

   1. Escolha Add query string (Adicionar string de consulta).

   2. Em Nome, digite stageName.

   3. Mantenha Obrigatório e Armazenamento em cache desativados.

3. Escolha Salvar.

4. Escolha a guia Solicitação de integração e, na seção Configurações de solicitação de integração, selecione Editar.

5. Em URL do endpoint, acrescente ?stageName=${stageVariables.stageName} ao valor do URL definido anteriormente, de forma que todo o URL do endpoint seja http://${stageVariables.url}?stageName=${stageVariables.stageName}.

6. Selecione Implantar API e o estágio beta.

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

8. Você receberá a seguinte resposta. Observe que beta, atribuído à variável de estágio stageName, é passado para o backend como o argumento stageName.

   

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.

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.

2. No painel Recursos, selecione Criar recurso e faça o seguinte:

   1. Em Caminho do recurso, selecione/.

   2. Em Resource Name (Nome do recurso), insira lambdav1.

   3. Selecione Criar recurso.

3. Selecione o recurso /lambdav1 e escolha Criar método.

   Então, faça o seguinte:

   1. Em Tipo de método, selecione GET.

   2. Em Tipo de integração, selecione Função do Lambda.

   3. Mantenha a opção Integração do proxy do Lambda desativada.

   4. Em Lambda function (Função do Lambda), insira ${stageVariables.function}.

      

      dica

      Quando for solicitado para Adicionar comando de permissão, copie o comando da AWS CLI. 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.

      

   5. Escolha Criar método.

4. Implante a API nos estágios prod e beta.

5. 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.

   Então, faça o seguinte:

   1. Em Tipo de método, selecione POST.

   2. Em Tipo de integração, selecione Função do Lambda.

   3. Mantenha a opção Integração do proxy do Lambda desativada.

   4. Em Lambda function (Função do Lambda), insira ${stageVariables.function}.

   5. Quando for solicitado para Adicionar comando de permissão, copie o comando da AWS CLI. Execute o comando em cada função do Lambda que será atribuída à variável de estágio function.

   6. Escolha Criar método.

2. Escolha a guia Solicitação de integração e, na seção Configurações de solicitação de integração, selecione Editar.

3. Selecione Modelos de mapeamento e, depois, Adicionar modelo de mapeamento.

4. Em Tipo de conteúdo, insira application/json.

5. 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}).

6. Escolha Salvar.

7. Implante a API nos estágios beta e prod.

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

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

9. 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.

   2. Em função, insira HelloWorld.

   3. Em stageName, insira beta.

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

   5. É 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."