Azure에서 IronPDF for Java 설정 방법

필수 사전 준비사항 {#prerequisites}

시작하기 전에 모든 필요 도구가 설치되었는지와 Azure 구독이 활발한지 확인하십시오. 이러한 확인을 생략하면 배포 과정 도중 빌드 실패가 자주 발생합니다.

필요한 로컬 도구:

• Azure CLI (버전 2.40 이상)
• Linux 컨테이너 사용으로 설정된 Docker Desktop
• Maven 3.8 이상
• JDK 11 또는 JDK 17 (JDK 17이 권장되는 LTS 버전)
• Azure Functions Core Tools v4

필요한 Azure 리소스:

• 활성화된 Azure 구독
• 리소스 그룹, 저장소 계정 및 기능 앱 계획을 생성할 수 있는 권한
• 빌드된 이미지를 호스팅하기 위한 Docker Hub 계정 (또는 Azure Container Registry)

다음 섹션으로 진행하기 전에 Azure CLI를 인증하려면 az login을 실행하십시오.

Azure Function 프로젝트를 어떻게 설정합니까? {#set-up-project}

Linux에서 사용자 정의 이미지를 사용하여 함수를 만드는 방법에 대한 Microsoft 가이드는 전체 구축 프로세스를 설명합니다. 프로그래밍 언어를 묻는 프롬프트가 나타나면 Java를 선택하십시오.

가이드를 진행하여 빌드된 스캐폴딩 프로젝트가 Azure Functions Core Tools를 사용하여 로컬에서 플레이스홀더 함수를 실행할 수 있을 때까지 진행하십시오. 다음으로 확인하십시오:

//: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

플레이스홀더가 로컬 HTTP 요청에 응답하면 프로젝트 구조가 올바르며 IronPDF 통합을 위한 준비가 된 것입니다. 주요 파일은 pom.xml (Maven 구성), Function.java (함수 코드) 및 Dockerfile (컨테이너 정의)입니다.

Maven 프로젝트에 IronPDF 종속성을 어떻게 추가합니까? {#add-IronPDF-dependencies}

IronPDF for Java는 Maven Central을 통해 제공됩니다. 두 가지 아티팩트가 필요합니다: Java API를 제공하는 코어 ironpdf 라이브러리와 Linux x86-64에 컴파일된 네이티브 Chromium 엔진을 번들로 제공하는 ironpdf-engine-linux-x64 입니다. 엔진 아티팩트는 Docker 배포를 필수로 만드는 이유입니다 - 런타임 시 실행해야 하는 바이너리를 배송합니다.

pom.xml 을 열고, <dependencies> 블록 안에 다음 내용을 추가하세요. 현재 버전으로 LATEST_VERSION 을 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>

두 아티팩트는 동일한 버전 번호를 사용해야 합니다. ironpdf 와 ironpdf-engine-linux-x64 간의 버전 불일치는 함수가 처음으로 PDF 렌더링을 시도할 때 런타임 예외를 유발합니다.

pom.xml을 업데이트한 후, Docker 이미지를 빌드하기 전에 Central에서 두 아티팩트를 다운로드할 수 있는지 확인하려면 mvn dependency:resolve을 실행하세요.

RenderPdf 함수를 어떻게 작성합니까? {#write-renderpdf-function}

RenderPdf 함수는 HTTP 트리거된 Azure Function으로, url 쿼리 매개변수를 받아 IronPDF의 Chromium 기반 엔진을 사용하여 대상 페이지를 렌더링하고, Content-Disposition: attachment 헤더와 함께 바이너리 응답으로 결과 PDF를 반환합니다. 이 헤더는 브라우저(또는 HTTP 클라이언트)에 PDF를 인라인으로 표시하지 않고 다운로드 하도록 지시합니다.

전체 함수 코드는 위의 빠른 시작에 나와 있습니다. Maven archetype이 생성한 대체 또는 확장하도록 src/main/java/com/example/Function.java에 넣으세요.

//: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)은 컨테이너 내에서 헤드리스 Chromium 인스턴스를 시작하고, JavaScript를 포함하여 대상 URL을 완전히 로드하며 렌더링된 출력을 PDF로 캡처합니다. 이는 사용자에게 브라우저에서 보이는 것과 시각적으로 동일한 출력을 생성하기 때문에 현대 웹 애플리케이션, 대시보드 및 보고서 페이지를 캡처하는 데 적합합니다.

IronPDF를 위한 Dockerfile을 어떻게 구성합니까? {#configure-dockerfile}

IronPDF의 Chromium 엔진은 base Azure Functions 이미지에 포함되지 않은 일련의 공유 Linux 라이브러리에 의존합니다. 기본 이미지 mcr.microsoft.com/azure-functions/java:4-java17-build 는 Debian 11에 구축되어 있으므로 패키지를 apt 을 사용하여 설치해야 합니다.

다음 RUN 명령어는 Azure Functions Maven archetype이 생성한 Dockerfile 에 추가해야 합니다. 그것을 FROM 명령어 다음 그리고 애플리케이션 JAR를 추가하는 단계 COPY 이전에 놓으십시오:

//: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

libgdiplus 패키지는 그래픽 렌더링을 위한 GDI+ 호환성을 제공합니다. libnss3 및 libatk-bridge2.0-0 는 Chromium의 샌드박스 및 접근성 계층에 필요합니다. xvfb 은 가상의 프레임 버퍼를 제공하며, 일부 Debian 구성에서 even headless 모드에서도 Chromium이 필요로 합니다. RUN 블록의 끝에 있는 rm -rf /var/lib/apt/lists/* 단계는 패키지 관리자 캐시를 제거하여 최종 이미지 크기를 최대한 작게 유지합니다.

Docker 이미지를 어떻게 빌드하고 푸시합니까? {#build-push-docker}

Maven 프로젝트가 빌드되고 Dockerfile이 업데이트되면 컨테이너 이미지를 조립하고 Docker 레지스트리에 업로드할 수 있습니다. Azure Functions는 Function 앱이 생성되거나 업데이트될 때 이 이미지를 가져옵니다.

1단계 — 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은 함수 코드를 컴파일하고, 모든 종속성(IronPDF 아티팩트 포함)을 해소하고, target/ 디렉토리에 배포 가능한 JAR를 생성합니다. 진행하기 전 모든 컴파일 오류를 수정하십시오.

2단계 — 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 .

이는 Dockerfile에 명시된 Linux 패키지를 설치하고 JAR 파일을 복사하며 최종 이미지를 레이어링합니다. 첫 빌드에서는 패키지 다운로드 및 레이어 캐시 설정으로 인해 몇 분이 소요될 수 있습니다. 같은 기본 이미지를 사용하는 후속 빌드는 상당히 빠릅니다.

3단계 — 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

Azure에 함수를 어떻게 배포합니까? {#deploy-to-azure}

이미지가 레지스트리에 있으면 Azure Function 앱을 생성(또는 업데이트)하여 이를 참조할 수 있습니다. az functionapp create 명령은 Function App을 조달하고 이를 스토리지 계정에 연결하며 단일 단계에서 컨테이너 이미지를 설정합니다.

1단계 — Function 앱 생성 또는 업데이트:

//: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

<APP_NAME> 는 Function App의 전역적으로 고유한 이름이, <STORAGE_NAME> 는 기존 Azure Storage 계정 이름이, 그리고 <DOCKER_ID>는 이전 단계에서 사용된 Docker Hub 사용자 이름 또는 ACR 로그인 서버와 대체합니다.

--plan myPremiumPlan 플래그는 Premium 호스팅 플랜을 선택합니다. IronPDF의 Chromium 엔진은 렌더링 동안 상당한 메모리를 소모합니다; 소모 계획의 1.5 GB 메모리 한계는 종종 불충분합니다. 프리미엄 계획은 최소 3.5 GB를 제공하며 콜드 스타트 지연을 제거하는 사전 웜 인스턴스를 지원합니다.

2단계 — 배포 확인:

//: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"

명령어가 성공적으로 실행되면 컨테이너 시작 상태를 나타내는 "Running" 를 반환합니다. "Starting" 이나 오류를 반환할 경우, Azure Portal의 Log Stream에서 함수 앱의 컨테이너 플 및 시작 오류를 확인하십시오.

함수를 어떻게 트리거하고 테스트합니까? {#trigger-and-test}

Function App이 Running 상태를 보고하면, RenderPdf 엔드포인트는 요청을 받을 준비가 된 것입니다. 엔드포인트 URL은 Function App 이름 및 @FunctionName 주석에 정의된 함수 이름을 기반으로 예측 가능한 패턴을 따릅니다.

브라우저 또는 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"

성공적인 응답은 현재 디렉터리에 output.pdf로 명명된 PDF 파일을 저장합니다. curl 명령어에서 -o 플래그는 출력 대신 파일에 바이너리 응답 본문을 씁니다.

브라우저에서 테스트할 때 다음으로 이동하십시오:

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

브라우저는 PDF 다운로드를 prompts할 것입니다. 이를 열어 페이지가 올바르게 렌더링되었는지 확인하십시오.

오류 확인을 위한 로그 확인: Azure 포털로 이동하여 기능 앱을 열고 모니터링 아래의 로그 스트림을 선택하십시오. context.getLogger() 호출에서 로그 항목은 여기에서 거의 실시간으로 표시되며 렌더링 실패 진단을 간소화합니다.

다음 단계는 무엇인가요? {#next-steps}

이 가이드는 Azure Functions Docker 컨테이너 내에서 IronPDF for Java를 배포하고 URLs을 PDF로 렌더링하는 HTTP로 트리거되는 함수를 작성하며, 필요한 Linux 종속성으로 Dockerfile을 구성하고 라이브 엔드포인트를 테스트하는 방법을 보여줍니다. 동일한 패턴은 최소한의 변경으로 보다 고급 사용 사례로 확장됩니다.

함수 확장:

• URL 대신 PdfDocument.renderHtmlAsPdf(htmlString)을 사용하여 HTML 문자열을 직접 렌더링합니다
• IronPDF의 전체 Java PDF API를 사용하여 워터마크 적용, 여러 PDF 병합, 또는 디지털 서명을 추가
• 요청 헤더나 POST 본문을 읽어 맞춤 HTML 콘텐츠나 렌더링 옵션 전달

프로덕션 준비 개선:

• authLevel 을 FUNCTION 으로 전환하고 정기적으로 함수 키를 회전시키세요
• Azure Key Vault를 사용하여 애플리케이션 설정에서 참조된 비밀을 저장하세요
• Application Insights를 구성하여 렌더링 지연 및 실패율의 끝단을 관측하세요
• Docker 이미지 업데이트 웹훅을 설정하여 새 이미지 버전이 푸시될 때 Azure가 자동으로 재배포하게 하세요

IronPDF for Java 가이드를 더 탐색하세요:

• IronPDF for Java: Linux 설치 가이드
• Java에서 HTML로 PDF 생성
• IronPDF for Java: Docker 배포 가이드
• IronPDF Java API 참고 문서 전체 보기

무료 IronPDF 체험판을 시작하여 평가 기간 동안 모든 렌더링 및 조작 기능을 워터마크 없이 액세스하세요. 생산에 배포할 준비가 되었을 때, IronPDF 라이선싱 옵션을 확인하여 프로젝트 규모에 맞는 계획을 찾으세요.