필수 사전 준비사항 {#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)

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

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을 업데이트한 후, mvn dependency:resolve을 실행하여 Maven이 Central에서 두 아티팩트를 모두 다운로드할 수 있는지 확인한 다음, Docker 이미지 빌드에 시간을 투자하십시오.

IronPDF for Java 릴리즈 노트를 확인하십시오. 가장 최근의 안정적인 버전을 사용하면 호환성이 확보됩니다. 최신 릴리즈를 사용하면 최신 Chromium 렌더링 엔진과의 호환성을 보장하고 알려진 문제점을 피할 수 있습니다.)}

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

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

전체 함수 코드는 위의 빠른 시작에 나와 있습니다. 이 내용을 src/main/java/com/example/Function.java에 배치하고, 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)는 컨테이너 내에서 헤드리스 Chromium 인스턴스를 실행하고, 대상 URL(JavaScript 포함)을 완전히 로드한 후, 렌더링된 출력을 PDF로 캡처합니다. 이는 사용자에게 브라우저에서 보이는 것과 시각적으로 동일한 출력을 생성하기 때문에 현대 웹 애플리케이션, 대시보드 및 보고서 페이지를 캡처하는 데 적합합니다.

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

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

Azure Functions Maven 아키타입에서 생성된 Dockerfile 파일에 다음 RUN 명령어를 추가해야 합니다. 이들을 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) 환경에서는 헤드리스 모드에서도 Chromium(Chromium)이 이를 필요로 합니다. rm -rf /var/lib/apt/lists/* 블록의 마지막에 있는 RUN 단계는 패키지 관리자 캐시를 제거하여 최종 이미지 크기를 최대한 작게 유지합니다.

{(Azure Functions 기본 이미지 버전이 변경되거나 다른 Linux 배포판이 기본으로 사용될 경우 필요한 패키지가 달라질 수 있습니다. Debian, Ubuntu, CentOS 및 Alpine을 대상으로 한 종속성 매트릭스는 IronPDF Linux 설치 가이드를 참조하십시오.)}

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 Container Registry(ACR)는 Docker Hub의 비공개 대안입니다. ACR은 Azure Active Directory와 직접 통합되며 이미지 개인 정보가 중요한 실행 작업에 대해 권장되는 선택입니다.)}

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 플래그는 프리미엄 호스팅 플랜을 선택합니다. 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 포털의 Function App 내 로그 스트림에서 컨테이너 풀링 또는 시작 오류가 있는지 확인하십시오.

{(Consume(Serverless) 계획은 IronPDF에 Azure Functions를 사용하는 데 권장되지 않습니다. Chromium과 함께하는 PDF 렌더링에는 소비 계획에서 할당된 것보다 더 많은 메모리가 필요합니다. 프리미엄 또는 전용(App Service) 계획을 사용하여 메모리 부족 오류를 방지하십시오.)}

함수를 어떻게 트리거하고 테스트합니까? {#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가 컨테이너 이미지를 가져오고 IronPDF가 Chromium을 초기화하는 동안 20–60초가 걸릴 수 있습니다. 이전 컨테이너 수명 내의 후속 요청은 훨씬 빠릅니다. 프리미엄 계획의 사전 웜 인스턴스 기능은 최소한 하나의 인스턴스를 연속으로 실행하여 콜드 스타트를 제거합니다.)}

오류 확인을 위한 로그 확인: 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 라이선싱 옵션을 확인하여 프로젝트 규모에 맞는 계획을 찾으세요.