# Creación de funciones de Lambda con TypeScript
Se puede utilizar el tiempo de ejecución de Node.js para ejecutar código TypeScript en AWS Lambda. Dado que Node.js no ejecuta código de TypeScript de manera nativa, antes se debe transpilar el código de TypeScript a JavaScript. A continuación, utilice los archivos JavaScript para implementar el código de la función en Lambda. El código se ejecuta en un entorno que incluye AWS SDK para JavaScript, con credenciales de un rol de AWS Identity and Access Management (IAM) que usted administra. Para obtener más información sobre las versiones del SDK incluidas en los tiempos de ejecución de Node.js, consulte [Versiones del SDK incluidas en el tiempo de ejecución](lambda-nodejs.md#nodejs-sdk-included).
Lambda admite los siguientes tiempos de ejecución de Node.js.
| Nombre | Identificador | Sistema operativo | Fecha de baja | Bloqueo de la función Crear | Bloqueo de la función Actualizar |
| --- | --- | --- | --- | --- | --- |
| Node.js 24 | `nodejs24.x` | Amazon Linux 2023 | 30 de abril de 2028 | 1 de junio de 2028 | 1 de julio de 2028 |
| Node.js 22 | `nodejs22.x` | Amazon Linux 2023 | 30 de abril de 2027 | 1 de junio de 2027 | 1 de julio de 2027 |
| Node.js 20 | `nodejs20.x` | Amazon Linux 2023 | 30 de abril de 2026 | 31 de agosto de 2026 | 30 de septiembre de 2026 |
**Topics**
+ [
## Configuración de un entorno de desarrollo de TypeScript
](#typescript-dev)
+ [
## Definiciones de tipos de Lambda
](#typescript-type-definitions)
+ [
# Definir el controlador de funciones de Lambda en Typescript
](typescript-handler.md)
+ [
# Implementar código de TypeScript transpilado en Lambda con archivos .zip
](typescript-package.md)
+ [
# Implementar código de TypeScript transpilado en Lambda con imágenes de contenedor
](typescript-image.md)
+ [
# Uso del objeto de contexto Lambda para recuperar la información de la función de TypeScript
](typescript-context.md)
+ [
# Registro y supervisión de las funciones de Lambda de TypeScript
](typescript-logging.md)
+ [
# Seguimiento del código de TypeScript en AWS Lambda
](typescript-tracing.md)
## Configuración de un entorno de desarrollo de TypeScript
Use un entorno de desarrollo integrado (IDE) local o un editor de texto para escribir el código de la función de TypeScript. No se puede crear código de TypeScript en la consola de Lambda.
Puede usar [esbuild](https://esbuild.github.io/) o el compilador de TypeScript de Microsoft (`tsc`) para transpilar su código TypeScript a JavaScript. Tanto [AWS Serverless Application Model (AWS SAM)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html) como [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) usan esbuild.
Al utilizar esbuild, tenga en cuenta lo siguiente:
+ Existen varias [advertencias en relación con TypeScript](https://esbuild.github.io/content-types/#typescript-caveats).
+ La configuración de transpilación de TypeScript se debe establecer de modo que coincida con el tiempo de ejecución de Node.js que se piense utilizar. Para obtener más información, consulte [Target](https://esbuild.github.io/api/#target) (Destino) en la documentación de esbuild. Para ver un ejemplo de archivo **tsconfig.json** que muestra cómo orientarse a una versión específica de Node.js compatible con Lambda, consulte el [repositorio de GitHub de TypeScript](https://github.com/tsconfig/bases/blob/main/bases/node14.json).
+ esbuild no realiza comprobaciones de tipos. Para comprobar los tipos, utilice el compilador `tsc`. Ejecute `tsc -noEmit` o agregue un parámetro `"noEmit"` al archivo **tsconfig.json**, como se muestra en el siguiente ejemplo. Eso configura `tsc` para que no emita archivos JavaScript. Después de comprobar los tipos, utilice esbuild para convertir los archivos de TypeScript a 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"]
}
```
## Definiciones de tipos de Lambda
El paquete [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) proporciona definiciones de tipos para funciones de Lambda. Instale este paquete cuando su función use cualquiera de los siguientes elementos:
+ Orígenes de eventos de AWS habituales, como:
+ `APIGatewayProxyEvent`: para [integraciones de proxy de Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html)
+ `SNSEvent`: para [notificaciones de Amazon Simple Notification Service](with-sns.md)
+ `SQSEvent`: para [mensajes de Amazon Simple Queue Service](with-sqs.md)
+ `S3Event`: para [eventos desencadenadores de S3](with-s3.md)
+ `DynamoDBStreamEvent`: para [Amazon DynamoDB Streams](with-ddb.md)
+ El objeto de [contexto](typescript-context.md) de Lambda
+ El patrón del controlador de [devolución de llamada](typescript-handler.md#typescript-handler-callback)
Para agregar las definiciones de tipos de Lambda a su función, instale `@types/aws-lambda` como una dependencia de desarrollo:
```
npm install -D @types/aws-lambda
```
A continuación, importe los tipos desde `aws-lambda`:
```
import { Context, S3Event, APIGatewayProxyEvent } from 'aws-lambda';
export const handler = async (event: S3Event, context: Context) => {
// Function code
};
```
La instrucción `import ... from 'aws-lambda'` importa las definiciones de tipos. No importa el paquete npm de `aws-lambda`, que es una herramienta de terceros no relacionada. Para obtener más información, consulte [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) en el repositorio de GitHub DefinitelyTyped.
**nota**
No necesita [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) cuando usa sus propias definiciones de tipos personalizadas. Para ver un ejemplo de función que define su propio tipo para un objeto de evento, consulte [Ejemplo de código de una función de Lambda en TypeScript](typescript-handler.md#typescript-example-code).
# Definir el controlador de funciones de Lambda en Typescript
El *controlador* de la función de Lambda es el método del código de la función que procesa eventos. Cuando se invoca una función, Lambda ejecuta el método del controlador. La función se ejecuta hasta que el controlador devuelve una respuesta, se cierra o se agota el tiempo de espera.
En esta página se describe cómo se trabaja con los controladores de funciones de Lambda en TypeScript, incluidas las opciones para la configuración del proyecto, las convenciones de nomenclatura y las prácticas recomendadas. En esta página también se incluye el ejemplo de una función de Lambda de TypeScript que recibe información sobre un pedido, genera un recibo en un archivo de texto y coloca este archivo en un bucket de Amazon Simple Storage Service (Amazon S3). Para obtener información sobre cómo implementar la función después de escribirla, consulte [Implementar código de TypeScript transpilado en Lambda con archivos .zip](typescript-package.md) o [Implementar código de TypeScript transpilado en Lambda con imágenes de contenedor](typescript-image.md).
**Topics**
+ [
## Configuración del proyecto de TypeScript
](#typescript-handler-setup)
+ [
## Ejemplo de código de una función de Lambda en TypeScript
](#typescript-example-code)
+ [
## Módulos de CommonJS y ES
](#typescript-commonjs-es-modules)
+ [
## Inicialización de Node.js
](#typescript-initialization)
+ [
## Convenciones de nomenclatura de controladores
](#typescript-handler-naming)
+ [
## Definición del objeto de evento de entrada y acceso a él
](#typescript-example-input)
+ [
## Patrones de controlador válidos para funciones de TypeScript
](#typescript-handler-signatures)
+ [
## Uso de la versión 3 del SDK para JavaScript en el controlador
](#typescript-example-sdk-usage)
+ [
## Acceso a las variables de entorno
](#typescript-example-envvars)
+ [
## Uso del estado global
](#typescript-handler-state)
+ [
## Prácticas recomendadas de codificación para las funciones de Lambda en Typescript
](#typescript-best-practices)
## Configuración del proyecto de TypeScript
Use un entorno de desarrollo integrado (IDE) local o un editor de texto para escribir el código de la función de TypeScript. No se puede crear código de TypeScript en la consola de Lambda.
Existen varias formas de inicializar un proyecto de Lambda en TypeScript. Por ejemplo, puede crear un proyecto mediante `npm`, crear una [aplicación de AWS SAM](typescript-package.md#aws-sam-ts) o crear una [aplicación de AWS CDK](typescript-package.md#aws-cdk-ts). Para crear un proyecto mediante `npm`:
```
npm init
```
El código de su función reside en un archivo `.ts`, que se transpila a un archivo de JavaScript en el momento de la compilación. Puede usar [esbuild](https://esbuild.github.io/) o el compilador de TypeScript de Microsoft (`tsc`) para transpilar su código TypeScript a JavaScript. Para usar esbuild, agréguelo como una dependencia de desarrollo:
```
npm install -D esbuild
```
Un proyecto habitual de la función de Lambda en TypeScript sigue esta estructura general:
```
/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
```
## Ejemplo de código de una función de Lambda en TypeScript
El siguiente ejemplo de código de función de Lambda recibe información sobre un pedido, genera un recibo en un archivo de texto y coloca este archivo en un bucket de Amazon S3. Este ejemplo define un tipo de evento personalizado (`OrderEvent`). Para aprender a importar definiciones de tipos para orígenes de eventos de AWS, consulte [Definiciones de tipos de Lambda](lambda-typescript.md#typescript-type-definitions).
**nota**
En este ejemplo se usa un controlador de módulos de ES. Lambda admite tanto controladores de módulos de ES como de CommonJS. Para obtener más información, consulte [Módulos de CommonJS y ES](nodejs-handler.md#nodejs-commonjs-es-modules).
**Example Función de Lambda en 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 archivo `index.ts` contiene las siguientes secciones de código:
+ Bloque `import`: use este bloque para incluir las bibliotecas que requiere la función de Lambda, como [clientes de AWS SDK](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/the-request-object.html).
+ Declaración `const s3Client`: esto inicializa un [cliente de Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/) fuera de la función del controlador. Esto hace que Lambda ejecute este código durante la [fase de inicialización](lambda-runtime-environment.md#runtimes-lifecycle-ib) y el cliente se conserva para su [reutilización en múltiples invocaciones](lambda-runtime-environment.md#execution-environment-reuse).
+ `type OrderEvent`: define la estructura del evento de entrada esperado.
+ `export const handler`: esta es la función principal del controlador que invoca Lambda. Al implementar su función, especifique `index.handler` para la propiedad [Handler](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler). El valor de la propiedad `Handler` es el nombre del archivo y el nombre del método del controlador exportado, separados por un punto.
+ Función `uploadReceiptToS3`: se trata de una función auxiliar a la que hace referencia la función del controlador principal.
Para que esta función se ejecute correctamente, su [rol de ejecución](lambda-intro-execution-role.md) debe permitir la acción `s3:PutObject`. Además, asegúrese de definir la variable de entorno `RECEIPT_BUCKET`. Tras una invocación correcta, el bucket de Amazon S3 debe contener un archivo de recibo.
## Módulos de CommonJS y ES
Node.js admite dos sistemas de módulos: módulos de CommonJS y ECMAScript (módulos de ES). Lambda recomienda usar módulos de ES, ya que admiten la espera de nivel superior, lo que permite completar tareas asíncronas durante la [inicialización del entorno de ejecución](#typescript-initialization).
Node.js trata los archivos con una extensión de nombre de archivo `.cjs` como módulos de CommonJS, mientras que una extensión `.mjs` denota módulos de ES. De forma predeterminada, Node.js trata los archivos con la extensión de nombre de archivo `.js` como módulos de CommonJS. Puede configurar Node.js para tratar los archivos `.js` como módulos de ES; para ello, especifique el `type` como `module` en el archivo `package.json` de la función. Puede configurar Node.js en Lambda para que detecte automáticamente si un archivo `.js` debe tratarse como un módulo de CommonJS o de ES; para ello, añada la marca `—experimental-detect-module` a la variable de entorno `NODE_OPTIONS`. Para obtener más información, consulte [Características experimentales de Node.js](lambda-nodejs.md#nodejs-experimental-features).
Los siguientes ejemplos muestran los controladores de funciones escritos con los módulos de ES y CommonJS. Todos los ejemplos restantes de esta página utilizan módulos de ES.
## Inicialización de Node.js
Node.js utiliza un modelo de E/S sin bloqueo que admite operaciones asíncronas eficientes mediante un bucle de eventos. Por ejemplo, si Node.js realiza una llamada de red, la función continúa procesando otras operaciones sin bloquear la respuesta de la red. Cuando se recibe la respuesta de la red, se coloca en la cola de devolución de llamada. Las tareas de la cola se procesan cuando se completa la tarea actual.
Lambda recomienda usar una espera de nivel superior para que las tareas asíncronas iniciadas durante la inicialización del entorno de ejecución se completen durante la inicialización. Las tareas asíncronas que no se completan durante la inicialización normalmente se ejecutan durante la primera invocación de la función. Esto puede provocar un comportamiento inesperado o errores. Por ejemplo, la inicialización de la función puede realizar una llamada de red para recuperar un parámetro del almacén de parámetros de AWS. Si esta tarea no se completa durante la inicialización, el valor puede ser nulo durante una invocación. También puede haber un retraso entre la inicialización y la invocación, que puede desencadenar errores en operaciones urgentes. En concreto, las llamadas de servicio de AWS pueden depender de firmas de solicitud urgentes, lo que provoca errores en las llamadas de servicio si la llamada no se completa durante la fase de inicialización. Completar las tareas durante la inicialización normalmente mejora el rendimiento del arranque en frío, y se invoca primero el rendimiento cuando se utiliza la concurrencia aprovisionada. Para obtener más información, consulte la publicación del blog [Using Node.js ES modules and top-level await in AWS Lambda](https://aws.amazon.com/blogs/compute/using-node-js-es-modules-and-top-level-await-in-aws-lambda).
## Convenciones de nomenclatura de controladores
Al configurar una función, el valor de la configuración [Handler](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler) es el nombre del archivo y el nombre del método del controlador exportado, separados por un punto. El valor predeterminado de las funciones creadas en la consola y de los ejemplos de esta guía es `index.handler`. Esto indica el método `handler` que se exporta desde el archivo `index.js` o `index.mjs`.
Si crea una función en la consola con un nombre de archivo o un nombre de controlador de funciones diferente, debe editar el nombre del controlador predeterminado.
**Para cambiar el nombre de controlador de la función (consola)**
1. Abra la página [Funciones](https://console.aws.amazon.com/lambda/home#/functions) de la consola de Lambda y elija su función.
1. Elija la pestaña **Código**.
1. Desplácese hacia abajo hasta el panel **Configuración del tiempo de ejecución** y elija **Editar**.
1. En **Controlador**, ingrese el nuevo nombre del controlador de funciones.
1. Seleccione **Save**.
## Definición del objeto de evento de entrada y acceso a él
El formato de entrada más común y estándar de las funciones de Lambda es JSON. En este ejemplo, la función espera una entrada similar a la siguiente:
```
{
"order_id": "12345",
"amount": 199.99,
"item": "Wireless Headphones"
}
```
Al trabajar con funciones de Lambda en TypeScript, puede definir la forma del evento de entrada mediante un tipo o una interfaz. En este ejemplo, se define la estructura del evento mediante un tipo:
```
type OrderEvent = {
order_id: string;
amount: number;
item: string;
}
```
Después de definir el tipo o la interfaz, úsela en la firma del controlador para garantizar la seguridad de los tipos:
```
export const handler = async (event: OrderEvent): Promise => {
```
Durante la compilación, TypeScript valida que el objeto de evento contenga los campos obligatorios con los tipos correspondientes. Por ejemplo, el compilador de TypeScript informa de un error si intenta usar `event.order_id` como número o `event.amount` como cadena.
## Patrones de controlador válidos para funciones de TypeScript
Le recomendamos que use [async/await](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-async-await.html) para declarar el controlador de funciones en lugar de usar [devoluciones de llamadas](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-a-callback-function.html). Async/await es una forma concisa y legible de escribir código asíncrono, sin necesidad de devoluciones de llamadas anidadas ni promesas encadenadas. Con async/await, puedes escribir código que se lea como código sincrónico, sin dejar de ser asíncrono y sin bloqueo.
Los ejemplos que aparecen en esta sección usan el tipo `S3Event`. Sin embargo, puede usar cualquier otro tipo de evento de AWS en el paquete [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) o definir su propio tipo de evento. Para usar tipos desde @types/aws-lambda:
1. Agregue el paquete @types/aws-lambda como dependencia de desarrollo:
```
npm install -D @types/aws-lambda
```
1. Importe los tipos que necesite, como `Context`, `S3Event` o `Callback`.
### controladores de funciones asíncronos (recomendados)
La palabra clave `async` marca una función como asíncrona y la palabra clave `await` detiene la ejecución de la función hasta que se resuelva una `Promise`. El controlador acepta los argumentos siguientes:
+ `event`: contiene los datos de entrada que se pasan a la función.
+ `context`: contiene información sobre la función de invocación y el entorno de ejecución. Para obtener más información, consulte [Uso del objeto de contexto Lambda para recuperar la información de la función de TypeScript](typescript-context.md).
A continuación se muestran las firmas válidas para el patrón async/await:
```
export const handler = async (event: S3Event): Promise => { };
```
```
export const handler = async (event: S3Event, context: Context): Promise => { };
```
**nota**
Cuando procese matrices de elementos de forma asíncrona, asegúrese de usar await con `Promise.all` para garantizar que se completen todas las operaciones. Métodos como `forEach` no esperan a que se completen las devoluciones de llamada asíncronas. Para obtener más información, consulte [Array.prototype.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) en la documentación de Mozilla.
### Controladores de funciones sincrónicos
Si su función no realiza ninguna tarea asíncrona, puede usar un controlador de funciones sincrónicas, con una de las siguientes firmas de función:
```
export const handler = (event: S3Event): void => { };
```
```
export const handler = (event: S3Event, context: Context): void => { };
```
### Controladores de funciones del flujo de respuesta
Lambda admite el flujo de respuesta con Node.js. Los controladores de funciones del flujo de respuesta utilizan el decorador awslambda.streamifyResponse() y toman 3 parámetros: event, responseStream y context. La siguiente es la firma de la función:
```
export const handler = awslambda.streamifyResponse(async (event: APIGatewayProxyEvent, responseStream: NodeJS.WritableStream, context: Context) => { });
```
Para obtener más información, consulte Flujo de respuesta para funciones de Lambda.
### Controladores de funciones basados en la devolución de llamada
**nota**
Los controladores de funciones basados en la devolución de llamada solo se admiten hasta Node.js 22. A partir de Node.js 24, las tareas asíncronas deben implementarse mediante controladores de funciones asíncronos.
Los controladores de funciones basados en la devolución de llamada pueden usar los argumentos de evento, contexto y devolución de llamada. El argumento de devolución de llamada espera un `Error` y una respuesta, que debe poder serializarse en JSON.
A continuación se indica la firma válida para el patrón del controlador de devolución de llamada:
```
export const handler = (event: S3Event, context: Context, callback: Callback): void => { };
```
La función continúa ejecutándose hasta que el [bucle de eventos](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/) se vacía o se agota el tiempo de espera de la función. La respuesta no se envía al invoker hasta que todas las tareas de bucle de eventos hayan terminado. Si el tiempo de espera de la función se agota, se devolverá un error en su lugar. Puede configurar el tiempo de ejecución para enviar la respuesta inmediatamente estableciendo [context.callbackWaitsForEmptyEventLoop](typescript-context.md) en false.
**Example Función de TypeScript con devolución de llamada**
En el siguiente ejemplo se usa `APIGatewayProxyCallback`, que es un tipo de devolución de llamada especializado específico para las integraciones de API Gateway. La mayoría de los orígenes de eventos de AWS usan el tipo genérico `Callback` que se muestra en las firmas anteriores.
```
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',
}),
});
};
```
## Uso de la versión 3 del SDK para JavaScript en el controlador
A menudo, utilizará las funciones de Lambda para interactuar con otros recursos de AWS o actualizarlos. La forma más sencilla de interactuar con estos recursos es utilizar AWS SDK para JavaScript. Todos los tiempos de ejecución de Node.js para Lambda admitidos incluyen la [versión 3 del SDK para JavaScript](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/). Sin embargo, se le recomienda firmemente que incluya los clientes de AWS SDK que sean necesarios en el paquete de implementación. Esto maximiza la [compatibilidad con versiones anteriores](runtimes-update.md#runtime-update-compatibility) en cualquiera de las futuras actualizaciones del tiempo de ejecución de Lambda.
Para agregar dependencias del SDK a la función, utilice el comando `npm install` para los clientes del SDK específicos que necesite. En el código de ejemplo, se usa el [cliente de Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/). Agregue esta dependencia mediante la ejecución del siguiente comando en el directorio que contiene el archivo `package.json`:
```
npm install @aws-sdk/client-s3
```
En el código de la función, importe el cliente y los comandos que sean necesarios, tal y como se demuestra en la función de ejemplo:
```
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
```
A continuación, inicialice un [cliente de Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/):
```
const s3Client = new S3Client();
```
En este ejemplo, inicializamos el cliente de Amazon S3 fuera de la función del controlador principal para evitar tener que inicializarlo cada vez que invocamos nuestra función. Después de inicializar el cliente del SDK, podrá usarlo para hacer llamadas a la API para ese servicio de AWS. El código de ejemplo llama a la API [PutObject](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/PutObjectCommand/) de Amazon S3 de la siguiente manera:
```
const command = new PutObjectCommand({
Bucket: bucketName,
Key: key,
Body: receiptContent
});
```
## Acceso a las variables de entorno
En el código del controlador, puede hacer referencia a cualquier [variable de entorno](configuration-envvars.md) mediante `process.env`. En este ejemplo, se hace referencia a la variable de entorno `RECEIPT_BUCKET` definida mediante las siguientes líneas de código:
```
// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
throw new Error('RECEIPT_BUCKET environment variable is not set');
}
```
## Uso del estado global
Lambda ejecuta su código estático durante la [fase de inicialización](lambda-runtime-environment.md#runtimes-lifecycle-ib) antes de invocar la función por primera vez. Los recursos que se crean durante la inicialización permanecen en la memoria entre las invocaciones, por lo que evita tener que crearlos cada vez que invoca la función.
En el código de ejemplo, el código de inicialización del cliente de S3 está fuera del controlador. El tiempo de ejecución inicializa el cliente antes de que la función gestione su primer evento; por su parte, el cliente permanece disponible para su reutilización en todas las invocaciones.
## Prácticas recomendadas de codificación para las funciones de Lambda en Typescript
Siga estas directrices para desarrollar funciones de Lambda:
+ **Separe el controlador de Lambda de la lógica del núcleo.** Esto le permite probar las distintas unidades de la función con mayor facilidad.
+ **Controle las dependencias del paquete de implementación de la función. ** El entorno de ejecución AWS Lambda contiene varias bibliotecas. Para los tiempos de ejecución de Node.js y Python, estos incluyen los AWS SDK. Para disponer del conjunto más reciente de características y actualizaciones de seguridad, Lambda actualizará periódicamente estas bibliotecas. Estas actualizaciones pueden introducir cambios sutiles en el comportamiento de la función de Lambda. Para disponer de un control total de las dependencias que utiliza la función, empaquete todas las dependencias con el paquete de implementación.
+ **Minimice la complejidad de las dependencias.** Son preferibles los marcos de trabajo más sencillos, ya que se cargan rápidamente al arrancar el [entorno de ejecución](lambda-runtime-environment.md).
+ **Minimice el tamaño del paquete de implementación de acuerdo con las necesidades de su tiempo de ejecución. ** Esto reducirá la cantidad de tiempo que tarda el paquete de implementación en descargarse y desempaquetarse antes de la invocación.
**Reutilice el entorno de ejecución para mejorar el rendimiento de la función.** Inicialice los clientes de SDK y las conexiones de base de datos fuera del controlador de funciones y almacene localmente en caché los recursos estáticos en el directorio `/tmp`. Las invocaciones posteriores procesadas por la misma instancia de su función pueden reutilizar estos recursos. Esto ahorra costes al reducir el tiempo de ejecución de la función.
Para evitar posibles filtraciones de datos entre las invocaciones, no utilice el entorno de ejecución para almacenar datos de usuario, eventos u otra información con implicaciones de seguridad. Si su función se basa en un estado mutable que no se puede almacenar en la memoria dentro del controlador, considere crear una función independiente o versiones independientes de una función para cada usuario.
**Utilice una directiva keep-alive para mantener conexiones persistentes.** Lambda purga las conexiones inactivas a lo largo del tiempo. Si intenta reutilizar una conexión inactiva al invocar una función, se producirá un error de conexión. Para mantener la conexión persistente, use la directiva keep-alive asociada al tiempo de ejecución. Para ver un ejemplo, consulte [Reutilización de conexiones con Keep-Alive en Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-reusing-connections.html).
**Utilice [variables de entorno](configuration-envvars.md) para pasar parámetros operativos a su función.** Por ejemplo, si está escribiendo en un bucket de Amazon S3, en lugar de codificar de forma rígida el nombre del bucket, configúrelo como una variable de entorno.
**Evite utilizar invocaciones recursivas** en la función de Lambda, en las que la función se invoca a sí misma o inicia un proceso que puede volver a invocarla. Esto podría producir un volumen no intencionado de invocaciones de la función y costos elevados. Si observa un volumen imprevisto de invocaciones, establezca la simultaneidad reservada de funciones en `0` inmediatamente para limitar todas las invocaciones de la función mientras actualiza el código.
**No utilice API no documentadas y no públicas** en el código de la función de Lambda. Para tiempos de ejecución administrados de AWS Lambda, Lambda aplica periódicamente actualizaciones funcionales y de seguridad a las API internas de Lambda. Estas actualizaciones de las API internas pueden ser incompatibles con versiones anteriores, lo que conlleva consecuencias no deseadas, como errores de invocación si su función depende de estas API no públicas. Consulte la [referencia de la API](https://docs.aws.amazon.com/lambda/latest/api/welcome.html) para obtener una lista de las API disponibles públicamente.
**Escriba el código idempotente.** Escribir el código idempotente para las funciones garantiza que los eventos duplicados se gestionen de la misma manera. El código debe validar y gestionar correctamente los eventos duplicados. Para obtener más información, consulte [¿Cómo puedo hacer que mi función de Lambda sea idempotente?](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-function-idempotent/).
# Implementar código de TypeScript transpilado en Lambda con archivos .zip
Para poder implementar código de TypeScript enAWS Lambda, tiene que transpilarlo a JavaScript. En esta página se explican tres formas de crear e implementar código de TypeScript en Lambda con archivos .zip:
+ [Uso de AWS Serverless Application Model (AWS SAM)](#aws-sam-ts)
+ [Uso de AWS Cloud Development Kit (AWS CDK)](#aws-cdk-ts)
+ [Uso de AWS Command Line Interface (AWS CLI) y esbuild](#aws-cli-ts)
AWS SAM y AWS CDK simplifican la creación e implementación de funciones de TypeScript. La [especificación de plantillas de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html) proporciona una sintaxis sencilla y limpia para describir las funciones, las API, los permisos, las configuraciones y los eventos de Lambda que constituyen la aplicación sin servidor. [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/home.html) permite crear aplicaciones fiables, escalables y rentables en la nube con la considerable potencia expresiva de un lenguaje de programación. AWS CDK se dirige a usuarios de AWS con una experiencia entre media y alta. Tanto AWS CDK como AWS SAM utilizan esbuild para transpilar código de TypeScript a JavaScript.
## Uso de AWS SAM para implementar código de TypeScript en Lambda
Siga los pasos que figuran a continuación para descargar, compilar e implementar una aplicación de ejemplo de TypeScript de tipo “hola mundo” mediante AWS SAM. Esta aplicación implementa un backend de API básico. Consta de un punto de conexión de Amazon API Gateway y una función de Lambda. Cuando se envía una solicitud GET al punto de conexión de API Gateway, se invoca la función de Lambda. La función devuelve el mensaje `hello world`.
**nota**
AWS SAM utiliza esbuild para crear funciones de Lambda de Node.js a partir de código de TypeScript. La compatibilidad con esbuild se encuentra actualmente en versión preliminar pública. Mientras se encuentre en versión preliminar pública, el soporte de esbuild puede verse sometido a cambios incompatibles con versiones anteriores.
**Requisitos previos**
Para completar los pasos de esta sección, debe disponer de lo siguiente:
+ [AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [Versión 1.75 o posterior de la CLI de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+ Node.js
**Implementar un aplicación de ejemplo de AWS SAM**
1. Inicialice la aplicación utilizando la plantilla de TypeScript de tipo “hola mundo”.
```
sam init --app-template hello-world-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. (Opcional) La aplicación de ejemplo incluye configuraciones para herramientas de uso habitual, tales como [ESLint](https://eslint.org/) para linting de código y [Jest](https://jestjs.io/) para pruebas unitarias. Para ejecutar comandos de lint y pruebas:
```
cd sam-app/hello-world
npm install
npm run lint
npm run test
```
1. Compile la aplicación.
```
cd sam-app
sam build
```
1. Implemente la aplicación.
```
sam deploy --guided
```
1. Siga las indicaciones que aparecen en pantalla. Para aceptar las opciones predeterminadas proporcionadas en la experiencia interactiva, responda con `Enter`.
1. El resultado muestra el punto de conexión de la API REST. Abra el punto de conexión en un navegador para probar la función. Debería ver esta respuesta:
```
{"message":"hello world"}
```
1. Se trata de un punto de conexión de API pública al que se puede acceder a través de Internet. Se recomienda eliminar el punto de conexión después de las pruebas.
```
sam delete
```
## Uso de AWS CDK para implementar código de TypeScript en Lambda
Siga los pasos que figuran a continuación para crear e implementar una aplicación de ejemplo de TypeScript mediante AWS CDK. Esta aplicación implementa un backend de API básico. Consiste en un punto de conexión de API Gateway y una función de Lambda. Cuando se envía una solicitud GET al punto de conexión de API Gateway, se invoca la función de Lambda. La función devuelve el mensaje `hello world`.
**Requisitos previos**
Para completar los pasos de esta sección, debe disponer de lo siguiente:
+ [AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versión 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ Node.js
+ Bien sea [Docker](https://www.docker.com/get-started/) o [esbuild](https://esbuild.github.io/)
**Implementar un aplicación de ejemplo de AWS CDK**
1. Cree un directorio de proyecto para la nueva aplicación.
```
mkdir hello-world
cd hello-world
```
1. Inicialice la aplicación.
```
cdk init app --language typescript
```
1. Agregue el paquete [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) en forma de dependencia de desarrollo. Este paquete contiene las definiciones de tipos de Lambda.
```
npm install -D @types/aws-lambda
```
1. Abra el directorio **lib**. Debería ver un archivo llamado **hello-world-stack.ts**. Cree dos nuevos archivos en este directorio: **hello-world.function.ts** y **hello-world.ts**.
1. Abra **hello-world.function.ts** y agregue el siguiente código al archivo. Se trata del código de la función de Lambda.
**nota**
La instrucción `import` importa las definiciones de tipo de [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). No importa el paquete NPM de `aws-lambda`, que es una herramienta de terceros no relacionada. Para obtener más información, consulte [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) en el repositorio de GitHub DefinitelyTyped.
```
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 **hello-world.ts** y agregue el siguiente código al archivo. Este código contiene [la construcción NodejsFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), que crea la función de Lambda, y la [construcción LambdaRestApi](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), que crea la 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,
});
}
}
```
La construcción `NodejsFunction` presupone lo siguiente de manera predeterminada:
+ El controlador de función se llama `handler`.
+ El archivo .ts que contiene el código de la función (**hello-world.function.ts**) se encuentra en el mismo directorio que el archivo .ts que contiene la construcción (**hello-world.ts**). La construcción utiliza el ID de la construcción (“hello-world”) y el nombre del archivo del controlador de Lambda (“function”) para buscar el código de la función. Por ejemplo, si el código de la función se encuentra en un archivo llamado **hello-world.my-function.ts**, el archivo **hello-world.ts** debe hacer referencia al código de la función de este modo:
```
const helloFunction = new NodejsFunction(this, 'my-function');
```
Puede cambiar este comportamiento y configurar otros parámetros de esbuild. Para obtener más información, consulte [Configuración de esbuild](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html#configuring-esbuild) en la Referencia de la API de AWS CDK.
1. Abra **hello-world-stack.ts**. Este es el código que define la [pila de AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Reemplace el código con lo siguiente:
```
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. el directorio `hello-world` que contiene su archivo `cdk.json`, implemente su aplicación.
```
cdk deploy
```
1. AWS CDK compila y empaqueta la función de Lambda mediante esbuild y, a continuación, implementa la función en el tiempo de ejecución de Lambda. El resultado muestra el punto de conexión de la API REST. Abra el punto de conexión en un navegador para probar la función. Debería ver esta respuesta:
```
{"message":"hello world"}
```
Se trata de un punto de conexión de API pública al que se puede acceder a través de Internet. Se recomienda eliminar el punto de conexión después de las pruebas.
## Uso de AWS CLI y esbuild para implementar código de TypeScript en Lambda
El siguiente ejemplo muestra cómo transpilar e implementar código de TypeScript en Lambda mediante esbuild y AWS CLI. esbuild produce un archivo de JavaScript con todas las dependencias. Este es el único archivo que hay que agregar al archivo .zip.
**Requisitos previos**
Para completar los pasos de esta sección, debe disponer de lo siguiente:
+ [AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ Node.js
+ Un [rol de ejecución](lambda-intro-execution-role.md) para la función de Lambda.
+ Para los usuarios de Windows, una utilidad de archivos zip como [7zip](https://www.7-zip.org/download.html).
**Implementar una función de ejemplo**
1. En su máquina local, cree un directorio de proyecto para su nueva función.
1. Cree un nuevo proyecto de Node.js con npm o un administrador de paquetes de su elección.
```
npm init
```
1. Agregue los paquetes [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) y [esbuild](https://esbuild.github.io/) en forma de dependencias de desarrollo. El paquete `@types/aws-lambda` contiene las definiciones de tipos de Lambda.
```
npm install -D @types/aws-lambda esbuild
```
1. Cree un nuevo archivo con el nombre **index.ts**. Agregue el siguiente código al nuevo archivo. Se trata del código de la función de Lambda. La función devuelve el mensaje `hello world`. La función no crea ningún recurso de API Gateway.
**nota**
La instrucción `import` importa las definiciones de tipo de [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). No importa el paquete NPM de `aws-lambda`, que es una herramienta de terceros no relacionada. Para obtener más información, consulte [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) en el repositorio de GitHub DefinitelyTyped.
```
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. Agregue un script de compilación al archivo **package.json**. Esto configura esbuild para que cree automáticamente el paquete de implementación .zip. Para obtener más información, consulte [Build scripts](https://esbuild.github.io/getting-started/#build-scripts) (Scripts de compilación) en la documentación de 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 ]
En este ejemplo, el comando `"postbuild"` usa la utilidad [7zip](https://www.7-zip.org/download.html) para crear el archivo.zip. Utilice la utilidad zip de Windows que prefiera y modifique el comando según sea necesario.
```
"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. Cree el paquete.
```
npm run build
```
1. Cree una función de Lambda mediante el paquete de implementación .zip. Reemplace el texto resaltado con el nombre de recurso de Amazon (ARN) del [rol de ejecución](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. [Ejecute un evento de prueba](testing-functions.md) para confirmar que la función devuelve la siguiente respuesta. Si desea invocar esta función mediante API Gateway, [cree y configure una API REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-create-api.html).
```
{
"statusCode": 200,
"body": "{\"message\":\"hello world\"}"
}
```
# Implementar código de TypeScript transpilado en Lambda con imágenes de contenedor
Puede implementar el código de TypeScript en una función de AWS Lambda en forma de [imagen de contenedor](images-create.md) de Node.js. AWS proporciona [imágenes base](nodejs-image.md#nodejs-image-base) para Node.js para ayudarle a crear la imagen de contenedor. Estas imágenes base están precargadas con un tiempo de ejecución de lenguaje y otros componentes necesarios para ejecutar la imagen en Lambda. AWS proporciona un archivo Dockerfile para cada una de las imágenes base para ayudar a crear su imagen contenedor.
Si utiliza una imagen base de la comunidad o de una empresa privada, debe [agregar el cliente de interfaz de tiempo de ejecución (RIC) de Node.js](nodejs-image.md#nodejs-image-clients) a la imagen base para que sea compatible con Lambda.
Lambda proporciona un emulador de interfaz de tiempo de ejecución para realizar pruebas de manera local. Las imágenes base AWS para Node.js incluyen el emulador de interfaz de tiempo de ejecución. Si utiliza una imagen base alternativa, como una imagen de Alpine Linux o Debian, puede [compilar el emulador en su imagen](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#build-rie-into-your-base-image) o [instalarlo en su equipo local](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#test-an-image-without-adding-rie-to-the-image).
## Uso de una imagen base de Node.js para compilar y empaquetar código de función de TypeScript
### Requisitos previos
Para completar los pasos de esta sección, debe disponer de lo siguiente:
+ [AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [Docker](https://docs.docker.com/get-docker) (versión mínima 25.0.0)
+ El [complemento buildx](https://github.com/docker/buildx/blob/master/README.md) de Docker.
+ Node.js 22.x
### Creación de una imagen a partir de una imagen base
**Para crear una imagen a partir de una imagen base AWS para Lambda**
1. En su máquina local, cree un directorio de proyecto para su nueva función.
1. Cree un nuevo proyecto de Node.js con `npm` o un administrador de paquetes de su elección.
```
npm init
```
1. Agregue los paquetes [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) y [esbuild](https://esbuild.github.io/) en forma de dependencias de desarrollo. El paquete `@types/aws-lambda` contiene las definiciones de tipos de Lambda.
```
npm install -D @types/aws-lambda esbuild
```
1. Agregue un [script de compilación](https://esbuild.github.io/getting-started/#build-scripts) al archivo `package.json`.
```
"scripts": {
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js"
}
```
1. Cree un nuevo archivo denominado `index.ts`. Agregue el siguiente código de muestra al nuevo archivo. Se trata del código de la función de Lambda. La función devuelve el mensaje `hello world`.
**nota**
La instrucción `import` importa las definiciones de tipo de [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). No importa el paquete NPM de `aws-lambda`, que es una herramienta de terceros no relacionada. Para obtener más información, consulte [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) en el repositorio de GitHub DefinitelyTyped.
```
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. Cree un nuevo archivo Dockerfile con la siguiente configuración:
+ Establezca la propiedad `FROM` en el URI de la imagen base.
+ Establezca el argumento `CMD` para especificar el controlador de función de Lambda.
El siguiente Dockerfile de ejemplo utiliza una compilación de varias etapas. El primer paso transpila el código de TypeScript a JavaScript. El segundo paso produce una imagen de contenedor que contiene solo archivos de JavaScript y dependencias de producción.
Tenga en cuenta que el Dockerfile de ejemplo no incluye una [instrucción USER](https://docs.docker.com/reference/dockerfile/#user). Al implementar una imagen de contenedor en Lambda, Lambda define automáticamente un usuario predeterminado de Linux con permisos de privilegio mínimo. Esto es diferente del comportamiento estándar de Docker, que utiliza de forma predeterminada el usuario `root` cuando no se proporciona ninguna instrucción `USER`.
**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. Cree la imagen de Docker con el comando [docker build](https://docs.docker.com/engine/reference/commandline/build/). En el siguiente ejemplo se asigna un nombre a la imagen `docker-image` y se le asigna la [etiqueta](https://docs.docker.com/engine/reference/commandline/build/#tag) `test`. Para que la imagen sea compatible con Lambda, debe usar la opción `--provenance=false`.
```
docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test .
```
**nota**
El comando especifica la opción `--platform linux/amd64` para garantizar que el contenedor sea compatible con el entorno de ejecución de Lambda, independientemente de la arquitectura de la máquina de compilación. Si tiene intención de crear una función de Lambda con la arquitectura del conjunto de instrucciones ARM64, asegúrese de cambiar el comando para utilizar la opción `--platform linux/arm64` en su lugar.
### (Opcional) Prueba de la imagen de forma local
1. Inicie la imagen de Docker con el comando **docker run**. En este ejemplo, `docker-image` es el nombre de la imagen y `test` es la etiqueta.
```
docker run --platform linux/amd64 -p 9000:8080 docker-image:test
```
Este comando ejecuta la imagen como un contenedor y crea un punto de conexión local en `localhost:9000/2015-03-31/functions/function/invocations`.
**nota**
Si creó la imagen de Docker para la arquitectura del conjunto de instrucciones ARM64, asegúrese de utilizar la opción `--platform linux/arm64` en lugar de `--platform linux/amd64`.
1. Desde una nueva ventana de terminal, publique un evento en el punto de conexión local.
------
#### [ Linux/macOS ]
En Linux y macOS, ejecute el siguiente comando `curl`:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
```
Este comando invoca la función con un evento vacío y devuelve una respuesta. Si utiliza su propio código de función en lugar del código de función de ejemplo, quizás quiera invocar la función con una carga JSON. Ejemplo:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'
```
------
#### [ PowerShell ]
En PowerShell, ejecute el siguiente comando `Invoke-WebRequest`:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json"
```
Este comando invoca la función con un evento vacío y devuelve una respuesta. Si utiliza su propio código de función en lugar del código de función de ejemplo, quizás quiera invocar la función con una carga JSON. Ejemplo:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json"
```
------
1. Obtenga el ID del contenedor.
```
docker ps
```
1. Use el comando [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) para detener el contenedor. En este comando, reemplace `3766c4ab331c` por el ID del contenedor del paso anterior.
```
docker kill 3766c4ab331c
```
### Implementación de la imagen
**Para cargar la imagen en Amazon ECR y crear la función de Lambda**
1. Para autenticar la CLI de Docker en su registro de Amazon ECR, ejecute el comando [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html).
+ Establezca el valor de `--region` en la Región de AWS en la que desee crear el repositorio de Amazon ECR.
+ Reemplace `111122223333` por el ID de su Cuenta de 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. Cree un repositorio en Amazon ECR con el 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**
El repositorio de Amazon ECR debe estar en la misma Región de AWS que la función de Lambda.
Si se realiza de la forma correcta, verá una respuesta como la siguiente:
```
{
"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 el valor de `repositoryUri` de la salida del paso anterior.
1. Ejecute el comando [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) para etiquetar la imagen local en su repositorio de Amazon ECR como la versión más reciente. En este comando:
+ `docker-image:test` es el nombre y la [etiqueta](https://docs.docker.com/engine/reference/commandline/build/#tag) de su imagen de Docker. Son el nombre y la etiqueta de la imagen que especificó en el comando `docker build`.
+ Reemplace `` por el `repositoryUri` que ha copiado. Asegúrese de incluir `:latest` al final del URI.
```
docker tag docker-image:test :latest
```
Ejemplo:
```
docker tag docker-image:test 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. Ejecute el comando [docker push](https://docs.docker.com/engine/reference/commandline/push/) para implementar la imagen local en el repositorio de Amazon ECR. Asegúrese de incluir `:latest` al final del URI del repositorio.
```
docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. [Cree un rol de ejecución](lambda-intro-execution-role.md#permissions-executionrole-api) para la función si aún no tiene uno. Necesitará el nombre de recurso de Amazon (ARN) del rol en el paso siguiente.
1. Cree la función de Lambda. En `ImageUri`, especifique el URI del repositorio anterior. Asegúrese de incluir `:latest` al final del 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**
Puede crear una función con una imagen de una cuenta AWS diferente, siempre que la imagen esté en la misma región que la función de Lambda. Para obtener más información, consulte [Permisos entre cuentas de Amazon ECR](images-create.md#configuration-images-xaccount-permissions).
1. Invoque la función.
```
aws lambda invoke --function-name hello-world response.json
```
Debería ver una respuesta como la siguiente:
```
{
"ExecutedVersion": "$LATEST",
"StatusCode": 200
}
```
1. Para ver la salida de la función, compruebe el archivo `response.json`.
Para actualizar el código de la función, debe volver a compilar la imagen, cargar la nueva imagen en el repositorio de Amazon ECR y, a continuación, utilizar el comando [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) para implementar la imagen en la función de Lambda.
Lambda resuelve la etiqueta de la imagen en un resumen de imagen específico. Esto significa que si apunta la etiqueta de imagen que se utilizó para implementar la función a una nueva imagen en Amazon ECR, Lambda no actualiza automáticamente la función para usar la nueva imagen.
Para implementar la nueva imagen en la misma función de Lambda, debe usar el comando [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html), incluso si la etiqueta de la imagen en Amazon ECR sigue siendo la misma. En el siguiente ejemplo, la opción `--publish` crea una nueva versión de la función con la imagen del contenedor actualizada.
```
aws lambda update-function-code \
--function-name hello-world \
--image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \
--publish
```
# Uso del objeto de contexto Lambda para recuperar la información de la función de TypeScript
Cuando Lambda ejecuta su función, pasa un objeto context al [controlador](typescript-handler.md). Este objeto proporciona métodos y propiedades que facilitan información acerca de la invocación, la función y el entorno de ejecución.
Para habilitar la verificación de tipos del objeto de contexto, debe agregar el paquete [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) como dependencia de desarrollo e importar el tipo `Context`. Para obtener más información, consulte [Definiciones de tipos de Lambda](lambda-typescript.md#typescript-type-definitions).
**Métodos de context**
+ `getRemainingTimeInMillis()`: devuelve el número de milisegundos que quedan antes del tiempo de espera de la ejecución.
**Propiedades de context**
+ `functionName`: el nombre de la función de Lambda.
+ `functionVersion`: la [versión](configuration-versions.md) de la función.
+ `invokedFunctionArn`: el nombre de recurso de Amazon (ARN) que se utiliza para invocar esta función. Indica si el invocador especificó un número de versión o alias.
+ `memoryLimitInMB`: cantidad de memoria asignada a la función.
+ `awsRequestId`: el identificador de la solicitud de invocación.
+ `logGroupName`: grupo de registros de para la función.
+ `logStreamName`: el flujo de registro de la instancia de la función.
+ `identity`: (aplicaciones móviles) Información acerca de la identidad de Amazon Cognito que autorizó la solicitud.
+ `cognitoIdentityId`: la identidad autenticada de Amazon Cognito.
+ `cognitoIdentityPoolId`: el grupo de identidad de Amazon Cognito que ha autorizado la invocación.
+ `clientContext`: (aplicaciones móviles) Contexto de cliente proporcionado a Lambda por la aplicación 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`: valores personalizados que establece la aplicación del cliente.
+ `callbackWaitsForEmptyEventLoop`: de forma predeterminada (`true`), cuando se utiliza un controlador de funciones basado en la devolución de llamada, Lambda espera a que el bucle de eventos esté vacío una vez ejecutada la devolución de llamada antes de finalizar la invocación de la función. Establézcalo en `false` para enviar la respuesta y finalizar la invocación de forma inmediata después de la ejecución de la devolución de llamada, en lugar de esperar a que el bucle de eventos esté vacío. Los eventos pendientes seguirán ejecutándose durante la siguiente invocación. Tenga en cuenta que Lambda solo admite controladores de funciones basados en la devolución de llamada para Node.js 22 y tiempos de ejecución anteriores.
**Example archivo index.ts**
La siguiente función de ejemplo registra información de contexto y devuelve la ubicación de los registros.
Antes de utilizar este código en una función de Lambda, debe agregar el paquete [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) como dependencia de implementación. Este paquete contiene las definiciones de tipos de Lambda. Para obtener más información, consulte [Definiciones de tipos de 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;
};
```
# Registro y supervisión de las funciones de Lambda de TypeScript
AWS Lambda supervisa de forma automática funciones de Lambda y envía entradas de registros a Amazon CloudWatch. Su función de Lambda viene con un grupo de registros de Registros de CloudWatch y con un flujo de registro para cada instancia de su función. El entorno de tiempo de ejecución de Lambda envía detalles sobre cada invocación y otros resultados del código de su función al flujo de registro. Para obtener más información acerca de Registros de CloudWatch, consulte [Envío de registros de funciones de Lambda a Registros de CloudWatch](monitoring-cloudwatchlogs.md).
Para generar registros desde el código de la función, puede utilizar los métodos del [objeto de la consola](https://nodejs.org/docs/latest-v18.x/api/console.html). Para un registro más detallado, puede utilizar cualquier biblioteca de registro que escriba en `stdout` o `stderr`.
**Topics**
+ [
## Uso de herramientas y bibliotecas de registro
](#typescript-tools-libraries)
+ [
## Uso de Powertools para AWS Lambda (TypeScript) y AWS SAM para el registro estructurado
](#typescript-logging-sam)
+ [
## Uso de Powertools para AWS Lambda (TypeScript) y el AWS CDK para el registro estructurado
](#typescript-logging-cdk)
+ [
## Visualización de los registros en la consola de Lambda
](#typescript-logging-console)
+ [
## Visualización de los registros de en la consola de CloudWatch
](#typescript-logging-cwconsole)
## Uso de herramientas y bibliotecas de registro
[Powertools para AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/) es un kit de herramientas para desarrolladores destinado a implementar prácticas recomendadas sin servidor y aumentar la velocidad de los desarrolladores. La [utilidad de logger](https://docs.powertools.aws.dev/lambda/typescript/latest/features/logger/) proporciona un logger optimizado para Lambda que incluye información adicional sobre el contexto de la función en todas las funciones con un resultado estructurado como JSON. Utilice esta utilidad para hacer lo siguiente:
+ Capturar campos clave del contexto de Lambda, arranque en frío y resultados de registro de estructuras como JSON
+ Registrar los eventos de invocación de Lambda cuando se le indique (desactivado de forma predeterminada)
+ Imprimir todos los registros solo para un porcentaje de las invocaciones mediante el muestreo de registros (desactivado de forma predeterminada)
+ Agregar claves adicionales al registro estructurado en cualquier momento
+ Utilizar un formateador de registros personalizado (traiga su propio formateador) para generar registros en una estructura compatible con el RFC de registro de su organización
## Uso de Powertools para AWS Lambda (TypeScript) y AWS SAM para el registro estructurado
Siga los pasos que figuran a continuación para descargar, crear e implementar una aplicación “Hola, mundo” de TypeScript de muestra con módulos de [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) integrados mediante AWS SAM. Esta aplicación implementa un backend de API básico y utiliza Powertools para emitir registros, métricas y seguimiento. Consta de un punto de conexión de Amazon API Gateway y una función de Lambda. Cuando se envía una solicitud GET al punto de conexión de API Gateway, la función de Lambda se invoca, envía registros y métricas a CloudWatch mediante Embedded Metric Format y envía seguimiento a AWS X-Ray. La función devuelve el mensaje `hello world`.
**Requisitos previos**
Para completar los pasos de esta sección, debe disponer de lo siguiente:
+ Node.js 20 o posterior
+ [AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM Versión 1.75 o posterior de la CLI de](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Si tiene una versión anterior de la CLI de AWS SAM, consulte [Actualización de la CLI de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Implementar una aplicación de ejemplo de AWS SAM**
1. Inicialice la aplicación utilizando la plantilla de TypeScript de tipo Hola Mundo.
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. Compile la aplicación.
```
cd sam-app && sam build
```
1. Implemente la aplicación.
```
sam deploy --guided
```
1. Siga las indicaciones que aparecen en pantalla. Para aceptar las opciones predeterminadas proporcionadas en la experiencia interactiva, oprima `Enter`.
**nota**
En **HelloWorldFunction es posible que no tenga definida la autorización, ¿está bien?**, asegúrese de ingresar `y`.
1. Obtenga la URL de la aplicación implementada:
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. Invoque el punto de conexión de la API:
```
curl
```
Si se realiza de forma correcta, verá el siguiente resultado:
```
{"message":"hello world"}
```
1. Para obtener los registros de la función, ejecute [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Para obtener más información, consulte [Uso de registros](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) en la *Guía para desarrolladores de AWS Serverless Application Model*.
```
sam logs --stack-name sam-app
```
El resultado del registro tendrá este aspecto:
```
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. Se trata de un punto de conexión de API pública al que se puede acceder a través de Internet. Se recomienda eliminar el punto de conexión después de las pruebas.
```
sam delete
```
### Administración de retención de registros
Los grupos de registro no se eliminan automáticamente cuando se elimina una función. Para evitar almacenar registros de forma indefinida, elimine el grupo de registros o configure un periodo de retención después del cual CloudWatch los eliminará de forma automática. Para configurar la retención de registros, agregue lo siguiente a la plantilla de 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 de Powertools para AWS Lambda (TypeScript) y el AWS CDK para el registro estructurado
Siga los pasos que figuran a continuación para descargar, crear e implementar una aplicación “Hola, mundo” de TypeScript de muestra con módulos de [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) integrados mediante AWS CDK. Esta aplicación implementa un backend de API básico y utiliza Powertools para emitir registros, métricas y seguimiento. Consta de un punto de conexión de Amazon API Gateway y una función de Lambda. Cuando se envía una solicitud GET al punto de conexión de API Gateway, la función de Lambda se invoca, envía registros y métricas a CloudWatch mediante Embedded Metric Format y envía seguimiento a AWS X-Ray. La función devuelve el mensaje `hello world`.
**Requisitos previos**
Para completar los pasos de esta sección, debe disponer de lo siguiente:
+ Node.js 20 o posterior
+ [AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versión 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM Versión 1.75 o posterior de la CLI de](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Si tiene una versión anterior de la CLI de AWS SAM, consulte [Actualización de la CLI de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Implementar una aplicación de ejemplo de AWS CDK**
1. Cree un directorio de proyecto para la nueva aplicación.
```
mkdir hello-world
cd hello-world
```
1. Inicialice la aplicación.
```
cdk init app --language typescript
```
1. Agregue el paquete [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) en forma de dependencia de desarrollo.
```
npm install -D @types/aws-lambda
```
1. Instale la [utilidad Logger](https://docs.aws.amazon.com/powertools/typescript/latest/features/logger/) de Powertools.
```
npm install @aws-lambda-powertools/logger
```
1. Abra el directorio **lib**. Debería ver un archivo llamado **hello-world-stack.ts**. Cree dos nuevos archivos en este directorio: **hello-world.function.ts** y **hello-world.ts**.
1. Abra **hello-world.function.ts** y agregue el siguiente código al archivo. Se trata del código de la función de 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 **hello-world.ts** y agregue el siguiente código al archivo. Contiene el [constructo NodejsFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), que crea la función de Lambda, configura las variables de entorno para Powertools y establece la retención de registros en una semana. También incluye el [constructo LambdaRestApi](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), que crea la API de 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 **hello-world-stack.ts**. Este es el código que define la [pila de AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Reemplace el código con lo siguiente:
```
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. Vuelva al directorio del proyecto.
```
cd hello-world
```
1. Implementación de la aplicación.
```
cdk deploy
```
1. Obtenga la URL de la aplicación implementada:
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. Invoque el punto de conexión de la API:
```
curl
```
Si se realiza de forma correcta, verá el siguiente resultado:
```
{"message":"hello world"}
```
1. Para obtener los registros de la función, ejecute [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Para obtener más información, consulte [Uso de registros](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) en la *Guía para desarrolladores de AWS Serverless Application Model*.
```
sam logs --stack-name HelloWorldStack
```
El resultado del registro tendrá este aspecto:
```
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. Se trata de un punto de conexión de API pública al que se puede acceder a través de Internet. Se recomienda eliminar el punto de conexión después de las pruebas.
```
cdk destroy
```
## Visualización de los registros en la consola de Lambda
Puede utilizar la consola de Lambda para ver la salida del registro después de invocar una función de Lambda.
Si su código se puede probar desde el editor de **código** integrado, encontrará los registros en los **resultados de ejecución**. Cuando utilice la característica de prueba de la consola para invocar una función, encontrará la **Salida de registro** en la sección de **Detalles**.
## Visualización de los registros de en la consola de CloudWatch
Puede utilizar la consola Amazon CloudWatch para ver los registros de todas las invocaciones de funciones de Lambda.
**Visualización de los registros en la consola CloudWatch**
1. En la consola de CloudWatch, abra la [página de grupos de registro](https://console.aws.amazon.com/cloudwatch/home?#logs:).
1. Seleccione el grupo de registros para su función (**/aws/lambda/*your-function-name***).
1. Elija una secuencia de registro.
Cada flujo de registro se corresponde con una [instancia de su función](lambda-runtime-environment.md). Aparece un flujo de registro cuando actualiza la función de Lambda y cuando se crean instancias adicionales para gestionar invocaciones simultáneas. Para encontrar registros para una invocación específica, le recomendamos que interfiera su función con AWS X-Ray. X-Ray registra los detalles sobre la solicitud y el flujo de registro en el seguimiento.
# Seguimiento del código de TypeScript en AWS Lambda
Lambda se integra con AWS X-Ray para permitirle seguir, depurar y optimizar aplicaciones de Lambda. Puede utilizar X-Ray para seguir una solicitud mientras atraviesa los recursos de la aplicación, que pueden incluir funciones de Lambda y otros servicios de AWS.
Para enviar datos de seguimiento a X-Ray, puede utilizar una de estas tres bibliotecas de SDK:
+ [AWS Distro for OpenTelemetry (ADOT)](https://aws.amazon.com/otel): una distribución segura, lista para producción y con soporte de AWS del OpenTelemetry (OTel) SDK.
+ [AWS X-Ray SDK para Node.js](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html): un SDK para generar y enviar datos de seguimiento a X-Ray.
+ [Powertools para AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/latest/): un kit de herramientas para desarrolladores destinado a implementar prácticas recomendadas sin servidor y aumentar la velocidad de los desarrolladores.
Cada uno de los SDK ofrecen formas de enviar los datos de telemetría al servicio X-Ray. Tras ello, se puede utilizar X-Ray para consultar, filtrar y obtener información sobre las métricas de rendimiento de la aplicación con el fin de identificar problemas y oportunidades de optimización.
**importante**
Los SDK de X-Ray y Powertools para AWS Lambda son parte de una solución de instrumentación completamente integrada que ofrece AWS. Las capas Lambda de ADOT forman parte de un estándar que abarca todo el sector para la instrumentación de seguimiento que recopila más datos en general, pero es posible que no sean adecuadas para todos los casos de uso. Puede implementar el seguimiento integral en X-Ray con cualquiera de las soluciones. Para obtener más información sobre cuál elegir, consulte [Elegir entre SDK de AWS Distro para OpenTelemetry y X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing).
**Topics**
+ [
## Uso de Powertools para AWS Lambda (TypeScript) y AWS SAM para el seguimiento
](#typescript-tracing-sam)
+ [
## Uso de Powertools para AWS Lambda (TypeScript) y el AWS CDK para el seguimiento
](#typescript-tracing-cdk)
+ [
## Interpretación de un seguimiento de X-Ray
](#typescript-tracing-interpretation)
## Uso de Powertools para AWS Lambda (TypeScript) y AWS SAM para el seguimiento
Siga los pasos que figuran a continuación para descargar, crear e implementar una aplicación “Hola, mundo” de TypeScript de muestra con módulos de [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) integrados mediante AWS SAM. Esta aplicación implementa un backend de API básico y utiliza Powertools para emitir registros, métricas y seguimiento. Consta de un punto de conexión de Amazon API Gateway y una función de Lambda. Cuando se envía una solicitud GET al punto de conexión de API Gateway, la función de Lambda se invoca, envía registros y métricas a CloudWatch mediante Embedded Metric Format y envía seguimiento a AWS X-Ray. La función devuelve el mensaje `hello world`.
**Requisitos previos**
Para completar los pasos de esta sección, debe disponer de lo siguiente:
+ Node.js
+ [AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM Versión 1.75 o posterior de la CLI de](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Si tiene una versión anterior de la CLI de AWS SAM, consulte [Actualización de la CLI de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Implementar una aplicación de ejemplo de AWS SAM**
1. Inicialice la aplicación utilizando la plantilla de TypeScript de tipo Hola Mundo.
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x --no-tracing
```
1. Compile la aplicación.
```
cd sam-app && sam build
```
1. Implemente la aplicación.
```
sam deploy --guided
```
1. Siga las indicaciones que aparecen en pantalla. Para aceptar las opciones predeterminadas proporcionadas en la experiencia interactiva, oprima `Enter`.
**nota**
En **HelloWorldFunction es posible que no tenga definida la autorización, ¿está bien?**, asegúrese de ingresar `y`.
1. Obtenga la URL de la aplicación implementada:
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. Invoque el punto de conexión de la API:
```
curl
```
Si se realiza de forma correcta, verá el siguiente resultado:
```
{"message":"hello world"}
```
1. Para obtener el seguimiento de la función, ejecute [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).
```
sam traces
```
El resultado del seguimiento tendrá este aspecto:
```
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. Se trata de un punto de conexión de API pública al que se puede acceder a través de Internet. Se recomienda eliminar el punto de conexión después de las pruebas.
```
sam delete
```
X-Ray no sigue todas las solicitudes realizadas a la aplicación. X-Ray aplica un algoritmo de muestreo para garantizar que el seguimiento sea eficiente, a la vez que proporciona una muestra representativa de todas las solicitudes. La tasa de muestreo es 1 solicitud por segundo y un 5 por ciento de las solicitudes adicionales. La frecuencia de muestreo de X-Ray no se puede configurar para las funciones.
## Uso de Powertools para AWS Lambda (TypeScript) y el AWS CDK para el seguimiento
Siga los pasos que figuran a continuación para descargar, crear e implementar una aplicación “Hola, mundo” de TypeScript de muestra con módulos de [Powertools para AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) integrados mediante AWS CDK. Esta aplicación implementa un backend de API básico y utiliza Powertools para emitir registros, métricas y seguimiento. Consta de un punto de conexión de Amazon API Gateway y una función de Lambda. Cuando se envía una solicitud GET al punto de conexión de API Gateway, la función de Lambda se invoca, envía registros y métricas a CloudWatch mediante Embedded Metric Format y envía seguimiento a AWS X-Ray. La función devuelve el mensaje `hello world`.
**Requisitos previos**
Para completar los pasos de esta sección, debe disponer de lo siguiente:
+ Node.js
+ [AWS CLI versión 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versión 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [Versión 1.75 o posterior de la CLI de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Si tiene una versión anterior de la CLI de AWS SAM, consulte [Actualización de la CLI de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Implementar una aplicación de ejemplo de AWS Cloud Development Kit (AWS CDK)**
1. Cree un directorio de proyecto para la nueva aplicación.
```
mkdir hello-world
cd hello-world
```
1. Inicialice la aplicación.
```
cdk init app --language typescript
```
1. Agregue el paquete [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) en forma de dependencia de desarrollo.
```
npm install -D @types/aws-lambda
```
1. Instale la [utilidad Tracer](https://docs.aws.amazon.com/powertools/typescript/latest/features/tracer/) de Powertools.
```
npm install @aws-lambda-powertools/tracer
```
1. Abra el directorio **lib**. Debería ver un archivo llamado **hello-world-stack.ts**. Cree dos nuevos archivos en este directorio: **hello-world.function.ts** y **hello-world.ts**.
1. Abra **hello-world.function.ts** y agregue el siguiente código al archivo. Se trata del código de la función de 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 **hello-world.ts** y agregue el siguiente código al archivo. Contiene el [constructo NodejsFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), que crea la función de Lambda, configura las variables de entorno para Powertools y establece la retención de registros en una semana. También incluye el [constructo LambdaRestApi](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), que crea la API de 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 **hello-world-stack.ts**. Este es el código que define la [pila de AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Reemplace el código con lo siguiente:
```
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. Implemente la aplicación.
```
cd ..
cdk deploy
```
1. Obtenga la URL de la aplicación implementada:
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. Invoque el punto de conexión de la API:
```
curl
```
Si se realiza de forma correcta, verá el siguiente resultado:
```
{"message":"hello world"}
```
1. Para obtener el seguimiento de la función, ejecute [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).
```
sam traces
```
El resultado del seguimiento tendrá este aspecto:
```
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. Se trata de un punto de conexión de API pública al que se puede acceder a través de Internet. Se recomienda eliminar el punto de conexión después de las pruebas.
```
cdk destroy
```
## Interpretación de un seguimiento de X-Ray
Después de configurar el seguimiento activo, se pueden observar solicitudes específicas a través de la aplicación. El [ mapa de seguimiento de X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-servicemap.html) muestra información sobre la aplicación y todos sus componentes. En el siguiente ejemplo, se muestra un seguimiento de la aplicación de muestra:
![\[\]](http://docs.aws.amazon.com/es_es/lambda/latest/dg/images/sample-typescript-servicemap.png)