Erstellen eines mit Azure Databricks kompatiblen JAR

Ein Java-Archiv (JAR) packt Java- oder Scala-Code für die Bereitstellung in Lakeflow-Aufträgen. In diesem Artikel werden JAR-Kompatibilitätsanforderungen und Projektkonfigurationen für verschiedene Computetypen behandelt.

Auf hoher Ebene muss Ihr JAR die folgenden Anforderungen für die Kompatibilität erfüllen:

• Abgleich der Versionen: Verwenden Sie dasselbe Java Development Kit (JDK), dieselben Scala- und Spark-Versionen wie Ihre Rechnerumgebung.
• Bereitstellen von Abhängigkeiten: Schließen Sie erforderliche Bibliotheken in Ihr JAR ein, oder installieren Sie sie auf der Berechnung.
• Verwenden der Databricks Spark-Sitzung: SparkSession.builder().getOrCreate() auf die Sitzung zugreifen
• Zulassungsliste Ihres JAR (nur Standardberechnung): Fügen Sie Ihre JAR zur Zulassungsliste hinzu.

Rechnerarchitektur

Serverlose und Standard-Rechenressourcen verwenden die Spark Connect-Architektur, um Benutzercode zu isolieren und die Governance des Unity Catalogs durchzusetzen. Databricks Connect bietet Zugriff auf Spark Connect-APIs. Serverlose und Standardmäßige Compute unterstützen keine Spark-Kontext- oder Spark-RDD-APIs. Informieren Sie sich über die Einschränkungen von serverlosen Umgebungen und des Standardzugriffsmodus.

Dedizierte Compute verwendet die klassische Spark-Architektur und bietet Zugriff auf alle Spark-APIs.

Finden Sie Ihre JDK-, Scala- und Spark-Versionen

Passen Sie JDK-, Scala- und Spark-Versionen an, die auf der Berechnung ausgeführt werden.

Wenn Sie ein JAR erstellen, müssen Ihre JDK-, Scala- und Spark-Versionen mit den Versionen übereinstimmen, die auf Ihrer Berechnung ausgeführt werden. Diese drei Versionen sind miteinander verbunden – die Spark-Version bestimmt die kompatible Scala-Version, und beide hängen von einer bestimmten JDK-Version ab.

Führen Sie die folgenden Schritte aus, um die richtigen Versionen für Ihren Computetyp zu finden:

Serverlos

1. Verwenden der serverlosen Umgebung, Version 4 oder höher
2. Suchen Sie die Databricks Connect-Version für Ihre Umgebung in der Tabelle mit serverlosen Umgebungsversionen . Die Databricks Connect-Version entspricht Ihrer Spark-Version.
3. Suchen der entsprechenden JDK-, Scala- und Spark-Versionen in der Versionsunterstützungsmatrix

Norm

1. Klicken Sie auf In der Seitenleiste, wählen Sie "Compute" und dann Ihren Computer aus, um die Version der Databricks Runtime anzuzeigen.
2. Verwenden Sie eine Databricks Connect-Version, die der Haupt- und Nebenversion der Databricks-Runtime entspricht (z. B. Databricks Runtime 17.3 → databricks-connect 17.x)
3. Suchen Sie die entsprechenden JDK-, Scala- und Spark-Versionen in der Versionsunterstützungsmatrix. Die Databricks Connect-Version entspricht Ihrer Spark-Version.

Dediziert

1. Klicken Sie auf In der Seitenleiste, wählen Sie "Compute" und dann Ihren Computer aus, um die Version der Databricks Runtime anzuzeigen.
2. Suchen Sie die JDK-, Scala- und Spark-Versionen im Abschnitt "Systemumgebung " der Versionshinweise für Ihre Databricks-Runtime-Version (z. B. Databricks Runtime 17.3 LTS)

Projektkonfiguration

Sobald Sie Ihre Versionsanforderungen kennen, konfigurieren Sie Ihre Builddateien und verpacken Sie Ihr JAR.

Festlegen von JDK- und Scala-Versionen

Konfigurieren Sie Ihre Builddatei so, dass die richtigen JDK- und Scala-Versionen verwendet werden. Die folgenden Beispiele zeigen die Versionen für Databricks Runtime 17.3 LTS und die serverlose Umgebungsversion 4-scala-preview.

SBT

In build.sbt:

scalaVersion := "2.13.16"

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

Maven

In 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-Abhängigkeiten

Fügen Sie eine Spark-Abhängigkeit hinzu, um auf Spark-APIs zuzugreifen, ohne Spark in Ihrem JAR zu verpacken.

Serverlos

Verwenden von Databricks Connect

Fügen Sie eine Abhängigkeit von Databricks Connect hinzu (empfohlen). Die Databricks Connect-Version muss mit der Databricks Connect-Version in Ihrer serverlosen Umgebung übereinstimmen. Markieren Sie es als provided, weil es in der Laufzeit enthalten ist. Schließen Sie keine Apache Spark-Abhängigkeiten wie spark-core oder andere org.apache.spark Artefakte in Ihre Builddatei ein. Databricks Connect stellt alle erforderlichen Spark-APIs bereit.

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"

Alternative: spark-sql-api

Sie können gegen spark-sql-api anstelle von Databricks Connect kompilieren, aber Databricks empfiehlt die Verwendung von Databricks Connect, da die Spark-APIs, die auf serverlosen Rechenressourcen ausgeführt werden, leicht von Open Source Spark abweichen können. Diese Bibliotheken sind in der Laufzeit enthalten, also markieren Sie sie als 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"

Standardzugriffsmodus

Verwenden von Databricks Connect

Fügen Sie eine Abhängigkeit von Databricks Connect hinzu (empfohlen). Die Databricks Connect-Version muss mit der Haupt- und Nebenversion der Databricks Runtime Ihres Clusters übereinstimmen (z. B. Databricks Runtime 17.3 → databricks-connect 17.x). Markieren Sie es als provided, weil es in der Laufzeit enthalten ist. Schließen Sie keine Apache Spark-Abhängigkeiten wie spark-core oder andere org.apache.spark Artefakte in Ihre Builddatei ein. Databricks Connect stellt alle erforderlichen Spark-APIs bereit.

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"

Alternative: spark-sql-api

Sie können gegen spark-sql-api anstelle von Databricks Connect kompilieren, aber Databricks empfiehlt die Verwendung von Databricks Connect, da die Spark-APIs, die auf serverlosen Rechenressourcen ausgeführt werden, leicht von Open Source Spark abweichen können. Diese Bibliotheken sind in der Laufzeit enthalten, also markieren Sie sie als 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"

Dedizierter Zugriffsmodus

Verwenden von Databricks Connect- oder Spark-APIs

Fügen Sie eine Abhängigkeit von Databricks Connect (empfohlen) hinzu oder kompilieren Sie Spark-Bibliotheken mit Bereich provided.

Option 1: databricks-connect (empfohlen)

Markieren Sie es als provided, weil es in der Laufzeit enthalten ist.

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"

Option 2: spark-sql-api

Sie können spark-sql-api kompilieren, aber es wird nicht empfohlen, da die Version auf Databricks leicht abweichen kann. Diese Bibliotheken sind in der Laufzeit enthalten, also markieren Sie sie als 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"

Option 3: Andere Spark-Bibliotheken

Sie können jede Apache Spark-Bibliothek (spark-core, spark-sqlusw.) mit Bereich providedverwenden, solange die Version mit der Spark-Version übereinstimmt, die auf Ihrem Cluster ausgeführt wird. Suchen Sie die Spark-Version Ihres Clusters im Abschnitt "Systemumgebung " der Versionshinweise zur Databricks-Runtime.

Anwendungsabhängigkeiten

Fügen Sie die erforderlichen Bibliotheken Ihrer Anwendung zu Ihrer Builddatei hinzu. Wie Sie diese verwalten, hängt von Ihrem Computetyp ab:

Serverlos

Serverless Compute stellt Databricks Connect und eine begrenzte Anzahl von Abhängigkeiten bereit (siehe Versionshinweise). Packen Sie alle anderen Bibliotheken in Ihrem JAR mithilfe der Sbt-Assembly oder des Maven Shade-Plug-Ins, oder fügen Sie sie ihrer serverlosen Umgebung hinzu.

Um beispielsweise eine Bibliothek in Ihrem JAR zu packen:

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"

Standardzugriffsmodus

Die Databricks-Runtime enthält viele gängige Bibliotheken über Spark hinaus. Hier finden Sie die vollständige Liste der bereitgestellten Bibliotheken und Versionen im Abschnitt "System Environment " der Versionshinweise zur Databricks-Runtime für Ihre Databricks-Runtime-Version (z. B. Databricks Runtime 17.3 LTS).

Fügen Sie sie für Bibliotheken, die von databricks Runtime bereitgestellt werden, als Abhängigkeiten mit Bereich providedhinzu. Beispielsweise wird Folgendes in Databricks Runtime 17.3 LTS bereitgestellt: 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"

Für Bibliotheken, die nicht von Databricks Runtime bereitgestellt werden, packen Sie diese entweder mithilfe von sbt-Assembly oder dem Maven Shade Plugin in Ihren JAR, oder installieren Sie sie als computing-spezifische Bibliotheken.

Dedizierter Zugriffsmodus

Die Databricks-Runtime enthält viele gängige Bibliotheken über Spark hinaus. Hier finden Sie die vollständige Liste der bereitgestellten Bibliotheken und Versionen im Abschnitt "System Environment " der Versionshinweise zur Databricks-Runtime für Ihre Databricks-Runtime-Version (z. B. Databricks Runtime 17.3 LTS).

Fügen Sie sie für Bibliotheken, die von databricks Runtime bereitgestellt werden, als Abhängigkeiten mit Bereich providedhinzu. Beispielsweise wird Folgendes in Databricks Runtime 17.3 LTS bereitgestellt: 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"

Für Bibliotheken, die nicht von Databricks Runtime bereitgestellt werden, packen Sie diese entweder mithilfe von sbt-Assembly oder dem Maven Shade Plugin in Ihren JAR, oder installieren Sie sie als computing-spezifische Bibliotheken.

Codeanforderungen

Befolgen Sie beim Schreiben ihres JAR-Codes diese Muster, um die Kompatibilität mit Databricks-Aufträgen sicherzustellen.

Verwenden der Databricks Spark-Sitzung

Wenn Sie einen JAR in einem Auftrag ausführen, müssen Sie die Spark-Sitzung verwenden, die von Azure Databricks bereitgestellt wird. Der folgende Code zeigt, wie Sie über Ihren Code auf die Sitzung zugreifen:

Java

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

Scala

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

Verwenden Sie try-finally Blöcke für die Auftragsbereinigung

Wenn Sie code möchten, der zuverlässig am Ende Ihres Auftrags ausgeführt wird, z. B. um temporäre Dateien zu bereinigen, verwenden Sie einen try-finally Block. Verwenden Sie keinen Shutdown-Hook, da diese in Jobs nicht zuverlässig ausgeführt werden.

Stellen Sie sich eine JAR vor, die aus zwei Teilen besteht:

• jobBody() enthält den Hauptteil des Auftrags.
• jobCleanup() die nach jobBody() ausgeführt werden muss, egal ob jene Funktion erfolgreich ist oder eine Ausnahme zurückgibt.

jobBody() erstellt z. B. Tabellen und jobCleanup() löscht diese Tabellen.

Um sicherzustellen, dass die Aufräummethode aufgerufen wird, können Sie einen try-finally-Block in den Code einfügen:

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

Versuchen Sie nicht, sys.addShutdownHook(jobCleanup) oder den folgenden Code zur Bereinigung zu verwenden.

// 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 verwaltet die Lebensdauern von Spark-Containern so, dass Shutdown-Hooks nicht zuverlässig ausgeführt werden können.

Auftragsparameter lesen

Databricks übergibt Parameter als JSON-Zeichenfolgenarray an Ihren JAR-Auftrag. Um auf diese Parameter zuzugreifen, untersuchen Sie das an Ihre String-Funktion übergebene main-Array.

Weitere Informationen zu Parametern finden Sie unter "Parametrisieren von Aufträgen".

Zusätzliche Konfiguration

Je nach Berechnungstyp benötigen Sie möglicherweise zusätzliche Konfiguration:

• Standardzugriffsmodus: Aus Sicherheitsgründen muss ein Administrator Maven-Koordinaten und Pfade für JAR-Bibliotheken zu einer Zulassungsliste hinzufügen.
• Serverlose Berechnung: Wenn Ihr Auftrag auf private Ressourcen (Datenbanken, APIs, Speicher) zugreift, konfigurieren Sie Netzwerk mit einer Netzwerkkonnektivitätskonfiguration (Network Connectivity Configuration, NCC). Siehe Serverlose Netzwerksicherheit.

Nächste Schritte

• Erfahren Sie, wie Sie ein Glas bei einer Aufgabe verwenden.
• Erfahren Sie mehr über Databricks Connect.
• Erfahren Sie mehr über Scala in Databricks.