Azure Databricks 互換 JAR を作成する

Java アーカイブ (JAR) は、Lakeflow ジョブにデプロイするために Java または Scala コードをパッケージ化します。 JAR 互換性要件を満たし、ターゲット コンピューティングの種類に合わせてプロジェクトを構成します。

大まかに言えば、JAR は互換性のために次の要件を満たす必要があります。

• バージョンの一致: コンピュート環境と同じ Java Development Kit (JDK)、Scala、Spark バージョンを使用する
• 依存関係を提供する: JAR に必要なライブラリを含めるか、コンピューティングにインストールします
• Databricks Spark セッションを使用する: SparkSession.builder().getOrCreate() を呼び出してセッションにアクセスする
• JAR の許可リスト (標準コンピューティングのみ): JAR を許可リストに追加します

コンピューティング アーキテクチャ

サーバーレスコンピューティングと標準コンピューティング では 、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 のバージョンがコンピューティングで実行されているバージョンと一致している必要があります。 これら 3 つのバージョンは相互接続されています。Spark バージョンは互換性のある Scala バージョンを決定し、両方とも特定の JDK バージョンに依存します。

コンピューティングの種類に適したバージョンを見つけるには、次の手順に従います。

Serverless

1. サーバーレス環境バージョン 4 以降を使用する

2. お使いの環境の Databricks Connect のバージョン、JDK、Scala のバージョンを サーバーレス環境のバージョン の表で確認します。

Standard

1. をクリックし、サイドバーのコンピュートを選択して、Databricks Runtime バージョンを確認してください。
2. Databricks Runtime のメジャー バージョンとマイナー バージョン (Databricks Runtime 17.3 → databricks-connect 17.x など) と一致する Databricks Connect バージョンを使用します。 バージョン サポート マトリックスで、対応する JDK と Scala のバージョンを見つけます。

Dedicated

1. をクリックし、サイドバーのコンピュートを選択して、Databricks Runtime バージョンを確認してください。
2. Databricks Runtime バージョン (Databricks Runtime 17.3 LTS など) のリリース ノートのシステム環境セクションで JDK、Scala、Spark のバージョンを確認します

プロジェクトの設定

バージョン要件がわかったら、ビルド ファイルを構成し、JAR をパッケージ化します。

JDK と Scala のバージョンを設定する

適切な JDK と Scala のバージョンを使用するようにビルド ファイルを構成します。 次の例は、Databricks Runtime 17.3 LTS および サーバーレス環境バージョン 4 のバージョンを示しています。

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 をパッケージ化せずに Spark API にアクセスします。

Serverless

Databricks Connect を使用する

Databricks Connect に依存関係を追加します (推奨)。 Databricks Connect のバージョンは、 サーバーレス環境の Databricks Connect バージョンと一致している必要があります。 ランタイムに含まれているため、 provided としてマークします。 spark-coreや他のorg.apache.spark成果物などの Apache Spark 依存関係をビルド ファイルに含めないでください。 Databricks Connect には、必要なすべての Spark API があります。

メイヴン pom.xml:

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

SBT build.sbt:

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

代替手段: spark-sql-api

Databricks Connect ではなく spark-sql-api に対してコンパイルできますが、サーバーレス コンピューティングで実行されている Spark API はオープンソースの Spark とは若干異なる可能性があるため、Databricks Connect の使用をお勧めします。 これらのライブラリはランタイムに含まれているため、 providedとしてマークします。

メイヴン 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 としてマークします。 spark-coreや他のorg.apache.spark成果物などの Apache Spark 依存関係をビルド ファイルに含めないでください。 Databricks Connect には、必要なすべての Spark API があります。

メイヴン pom.xml:

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

SBT build.sbt:

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

代替手段: spark-sql-api

Databricks Connect ではなく spark-sql-api に対してコンパイルできますが、サーバーレス コンピューティングで実行されている Spark API はオープンソースの Spark とは若干異なる可能性があるため、Databricks Connect の使用をお勧めします。 これらのライブラリはランタイムに含まれているため、 providedとしてマークします。

メイヴン 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 を使用する

スコープ providedを使用して、Databricks Connect (推奨) に依存関係を追加するか、Spark ライブラリに対してコンパイルします。

オプション 1: databricks-connect (推奨)

ランタイムに含まれているため、 provided としてマークします。

メイヴン pom.xml:

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

SBT build.sbt:

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

オプション 2: spark-sql-api

spark-sql-apiに対してコンパイルできますが、Databricks のバージョンが若干異なる場合があるため、これはお勧めしません。 これらのライブラリはランタイムに含まれているため、 providedとしてマークします。

メイヴン 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 ライブラリ

任意の Apache Spark ライブラリ ( spark-core や spark-sqlなど) をスコープ providedと共に使用できます。そのバージョンがクラスターで実行されている Spark のバージョンと一致している限りです。 Databricks Runtime リリース ノートのシステム環境セクションで、クラスターの Spark バージョンを確認します。

アプリケーションの依存関係

アプリケーションの必要なライブラリをビルド ファイルに追加します。 これらの管理方法は、コンピューティングの種類によって異なります。

Serverless

サーバーレス コンピューティングは、Databricks Connect と限られた依存関係のセットを提供します (リリース ノートを参照)。 sbt-assembly または Maven Shade Plugin を使用して JAR 内の他のすべてのライブラリをパッケージ化するか、サーバーレス環境に追加します。

たとえば、JAR にライブラリをパッケージ化するには、次のようにします。

メイヴン 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 Runtime 17.3 LTS など) の Databricks Runtime リリース ノートのシステム環境セクションで、提供されているライブラリとバージョンの完全な一覧を確認します。

Databricks Runtime によって提供されるライブラリの場合は、スコープ providedを持つ依存関係として追加します。 たとえば、Databricks Runtime 17.3 LTS では、 protobuf-java が提供されます。

メイヴン 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 ランタイムには、Spark 以外の多くの共通ライブラリが含まれています。 Databricks Runtime バージョン (Databricks Runtime 17.3 LTS など) の Databricks Runtime リリース ノートのシステム環境セクションで、提供されているライブラリとバージョンの完全な一覧を確認します。

Databricks Runtime によって提供されるライブラリの場合は、スコープ providedを持つ依存関係として追加します。 たとえば、Databricks Runtime 17.3 LTS では、 protobuf-java が提供されます。

メイヴン 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 ブロックを使用します。 シャットダウン フックはジョブで確実に実行されないため、使用しないでください。

次の 2 つの部分で構成される 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) を使用してネットワークを構成します。 サーバーレス ネットワーク セキュリティに関する説明を参照してください。

サーバーレス コンピューティングのログ記録を構成する

サーバーレス コンピューティングでは、SLF4J ログ API は既定で no-operation (NOP) バックエンドを使用します。 つまり、SLF4J を使用するライブラリおよびアプリケーション コードからのログ メッセージは、自動的に破棄されます。

SLF4J ログ出力を Log4j 2 バックエンドにルーティングするには、 log4j-slf4j2-impl ブリッジを fat JAR に追加するか、ジョブに対する個別の JAR 依存関係として追加する必要があります。 サーバーレス環境には Log4j 2 バックエンド (log4j-api と log4j-core) が含まれていますが、SLF4J を Log4j に接続するブリッジは、既定ではユーザー クラスパス上にありません。

ブリッジのバージョンは、log4j-apiのバージョンに付属しているバージョンと一致している必要があります。 たとえば、環境バージョン 5 ではバージョン log4j-api2.20.0使用するため、バージョン log4j-slf4j2-impl2.20.0追加する必要があります。

オプション 1: fat JAR にブリッジを含める

log4j-slf4j2-implをコンパイル依存関係として追加して、fat JAR にパッケージ化します。

Sbt

build.sbtの場合:

libraryDependencies += "org.apache.logging.log4j" % "log4j-slf4j2-impl" % "2.20.0"

Maven

pom.xmlの場合:

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-slf4j2-impl</artifactId>
  <version>2.20.0</version>
</dependency>

オプション 2: ジョブに対する別の JAR 依存関係としてブリッジを追加する

FAT JAR にブリッジをパッケージ化する代わりに、JAR タスクを構成するときに別のライブラリ依存関係として追加できます。 [ 環境とライブラリ] のタスク構成で、Maven 座標を使用して JAR 依存関係を追加します。

org.apache.logging.log4j:log4j-slf4j2-impl:2.20.0

サーバーレス ジョブへの JAR 依存関係の追加の詳細については、 サーバーレス環境の構成に関するページを参照してください。

追加リソース

• ジョブで jar を使用する方法について説明します。
• Databricks Connect について説明します。
• Databricks の Scala について説明します。