Table des matières

• Quels sont les prérequis ?
• Pourquoi devez-vous utiliser Docker au lieu du déploiement Zip ?
• Comment configurer les dépendances Maven ?
• Comment écrire le gestionnaire Lambda ?
• Comment configurer le modèle SAM ?
• Comment créer le fichier Dockerfile ?
• Comment créer et déployer la fonction Lambda ?
• Quelles sont les prochaines étapes ?

Quels sont les prérequis ? {#prerequisites}

Avant de commencer, confirmez que les outils suivants sont installés sur la machine de développement. Chaque outil joue un rôle spécifique dans le pipeline de construction et de déploiement.

• IntelliJ IDEA — l'IDE utilisé dans ce guide. Téléchargez-le depuis jetbrains.com/idea.
• AWS Toolkit for JetBrains — fournit l'assistant de projet SAM et les configurations de lancement Lambda dans IntelliJ. Les instructions de configuration se trouvent sur la page de documentation AWS Toolkit for JetBrains.
• AWS SAM CLI — l'outil en ligne de commande qui crée les images Docker et déploie les fonctions Lambda. Installez-le en suivant le guide d'installation SAM CLI.
• Docker Desktop — nécessaire car la fonction Lambda est emballée sous forme d'image de conteneur, et non d'archive Zip. Téléchargez Docker Community Edition.

Pour le test d'invocation local avant de déployer sur AWS, installez également :

• Java 8 JDK — disponible sur la page de téléchargement d'Oracle JDK 8.
• Apache Maven — suivez le guide d'installation de Maven.

Une fois tous les outils en place, ouvrez IntelliJ IDEA et créez un nouveau projet via Fichier → Nouveau → Projet. Dans l'assistant de projet, sélectionnez le modèle AWS Lambda et choisissez les options suivantes :

• Type de package : Image
• Runtime : java8 ou java11
• Modèle SAM : Maven

Pourquoi devez-vous utiliser Docker au lieu du déploiement Zip ? {#why-docker}

AWS Lambda prend en charge deux types de paquets de déploiement : les archives Zip et les images de conteneur. Le déploiement par Zip fonctionne bien pour les fonctions Java légères car l'environnement d'exécution est entièrement géré par AWS. IronPDF, cependant, est fourni avec un binaire natif — un moteur de rendu PDF basé sur Chrome — qui doit être extrait et exécuté au moment de l'exécution. L'environnement d'exécution Lambda pour les déploiements ZIP limite les écritures sur le système de fichiers à /tmp, et les restrictions de la couche de paquets ZIP empêchent l'extraction de binaires natifs volumineux.

Le déploiement d'image de conteneur supprime ces restrictions. Lorsque vous définissez votre propre image Docker, vous contrôlez le système d'exploitation de base, les paquets système installés et la disposition du répertoire. Le moteur de rendu d'IronPDF peut être extrait vers /tmp au démarrage, les bibliothèques système requises peuvent être préinstallées dans l'image, et la limite de taille du conteneur (10 Go) est suffisamment grande pour accueillir le moteur complet.

La conséquence pratique est simple : définissez PackageType: Image dans template.yaml et compilez en utilisant une image de base compatible avec Docker. Le SAM CLI s'occupe du reste.

Comment configurer les dépendances Maven ? {#Maven-dependencies}

Le fichier pom.xml nécessite trois catégories de dépendances supplémentaires en plus du SDK Lambda standard : la bibliothèque Java IronPDF, le moteur de rendu IronPDF Linux x64 et le transport gRPC utilisé en interne par le moteur IronPDF.

Ouvrez pom.xml et ajoutez les dépendances suivantes à l'intérieur de <dependencies> :

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.perfmark</groupId>
    <artifactId>perfmark-api</artifactId>
    <version>0.26.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-okhttp</artifactId>
    <version>1.50.2</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty-shaded</artifactId>
    <version>1.50.2</version>
</dependency>

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>2024.9.1</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>io.perfmark</groupId>
    <artifactId>perfmark-api</artifactId>
    <version>0.26.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-okhttp</artifactId>
    <version>1.50.2</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty-shaded</artifactId>
    <version>1.50.2</version>
</dependency>

L'artefact ironpdf-engine-linux-x64 regroupe le moteur de rendu précompilé basé sur Chromium pour Linux 64 bits. C'est ce qui permet à IronPDF de rendre du HTML en PDF à l'intérieur du conteneur Lambda. Sans cela, les appels de rendu échoueront avec une erreur de binaire manquant. Les dépendances gRPC (grpc-okhttp, grpc-netty-shaded, perfmark-api) sont requises car IronPDF communique avec son moteur de rendu via un canal gRPC local. La dépendance slf4j-simple fournit une implémentation minimale de la journalisation afin que les journaux internes d'IronPDF soient visibles dans CloudWatch.

Alignez toujours les numéros de version ironpdf et ironpdf-engine-linux-x64 — le mélange des versions entraînera un échec au démarrage. Vérifiez IronPDF for Java sur Maven Central pour la dernière version.

Comment écrire le gestionnaire Lambda ? {#lambda-handler}

La classe de gestionnaire Lambda reçoit un APIGatewayProxyRequestEvent, génère un PDF et renvoie un APIGatewayProxyResponseEvent. Deux appels de configuration IronPDF doivent apparaître avant la première opération de rendu : la définition du répertoire de travail sur /tmp et, éventuellement, l'activation de la journalisation de débogage.

Remplacez le contenu de App.java par ce qui suit :

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}

//:path=App.java
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.Settings;

import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

public class App {
    public APIGatewayProxyResponseEvent handleRequest(
            final APIGatewayProxyRequestEvent input,
            final Context context) {

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent();

        // IronPDF must write its engine binaries and temporary files to /tmp.
        // This is the only writable path available in the Lambda execution environment.
        Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/"));

        // Enable debug logging to CloudWatch during initial testing.
        Settings.setDebug(true);

        try {
            context.getLogger().log("Starting PDF render");

            // Render a PDF from a live URL. Replace with your own HTML or URL as needed.
            PdfDocument pdf = PdfDocument.renderUrlAsPdf("https://www.google.com");

            context.getLogger().log("PDF render complete");

            // Save the rendered PDF to /tmp. Files in /tmp persist for the lifetime
            // of the Lambda execution environment (warm instance).
            pdf.saveAs("/tmp/output.pdf");

            Map<String, String> headers = new HashMap<>();
            headers.put("Content-Type", "application/json");

            return response
                    .withStatusCode(200)
                    .withHeaders(headers)
                    .withBody("PDF generated successfully.");

        } catch (Exception e) {
            context.getLogger().log("PDF render failed: " + e.getMessage());
            return response
                    .withStatusCode(500)
                    .withBody("{\"error\": \"" + e.getMessage() + "\"}");
        }
    }
}

L'appel à Settings.setIronPdfEngineWorkingDirectory(Paths.get("/tmp/")) est obligatoire. L'environnement d'exécution AWS Lambda monte le code de la fonction dans un répertoire en lecture seule. Le moteur IronPDF doit extraire les fichiers de support et créer des sockets au démarrage — des activités qui nécessitent un accès en écriture. Le répertoire /tmp est le seul emplacement autorisé par Lambda pour l'écriture de fichiers ; IronPDF doit donc y être redirigé avant tout rendu. Si ce paramètre est omis, le moteur échouera à démarrer et chaque appel de rendu jettera une exception.

L'appel pdf.saveAs("/tmp/output.pdf") stocke le fichier rendu dans le système de fichiers éphémère /tmp. Si la fonction Lambda doit renvoyer le PDF sous forme de réponse binaire ou le télécharger sur S3, récupérez les octets avec pdf.getBinaryData() au lieu de les écrire sur le disque. Pour les charges de travail à grande échelle, le téléchargement vers Amazon S3 et le retour d'une URL pré-signée est le modèle recommandé.

Comment configurer le modèle SAM ? {#sam-template}

Le fichier template.yaml contrôle l'allocation des ressources de la fonction Lambda. Trois paramètres ont une incidence directe sur le bon fonctionnement d'IronPDF : Timeout, MemorySize et EphemeralStorage.Size.

Mettez à jour la section Globals de template.yaml comme suit :

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024

//:path=template.yaml
Globals:
  Function:
    Timeout: 400
    MemorySize: 2048
    EphemeralStorage:
      Size: 1024

Timeout est réglé sur 400 secondes. Au démarrage à froid, IronPDF doit extraire le moteur de rendu vers /tmp et lancer un processus Chromium local. Cette extraction peut prendre 30 à 60 secondes lors de la première invocation. Un délai d'expiration inférieur à 330 secondes entraînera l'échec des invocations à froid avec une erreur de délai d'expiration de tâche. Les invocations chaudes sont beaucoup plus rapides — généralement moins de 5 secondes pour des conversions HTML en PDF simples.

MemorySize est réglé sur 2048 Mo. Le rendu Chromium est gourmand en mémoire. La mémoire minimale viable d'AWS Lambda pour IronPDF est de 1024 Mo, mais 2048 Mo réduisent le risque d'échecs dus au manque de mémoire pour les pages complexes et permettent des temps de rendu sensiblement plus rapides car Lambda évolue également l'allocation CPU proportionnellement avec la mémoire.

EphemeralStorage.Size est réglé sur 1024 Mo. L'allocation par défaut de Lambda /tmp est de 512 Mo. IronPDF écrit les binaires du moteur de rendu, le cache de polices et les fichiers de rendu temporaires dans /tmp. Ces actifs peuvent dépasser 512 Mo au démarrage à froid, ce qui provoque l'échec de l'extraction du moteur. Régler le stockage éphémère à au moins 1024 Mo prévient ce mode d'échec.

Comment créer le fichier Dockerfile ? {#dockerfile}

Le Dockerfile est le cœur de ce déploiement. Il effectue une construction à plusieurs étapes : la première étape compile le projet Java en utilisant une image de construction Maven ; la seconde étape crée l'image d'exécution Lambda finale basée sur Amazon Linux 2, installe les paquets système requis par le moteur Chromium d'IronPDF, et copie les artefacts compilés.

Ouvrez le fichier Dockerfile du projet et remplacez son contenu par ce qui suit :

//:path=Dockerfile
# Stage 1: Build the Maven project
FROM public.ecr.aws/sam/build-java8.al2:latest AS build-image
WORKDIR /task
COPY src/ src/
COPY pom.xml ./
RUN mvn -q clean install
RUN mvn dependency:copy-dependencies -DincludeScope=compile

# Stage 2: Create the Lambda runtime image
FROM public.ecr.aws/lambda/java:8.al2

# Update the package index and install system libraries required by Chromium.
# These packages provide font rendering, graphics, audio, GTK3, and input
# method support — all needed by the headless browser inside IronPDF.
RUN yum update -y && \
    yum install -y \
        pango.x86_64 \
        libXcomposite.x86_64 \
        libXcursor.x86_64 \
        libXdamage.x86_64 \
        libXext.x86_64 \
        libXi.x86_64 \
        libXtst.x86_64 \
        cups-libs.x86_64 \
        libXScrnSaver.x86_64 \
        libXrandr.x86_64 \
        GConf2.x86_64 \
        alsa-lib.x86_64 \
        atk.x86_64 \
        gtk3.x86_64 \
        ipa-gothic-fonts \
        xorg-x11-fonts-100dpi \
        xorg-x11-fonts-75dpi \
        xorg-x11-utils \
        xorg-x11-fonts-cyrillic \
        xorg-x11-fonts-Type1 \
        xorg-x11-fonts-misc \
        glibc-devel.x86_64 \
        at-spi2-atk.x86_64 \
        mesa-libgbm.x86_64 \
        libxkbcommon \
        amazon-linux-extras && \
    amazon-linux-extras install epel -y && \
    yum install -y libgdiplus

# Ensure /tmp is writable by the Lambda execution user.
RUN chmod 777 /tmp/

# Copy the compiled classes and dependencies from the build stage.
COPY --from=build-image /task/target/classes /var/task/
COPY --from=build-image /task/target/dependency /var/task/lib

# Entry point: package.ClassName::methodName
CMD ["helloworld.App::handleRequest"]

Les images de base pour les deux étapes utilisent la balise java8.al2 plutôt que la balise simple java8. Le suffixe .al2 indique Amazon Linux 2, qui est requis pour IronPDF. L'ancienne image java8 s'exécute sur Amazon Linux 1 d'origine, qui utilise des dépôts yum qui ne reçoivent plus de mises à jour et ne contiennent pas plusieurs paquets dont IronPDF dépend. Utilisez toujours les images .al2 lors du déploiement d'IronPDF sur Java 8.

Le bloc yum install installe les bibliothèques X11, GTK3, Pango et celles liées aux polices dont Chromium a besoin pour afficher les pages. Omission de l'un de ces paquets peut produire une sortie PDF incomplète ou provoquer le crash du moteur de rendu avec une erreur de bibliothèque partagée manquante. Le package libgdiplus est nécessaire pour la compatibilité GDI+, qui est utilisée par certaines opérations de dessin d'IronPDF.

Mettez à jour l'instruction CMD pour qu'elle corresponde à votre nom de package et de classe réels s'ils diffèrent de helloworld.App.

Comment créer et déployer la fonction Lambda ? {#build-deploy}

Une fois le Dockerfile, template.yaml, pom.xml et App.java configurés, exécutez les deux commandes SAM CLI suivantes depuis la racine du projet.

Étape 1 — Construire l'image du conteneur :

//:path=build.sh
sam build -u

//:path=build.sh
sam build -u

Le drapeau -u indique à SAM d'utiliser Docker (mode " utiliser un conteneur "). SAM exécute le Dockerfile à plusieurs étapes, compile le projet Maven et produit l'image finale Lambda. Attendez-vous à ce que cette étape prenne plusieurs minutes lors de la première exécution tandis que Docker télécharge les images de base.

Étape 2 — Déployer sur AWS :

//:path=deploy.sh
sam deploy --guided

//:path=deploy.sh
sam deploy --guided

Le drapeau --guided lance une invite interactive qui demande le nom de la pile, la région AWS, le compartiment S3 pour les artefacts et s'il faut confirmer les ensembles de modifications avant le déploiement. Répondez aux invites, et SAM poussera l'image du conteneur vers Amazon ECR et créera la fonction Lambda, l'API Gateway et le rôle IAM définis dans template.yaml.

Une fois le déploiement terminé, le SAM CLI affiche l'URL du point d'accès API. Ouvrez la Console AWS Lambda pour voir la fonction déployée, exécuter des invocations de test, et inspecter les journaux CloudWatch pour la sortie de débogage IronPDF.

Lors de la première invocation (démarrage à froid), prévoyez un temps de réponse de 60 à 120 secondes, le temps que l'environnement d'exécution Lambda démarre et qu'IronPDF extraie son moteur de rendu vers /tmp. Les invocations suivantes sur le même instance chaude retourneront en quelques secondes. Si la latence de démarrage à froid est une préoccupation pour les charges de travail de production, envisagez d'utiliser Lambda Provisioned Concurrency pour garder les instances chaudes.

Vous pouvez également tester la fonction localement avant le déploiement en exécutant sam local invoke avec une charge utile d'événement de test, à condition que Docker soit en cours d'exécution sur la machine de développement.

Quelles sont les prochaines étapes? {#next-steps}

La fonction Lambda est maintenant déployée et rend des PDFs. Les guides suivants couvrent les étapes les plus courantes après un déploiement réussi d'IronPDF :

• IronPDF for Java — Démarrage — vue d'ensemble de l'API complète IronPDF Java, y compris HTML en PDF, URL en PDF, et estampillage de PDF.
• Comment générer des PDFs à partir de HTML en Java — rendu de chaînes, fichiers et modèles HTML en PDF.
• Comment appliquer des en-têtes et pieds de page aux PDFs en Java — ajout de numéros de page, de logos, et d'en-têtes de texte aux PDFs générés par Lambda.
• Comment ajouter des filigranes aux PDFs en Java — estampillage de la sortie PDF avec des filigranes de texte ou d'image avant de les retourner à l'appelant.
• Licences IronPDF — options de licence pour les déploiements Lambda en production, y compris le licensing basé sur le nombre de déploiements.

Commencez une évaluation gratuite d'IronPDF for Java pour générer et éditer des PDFs dans votre fonction Lambda sans restrictions pendant l'évaluation. Lorsque vous êtes prêt à déployer en production, consultez les options de licences IronPDF pour trouver le plan qui correspond à votre charge de travail sans serveur.