O Guia de API referência da AWS SDK for JavaScript V3 descreve detalhadamente todas as API operações da AWS SDK for JavaScript versão 3 (V3).
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Invocar o Lambda com o API Gateway
Você pode invocar uma função do Lambda usando o Amazon API Gateway, que é um serviço da AWS para criar, publicar, manter, monitorar e proteger APIs de WebSocket, REST e HTTP em qualquer escala. Os desenvolvedores de API podem criar APIs que acessem a AWS ou outros serviços da Web, bem como dados armazenados na Nuvem da AWS. Como um desenvolvedor do API Gateway, você pode criar APIs para usar em suas próprias aplicações cliente. Para obter mais informações, consulte O que é o Amazon API Gateway.
O AWS Lambda é um serviço de computação que permite executar código sem provisionar ou gerenciar servidores. Você pode criar funções do Lambda em várias linguagens de programação. Para obter mais informações sobre o AWS Lambda, consulte O que é o AWS Lambda.
Neste exemplo, você cria uma função do Lambda usando a API de runtime de JavaScript do Lambda. Este exemplo invoca diferentes serviços da AWS para lidar com um caso de uso específico. Por exemplo, suponha que uma organização envie uma mensagem de SMS para seus funcionários parabenizando-os pela data de um ano de tempo de casa, conforme mostrado nesta ilustração.
![Tabela DynamoDB](images/apigateway_example/picPhone.png)
O exemplo levará aproximadamente 20 minutos para ser concluído.
Este exemplo mostra como usar a lógica do JavaScript para criar uma solução que execute este caso de uso. Por exemplo, você aprenderá como ler um banco de dados para determinar quais funcionários atingiram a data de aniversário de um ano, como processar os dados e enviar uma mensagem de texto usando uma função do Lambda. Em seguida, você aprenderá como usar o API Gateway para invocar essa função AWS Lambda usando um endpoint Rest. Por exemplo, você pode invocar a função do Lambda usando este comando curl:
curl -XGET "https://xxxxqjko1o3.execute-api.us-east-1.amazonaws.com/cronstage/employee"
Este tutorial da AWS usa uma tabela do Amazon DynamoDB chamada Funcionários que contém estes campos.
id - a chave primária da tabela.
firstName - o nome do funcionário.
phone - o número de telefone do funcionário.
startDate - a data de início do funcionário.
![Tabela do DynamoDB](images/apigateway_example/pic00.png)
Importante
Custo para concluir: os serviços da AWS incluídos neste documento estão incluídos no Nível gratuito da AWS. No entanto, certifique-se de encerrar todos os recursos depois de concluir este exemplo para garantir que você não seja cobrado.
Para criar o aplicativo:
Tarefas de pré-requisito
Para configurar e executar este exemplo, você deve primeiro concluir estas tarefas:
-
Configure o ambiente do projeto para executar esses exemplos do Node TypeScript e instale os módulos do AWS SDK for JavaScript e de terceiros necessários. Siga as instruções no GitHub
. -
Crie um arquivo de configurações compartilhado com as credenciais de usuário. Para obter mais informações sobre como fornecer um arquivo de credenciais compartilhado, consulte Arquivos de configuração e credenciais compartilhados no Guia de referência de ferramentas e SDKs da AWS.
Criar os recursos da AWS
Este tutorial requer os seguintes recursos:
-
Uma tabela do Amazon DynamoDB chamada
Employee
com uma chave chamadaId
e os campos mostrados na ilustração anterior. Certifique-se de inserir os dados corretos, incluindo um telefone celular válido com o qual você deseja testar esse caso de uso. Para obter mais informações, consulte Criar uma tabela. -
Um perfil do IAM com permissões anexadas para executar funções do Lambda.
-
Um bucket do Amazon S3 para hospedar a função do Lambda.
Você pode criar esses recursos manualmente, mas recomendamos provisioná-los usando o AWS CloudFormation conforme descrito neste tutorial.
Criar os recursos da AWS usando o AWS CloudFormation
O AWS CloudFormation permite que você crie e provisione implantações de infraestrutura da AWS de maneira previsível e repetida. Para mais informações sobre o AWS CloudFormation, consulte o AWS CloudFormationGuia do usuário do .
Para criar a pilha AWS CloudFormation usando a AWS CLI:
Instale e configure a AWS CLI seguindo as instruções do Guia do usuário da AWS CLI.
Crie um arquivo chamado
setup.yaml
no diretório raiz da pasta do projeto e copie o conteúdo aqui no GitHubpara ele. nota
O modelo AWS CloudFormation foi gerado usando o AWS CDK disponível aqui no GitHub
. Para obter mais informações sobre o AWS CDK, consulte o Guia do desenvolvedor do AWS Cloud Development Kit (AWS CDK). Execute o comando a seguir na linha de comando, substituindo
STACK_NAME
por um nome exclusivo para a pilha.Importante
O nome da pilha deve ser exclusivo em uma Região da AWS e em uma conta da AWS. Você pode especificar até 128 caracteres, e números e hifens são permitidos.
aws cloudformation create-stack --stack-name STACK_NAME --template-body file://setup.yaml --capabilities CAPABILITY_IAM
Para obter mais informações sobre os parâmetros do comando
create-stack
, consulte o Guia de referência de comandos da AWS CLI e o Guia do usuário do AWS CloudFormation.-
Em seguida, preencha a tabela seguindo o procedimento Como preencher a tabela.
Como preencher a tabela
Para preencher a tabela, primeiro crie um diretório chamado libs
, nele crie um arquivo chamado dynamoClient.js
e cole o conteúdo abaixo nesse arquivo.
const { DynamoDBClient } = require ( "@aws-sdk/client-dynamodb" ); // Set the AWS Region. const REGION = "REGION"; // e.g. "us-east-1" // Create an Amazon Lambda service client object. const dynamoClient = new DynamoDBClient({region:REGION}); module.exports = { dynamoClient };
Esse código está disponível aqui no GitHub
Em seguida, crie um arquivo chamado populate-table.js
no diretório raiz da pasta do projeto e copie o conteúdo aqui no GitHubphone
por um número de celular válido no formato E.164, e o valor de startDate
pela data de hoje.
Na linha de comando, execute o seguinte comando:
node populate-table.js
const { BatchWriteItemCommand } = require ( "aws-sdk/client-dynamodb" ); const {dynamoClient} = require ( "./libs/dynamoClient" ); // Set the parameters. export const params = { RequestItems: { Employees: [ { PutRequest: { Item: { id: { N: "1" }, firstName: { S: "Bob" }, phone: { N: "155555555555654" }, startDate: { S: "2019-12-20" }, }, }, }, { PutRequest: { Item: { id: { N: "2" }, firstName: { S: "Xing" }, phone: { N: "155555555555653" }, startDate: { S: "2019-12-17" }, }, }, }, { PutRequest: { Item: { id: { N: "55" }, firstName: { S: "Harriette" }, phone: { N: "155555555555652" }, startDate: { S: "2019-12-19" }, }, }, }, ], }, }; export const run = async () => { try { const data = await dbclient.send(new BatchWriteItemCommand(params)); console.log("Success", data); } catch (err) { console.log("Error", err); } }; run();
Esse código está disponível aqui no GitHub
Criar a função do AWS Lambda
Como configurar o SDK
No diretório libs
, crie arquivos chamados snsClient.js
e lambdaClient.js
e cole o conteúdo abaixo nesses arquivos, respectivamente.
const { SNSClient } = require ( "@aws-sdk/client-sns" ); // Set the AWS Region. const REGION = "REGION"; //e.g. "us-east-1" // Create an Amazon SNS service client object. const snsClient = new SNSClient({ region: REGION }); module.exports = { snsClient };
Substitua REGION
pela Região da AWS. Esse código está disponível aqui no GitHub
const { LambdaClient } = require ( "@aws-sdk/client-lambda" ); // Set the AWS Region. const REGION = "REGION"; //e.g. "us-east-1" // Create an Amazon Lambda service client object. const lambdaClient = new LambdaClient({ region: REGION }); module.exports = { lambdaClient };
Substitua REGION
pela Região da AWS. Esse código está disponível aqui no GitHub
Primeiro, importe os módulos e comandos do AWS SDK for JavaScript (v3) necessários. Em seguida, calcule a data de hoje e atribua-a a um parâmetro. Em terceiro lugar, crie os parâmetros para ScanCommand
. Substitua TABLE_NAME
pelo nome da tabela que você criou na seção Criar os recursos da AWS deste exemplo.
O snippet de código a seguir mostra essa etapa. (Consulte Como empacotar a função do Lambda para ver o exemplo completo.)
"use strict"; const { ScanCommand } = require("@aws-sdk/client-dynamodb"); const { PublishCommand } = require("@aws-sdk/client-sns"); const {snsClient} = require ( "./libs/snsClient" ); const {dynamoClient} = require ( "./libs/dynamoClient" ); // Get today's date. const today = new Date(); const dd = String(today.getDate()).padStart(2, "0"); const mm = String(today.getMonth() + 1).padStart(2, "0"); //January is 0! const yyyy = today.getFullYear(); const date = yyyy + "-" + mm + "-" + dd; // Set the parameters for the ScanCommand method. const params = { // Specify which items in the results are returned. FilterExpression: "startDate = :topic", // Define the expression attribute value, which are substitutes for the values you want to compare. ExpressionAttributeValues: { ":topic": { S: date }, }, // Set the projection expression, which are the attributes that you want. ProjectionExpression: "firstName, phone", TableName: "Employees", };
Como escanear a tabela do DynamoDB
Primeiro, crie uma função async/await chamada sendText
para publicar uma mensagem de texto usando o Amazon SNS PublishCommand
. Em seguida, adicione um padrão de bloco try
que verifique a tabela do DynamoDB em busca de funcionários com aniversários de trabalho na data de hoje e, em seguida, chame a função sendText
para enviar uma mensagem de texto a esses funcionários. Se ocorrer um erro, o bloco catch
será chamado.
O snippet de código a seguir mostra essa etapa. (Consulte Como empacotar a função do Lambda para ver o exemplo completo.)
// Helper function to send message using Amazon SNS. exports.handler = async () => { // Helper function to send message using Amazon SNS. async function sendText(textParams) { try { await snsClient.send(new PublishCommand(textParams)); console.log("Message sent"); } catch (err) { console.log("Error, message not sent ", err); } } try { // Scan the table to identify employees with work anniversary today. const data = await dynamoClient.send(new ScanCommand(params)); data.Items.forEach(function (element) { const textParams = { PhoneNumber: element.phone.N, Message: "Hi " + element.firstName.S + "; congratulations on your work anniversary!", }; // Send message using Amazon SNS. sendText(textParams); }); } catch (err) { console.log("Error, could not scan table ", err); } };
Como empacotar a função do Lambda
Este tópico descreve como empacotar a mylambdafunction.ts
e os módulos do AWS SDK for JavaScript necessários para este exemplo em um arquivo empacotado chamado index.js
.
Caso ainda não tenha feito isso, siga as instruções descritas em Tarefas de pré-requisito para este exemplo para instalar o webpack.
nota
Para obter informações sobre o webpack, consulte Agrupe aplicativos com o webpack.
Execute o seguinte na linha de comando para empacotar o JavaScript deste exemplo em um arquivo chamado
<index.js>
:webpack mylambdafunction.ts --mode development --target node --devtool false --output-library-target umd -o index.js
Importante
A saída é chamada
index.js
. Isso ocorre porque as funções do Lambda precisam ter um manipuladorindex.js
para funcionar.Comprima o arquivo de saída empacotado,
index.js
, em um arquivo ZIP chamadomylambdafunction.zip
.Faça o upload de
mylambdafunction.zip
para o bucket Amazon S3 que você criou no tópico no Criar os recursos da AWS deste tutorial.
Implantar a função do Lambda
Na raiz do projeto, crie um arquivo lambda-function-setup.ts
e cole o conteúdo abaixo nele.
Substitua BUCKET_NAME
pelo nome do bucket Amazon S3 para o qual você fez o upload da versão ZIP da sua função do Lambda. Substitua ZIP_FILE_NAME
pelo nome da versão ZIP da sua função do Lambda. Substitua ROLE
pelo Número de recurso da Amazon (ARN) do perfil do IAM que você criou no tópico Criar os recursos da AWS deste tutorial. Substitua LAMBDA_FUNCTION_NAME
por um nome para a função do Lambda.
// Load the required Lambda client and commands. const { CreateFunctionCommand } = require ( "@aws-sdk/client-lambda" ); const { lambdaClient} = require ( "./libs/lambdaClient.js ); // Set the parameters. const params = { Code: { S3Bucket: "BUCKET_NAME", // BUCKET_NAME S3Key: "ZIP_FILE_NAME", // ZIP_FILE_NAME }, FunctionName: "LAMBDA_FUNCTION_NAME", Handler: "index.handler", Role: "IAM_ROLE_ARN", // IAM_ROLE_ARN; e.g., arn:aws:iam::650138640062:role/v3-lambda-tutorial-lambda-role Runtime: "nodejs12.x", Description: "Scans a DynamoDB table of employee details and using Amazon Simple Notification Services (Amazon SNS) to " + "send employees an email on each anniversary of their start-date.", }; const run = async () => { try { const data = await lambdaClient.send(new CreateFunctionCommand(params)); console.log("Success", data); // successful response } catch (err) { console.log("Error", err); // an error occurred } }; run();
Insira o seguinte na linha de comando para implantar a função do Lambda.
node lambda-function-setup.ts
Esse exemplo de código está disponível aqui no GitHub
Configurar o API Gateway para invocar a função do Lambda
Para criar o aplicativo:
Criar a API REST
Você pode usar o console do API Gateway para criar um endpoint rest para a função do Lambda. Depois de concluído, você pode invocar a função do Lambda usando uma chamada restful.
Inicie uma sessão no console do Amazon API Gateway
. Na API REST, escolha Criar.
Selecione Nova API.
Especifique Funcionário como o nome da API e forneça uma descrição.
Selecione Criar API.
Escolha Recursos na seção Funcionário.
No campo de nome, especifique employees.
Selecione Create Resources (Criar recursos).
No menu suspenso Ações, escolha Criar recursos.
Escolha /employees, selecione Criar método no menu Ações e selecione GET no menu suspenso abaixo de /employees. Selecione o ícone de marca de seleção.
Escolha Função do Lambda e insira mylambdafunction como o nome da função do Lambda. Escolha Save (Salvar).
Testar o método do API Gateway
Neste ponto do tutorial, você pode testar o método do API Gateway que invoca a função do Lambda mylambdafunction. Para testar o método, escolha Testar, conforme mostrado na ilustração a seguir.
![Tabela do DynamoDB](images/apigateway_example/picTest.png)
Depois que a função do Lambda é invocada, você pode visualizar o arquivo de log para ver uma mensagem de sucesso.
Implantar o método do API Gateway
Após o teste bem-sucedido, você pode implantar o método do console do Amazon API Gateway
Selecione GET.
No menu suspenso Ações, selecione Implantar API.
Preencha o formulário Implantar API e escolha Implantar.
Escolha Save Changes (Salvar alterações).
Escolha Get novamente e observe que o URL muda. Esse é o URL de invocação que você pode usar para invocar a função do Lambda.
Excluir os recursos
Parabéns! Você invocou uma função do Lambda por meio do Amazon API Gateway usando o AWS SDK for JavaScript. Conforme informado no início deste tutorial, certifique-se de encerrar todos os recursos que criar enquanto percorre este tutorial para garantir que você não seja cobrado. Você pode fazer isso excluindo a pilha AWS CloudFormation que criou no tópico Criar os recursos da AWS deste tutorial, da seguinte forma:
-
Abra o AWS CloudFormation no console de gerenciamento da AWS
. Abra a página Pilhas e selecione a pilha.
Escolha Delete (Excluir).