创建 Azure Databricks 兼容的 JAR

Java 存档（JAR）打包用于在 Lakeflow 作业中部署的 Java 或 Scala 代码。本文介绍不同计算类型的 JAR 兼容性要求和项目配置。

小窍门

对于自动化部署和持续集成工作流，使用 Databricks Asset Bundles（资产捆绑包）利用带有预配置构建和部署设置的模板创建项目。请参阅使用 Databricks Asset Bundles 构建 Scala JAR和将 JAR 文件上传到 Unity Catalog 的捆绑包。本文介绍用于了解 JAR 要求和自定义配置的手动方法。

概括而言，JAR 必须满足以下兼容性要求：

匹配版本：使用与计算相同的 Java 开发工具包（JDK）、Scala 和 Spark 版本
提供依赖项：在 JAR 中包含所需的库或在计算上安装它们
使用 Databricks Spark 会话：调用 SparkSession.builder().getOrCreate() 以访问会话
将 JAR 加入允许列表 （仅用于标准计算）：将 JAR 添加到允许列表

重要

无服务器 Scala 和 Java 作业处于 Beta 阶段。可以使用 JAR 任务来部署 JAR 文件。如果尚未启用，请参阅管理 Azure Databricks 预览。

计算体系结构

无服务器计算和标准计算 使用 Spark Connect 体系结构来隔离用户代码并强制实施 Unity 目录治理。 Databricks Connect 提供对 Spark Connect API 的访问权限。无服务器和标准计算不支持 Spark 上下文或 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 Runtime 版本。
使用与 Databricks Runtime 主版本和次要版本匹配的 Databricks Connect 版本（例如，Databricks Runtime 17.3 → databricks-connect 17.x）
在版本支持矩阵中查找匹配的 JDK、Scala 和 Spark 版本。 Databricks Connect 版本对应于 Spark 版本。

专属

单击在边栏中选择计算，然后选择您的计算资源以查看 Databricks Runtime 版本。
在 Databricks Runtime 版本的发行说明的“系统环境”部分中查找 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 依赖项以访问 Spark API，而无需在 JAR 中打包 Spark。

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 Runtime 版本匹配（例如，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 的依赖项（建议）或针对作用域 provided的 Spark 库进行编译。

选项 1： 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"

选项 2： 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"

选项 3： 其他 Spark 库

只要版本与群集上运行的 Spark 版本匹配，就可以将任何 Apache Spark 库（spark-corespark-sql等）与范围provided一起使用。在 Databricks Runtime 发行说明的“系统环境”部分中查找群集的 Spark 版本。

应用程序依赖项

将应用程序所需的库添加到生成文件。管理这些方法取决于计算类型：

Serverless

无服务器计算提供 Databricks Connect 和有限的一组依赖项（请参阅发行说明）。使用 sbt 程序集或 Maven 着色插件将 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 Runtime 包括 Spark 以外的许多常见库。在针对您的 Databricks Runtime 版本（例如，Databricks Runtime 17.3 LTS）的 Databricks Runtime 发行说明的“系统环境”部分中，查找提供的库和版本的完整列表。

对于 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、存储），请使用网络连接配置（NCC）配置网络。请参阅无服务器网络安全。

后续步骤

Last updated on 2026-01-26

通过

创建 Azure Databricks 兼容的 JAR

计算体系结构

查找 JDK、Scala 和 Spark 版本

Serverless

标准

专属

项目设置

设置 JDK 和 Scala 版本

Sbt

Maven

Spark 依赖项

Serverless

标准访问模式

专用访问模式

应用程序依赖项

Serverless

标准访问模式

专用访问模式

代码要求

使用 Databricks Spark 会话

Java

Scala

使用 try-finally 块来进行作业清理

读取作业参数

其他配置

后续步骤

其他资源

使用 `try-finally` 块来进行作业清理