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 ou Déployez TypeScript du code transpilé dans Lambda avec des images de conteneur.

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 utilisantnpm, créer une AWS SAM application ou créer une AWS CDK application. Pour créer le projet à l'aide de 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 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.

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<string> => {
    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<void> {
    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 :

Pour que cette fonction fonctionne correctement, son rôle d'exécution doit autoriser l's3:PutObjectaction. 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.

Convention de nommage du gestionnaire

Lorsque vous configurez une fonction, la valeur du paramètre Handler est le nom du fichier et le nom de la méthode de gestion exportée, 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.

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<string> => {

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 pour déclarer le gestionnaire de fonctions au lieu d'utiliser des rappels. Async/await is a concise and readable way to write asynchronous code, without the need for nested callbacks or chaining promises. With 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 S3Event type. Cependant, vous pouvez utiliser n'importe quel autre type d' AWS événement dans le package @types /aws-lambda ou définir votre propre type d'événement. Pour utiliser les types de @types/aws-lambda:

Utiliser async/await (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 :

Voici les signatures valides pour le modèle async/await :

Utilisation de callbacks

Les gestionnaires de rappel peuvent utiliser les arguments d'événement, de contexte et de rappel. L'argument de rappel attend une réponse Error et une réponse, qui doit être sérialisable en JSON.

Voici les signatures valides pour le modèle de gestionnaire de rappel :

La fonction continue de s'exécuter jusqu'à ce que la boucle d'événements soit vide ou que la fonction expire. 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à faux.

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 le AWS SDK pour JavaScript. Tous les environnements d'exécution Lambda Node.js pris en charge incluent le SDK pour la version 3. JavaScript 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é lors des futures mises à jour du moteur 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. Ajoutez cette dépendance en exécutant la commande suivante dans le répertoire qui contient votre package.json fichier :

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 :

const s3Client = new S3Client();

Dans cet exemple, nous avons initialisé notre client Amazon S3 en dehors de la fonction de gestion 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'PutObjectAPI 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 en utilisantprocess.env. Dans cet exemple, nous référençons la variable d'RECEIPT_BUCKETenvironnement 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 avant d'appeler votre fonction pour la première fois. Les ressources créées lors de l'initialisation restent en mémoire entre les invocations, ce qui vous évite d'avoir à les créer à chaque fois que vous appelez votre fonction.

Dans l'exemple de code, le code d'initialisation du client S3 se trouve en dehors du gestionnaire. Le moteur d'exécution initialise le client avant que la fonction ne gère son premier événement, et le client reste disponible pour être réutilisé lors de tous les appels.

Bonnes pratiques en matière de code pour les TypeScript fonctions Lambda

Suivez ces directives lors de la création de fonctions Lambda :