# Criar funções Lambda com TypeScript
Você pode usar o runtime Node.js para executar o código TypeScript no AWS Lambda. Como o Node.js não executa o código TypeScript de modo nativo, você deve primeiro transcompilar seu código TypeScript em JavaScript. Em seguida, use os arquivos JavaScript para implantar o código de função no Lambda. Seu código é executado em um ambiente que inclui o AWS SDK for JavaScript, com as credenciais de uma função do AWS Identity and Access Management (IAM) que você gerencia. Para saber mais sobre as versões do SDK incluídas nos runtimes do Node.js, consulte [Versões do SDK incluídas no runtime](lambda-nodejs.md#nodejs-sdk-included).
O Lambda oferece suporte aos runtimes Node.js a seguir.
| Nome | Identificador | Sistema operacional | Data da substituição | Bloquear a criação de funções | Bloquear a atualização de funções |
| --- | --- | --- | --- | --- | --- |
| Node.js 24 | `nodejs24.x` | Amazon Linux 2023 | 30 de abril de 2028 | 1º de junho de 2028 | 1º de julho de 2028 |
| Node.js 22 | `nodejs22.x` | Amazon Linux 2023 | 30 de abril de 2027 | 1º de junho de 2027 | 1º de julho de 2027 |
| Node.js 20 | `nodejs20.x` | Amazon Linux 2023 | 30 de abril de 2026 | 31 de agosto de 2026 | 30 de setembro de 2026 |
**Topics**
+ [
## Configurar seu ambiente de desenvolvimento de TypeScript
](#typescript-dev)
+ [
## Definições de tipo para o Lambda
](#typescript-type-definitions)
+ [
# Definir o manipulador de função do Lambda em TypeScript
](typescript-handler.md)
+ [
# Implantar código TypeScript transcompilado no Lambda com arquivos .zip
](typescript-package.md)
+ [
# Implantar código TypeScript transcompilado no Lambda com imagens de contêiner
](typescript-image.md)
+ [
# Usar o objeto de contexto do Lambda para recuperar informações das funções em TypeScript
](typescript-context.md)
+ [
# Registrar em log e monitorar funções do Lambda em TypeScript
](typescript-logging.md)
+ [
# Como rastrear o código TypeScript no AWS Lambda
](typescript-tracing.md)
## Configurar seu ambiente de desenvolvimento de TypeScript
Use um ambiente de desenvolvimento integrado (IDE) ou editor de texto local para escrever o código de função TypeScript. Não é possível criar código TypeScript no console do Lambda.
É possível usar o [esbuild](https://esbuild.github.io/) ou o compilador TypeScript da Microsoft (`tsc`) para transcompilar seu código TypeScript em JavaScript. Tanto o [AWS Serverless Application Model (AWS SAM)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html) quanto o [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) usam esbuild.
Ao usar o esbuild, considere o seguinte:
+ Existem várias [advertências de TypeScript](https://esbuild.github.io/content-types/#typescript-caveats).
+ É necessário definir as configurações de transcompilação do TypeScript para corresponder ao runtime Node.js que você pretende usar. Para obter mais informações, consulte [Target](https://esbuild.github.io/api/#target) (Destino) na documentação do esbuild. Para ver um exemplo de arquivo **tsconfig.json** que mostra como direcionar uma versão específica do Node.js compatível com o Lambda, consulte o [repositório GitHub do TypeScript](https://github.com/tsconfig/bases/blob/main/bases/node14.json).
+ O esbuild não executa verificações de tipo. Para verificar tipos, use o compilador `tsc`. Execute `tsc -noEmit` ou adicione um parâmetro `"noEmit"` no arquivo **tsconfig.json**, conforme mostrado no exemplo a seguir. Isso configura `tsc` para não emitir arquivos JavaScript. Após verificar os tipos, use esbuild para converter os arquivos TypeScript em JavaScript.
**Example tsconfig.json**
```
{
"compilerOptions": {
"target": "es2020",
"strict": true,
"preserveConstEnums": true,
"noEmit": true,
"sourceMap": false,
"module":"commonjs",
"moduleResolution":"node",
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"isolatedModules": true,
},
"exclude": ["node_modules", "**/*.test.ts"]
}
```
## Definições de tipo para o Lambda
O pacote [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) fornece definições de tipo para as funções do Lambda. Instale esse pacote quando sua função usar qualquer uma das seguintes opções:
+ Fontes de eventos comuns da AWS, como:
+ `APIGatewayProxyEvent`: para [integrações de proxy no Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html)
+ `SNSEvent`: para [notificações do Amazon Simple Notification Service](with-sns.md)
+ `SQSEvent`: para [mensagens do Amazon Simple Queue Service](with-sqs.md)
+ `S3Event`: para [eventos de gatilho do S3](with-s3.md)
+ `DynamoDBStreamEvent`: para [Amazon DynamoDB Streams](with-ddb.md)
+ O objeto [Context](typescript-context.md) do Lambda
+ O padrão do manipulador [callback](typescript-handler.md#typescript-handler-callback)
Para adicionar as definições de tipo do Lambda à sua função, instale `@types/aws-lambda` como uma dependência de desenvolvimento:
```
npm install -D @types/aws-lambda
```
Em seguida, importe os tipos de `aws-lambda`:
```
import { Context, S3Event, APIGatewayProxyEvent } from 'aws-lambda';
export const handler = async (event: S3Event, context: Context) => {
// Function code
};
```
A instrução `import ... from 'aws-lambda'` importa as definições de tipo. Ela não importa o pacote `aws-lambda` do npm, que é uma ferramenta de terceiros não relacionada. Para obter mais informações, consulte [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) no repositório DefinitelyTyped do GitHub.
**nota**
Você não precisa de [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) ao usar suas próprias definições de tipo personalizadas. Para obter um exemplo de função que define seu próprio tipo para um objeto de evento, consulte [Exemplo de função do Lambda em TypeScript](typescript-handler.md#typescript-example-code).
# Definir o manipulador de função do Lambda em TypeScript
O *manipulador* da função do Lambda é o método no código da função que processa eventos. Quando sua função é invocada, o Lambda executa o método do manipulador. A função é executada até que o manipulador retorne uma resposta, seja encerrado ou atinja o tempo limite.
Esta página descreve como trabalhar com manipuladores de função do Lambda em TypeScript, incluindo opções para a configuração de projeto, convenções de nomenclatura e práticas recomendadas. Além disso, esta página apresenta um exemplo de uma função do Lambda em TypeScript que aceita informações sobre um pedido, produz um recibo em formato de texto e armazena esse arquivo em um bucket do Amazon Simple Storage Service (Amazon S3). Para obter mais informações sobre como implantar a função após gravá-la, consulte [Implantar código TypeScript transcompilado no Lambda com arquivos .zip](typescript-package.md) ou [Implantar código TypeScript transcompilado no Lambda com imagens de contêiner](typescript-image.md).
**Topics**
+ [
## Configurar seu projeto em TypeScript
](#typescript-handler-setup)
+ [
## Exemplo de função do Lambda em TypeScript
](#typescript-example-code)
+ [
## Módulos CommonJS e ES
](#typescript-commonjs-es-modules)
+ [
## Inicialização do Node.js
](#typescript-initialization)
+ [
## Convenções de nomenclatura para manipuladores
](#typescript-handler-naming)
+ [
## Definição e acesso ao objeto do evento de entrada
](#typescript-example-input)
+ [
## Padrões de manipulador válidos para funções TypeScript
](#typescript-handler-signatures)
+ [
## Usar o SDK para JavaScript v3 em seu manipulador
](#typescript-example-sdk-usage)
+ [
## Acesso a variáveis de ambiente
](#typescript-example-envvars)
+ [
## Usar o estado global
](#typescript-handler-state)
+ [
## Práticas recomendadas de codificação para funções do Lambda em TypeScript
](#typescript-best-practices)
## Configurar seu projeto em TypeScript
Use um ambiente de desenvolvimento integrado (IDE) ou editor de texto local para escrever o código de função TypeScript. Não é possível criar código TypeScript no console do Lambda.
Há várias maneiras de inicializar um projeto do Lambda em TypeScript. Por exemplo, é possível criar um projeto padrão usando o `npm`, criar uma [aplicação do AWS SAM](typescript-package.md#aws-sam-ts), ou criar uma [aplicação do AWS CDK](typescript-package.md#aws-cdk-ts). Para criar um projeto usando o `npm`:
```
npm init
```
Seu código de função reside em um arquivo `.ts`, que você transcompila em um arquivo JavaScript em tempo de compilação. É possível usar o [esbuild](https://esbuild.github.io/) ou o compilador TypeScript da Microsoft (`tsc`) para transcompilar seu código TypeScript em JavaScript. Para usar o esbuild, adicione-o como uma dependência de desenvolvimento:
```
npm install -D esbuild
```
Um projeto típico de função do Lambda em TypeScript segue esta estrutura geral:
```
/project-root
├── index.ts - Contains main handler
├── dist/ - Contains compiled JavaScript
├── package.json - Project metadata and dependencies
├── package-lock.json - Dependency lock file
├── tsconfig.json - TypeScript configuration
└── node_modules/ - Installed dependencies
```
## Exemplo de função do Lambda em TypeScript
O exemplo de código apresentado a seguir para uma função do Lambda em Node.js aceita informações sobre um pedido, produz um recibo em formato de texto e armazena esse arquivo em um bucket do Amazon S3. Este exemplo define um tipo de evento personalizado (`OrderEvent`). Para saber como importar definições de tipo para fontes de eventos da AWS, consulte [Definições de tipo para o Lambda](lambda-typescript.md#typescript-type-definitions).
**nota**
Este exemplo usa um manipulador de módulo ES. O Lambda oferece suporte a manipuladores de módulo ES e CommonJS. Para obter mais informações, consulte [Módulos CommonJS e ES](nodejs-handler.md#nodejs-commonjs-es-modules).
**Example Função do Lambda index.ts**
```
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
// Initialize the S3 client outside the handler for reuse
const s3Client = new S3Client();
// Define the shape of the input event
type OrderEvent = {
order_id: string;
amount: number;
item: string;
}
/**
* Lambda handler for processing orders and storing receipts in S3.
*/
export const handler = async (event: OrderEvent): Promise => {
try {
// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
throw new Error('RECEIPT_BUCKET environment variable is not set');
}
// Create the receipt content and key destination
const receiptContent = `OrderID: ${event.order_id}\nAmount: $${event.amount.toFixed(2)}\nItem: ${event.item}`;
const key = `receipts/${event.order_id}.txt`;
// Upload the receipt to S3
await uploadReceiptToS3(bucketName, key, receiptContent);
console.log(`Successfully processed order ${event.order_id} and stored receipt in S3 bucket ${bucketName}`);
return 'Success';
} catch (error) {
console.error(`Failed to process order: ${error instanceof Error ? error.message : 'Unknown error'}`);
throw error;
}
};
/**
* Helper function to upload receipt to S3
*/
async function uploadReceiptToS3(bucketName: string, key: string, receiptContent: string): Promise {
try {
const command = new PutObjectCommand({
Bucket: bucketName,
Key: key,
Body: receiptContent
});
await s3Client.send(command);
} catch (error) {
throw new Error(`Failed to upload receipt to S3: ${error instanceof Error ? error.message : 'Unknown error'}`);
}
}
```
Este arquivo `index.ts` contém as seguintes seções de código:
+ Bloco `import`: utilize este bloco para incluir as bibliotecas necessárias para a função do Lambda, como [clientes do AWS SDK](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/the-request-object.html).
+ Declaração de `const s3Client`: inicializa um [cliente do Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/) fora da função do manipulador. Isso faz com que o Lambda execute esse código durante a [fase de inicialização](lambda-runtime-environment.md#runtimes-lifecycle-ib), e o cliente é preservado para [reutilização em várias invocações](lambda-runtime-environment.md#execution-environment-reuse).
+ `type OrderEvent`: define a estrutura do evento de entrada esperado.
+ `export const handler`: esta é a função de manipulação principal invocada pelo Lambda. Ao implantar sua função, especifique `index.handler` para a propriedade [Handler](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler). O valor da propriedade `Handler` é o nome do arquivo e o nome do método do manipulador exportado, separados por um ponto.
+ Função `uploadReceiptToS3`: uma função auxiliar referenciada pela função do manipulador principal.
Para que esta função funcione corretamente, seu [ perfil de execução](lambda-intro-execution-role.md) deve permitir a ação `s3:PutObject`. Além disso, certifique-se de definir a variável de ambiente `RECEIPT_BUCKET`. Após uma invocação com êxito, o bucket do Amazon S3 deve conter um arquivo de recibo.
## Módulos CommonJS e ES
O Node.js oferece suporte a dois sistemas de módulos, CommonJS e ECMAScript (módulos ES). O Lambda recomenda o uso de módulos ES, pois eles oferecem suporte à espera de alto nível, o que permite que tarefas assíncronas sejam concluídas durante a [inicialização do ambiente de execução](#typescript-initialization).
O Node.js trata arquivos com uma extensão de nome de arquivo `.cjs` como módulos CommonJS, enquanto uma extensão `.mjs` denota módulos ES. Por padrão, o Node.js trata arquivos com a extensão do nome de arquivo `.js` como módulos CommonJS. É possível configurar o Node.js para tratar arquivos `.js` como módulos ES especificando o `type` como `module` no arquivo `package.json` da função. É possível configurar o Node.js no Lambda para detectar automaticamente se um arquivo `.js` deve ser tratado como CommonJS ou como um módulo ES adicionando o sinalizador `—experimental-detect-module` à variável de ambiente `NODE_OPTIONS`. Para obter mais informações, consulte [Recursos experimentais do Node.js](lambda-nodejs.md#nodejs-experimental-features).
Os exemplos a seguir mostram manipuladores de funções escritos usando módulos ES e módulos CommonJS. Todos os exemplos restantes nesta página usam módulos ES.
## Inicialização do Node.js
O Node.js utiliza um modelo de E/S sem bloqueio que oferece suporte a operações assíncronas eficientes usando um loop de eventos. Por exemplo, se o Node.js fizer uma chamada de rede, a função continuará processando outras operações sem bloquear uma resposta da rede. Quando a resposta da rede é recebida, ela é colocada na fila de retorno de chamada. As tarefas da fila são processadas quando a tarefa atual é concluída.
O Lambda recomenda usar espera de alto nível para que as tarefas assíncronas iniciadas durante a inicialização do ambiente de execução sejam concluídas durante a inicialização. As tarefas assíncronas que não são concluídas durante a inicialização geralmente são executadas durante a primeira chamada da função. Isso pode causar comportamento inesperado ou erros. Por exemplo, sua inicialização de função pode fazer uma chamada de rede para buscar um parâmetro da AWS Parameter Store. Se essa tarefa não for concluída durante a inicialização, o valor poderá ser nulo durante uma invocação. Também pode haver um atraso entre a inicialização e a invocação, o que pode gerar erros em operações sensíveis a tempo. Em especial, as chamadas de serviço da AWS podem depender de assinaturas de solicitação sensíveis a tempo, resultando em falhas se a chamada de serviço não for concluída durante a fase de inicialização. A conclusão de tarefas durante a inicialização geralmente melhora a performance da inicialização a frio e a performance da primeira invocação ao usar a simultaneidade provisionada. Para obter mais informações, consulte a postagem no nosso blog [Uso de módulos ES do Node.js e de espera em nível superior no AWS Lambda](https://aws.amazon.com/blogs/compute/using-node-js-es-modules-and-top-level-await-in-aws-lambda).
## Convenções de nomenclatura para manipuladores
Quando você [configura uma função](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler), o valor da configuração do Handler é o nome do arquivo e o nome do módulo do handler exportado, separados por um ponto. O padrão para as funções criadas no console e para os exemplos deste guia é `index.handler`. Isso indica o método de `handler` que é exportado do arquivo `index.js` ou `index.mjs`.
Se você criar uma função no console usando um nome de arquivo ou nome de manipulador de funções diferente, deverá editar o nome do manipulador padrão.
**Para alterar o nome do manipulador de funções (console)**
1. Abra a página [Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda e escolha sua função.
1. Escolha a guia **Código**.
1. Role para baixo até o painel **Configurações de runtime** e escolha **Editar**.
1. Em **Manipulador**, insira o novo nome para seu manipulador de funções.
1. Escolha **Salvar**.
## Definição e acesso ao objeto do evento de entrada
O formato de entrada JSON é o mais comum e padrão para funções do Lambda. Neste exemplo, a função espera uma entrada semelhante à seguinte:
```
{
"order_id": "12345",
"amount": 199.99,
"item": "Wireless Headphones"
}
```
Ao trabalhar com funções do Lambda em TypeScript, é possível definir a estrutura do evento de entrada usando um tipo ou interface. Neste exemplo, definimos a estrutura do evento usando um tipo:
```
type OrderEvent = {
order_id: string;
amount: number;
item: string;
}
```
Depois de definir o tipo ou a interface, use-a na assinatura do manipulador para garantir a segurança do tipo:
```
export const handler = async (event: OrderEvent): Promise => {
```
Durante a compilação, o TypeScript valida se o objeto do evento contém os campos obrigatórios com os tipos corretos. Por exemplo, o compilador TypeScript retornará um erro se você tentar usar `event.order_id` como um número ou `event.amount` como uma string.
## Padrões de manipulador válidos para funções TypeScript
Recomendamos usar [async/await](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-async-await.html) para declarar o manipulador da função em vez de usar [retornos de chamada](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-a-callback-function.html). O uso de async/await é uma forma concisa e legível de escrever código assíncrono em Node.js, sem a necessidade de usar retornos de chamada aninhados ou promessas de encadeamento. Com async/await, é possível escrever um código que seja lido como código síncrono e, ao mesmo tempo, seja assíncrono e sem bloqueio.
Os exemplos desta seção usam o tipo `S3Event`. No entanto, é possível usar quaisquer outros tipos de evento da AWS no pacote [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) ou definir seu próprio tipo de evento. Para usar tipos de @types/aws-lambda:
1. Adicione o pacote @types/aws-lambda como uma dependência de desenvolvimento:
```
npm install -D @types/aws-lambda
```
1. Importe os tipos necessários, como `Context`, `S3Event` ou `Callback`.
### manipuladores de funções assíncronas (recomendados)
A palavra-chave `async` marca uma função como assíncrona, e a palavra-chave `await` pausa a execução da função até que uma `Promise` seja resolvida. O manipulador aceita os seguintes argumentos:
+ `event`: contém os dados de entrada passados para sua função.
+ `context`: contém informações sobre a invocação, a função e o ambiente de execução. Para obter mais informações, consulte [Usar o objeto de contexto do Lambda para recuperar informações das funções em TypeScript](typescript-context.md).
As assinaturas válidas para o padrão async/await são:
```
export const handler = async (event: S3Event): Promise => { };
```
```
export const handler = async (event: S3Event, context: Context): Promise => { };
```
**nota**
Ao processar matrizes de itens de forma assíncrona, certifique-se de usar await com `Promise.all` para garantir que todas as operações sejam concluídas. Métodos como `forEach` não esperam que os retornos de chamada assíncronos sejam concluídos. Para obter mais informações, consulte [Array.prototype.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) na documentação do Mozilla.
### Manipuladores de funções síncronas
Quando sua função não executa nenhuma tarefa assíncrona, é possível usar um manipulador de função síncrona, usando uma das assinaturas de função a seguir:
```
export const handler = (event: S3Event): void => { };
```
```
export const handler = (event: S3Event, context: Context): void => { };
```
### Manipuladores de função de streaming de resposta
O Lambda oferece suporte ao streaming de resposta com Node.js. Os manipuladores de funções de streaming de resposta usam o decorador awslambda.streamifyResponse() e usam 3 parâmetros: event, responseStream e context. A assinatura da função é:
```
export const handler = awslambda.streamifyResponse(async (event: APIGatewayProxyEvent, responseStream: NodeJS.WritableStream, context: Context) => { });
```
Para acessar mais informações, consulte Streaming de respostas para funções do Lambda.
### Manipuladores de funções baseadas em retorno de chamada
**nota**
Só há suporte para os manipuladores de funções baseadas em retorno de chamada até o Node.js 22. A partir do Node.js 24, as tarefas assíncronas devem ser implementadas usando manipuladores de funções assíncronas.
Os manipuladores de funções baseadas em retorno de chamada podem usar os argumentos event, context e callback. O argumento de retorno de chamada espera um `Error` e uma resposta, a qual deve ser serializável em JSON.
Aqui está a assinatura válida para o padrão do manipulador de retorno de chamada:
```
export const handler = (event: S3Event, context: Context, callback: Callback): void => { };
```
A função continuará em execução até que o [loop de evento](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/) esteja vazio ou o tempo da função se esgote. A resposta não é enviada para o chamador até que todas as tarefas de loop de evento estejam concluídas. Se a função expirar, um erro será retornado. É possível configurar o runtime para enviar a resposta imediatamente, definindo [context.callbackWaitsForEmptyEventLoop](typescript-context.md) como false.
**Example Função TypeScript com retorno de chamada**
O exemplo a seguir usa `APIGatewayProxyCallback`, um tipo de retorno de chamada especializado específico para integrações do API Gateway. A maioria das fontes de eventos da AWS usa o tipo genérico `Callback` mostrado nas assinaturas acima.
```
import { Context, APIGatewayProxyCallback, APIGatewayEvent } from 'aws-lambda';
export const lambdaHandler = (event: APIGatewayEvent, context: Context, callback: APIGatewayProxyCallback): void => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
callback(null, {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
});
};
```
## Usar o SDK para JavaScript v3 em seu manipulador
Frequentemente, você usará as funções do Lambda para interagir com ou fazer atualizações em outros recursos da AWS. A maneira mais simples de interagir com esses recursos é usar o AWS SDK para JavaScript. Todos os runtimes Node.js do Lambda compatíveis incluem o [SDK para JavaScript versão 3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/). No entanto, recomendamos fortemente que você inclua os clientes do AWS SDK necessários em seu pacote de implantação. Isso maximiza a [compatibilidade com versões anteriores](runtimes-update.md#runtime-update-compatibility) durante futuras atualizações do runtime do Lambda.
Para adicionar as dependências do SDK à sua função, use o comando `npm install` para os clientes específicos do SDK que você precisa. No código de exemplo, usamos o [cliente do Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/). Adicione essa dependência executando o seguinte comando no diretório que contém seu arquivos `package.json`:
```
npm install @aws-sdk/client-s3
```
No código da função, importe o cliente e os comandos necessários, conforme demonstrado na função de exemplo:
```
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
```
Em seguida, inicialize um [cliente do Amazon S3:](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/)
```
const s3Client = new S3Client();
```
Neste exemplo, inicializamos nosso cliente do Amazon S3 fora da função do manipulador principal para evitar a necessidade que inicializá-lo a cada vez que nossa função é invocada. Após inicializar o cliente do SDK, você poderá usá-lo para fazer chamadas de API para esse serviço da AWS. O código de exemplo chama a API [PutObject](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/PutObjectCommand/) do Amazon S3 da seguinte forma:
```
const command = new PutObjectCommand({
Bucket: bucketName,
Key: key,
Body: receiptContent
});
```
## Acesso a variáveis de ambiente
No código do manipulador, você pode fazer referência a quaisquer [variáveis de ambiente](configuration-envvars.md) usando o método `process.env`. Neste exemplo, referenciamos a variável de ambiente `RECEIPT_BUCKET` definida usando as seguintes linhas de código:
```
// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
throw new Error('RECEIPT_BUCKET environment variable is not set');
}
```
## Usar o estado global
O Lambda executa seu código estático durante a [fase de inicialização](lambda-runtime-environment.md#runtimes-lifecycle-ib) antes de invocar a função pela primeira vez. Os recursos criados durante a inicialização permanecem na memória entre as invocações, para que você possa evitar ter que criá-los toda vez que invocar sua função.
No código de exemplo, o código de inicialização do cliente do S3 está fora do manipulador. O runtime inicializa o cliente antes que a função manipule seu primeiro evento e o cliente permanece disponível para reutilização em todas as invocações.
## Práticas recomendadas de codificação para funções do Lambda em TypeScript
Siga estas diretrizes ao criar funções do Lambda:
+ **Separe o manipulador do Lambda da lógica central.** Isso permite que você crie uma função mais fácil para teste de unidade.
+ **Controle as dependências no pacote de implantação da função. ** O ambiente de execução do AWS Lambda contém várias bibliotecas. Para os runtimes em Node.js e Python, os AWS SDKs estão incluídos. Para habilitar o conjunto de recursos e atualizações de segurança mais recente, o Lambda atualizará periodicamente essas bibliotecas. Essas atualizações podem introduzir alterações sutis ao comportamento de sua função do Lambda. Para ter controle total das dependências usadas por sua função, empacote todas as dependências em seu pacote de implantação.
+ **Minimize a complexidade de suas dependências.** Prefira frameworks mais simples que sejam carregados rapidamente no startup do [ambiente de execução](lambda-runtime-environment.md).
+ **Minimize o tamanho do pacote de implantação para conter somente o necessário para o runtime. ** Isso reduzirá a quantidade de tempo necessária para que seu pacote de implantação seja obtido por download e desempacotado antes da invocação.
**Aproveite a reutilização do ambiente de execução para melhorar a performance da função.** Inicialize clientes SDK e conexões de banco de dados fora do manipulador de funções e armazene em cache os ativos estáticos localmente no diretório `/tmp`. As invocações subsequentes processadas pela mesma instância da função podem reutilizar esses recursos. Isso economiza custos reduzindo o runtime da função.
Para evitar possíveis vazamentos de dados entre invocações, não use o ambiente de execução para armazenar dados do usuário, eventos ou outras informações com implicações de segurança. Se sua função depende de um estado mutável que não pode ser armazenado na memória dentro do manipulador, considere criar uma função separada ou versões separadas de uma função para cada usuário.
**Use uma diretiva de keep-alive para manter conexões persistentes.** O Lambda limpa conexões ociosas ao longo do tempo. A tentativa de reutilizar uma conexão ociosa ao invocar uma função resultará em um erro de conexão. Para manter sua conexão persistente, use a diretiva keep-alive associada ao runtime. Para obter um exemplo, consulte [Reutilizar conexões com keep-alive em Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-reusing-connections.html).
**Use [variáveis de ambiente](configuration-envvars.md) para passar parâmetros operacionais para sua função.** Por exemplo, se estiver gravando em um bucket do Amazon S3, em vez fixar no código o nome do bucket em que você está gravando, configure o nome do bucket como uma variável de ambiente.
**Evite usar invocações recursivas** em sua função do Lambda, em que a função invoca a si mesma ou inicia um processo que pode invocar a função novamente. Isso pode levar a um volume não intencional de invocações da função e a custos elevados. Se você observar um volume não intencional de invocações, defina a simultaneidade reservada da função como `0` imediatamente para limitar todas as invocações da função enquanto atualiza o código.
**Não use APIs não documentadas e não públicas** no código da função do Lambda. Para os tempos de execução gerenciados pelo AWS Lambda, o Lambda aplica periodicamente atualizações funcionais e de segurança às APIs internas do Lambda. Essas atualizações internas da API podem ser incompatíveis com versões anteriores, gerando consequências não intencionais, como falhas de invocação, caso sua função tenha dependência nessas APIs não públicas. Consulte [a referência da API](https://docs.aws.amazon.com/lambda/latest/api/welcome.html) para obter uma lista de APIs disponíveis publicamente.
**Escreva um código idempotente.** Escrever um código idempotente para suas funções garante que eventos duplicados sejam tratados da mesma maneira. Seu código deve validar eventos adequadamente e lidar corretamente com eventos duplicados. Para obter mais informações, consulte [Como torno minha função do Lambda idempotente?](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-function-idempotent/).
# Implantar código TypeScript transcompilado no Lambda com arquivos .zip
Antes que você possa implantar o código TypeScript ao AWS Lambda, é necessário transcompilá-lo para JavaScript. Esta página explica três maneiras de criar e implantar o código TypeScript no Lambda com arquivos .zip:
+ [Usar o AWS Serverless Application Model (AWS SAM)](#aws-sam-ts)
+ [Usar o AWS Cloud Development Kit (AWS CDK)](#aws-cdk-ts)
+ [Usar a AWS Command Line Interface (AWS CLI) e o esbuild](#aws-cli-ts)
O AWS SAM e o AWS CDK simplificam a construção e a implantação de funções do TypeScript. A [especificação do modelo do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html) fornece uma sintaxe simples e clara para descrever as funções, APIs, permissões, configurações e eventos do Lambda que compõem sua aplicação sem servidor. O [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/home.html) permite criar aplicações confiáveis, escaláveis e com bom custo-benefício na nuvem com o considerável poder expressivo de uma linguagem de programação. O AWS CDK destina-se a usuários da AWS bastante experientes ou moderadamente experientes. Tanto o AWS CDK como o AWS SAM usam esbuild para transcompilar código TypeScript em JavaScript.
## Uso do AWS SAM para implantar código TypeScript no Lambda
Siga as etapas abaixo para baixar, criar e implantar uma aplicação de exemplo do Hello World TypeScript usando o AWS SAM. Esta aplicação implementa um backend básico da API. Consiste em um endpoint do Amazon API Gateway e uma função Lambda. Ao enviar uma solicitação GET ao endpoint do API Gateway, você invoca a função Lambda. A função retorna uma mensagem `hello world`.
**nota**
O AWS SAM usa esbuild para criar funções do Lambda do Node.js a partir de código do TypeScript. O suporte ao esbuild está atualmente em pré-visualização pública. Durante a pré-visualização pública, o suporte ao esbuild pode estar sujeito a alterações incompatíveis com versões anteriores.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [CLI do AWS SAM, versão 1.75 ou posterior](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+ Node.js
**Implantar uma aplicação de exemplo do AWS SAM**
1. Inicialize a aplicação usando o modelo Hello World TypeScript.
```
sam init --app-template hello-world-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. (Opcional) A aplicação de exemplo inclui configurações para ferramentas bastante usadas, como [ESLlint](https://eslint.org/) para linting de código e [Jest](https://jestjs.io/) para testes unitários. Para executar comandos lint e de teste:
```
cd sam-app/hello-world
npm install
npm run lint
npm run test
```
1. Crie a aplicação.
```
cd sam-app
sam build
```
1. Implante o aplicativo.
```
sam deploy --guided
```
1. Siga as instruções na tela. Para aceitar as opções padrão fornecidas na experiência interativa, responda com `Enter`.
1. A saída mostra o endpoint para a API REST. Abra o endpoint em um navegador para testar a função. Você deverá visualizar esta resposta:
```
{"message":"hello world"}
```
1. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
sam delete
```
## Usar o AWS CDK para implantar código TypeScript no Lambda
Siga as etapas abaixo para criar e implantar uma aplicação TypeScript de exemplo usando o AWS CDK. Esta aplicação implementa um backend básico da API. Consiste em um endpoint do API Gateway e uma função Lambda. Ao enviar uma solicitação GET ao endpoint do API Gateway, você invoca a função Lambda. A função retorna uma mensagem `hello world`.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versão 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ Node.js
+ [Docker](https://www.docker.com/get-started/) ou [esbuild](https://esbuild.github.io/)
**Implantar uma aplicação de exemplo do AWS CDK**
1. Crie um diretório de projeto para sua aplicação.
```
mkdir hello-world
cd hello-world
```
1. Inicialize a aplicação.
```
cdk init app --language typescript
```
1. Adicione o pacote [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) como uma dependência de desenvolvimento. Esse pacote contém as definições de tipo para o Lambda.
```
npm install -D @types/aws-lambda
```
1. Abra o diretório **lib**. Você deverá ver um arquivo chamado **hello-world-stack.ts**. Crie dois novos arquivos neste diretório: **hello-world.function.ts** e **hello-world.ts**.
1. Abra o **hello-world.function.ts** e adicione o código a seguir ao arquivo. Este é o código da função Lambda.
**nota**
A instrução `import` importa as definições de tipo de [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Ela não importa o pacote `aws-lambda` do NPM, que é uma ferramenta de terceiros não relacionada. Para obter mais informações, consulte [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) no repositório DefinitelyTyped do GitHub.
```
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. Abra o **hello-world.ts** e adicione o código a seguir ao arquivo. Ele contém o [constructo NodejsFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), que cria a função Lambda, e o [constructo LambdaRestApi](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), que cria a API REST.
```
import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
export class HelloWorld extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
const helloFunction = new NodejsFunction(this, 'function');
new LambdaRestApi(this, 'apigw', {
handler: helloFunction,
});
}
}
```
O constructo `NodejsFunction` assume o seguinte, por padrão:
+ O manipulador de funções chama-se `handler`.
+ O arquivo .ts que contém o código da função (**hello-world.function.ts**) está no mesmo diretório que o arquivo .ts que contém o constructo (**hello-world.ts**). O constructo usa o ID do constructo (“hello-world”) e o nome de arquivo do manipulador do Lambda (“function”) para encontrar o código da função. Por exemplo, se o código da função estiver em um arquivo chamado **hello-world.my-function.ts**, o arquivo **hello-world.ts** deverá referenciar o código da função deste modo:
```
const helloFunction = new NodejsFunction(this, 'my-function');
```
É possível alterar esse comportamento e configurar outros parâmetros do esbuild. Para mais informações, consulte [Configuring esbuild](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html#configuring-esbuild) (Configurar esbuild) na referência de API do AWS CDK.
1. Abra o **hello-world-stack.ts**. Este é o código que define sua [pilha do AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Substitua o código pelo seguinte:
```
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';
export class HelloWorldStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new HelloWorld(this, 'hello-world');
}
}
```
1. a partir do diretório do `hello-world` que contém seu arquivo `cdk.json`, implante sua aplicação.
```
cdk deploy
```
1. O AWS CDK cria e empacota a função Lambda usando esbuild e implanta a função no runtime do Lambda. A saída mostra o endpoint para a API REST. Abra o endpoint em um navegador para testar a função. Você deverá visualizar esta resposta:
```
{"message":"hello world"}
```
Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
## Usar a AWS CLI e o esbuild para implantar código TypeScript no Lambda
O exemplo a seguir demonstra como transcompilar e implantar código TypeScript no Lambda usando o esbuild e a AWS CLI. O esbuild produz um arquivo JavaScript com todas as dependências. Este é o único arquivo que você precisa adicionar ao arquivo.zip.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ Node.js
+ Uma [função de execução](lambda-intro-execution-role.md) para a função Lambda
+ Para usuários do Windows, um utilitário de arquivo zip, como o [7zip](https://www.7-zip.org/download.html).
**Implantar uma função de exemplo**
1. Em sua máquina local, crie um diretório de projeto para sua nova função.
1. Crie um novo projeto Node.js com npm ou um gerenciador de pacotes de sua escolha.
```
npm init
```
1. Adicione pacotes [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) e [esbuild](https://esbuild.github.io/) como dependência de desenvolvimento. O pacote `@types/aws-lambda` contém as definições de tipo para o Lambda.
```
npm install -D @types/aws-lambda esbuild
```
1. Crie um novo arquivo chamado **index.ts**. Adicione o código a seguir ao novo arquivo. Este é o código da função Lambda. A função retorna uma mensagem `hello world`. A função não cria recursos do API Gateway.
**nota**
A instrução `import` importa as definições de tipo de [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Ela não importa o pacote `aws-lambda` do NPM, que é uma ferramenta de terceiros não relacionada. Para obter mais informações, consulte [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) no repositório DefinitelyTyped do GitHub.
```
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. Adicione um script de compilação ao arquivo **package.json**. Isso configura o esbuild para criar automaticamente o pacote de implantação .zip. Para obter mais informações, consulte [Build scripts](https://esbuild.github.io/getting-started/#build-scripts) (Scripts de compilação) na documentação do esbuild.
------
#### [ Linux and MacOS ]
```
"scripts": {
"prebuild": "rm -rf dist",
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js",
"postbuild": "cd dist && zip -r index.zip index.js*"
},
```
------
#### [ Windows ]
Neste exemplo, o comando `"postbuild"` usa o utilitário [7zip](https://www.7-zip.org/download.html) para criar o arquivo .zip. Use seu próprio utilitário zip do Windows preferido e modifique o comando conforme necessário.
```
"scripts": {
"prebuild": "del /q dist",
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js",
"postbuild": "cd dist && 7z a -tzip index.zip index.js*"
},
```
------
1. Construa o pacote.
```
npm run build
```
1. Crie uma função Lambda usando o pacote de implantação .zip. Substitua o texto em destaque pelo nome do recurso da Amazon (ARN) da [função de execução](lambda-intro-execution-role.md).
```
aws lambda create-function --function-name hello-world --runtime "nodejs24.x" --role arn:aws:iam::123456789012:role/lambda-ex --zip-file "fileb://dist/index.zip" --handler index.handler
```
1. [Execute um evento de teste](testing-functions.md) para confirmar que a função retorna a resposta a seguir. Para invocar essa função usando o API Gateway, [crie e configure uma API REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-create-api.html).
```
{
"statusCode": 200,
"body": "{\"message\":\"hello world\"}"
}
```
# Implantar código TypeScript transcompilado no Lambda com imagens de contêiner
Você pode implantar seu código TypeScript em uma função do AWS Lambda como [imagem de contêiner](images-create.md) Node.js. A AWS fornece [imagens base](nodejs-image.md#nodejs-image-base) para Node.js para ajudar você a criar a imagem do contêiner. Essas imagens base são pré-carregadas com um runtime de linguagem e outros componentes necessários para executar a imagem no Lambda. A AWS fornece um Dockerfile para cada uma das imagens base para ajudar a criar sua imagem de contêiner.
Se você usa uma imagem base pertencente a uma comunidade ou empresa privada, é necessário adicionar um [cliente de interface de runtime (RIC) Node.js](nodejs-image.md#nodejs-image-clients) à imagem base para torná-la compatível com o Lambda.
O Lambda oferece um emulador de interface de runtime para testes locais. As imagens base da AWS para o Node.js incluem o emulador de interface de runtime. Caso use uma imagem base alternativa, como uma imagem Alpine Linux ou Debian, você poderá [criar o emulador na sua imagem](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#build-rie-into-your-base-image) ou [instalá-lo na máquina local](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#test-an-image-without-adding-rie-to-the-image).
## Usar uma imagem base Node.js para criar e empacotar código da função TypeScript
### Pré-requisitos
Para executar as etapas desta seção, você deve ter o seguinte:
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [Docker](https://docs.docker.com/get-docker) (versão mínima 25.0.0)
+ O plug-in [buildx](https://github.com/docker/buildx/blob/master/README.md) do Docker.
+ Node.js 22.x
### Criação de uma imagem a partir de uma imagem base
**Para criar uma imagem a partir de uma imagem base da AWS para o Lambda**
1. Em sua máquina local, crie um diretório de projeto para sua nova função.
1. Crie um novo projeto Node.js com `npm` ou um gerenciador de pacotes de sua escolha.
```
npm init
```
1. Adicione pacotes [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) e [esbuild](https://esbuild.github.io/) como dependência de desenvolvimento. O pacote `@types/aws-lambda` contém as definições de tipo para o Lambda.
```
npm install -D @types/aws-lambda esbuild
```
1. Adicione um [script de construção](https://esbuild.github.io/getting-started/#build-scripts) ao arquivo `package.json`.
```
"scripts": {
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js"
}
```
1. Crie um novo arquivo chamado `index.ts`. Adicione o código de exemplo a seguir ao novo arquivo. Este é o código da função do Lambda. A função retorna uma mensagem `hello world`.
**nota**
A instrução `import` importa as definições de tipo de [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Ela não importa o pacote `aws-lambda` do NPM, que é uma ferramenta de terceiros não relacionada. Para obter mais informações, consulte [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) no repositório DefinitelyTyped do GitHub.
```
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. Crie um novo Dockerfile com a seguinte configuração:
+ Defina a propriedade `FROM` como o URI da imagem base.
+ Defina o argumento `CMD` para especificar o manipulador de funções do Lambda.
O exemplo de Dockerfile a seguir usa uma compilação em várias etapas. A primeira etapa transcompila o código TypeScript em JavaScript. A segunda etapa produz uma imagem de contêiner contendo somente arquivos JavaScript e dependências de produção.
Observe que o Dockerfile de exemplo não inclui uma [instrução USER](https://docs.docker.com/reference/dockerfile/#user). Quando você implanta uma imagem de contêiner no Lambda, o Lambda define automaticamente um usuário padrão do Linux com permissões de privilégio mínimo. Isso é diferente do comportamento padrão do Docker, que adota o usuário `root` como padrão quando nenhuma instrução `USER` é fornecida.
**Example Dockerfile**
```
FROM public.ecr.aws/lambda/nodejs:22 as builder
WORKDIR /usr/app
COPY package.json index.ts ./
RUN npm install
RUN npm run build
FROM public.ecr.aws/lambda/nodejs:22
WORKDIR ${LAMBDA_TASK_ROOT}
COPY --from=builder /usr/app/dist/* ./
CMD ["index.handler"]
```
1. Crie a imagem do Docker com o comando [docker build](https://docs.docker.com/engine/reference/commandline/build/). O exemplo a seguir nomeia a imagem como `docker-image` e atribui a ela a [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) `test`. Para tornar sua imagem compatível com o Lambda, é necessário usar a opção `--provenance=false`.
```
docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test .
```
**nota**
O comando especifica a opção `--platform linux/amd64` para garantir que seu contêiner seja compatível com o ambiente de execução do Lambda, independentemente da arquitetura da sua máquina de compilação. Se você pretende criar uma função do Lambda usando a arquitetura do conjunto de instruções ARM64, certifique-se de alterar o comando para usar a opção `--platform linux/arm64` em vez disso.
### (Opcional) Teste a imagem localmente
1. Inicie a imagem do Docker com o comando **docker run**. Neste exemplo, `docker-image` é o nome da imagem e `test` é a tag.
```
docker run --platform linux/amd64 -p 9000:8080 docker-image:test
```
Esse comando executa a imagem como um contêiner e cria um endpoint local em `localhost:9000/2015-03-31/functions/function/invocations`.
**nota**
Se você criou a imagem do Docker para a arquitetura do conjunto de instruções ARM64, certifique-se de usar a opção `--platform linux/arm64`, em vez de `--platform linux/amd64`.
1. Em uma nova janela de terminal, publique um evento no endpoint local.
------
#### [ Linux/macOS ]
No Linux e no MacOS, execute o seguinte comando `curl`:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
```
Esse comando invoca a função com um evento vazio e retorna uma resposta. Caso esteja usando seu próprio código de função em vez do código de função de exemplo, você talvez queira invocar a função com uma carga útil JSON. Exemplo:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'
```
------
#### [ PowerShell ]
No PowerShell, execute o seguinte comando `Invoke-WebRequest`:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json"
```
Esse comando invoca a função com um evento vazio e retorna uma resposta. Caso esteja usando seu próprio código de função em vez do código de função de exemplo, você talvez queira invocar a função com uma carga útil JSON. Exemplo:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json"
```
------
1. Obtenha o ID do contêiner.
```
docker ps
```
1. Use o comando [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) para parar o contêiner. Nesse comando, substitua `3766c4ab331c` pelo ID do contêiner da etapa anterior.
```
docker kill 3766c4ab331c
```
### Implantação da imagem
**Para enviar a imagem ao Amazon ECR e criar a função do Lambda**
1. Execute o comando [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html) para autenticar a CLI do Docker no seu registro do Amazon ECR.
+ Defina o valor `--region` para a Região da AWS onde você deseja criar o repositório do Amazon ECR.
+ Substituir `111122223333` por seu ID da Conta da AWS.
```
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com
```
1. Crie um repositório no Amazon ECR usando o comando [create-repository](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/create-repository.html).
```
aws ecr create-repository --repository-name hello-world --region us-east-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE
```
**nota**
O repositório do Amazon ECR deve estar na mesma Região da AWS que a função do Lambda.
Se tiver êxito, você verá uma resposta como esta:
```
{
"repository": {
"repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world",
"registryId": "111122223333",
"repositoryName": "hello-world",
"repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world",
"createdAt": "2023-03-09T10:39:01+00:00",
"imageTagMutability": "MUTABLE",
"imageScanningConfiguration": {
"scanOnPush": true
},
"encryptionConfiguration": {
"encryptionType": "AES256"
}
}
}
```
1. Copie o `repositoryUri` da saída na etapa anterior.
1. Execute o comando [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) para aplicar uma tag na sua imagem local em seu repositório do Amazon ECR como a versão mais recente. Neste comando:
+ `docker-image:test` é o nome e a [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) da sua imagem do Docker. Esse é o nome e a tag da imagem que você especificou no comando `docker build`.
+ Substitua `` pelo `repositoryUri` que você copiou. Certifique-se de incluir `:latest` no final do URI.
```
docker tag docker-image:test :latest
```
Exemplo:
```
docker tag docker-image:test 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. Execute o comando [docker push](https://docs.docker.com/engine/reference/commandline/push/) para implantar a imagem local no repositório do Amazon ECR. Certifique-se de incluir `:latest` no final do URI do repositório.
```
docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. [Crie um perfil de execução](lambda-intro-execution-role.md#permissions-executionrole-api) para a função, caso ainda não tenha um. Você precisará do nome do recurso da Amazon (ARN) do perfil na próxima etapa.
1. Criar a função do Lambda. Em `ImageUri`, especifique o URI do repositório anterior. Certifique-se de incluir `:latest` no final do URI.
```
aws lambda create-function \
--function-name hello-world \
--package-type Image \
--code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \
--role arn:aws:iam::111122223333:role/lambda-ex
```
**nota**
É possível criar uma função usando uma imagem em uma conta da AWS diferente desde que a imagem esteja na mesma região da função do Lambda. Para obter mais informações, consulte [Permissões entre contas do Amazon ECR](images-create.md#configuration-images-xaccount-permissions).
1. Invoque a função.
```
aws lambda invoke --function-name hello-world response.json
```
Você obterá uma resposta parecida com esta:
```
{
"ExecutedVersion": "$LATEST",
"StatusCode": 200
}
```
1. Para ver a saída da função, verifique o arquivo `response.json`.
Para atualizar o código da função, você deve criar a imagem novamente, fazer upload da nova imagem no repositório do Amazon ECR e, em seguida, usar o comando [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) para implantar a imagem na função do Lambda.
O Lambda resolve a tag de imagem em um resumo de imagem específico. Isso significa que, se você apontar a tag de imagem que foi usada para implantar a função em uma nova imagem no Amazon ECR, o Lambda não atualizará automaticamente a função para usar a nova imagem.
Para implantar a nova imagem na mesma função do Lambda, você deverá usar o comando [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html), mesmo que a tag da imagem no Amazon ECR permaneça a mesma. No exemplo a seguir, a opção `--publish` cria uma nova versão da função usando a imagem de contêiner atualizada.
```
aws lambda update-function-code \
--function-name hello-world \
--image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \
--publish
```
# Usar o objeto de contexto do Lambda para recuperar informações das funções em TypeScript
Quando o Lambda executa a função, ele transmite um objeto de contexto para o [handler](typescript-handler.md). Esse objeto fornece métodos e propriedades que fornecem informações sobre a invocação, a função e o ambiente de execução.
Para habilitar a verificação de tipo para o objeto de contexto, é necessário adicionar o pacote [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) como uma dependência de desenvolvimento e importar o tipo `Context`. Para obter mais informações, consulte [Definições de tipo para o Lambda](lambda-typescript.md#typescript-type-definitions).
**Métodos de contexto**
+ `getRemainingTimeInMillis()`: retorna o número de milissegundos restantes antes do tempo limite da execução.
**Propriedades de contexto**
+ `functionName`: o nome da função do Lambda.
+ `functionVersion`: a [versão](configuration-versions.md) da função.
+ `invokedFunctionArn`: o nome do recurso da Amazon (ARN) usado para invocar a função. Indica se o invocador especificou um alias ou número de versão.
+ `memoryLimitInMB`: a quantidade de memória alocada para a função.
+ `awsRequestId`: o identificador da solicitação de invocação.
+ `logGroupName`: o grupo de logs da função.
+ `logStreamName`: a transmissão de log para a instância da função.
+ `identity`: (aplicativos móveis) informações sobre a identidade do Amazon Cognito que autorizou a solicitação.
+ `cognitoIdentityId`: a identidade autenticada do Amazon Cognito.
+ `cognitoIdentityPoolId`: o grupo de identidades do Amazon Cognito que autorizou a invocação.
+ `clientContext`: (aplicativos móveis) contexto do cliente fornecido ao Lambda pela aplicação cliente.
+ `client.installation_id`
+ `client.app_title`
+ `client.app_version_name`
+ `client.app_version_code`
+ `client.app_package_name`
+ `env.platform_version`
+ `env.platform`
+ `env.make`
+ `env.model`
+ `env.locale`
+ `Custom`: os valores personalizados que são definidos pela aplicação cliente.
+ `callbackWaitsForEmptyEventLoop`: por padrão (`true`), ao usar um manipulador de função baseado em retorno de chamada, o Lambda espera que o loop de eventos fique vazio após a execução do retorno de chamada antes de encerrar a invocação da função. Definido como `false` para enviar a resposta e encerrar a chamada imediatamente após a execução do retorno de chamada, em vez de aguardar até que o loop de eventos esteja vazio. Os eventos pendentes continuarão a ser executados durante a próxima invocação. Observe que o Lambda oferece suporte a manipuladores de funções baseados em retorno de chamada somente para runtimes do Node.js 22 e anteriores.
**Example arquivo index.ts**
O exemplo a seguir registra informações de contexto da função e retorna a localização dos logs.
Antes de usar esse código em uma função do Lambda, você deve adicionar o pacote [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) como uma dependência de desenvolvimento. Esse pacote contém as definições de tipo para o Lambda. Para obter mais informações, consulte [Definições de tipo para o Lambda](lambda-typescript.md#typescript-type-definitions).
```
import { Context } from 'aws-lambda';
export const lambdaHandler = async (event: string, context: Context): Promise => {
console.log('Remaining time: ', context.getRemainingTimeInMillis());
console.log('Function name: ', context.functionName);
return context.logStreamName;
};
```
# Registrar em log e monitorar funções do Lambda em TypeScript
O AWS Lambda monitora automaticamente as funções do Lambda e envia entradas de logs para o Amazon CloudWatch. Sua função do Lambda vem com um grupo de logs do CloudWatch Logs e uma transmissão de logs para cada instância de sua função. O ambiente de runtime do Lambda envia detalhes sobre cada invocação e outras saídas do código da função para o fluxo de logs. Para obter mais informações sobre o CloudWatch Logs, consulte [Enviar logs de função do Lambda para o CloudWatch Logs](monitoring-cloudwatchlogs.md).
Para exibir logs do código de função, você pode usar métodos no [objeto de console](https://nodejs.org/docs/latest-v18.x/api/console.html). Para um log mais detalhado, você pode usar qualquer biblioteca de registro em log que grava em `stdout` ou `stderr`.
**Topics**
+ [
## Usar bibliotecas e ferramentas de registro em log
](#typescript-tools-libraries)
+ [
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS SAM para registro em log estruturado
](#typescript-logging-sam)
+ [
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS CDK para registro em log estruturado
](#typescript-logging-cdk)
+ [
## Visualizar logs no console do Lambda
](#typescript-logging-console)
+ [
## Visualização de logs no console do CloudWatch
](#typescript-logging-cwconsole)
## Usar bibliotecas e ferramentas de registro em log
O [Powertools para AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/) é um kit de ferramentas para desenvolvedores para implementar as práticas recomendadas da tecnologia sem servidor e aumentar a velocidade do desenvolvedor. O [utilitário Logger](https://docs.powertools.aws.dev/lambda/typescript/latest/features/logger/) fornece um registrador otimizado para Lambda que inclui informações adicionais sobre o contexto da função em todas as suas funções com saída estruturada como JSON. Use esse utilitário para fazer o seguinte:
+ Capturar campos-chave do contexto do Lambda, inicialização a frio e estruturas registrando em log a saída como JSON
+ Registrar em log eventos de invocação do Lambda quando instruído (desativado por padrão)
+ Imprimir todos os logs somente para uma porcentagem das invocações por meio da amostragem de logs (desativado por padrão)
+ Anexar chaves adicionais ao log estruturado a qualquer momento
+ Use um formatador de log personalizado (Bring Your Own Formatter) para gerar logs em uma estrutura compatível com o RFC de logs da sua organização
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS SAM para registro em log estruturado
Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação Hello World TypeScript com os módulos integrados do [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) usando o AWS SAM. Esta aplicação implementa um backend de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda invoca, envia logs e métricas usando o formato de métricas incorporadas ao CloudWatch e envia rastreamentos ao AWS X-Ray. A função retorna uma mensagem `hello world`.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ Node.js 20 ou posterior
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI versão 1.75 ou posterior](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte [Atualizando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Implantar uma aplicação de exemplo do AWS SAM**
1. Inicialize a aplicação usando o modelo Hello World TypeScript.
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. Crie a aplicação.
```
cd sam-app && sam build
```
1. Implante o aplicativo.
```
sam deploy --guided
```
1. Siga as instruções na tela. Para aceitar as opções padrão fornecidas na experiência interativa, pressione `Enter`.
**nota**
Em **HelloWorldFunction pode não ter autorização definida, tudo bem?**, certifique-se de inserir `y`.
1. Obtenha o URL da aplicação implantada:
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. Invoque o endpoint da API:
```
curl
```
Se tiver êxito, você verá esta resposta:
```
{"message":"hello world"}
```
1. Para obter os logs da função, execute [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Para obter mais informações, consulte [Trabalhar com logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) no *Guia do desenvolvedor do AWS Serverless Application Model*.
```
sam logs --stack-name sam-app
```
O resultado de saída do log se parece com:
```
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.552000 START RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Version: $LATEST
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.594000 2025-08-31T09:33:10.557Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390556,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[{"Name":"ColdStart","Unit":"Count"}]}]},"service":"helloWorld","ColdStart":1}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.595000 2025-08-31T09:33:10.595Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"level":"INFO","message":"This is an INFO log - sending HTTP 200 - hello world response","service":"helloWorld","timestamp":"2025-08-31T09:33:10.594Z"}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.655000 2025-08-31T09:33:10.655Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390655,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[]}]},"service":"helloWorld"}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.754000 END RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.754000 REPORT RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Duration: 201.55 ms Billed Duration: 202 ms Memory Size: 128 MB Max Memory Used: 66 MB Init Duration: 252.42 ms
XRAY TraceId: 1-630f2ad5-1de22b6d29a658a466e7ecf5 SegmentId: 567c116658fbf11a Sampled: true
```
1. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
sam delete
```
### Gerenciar a retenção de logs
Os grupos de logs não são excluídos automaticamente excluídos quando você exclui uma função. Para evitar armazenar logs por tempo indeterminado, exclua o grupo de logs ou configure um período de retenção após o qual o CloudWatch excluirá os logs automaticamente. Para configurar a retenção de logs, adicione o seguinte ao seu modelo do AWS SAM:
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
# Omitting other properties
LogGroup:
Type: AWS::Logs::LogGroup
Properties:
LogGroupName: !Sub "/aws/lambda/${HelloWorldFunction}"
RetentionInDays: 7
```
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS CDK para registro em log estruturado
Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação Hello World TypeScript com os módulos integrados do [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) usando o AWS CDK. Esta aplicação implementa um backend de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda invoca, envia logs e métricas usando o formato de métricas incorporadas ao CloudWatch e envia rastreamentos ao AWS X-Ray. A função retorna uma mensagem `hello world`.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ Node.js 20 ou posterior
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versão 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM CLI versão 1.75 ou posterior](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte [Atualizando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Implantar uma aplicação de exemplo do AWS CDK**
1. Crie um diretório de projeto para sua aplicação.
```
mkdir hello-world
cd hello-world
```
1. Inicialize a aplicação.
```
cdk init app --language typescript
```
1. Adicione o pacote [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) como uma dependência de desenvolvimento.
```
npm install -D @types/aws-lambda
```
1. Instale o [Utilitário logger](https://docs.aws.amazon.com/powertools/typescript/latest/features/logger/) do Powertools.
```
npm install @aws-lambda-powertools/logger
```
1. Abra o diretório **lib**. Você deverá ver um arquivo chamado **hello-world-stack.ts**. Crie novos dois novos arquivos neste diretório: **hello-world.function.ts** e **hello-world.ts**.
1. Abra o **hello-world.function.ts** e adicione o código a seguir ao arquivo. Este é o código da função do Lambda.
```
import { APIGatewayEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
import { Logger } from '@aws-lambda-powertools/logger';
const logger = new Logger();
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
logger.info('This is an INFO log - sending HTTP 200 - hello world response');
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. Abra o **hello-world.ts** e adicione o código a seguir ao arquivo. Ele contém a [estrutura NodeJSFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), que cria a função do Lambda, configura variáveis de ambiente para o Powertools e define a retenção de logs para uma semana. Também inclui a [estrutura LambdaRestAPI](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), que cria a API REST.
```
import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
import { RetentionDays } from 'aws-cdk-lib/aws-logs';
import { CfnOutput } from 'aws-cdk-lib';
export class HelloWorld extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
const helloFunction = new NodejsFunction(this, 'function', {
environment: {
Powertools_SERVICE_NAME: 'helloWorld',
LOG_LEVEL: 'INFO',
},
logRetention: RetentionDays.ONE_WEEK,
});
const api = new LambdaRestApi(this, 'apigw', {
handler: helloFunction,
});
new CfnOutput(this, 'apiUrl', {
exportName: 'apiUrl',
value: api.url,
});
}
}
```
1. Abra o **hello-world-stack.ts**. Este é o código que define sua [pilha do AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Substitua o código pelo seguinte:
```
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';
export class HelloWorldStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new HelloWorld(this, 'hello-world');
}
}
```
1. Volte ao diretório do projeto.
```
cd hello-world
```
1. Implante o aplicativo.
```
cdk deploy
```
1. Obtenha o URL da aplicação implantada:
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. Invoque o endpoint da API:
```
curl
```
Se tiver êxito, você verá esta resposta:
```
{"message":"hello world"}
```
1. Para obter os logs da função, execute [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Para obter mais informações, consulte [Trabalhar com logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) no *Guia do desenvolvedor do AWS Serverless Application Model*.
```
sam logs --stack-name HelloWorldStack
```
O resultado de saída do log se parece com:
```
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.047000 START RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Version: $LATEST
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.050000 {
"level": "INFO",
"message": "This is an INFO log - sending HTTP 200 - hello world response",
"service": "helloWorld",
"timestamp": "2025-08-31T14:48:37.048Z",
"xray_trace_id": "1-630f74c4-2b080cf77680a04f2362bcf2"
}
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.082000 END RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.082000 REPORT RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Duration: 34.60 ms Billed Duration: 35 ms Memory Size: 128 MB Max Memory Used: 57 MB Init Duration: 173.48 ms
```
1. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
cdk destroy
```
## Visualizar logs no console do Lambda
É possível usar o console do Lambda para exibir a saída do log depois de invocar uma função do Lambda.
Se seu código puder ser testado no editor de **Código** incorporado, você encontrará logs nos **resultados de execução**. Ao usar o recurso de teste do console para invocar uma função, você encontrará **Saída de log** na seção **Detalhes**.
## Visualização de logs no console do CloudWatch
É possível usar o console do Amazon CloudWatch para exibir logs de todas as invocações da função do Lambda.
**Para visualizar logs no console do CloudWatch**
1. No console do Amazon CloudWatch, abra a [página Log groups](https://console.aws.amazon.com/cloudwatch/home?#logs:) (Grupos de log).
1. Escolha o grupo de logs de sua função (**/aws/lambda/*nome-de-sua-função***).
1. Escolha um stream de logs.
Cada fluxo de log corresponde a uma [instância da sua função](lambda-runtime-environment.md). Um fluxo de logs é exibido quando você atualiza sua função do Lambda e quando mais instâncias são criadas para lidar com invocações simultâneas. Para localizar logs de uma invocação específica, recomendamos intrumentar sua função com AWS X-Ray. O X-Ray registra detalhes sobre a solicitação e o stream de logs no rastreamento.
# Como rastrear o código TypeScript no AWS Lambda
O Lambda se integra ao AWS X-Ray para ajudar você a rastrear, depurar e otimizar aplicações do Lambda. É possível usar o X-Ray para rastrear uma solicitação enquanto ela atravessa recursos na aplicação, o que pode incluir funções Lambda e outros produtos da AWS.
Para enviar dados de rastreamento ao X-Ray, é possível usar uma das três bibliotecas SDK:
+ [AWS Distro for OpenTelemetry (ADOT)](https://aws.amazon.com/otel): uma distribuição segura, pronta para produção e com suporte na AWS do SDK OpenTelemetry (OTel).
+ [SdK do AWS X-Ray para Node.js](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html): um SDK para geração e envio de dados de rastreamento ao X-Ray.
+ [Powertools para AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/latest/): kit de ferramentas para desenvolvedores para implementar as práticas recomendadas da tecnologia sem servidor e aumentar a velocidade do desenvolvedor.
Cada um dos SDKs oferece maneiras de enviar dados de telemetria ao serviço do X-Ray. Em seguida, é possível usar o X-Ray para visualizar, filtrar e obter insights sobre as métricas de performance da aplicação para identificar problemas e oportunidades de otimização.
**Importante**
Os SDKs do X-Ray e do Powertools para AWS Lambda fazem parte de uma solução de instrumentação totalmente integrada oferecida pela AWS. As camadas do Lambda para ADOT fazem parte de um padrão em todo o setor para instrumentação de rastreamento que coleta mais dados em geral, mas pode não ser adequado para todos os casos de uso. É possível implementar o rastreamento de ponta a ponta no X-Ray usando ambas as soluções. Para saber mais sobre como escolher entre elas, consulte [Como escolher entre os SDKs do AWS Distro para OpenTelemetry e do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing).
**Topics**
+ [
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS SAM para rastreamento
](#typescript-tracing-sam)
+ [
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS CDK para rastreamento
](#typescript-tracing-cdk)
+ [
## Interpretar um rastreamento do X-Ray
](#typescript-tracing-interpretation)
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS SAM para rastreamento
Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação Hello World TypeScript com os módulos integrados do [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) usando o AWS SAM. Esta aplicação implementa um backend de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda invoca, envia logs e métricas usando o formato de métricas incorporadas ao CloudWatch e envia rastreamentos ao AWS X-Ray. A função retorna uma mensagem `hello world`.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ Node.js
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI versão 1.75 ou posterior](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte [Atualizando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Implantar uma aplicação de exemplo do AWS SAM**
1. Inicialize a aplicação usando o modelo Hello World TypeScript.
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x --no-tracing
```
1. Crie a aplicação.
```
cd sam-app && sam build
```
1. Implante o aplicativo.
```
sam deploy --guided
```
1. Siga as instruções na tela. Para aceitar as opções padrão fornecidas na experiência interativa, pressione `Enter`.
**nota**
Em **HelloWorldFunction pode não ter autorização definida, tudo bem?**, certifique-se de inserir `y`.
1. Obtenha o URL da aplicação implantada:
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. Invoque o endpoint da API:
```
curl
```
Se tiver êxito, você verá esta resposta:
```
{"message":"hello world"}
```
1. Para obter os rastreamentos da função, execute [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).
```
sam traces
```
A saída de rastreamento se parece com:
```
XRay Event [revision 1] at (2023-01-31T11:29:40.527000) with id (1-11a2222-111a222222cb33de3b95daf9) and duration (0.483s)
- 0.425s - sam-app/Prod [HTTP: 200]
- 0.422s - Lambda [HTTP: 200]
- 0.406s - sam-app-HelloWorldFunction-Xyzv11a1bcde [HTTP: 200]
- 0.172s - sam-app-HelloWorldFunction-Xyzv11a1bcde
- 0.179s - Initialization
- 0.112s - Invocation
- 0.052s - ## app.lambdaHandler
- 0.001s - ### MySubSegment
- 0.059s - Overhead
```
1. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
sam delete
```
O X-Ray não rastreia todas as solicitações para sua aplicação. O X-Ray aplica um algoritmo de amostragem para garantir que o rastreamento seja eficiente, enquanto ainda fornece uma amostra representativa das solicitações. A taxa de amostragem é uma solicitação por segundo e 5% de solicitações adicionais. Você não pode configurar a taxa de amostragem do X-Ray para suas funções.
## Uso do Powertools para AWS Lambda (TypeScript) e do AWS CDK para rastreamento
Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação Hello World TypeScript com os módulos integrados do [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) usando o AWS CDK. Esta aplicação implementa um backend de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda invoca, envia logs e métricas usando o formato de métricas incorporadas ao CloudWatch e envia rastreamentos ao AWS X-Ray. A função retorna uma mensagem `hello world`.
**Pré-requisitos**
Para executar as etapas desta seção, você deve ter o seguinte:
+ Node.js
+ [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versão 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM CLI versão 1.75 ou posterior](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Se você tiver uma versão mais antiga da CLI do AWS SAM, consulte [Atualizando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Implantar uma aplicação de exemplo do AWS Cloud Development Kit (AWS CDK)**
1. Crie um diretório de projeto para sua aplicação.
```
mkdir hello-world
cd hello-world
```
1. Inicialize a aplicação.
```
cdk init app --language typescript
```
1. Adicione o pacote [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) como uma dependência de desenvolvimento.
```
npm install -D @types/aws-lambda
```
1. Instale o [Utilitário Tracer](https://docs.aws.amazon.com/powertools/typescript/latest/features/tracer/) do Powertools.
```
npm install @aws-lambda-powertools/tracer
```
1. Abra o diretório **lib**. Você deverá ver um arquivo chamado **hello-world-stack.ts**. Crie novos dois novos arquivos neste diretório: **hello-world.function.ts** e **hello-world.ts**.
1. Abra o **hello-world.function.ts** e adicione o código a seguir ao arquivo. Este é o código da função Lambda.
```
import { APIGatewayEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
import { Tracer } from '@aws-lambda-powertools/tracer';
const tracer = new Tracer();
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
// Get facade segment created by Lambda
const segment = tracer.getSegment();
// Create subsegment for the function and set it as active
const handlerSegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
tracer.setSegment(handlerSegment);
// Annotate the subsegment with the cold start and serviceName
tracer.annotateColdStart();
tracer.addServiceNameAnnotation();
// Add annotation for the awsRequestId
tracer.putAnnotation('awsRequestId', context.awsRequestId);
// Create another subsegment and set it as active
const subsegment = handlerSegment.addNewSubsegment('### MySubSegment');
tracer.setSegment(subsegment);
let response: APIGatewayProxyResult = {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
// Close subsegments (the Lambda one is closed automatically)
subsegment.close(); // (### MySubSegment)
handlerSegment.close(); // (## index.handler)
// Set the facade segment as active again (the one created by Lambda)
tracer.setSegment(segment);
return response;
};
```
1. Abra o **hello-world.ts** e adicione o código a seguir ao arquivo. Ele contém a [estrutura NodeJSFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), que cria a função do Lambda, configura variáveis de ambiente para o Powertools e define a retenção de logs para uma semana. Também inclui a [estrutura LambdaRestAPI](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), que cria a API REST.
```
import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
import { CfnOutput } from 'aws-cdk-lib';
import { Tracing } from 'aws-cdk-lib/aws-lambda';
export class HelloWorld extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
const helloFunction = new NodejsFunction(this, 'function', {
environment: {
POWERTOOLS_SERVICE_NAME: 'helloWorld',
},
tracing: Tracing.ACTIVE,
});
const api = new LambdaRestApi(this, 'apigw', {
handler: helloFunction,
});
new CfnOutput(this, 'apiUrl', {
exportName: 'apiUrl',
value: api.url,
});
}
}
```
1. Abra o **hello-world-stack.ts**. Este é o código que define sua [pilha do AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Substitua o código pelo seguinte:
```
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';
export class HelloWorldStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new HelloWorld(this, 'hello-world');
}
}
```
1. Implante o aplicativo.
```
cd ..
cdk deploy
```
1. Obtenha o URL da aplicação implantada:
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. Invoque o endpoint da API:
```
curl
```
Se tiver êxito, você verá esta resposta:
```
{"message":"hello world"}
```
1. Para obter os rastreamentos da função, execute [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).
```
sam traces
```
A saída de rastreamento se parece com:
```
XRay Event [revision 1] at (2023-01-31T11:50:06.997000) with id (1-11a2222-111a222222cb33de3b95daf9) and duration (0.449s)
- 0.350s - HelloWorldStack-helloworldfunction111A2BCD-Xyzv11a1bcde [HTTP: 200]
- 0.157s - HelloWorldStack-helloworldfunction111A2BCD-Xyzv11a1bcde
- 0.169s - Initialization
- 0.058s - Invocation
- 0.055s - ## index.handler
- 0.000s - ### MySubSegment
- 0.099s - Overhead
```
1. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.
```
cdk destroy
```
## Interpretar um rastreamento do X-Ray
Após configurar o rastreamento ativo, você pode observar solicitações específicas por meio da aplicação. O [mapa de rastreamento do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-servicemap.html) fornece informações sobre a aplicação e todos os seus componentes. O seguinte exemplo mostra um rastreamento do exemplo de aplicação:
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sample-typescript-servicemap.png)