Créer un fichier JAR compatible Avec Azure Databricks

Un fichier JAR (Java archive) regroupe du code Java ou Scala pour des déploiements dans les jobs Lakeflow. Cet article traite des exigences de compatibilité JAR et de la configuration de projet pour différents types de calcul.

À un niveau élevé, votre fichier JAR doit répondre aux exigences suivantes en matière de compatibilité :

• Faites correspondre les versions : utilisez le même Kit de développement Java (JDK), Scala et Spark que votre environnement de calcul
• Fournir des dépendances : inclure les bibliothèques requises dans votre fichier JAR ou les installer sur votre calcul
• Utiliser la session Databricks Spark : appel SparkSession.builder().getOrCreate() pour accéder à la session
• Liste verte de votre fichier JAR (calcul standard uniquement) : ajoutez votre fichier JAR à la liste verte.

Architecture de calcul

Le calcul serverless et standard utilise l’architecture Spark Connect pour isoler le code utilisateur et appliquer la gouvernance de Unity Catalog. Databricks Connect permet d’accéder aux API Spark Connect. Le calcul serverless et standard ne prend pas en charge les API Spark Context ou Spark RDD. Consultez les limitations de serverless et les limitations du mode d’accès standard.

Le calcul dédié utilise l’architecture Spark classique et fournit l’accès à toutes les API Spark.

Rechercher vos versions JDK, Scala et Spark

Mettre en correspondance les versions JDK, Scala et Spark s’exécutant sur votre calcul

Lorsque vous générez un fichier JAR, vos versions JDK, Scala et Spark doivent correspondre aux versions exécutées sur votre calcul. Ces trois versions sont interconnectées : la version Spark détermine la version Scala compatible, et les deux dépendent d’une version JDK spécifique.

Procédez comme suit pour rechercher les versions appropriées pour votre type de calcul :

Serverless

1. Utilisez un environnement serverless de version 4 ou ultérieure
2. Recherchez la version de Databricks Connect pour votre environnement dans le tableau des versions d'environnement serverless. La version databricks Connect correspond à votre version Spark.
3. Recherchez les versions JDK, Scala et Spark correspondantes dans la matrice de prise en charge des versions

Norme

1. Cliquez sur Calcul dans la barre latérale et sélectionnez votre calcul pour afficher la version de Databricks Runtime
2. Utilisez une version Databricks Connect qui correspond à la version principale et mineure de Databricks Runtime (par exemple, Databricks Runtime 17.3 → databricks-connect 17.x)
3. Recherchez les versions JDK, Scala et Spark correspondantes dans la matrice de prise en charge des versions. La version databricks Connect correspond à votre version Spark.

Dedicated

1. Cliquez sur Calcul dans la barre latérale et sélectionnez votre calcul pour afficher la version de Databricks Runtime
2. Recherchez les versions JDK, Scala et Spark dans la section Environnement système des notes de publication de votre version databricks Runtime (par exemple, Databricks Runtime 17.3 LTS)

Configuration du projet

Une fois que vous connaissez vos exigences de version, configurez vos fichiers de build et empaquetez votre fichier JAR.

Définir des versions JDK et Scala

Configurez votre fichier de build pour utiliser les versions JDK et Scala appropriées. Les exemples suivants montrent les versions de Databricks Runtime 17.3 LTS et de l’environnement serverless version 4-scala-preview.

Sbt

Dans build.sbt :

scalaVersion := "2.13.16"

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

Maven

Dans 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>

Dépendances Spark

Ajoutez une dépendance Spark pour accéder aux API Spark sans empaqueter Spark dans votre fichier JAR.

Serverless

Utiliser Databricks Connect

Ajoutez une dépendance à Databricks Connect (recommandé). La version Databricks Connect doit correspondre à la version Databricks Connect dans votre environnement serverless. Marquez-le comme provided parce qu'il est inclus dans le temps d'exécution. N’incluez pas de dépendances Apache Spark comme spark-core ou d’autres org.apache.spark artefacts dans votre fichier de build. Databricks Connect fournit toutes les API Spark nécessaires.

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

Vous pouvez effectuer une compilation à spark-sql-api la place de Databricks Connect, mais Databricks recommande d’utiliser Databricks Connect, car les API Spark exécutées sur un calcul serverless peuvent différer légèrement de celles de Spark open source. Ces bibliothèques sont incluses dans le runtime. Par conséquent, marquez-les comme 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"

Mode d’accès standard

Utiliser Databricks Connect

Ajoutez une dépendance à Databricks Connect (recommandé). La version Databricks Connect doit correspondre à la version principale et mineure de Databricks Runtime de votre cluster (par exemple, Databricks Runtime 17.3 → databricks-connect 17.x). Marquez-le comme provided parce qu'il est inclus dans le temps d'exécution. N’incluez pas de dépendances Apache Spark comme spark-core ou d’autres org.apache.spark artefacts dans votre fichier de build. Databricks Connect fournit toutes les API Spark nécessaires.

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

Vous pouvez effectuer une compilation à spark-sql-api la place de Databricks Connect, mais Databricks recommande d’utiliser Databricks Connect, car les API Spark exécutées sur un calcul serverless peuvent différer légèrement de celles de Spark open source. Ces bibliothèques sont incluses dans le runtime. Par conséquent, marquez-les comme 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"

Mode d’accès dédié

Utiliser les API Databricks Connect ou Spark

Ajoutez une dépendance à Databricks Connect (recommandé) ou compilez contre les bibliothèques Spark avec la portée provided.

Option 1 : databricks-connect (recommandé)

Marquez-le comme provided parce qu'il est inclus dans le temps d'exécution.

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

Vous pouvez compiler contre spark-sql-api, mais cela n'est pas recommandé, car la version sur Databricks peut différer légèrement. Ces bibliothèques sont incluses dans le runtime. Par conséquent, marquez-les comme 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 : Autres bibliothèques Spark

Vous pouvez utiliser n’importe quelle bibliothèque Apache Spark (spark-core, spark-sqletc.) avec étendue provided, tant que la version correspond à la version Spark exécutée sur votre cluster. Recherchez la version Spark de votre cluster dans la section Environnement système des notes de publication databricks Runtime.

Dépendances d’application

Ajoutez les bibliothèques requises de votre application à votre fichier de build. La façon dont vous gérez ces éléments dépend de votre type de calcul :

Serverless

Le calcul serverless fournit Databricks Connect et un ensemble limité de dépendances (consultez les notes de publication). Empaquetez toutes les autres bibliothèques de votre fichier JAR à l’aide de sbt-assembly ou du plug-in Maven Shade, ou ajoutez-les à votre environnement serverless.

Par exemple, pour empaqueter une bibliothèque dans votre fichier 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"

Mode d’accès standard

Databricks Runtime inclut de nombreuses bibliothèques courantes au-delà de Spark. Recherchez la liste complète des bibliothèques et versions fournies dans la section Environnement système des notes de publication de Databricks Runtime pour votre version databricks Runtime (par exemple, Databricks Runtime 17.3 LTS).

Pour les bibliothèques fournies par Databricks Runtime, ajoutez-les en tant que dépendances avec étendue provided. Par exemple, dans Databricks Runtime 17.3 LTS, protobuf-java est fourni :

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"

Pour les bibliothèques non fournies par Databricks Runtime, empaquetez-les dans votre fichier JAR à l’aide de sbt-assembly ou du plug-in Maven Shade, ou installez-les en tant que bibliothèques délimitées par le calcul.

Mode d’accès dédié

Databricks Runtime inclut de nombreuses bibliothèques courantes au-delà de Spark. Recherchez la liste complète des bibliothèques et versions fournies dans la section Environnement système des notes de publication de Databricks Runtime pour votre version databricks Runtime (par exemple, Databricks Runtime 17.3 LTS).

Pour les bibliothèques fournies par Databricks Runtime, ajoutez-les en tant que dépendances avec étendue provided. Par exemple, dans Databricks Runtime 17.3 LTS, protobuf-java est fourni :

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"

Pour les bibliothèques non fournies par Databricks Runtime, empaquetez-les dans votre fichier JAR à l’aide de sbt-assembly ou du plug-in Maven Shade, ou installez-les en tant que bibliothèques délimitées par le calcul.

Exigences relatives au code

Lorsque vous écrivez votre code JAR, suivez ces modèles pour garantir la compatibilité avec les travaux Databricks.

Utiliser la session Databricks Spark

Lors de l’exécution d’un fichier JAR dans un travail, vous devez utiliser la session Spark fournie par Azure Databricks. Le code suivant montre comment accéder à la session à partir de votre code :

Java

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

Scala

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

Utiliser try-finally des blocs pour le nettoyage des travaux

Si vous souhaitez qu'un code s'exécute fiablement à la fin de votre travail, par exemple, pour nettoyer les fichiers temporaires, utilisez un bloc try-finally. N’utilisez pas de hook d’arrêt, car ceux-ci ne s’exécutent pas de manière fiable dans les travaux.

Imaginez un fichier JAR constitué de deux parties :

• jobBody() qui contient la partie principale du travail.
• jobCleanup() qui doit s’exécuter après jobBody(), si cette fonction réussit ou retourne une exception.

Par exemple, jobBody() crée des tableaux et jobCleanup() dépose ces tableaux.

Le moyen le plus sûr pour s’assurer que la méthode de nettoyage est bien appelée consiste à placer un bloc try-finally dans le code :

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

N’essayez pas de nettoyer en utilisant sys.addShutdownHook(jobCleanup) ou le code suivant :

// 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 gère les durées de vie des conteneurs Spark de manière à empêcher les hooks de fermeture de s'exécuter de manière fiable.

Lire les paramètres de travail

Databricks transmet des paramètres à votre travail JAR en tant que tableau de chaînes JSON. Pour accéder à ces paramètres, inspectez le tableau String passé dans votre fonction main.

Pour plus d’informations sur les paramètres, consultez Paramètres des travaux.

Configuration supplémentaire

Selon votre type de calcul, vous pouvez avoir besoin d’une configuration supplémentaire :

• Mode d’accès standard : pour des raisons de sécurité, un administrateur doit ajouter des coordonnées et des chemins Maven pour les bibliothèques JAR à une liste verte.
• Calcul serverless : si votre travail accède à des ressources privées (bases de données, API, stockage), configurez la mise en réseau avec une configuration de connectivité réseau (CCN). Consultez la sécurité du réseau sans serveur.

Étapes suivantes

• Découvrez comment utiliser un fichier jar dans un travail.
• Découvrez Databricks Connect.
• Découvrez Scala dans Databricks.