Tworzenie pliku JAR zgodnego z usługą Azure Databricks

Archiwum Java (JAR) pakuje kod Java lub Scala na potrzeby wdrażania w zadaniach Lakeflow. W tym artykule opisano wymagania dotyczące zgodności jar i konfigurację projektu dla różnych typów obliczeniowych.

Na wysokim poziomie plik JAR musi spełniać następujące wymagania dotyczące zgodności:

• Dopasuj wersje: użyj tych samych wersji Java Development Kit (JDK), Scala i Spark co twój system obliczeniowy
• Podaj zależności: uwzględnij wymagane biblioteki w pliku JAR lub zainstaluj je w środowisku obliczeniowym
• Użyj sesji Spark usługi Databricks: Wywołaj SparkSession.builder().getOrCreate() aby uzyskać dostęp do sesji
• Dodaj swój plik JAR do listy dozwolonych (tylko standardowe zasoby obliczeniowe): dodaj plik JAR do listy dozwolonych

Architektura obliczeniowa

Bezserwerowe i standardowe zasoby obliczeniowe używają architektury Spark Connect, w celu zabezpieczenia kodu użytkownika i egzekwowania nadzoru Unity Catalog. Usługa Databricks Connect zapewnia dostęp do interfejsów API programu Spark Connect. Przetwarzanie bezserwerowe i standardowe przetwarzanie danych nie obsługują interfejsów API Spark Context ani interfejsów API Spark RDD. Zobacz ograniczenia bezserwerowe i ograniczenia trybu dostępu standardowego.

Dedykowane zasoby obliczeniowe korzystają z klasycznej architektury Spark i zapewniają dostęp do wszystkich interfejsów API platformy Spark.

Znajdź wersje JDK, Scala i Spark

Dopasuj wersje JDK, Scala i Spark działające w środowisku obliczeniowym.

Podczas tworzenia pliku JAR wersje JDK, Scala i Spark muszą być zgodne z wersjami uruchomionymi na obliczeniach. Te trzy wersje są połączone ze sobą — wersja platformy Spark określa zgodną wersję języka Scala i zależy od określonej wersji zestawu JDK.

Wykonaj następujące kroki, aby znaleźć poprawne wersje dla typu obliczeniowego:

Serverless

1. Korzystanie ze środowiska bezserwerowego w wersji 4 lub nowszej
2. Znajdź wersję programu Databricks Connect dla środowiska w tabeli wersji środowiska bezserwerowego . Wersja programu Databricks Connect odpowiada wersji platformy Spark.
3. Wyszukiwanie pasujących wersji JDK, Scala i Spark w macierzy obsługi wersji

Standard

1. Kliknij Wybierz Obliczenia na pasku bocznym i wybierz swoją instancję obliczeniową, aby wyświetlić wersję Databricks Runtime.
2. Użyj wersji databricks Connect zgodnej z wersją główną i pomocniczą środowiska Databricks Runtime (na przykład Databricks Runtime 17.3 → databricks-connect 17.x)
3. Wyszukaj pasujące wersje JDK, Scala i Spark w macierzy obsługi wersji. Wersja programu Databricks Connect odpowiada wersji platformy Spark.

Dedykowana

1. Kliknij Wybierz Obliczenia na pasku bocznym i wybierz swoją instancję obliczeniową, aby wyświetlić wersję Databricks Runtime.
2. Znajdź wersje JDK, Scala i Spark w sekcji Środowisko systemowe informacji o wersji środowiska databricks Runtime (na przykład Databricks Runtime 17.3 LTS)

Konfiguracja projektu

Gdy znasz wymagania dotyczące wersji, skonfiguruj pliki kompilacji i spakuj plik JAR.

Ustaw wersje JDK i Scala

Skonfiguruj plik kompilacji, aby używał poprawnych wersji zestawów JDK i Scala. W poniższych przykładach pokazano wersje środowiska Databricks Runtime 17.3 LTS oraz środowiska bezserwerowego w wersji 4-scala-preview.

Sbt

W pliku build.sbt:

scalaVersion := "2.13.16"

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

Maven

W pliku 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>

Zależności platformy Spark

Dodaj zależność platformy Spark, aby uzyskać dostęp do interfejsów API platformy Spark bez pakowania platformy Spark w pliku JAR.

Serverless

Korzystanie z usługi Databricks Connect

Dodaj zależność od usługi Databricks Connect (zalecane). Wersja programu Databricks Connect musi być zgodna z wersją programu Databricks Connect w środowisku bezserwerowym. Oznacz go jako provided , ponieważ jest on uwzględniony w środowisku uruchomieniowym. Nie dołączaj zależności platformy Apache Spark, takich jak spark-core lub inne org.apache.spark artefakty w pliku kompilacji. Usługa Databricks Connect udostępnia wszystkie niezbędne interfejsy API platformy Spark.

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"

Alternatywa: spark-sql-api

Możesz kompilować przy użyciu spark-sql-api zamiast Databricks Connect, ale Databricks zaleca korzystanie z Databricks Connect, ponieważ interfejsy API Spark działające na bezserwerowych obliczeniach mogą się nieznacznie różnić od open-source Spark. Te biblioteki są uwzględniane w środowisku uruchomieniowym, dlatego oznacz je jako 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"

Tryb dostępu standardowego

Korzystanie z usługi Databricks Connect

Dodaj zależność od usługi Databricks Connect (zalecane). Wersja Databricks Connect musi być zgodna z główną i drobniejszą wersją środowiska Databricks Runtime dla klastra (na przykład Databricks Runtime 17.3 → databricks-connect 17.x). Oznacz go jako provided , ponieważ jest on uwzględniony w środowisku uruchomieniowym. Nie dołączaj zależności platformy Apache Spark, takich jak spark-core lub inne org.apache.spark artefakty w pliku kompilacji. Usługa Databricks Connect udostępnia wszystkie niezbędne interfejsy API platformy Spark.

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"

Alternatywa: spark-sql-api

Możesz kompilować przy użyciu spark-sql-api zamiast Databricks Connect, ale Databricks zaleca korzystanie z Databricks Connect, ponieważ interfejsy API Spark działające na bezserwerowych obliczeniach mogą się nieznacznie różnić od open-source Spark. Te biblioteki są uwzględniane w środowisku uruchomieniowym, dlatego oznacz je jako 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"

Tryb dedykowanego dostępu

Korzystanie z usługi Databricks Connect lub interfejsów API platformy Spark

Dodaj zależność od usługi Databricks Connect (zalecane) lub skompiluj biblioteki platformy Spark z zakresem provided.

Opcja 1: databricks-connect (zalecane)

Oznacz go jako provided , ponieważ jest on uwzględniony w środowisku uruchomieniowym.

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"

Opcja 2. Spark-sql-api

Można kompilować z spark-sql-api, ale nie jest to zalecane, ponieważ wersja w środowisku Databricks może się nieco różnić. Te biblioteki są uwzględniane w środowisku uruchomieniowym, dlatego oznacz je jako 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"

Opcja 3. Inne biblioteki platformy Spark

Możesz użyć dowolnej biblioteki platformy Apache Spark (spark-core, spark-sqlitp.) z zakresem provided, o ile wersja jest zgodna z wersją platformy Spark uruchomioną w klastrze. Znajdź wersję systemu Spark klastra w sekcji Środowisko systemowe notatek o wydaniu Databricks Runtime.

Zależności aplikacji

Dodaj wymagane biblioteki aplikacji do pliku kompilacji. Sposób zarządzania tymi elementami zależy od typu obliczeniowego:

Serverless

Przetwarzanie bezserwerowe zapewnia program Databricks Connect i ograniczony zestaw zależności (zobacz informacje o wersji). Spakuj wszystkie inne biblioteki w pliku JAR przy użyciu sbt-assembly lub Maven Shade Plugin albo dodaj je do środowiska bezserwerowego.

Aby na przykład spakować bibliotekę w pliku 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"

Tryb dostępu standardowego

Środowisko Databricks Runtime zawiera wiele popularnych bibliotek poza platformą Spark. Znajdź pełną listę udostępnionych bibliotek i wersji w sekcji Środowisko systemowe notatek o wydaniu Databricks Runtime dla wersji Databricks Runtime (na przykład Databricks Runtime 17.3 LTS).

W przypadku bibliotek udostępnianych przez środowisko Databricks Runtime dodaj je jako zależności z zakresem provided. Na przykład w środowisku Databricks Runtime 17.3 LTS, protobuf-java jest dostępny:

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"

W przypadku bibliotek, które nie są dostarczane przez Databricks Runtime, spakuj je w JAR przy użyciu sbt-assembly lub Maven Shade Plugin, albo zainstaluj je jako biblioteki obliczeniowe.

Tryb dedykowanego dostępu

Środowisko Databricks Runtime zawiera wiele popularnych bibliotek poza platformą Spark. Znajdź pełną listę udostępnionych bibliotek i wersji w sekcji Środowisko systemowe notatek o wydaniu Databricks Runtime dla wersji Databricks Runtime (na przykład Databricks Runtime 17.3 LTS).

W przypadku bibliotek udostępnianych przez środowisko Databricks Runtime dodaj je jako zależności z zakresem provided. Na przykład w środowisku Databricks Runtime 17.3 LTS, protobuf-java jest dostępny:

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"

W przypadku bibliotek, które nie są dostarczane przez Databricks Runtime, spakuj je w JAR przy użyciu sbt-assembly lub Maven Shade Plugin, albo zainstaluj je jako biblioteki obliczeniowe.

Wymagania dotyczące kodu

Podczas pisania kodu JAR postępuj zgodnie z tymi wzorcami, aby zapewnić zgodność z zadaniami usługi Databricks.

Użyj sesji Spark Databricks

Podczas uruchamiania pliku JAR w zadaniu należy użyć sesji platformy Spark dostarczonej przez usługę Azure Databricks. Poniższy kod pokazuje, jak uzyskać dostęp do sesji z poziomu kodu:

Java

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

Scala

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

Użyj try-finally bloków do czyszczenia zadań

Jeśli chcesz, aby kod, który niezawodnie uruchamia się na końcu zadania, na przykład w celu oczyszczenia plików tymczasowych, użyj try-finally bloku. Nie używaj haka zamknięcia, ponieważ nie działają one niezawodnie w zadaniach.

Rozważ plik JAR składający się z dwóch części:

• jobBody() który zawiera główną część zadania.
• jobCleanup() który musi być uruchomiony po jobBody() tej funkcji, niezależnie od tego, czy funkcja zakończy się powodzeniem, czy zwróci wyjątek.

Na przykład jobBody() tworzy tabele i jobCleanup() pomija te tabele.

Bezpiecznym sposobem zapewnienia, że wywoływana jest metoda czyszczenia, jest umieszczenie bloku try-finally w kodzie.

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

Nie próbuj czyścić przy użyciu sys.addShutdownHook(jobCleanup) ani przy pomocy następującego kodu:

// 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)

Usługa Azure Databricks zarządza cyklami życia kontenerów platformy Spark w sposób uniemożliwiający niezawodne działanie wyzwalaczy zamykania.

Odczytywanie parametrów zadania

Usługa Databricks przekazuje parametry do zadania JAR jako tablicy ciągów JSON. Aby uzyskać dostęp do tych parametrów, sprawdź tablicę String przekazaną do twojej funkcji main.

Aby uzyskać więcej informacji na temat parametrów, zobacz Parametryzację zadań.

Dodatkowa konfiguracja

W zależności od typu obliczeniowego może być potrzebna dodatkowa konfiguracja:

• Standardowy tryb dostępu: ze względów bezpieczeństwa administrator musi dodać współrzędne i ścieżki programu Maven dla bibliotek JAR do listy dozwolonych.
• Obliczenia bezserwerowe: jeśli zadanie uzyskuje dostęp do zasobów prywatnych (baz danych, interfejsów API, magazynu), skonfiguruj sieć przy użyciu konfiguracji łączności sieciowej (NCC). Zobacz Zabezpieczenia sieci bezserwerowe.

Dalsze kroki

• Dowiedz się, jak wykorzystywać plik jar w projekcie.
• Dowiedz się więcej o usłudze Databricks Connect.
• Dowiedz się więcej o języku Scala w usłudze Databricks.