如何在Azure上設置IronPDF for Java
本指南涵蓋了在Azure Functions容器內部署IronPDF for Java,並從無伺服器的HTTP端點按需生成PDF的所有步驟。 由於IronPDF搭載了一個原生的Chromium渲染引擎,因此必須打包為Docker映像—Azure Functions上的標準Zip部屬方法無法在運行時執行IronPDF所依賴的二進位文件。按照本指南進行,一個工作中的Azure Function會接受作為查詢參數的URL並返回完全渲染的PDF作為可下載文件。
此方法使用Microsoft推薦的自定義容器工作流程適用於基於Linux的Azure Functions。 一個Maven專案提供了功能程式碼和依賴管理。 Docker建構容器映像,然後將其推送到註冊表,並由Azure Function App引用。一旦部署,冷啟動時間是主要的性能考慮——隨後的調用速度快且一致。
在開始之前,請確保Azure CLI、Docker Desktop、Maven 3.8+ 和 JDK 11 或 JDK 17 已安裝在本地。 還需要一個活躍的Azure訂閱,並有權建立Functions App和儲存帳戶。
快速入門:在Azure Functions上部署IronPDF for Java
下面的程式碼顯示了完整的RenderPdf Azure Function。 它接受url 查詢參數並返回一個PDF位元組流。 在完成接下來各部分的Maven依賴設置後,將其新增到Function.java。
//:path=/static-assets/pdf/content-code-examples/tutorials/azure/RenderPdf.java
import com.microsoft.azure.functions.*;
import com.ironsoftware.ironpdf.PdfDocument;
import java.util.Optional;
public class Function {
/**
* HTTP-triggered Azure Function: accepts a URL, renders it as a PDF,
* and returns the PDF bytes as a downloadable attachment.
*/
@FunctionName("RenderPdf")
public HttpResponseMessage renderPdf(
@HttpTrigger(
name = "req",
methods = {HttpMethod.GET, HttpMethod.POST},
authLevel = AuthorizationLevel.ANONYMOUS)
HttpRequestMessage<Optional<String>> request,
final ExecutionContext context) {
context.getLogger().info("RenderPdf function triggered.");
// Read the target URL from the query string
final String url = request.getQueryParameters().get("url");
if (url == null) {
return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
.body("Provide a 'url' query parameter.")
.build();
}
try {
context.getLogger().info("Rendering URL as PDF: " + url);
// IronPDF renders the full page including JavaScript
PdfDocument pdf = PdfDocument.renderUrlAsPdf(url);
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("PDF rendering failed: " + ex.getMessage());
return request.createResponseBuilder(HttpStatus.INTERNAL_SERVER_ERROR)
.body("PDF rendering failed. Check function logs for details.")
.build();
}
}
}
//:path=/static-assets/pdf/content-code-examples/tutorials/azure/RenderPdf.java
import com.microsoft.azure.functions.*;
import com.ironsoftware.ironpdf.PdfDocument;
import java.util.Optional;
public class Function {
/**
* HTTP-triggered Azure Function: accepts a URL, renders it as a PDF,
* and returns the PDF bytes as a downloadable attachment.
*/
@FunctionName("RenderPdf")
public HttpResponseMessage renderPdf(
@HttpTrigger(
name = "req",
methods = {HttpMethod.GET, HttpMethod.POST},
authLevel = AuthorizationLevel.ANONYMOUS)
HttpRequestMessage<Optional<String>> request,
final ExecutionContext context) {
context.getLogger().info("RenderPdf function triggered.");
// Read the target URL from the query string
final String url = request.getQueryParameters().get("url");
if (url == null) {
return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
.body("Provide a 'url' query parameter.")
.build();
}
try {
context.getLogger().info("Rendering URL as PDF: " + url);
// IronPDF renders the full page including JavaScript
PdfDocument pdf = PdfDocument.renderUrlAsPdf(url);
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("PDF rendering failed: " + ex.getMessage());
return request.createResponseBuilder(HttpStatus.INTERNAL_SERVER_ERROR)
.body("PDF rendering failed. Check function logs for details.")
.build();
}
}
}
今天就使用IronPDF開始專案,免費試用。
目錄
- 需要哪些先決條件?
- 如何建立Azure Function專案?
- 如何將IronPDF依賴新增到Maven專案中?
- 如何編寫RenderPdf功能?
- 如何配置IronPDF的Dockerfile?
- 如何構建並發布Docker映像?
- 如何將功能部署到Azure?
- 如何觸發並測試功能?
- 接下來的步驟是什麼?
需要哪些先決條件?
在開始之前,確認所有必需的工具已安裝並且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訂閱
- 建立資源組、儲存帳戶和Functions App計劃的權限
- 一個Docker Hub帳戶(或Azure容器註冊表)以託管構建的映像
ironpdf-engine-linux-x64 工件。 Azure Functions上的標準Zip部屬無法執行IronPDF的原生二進位文件—Docker是唯一支持的部屬方法。在繼續到下一部分之前,運行az login 進行Azure CLI身份驗證。
如何建立Azure Function專案?
Microsoft為使用自定義映像在Linux上建立Function的指南涵蓋了完整的腳手架過程。 按照這些步驟進行,並在提示選擇編程語言時選擇Java。
通過指南中的步驟,直到腳手架專案構建完成並使用Azure Functions核心工具本地運行占位符功能。 使用以下指令驗證:
//: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整合。 關鍵文件是Dockerfile(容器定義)。
host.json 和 local.settings.json 與 pom.xml 一起。 local.settings.json 文件儲存本地開發的環境變數—預設情況下,它未納入版本控制且不應提交。如何將IronPDF依賴新增到Maven專案中?
IronPDF for Java是通過Maven Central發佈的。 需要兩個工件:提供Java API的核心ironpdf 程式庫,以及ironpdf-engine-linux-x64,它包含針對Linux x86-64編譯的原生Chromium引擎。引擎工件是使Docker部屬成為必需的原因—它攜帶必須在運行時執行的二進位文件。
打開pom.xml 並在<dependencies> 區塊中新增以下內容。 用Maven Central上可用的當前版本替換LATEST_VERSION:
//: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映像。
如何編寫RenderPdf功能?
RenderPdf 是一個HTTP觸發的Azure Function,它接受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。 這會產生與使用者在瀏覽器中看到的視覺上完全一致的輸出,使其適合捕獲現代Web應用、儀表板和報告頁面。
authLevel = AuthorizationLevel.ANONYMOUS 設定使端點公開存取。 對於生產部屬,將其更改為FUNCTION 或 ADMIN,並在請求標頭中傳遞功能密鑰。如何配置IronPDF的Dockerfile?
IronPDF的Chromium引擎依賴於一組不包含在基礎Azure Functions映像中的共享Linux程式庫。 基礎映像mcr.microsoft.com/azure-functions/java:4-java17-build 是基於Debian 11建構,因此必須使用apt 安裝軟體包。
必須將以下RUN 命令新增到Azure Functions Maven模版生成的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配置的無頭模式下,Chromium也需要。 rm -rf /var/lib/apt/lists/* 步驟在RUN 區塊的最後刪除包管理器快取,保持最終映像大小盡可能小。
如何構建並發布Docker映像?
隨著Maven專案構建完成並更新Dockerfile, 容器映像可以被組裝並上傳到Docker註冊表。 當Functions App被建立或更新時,Azure Functions會拉取此映像。
第一步—構建並打包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。 在繼續之前修正所有編譯錯誤。
第二步—構建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,並將所有層組成最終映像。 首次構建可能需要幾分鐘,因為包下載和層快取需要時間建立。 使用相同基礎映像的後續構建顯著更快。
第三步—將映像推送到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?
映像在註冊表中後,可以建立(或更新)Azure Functions App來引用它。 az functionapp create 命令配置Functions App,將其連結到一個儲存帳戶,並在單一步驟中設置容器映像。
第一步—建立或更新Functions App:
//: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> 替換為Functions App的全球唯一名稱,用<STORAGE_NAME> 替換為現有的Azure Storage帳戶名稱,<DOCKER_ID> 替換為上一步中使用的Docker Hub使用者名或ACR登錄伺服器。
--plan myPremiumPlan 標識選擇了一個高級託管方案。 IronPDF的Chromium引擎在渲染期間消耗大量記憶體; 消耗方案1.5 GB的記憶體上限通常是不夠的。 高級方案至少提供3.5 GB,且支援預熱實例以消除冷啟動延遲。
第二步—驗證部署:
//: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門戶中Functions App下的Log Stream以查看容器拉取或啟動錯誤。
如何觸發並測試功能?
一旦Functions App報告Running 狀態,RenderPdf 端點即可準備接受請求。 端點URL遵循根據Functions 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。 打開它以驗證頁面是否正確渲染。
檢查錯誤日誌:導航到Azure門戶,打開Functions App,並在 監控 下選擇 日誌流。 來自context.getLogger() 呼叫的日誌條目會在此處實時顯示,這使得診斷渲染失敗變得簡單明瞭。
接下來的步驟是什麼?
本指南演示了如何將IronPDF for Java部屬在Azure Functions Docker容器中,編寫HTTP觸發功能以將URL渲染為PDF,配置包含所需Linux依賴的Dockerfile,並測試在線端點。 相同的模式擴展到更高級的用例,僅需進行最小的更改。
擴展功能:
- 使用
PdfDocument.renderHtmlAsPdf(htmlString)直接渲染HTML字串而不是URL - 使用IronPDF完整的Java PDF API應用水印,合併多個PDF或新增數位簽名
- 讀取請求標頭或POST主體以傳遞自定HTML內容或渲染選項
提高生產就緒性:
- 切換
authLevel至FUNCTION並定期旋轉功能密鑰 - 使用Azure Key Vault儲存在應用程式設置中引用的所有密鑰
- 配置應用程式洞察以全面觀察呈現延遲和失敗率
- 設置Docker映像更新Webhook,使Azure在推送新映像版本時自動重新部署
探索更多IronPDF for Java指南:
開始免費的IronPDF試用,在評估期內存取所有渲染和操作功能而不帶水印。 準備好部署到生產環境時,查看IronPDF授權選擇以找到適合項目規模的方案。
常見問題
為什麼在 Azure Functions 上需要 Docker 部署 IronPDF?
IronPDF 附帶一個本地 Chromium 渲染引擎,必須在運行時執行二進制文件。Azure Functions Zip 部署無法運行本地二進制文件,因此 Docker 集裝箱映像是唯一支持的部署路徑。
在 Docker 容器內運行 IronPDF 需要哪些 Maven 工件?
需要在 pom.xml 中的兩個工件:com.ironsoftware:ironpdf 用於 Java API 和 com.ironsoftware:ironpdf-engine-linux-x64 用於本地下層 Chromium 引擎。兩者必須共享相同的版本號。
Dockerfile 必須為 IronPDF 安裝哪些 Linux 套件?
The Dockerfile must install 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, xvfb, and libva-dev.
RenderPdf 函式如何運作?
RenderPdf 函式是一個 HTTP 觸發的 Azure Function。它讀取 url 查詢參數,將其傳遞給 PdfDocument.renderUrlAsPdf,並返回帶有 Content-Disposition: attachment 標頭的 PDF 字節,使呼叫者獲得一個可下載的 PDF 文件。
哪種 Azure Functions 託管計劃應用於 IronPDF?
建議使用高級計劃。IronPDF 的 Chromium 引擎需要大量記憶體,通常超過消耗計劃的 1.5 GB 上限。高級計劃至少提供 3.5 GB 並支持預熱實例以消除冷啟動延遲。
為什麼新部署的函式的第一次請求很慢?
冷啟動後的第一次請求可能需要 20–60 秒,因為 Azure 必須提取容器映像,而且 IronPDF 必須初始化其 Chromium 引擎。在同一容器生命周期內的後續請求速度要快得多。高級計劃的預熱實例功能可以消除此延遲。
如何更新現有的 Azure Function App 以使用新的 Docker 映像?
通過更新標籤重建並推送新映像,然後使用新的 --deployment-container-image-name 值再次運行 az functionapp create,或者在 Azure 入口網站的 Function App 部署中心中更新容器設置。
IronPDF 可以在 Azure Function 中渲染 HTML 字串,而不僅僅是 URL 嗎?
可以。將 PdfDocument.renderUrlAsPdf(url) 替換為 PdfDocument.renderHtmlAsPdf(htmlString) 以直接渲染 HTML 字串。函式結構和響應處理保持不變。
如果請求中缺少 url 查詢參數會發生什麼?
該函式會檢查 url 參數是否為 null,並在嘗試任何 PDF 渲染之前返回描述性消息的 HTTP 400 錯誤請求響應。


