Pré-requisitos Criação de uma política de permissões Criar uma função de execução Criar a função Invocação da função usando a AWS CLI Criar uma API REST usando o API Gateway Criação de um recurso na API REST Criação de um método HTTP POST Criar uma tabela do DynamoDB Teste da integração do API Gateway, do Lambda e do DynamoDB Implantar a API Uso de curl para invocar a função usando solicitações HTTP Limpeza dos recursos (opcional)

Tutorial: Uso do Lambda com API Gateway

Neste tutorial, você criará uma API REST que será usada para invocar uma função do Lambda usando uma solicitação HTTP. A função do Lambda executará operações de criação, leitura, atualização e exclusão (CRUD) em uma tabela do DynamoDB. Essa função será fornecida aqui para fins de demonstração, mas você aprenderá a configurar uma API REST do API Gateway que pode invocar qualquer função do Lambda.

Serviços e recursos usados neste tutorial.

O uso do API Gateway fornece aos usuários um endpoint HTTP seguro para invocar a função do Lambda e pode ajudar a gerenciar grandes volumes de chamadas para a função, ao realizar o controle de utilização do tráfego e validar e autorizar as chamadas de API automaticamente. O API Gateway também oferece controles de segurança flexíveis usando o AWS Identity and Access Management (IAM) e o Amazon Cognito. Isso é útil para casos de uso em que é necessária uma autorização prévia para as chamadas em sua aplicação.

Para concluir este tutorial, você passará pelos estágios a seguir:

Criação e configuração de uma função do Lambda em Python ou em Node.js para a execução de operações em uma tabela do DynamoDB.
Criação de uma API REST no API Gateway para conexão com a função do Lambda.
Criação de uma tabela do DynamoDB e realização de teste com a função do Lambda no console.
Implantação da API e realização de teste da configuração completa usando curl em um terminal.

Ao concluir esses estágios, você aprenderá a usar o API Gateway para criar um endpoint HTTP que pode invocar uma função do Lambda com segurança em qualquer escala. Você também aprenderá como implantar a API e testá-la no console, além de como enviar uma solicitação HTTP usando um terminal.

Seções

Pré-requisitos
Criação de uma política de permissões
Criar uma função de execução
Criar a função
Invocação da função usando a AWS CLI
Criar uma API REST usando o API Gateway
Criação de um recurso na API REST
Criação de um método HTTP POST
Criar uma tabela do DynamoDB
Teste da integração do API Gateway, do Lambda e do DynamoDB
Implantar a API
Uso de curl para invocar a função usando solicitações HTTP
Limpeza dos recursos (opcional)

Pré-requisitos

Se você ainda não tem Conta da AWS, siga as etapas a seguir para criar uma.

Para se cadastrar em uma Conta da AWS

Abra https://portal.aws.amazon.com/billing/signup.
Siga as instruções on-line.

Parte do procedimento de inscrição envolve receber uma chamada telefônica e digitar um código de verificação no teclado do telefone.

Quando você se cadastra em uma Conta da AWS, um Usuário raiz da conta da AWS é criado. O usuário-raiz tem acesso a todos os Serviços da AWS e recursos na conta. Como uma prática recomendada de segurança, atribua o acesso administrativo para um usuário e use somente o usuário-raiz para executar tarefas que requerem o acesso de usuário-raiz.

A AWS envia um e-mail de confirmação depois que o processo de cadastramento é concluído. A qualquer momento, é possível visualizar as atividades da conta atual e gerenciar sua conta acessando https://aws.amazon.com/ e selecionando Minha conta.

Depois de se cadastrar em uma Conta da AWS, proteja seu Usuário raiz da conta da AWS, habilite o AWS IAM Identity Center e crie um usuário administrativo para não usar o usuário raiz em tarefas cotidianas.

Proteger seu Usuário raiz da conta da AWS

Faça login no AWS Management Console como o proprietário da conta ao escolher a opção Usuário raiz e inserir o endereço de e-mail da Conta da AWS. Na próxima página, digite sua senha.

Para obter ajuda ao fazer login usando o usuário-raiz, consulte Signing in as the root user (Fazer login como usuário-raiz) no Guia do usuário do Início de Sessão da AWS.
Habilite a autenticação multifator (MFA) para o usuário-raiz.

Para obter instruções, consulte Habilitar um dispositivo MFA virtual para o usuário-raiz de sua conta da Conta da AWS (console) no Guia do usuário do IAM.

Criar um usuário com acesso administrativo

Habilitar o IAM Identity Center.

Para obter instruções, consulte Habilitar AWS IAM Identity Center no Guia do usuário do AWS IAM Identity Center.
No Centro de Identidade do IAM, conceda o acesso administrativo para um usuário.

Para obter um tutorial sobre como usar o Diretório do Centro de Identidade do IAM como fonte de identidade, consulte Configurar o acesso dos usuários com o Diretório do Centro de Identidade do IAM padrão no Guia do usuário do AWS IAM Identity Center.

Iniciar sessão como o usuário com acesso administrativo

Para fazer login com seu usuário do Centro de Identidade do IAM, use a URL de login que foi enviada ao seu endereço de e-mail quando você criou o usuário do Centro do Usuário do IAM.

Para obter ajuda com o login utilizando um usuário do Centro de Identidade do IAM, consulte Fazer login no portal de acesso da AWS, no Guia do usuário do Início de Sessão da AWS.

Atribuir acesso para usuários adicionais

No Centro de Identidade do IAM, crie um conjunto de permissões que siga as práticas recomendadas de aplicação de permissões com privilégio mínimo.

Para obter instruções, consulte Create a permission set no Guia do usuário do AWS IAM Identity Center.
Atribua usuários a um grupo e, em seguida, atribua o acesso de autenticação única ao grupo.

Para obter instruções, consulte Add groups no Guia do usuário do AWS IAM Identity Center.

Se você ainda não instalou a AWS Command Line Interface, siga as etapas em Instalar ou atualizar a versão mais recente da AWS CLI para instalá-la.

O tutorial requer um terminal de linha de comando ou um shell para executar os comandos. No Linux e no macOS, use o gerenciador de pacotes e de shell de sua preferência.

nota

No Windows, alguns comandos da CLI do Bash que você costuma usar com o Lambda (como zip) não são compatíveis com os terminais integrados do sistema operacional. Para obter uma versão do Ubuntu com o Bash integrada no Windows, instale o Subsistema do Windows para Linux.

Criação de uma política de permissões

Antes de ser possível criar uma função de execução para a função do Lambda, primeiro é necessário criar uma política de permissões para fornecer à sua função permissão para acessar os recursos da AWS necessários. Para este tutorial, a política permitirá que o Lambda execute operações de CRUD em uma tabela do DynamoDB e grave no Amazon CloudWatch Logs.

Para criar a política

Abra a página Policies (Políticas) do console do IAM.
Escolha Criar política.

Escolha a guia JSON e cole a política personalizada a seguir no editor JSON.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1428341300017",
      "Action": [
        "dynamodb:DeleteItem",
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:Query",
        "dynamodb:Scan",
        "dynamodb:UpdateItem"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Sid": "",
      "Resource": "*",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Effect": "Allow"
    }
  ]
}

Escolha Próximo: etiquetas.
Selecione Next: Review (Próximo: revisar).
No campo Política de revisão, em Nome da política, insira lambda-apigateway-policy.
Escolha Criar política.

Criar uma função de execução

Etapa 2: criação de um perfil de execução

Um perfil de execução é um perfil do AWS Identity and Access Management (IAM) que concede a uma função do Lambda permissão para acessar serviços e recursos da AWS. Para permitir que a função execute operações em uma tabela do DynamoDB, vincule a política de permissões criada na etapa anterior.

Para criar um perfil de execução e vincular a política de permissões personalizada

Abra a página Roles (Funções) no console do IAM.
Selecione Criar função.
Para o tipo de entidade confiável, escolha Serviço da AWS e, em seguida, para o caso de uso, selecione Lambda.
Escolha Próximo.
Na caixa de pesquisa de política, insira lambda-apigateway-policy.
Nos resultados da pesquisa, selecione a política que você criou (lambda-apigateway-policy) e, depois, escolha Next (Avançar).
Em Role details (Detalhes do perfil), para Role name (Nome do perfil), insira lambda-apigateway-role e, em seguida, escolha Create role (Criar perfil).

Posteriormente no tutorial, você precisará do nome do recurso da Amazon (ARN) do perfil que acabou de criar. Na página Roles (Perfis) do console do IAM, escolha o nome do seu perfil (lambda-apigateway-role) e copie o Role ARN (ARN do perfil) exibido na página Summary (Resumo).

Criar a função

O exemplo de código a seguir recebe uma entrada de evento do API Gateway especificando uma operação a ser executada na tabela do DynamoDB que você criará e alguns dados de carga útil. Se os parâmetros recebidos pela função forem válidos, ela executará a operação solicitada na tabela.

Node.js

exemplo index.mjs


console.log('Loading function');

import { DynamoDBDocumentClient, PutCommand, GetCommand, 
         UpdateCommand, DeleteCommand} from "@aws-sdk/lib-dynamodb";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const ddbClient = new DynamoDBClient({ region: "us-west-2" });
const ddbDocClient = DynamoDBDocumentClient.from(ddbClient);

// Define the name of the DDB table to perform the CRUD operations on
const tablename = "lambda-apigateway";

/**
 * Provide an event that contains the following keys:
 *
 *   - operation: one of 'create,' 'read,' 'update,' 'delete,' or 'echo'
 *   - payload: a JSON object containing the parameters for the table item
 *              to perform the operation on
 */
export const handler = async (event, context) => {
   
     const operation = event.operation;
   
     if (operation == 'echo'){
          return(event.payload);
     }
     
    else { 
        event.payload.TableName = tablename;
        
        switch (operation) {
          case 'create':
               await ddbDocClient.send(new PutCommand(event.payload));
               break;
          case 'read':
               var table_item = await ddbDocClient.send(new GetCommand(event.payload));
               console.log(table_item);
               break;
          case 'update':
               await ddbDocClient.send(new UpdateCommand(event.payload));
               break;
          case 'delete':
               await ddbDocClient.send(new DeleteCommand(event.payload));
               break;
          default:
            return ('Unknown operation: ${operation}');
          }
    }
};

nota

Neste exemplo, o nome da tabela do DynamoDB está definido como uma variável em seu código da função. Em uma aplicação real, a prática recomendada é transferir esse parâmetro como uma variável de ambiente e evitar codificar o nome da tabela. Para obter mais informações, consulte Usar variáveis de ambiente do AWS Lambda.

Para criar a função

Salve o exemplo de código como um arquivo denominado index.mjs e, se necessário, edite a região da AWS especificada no código. A região especificada no código deve ser semelhante à região que você criará a tabela do DynamoDB, posteriormente, no tutorial.
Crie um pacote de implantação usando o comando zip a seguir.
```
zip function.zip index.mjs
```

Crie uma função do Lambda com o comando create-function da AWS CLI. Para o parâmetro role, insira o nome do recurso da Amazon (ARN) do perfil de execução que você copiou anteriormente.


aws lambda create-function \
--function-name LambdaFunctionOverHttps \
--zip-file fileb://function.zip \
--handler index.handler \
--runtime nodejs20.x \
--role arn:aws:iam::123456789012:role/service-role/lambda-apigateway-role

Python 3

exemplo LambdaFunctionOverHttps.py


import boto3
import json

# define the DynamoDB table that Lambda will connect to
tableName = "lambda-apigateway"

# create the DynamoDB resource
dynamo = boto3.resource('dynamodb').Table(tableName)

print('Loading function')

def lambda_handler(event, context):
    '''Provide an event that contains the following keys:

      - operation: one of the operations in the operations dict below
      - payload: a JSON object containing parameters to pass to the 
                 operation being performed
    '''
    
    # define the functions used to perform the CRUD operations
    def ddb_create(x):
        dynamo.put_item(**x)

    def ddb_read(x):
        dynamo.get_item(**x)

    def ddb_update(x):
        dynamo.update_item(**x)
        
    def ddb_delete(x):
        dynamo.delete_item(**x)

    def echo(x):
        return x

    operation = event['operation']

    operations = {
        'create': ddb_create,
        'read': ddb_read,
        'update': ddb_update,
        'delete': ddb_delete,
        'echo': echo,
    }

    if operation in operations:
        return operations[operation](event.get('payload'))
    else:
        raise ValueError('Unrecognized operation "{}"'.format(operation))

nota

Para criar a função

Salve o exemplo de código como um arquivo denominado LambdaFunctionOverHttps.py.
Crie um pacote de implantação usando o comando zip a seguir.
```
zip function.zip LambdaFunctionOverHttps.py
```

Crie uma função do Lambda com o comando create-function da AWS CLI. Para o parâmetro role, insira o nome do recurso da Amazon (ARN) da função de execução que você copiou anteriormente.


aws lambda create-function \
--function-name LambdaFunctionOverHttps \
--zip-file fileb://function.zip \
--handler LambdaFunctionOverHttps.lambda_handler \
--runtime python3.12 \
--role arn:aws:iam::123456789012:role/service-role/lambda-apigateway-role

Invocação da função usando a AWS CLI

Antes de integrar a função com o API Gateway, confirme se a implantação da função ocorreu com êxito. Crie um evento de teste contendo os parâmetros que a API do API Gateway enviará para o Lambda e use o comando invoke da AWS CLI para executar a função.

Para invocar a função do Lambda com a AWS CLI

Salve o JSON a seguir como um arquivo denominado input.txt.


{
    "operation": "echo",
    "payload": {
        "somekey1": "somevalue1",
        "somekey2": "somevalue2"
    }
}

Execute o comando invoke a seguir da AWS CLI.
```
aws lambda invoke \
--function-name LambdaFunctionOverHttps \
--payload file://input.txt outputfile.txt \
--cli-binary-format raw-in-base64-out
```
A opção cli-binary-format será necessária se você estiver usando a AWS CLI versão 2. Para que essa seja a configuração padrão, execute aws configure set cli-binary-format raw-in-base64-out. Para obter mais informações, consulte A AWS CLI comporta opções de linha de comando globais no Guia do usuário da AWS Command Line Interface versão 2.

Você deverá ver a seguinte resposta:
```
{
"StatusCode": 200,
"ExecutedVersion": "LATEST"
}
```
Confirme se a função executou a operação echo especificada no evento de teste JSON. Inspecione o arquivo outputfile.txt e verifique se ele contém o seguinte:
```
{"somekey1": "somevalue1", "somekey2": "somevalue2"}
```

Criar uma API REST usando o API Gateway

Nesta etapa, você cria a API REST do API Gateway que usará para invocar a função do Lambda.

Para criar a API

Abra o console do API Gateway.
Selecione Create API (Criar API).
Na caixa do API REST, escolha Construir.
Em Detalhes da API, deixe a opção Nova API selecionada e, em Nome da API, insiraDynamoDBOperations.
Selecione Criar API.

Criação de um recurso na API REST

Para adicionar um método HTTP à API, primeiro é necessário criar um recurso no qual esse método possa operar. Aqui você cria o recurso para gerenciar a tabela do DynamoDB.

Para criar o recurso

No Console do API Gateway, na página Recursos da sua API, escolha Criar recurso.
Em Detalhes do recurso, em Nome do recurso, insira DynamoDBManager.
Escolha Create Resource (Criar recurso).

Criação de um método HTTP POST

Nesta etapa, você cria um método (POST) para o recurso DynamoDBManager. Você vincula esse método POST à função do Lambda para que, quando o método receber uma solicitação HTTP, o API Gateway invoque sua função do Lambda.

nota

Para a finalidade deste tutorial, um método HTTP (POST) será usado para invocar uma única função do Lambda que executa todas as operações em sua tabela do DynamoDB. Em uma aplicação real, a prática recomendada é usar diferentes funções do Lambda e métodos HTTP para cada operação. Para obter mais informações, consulte The Lambda monolith no Serverless Land.

Para criar o método POST

Na página Recursos da API, certifique-se de que o recurso /DynamoDBManager esteja realçado. Em seguida, no painel Métodos, escolha Criar método.
Em Tipo de método, escolha POST.
Em Tipo de integração, mantenha a opção Função do Lambda selecionada.
Em Função do Lambda, escolha o nome do recurso da Amazon (ARN) para sua função (LambdaFunctionOverHttps).
Escolha Criar método.

Criar uma tabela do DynamoDB

Etapa 8: criação de uma tabela do DynamoDB

Crie uma tabela do DynamoDB em branco na qual a função do Lambda executará as operações de CRUD.

Para criar uma tabela do DynamoDB

Abra a página Tables (Tabelas) no console do DynamoDB.
Escolha Create table.
Em Detalhes da tabela, faça o seguinte:
1. Em Table name (Nome da tabela), insira lambda-apigateway.
2. Para a Chave de partição, insira id e mantenha o tipo de dados definido como String.
Em Table settings (Configurações da tabela), mantenha Default settings (Configurações padrões).
Escolha Create table.

Teste da integração do API Gateway, do Lambda e do DynamoDB

Agora está tudo pronto para que ocorra o teste da integração do método de API do API Gateway com a função do Lambda e a tabela do DynamoDB. Ao usar o console do API Gateway, você envia solicitações diretamente para o método POST usando a função de teste do console. Nesta etapa, primeiro você usa uma operação create para adicionar um novo item à tabela do DynamoDB e, em seguida, usa uma operação update para modificar o item.

Teste 1: para criar um novo item na tabela do DynamoDB

No API Gateway console (Console do API Gateway), escolha a sua API (DynamoDBOperations).
No recurso DynamoDBManager, escolha o método POST.
Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

Em Método de teste, mantenha as opções Strings de consulta e Cabeçalhos vazias. Em Corpo da solicitação, cole o seguinte JSON:


{
  "operation": "create",
  "payload": {
    "Item": {
      "id": "1234ABCD",
      "number": 5
    }
  }
}

Escolha Testar.

Os resultados que são exibidos quando o teste é concluído devem mostrar status 200. Esse código de status indica que a operação create ocorreu com êxito.

Para confirmar, verifique se a tabela do DynamoDB passou a conter o novo item.
Abra a página Tables (Tabelas) do console do DynamoDB e escolha a tabela lambda-apigateway.
Escolha Explore table items (Explorar itens da tabela). No painel Itens retornados, você verá um item com o id 1234ABCD e o número 5.

Teste 2: para atualizar o item na tabela do DynamoDB

No Console do API Gateway, retorne para a guia Teste do seu método POST.

Em Método de teste, mantenha as opções Strings de consulta e Cabeçalhos vazias. Em Corpo da solicitação, cole o seguinte JSON:


{
    "operation": "update",
    "payload": {
        "Key": {
            "id": "1234ABCD"
        },
        "AttributeUpdates": {
            "number": {
                "Value": 10
            }
        }
    }
}

Escolha Testar.

Os resultados que são exibidos quando o teste é concluído devem mostrar status 200. Esse código de status indica que a operação update ocorreu com êxito.

Para confirmar, verifique se o item na tabela do DynamoDB foi modificado.
Abra a página Tables (Tabelas) do console do DynamoDB e escolha a tabela lambda-apigateway.
Escolha Explore table items (Explorar itens da tabela). No painel Itens retornados, você verá um item com o id 1234ABCD e o número 10.

Implantar a API

Para que um cliente chame a API, você deve criar uma implantação e um estágio associado. Um estágio representa um snapshot da API, incluindo seus métodos e integrações.

Para implantar a API

Abra a página APIs do API Gateway console (Console do API Gateway) e escolha a API DynamoDBOperations.
Na página Recursos da sua API, escolha Implantar API.
Em Estágio, escolha *Novo estágio* e, em seguida, em Nome do estágio, insira test.
Escolha Implantar.
No painel Detalhes do estágio copie o URL de invocação. Você usará isso na próxima etapa para invocar a função usando uma solicitação HTTP.

Uso de curl para invocar a função usando solicitações HTTP

Etapa 11: invocação da função com uma solicitação HTTP

Agora é possível invocar a função do Lambda ao emitir uma solicitação HTTP para a API. Nesta etapa, você criará um novo item na tabela do DynamoDB e o excluirá.

Para invocar a função do Lambda usando curl

Execute o comando curl usando o URL de invocação que você copiou na etapa anterior. Quando você usa curl com a opção -d (dados), o método HTTP POST é usado automaticamente.
```
curl https://l8togsqxd8.execute-api.us-west-2.amazonaws.com/test/DynamoDBManager \
-d '{"operation": "create", "payload": {"Item": {"id": "5678EFGH", "number": 15}}}'
```
Para verificar se a operação de criação ocorreu com êxito, faça o seguinte:
1. Abra a página Tables (Tabelas) do console do DynamoDB e escolha a tabela lambda-apigateway.
2. Escolha Explore table items (Explorar itens da tabela). No painel Itens retornados, você verá um item com o id 5678EFGH e o número 15.

Execute o comando curl a seguir para excluir o item que você acabou de criar. Use seu próprio URL de invocação.


curl https://l8togsqxd8.execute-api.us-west-2.amazonaws.com/test/DynamoDBManager \
-d '{"operation": "delete", "payload": {"Key": {"id": "5678EFGH"}}}'

Confirme se a operação de exclusão ocorreu com êxito. No painel Items returned (Itens retornados) da página Explore items (Explorar itens) do console do DynamoDB, verifique se o item com o id 5678EFGH não está mais na tabela.

Limpeza dos recursos (opcional)

Agora você pode excluir os recursos criados para este tutorial, a menos que queira mantê-los. Excluindo os recursos da AWS que você não está mais usando, você evita cobranças desnecessárias em sua Conta da AWS.

Como excluir a função do Lambda

Abra a página Functions (Funções) no console do Lambda.
Selecione a função que você criou.
Escolha Ações, Excluir.
Digite delete no campo de entrada de texto e escolha Delete (Excluir).

Para excluir a função de execução

Abra a página Roles (Funções) no console do IAM.
Selecione a função de execução que você criou.
Escolha Excluir.
Insira o nome do perfil no campo de entrada de texto e escolha Delete (Excluir).

Para excluir a API

Abra a página APIs do console do API Gateway.
Selecione a API que você criou.
Escolha Ações, Excluir.
Escolha Excluir.

Para excluir uma tabela do DynamoDB

Abra a página Tables (Tabelas) no console do DynamoDB.
Selecione a tabela que você criou.
Escolha Excluir.
Digite delete na caixa de texto.
Selecione Delete table (Excluir tabela).

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

API Gateway

Erros