建立 Azure Databricks 相容的 JAR

Java 壓縮檔（JAR）將 Java 或 Scala 程式碼打包，用於部署於 Lakeflow Jobs。本文將介紹不同運算類型的 JAR 相容性需求與專案配置。

小提示

對於自動化部署與持續整合工作流程，請使用 Databricks 資產套件，從帶有預先配置建置與部署設定的範本建立專案。請參考使用 Databricks 的 Asset Bundles 建置 Scala JAR 和將 JAR 檔案上傳到 Unity Catalog 的 Bundle。本文說明手動方法來理解 JAR 需求與自訂配置。

在高層級上，您的 JAR 必須符合下列相容性需求：

版本匹配：使用相同的 Java Development Kit（JDK）、Scala 和 Spark 版本作為你的計算環境
提供相依性：在你的 JAR 中包含必要的函式庫，或將它們安裝在你的電腦上
使用 Databricks 的 Spark 會話：呼叫 SparkSession.builder().getOrCreate() 來存取該會話
將你的 JAR 加入允許清單 （僅限標準運算）：將你的 JAR 加入允許清單

這很重要

無伺服器的 Scala 和 Java 工作目前還在測試階段。你可以用 JAR 任務來部署你的 JAR。如果還沒啟用，請參考管理 Azure Databricks 預覽。

運算架構

無伺服器與標準運算 使用 Spark Connect 架構來隔離使用者程式碼並強制執行 Unity 目錄治理。 Databricks Connect 提供 Spark Connect API 的存取權限。無伺服器和標準運算不支援 Spark Context 或 Spark RDD API。請參見無伺服器限制與標準存取模式限制。

專用運算 採用經典 Spark 架構，並提供所有 Spark API 存取權限。

找到你的 JDK、Scala 和 Spark 版本

匹配你電腦上運行的 JDK、Scala 和 Spark 版本

當你建立 JAR 時，你的 JDK、Scala 和 Spark 版本必須與計算中執行的版本相符。這三個版本彼此連結——Spark 版本決定相容的 Scala 版本，兩者都依賴特定的 JDK 版本。

請依照以下步驟找到適合您計算類型的正確版本：

Serverless

請使用無伺服器環境版本 4 或更高版本
在無伺服器環境版本表中找到你環境的 Databricks Connect 版本。 Databricks Connect 版本對應你的 Spark 版本。
在版本支援矩陣中查找相符的 JDK、Scala 和 Spark 版本

標準

點擊，在側邊欄中選擇計算，然後選擇您的計算資源以查看 Databricks 執行時版本。
使用與 Databricks 執行時主版與次要版本相符的 Databricks Connect 版本（例如 Databricks Runtime 17.3 → databricks-connect 17.x）
在版本支援矩陣中查找相符的 JDK、Scala 和 Spark 版本。 Databricks Connect 版本對應你的 Spark 版本。

專用

點擊，在側邊欄中選擇計算，然後選擇您的計算資源以查看 Databricks 執行時版本。
在 Databricks 執行環境說明的系統環境區塊中找到 JDK、Scala 和 Spark 版本（例如 Databricks Runtime 17.3 LTS）

備註

使用不匹配的 JDK、Scala 或 Spark 版本可能會導致意外行為，或阻礙程式碼執行。

項目設定

一旦你知道版本需求，就設定建置檔並打包你的 JAR。

設定 JDK 與 Scala 版本

設定你的建置檔使用正確的 JDK 和 Scala 版本。以下範例展示了 Databricks Runtime 17.3 LTS 及無伺服器環境版本 4-scala-preview 的版本。

Sbt

在 build.sbt 中：

scalaVersion := "2.13.16"

javacOptions ++= Seq("-source", "17", "-target", "17")

Maven

在 pom.xml 中：

<properties>
  <scala.version>2.13.16</scala.version>
  <scala.binary.version>2.13</scala.binary.version>
  <maven.compiler.source>17</maven.compiler.source>
  <maven.compiler.target>17</maven.compiler.target>
</properties>

火花相依

新增 Spark 的依賴以便在不需要將 Spark 打包到你的 JAR 中的情況下存取 Spark API。

Serverless

使用 Databricks Connect

建議新增對 Databricks Connect 的依賴。 Databricks Connect 的版本必須與你的無伺服器環境中的 Databricks Connect 版本相符。標記為 provided 因為包含在執行時間裡。不要在建置檔中包含 Apache Spark 相依性 spark-core 或其他 org.apache.spark 工件。 Databricks Connect 提供所有必要的 Spark API。

Maven pom.xml：

<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-connect_2.13</artifactId>
  <version>17.0.2</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt：

libraryDependencies += "com.databricks" %% "databricks-connect" % "17.0.2" % "provided"

替代方案：spark-sql-api

你可以對著 spark-sql-api 編譯，而不是使用 Databricks Connect，但 Databricks 建議使用 Databricks Connect，因為在無伺服器計算上運行的 Spark API 可能與開源 Spark 略有不同。這些函式庫包含在執行時中，因此請標記為 provided。

Maven pom.xml：

<dependency>
  <groupId>org.apache.spark</groupId>
  <artifactId>spark-sql-api</artifactId>
  <version>4.0.1</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt：

libraryDependencies += "org.apache.spark" %% "spark-sql-api" % "4.0.1" % "provided"

標準存取模式

使用 Databricks Connect

建議新增對 Databricks Connect 的依賴。 Databricks Connect 版本必須與叢集的主要及次要 Databricks 執行時版本相符（例如 Databricks Runtime 17.3 → databricks-connect 17.x）。標記為 provided 因為包含在執行時間裡。不要在建置檔中包含 Apache Spark 相依性 spark-core 或其他 org.apache.spark 工件。 Databricks Connect 提供所有必要的 Spark API。

Maven pom.xml：

<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-connect_2.13</artifactId>
  <version>17.0.2</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt：

libraryDependencies += "com.databricks" %% "databricks-connect" % "17.0.2" % "provided"

替代方案：spark-sql-api

Maven pom.xml：

<dependency>
  <groupId>org.apache.spark</groupId>
  <artifactId>spark-sql-api</artifactId>
  <version>4.0.1</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt：

libraryDependencies += "org.apache.spark" %% "spark-sql-api" % "4.0.1" % "provided"

專用存取模式

使用 Databricks Connect 或 Spark API

建議新增對 Databricks Connect 的相依性，或針對 Spark 函式庫進行編譯，並設定範圍 provided。

選項一： databricks-connect（推薦）

標記為 provided 因為包含在執行時間裡。

Maven pom.xml：

<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-connect_2.13</artifactId>
  <version>17.0.2</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt：

libraryDependencies += "com.databricks" %% "databricks-connect" % "17.0.2" % "provided"

選項二： spark-sql-api

你可以編譯 spark-sql-api，但不建議這樣做，因為 Databricks 上的版本可能會有些微差異。這些函式庫包含在執行時中，因此請標記為 provided。

Maven pom.xml：

<dependency>
  <groupId>org.apache.spark</groupId>
  <artifactId>spark-sql-api</artifactId>
  <version>4.0.1</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt：

libraryDependencies += "org.apache.spark" %% "spark-sql-api" % "4.0.1" % "provided"

選項三： 其他 Spark 函式庫

你可以使用任何帶有範圍spark-core的 Apache Spark 函式庫（spark-sql、、provided等），只要版本與你叢集上運行的 Spark 版本相符即可。在 Databricks 執行時發布說明的系統環境區塊中找到你叢集的 Spark 版本。

應用程式相依關係

把你應用程式所需的函式庫加入你的建置檔案。如何管理這些取決於你的運算類型：

Serverless

無伺服器運算提供 Databricks Connect 及有限的相依性（詳見發布說明）。用 sbt-assembly 或 Maven Shade Plugin 把所有其他函式庫打包在你的 JAR 裡，或是把它們加入你的無伺服器環境。

例如，要在你的 JAR 中打包一個函式庫：

Maven pom.xml：

<dependency>
  <groupId>io.circe</groupId>
  <artifactId>circe-core_2.13</artifactId>
  <version>0.14.10</version>
</dependency>

sbt build.sbt：

libraryDependencies += "io.circe" %% "circe-core" % "0.14.10"

標準存取模式

Databricks 執行環境包含許多 Spark 以外的常見函式庫。在 Databricks Runtime 發布說明中關於您所使用的 Databricks 執行時版本的系統環境區段（例如 Databricks Runtime 17.3 LTS）中，您可以找到完整的函式庫與版本清單。

對於 Databricks Runtime 所提供的函式庫，請將它們作為具有範圍 provided 的相依關係添加。例如，在 Databricks Runtime 17.3 LTS 中， protobuf-java 提供了：

Maven pom.xml：

<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
  <version>3.25.5</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt：

libraryDependencies += "com.google.protobuf" % "protobuf-java" % "3.25.5" % "provided"

對於 Databricks Runtime 沒有提供的函式庫，要麼用 sbt-assembly 或 Maven Shade Plugin 打包在 JAR 裡，要麼安裝成計算範圍函式庫。

專用存取模式

對於 Databricks Runtime 所提供的函式庫，請將它們作為具有範圍 provided 的相依關係添加。例如，在 Databricks Runtime 17.3 LTS 中， protobuf-java 提供了：

Maven pom.xml：

<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
  <version>3.25.5</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt：

libraryDependencies += "com.google.protobuf" % "protobuf-java" % "3.25.5" % "provided"

對於 Databricks Runtime 沒有提供的函式庫，要麼用 sbt-assembly 或 Maven Shade Plugin 打包在 JAR 裡，要麼安裝成計算範圍函式庫。

法規要求

撰寫 JAR 程式碼時，請遵循以下模式以確保與 Databricks 工作相容。

使用 Databricks 的 Spark 會話

在工作中執行 JAR 時，必須使用 Azure Databricks 提供的 Spark 會話。下列程式碼顯示如何從程式碼存取會話：

JAVA

SparkSession spark = SparkSession.builder().getOrCreate();

Scala

val spark = SparkSession.builder().getOrCreate()

使用 `try-finally` 區塊進行工作清理

例如，如果你想要在工作結束時能穩定執行的程式碼，例如清理暫存檔案，可以使用 try-finally 區塊。請勿使用關機鉤子，因為它們在任務中無法可靠地運行。

請考慮包含兩個部分的 JAR：

jobBody()，其中包含作業的主要部分。
jobCleanup() 該函式必須在 jobBody()之後執行，無論該函式成功還是回傳例外。

例如，jobBody() 建立數據表，jobCleanup() 卸除這些數據表。

確保呼叫清除方法的安全方法是在程式碼中放置 try-finally區塊：

try {
  jobBody()
} finally {
  jobCleanup()
}

不要嘗試使用 sys.addShutdownHook(jobCleanup) 或以下程式碼來清理：

// Do NOT clean up with a shutdown hook like this. This will fail.
val cleanupThread = new Thread { override def run = jobCleanup() }
Runtime.getRuntime.addShutdownHook(cleanupThread)

Azure Databricks 以一種防止關機掛鉤無法穩定運行的方式管理 Spark 容器的生命週期。

讀取工作參數

Databricks 會將參數以 JSON 字串陣列傳遞給你的 JAR 工作。若要存取這些參數，請檢查傳遞至 String 函式的 main 陣列。

如需參數的詳細資訊，請參閱參數化任務。

其他設定

根據你的運算類型，你可能需要額外的設定：

標準存取模式：出於安全考量，管理員必須將 JAR 函式庫的 Maven 座標與路徑加入允許清單。
無伺服器運算：如果你的工作存取私有資源（資料庫、API、儲存），請用網路連接配置（Network Connectivity Configuration，NCC）來配置網路。請參閱無伺服器網路安全。

後續步驟

瞭解如何在工作中使用 JAR 檔案。
瞭解 Databricks Connect。
瞭解 Databricks 中的 Scala。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-30

共用方式為

建立 Azure Databricks 相容的 JAR

運算架構

找到你的 JDK、Scala 和 Spark 版本

Serverless

標準

專用

項目設定

設定 JDK 與 Scala 版本

Sbt

Maven

火花相依

Serverless

標準存取模式

專用存取模式

應用程式相依關係

Serverless

標準存取模式

專用存取模式

法規要求

使用 Databricks 的 Spark 會話

JAVA

Scala

使用 try-finally 區塊進行工作清理

讀取工作參數

其他設定

後續步驟

意見反應

其他資源

使用 `try-finally` 區塊進行工作清理