Définition du gestionnaire de fonction Lambda dans Go

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 Go, notamment la configuration du projet, les conventions de dénomination et les pratiques exemplaires. Cette page inclut également un exemple de fonction Go 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éployer des fonctions Lambda Go avec des archives de fichiers .zip ou Déployer des fonctions Lambda Go avec des images conteneurs.

Configuration de votre projet de gestionnaire Go

Une fonction Lambda écrite en Go est créée en tant qu'exécutable Go. Vous pouvez initialiser un projet de fonction Lambda Go de la même manière que vous initialisez n’importe quel autre projet Go à l’aide de la commande suivante : go mod init

go mod init example-go

Ici, example-go est le nom du module. Vous pouvez le remplacer par n’importe quelle valeur. Cette commande initialise votre projet et génère le fichier go.mod répertoriant les dépendances de votre projet.

Utilisez la commande go get pour ajouter des dépendances externes à votre projet. Par exemple, pour toutes les fonctions Lambda de Go, vous devez inclure le github. com/aws/aws-lambda-go/lambdapackage, qui implémente le modèle de programmation Lambda pour Go. Installez ce package à l’aide de la commande go get suivante :

go get github.com/aws/aws-lambda-go

Le code de votre fonction doit résider dans un fichier Go. Dans l’exemple suivant, nous nommons ce fichier main.go. Dans ce fichier, vous implémentez la logique de votre fonction de base dans une méthode de gestion, ainsi que dans une fonction main() qui appelle ce gestionnaire.

Exemple de fonction Lambda Go

L’exemple de code de fonction Lambda Go 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.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"os"
	"strings"

	"github.com/aws/aws-lambda-go/lambda"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/s3"
)

type Order struct {
	OrderID string  `json:"order_id"`
	Amount  float64 `json:"amount"`
	Item    string  `json:"item"`
}

var (
	s3Client *s3.Client
)

func init() {
	// Initialize the S3 client outside of the handler, during the init phase
	cfg, err := config.LoadDefaultConfig(context.TODO())
	if err != nil {
		log.Fatalf("unable to load SDK config, %v", err)
	}

	s3Client = s3.NewFromConfig(cfg)
}

func uploadReceiptToS3(ctx context.Context, bucketName, key, receiptContent string) error {
	_, err := s3Client.PutObject(ctx, &s3.PutObjectInput{
		Bucket: &bucketName,
		Key:    &key,
		Body:   strings.NewReader(receiptContent),
	})
	if err != nil {
		log.Printf("Failed to upload receipt to S3: %v", err)
		return err
	}
	return nil
}

func handleRequest(ctx context.Context, event json.RawMessage) error {
	// Parse the input event
	var order Order
	if err := json.Unmarshal(event, &order); err != nil {
		log.Printf("Failed to unmarshal event: %v", err)
		return err
	}

	// Access environment variables
	bucketName := os.Getenv("RECEIPT_BUCKET")
	if bucketName == "" {
		log.Printf("RECEIPT_BUCKET environment variable is not set")
		return fmt.Errorf("missing required environment variable RECEIPT_BUCKET")
	}

	// Create the receipt content and key destination
	receiptContent := fmt.Sprintf("OrderID: %s\nAmount: $%.2f\nItem: %s",
		order.OrderID, order.Amount, order.Item)
	key := "receipts/" + order.OrderID + ".txt"

	// Upload the receipt to S3 using the helper method
	if err := uploadReceiptToS3(ctx, bucketName, key, receiptContent); err != nil {
		return err
	}

	log.Printf("Successfully processed order %s and stored receipt in S3 bucket %s", order.OrderID, bucketName)
	return nil
}

func main() {
	lambda.Start(handleRequest)
}

Ce fichier main.go comprend les sections suivantes :

Pour que cette fonction fonctionne correctement, son rôle d’exécution 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.

Convention de nommage du gestionnaire

Pour les fonctions Lambda dans Go, vous pouvez utiliser n’importe quel nom pour le gestionnaire. Dans cet exemple, le nom de la méthode de traitement est handleRequest. Pour référencer la valeur du gestionnaire dans votre code, vous pouvez utiliser la variable d'environnement _HANDLER.

Pour les fonctions Go qui utilisent l’exécution dans un package de déploiement .zip, le fichier exécutable qui contient le code de votre fonction doit être nommé bootstrap. De plus, le fichier bootstrap doit se trouver à la racine du fichier .zip. Pour les fonctions Go déployées à l’aide d’une image de conteneur, vous pouvez utiliser n’importe quel nom pour le fichier exécutable.

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 Go, vous pouvez définir la forme de l’événement d’entrée attendu sous la forme d’une structure Go. Dans cet exemple, nous définissons une structure pour représenter un Order :

type Order struct {
    OrderID string  `json:"order_id"`
    Amount  float64 `json:"amount"`
    Item    string  `json:"item"`
}

Cette structure correspond à la forme d’entrée attendue. Après avoir défini votre structure, vous pouvez écrire une signature de gestionnaire qui utilise un type JSON générique compatible avec la bibliothèque standard encoding/json. Vous pouvez ensuite le désérialiser dans votre structure à l’aide de la fonction func Unmarshal. Ceci est illustré dans les premières lignes du gestionnaire :

func handleRequest(ctx context.Context, event json.RawMessage) error {
    // Parse the input event
    var order Order
    if err := json.Unmarshal(event, &order); err != nil {
        log.Printf("Failed to unmarshal event: %v", err)
        return err
    ...
}

Après cette désérialisation, vous pouvez accéder aux champs de la variable order. Par exemple, order.OrderID récupère la valeur de "order_id" à partir de l’entrée d’origine.

Accès et utilisation de l’objet de contexte Lambda

L’objet de contexte Lambda contient des informations sur l’invocation, la fonction et l’environnement d’exécution. Dans cet exemple, nous avons déclaré cette variable comme ctx dans la signature du gestionnaire :

func handleRequest(ctx context.Context, event json.RawMessage) error {
    ...
}

L’entrée ctx context.Context est un argument facultatif dans votre gestionnaire de fonctions. Pour plus d’informations sur les signatures de gestionnaire acceptées, consultez Signatures de gestionnaire valides pour les gestionnaires Go.

Si vous appelez d'autres services à l'aide du AWS SDK, l'objet de contexte est requis dans quelques domaines clés. Par exemple, pour initialiser correctement vos clients SDK, vous pouvez charger la configuration du kit SDK  AWS appropriée à l’aide de l’objet de contexte comme suit :

// Load AWS SDK configuration using the default credential provider chain
    cfg, err := config.LoadDefaultConfig(ctx)

Les appels du kit SDK eux-mêmes peuvent nécessiter l’objet de contexte comme entrée. Par exemple, l’appel s3Client.PutObject accepte l’objet de contexte comme premier argument :

// Upload the receipt to S3
    _, err = s3Client.PutObject(ctx, &s3.PutObjectInput{
        ...
    })

En dehors des demandes du AWS SDK, vous pouvez également utiliser l'objet de contexte pour surveiller les fonctions. Pour plus d’informations sur la copie d’objets, consultez Utilisation de l’objet de contexte Lambda pour récupérer les informations de la fonction Go.

Signatures de gestionnaire valides pour les gestionnaires Go

Vous disposez de plusieurs options lorsque vous créez un gestionnaire de fonction Lambda dans Go, mais vous devez respecter les règles suivantes :

Voici la liste des signatures de gestionnaire valides. TIn et TOut représentent des types compatibles avec la bibliothèque encoding/json standard. Pour en savoir plus, reportez-vous à la section func Unmarshal pour savoir comment ces types sont désérialisés.

Utilisation de la AWS SDK pour Go v2 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 la AWS SDK pour Go v2.

Pour ajouter des dépendances au SDK à votre fonction, utilisez la commande go get correspondant aux clients SDK spécifiques dont vous avez besoin. Dans l’exemple de code précédent, nous avons utilisé les bibliothèques config et s3. Ajoutez ces dépendances en exécutant les commandes suivantes dans le répertoire qui contient vos fichiers go.mod et main.go  :

go get github.com/aws/aws-sdk-go-v2/config
go get github.com/aws/aws-sdk-go-v2/service/s3

Importez ensuite les dépendances en conséquence dans le bloc d’importation de votre fonction :

import (
    ...
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

Lorsque vous utilisez le kit SDK dans votre gestionnaire, configurez vos clients avec les bons paramètres. La méthode la plus simple consiste à utiliser la chaîne de fournisseurs d’informations d’identification par défaut. Cet exemple illustre une manière de charger cette configuration :

// Load AWS SDK configuration using the default credential provider chain
    cfg, err := config.LoadDefaultConfig(ctx)
    if err != nil {
        log.Printf("Failed to load AWS SDK config: %v", err)
        return err
    }

Après avoir chargé cette configuration dans la variable cfg, vous pouvez transmettre cette variable aux instanciations du client. L’exemple de code instancie un client Amazon S3 comme suit :

// Create an S3 client
    s3Client := s3.NewFromConfig(cfg)

Dans cet exemple, nous avons initialisé notre client Amazon S3 dans la fonction init() pour éviter d’avoir à l’initialiser à chaque fois que nous invoquons notre fonction. Le problème est que dans la fonction init(), Lambda n’a pas accès à l’objet de contexte. Pour contourner le problème, vous pouvez transmettre un espace réservé, comme context.TODO(), lors de la phase d’initialisation. Plus tard, lorsque vous passez un appel à l’aide du client, transmettez l’objet de contexte complet. Cette solution est également décrite dans Utilisation du contexte dans les initialisations et les appels des clients du AWS SDK.

Après avoir configuré et initialisé votre client SDK, vous pouvez l’utiliser pour interagir avec d’autres services  AWS . L’exemple de code appelle l’API Amazon S3 PutObject comme suit :

_, err = s3Client.PutObject(ctx, &s3.PutObjectInput{
    Bucket: &bucketName,
    Key:    &key,
    Body:   strings.NewReader(receiptContent),
})

Accès aux variables d’environnement

Dans le code de votre gestionnaire, vous pouvez référencer n’importe quelle variable d’environnement à l’aide de la méthode os.Getenv(). Dans cet exemple, nous référençons la variable d’environnement RECEIPT_BUCKET définie à l’aide de la ligne de code suivante :

// Access environment variables
    bucketName := os.Getenv("RECEIPT_BUCKET")
    if bucketName == "" {
        log.Printf("RECEIPT_BUCKET environment variable is not set")
        return fmt.Errorf("missing required environment variable RECEIPT_BUCKET")
    }

Utilisation de l'état global

Pour éviter de créer des ressources à chaque fois que vous invoquez votre fonction, vous pouvez déclarer et modifier les variables globales en dehors du code de votre gestionnaire de fonction Lambda. Vous définissez ces variables globales dans un bloc ou une instruction var. De plus, votre gestionnaire peut déclarer une fonction init() qui est exécutée pendant la phase d’initialisation. La init méthode se comporte de la même manière AWS Lambda que dans les programmes Go standard.

Pratiques exemplaires en matière de code pour les fonctions Lambda Go

Respectez les directives de la liste suivante pour utiliser les pratiques exemplaires de codage lors de la création de vos fonctions Lambda :