Aller au contenu principal
Dernière mise à jour le

Créer un JAR compatible Databricks

Une archive Java (JAR) regroupe du code Java ou Scala pour un déploiement dans les Lakeflow Jobs. Respectez les exigences de compatibilité JAR et configurez votre projet pour le type de compute cible.

astuce

Pour les workflows de déploiement automatisé et d'intégration continue, utilisez les Declarative Automation Bundles pour créer un projet à partir d'un template avec des paramètres de build et de déploiement préconfigurés. Voir Créer un JAR Scala à l'aide de bundles d'automatisation déclaratifs et Bundle qui upload un fichier JAR dans Unity Catalog. Cette page décrit l'approche manuelle pour comprendre les exigences des JAR et les configurations personnalisées.

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

  • **Faire correspondre les versions** : Utilisez les mêmes versions de Java Development Kit (JDK), Scala et Spark que votre compute
  • **Fournir les dépendances** : Incluez les bibliothèques requises dans votre JAR ou installez-les sur votre compute.
  • Utilisez la session Spark Databricks : Appelez SparkSession.builder().getOrCreate() pour accéder à la session
  • Mettez votre fichier JAR en liste d'autorisation (compute standard uniquement) : Ajoutez votre fichier JAR à la liste d'autorisation
info

Aperçu

Les jobs Serverless Scala et Java sont en aperçu public. Vous pouvez utiliser des tâches JAR pour déployer votre JAR. Consultez Gérer les aperçus Databricks si ce n'est pas déjà activé.

Architecture de compute​

Le compute Serverless et standard utilisent l'architecture Spark Connect pour isoler le code utilisateur et appliquer la gouvernance Unity Catalog. Databricks Connect inclut les APIs Spark Connect. Le compute Serverless et standard ne prennent pas en charge directement les APIs Spark Context ou Spark RDD. Voir les limitations serverless et les limitations du mode d'accès standard.

Le compute dédié utilise l'architecture Spark classique et comprend toutes les Spark API.

Trouver vos versions de JDK, Scala et Spark​

Faites correspondre les versions de JDK, Scala et Spark exécutées sur votre compute.

Lorsque vous créez un JAR, vos versions de JDK, Scala et Spark doivent correspondre aux versions exécutées sur votre compute. 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.

Suivez ces étapes pour trouver les versions correctes pour votre type de compute :

  1. Utilisez la version d'environnement serverless 4 ou supérieure

  2. Recherchez les versions Databricks Connect, JDK et Scala pour votre environnement dans le tableau des versions de l'environnement serverless.

remarque

L'utilisation de versions JDK, Scala ou Spark non concordantes peut entraîner un comportement inattendu ou empêcher votre code de s'exécuter.

Configuration du projet​

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

Définir les versions de JDK et de Scala​

Configurez votre fichier de build pour utiliser les versions de JDK et de Scala correctes. Les exemples suivants présentent les versions de Databricks Runtime 17.3 LTS et la version 4 de l'environnement Serverless.

Dans build.sbt:

Scala
scalaVersion := "2.13.16"

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

Dépendances Spark​

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

Utilisez Databricks Connect

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

Maven pom.xml:

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

sbt build.sbt:

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

Alternative : spark-sql-api

Vous pouvez compiler sur spark-sql-api au lieu de Databricks Connect, mais Databricks recommande d'utiliser Databricks Connect parce que les Spark API s'exécutant sur le compute Serverless peuvent différer légèrement de Spark open source. Ces bibliothèques sont incluses dans le runtime, il faut donc les marquer comme provided.

Maven pom.xml:

XML
<dependency>
  <groupId>org.apache.spark</groupId>
  <artifactId>spark-sql-api</artifactId>
  <version>4.0.1</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt:

Scala
libraryDependencies += "org.apache.spark" %% "spark-sql-api" % "4.0.1" % "provided"

Dépendances d'application​

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

Serverless compute fournit Databricks Connect et un ensemble limité de dépendances (consultez les notes de publication). Packagez toutes les autres bibliothèques dans votre JAR en utilisant sbt-assembly ou Maven Shade Plugin, ou ajoutez-les à votre environnement serverless.

Par exemple, pour regrouper une bibliothèque dans votre JAR :

Maven pom.xml:

XML
<dependency>
  <groupId>io.circe</groupId>
  <artifactId>circe-core_2.13</artifactId>
  <version>0.14.10</version>
</dependency>

sbt build.sbt:

Scala
libraryDependencies += "io.circe" %% "circe-core" % "0.14.10"

Exigences de code​

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

Utilisez la session Spark Databricks​

Lorsque vous exécutez un JAR dans un Job, vous devez utiliser la session Spark fournie par Databricks. Le code suivant montre comment accéder à la session depuis votre code :

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

Utilisez try-finally blocs pour le nettoyage du Job​

Si vous voulez que le code s'exécute de manière fiable à la fin de votre job, par exemple pour nettoyer les fichiers temporaires, utilisez un bloc try-finally. N'utilisez pas de hook d'arrêt, car ils ne s'exécutent pas de manière fiable dans les jobs.

Considérez un JAR qui se compose de deux parties :

  • jobBody() qui contient la partie principale du job.
  • jobCleanup() qui doit s'exécuter après jobBody(), que cette fonction réussisse ou renvoie une exception.

Par exemple, jobBody() crée des tables et jobCleanup() supprime ces tables.

La manière sûre de s'assurer que la méthode de nettoyage est appelée est d'insérer un bloc try-finally dans le code :

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

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

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

Databricks gère la durée de vie des conteneurs Spark d'une manière qui empêche l'exécution fiable des hooks d'arrêt.

Lire les paramètres du job​

Databricks transmet les paramètres à votre job JAR en tant que tableau de chaînes JSON. Pour utiliser ces paramètres, inspectez le tableau String transmis à votre fonction main.

Pour plus de détails sur les paramètres, consultez Paramétrer les jobs.

Configuration supplémentaire​

Selon votre type de compute, vous pourriez avoir besoin d'une configuration supplémentaire :

  • Mode d'accès standard : Pour des raisons de sécurité, un administrateur doit ajouter les coordonnées Maven et les chemins d'accès des bibliothèques JAR à une liste d'autorisation.
  • Compute Serverless : si votre Job accède à des ressources privées (bases de données, APIs, stockage), configurez le réseau avec une configuration de la connectivité réseau (NCC). Voir Sécurité réseau Serverless.

Configurer la journalisation pour le compute serverless​

Sur le compute serverless, l'API de journalisation SLF4J utilise un backend sans opérations (NOP) par default. Cela signifie que les messages de logs des bibliothèques et du code d'application qui utilisent SLF4J sont silencieusement ignorés.

Pour acheminer la sortie des logs SLF4J vers le backend Log4j 2, vous devez ajouter le pont log4j-slf4j2-impl à votre JAR fat ou comme dépendance JAR distincte sur votre Job. L'environnement Serverless inclut le backend Log4j 2 (log4j-api et log4j-core), mais le pont qui connecte SLF4J à Log4j n'est pas sur le classpath de l'utilisateur par default.

La version du pont doit correspondre à la version log4j-api fournie avec votre version de l’environnement serverless. Par exemple, la version 5 de l'environnement utilise log4j-api version 2.20.0, vous devez donc ajouter log4j-slf4j2-impl version 2.20.0.

Option 1 : Incluez le pont dans votre JAR volumineux​

Ajoutez log4j-slf4j2-impl en tant que dépendance de compilation afin qu'il soit packagé dans votre JAR autonome :

Dans build.sbt:

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

Option 2 : Ajoutez le pont comme dépendance JAR distincte au job​

Au lieu d'inclure le pont dans votre JAR fat, vous pouvez l'ajouter en tant que dépendance de bibliothèque distincte lorsque vous configurez votre tâche JAR. Dans la configuration de la tâche sous Environnement et Bibliothèques , ajoutez une dépendance JAR à l’aide de la coordonnée Maven :

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

Pour plus de détails sur l'ajout de dépendances JAR aux jobs Serverless, consultez Configurer l'environnement Serverless.

remarque

N'incluez pas log4j-api ou log4j-core dans votre JAR d'application. Ces bibliothèques sont déjà fournies par l'exécution serverless, et leur regroupement peut entraîner des conflits de version.

Ressources supplémentaires​

Sur cette page