Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Création de fonctions Lambda avec TypeScript
Vous pouvez utiliser le moteur d'exécution Node.js pour exécuter TypeScript du code dans AWS Lambda. Étant donné que Node.js n'exécute pas TypeScript le code de manière native, vous devez d'abord le transpiler dans TypeScript . JavaScript Utilisez ensuite les JavaScript fichiers pour déployer votre code de fonction sur Lambda. Votre code s'exécute dans un environnement qui inclut le AWS SDK pour JavaScript, avec les informations d'identification d'un rôle Gestion des identités et des accès AWS (IAM) que vous gérez. Pour en savoir plus sur les versions du kit SDK incluses dans les environnements d’exécution Node.js, consultez [Versions du SDK incluses dans l’environnement d’exécution](lambda-nodejs.md#nodejs-sdk-included).
Lambda prend en charge les environnements d’exécution Node.js suivants.
| Nom | Identifiant | Système d’exploitation | Date d’obsolescence | Créer la fonction de blocage | Mettre à jour la fonction de blocage |
| --- | --- | --- | --- | --- | --- |
| Node.js 24 | `nodejs24.x` | Amazon Linux 2023 | 30 avril 2028 | 1 juin 2028 | 1 juillet 2028 |
| Node.js 22 | `nodejs22.x` | Amazon Linux 2023 | 30 avril 2027 | 1 juin 2027 | 1 juillet 2027 |
| Node.js 20 | `nodejs20.x` | Amazon Linux 2023 | 30 avril 2026 | 31 août 2026 | 30 sept. 2026 |
**Topics**
+ [Configuration d'un environnement TypeScript de développement](#typescript-dev)
+ [Définitions de type pour Lambda](#typescript-type-definitions)
+ [Définissez le gestionnaire de fonctions Lambda dans TypeScript](typescript-handler.md)
+ [Déployez TypeScript du code transpilé dans Lambda avec des archives de fichiers .zip](typescript-package.md)
+ [Déployez TypeScript du code transpilé dans Lambda avec des images de conteneur](typescript-image.md)
+ [Utilisation de l'objet de contexte Lambda pour récupérer les informations relatives aux fonctions TypeScript](typescript-context.md)
+ [Enregistrez et surveillez les fonctions TypeScript Lambda](typescript-logging.md)
+ [TypeScript Code de suivi dans AWS Lambda](typescript-tracing.md)
## Configuration d'un environnement TypeScript de développement
Utilisez un environnement de développement intégré (IDE) local ou un éditeur de texte pour écrire votre code de TypeScript fonction. Vous ne pouvez pas créer de TypeScript code sur la console Lambda.
Vous pouvez utiliser [esbuild](https://esbuild.github.io/) ou le TypeScript compilateur (`tsc`) de Microsoft pour transpiler votre TypeScript code dans. JavaScript [AWS Serverless Application Model (AWS SAM)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html) et [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) utilisent tous deux esbuild.
Tenez compte des éléments suivants lorsque vous utilisez esbuild :
+ Il y a plusieurs [TypeScript mises en garde](https://esbuild.github.io/content-types/#typescript-caveats).
+ Vous devez configurer vos paramètres de TypeScript transpilation pour qu'ils correspondent à l'environnement d'exécution Node.js que vous prévoyez d'utiliser. Pour plus d’informations, consultez [Cible](https://esbuild.github.io/api/#target) dans la documentation d’esbuild. [Pour un exemple de fichier **tsconfig.json** qui montre comment cibler une version spécifique de Node.js prise en charge par Lambda, reportez-vous au référentiel. TypeScript GitHub ](https://github.com/tsconfig/bases/blob/main/bases/node14.json)
+ esbuild n’effectue pas de vérifications du type. Pour vérifier les types, utilisez le compilateur `tsc`. Exécutez `tsc -noEmit` ou ajoutez un paramètre `"noEmit"` dans votre fichier **tsconfig.json** comme illustré dans l’exemple suivant. Cela permet de ne pas `tsc` émettre de JavaScript fichiers. Après avoir vérifié les types, utilisez esbuild pour convertir les TypeScript fichiers en 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"]
}
```
## Définitions de type pour Lambda
Le package [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) contient les définitions de type pour les fonctions Lambda. Installez ce package lorsque votre fonction utilise l’un des éléments suivants :
+ Sources AWS d'événements courantes, telles que :
+ `APIGatewayProxyEvent` : pour les [intégrations de proxy Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html)
+ `SNSEvent` : pour les [notifications Amazon Simple Notification Service](with-sns.md)
+ `SQSEvent` : pour les [messages Amazon Simple Queue Service](with-sqs.md)
+ `S3Event` : pour les [événements de déclencheur S3](with-s3.md)
+ `DynamoDBStreamEvent` : pour [Amazon DynamoDB Streams](with-ddb.md)
+ L’objet [Contexte](typescript-context.md) Lambda
+ Le modèle du gestionnaire de [rappels](typescript-handler.md#typescript-handler-callback)
Pour ajouter les définitions de type Lambda à votre fonction, installez `@types/aws-lambda` en tant que dépendance de développement :
```
npm install -D @types/aws-lambda
```
Importez ensuite les types depuis `aws-lambda` :
```
import { Context, S3Event, APIGatewayProxyEvent } from 'aws-lambda';
export const handler = async (event: S3Event, context: Context) => {
// Function code
};
```
L’instruction `import ... from 'aws-lambda'` importe les définitions de type. Elle n’importe pas le package npm `aws-lambda`, qui est un outil tiers indépendant. Pour plus d'informations, consultez [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) dans le référentiel. DefinitelyTyped GitHub
**Note**
Vous n’avez pas besoin de [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) lorsque vous utilisez vos propres définitions de type personnalisées. Pour un exemple de fonction qui définit son propre type pour un objet d’événement, consultez [Exemple de code de TypeScript fonction Lambda](typescript-handler.md#typescript-example-code).
# Définissez le gestionnaire de fonctions Lambda dans TypeScript
Le *gestionnaire* de fonction Lambda est la méthode dans votre code de fonction qui traite les événements. Lorsque votre fonction est invoquée, Lambda exécute la méthode du gestionnaire. Votre fonction s’exécute jusqu’à ce que le gestionnaire renvoie une réponse, se ferme ou expire.
Cette page explique comment utiliser les gestionnaires de fonctions Lambda dans TypeScript, notamment les options de configuration du projet, les conventions de dénomination et les meilleures pratiques. Cette page inclut également un exemple de fonction TypeScript Lambda qui collecte des informations relatives à une commande, produit un reçu sous forme de fichier texte et place ce fichier dans un bucket Amazon Simple Storage Service (Amazon S3). Pour plus d’informations sur le déploiement de votre fonction après l’avoir écrite, consultez [Déployez TypeScript du code transpilé dans Lambda avec des archives de fichiers .zip](typescript-package.md) ou [Déployez TypeScript du code transpilé dans Lambda avec des images de conteneur](typescript-image.md).
**Topics**
+ [Configuration de votre TypeScript projet](#typescript-handler-setup)
+ [Exemple de code de TypeScript fonction Lambda](#typescript-example-code)
+ [Modules CommonJS et ES](#typescript-commonjs-es-modules)
+ [Initialisation de Node.js](#typescript-initialization)
+ [Convention de nommage du gestionnaire](#typescript-handler-naming)
+ [Définition et accès à l’objet d’événement d’entrée](#typescript-example-input)
+ [Modèles de gestionnaire valides pour les fonctions TypeScript](#typescript-handler-signatures)
+ [Utilisation du SDK pour la JavaScript version 3 dans votre gestionnaire](#typescript-example-sdk-usage)
+ [Accès aux variables d’environnement](#typescript-example-envvars)
+ [Utilisation de l'état global](#typescript-handler-state)
+ [Meilleures pratiques en matière de code pour les fonctions TypeScript Lambda](#typescript-best-practices)
## Configuration de votre TypeScript projet
Utilisez un environnement de développement intégré (IDE) local ou un éditeur de texte pour écrire votre code de TypeScript fonction. Vous ne pouvez pas créer de TypeScript code sur la console Lambda.
Il existe plusieurs manières d'initialiser un projet TypeScript Lambda. Par exemple, vous pouvez créer un projet en utilisant `npm`, créer une [application AWS SAM](typescript-package.md#aws-sam-ts) ou créer une [application AWS CDK](typescript-package.md#aws-cdk-ts). Pour créer un projet avec `npm` :
```
npm init
```
Le code de votre fonction se trouve dans un `.ts` fichier que vous transpirez dans un JavaScript fichier au moment de la création. Vous pouvez utiliser [esbuild](https://esbuild.github.io/) ou le TypeScript compilateur (`tsc`) de Microsoft pour transpiler votre TypeScript code dans. JavaScript Pour utiliser esbuild, ajoutez-le en tant que dépendance de développement :
```
npm install -D esbuild
```
Un projet de fonction TypeScript Lambda typique suit cette structure générale :
```
/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
```
## Exemple de code de TypeScript fonction Lambda
L’exemple de code de fonction Lambda suivant prend en compte les informations relatives à une commande, produit un reçu sous forme de fichier texte et place ce fichier dans un compartiment Amazon S3. Cet exemple définit un type d’événement personnalisé (`OrderEvent`). Pour savoir comment importer des définitions de type pour les sources d' AWS événements, consultez la section [Définitions de type pour Lambda](lambda-typescript.md#typescript-type-definitions).
**Note**
Cet exemple utilise un gestionnaire de modules ES. Lambda prend en charge à la fois le module ES et les gestionnaires CommonJS. Pour de plus amples informations, veuillez consulter [Modules CommonJS et ES](nodejs-handler.md#nodejs-commonjs-es-modules).
**Example Fonction 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'}`);
}
}
```
Ce fichier `index.ts` comprend les sections suivantes :
+ Bloc `import` : utilisez ce bloc pour inclure les bibliothèques que votre fonction Lambda requiert, comme les [clients du SDK AWS](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/the-request-object.html).
+ Déclaration `const s3Client` : initialise un [client Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/) en dehors de la fonction du gestionnaire. Lambda exécute donc ce code pendant la [phase d’initialisation](lambda-runtime-environment.md#runtimes-lifecycle-ib), et le client est conservé pour être [réutilisé lors de plusieurs appels](lambda-runtime-environment.md#execution-environment-reuse).
+ `type OrderEvent` : définit la structure de l’événement d’entrée attendu.
+ `export const handler` : le gestionnaire de la fonction principal que Lambda invoque. Lorsque vous déployez votre fonction, spécifiez `index.handler` pour la propriété [Gestionnaire](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler). La valeur de la propriété `Handler` est le nom du fichier et le nom de la méthode du gestionnaire exporté, séparés par un point.
+ Fonction `uploadReceiptToS3` : une fonction d’assistance référencée par la fonction du gestionnaire principal.
Pour que cette fonction fonctionne correctement, son [rôle d’exécution](lambda-intro-execution-role.md) doit autoriser l’action `s3:PutObject`. Assurez-vous également de définir la variable d’environnement `RECEIPT_BUCKET`. Après une invocation réussie, le compartiment Amazon S3 doit contenir un fichier de reçu.
## Modules CommonJS et ES
Node.js prend en charge deux systèmes de modules : CommonJS et ECMAScript modules (modules ES). [Lambda recommande d'utiliser les modules ES car ils prennent en charge l'attente de haut niveau, ce qui permet d'effectuer des tâches asynchrones lors de l'initialisation de l'environnement d'exécution.](#typescript-initialization)
Node.js traite les fichiers avec une extension de nom de `.cjs` fichier comme des modules CommonJS tandis qu'une `.mjs` extension désigne les modules ES. Par défaut, Node.js traite les fichiers portant l'extension de nom de `.js` fichier comme des modules CommonJS. Vous pouvez configurer Node.js pour traiter les `.js` fichiers comme des modules ES en spécifiant le `type` as `module` dans le `package.json` fichier de la fonction. Vous pouvez configurer Node.js dans Lambda pour détecter automatiquement si un `.js` fichier doit être traité comme CommonJS ou comme un module ES en ajoutant l'`—experimental-detect-module`indicateur à la `NODE_OPTIONS` variable d'environnement. Pour plus d'informations, consultez la section [Fonctionnalités expérimentales de Node.js](lambda-nodejs.md#nodejs-experimental-features).
Les exemples suivants montrent des gestionnaires de fonctions écrits à l'aide de modules ES et de modules CommonJS. Les autres exemples de cette page utilisent tous des modules ES.
## Initialisation de Node.js
Node.js utilise un I/O modèle non bloquant qui prend en charge des opérations asynchrones efficaces à l'aide d'une boucle d'événements. Par exemple, si Node.js effectue un appel réseau, la fonction continue de traiter les autres opérations sans bloquer une réponse réseau. Lorsque la réponse du réseau est reçue, elle est placée dans la file de rappel. Les tâches de la file d'attente sont traitées lorsque la tâche en cours est terminée.
Lambda recommande d'utiliser l'attente de haut niveau afin que les tâches asynchrones initiées lors de l'initialisation de l'environnement d'exécution soient terminées pendant l'initialisation. Les tâches asynchrones qui ne sont pas terminées lors de l'initialisation s'exécutent généralement lors du premier appel de fonction. Cela peut entraîner un comportement inattendu ou des erreurs. Par exemple, l'initialisation de votre fonction peut effectuer un appel réseau pour récupérer un paramètre depuis le Parameter Store AWS . Si cette tâche n'est pas terminée lors de l'initialisation, la valeur peut être nulle lors d'un appel. Il peut également y avoir un délai entre l'initialisation et l'appel, ce qui peut déclencher des erreurs lors d'opérations sensibles au facteur temps. En particulier, les appels de AWS service peuvent s'appuyer sur des signatures de demande urgentes, ce qui entraîne l'échec des appels de service si l'appel n'est pas terminé pendant la phase d'initialisation. L'exécution des tâches lors de l'initialisation améliore généralement les performances de démarrage à froid et les performances d'appel d'abord lors de l'utilisation de la concurrence provisionnée. Pour plus d'informations, consultez notre article de 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).
## Convention de nommage du gestionnaire
Lorsque vous configurez une fonction, la valeur du paramètre [Gestionnaire](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler) est le nom du fichier et le nom de la méthode du gestionnaire exporté, séparés par un point. La valeur par défaut des fonctions créées dans la console et dans les exemples de ce guide est `index.handler`. Cela indique la méthode `handler` qui est exportée à partir du fichier `index.js` ou `index.mjs`.
Si vous créez une fonction dans la console en utilisant un nom de fichier ou un nom de gestionnaire de fonction différent, vous devez modifier le nom du gestionnaire par défaut.
**Pour modifier le nom du gestionnaire de fonction (console)**
1. Ouvrez la page [Fonctions](https://console.aws.amazon.com/lambda/home#/functions) de la console Lambda et choisissez votre fonction.
1. Cliquez sur l’onglet **Code**.
1. Faites défiler l’écran jusqu’au volet **Paramètres d’exécution** et choisissez **Modifier**.
1. Dans **Gestionnaire**, saisissez le nouveau nom de votre gestionnaire de fonction.
1. Choisissez **Enregistrer**.
## Définition et accès à l’objet d’événement d’entrée
JSON est le format d’entrée le plus courant et standard pour les fonctions Lambda. Dans cet exemple, la fonction exige une entrée similaire à l’exemple suivant :
```
{
"order_id": "12345",
"amount": 199.99,
"item": "Wireless Headphones"
}
```
Lorsque vous utilisez des fonctions Lambda dans TypeScript, vous pouvez définir la forme de l'événement d'entrée à l'aide d'un type ou d'une interface. Dans cet exemple, nous définissons la structure de l’événement à l’aide d’un type :
```
type OrderEvent = {
order_id: string;
amount: number;
item: string;
}
```
Après avoir défini le type ou l’interface, utilisez-le dans la signature de votre gestionnaire pour garantir la sécurité du type :
```
export const handler = async (event: OrderEvent): Promise => {
```
Lors de la compilation, TypeScript vérifie que l'objet d'événement contient les champs obligatoires avec les types corrects. Par exemple, le TypeScript compilateur signale une erreur si vous essayez de l'utiliser `event.order_id` sous forme de nombre ou `event.amount` de chaîne.
## Modèles de gestionnaire valides pour les fonctions TypeScript
[Nous vous recommandons d'utiliser [async/await](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-async-await.html) pour déclarer le gestionnaire de fonctions au lieu d'utiliser des rappels.](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-a-callback-function.html) Async/await est un moyen concis et lisible d'écrire du code asynchrone, sans avoir besoin de rappels imbriqués ou de promesses enchaînées. Avec async/await, vous pouvez écrire du code qui se lit comme du code synchrone, tout en étant asynchrone et non bloquant.
Les exemples de cette section utilisent le type `S3Event`. Cependant, vous pouvez utiliser n'importe quel autre type d' AWS événement dans le package [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) ou définir votre propre type d'événement. Pour utiliser des types provenant de @types/aws-lambda :
1. Ajoutez le package @types/aws-lambda en tant que dépendance de développement :
```
npm install -D @types/aws-lambda
```
1. Importez les types dont vous avez besoin, comme `Context`, `S3Event` ou `Callback`.
### gestionnaires de fonctions asynchrones (recommandé)
Le mot-clé `async` marque une fonction comme étant asynchrone, et le mot-clé `await` met en pause l’exécution de la fonction jusqu’à ce qu’une `Promise` soit résolue. Le gestionnaire accepte les arguments suivants :
+ `event` : contient les données d’entrée transmises à votre fonction.
+ `context` : contient des informations sur l’invocation, la fonction et l’environnement d’exécution. Pour de plus amples informations, veuillez consulter [Utilisation de l'objet de contexte Lambda pour récupérer les informations relatives aux fonctions TypeScript](typescript-context.md).
Voici les signatures valides pour le async/await modèle :
```
export const handler = async (event: S3Event): Promise => { };
```
```
export const handler = async (event: S3Event, context: Context): Promise => { };
```
**Note**
Lorsque vous traitez des tableaux d’éléments de manière asynchrone, assurez-vous d’utiliser await avec `Promise.all` pour vous assurer que toutes les opérations sont terminées. Des méthodes comme `forEach` n’attendent pas la fin des rappels asynchrones. Pour plus d’informations, consultez [Array.prototype.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) dans la documentation Mozilla.
### Gestionnaires de fonctions synchrones
Lorsque votre fonction n'exécute aucune tâche asynchrone, vous pouvez utiliser un gestionnaire de fonctions synchrones en utilisant l'une des signatures de fonction suivantes :
```
export const handler = (event: S3Event): void => { };
```
```
export const handler = (event: S3Event, context: Context): void => { };
```
### Gestionnaires de fonctions de diffusion des réponses
Lambda prend en charge le streaming des réponses avec Node.js. Les gestionnaires de fonctions de streaming de réponses utilisent le décorateur AWSLambda.streamifyResponse () et prennent 3 paramètres : event, responseStream et context. La signature de la fonction est la suivante :
```
export const handler = awslambda.streamifyResponse(async (event: APIGatewayProxyEvent, responseStream: NodeJS.WritableStream, context: Context) => { });
```
Pour plus d'informations, consultez Streaming de réponses pour les fonctions Lambda.
### Gestionnaires de fonctions basés sur le rappel
**Note**
Les gestionnaires de fonctions basés sur le rappel ne sont pris en charge que jusqu'à Node.js 22. À partir de Node.js 24, les tâches asynchrones doivent être implémentées à l'aide de gestionnaires de fonctions asynchrones.
Les gestionnaires de fonctions basés sur le rappel peuvent utiliser les arguments d'événement, de contexte et de rappel. L’argument de rappel attend une `Error` et une réponse, qui doit être sérialisable en JSON.
Voici la signature valide pour le modèle de gestionnaire de rappel :
```
export const handler = (event: S3Event, context: Context, callback: Callback): void => { };
```
La fonction continue à s’exécuter jusqu’à ce que la [boucle d’événement](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/) soit vide ou que la fonction s’arrête. La réponse n’est pas envoyée à l’appelant tant que toutes les tâches d’événement de boucle ne sont pas terminées. Si la fonction expire, une erreur est renvoyée à la place. Vous pouvez configurer le moteur d'exécution pour envoyer la réponse immédiatement en définissant [le contexte. callbackWaitsForEmptyEventLoop](typescript-context.md)à faux.
**Example TypeScript fonction avec rappel**
L’exemple suivant utilise `APIGatewayProxyCallback`, un type de rappel spécialisé spécifique aux intégrations API Gateway. La plupart des sources d' AWS événements utilisent le `Callback` type générique indiqué dans les signatures ci-dessus.
```
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',
}),
});
};
```
## Utilisation du SDK pour la JavaScript version 3 dans votre gestionnaire
Vous utiliserez souvent les fonctions Lambda pour interagir avec d'autres AWS ressources ou pour les mettre à jour. Le moyen le plus simple d’interagir avec ces ressources est d’utiliser AWS SDK pour JavaScript. Tous les environnements d'exécution Lambda Node.js pris en charge incluent le [SDK pour la version 3. JavaScript ](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/) Toutefois, nous vous recommandons vivement d'inclure les clients AWS SDK dont vous avez besoin dans votre package de déploiement. Cela permet d’optimiser la [rétrocompatibilité](runtimes-update.md#runtime-update-compatibility) lors des futures mises à jour de l’environnement d’exécution Lambda.
Pour ajouter des dépendances au SDK à votre fonction, utilisez la commande `npm install` correspondant aux clients SDK spécifiques dont vous avez besoin. Dans l’exemple de code, nous avons utilisé le [client Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/). Ajoutez cette dépendance en exécutant la commande suivante dans le répertoire qui contient votre fichier `package.json` :
```
npm install @aws-sdk/client-s3
```
Dans le code de fonction, importez le client et les commandes dont vous avez besoin, comme le montre l’exemple de fonction :
```
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
```
Initialisez ensuite un [client Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/) :
```
const s3Client = new S3Client();
```
Dans cet exemple, nous avons initialisé notre client Amazon S3 en dehors de la fonction de gestionnaire principale pour éviter d’avoir à l’initialiser à chaque fois que nous invoquons notre fonction. Après avoir initialisé votre client SDK, vous pouvez l'utiliser pour effectuer des appels d'API pour ce AWS service. L'exemple de code appelle l'action d'[PutObject](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/PutObjectCommand/)API Amazon S3 comme suit :
```
const command = new PutObjectCommand({
Bucket: bucketName,
Key: key,
Body: receiptContent
});
```
## Accès aux variables d’environnement
Dans le code de votre gestionnaire, vous pouvez référencer n’importe quelle [variable d’environnement](configuration-envvars.md) à l’aide de `process.env`. Dans cet exemple, nous référençons la variable d’environnement `RECEIPT_BUCKET` définie à l’aide des lignes de code suivantes :
```
// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
throw new Error('RECEIPT_BUCKET environment variable is not set');
}
```
## Utilisation de l'état global
Lambda exécute votre code statique pendant la [phase d’initialisation](lambda-runtime-environment.md#runtimes-lifecycle-ib) avant d’invoquer votre fonction pour la première fois. Les ressources créées pendant l’initialisation restent en mémoire entre les invocations, ce qui vous évite d’avoir à les créer chaque fois que vous invoquez votre fonction.
Dans l’exemple de code, le code d’initialisation du client S3 se trouve en dehors du gestionnaire. L’exécution initialise le client avant que la fonction n’exécute son premier événement, et le client reste disponible pour être réutilisé pendant toutes les invocations.
## Meilleures pratiques en matière de code pour les fonctions TypeScript Lambda
Suivez ces instructions pour créer des fonctions Lambda :
+ **Séparez le gestionnaire Lambda de votre logique principale.** Cela vous permet de créer une fonction testable plus unitaire.
+ **Contrôlez les dépendances du package de déploiement de vos fonctions. ** L'environnement AWS Lambda d'exécution contient un certain nombre de bibliothèques. Pour les environnements d'exécution Node.js et Python, ceux-ci incluent le AWS SDKs. Pour activer le dernier ensemble de mises à jour des fonctionnalités et de la sécurité, Lambda met régulièrement à jour ces bibliothèques. Ces mises à jour peuvent introduire de subtiles modifications dans le comportement de votre fonction Lambda. Pour disposer du contrôle total des dépendances que votre fonction utilise, empaquetez toutes vos dépendances avec votre package de déploiement.
+ **Réduisez la complexité de vos dépendances.** Privilégiez les infrastructures plus simples qui se chargent rapidement au démarrage de l’[environnement d’exécution](lambda-runtime-environment.md).
+ **Réduisez la taille de votre package de déploiement selon ses besoins d’exécution. ** Cela contribue à réduire le temps nécessaire au téléchargement et à la décompression de votre package de déploiement avant l'invocation.
**Tirez parti de la réutilisation de l’environnement d’exécution pour améliorer les performances de votre fonction**. Initialisez les clients SDK et les connexions à la base de données en dehors du gestionnaire de fonctions et mettez en cache les actifs statiques localement dans le répertoire `/tmp`. Les invocations ultérieures traitées par la même instance de votre fonction peuvent réutiliser ces ressources. Cela permet d’économiser des coûts, tout en réduisant le temps d’exécution de la fonction.
Pour éviter des éventuelles fuites de données entre les invocations, n’utilisez pas l’environnement d’exécution pour stocker des données utilisateur, des événements ou d’autres informations ayant un impact sur la sécurité. Si votre fonction repose sur un état réversible qui ne peut pas être stocké en mémoire dans le gestionnaire, envisagez de créer une fonction distincte ou des versions distinctes d’une fonction pour chaque utilisateur.
**Utilisez une directive keep-alive pour maintenir les connexions persistantes.** Lambda purge les connexions inactives au fil du temps. Si vous tentez de réutiliser une connexion inactive lorsque vous invoquez une fonction, cela entraîne une erreur de connexion. Pour maintenir votre connexion persistante, utilisez la directive Keep-alive associée à votre environnement d’exécution. Pour obtenir un exemple, consultez [Réutilisation des connexions avec Keep-Alive dans Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-reusing-connections.html).
**Utilisez des [variables d’environnement](configuration-envvars.md) pour transmettre des paramètres opérationnels à votre fonction.** Par exemple, si vous écrivez dans un compartiment Amazon S3 au lieu de coder en dur le nom du compartiment dans lequel vous écrivez, configurez le nom du compartiment comme variable d’environnement.
**Évitez d’utiliser des invocations récursives** dans votre fonction Lambda, lorsque la fonction s’invoque elle-même ou démarre un processus susceptible de l’invoquer à nouveau. Cela peut entraîner un volume involontaire d’invocations de fonction et des coûts accrus. Si vous constatez un volume involontaire d’invocations, définissez immédiatement la simultanéité réservée à la fonction sur `0` afin de limiter toutes les invocations de la fonction, pendant que vous mettez à jour le code.
**N'utilisez pas de code non documenté ni public APIs dans votre code** de fonction Lambda. Pour les AWS Lambda environnements d'exécution gérés, Lambda applique régulièrement des mises à jour de sécurité et fonctionnelles aux applications internes de Lambda. APIs Ces mises à jour internes de l'API peuvent être rétroincompatibles, ce qui peut entraîner des conséquences imprévues, telles que des échecs d'invocation si votre fonction dépend de ces mises à jour non publiques. APIs Consultez [la référence de l'API](https://docs.aws.amazon.com/lambda/latest/api/welcome.html) pour obtenir une liste des API accessibles au public APIs.
**Écriture du code idempotent.** L’écriture de code idempotent pour vos fonctions garantit ne gestion identique des événements dupliqués. Votre code doit valider correctement les événements et gérer correctement les événements dupliqués. Pour de plus amples informations, veuillez consulter[Comment faire en sorte que ma fonction Lambda soit idempotente ?](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-function-idempotent/).
# Déployez TypeScript du code transpilé dans Lambda avec des archives de fichiers .zip
Avant de pouvoir déployer TypeScript du code sur AWS Lambda, vous devez le transpiler dans JavaScript. Cette page explique trois méthodes pour créer et déployer TypeScript du code sur Lambda avec des archives de fichiers .zip :
+ [En utilisant AWS Serverless Application Model (AWS SAM)](#aws-sam-ts)
+ [À l'aide du AWS Cloud Development Kit (AWS CDK)](#aws-cdk-ts)
+ [Utilisation de la AWS Command Line Interface (AWS CLI) et d'esbuild](#aws-cli-ts)
AWS SAM et AWS CDK simplifiez la création et le déploiement TypeScript des fonctions. La [spécification du AWS SAM modèle](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html) fournit une syntaxe simple et claire pour décrire les fonctions, les autorisations APIs, les configurations et les événements Lambda qui constituent votre application sans serveur. Le [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/home.html) vous permet de créer des applications fiables, évolutives et rentables dans le cloud, avec la puissance expressive considérable d’un langage de programmation. AWS CDK Il est destiné aux AWS utilisateurs modérément à très expérimentés. Le AWS CDK et le AWS SAM utilisent esbuild pour transpiler le TypeScript code dans. JavaScript
## Utilisation AWS SAM pour déployer TypeScript du code sur Lambda
Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d' TypeScript application Hello World à l'aide du AWS SAM. Cette application implémente un backend API de base. Elle se compose d’un point de terminaison Amazon API Gateway et d’une fonction Lambda. Lorsque vous envoyez une demande GET au point de terminaison API Gateway, la fonction Lambda est invoquée. La fonction renvoie un message `hello world`.
**Note**
AWS SAM utilise esbuild pour créer des fonctions Lambda Node.js à TypeScript partir du code. le support d'esbuild est actuellement en version préliminaire publique. Au cours de la version préliminaire publique, la prise en charge d’esbuild peut faire l’objet de modifications incompatibles.
**Conditions préalables**
Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI version 1.75 ou ultérieure](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+ Node.js
**Déployer un exemple d' AWS SAM application**
1. Initialisez l'application à l'aide du TypeScript modèle Hello World.
```
sam init --app-template hello-world-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. (Facultatif) L'exemple d'application inclut des configurations pour les outils couramment utilisés, tels que le [ESLlint](https://eslint.org/)linting de code et [Jest pour les tests](https://jestjs.io/) unitaires. Pour exécuter des commandes de test et de validation :
```
cd sam-app/hello-world
npm install
npm run lint
npm run test
```
1. Créez l’application.
```
cd sam-app
sam build
```
1. Déployez l’application.
```
sam deploy --guided
```
1. Suivez les invites à l’écran. Répondez avec `Enter` pour accepter les options par défaut fournies dans l’expérience interactive.
1. La sortie affiche le point de terminaison de l’API REST. Ouvrez le point de terminaison dans un navigateur pour tester la fonction. Vous devriez voir la réponse suivante :
```
{"message":"hello world"}
```
1. Il s’agit d’un point de terminaison d’API public accessible par Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
```
sam delete
```
## Utilisation du AWS CDK pour déployer du TypeScript code sur Lambda
Suivez les étapes ci-dessous pour créer et déployer un exemple d' TypeScript application à l'aide du AWS CDK. Cette application implémente un backend API de base. Elle se compose d’un point de terminaison API Gateway et d’une fonction Lambda. Lorsque vous envoyez une demande GET au point de terminaison API Gateway, la fonction Lambda est invoquée. La fonction renvoie un message `hello world`.
**Conditions préalables**
Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK version 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/)
**Déployer un exemple d' AWS CDK application**
1. Créez un répertoire de projets pour votre nouvelle application.
```
mkdir hello-world
cd hello-world
```
1. Initialisez l’application.
```
cdk init app --language typescript
```
1. Ajoutez le pack [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) en tant que dépendance de développement. Ce package contient les définitions de type pour Lambda.
```
npm install -D @types/aws-lambda
```
1. Ouvrez le répertoire **lib**. Vous devriez voir un fichier appelé **hello-world-stack.ts.** Créez deux nouveaux fichiers dans ce répertoire : **hello-world.function.ts** et **hello-world.ts**.
1. Ouvrez **hello-world.function.ts** et ajoutez le code suivant au fichier. Il s’agit du code de la fonction Lambda.
**Note**
L'instruction `import` importe les définitions de type depuis [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Elle n’importe pas le package NPM `aws-lambda`, qui est un outil tiers indépendant. Pour plus d'informations, consultez [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) dans le référentiel. DefinitelyTyped 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. Ouvrez **hello-world.ts** et ajoutez le code suivant au fichier. Il contient la [NodejsFunction construction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), qui crée la fonction Lambda, et la [LambdaRestApi construction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), qui crée l'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,
});
}
}
```
Le composant `NodejsFunction` suppose les éléments suivants par défaut :
+ Votre gestionnaire de fonctions se nomme `handler`.
+ Le fichier .ts qui contient le code de fonction (**hello-world.function.ts**) se trouve dans le même répertoire que le fichier .ts qui contient le composant (**hello-world.ts**). Le composant utilise l’ID du composant (« hello-world ») et le nom du fichier du gestionnaire Lambda (« fonction ») pour trouver le code de la fonction. Par exemple, si le code de votre fonction se trouve dans un fichier nommé **hello-world.my-fonction.ts**, le fichier **hello-world.ts** doit référencer le code de la fonction comme suit :
```
const helloFunction = new NodejsFunction(this, 'my-function');
```
Vous pouvez modifier ce comportement et configurer d’autres paramètres esbuild. Pour plus d'informations, consultez [Configuration d'esbuild](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html#configuring-esbuild) dans la référence de l' AWS CDK API.
1. Ouvrez **hello-world-stack.ts.** C’est le code qui définit votre [pile de AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Remplacez le code par ce qui suit :
```
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. à partir du répertoire `hello-world` contenant votre fichier `cdk.json`, déployez votre application.
```
cdk deploy
```
1. AWS CDK Construit et empaquète la fonction Lambda à l'aide d'esbuild, puis déploie la fonction dans le moteur d'exécution Lambda. La sortie affiche le point de terminaison de l’API REST. Ouvrez le point de terminaison dans un navigateur pour tester la fonction. Vous devriez voir la réponse suivante :
```
{"message":"hello world"}
```
Il s’agit d’un point de terminaison d’API public accessible par Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
## Utilisation de AWS CLI et esbuild pour déployer TypeScript du code sur Lambda
L'exemple suivant montre comment transpiler et déployer TypeScript du code sur Lambda à l'aide d'esbuild et de. esbuild produit JavaScript un fichier avec toutes AWS CLI les dépendances. Il s’agit du seul fichier que vous devez ajouter à l’archive .zip.
**Conditions préalables**
Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ Node.js
+ Un [rôle d’exécution](lambda-intro-execution-role.md) pour votre fonction Lambda
+ Pour les utilisateurs de Windows, un utilitaire de fichier zip tel que [7zip](https://www.7-zip.org/download.html).
**Déployez un exemple de fonction**
1. Sur votre machine locale, créez un répertoire de projets pour votre nouvelle fonction.
1. Créez un nouveau projet Node.js avec npm ou un gestionnaire de packs de votre choix.
```
npm init
```
1. Ajoutez les packs [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) et [esbuild](https://esbuild.github.io/) en tant que dépendances de développement. Le package `@types/aws-lambda` contient les définitions de type pour Lambda.
```
npm install -D @types/aws-lambda esbuild
```
1. Créez un nouveau fichier nommé **index.ts**. Ajoutez le code suivant au nouveau fichier. Il s’agit du code de la fonction Lambda. La fonction renvoie un message `hello world`. La fonction ne crée aucune ressource API Gateway.
**Note**
L'instruction `import` importe les définitions de type depuis [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Elle n’importe pas le package NPM `aws-lambda`, qui est un outil tiers indépendant. Pour plus d'informations, consultez [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) dans le référentiel. DefinitelyTyped 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. Ajoutez un script de génération au fichier **package.json**. Ceci permet de configurer esbuild pour créer automatiquement le pack de déploiement .zip. Pour plus d’informations, consultez [Scripts de génération](https://esbuild.github.io/getting-started/#build-scripts) dans la documentation d’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 ]
Dans cet exemple, la commande `"postbuild"` utilise l'utilitaire [7zip](https://www.7-zip.org/download.html) pour créer votre fichier .zip. Utilisez votre propre utilitaire Windows zip préféré et modifiez la commande si nécessaire.
```
"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. Créez le pack.
```
npm run build
```
1. Créez une fonction Lambda à l’aide du pack de déploiement .zip. Remplacez le texte surligné par l’Amazon Resource Name (ARN) de votre [rôle d’exécution](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. [Exécutez un événement de test](testing-functions.md) pour confirmer que la fonction renvoie la réponse suivante. Si vous souhaitez invoquez cette fonction à l’aide d’API Gateway, [créez et configurez l’API REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-create-api.html).
```
{
"statusCode": 200,
"body": "{\"message\":\"hello world\"}"
}
```
# Déployez TypeScript du code transpilé dans Lambda avec des images de conteneur
Vous pouvez déployer votre TypeScript code sur une AWS Lambda fonction sous la forme d'une [image de conteneur](images-create.md) Node.js. AWS fournit des [images de base](nodejs-image.md#nodejs-image-base) pour Node.js afin de vous aider à créer l'image du conteneur. Ces images de base sont préchargées avec un environnement d'exécution du langage et d'autres composants nécessaires pour exécuter l'image sur Lambda. AWS fournit un Dockerfile pour chacune des images de base afin de vous aider à créer votre image de conteneur.
Si vous utilisez une image de base de communauté ou d’entreprise privée, vous devez y [ajouter un client de l’environnement d’exécution de Node.js (RIC)](nodejs-image.md#nodejs-image-clients) pour la rendre compatible avec Lambda.
Lambda fournit un émulateur d’interface d’exécution pour les tests locaux. Les images AWS de base de Node.js incluent l'émulateur d'interface d'exécution. Si vous utilisez une autre image de base, telle qu’une image Alpine Linux ou Debian, vous pouvez [intégrer l’émulateur dans votre image](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#build-rie-into-your-base-image) ou l’[installer sur votre ordinateur local](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#test-an-image-without-adding-rie-to-the-image).
## Utilisation d'une image de base Node.js pour créer et empaqueter le code de TypeScript fonction
### Conditions préalables
Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [Docker](https://docs.docker.com/get-docker) (version minimale 25.0.0)
+ Le [plug-in buildx](https://github.com/docker/buildx/blob/master/README.md) Docker.
+ Node.js 22.x
### Création d’une image à partir d’une image de base
**Pour créer une image à partir d'une image de AWS base pour Lambda**
1. Sur votre machine locale, créez un répertoire de projets pour votre nouvelle fonction.
1. Créez un nouveau projet Node.js avec `npm` ou un gestionnaire de packs de votre choix.
```
npm init
```
1. Ajoutez les packs [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) et [esbuild](https://esbuild.github.io/) en tant que dépendances de développement. Le package `@types/aws-lambda` contient les définitions de type pour Lambda.
```
npm install -D @types/aws-lambda esbuild
```
1. Ajoutez un [script de création](https://esbuild.github.io/getting-started/#build-scripts) au fichier `package.json`.
```
"scripts": {
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js"
}
```
1. Créez un nouveau fichier appelé `index.ts`. Ajoutez l’exemple de code suivant au nouveau fichier. Il s’agit du code de la fonction Lambda. La fonction renvoie un message `hello world`.
**Note**
L’instruction `import` importe les définitions de type depuis [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Elle n’importe pas le package NPM `aws-lambda`, qui est un outil tiers indépendant. Pour plus d'informations, consultez [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) dans le référentiel. DefinitelyTyped 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. Créez un nouveau Dockerfile avec la configuration suivante :
+ Définissez la propriété `FROM` sur l’URI de l’image de base.
+ Définissez l’argument `CMD` pour spécifier le gestionnaire de la fonction Lambda.
L’exemple de fichier Docker suivant utilise une génération en plusieurs étapes. La première étape consiste à transspirer le TypeScript code en. JavaScript La deuxième étape produit une image de conteneur contenant uniquement des JavaScript fichiers et des dépendances de production.
Notez que l’exemple de Dockerfile n’inclut pas d’[instruction USER](https://docs.docker.com/reference/dockerfile/#user). Lorsque vous déployez une image de conteneur sur Lambda, Lambda définit automatiquement un utilisateur Linux par défaut disposant d’autorisations de moindre privilège. Ceci est différent du comportement standard de Docker qui est défini par défaut par l’utilisateur `root` lorsqu’aucune instruction `USER` n’est fournie.
**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. Générez l’image Docker à l’aide de la commande [docker build](https://docs.docker.com/engine/reference/commandline/build/). L’exemple suivant nomme l’image `docker-image` et lui donne la [balise](https://docs.docker.com/engine/reference/commandline/build/#tag) `test`. Pour rendre votre image compatible avec Lambda, vous devez utiliser l’option `--provenance=false`.
```
docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test .
```
**Note**
La commande spécifie l’option `--platform linux/amd64` pour garantir la compatibilité de votre conteneur avec l’environnement d’exécution Lambda, quelle que soit l’architecture de votre machine de génération. Si vous avez l'intention de créer une fonction Lambda à l'aide de l'architecture du jeu ARM64 d'instructions, veillez à modifier la commande pour utiliser l'`--platform linux/arm64`option à la place.
### (Facultatif) Testez l'image localement
1. Démarrez votre image Docker à l’aide de la commande **docker run**. Dans cet exemple, `docker-image` est le nom de l’image et `test` est la balise.
```
docker run --platform linux/amd64 -p 9000:8080 docker-image:test
```
Cette commande exécute l’image en tant que conteneur et crée un point de terminaison local à `localhost:9000/2015-03-31/functions/function/invocations`.
**Note**
Si vous avez créé l'image Docker pour l'architecture du jeu ARM64 d'instructions, veillez à utiliser l'`--platform linux/arm64`option au lieu de`--platform linux/amd64`.
1. À partir d’une nouvelle fenêtre de terminal, publiez un événement au point de terminaison local.
------
#### [ Linux/macOS ]
Sous Linux et macOS, exécutez la commande `curl` suivante :
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
```
Cette commande invoque la fonction avec un événement vide et renvoie une réponse. Si vous utilisez votre propre code de fonction plutôt que l’exemple de code de fonction, vous pouvez invoquer la fonction avec une charge utile JSON. Exemple :
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'
```
------
#### [ PowerShell ]
Dans PowerShell, exécutez la `Invoke-WebRequest` commande suivante :
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json"
```
Cette commande invoque la fonction avec un événement vide et renvoie une réponse. Si vous utilisez votre propre code de fonction plutôt que l’exemple de code de fonction, vous pouvez invoquer la fonction avec une charge utile JSON. Exemple :
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json"
```
------
1. Obtenez l’ID du conteneur.
```
docker ps
```
1. Utilisez la commande [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) pour arrêter le conteneur. Dans cette commande, remplacez `3766c4ab331c` par l’ID du conteneur de l’étape précédente.
```
docker kill 3766c4ab331c
```
### Déploiement de l’image
**Pour charger l’image sur Amazon RIE et créer la fonction Lambda**
1. Exécutez la [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html)commande pour authentifier la CLI Docker auprès de votre registre Amazon ECR.
+ Définissez la `--region` valeur à l' Région AWS endroit où vous souhaitez créer le référentiel Amazon ECR.
+ `111122223333`Remplacez-le par votre Compte AWS identifiant.
```
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com
```
1. Créez un référentiel dans Amazon ECR à l’aide de la commande [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
```
**Note**
Le référentiel Amazon ECR doit être Région AWS identique à la fonction Lambda.
En cas de succès, vous obtenez une réponse comme celle-ci :
```
{
"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. Copiez le `repositoryUri` à partir de la sortie de l’étape précédente.
1. Exécutez la commande [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) pour étiqueter votre image locale dans votre référentiel Amazon ECR en tant que dernière version. Dans cette commande :
+ `docker-image:test` est le nom et la [balise](https://docs.docker.com/engine/reference/commandline/build/#tag) de votre image Docker. Il s’agit du nom et de la balise de l’image que vous avez spécifiés dans la commande `docker build`.
+ Remplacez `` par l’`repositoryUri` que vous avez copié. Assurez-vous d’inclure `:latest` à la fin de l’URI.
```
docker tag docker-image:test :latest
```
Exemple :
```
docker tag docker-image:test 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. Exécutez la commande [docker push](https://docs.docker.com/engine/reference/commandline/push/) pour déployer votre image locale dans le référentiel Amazon ECR. Assurez-vous d’inclure `:latest` à la fin de l’URI du référentiel.
```
docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. [Créez un rôle d’exécution](lambda-intro-execution-role.md#permissions-executionrole-api) pour la fonction, si vous n’en avez pas déjà un. Vous aurez besoin de l’Amazon Resource Name (ARN) du rôle à l’étape suivante.
1. Créez la fonction Lambda. Pour `ImageUri`, indiquez l’URI du référentiel mentionné précédemment. Assurez-vous d’inclure `:latest` à la fin de l’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
```
**Note**
Vous pouvez créer une fonction en utilisant une image d'un autre AWS compte, à condition que l'image se trouve dans la même région que la fonction Lambda. Pour de plus amples informations, veuillez consulter [Autorisations entre comptes Amazon ECR](images-create.md#configuration-images-xaccount-permissions).
1. Invoquer la fonction.
```
aws lambda invoke --function-name hello-world response.json
```
Vous devriez obtenir une réponse comme celle-ci :
```
{
"ExecutedVersion": "$LATEST",
"StatusCode": 200
}
```
1. Pour voir la sortie de la fonction, consultez le fichier `response.json`.
Pour mettre à jour le code de fonction, vous devez créer à nouveau l'image, télécharger la nouvelle image dans le référentiel Amazon ECR, puis utiliser la [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html)commande pour déployer l'image sur la fonction Lambda.
Lambda résout l’étiquette d’image en hachage d’image spécifique. Cela signifie que si vous pointez la balise d’image qui a été utilisée pour déployer la fonction vers une nouvelle image dans Amazon ECR, Lambda ne met pas automatiquement à jour la fonction pour utiliser la nouvelle image.
Pour déployer la nouvelle image sur la même fonction Lambda, vous devez utiliser la [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html)commande, même si la balise d'image dans Amazon ECR reste la même. Dans l’exemple suivant, l’option `--publish` crée une version de la fonction à l’aide de l’image du conteneur mise à jour.
```
aws lambda update-function-code \
--function-name hello-world \
--image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \
--publish
```
# Utilisation de l'objet de contexte Lambda pour récupérer les informations relatives aux fonctions TypeScript
Lorsque Lambda exécute votre fonction, il transmet un objet contexte au [gestionnaire](typescript-handler.md). Cet objet fournit des méthodes et des propriétés fournissant des informations sur l’invocation, la fonction et l’environnement d’exécution.
Pour activer la vérification de type pour l’objet de contexte, vous devez ajouter le package [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) en tant que dépendance de développement et importer le type `Context`. Pour de plus amples informations, veuillez consulter [Définitions de type pour Lambda](lambda-typescript.md#typescript-type-definitions).
**Méthodes de contexte**
+ `getRemainingTimeInMillis()` – Renvoie le nombre de millisecondes restant avant l’expiration de l’exécution.
**Propriétés du contexte**
+ `functionName` – Nom de la fonction Lambda.
+ `functionVersion` – [Version](configuration-versions.md) de la fonction.
+ `invokedFunctionArn` – Amazon Resource Name (ARN) utilisé pour appeler la fonction. Indique si l’appelant a spécifié un numéro de version ou un alias.
+ `memoryLimitInMB` – Quantité de mémoire allouée à la fonction.
+ `awsRequestId` – Identifiant de la demande d’invocation.
+ `logGroupName` – Groupe de journaux pour la fonction.
+ `logStreamName` – Flux de journal de l’instance de fonction.
+ `identity` – (applications mobiles) Informations sur l’identité Amazon Cognito qui a autorisé la demande.
+ `cognitoIdentityId` – Identité Amazon Cognito authentifiée.
+ `cognitoIdentityPoolId` – Groupe d’identités Amazon Cognito ayant autorisé l’invocation.
+ `clientContext` – (applications mobiles) Contexte client fourni à Lambda par l’application client.
+ `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` – Personnalisez les valeurs qui sont définies par l’application client.
+ `callbackWaitsForEmptyEventLoop`— Par défaut (`true`), lors de l'utilisation d'un gestionnaire de fonctions basé sur le rappel, Lambda attend que la boucle d'événements soit vide après l'exécution du rappel avant de mettre fin à l'appel de la fonction. Définissez cette valeur `false` sur pour envoyer la réponse et mettre fin à l'appel immédiatement après l'exécution du rappel au lieu d'attendre que la boucle d'événements soit vide. Les événements exceptionnels continuent de se dérouler lors de la prochaine invocation. Notez que Lambda prend en charge les gestionnaires de fonctions basés sur le rappel pour les environnements d'exécution de Node.js 22 et antérieurs uniquement.
**Example Fichier index.ts**
Dans l’exemple suivant, la fonction enregistre des informations de contexte et renvoie l’emplacement des journaux.
Avant d’utiliser ce code dans une fonction Lambda, vous devez ajouter le package [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) en tant que dépendance de développement. Ce package contient les définitions de type pour Lambda. Pour de plus amples informations, veuillez consulter [Définitions de type pour 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;
};
```
# Enregistrez et surveillez les fonctions TypeScript Lambda
AWS Lambda surveille automatiquement les fonctions Lambda et envoie des entrées de journal à Amazon. CloudWatch Votre fonction Lambda est fournie avec un groupe de CloudWatch journaux Logs et un flux de journaux pour chaque instance de votre fonction. L’environnement d’exécution Lambda envoie des détails sur chaque invocation et d’autres sorties provenant du code de votre fonction au flux de journaux. Pour plus d'informations sur CloudWatch les journaux, consultez[Envoi automatique des journaux de la fonction Lambda à CloudWatch Logs](monitoring-cloudwatchlogs.md).
Pour générer les journaux à partir de votre code de fonction, vous pouvez utiliser des méthodes sur l’[objet console](https://nodejs.org/docs/latest-v18.x/api/console.html). Pour une journalisation plus détaillée, vous pouvez utiliser n’importe quelle bibliothèque de journalisation qui écrit dans `stdout` ou `stderr`.
**Topics**
+ [Utilisation d’outils et de bibliothèques de journalisation](#typescript-tools-libraries)
+ [Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS SAM pour la journalisation structurée](#typescript-logging-sam)
+ [Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS CDK pour la journalisation structurée](#typescript-logging-cdk)
+ [Affichage des journaux dans la console Lambda](#typescript-logging-console)
+ [Afficher les journaux dans la CloudWatch console](#typescript-logging-cwconsole)
## Utilisation d’outils et de bibliothèques de journalisation
[Powertools for AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/) est une boîte à outils destinée aux développeurs qui permet de mettre en œuvre les meilleures pratiques sans serveur et d'accroître la rapidité des développeurs. L’[utilitaire Logger](https://docs.powertools.aws.dev/lambda/typescript/latest/features/logger/) fournit un enregistreur optimisé pour Lambda qui inclut des informations supplémentaires sur le contexte de fonction pour toutes vos fonctions avec une sortie structurée en JSON. Utilisez cet utilitaire pour effectuer les opérations suivantes :
+ Capturer les champs clés du contexte Lambda, démarrer à froid et structurer la sortie de la journalisation sous forme de JSON
+ Journaliser les événements d’invocation Lambda lorsque cela est demandé (désactivé par défaut)
+ Imprimer tous les journaux uniquement pour un pourcentage d’invocations via l’échantillonnage des journaux (désactivé par défaut)
+ Ajouter des clés supplémentaires au journal structuré à tout moment
+ Utiliser un formateur de journaux personnalisé (Apportez votre propre formateur) pour produire des journaux dans une structure compatible avec le RFC de journalisation de votre organisation
## Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS SAM pour la journalisation structurée
Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d' TypeScript application Hello World avec des modules [Powertools for AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) intégrés à l'aide du AWS SAM. Cette application met en œuvre un backend API de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Elle se compose d’un point de terminaison Amazon API Gateway et d’une fonction Lambda. Lorsque vous envoyez une requête GET au point de terminaison API Gateway, la fonction Lambda appelle, envoie des journaux et des métriques au format métrique intégré à CloudWatch, et envoie des traces à. AWS X-Ray La fonction renvoie un message `hello world`.
**Conditions préalables**
Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :
+ Node.js 20 ou version ultérieure
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI version 1.75 ou ultérieure](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Si vous disposez d'une ancienne version de la AWS SAM CLI, reportez-vous [à la section Mise à niveau de la AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Déployer un exemple d' AWS SAM application**
1. Initialisez l'application à l'aide du TypeScript modèle Hello World.
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. Créez l’application.
```
cd sam-app && sam build
```
1. Déployez l’application.
```
sam deploy --guided
```
1. Suivez les invites à l’écran. Appuyez sur `Enter` pour accepter les options par défaut fournies dans l’expérience interactive.
**Note**
Car l'**autorisation n'a HelloWorldFunction peut-être pas été définie, est-ce que ça va ?** , assurez-vous de participer`y`.
1. Obtenez l’URL de l’application déployée :
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. Invoquez le point de terminaison de l’API :
```
curl
```
En cas de succès, vous obtiendrez cette réponse :
```
{"message":"hello world"}
```
1. Pour obtenir les journaux de la fonction, exécutez [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Pour en savoir plus, consultez [Utilisation des journaux](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) dans le *Guide du développeur AWS Serverless Application Model *.
```
sam logs --stack-name sam-app
```
La sortie du journal se présente comme suit :
```
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. Il s’agit d’un point de terminaison d’API public accessible par Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
```
sam delete
```
### Gestion de la conservation des journaux
Les groupes de journaux ne sont pas supprimés automatiquement quand vous supprimez une fonction. Pour éviter de stocker les journaux indéfiniment, supprimez le groupe de journaux ou configurez une période de conservation après laquelle les journaux CloudWatch sont automatiquement supprimés. Pour configurer la conservation des journaux, ajoutez ce qui suit à votre AWS SAM modèle :
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
# Omitting other properties
LogGroup:
Type: AWS::Logs::LogGroup
Properties:
LogGroupName: !Sub "/aws/lambda/${HelloWorldFunction}"
RetentionInDays: 7
```
## Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS CDK pour la journalisation structurée
Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d' TypeScript application Hello World avec des modules [Powertools for AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) intégrés à l'aide du AWS CDK. Cette application met en œuvre un backend API de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Elle se compose d’un point de terminaison Amazon API Gateway et d’une fonction Lambda. Lorsque vous envoyez une requête GET au point de terminaison API Gateway, la fonction Lambda appelle, envoie des journaux et des métriques au format métrique intégré à CloudWatch, et envoie des traces à. AWS X-Ray La fonction renvoie un message `hello world`.
**Conditions préalables**
Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :
+ Node.js 20 ou version ultérieure
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK version 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM CLI version 1.75 ou ultérieure](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Si vous disposez d'une ancienne version de la AWS SAM CLI, reportez-vous [à la section Mise à niveau de la AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Déployer un exemple d' AWS CDK application**
1. Créez un répertoire de projets pour votre nouvelle application.
```
mkdir hello-world
cd hello-world
```
1. Initialisez l’application.
```
cdk init app --language typescript
```
1. Ajoutez le pack [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) en tant que dépendance de développement.
```
npm install -D @types/aws-lambda
```
1. Installez [l’utilitaire Powertools Logger](https://docs.aws.amazon.com/powertools/typescript/latest/features/logger/) (français non garanti).
```
npm install @aws-lambda-powertools/logger
```
1. Ouvrez le répertoire **lib**. Vous devriez voir un fichier appelé **hello-world-stack.ts.** Créez deux nouveaux fichiers dans ce répertoire : **hello-world.function.ts** et **hello-world.ts**.
1. Ouvrez **hello-world.function.ts** et ajoutez le code suivant au fichier. Il s’agit du code de la fonction 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. Ouvrez **hello-world.ts** et ajoutez le code suivant au fichier. Il contient la [NodejsFunction construction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html) qui crée la fonction Lambda, configure les variables d'environnement pour Powertools et définit la durée de conservation des journaux à une semaine. Il inclut également la [LambdaRestApi construction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html) qui crée l'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. Ouvrez **hello-world-stack.ts.** C’est le code qui définit votre [pile de AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Remplacez le code par ce qui suit :
```
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. Revenez au répertoire du projet.
```
cd hello-world
```
1. Déployez votre application.
```
cdk deploy
```
1. Obtenez l’URL de l’application déployée :
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. Invoquez le point de terminaison de l’API :
```
curl
```
En cas de succès, vous obtiendrez cette réponse :
```
{"message":"hello world"}
```
1. Pour obtenir les journaux de la fonction, exécutez [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Pour en savoir plus, consultez [Utilisation des journaux](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) dans le *Guide du développeur AWS Serverless Application Model *.
```
sam logs --stack-name HelloWorldStack
```
La sortie du journal se présente comme suit :
```
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. Il s’agit d’un point de terminaison d’API public accessible par Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
```
cdk destroy
```
## Affichage des journaux dans la console Lambda
Vous pouvez utiliser la console Lambda pour afficher la sortie du journal après avoir invoqué une fonction Lambda.
Si votre code peut être testé à partir de l’éditeur **Code** intégré, vous trouverez les journaux dans les **résultats d’exécution**. Lorsque vous utilisez la fonctionnalité de test de console pour invoquer une fonction, vous trouverez **Sortie du journal** dans la section **Détails**.
## Afficher les journaux dans la CloudWatch console
Vous pouvez utiliser la CloudWatch console Amazon pour consulter les journaux de toutes les invocations de fonctions Lambda.
**Pour afficher les journaux sur la CloudWatch console**
1. Ouvrez la [page Groupes de journaux](https://console.aws.amazon.com/cloudwatch/home?#logs:) sur la CloudWatch console.
1. Choisissez le groupe de journaux pour votre fonction (***your-function-name*/aws/lambda/**).
1. Choisissez un flux de journaux.
Chaque flux de journal correspond à une [instance de votre fonction](lambda-runtime-environment.md). Un flux de journal apparaît lorsque vous mettez à jour votre fonction Lambda et lorsque des instances supplémentaires sont créées pour gérer les appels simultanés. Pour trouver les journaux d'un appel spécifique, nous vous recommandons d'instrumenter votre fonction avec. AWS X-Ray X-Ray enregistre des détails sur la demande et le flux de journaux dans le suivi.
# TypeScript Code de suivi dans AWS Lambda
Lambda s'intègre pour vous aider AWS X-Ray à suivre, à déboguer et à optimiser les applications Lambda. Vous pouvez utiliser X-Ray pour suivre une demande lorsque celle-ci parcourt les ressources de votre application, qui peuvent inclure des fonctions Lambda et d’autres services AWS .
Pour envoyer des données de traçage à X-Ray, vous pouvez utiliser l’une des trois bibliothèques SDK suivantes :
+ [AWS Distro for OpenTelemetry (ADOT)](https://aws.amazon.com/otel) — Une distribution sécurisée, prête pour la production et AWS prise en charge du SDK (). OpenTelemetry OTel
+ [AWS X-Ray SDK pour Node.js](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html) : SDK permettant de générer et d'envoyer des données de suivi à X-Ray.
+ [Powertools for AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/latest/) — Une boîte à outils pour les développeurs permettant de mettre en œuvre les meilleures pratiques sans serveur et d'accroître la rapidité des développeurs.
Chacune d'entre elles SDKs propose des moyens d'envoyer vos données de télémétrie au service X-Ray. Vous pouvez ensuite utiliser X-Ray pour afficher, filtrer et avoir un aperçu des métriques de performance de votre application, afin d’identifier les problèmes et les occasions d’optimiser votre application.
**Important**
Les outils X-Ray et Powertools pour AWS Lambda SDKs font partie d'une solution d'instrumentation étroitement intégrée proposée par AWS. Les couches ADOT Lambda font partie d’une norme industrielle pour l’instrumentation de traçage qui collecte plus de données en général, mais qui peut ne pas convenir à tous les cas d’utilisation. Vous pouvez implémenter le end-to-end traçage dans X-Ray en utilisant l'une ou l'autre solution. Pour en savoir plus sur le choix entre les deux, consultez [Choosing between the AWS Distro for Open Telemetry and](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing) X-Ray. SDKs
**Topics**
+ [Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS SAM pour le traçage](#typescript-tracing-sam)
+ [Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS CDK pour le traçage](#typescript-tracing-cdk)
+ [Interprétation d’un suivi X-Ray](#typescript-tracing-interpretation)
## Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS SAM pour le traçage
Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d' TypeScript application Hello World avec des modules [Powertools for AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) intégrés à l'aide du AWS SAM. Cette application met en œuvre un backend API de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Elle se compose d’un point de terminaison Amazon API Gateway et d’une fonction Lambda. Lorsque vous envoyez une requête GET au point de terminaison API Gateway, la fonction Lambda appelle, envoie des journaux et des métriques au format métrique intégré à CloudWatch, et envoie des traces à. AWS X-Ray La fonction renvoie un message `hello world`.
**Conditions préalables**
Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :
+ Node.js
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI version 1.75 ou ultérieure](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Si vous disposez d'une ancienne version de la AWS SAM CLI, reportez-vous [à la section Mise à niveau de la AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Déployer un exemple d' AWS SAM application**
1. Initialisez l'application à l'aide du TypeScript modèle Hello World.
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x --no-tracing
```
1. Créez l’application.
```
cd sam-app && sam build
```
1. Déployez l’application.
```
sam deploy --guided
```
1. Suivez les invites à l’écran. Appuyez sur `Enter` pour accepter les options par défaut fournies dans l’expérience interactive.
**Note**
Car l'**autorisation n'a HelloWorldFunction peut-être pas été définie, est-ce que ça va ?** , assurez-vous de participer`y`.
1. Obtenez l’URL de l’application déployée :
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. Invoquez le point de terminaison de l’API :
```
curl
```
En cas de succès, vous obtiendrez cette réponse :
```
{"message":"hello world"}
```
1. Pour obtenir les traces de la fonction, exécutez [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).
```
sam traces
```
La sortie de la trace ressemble à ceci :
```
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. Il s’agit d’un point de terminaison d’API public accessible par Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
```
sam delete
```
X-Ray ne trace pas toutes les requêtes vers votre application. X-Ray applique un algorithme d’échantillonnage pour s’assurer que le suivi est efficace, tout en fournissant un échantillon représentatif de toutes les demandes. Le taux d’échantillonnage est 1 demande par seconde et 5 % de demandes supplémentaires. Vous ne pouvez pas configurer ce taux d’échantillonnage X-Ray pour vos fonctions.
## Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS CDK pour le traçage
Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d' TypeScript application Hello World avec des modules [Powertools for AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) intégrés à l'aide du AWS CDK. Cette application met en œuvre un backend API de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Elle se compose d’un point de terminaison Amazon API Gateway et d’une fonction Lambda. Lorsque vous envoyez une requête GET au point de terminaison API Gateway, la fonction Lambda appelle, envoie des journaux et des métriques au format métrique intégré à CloudWatch, et envoie des traces à. AWS X-Ray La fonction renvoie un message `hello world`.
**Conditions préalables**
Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :
+ Node.js
+ [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK version 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM CLI version 1.75 ou ultérieure](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). Si vous disposez d'une ancienne version de la AWS SAM CLI, reportez-vous [à la section Mise à niveau de la AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade).
**Déployer un exemple d' AWS Cloud Development Kit (AWS CDK) application**
1. Créez un répertoire de projets pour votre nouvelle application.
```
mkdir hello-world
cd hello-world
```
1. Initialisez l’application.
```
cdk init app --language typescript
```
1. Ajoutez le pack [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) en tant que dépendance de développement.
```
npm install -D @types/aws-lambda
```
1. Installez l’[utilitaire Powertools Tracer](https://docs.aws.amazon.com/powertools/typescript/latest/features/tracer/).
```
npm install @aws-lambda-powertools/tracer
```
1. Ouvrez le répertoire **lib**. Vous devriez voir un fichier appelé **hello-world-stack.ts.** Créez deux nouveaux fichiers dans ce répertoire : **hello-world.function.ts** et **hello-world.ts**.
1. Ouvrez **hello-world.function.ts** et ajoutez le code suivant au fichier. Il s’agit du code de la fonction 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. Ouvrez **hello-world.ts** et ajoutez le code suivant au fichier. Il contient la [NodejsFunction construction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html) qui crée la fonction Lambda, configure les variables d'environnement pour Powertools et définit la durée de conservation des journaux à une semaine. Il inclut également la [LambdaRestApi construction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html) qui crée l'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. Ouvrez **hello-world-stack.ts.** C’est le code qui définit votre [pile de AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Remplacez le code par ce qui suit :
```
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. Déployez votre application.
```
cd ..
cdk deploy
```
1. Obtenez l’URL de l’application déployée :
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. Invoquez le point de terminaison de l’API :
```
curl
```
En cas de succès, vous obtiendrez cette réponse :
```
{"message":"hello world"}
```
1. Pour obtenir les traces de la fonction, exécutez [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).
```
sam traces
```
La sortie de la trace ressemble à ceci :
```
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. Il s’agit d’un point de terminaison d’API public accessible par Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
```
cdk destroy
```
## Interprétation d’un suivi X-Ray
Une fois que vous avez configuré le suivi actif, vous pouvez observer des demandes spécifiques via votre application. La [mappe de trace X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-servicemap.html) fournit des informations sur votre application et tous ses composants. L’exemple suivant montre une trace à partir de l’exemple d’application :
![\[\]](http://docs.aws.amazon.com/fr_fr/lambda/latest/dg/images/sample-typescript-servicemap.png)