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.
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 um.
Para se cadastrar em uma Conta da AWS
Abra https://portal.aws.amazon.com/billing/signup
. Siga as instruções online.
Parte do procedimento de inscrição envolve receber uma chamada telefônica e inserir 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 atributos na conta. Como prática recomendada de segurança, atribua o acesso administrativo a um usuário e use somente o usuário-raiz para executar tarefas que exigem 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/
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, insira sua senha. Para obter ajuda ao fazer login usando o usuário raiz, consulte 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 o URL de login que foi enviado 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 a 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
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.
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 arquivooutputfile.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, insira
DynamoDBOperations
. -
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
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
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
-
Escolha Create table.
-
Em Detalhes da tabela, faça o seguinte:
-
Em Table name (Nome da tabela), insira
lambda-apigateway
. -
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çãocreate
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úmero5
.
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" }, "UpdateExpression": "SET #num = :newNum", "ExpressionAttributeNames": { "#num": "number" }, "ExpressionAttributeValues": { ":newNum": 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çãoupdate
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úmero10
.
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
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 realizará as operações de leitura, atualização e exclusão nesses itens.
Para criar um item na tabela do DynamoDB 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-east-2.amazonaws.com/test
/DynamoDBManager \ -d '{"operation": "create", "payload": {"Item": {"id": "5678EFGH", "number": 15}}}'Se a operação foi bem-sucedida, você deverá ver uma resposta retornada com um código 200 de status de HTTP.
-
Você também pode usar o console do DynamoDB para confirmar que o item novo está na sua tabela fazendo o seguinte:
-
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
5678EFGH
e o número15
.
-
Para ler o item na tabela do DynamoDB usando curl
-
Execute o comando
curl
a seguir para ler o valor do item que você acabou de criar. Use seu próprio URL de invocação.curl https://
avos4dr2rk.execute-api.us-east-2.amazonaws.com/test
/DynamoDBManager -d \ '{"operation": "read", "payload": {"Key": {"id": "5678EFGH"}}}'Você deve ver uma saída como uma das seguintes, dependendo de ter escolhido o código da função em Node.js ou em Python:
Para atualizar o item na tabela do DynamoDB usando curl
-
Execute o comando
curl
a seguir para atualizar o item que você acabou de criar alterando o valor denumber
. Use seu próprio URL de invocação.curl https://
avos4dr2rk.execute-api.us-east-2.amazonaws.com/test
/DynamoDBManager \ -d '{"operation": "update", "payload": {"Key": {"id": "5678EFGH"}, "UpdateExpression": "SET #num = :new_value", "ExpressionAttributeNames": {"#num": "number"}, "ExpressionAttributeValues": {":new_value": 42}}}' -
Para confirmar que o valor de
number
para p item foi atualizado, execute outro comando de leitura:curl https://
avos4dr2rk.execute-api.us-east-2.amazonaws.com/test
/DynamoDBManager \ -d '{"operation": "read", "payload": {"Key": {"id": "5678EFGH"}}}'
Para excluir o item na tabela do DynamoDB usando curl
-
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-east-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).