Jak skonfigurować IronPDF dla Java na Azure

Jakie są wymagania wstępne? {#prerequisites}

Przed rozpoczęciem potwierdź, że wszystkie wymagane narzędzia są zainstalowane i subskrypcja Azure jest aktywna. Pominięcie tych kontroli często skutkuje niepowodzeniem budowy w połowie procesu wdrożenia.

Wymagane lokalne narzędzia:

• Azure CLI (wersja 2.40 lub późniejsza)
• Docker Desktop z włączonymi kontenerami Linux
• Maven 3.8 lub późniejszy
• JDK 11 lub JDK 17 (JDK 17 jest zalecaną wersją LTS)
• Azure Functions Core Tools v4

Wymagane zasoby Azure:

• Aktywna subskrypcja Azure
• Uprawnienia do tworzenia grup zasobów, kont storage i planów aplikacji funkcji
• Konto Docker Hub (lub Azure Container Registry) do hostowania zbudowanego obrazu

Uruchom az login, aby uwierzytelnić Azure CLI przed przejściem do następnej sekcji.

Jak skonfigurować projekt Azure Function? {#set-up-project}

Przewodnik Microsoft dotyczący tworzenia funkcji na Linux przy użyciu niestandardowego obrazu obejmuje kompletny proces tworzenia szkieletu. Postępuj zgodnie z tymi etapami z jednym ważnym wyborem: wybierz Java, gdy zostaniesz poproszony o język programowania.

Pracuj przez przewodnik, aż projekt z szablonem zostanie zbudowany i funkcja zastępcza uruchomi się lokalnie przy użyciu Azure Functions Core Tools. Zweryfikuj to za pomocą:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/local-run.sh
mvn clean package
func start

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/local-run.sh
mvn clean package
func start

Po odpowiedzi szablonu na lokalne żądanie HTTP, struktura projektu jest poprawna i gotowa na integrację z IronPDF. Kluczowe pliki to pom.xml (konfiguracja Maven), Function.java (kod funkcji) i Dockerfile (definicja kontenera).

Jak dodać zależności IronPDF do projektu Maven? {#add-IronPDF-dependencies}

IronPDF dla Java jest dystrybuowany przez Maven Central. Wymagane są dwa artefakty: biblioteka ironpdf, która dostarcza API Java, oraz ironpdf-engine-linux-x64, która zawiera natywny silnik Chromium skompilowany dla Linux x86-64. Artefakt silnika jest tym, co sprawia, że wdrożenie Dockera jest obowiązkowe — zawiera binaria, które muszą być wykonane w czasie runtime.

Otwórz pom.xml i dodaj poniższe wewnątrz bloku <dependencies>. Zamień LATEST_VERSION na bieżące wydanie dostępne na Maven Central:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/pom.xml
<dependencies>

    <dependency>
        <groupId>com.ironsoftware</groupId>
        <artifactId>ironpdf</artifactId>
        <version>LATEST_VERSION</version>
    </dependency>

    <dependency>
        <groupId>com.ironsoftware</groupId>
        <artifactId>ironpdf-engine-linux-x64</artifactId>
        <version>LATEST_VERSION</version>
    </dependency>
</dependencies>

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/pom.xml
<dependencies>

    <dependency>
        <groupId>com.ironsoftware</groupId>
        <artifactId>ironpdf</artifactId>
        <version>LATEST_VERSION</version>
    </dependency>

    <dependency>
        <groupId>com.ironsoftware</groupId>
        <artifactId>ironpdf-engine-linux-x64</artifactId>
        <version>LATEST_VERSION</version>
    </dependency>
</dependencies>

Oba artefakty muszą używać tego samego numeru wersji. Niepasujące wersje między ironpdf a ironpdf-engine-linux-x64 powodują wyjątek wykonania, gdy funkcja po raz pierwszy próbuje renderować PDF.

Po zaktualizowaniu pom.xml, uruchom mvn dependency:resolve, aby zweryfikować, czy Maven może pobrać oba artefakty z Central, zanim zainwestujesz czas w budowanie obrazu Dockera.

Jak napisać funkcję RenderPdf? {#write-renderpdf-function}

Funkcja RenderPdf jest funkcją Azure wyzwalaną przez HTTP, która akceptuje parametr zapytania url, renderuje docelową stronę za pomocą silnika opartego na Chromium IronPDF i zwraca wynikowy PDF jako odpowiedź binarna z nagłówkiem Content-Disposition: attachment. Ten nagłówek mówi przeglądarce (lub klientowi HTTP), aby pobrała plik PDF zamiast wyświetlać go w linii.

Kompletny kod funkcji pokazano w powyższym Szybkim Starcie. Umieść ją w src/main/java/com/example/Function.java, zamieniając lub rozszerzając placeholder wygenerowany przez archetyp Maven.

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/RenderPdf-annotated.java
import com.microsoft.azure.functions.*;
import com.ironsoftware.ironpdf.PdfDocument;
import java.util.Optional;

public class Function {

    @FunctionName("RenderPdf")
    public HttpResponseMessage renderPdf(
            @HttpTrigger(
                    name = "req",
                    methods = {HttpMethod.GET, HttpMethod.POST},
                    authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Log each invocation for Azure Monitor / Application Insights
        context.getLogger().info("RenderPdf triggered.");

        final String url = request.getQueryParameters().get("url");

        // Return 400 if no URL was supplied
        if (url == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                    .body("Provide a 'url' query parameter.")
                    .build();
        }

        try {
            // renderUrlAsPdf launches Chromium, loads the page, and captures it as PDF
            PdfDocument pdf = PdfDocument.renderUrlAsPdf(url);

            // getBinaryData returns the raw PDF bytes ready for transmission
            byte[] pdfBytes = pdf.getBinaryData();

            return request.createResponseBuilder(HttpStatus.OK)
                    .body(pdfBytes)
                    .header("Content-Disposition", "attachment; filename=output.pdf")
                    .header("Content-Type", "application/pdf")
                    .build();

        } catch (Exception ex) {
            context.getLogger().severe("Rendering error: " + ex.getMessage());
            return request.createResponseBuilder(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("PDF rendering failed.")
                    .build();
        }
    }
}

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/RenderPdf-annotated.java
import com.microsoft.azure.functions.*;
import com.ironsoftware.ironpdf.PdfDocument;
import java.util.Optional;

public class Function {

    @FunctionName("RenderPdf")
    public HttpResponseMessage renderPdf(
            @HttpTrigger(
                    name = "req",
                    methods = {HttpMethod.GET, HttpMethod.POST},
                    authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Log each invocation for Azure Monitor / Application Insights
        context.getLogger().info("RenderPdf triggered.");

        final String url = request.getQueryParameters().get("url");

        // Return 400 if no URL was supplied
        if (url == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                    .body("Provide a 'url' query parameter.")
                    .build();
        }

        try {
            // renderUrlAsPdf launches Chromium, loads the page, and captures it as PDF
            PdfDocument pdf = PdfDocument.renderUrlAsPdf(url);

            // getBinaryData returns the raw PDF bytes ready for transmission
            byte[] pdfBytes = pdf.getBinaryData();

            return request.createResponseBuilder(HttpStatus.OK)
                    .body(pdfBytes)
                    .header("Content-Disposition", "attachment; filename=output.pdf")
                    .header("Content-Type", "application/pdf")
                    .build();

        } catch (Exception ex) {
            context.getLogger().severe("Rendering error: " + ex.getMessage());
            return request.createResponseBuilder(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("PDF rendering failed.")
                    .build();
        }
    }
}

PdfDocument.renderUrlAsPdf(url) uruchamia instancję Chromium bez głowy wewnątrz kontenera, w pełni ładuje docelowy URL (w tym JavaScript) i zapisuje renderowany wynik jako PDF. To generuje wyjście wizualnie identyczne z tym, co użytkownik widzi w przeglądarce, co czyni go odpowiednim do przechwytywania nowoczesnych aplikacji webowych, pulpitów i stron raportów.

Jak skonfigurować Dockerfile dla IronPDF? {#configure-dockerfile}

Silnik Chromium IronPDF zależy od zestawu współdzielonych bibliotek Linux, które nie są zawarte w bazowym obrazie dla Azure Functions. Bazowy obraz mcr.microsoft.com/azure-functions/java:4-java17-build jest zbudowany na Debianie 11, więc pakiety muszą być instalowane za pomocą apt.

Poniższe polecenia RUN muszą być dodane do Dockerfile wygenerowanego przez archetyp Maven Azure Functions. Umieść je po instrukcji FROM i przed krokami COPY, które dodają aplikację JAR:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/Dockerfile
FROM mcr.microsoft.com/azure-functions/java:4-java17-build AS installer-env

# Install system dependencies required by IronPDF's Chromium renderer
RUN apt-get update && apt-get install -y \
    libgdiplus \
    libxkbcommon-x11-0 \
    libc6 \
    libc6-dev \
    libgtk2.0-0 \
    libnss3 \
    libatk-bridge2.0-0 \
    libx11-xcb1 \
    libxcb-dri3-0 \
    libdrm-common \
    libgbm1 \
    libasound2 \
    libxrender1 \
    libfontconfig1 \
    libxshmfence1 \
    && apt-get install -y xvfb libva-dev libgdiplus \
    && rm -rf /var/lib/apt/lists/*

# Copy the built function JAR
COPY --from=installer-env /home/site/wwwroot /home/site/wwwroot

ENV AzureWebJobsScriptRoot=/home/site/wwwroot \
    AzureFunctionsJobHost__Logging__Console__IsEnabled=true

Pakiet libgdiplus zapewnia zgodność z GDI+ dla renderowania grafiki. libnss3 i libatk-bridge2.0-0 są wymagane przez warstwy piaskownicy i dostępności w Chromium. xvfb dostarcza wirtualną ramkę buforową, której Chromium potrzebuje nawet w trybie bez głowy na niektórych konfiguracjach Debiana. Krok rm -rf /var/lib/apt/lists/* na końcu bloku RUN usuwa pamięć podręczną menedżera paczek, aby utrzymać rozmiar końcowego obrazu jak najmniejszy.

Jak zbudować i przesłać obraz Docker? {#build-push-docker}

Po zbudowaniu projektu Maven i zaktualizowaniu Dockerfile, obraz kontenera może zostać złożony i przesłany do rejestru Docker. Azure Functions pobiera ten obraz, gdy aplikacja funkcji jest tworzona lub aktualizowana.

Krok 1 — Zbuduj i zapakuj projekt Maven:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/build.sh
# Compile the Java code and package it as a JAR
mvn clean package

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/build.sh
# Compile the Java code and package it as a JAR
mvn clean package

Maven kompiluje kod funkcji, rozwiązuje wszystkie zależności (w tym oba artefakty IronPDF) i produkuje wdrażalny JAR w katalogu target/. Należy naprawić wszelkie błędy kompilacji przed kontynuacją.

Krok 2 — Zbuduj obraz Docker:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/docker-build.sh
# Replace <DOCKER_ID> with your Docker Hub username or ACR login server
docker build --tag <DOCKER_ID>/ironpdf-azure-functions:v1.0.0 .

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/docker-build.sh
# Replace <DOCKER_ID> with your Docker Hub username or ACR login server
docker build --tag <DOCKER_ID>/ironpdf-azure-functions:v1.0.0 .

Budowa instaluje pakiety Linuksa wymienione w Dockerfile, kopiuje JAR i warstwy wszystko w końcowym obrazie. Podczas pierwszej budowy może to zająć kilka minut, ponieważ ustanawiane są pobierania pakietów i pamięć podręczna warstw. Kolejne budowy przy użyciu tego samego obrazu bazowego są znacznie szybsze.

Krok 3 — Prześlij obraz do Docker Hub:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/docker-push.sh
# Authenticate if not already logged in
docker login

# Push the image to the registry
docker push <DOCKER_ID>/ironpdf-azure-functions:v1.0.0

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/docker-push.sh
# Authenticate if not already logged in
docker login

# Push the image to the registry
docker push <DOCKER_ID>/ironpdf-azure-functions:v1.0.0

Jak wdrożyć funkcję na Azure? {#deploy-to-azure}

Z obrazem w rejestrze, aplikacja Azure Function może być utworzona (lub zaktualizowana) do odwołania się do niego. Polecenie az functionapp create zapewnia Function App, łączy ją z kontem magazynu i ustawia obraz kontenera w jednym kroku.

Krok 1 — Utwórz lub zaktualizuj aplikację funkcji:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/az-deploy.sh
az functionapp create \
  --name <APP_NAME> \
  --storage-account <STORAGE_NAME> \
  --resource-group AzureFunctionsContainers-rg \
  --plan myPremiumPlan \
  --deployment-container-image-name <DOCKER_ID>/ironpdf-azure-functions:v1.0.0

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/az-deploy.sh
az functionapp create \
  --name <APP_NAME> \
  --storage-account <STORAGE_NAME> \
  --resource-group AzureFunctionsContainers-rg \
  --plan myPremiumPlan \
  --deployment-container-image-name <DOCKER_ID>/ironpdf-azure-functions:v1.0.0

Zamień <APP_NAME> na globalnie unikalną nazwę dla Function App, <STORAGE_NAME> na istniejącą nazwę konta Azure Storage i <DOCKER_ID> na nazwę użytkownika Docker Hub lub serwer logowania ACR używany w poprzednim kroku.

Flaga --plan myPremiumPlan wybiera plan hostingowy Premium. Silnik Chromium IronPDF zużywa znaczną ilość pamięci podczas renderowania; 1,5 GB limit pamięci planu Consumption jest często niewystarczający. Plan Premium zapewnia co najmniej 3,5 GB i obsługuje wstępnie rozgrzane instancje, które eliminują opóźnienia zimnego startu.

Krok 2 — Zweryfikuj wdrożenie:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/az-verify.sh
# Check that the function app is running and the container has been pulled
az functionapp show \
  --name <APP_NAME> \
  --resource-group AzureFunctionsContainers-rg \
  --query "state"

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/az-verify.sh
# Check that the function app is running and the container has been pulled
az functionapp show \
  --name <APP_NAME> \
  --resource-group AzureFunctionsContainers-rg \
  --query "state"

Polecenie zwraca "Running", gdy kontener został pomyślnie uruchomiony. Jeśli zwraca "Starting" lub błąd, sprawdź Strumień Dzienników w portalu Azure w ramach Function App w celu błędów pobierania kontenera lub uruchomienia.

Jak uruchomić i przetestować funkcję? {#trigger-and-test}

Gdy Function App melduje stan Running, punkt końcowy RenderPdf jest gotowy do akceptowania żądań. URL punktu końcowego podąża za przewidywalnym wzorcem opartym na nazwie Function App oraz nazwie funkcji zdefiniowanej w adnotacji @FunctionName.

Przetestuj, używając przeglądarki lub curl:

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/test-request.sh
# Replace <APP_NAME> with the Function App name
curl -o output.pdf \
  "https://<APP_NAME>.azurewebsites.net/api/RenderPdf?url=https://www.example.com"

//:path=/static-assets/pdf/content-code-examples/tutorials/azure/test-request.sh
# Replace <APP_NAME> with the Function App name
curl -o output.pdf \
  "https://<APP_NAME>.azurewebsites.net/api/RenderPdf?url=https://www.example.com"

Pomyślna odpowiedź zapisuje plik PDF nazwany output.pdf do bieżącego katalogu. Flaga -o w curl zapisuje binarną treść odpowiedzi do pliku zamiast wypisywać ją na terminalu.

Podczas testowania w przeglądarce, przejdź do:

https://<APP_NAME>.azurewebsites.net/api/RenderPdf?url=https://www.example.com

Przeglądarka poprosi o pobranie pliku PDF. Otwórz go, aby zweryfikować, że strona została poprawnie wyrenderowana.

Sprawdzanie logów w celu wykrycia błędów: Przejdź do portalu Azure, otwórz aplikację funkcji i wybierz Strumień Logów w sekcji Monitoring. Zapisy z wywołań context.getLogger() pojawiają się tutaj niemal w czasie rzeczywistym, co ułatwia diagnozowanie awarii renderowania.

Jakie są kolejne kroki? {#next-steps}

Ten przewodnik demonstrował, jak wdrożyć IronPDF dla Java wewnątrz kontenera Docker Azure Functions, napisać funkcję wywoływaną przez HTTP, która renderuje URL do PDF, skonfigurować Dockerfile z wymaganymi zależnościami Linuksa i przetestować działający punkt końcowy. Ten sam schemat rozszerza się na bardziej zaawansowane przypadki użycia z minimalnymi zmianami.

Rozszerz funkcję:

• Ręderuj łańcuchy HTML bezpośrednio za pomocą PdfDocument.renderHtmlAsPdf(htmlString) zamiast URL
• Stosuj znaki wodne, scalaj wiele PDF-ów lub dodawaj cyfrowe podpisy, używając pełnego API Java IronPDF
• Odczytuj nagłówki żądań lub korpus POST, aby przekazać niestandardową treść HTML lub opcje renderowania

Popraw gotowość produkcyjną:

• Zmień authLevel na FUNCTION i regularnie obracaj klucze funkcji
• Używaj Azure Key Vault do przechowywania wszelkich tajemnic odwołanych w ustawieniach aplikacji
• Skonfiguruj Application Insights dla pełnej obserwowalności opóźnień renderowania i wskaźników błedów
• Ustaw webhook aktualizacji obrazu Docker, aby Azure automatycznie wdrażało ponownie, gdy nowa wersja obrazu zostanie przesłana

Odkryj więcej przewodników IronPDF dla Java:

• IronPDF dla Java: Przewodnik instalacji na Linuksie
• Generowanie PDF-ów z HTML w Java
• IronPDF dla Java: Przewodnik wdrożenia Docker
• Pełna Dokumentacja API IronPDF Java

Rozpocznij darmowy okres próbny IronPDF, aby uzyskać dostęp do wszystkich funkcji renderowania i manipulacji bez znaku wodnego podczas okresu oceny. Gdy będziesz gotowy do wdrożenia produkcyjnego, zobacz opcje licencjonowania IronPDF, aby znaleźć plan pasujący do skali projektu.