Compartir a través de

Creación de un ARCHIVO JAR compatible con Azure Databricks

Un archivo java (JAR) empaqueta código Java o Scala para la implementación en trabajos de Lakeflow. En este artículo se tratan los requisitos de compatibilidad de JAR y la configuración del proyecto para diferentes tipos de proceso.

Sugerencia

Para flujos de trabajo de implementación automatizada e integración continua, use Conjuntos de recursos de Databricks para crear un proyecto a partir de una plantilla con opciones de compilación e implementación preconfiguradas. Consulte Compilación de un archivo JAR de Scala mediante conjuntos de recursos de Databricks y Lote que carga un archivo JAR en el catálogo de Unity. En este artículo se describe el enfoque manual para comprender los requisitos de JAR y las configuraciones personalizadas.

En un nivel alto, el archivo JAR debe cumplir los siguientes requisitos de compatibilidad:

  • Versiones de coincidencia: use el mismo Kit de Desarrollo de Java (JDK), Scala y Spark que su entorno de computación.
  • Proporcionar dependencias: incluya las bibliotecas necesarias en un archivo JAR o instálelas en el entorno de ejecución.
  • Uso de la sesión de Spark de Databricks: llamada SparkSession.builder().getOrCreate() para acceder a la sesión
  • Lista de permitidos JAR (sólo para computación estándar): agregue el archivo JAR a la lista de permitidos.

Importante

Los trabajos de Scala y Java sin servidor están en beta. Puede usar tareas JAR para desplegar su archivo JAR. Consulte Administración de versiones preliminares de Azure Databricks si aún no está habilitada.

Arquitectura de computación

El proceso sin servidor y el proceso estándar usan la arquitectura de Spark Connect para aislar el código de usuario y aplicar la gobernanza del catálogo de Unity. Databricks Connect proporciona acceso a las API de Spark Connect. La computación sin servidor y estándar no admite Spark Context ni las API de Spark RDD. Consulte Limitaciones sin servidor y limitaciones del modo de acceso estándar.

El proceso dedicado usa la arquitectura clásica de Spark y proporciona acceso a todas las API de Spark.

Búsqueda de las versiones de JDK, Scala y Spark

Alinea las versiones de JDK, Scala y Spark que se ejecutan en tu entorno de cómputo

Al compilar un archivo JAR, las versiones de JDK, Scala y Spark deben coincidir con las versiones que se ejecutan en el proceso. Estas tres versiones están interconectadas: la versión de Spark determina la versión de Scala compatible y ambas dependen de una versión específica de JDK.

Siga estos pasos para encontrar las versiones correctas para su tipo de cómputo:

Serverless

  1. Uso de la versión 4 o posterior del entorno sin servidor
  2. Busque la versión de Databricks Connect para su entorno en la tabla de versiones de entorno sin servidor . La versión de Databricks Connect corresponde a la versión de Spark.
  3. Busque las versiones de JDK, Scala y Spark coincidentes en la matriz de compatibilidad de versiones.

Estándar

  1. Haga clic en el icono Nube.Cómputo en la barra lateral, y selecciona tu cómputo para ver la versión de Databricks Runtime.
  2. Use una versión de Databricks Connect que coincida con la versión principal y secundaria de Databricks Runtime (por ejemplo, Databricks Runtime 17.3 → databricks-connect 17.x)
  3. Busque las versiones de JDK, Scala y Spark coincidentes en la matriz de compatibilidad de versiones. La versión de Databricks Connect corresponde a la versión de Spark.

Dedicated

  1. Haga clic en el icono Nube.Cómputo en la barra lateral, y selecciona tu cómputo para ver la versión de Databricks Runtime.
  2. Consulte las versiones de JDK, Scala y Spark en la sección Entorno del sistema de las Notas de la Versión para su versión de Databricks Runtime (por ejemplo, Databricks Runtime 17.3 LTS).

Nota:

El uso de versiones de JDK, Scala o Spark no coincidente puede provocar un comportamiento inesperado o impedir que el código se ejecute.

Configuración del proyecto

Una vez que conozca los requisitos de versión, configure los archivos de compilación y empaquete el archivo JAR.

Establecer versiones de JDK y Scala

Configure el archivo de compilación para usar las versiones correctas de JDK y Scala. En los ejemplos siguientes se muestran las versiones de Databricks Runtime 17.3 LTS y la versión 4-scala-preview del entorno sin servidor.

Sbt

En build.sbt:

scalaVersion := "2.13.16"

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

Maven

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

Dependencias de Spark

Agregue una dependencia de Spark para acceder a las API de Spark sin empaquetar Spark en el archivo JAR.

Serverless

Uso de Databricks Connect

Agregue una dependencia en Databricks Connect (recomendado). La versión de Databricks Connect debe coincidir con la versión de Databricks Connect en el entorno sin servidor. Márquelo como provided porque está incluido en el tiempo de ejecución. No incluya dependencias de Apache Spark como spark-core u otros org.apache.spark artefactos en el archivo de compilación. Databricks Connect proporciona todas las API de Spark necesarias.

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"

Alternativa: spark-sql-api

Puede compilar contra spark-sql-api en lugar de Databricks Connect, pero Databricks recomienda usar Databricks Connect porque las API de Spark que se ejecutan en computación sin servidor pueden diferir ligeramente de Spark de código abierto. Estas bibliotecas se incluyen en el tiempo de ejecución, por lo que las marca como 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"

Modo de acceso estándar

Uso de Databricks Connect

Agregue una dependencia en Databricks Connect (recomendado). La versión de Databricks Connect debe coincidir con la versión principal y secundaria de Databricks Runtime del clúster (por ejemplo, Databricks Runtime 17.3 → databricks-connect 17.x). Márquelo como provided porque está incluido en el tiempo de ejecución. No incluya dependencias de Apache Spark como spark-core u otros org.apache.spark artefactos en el archivo de compilación. Databricks Connect proporciona todas las API de Spark necesarias.

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"

Alternativa: spark-sql-api

Puede compilar contra spark-sql-api en lugar de Databricks Connect, pero Databricks recomienda usar Databricks Connect porque las API de Spark que se ejecutan en computación sin servidor pueden diferir ligeramente de Spark de código abierto. Estas bibliotecas se incluyen en el tiempo de ejecución, por lo que las marca como 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"

Modo de acceso dedicado

Uso de Las API de Databricks Connect o Spark

Agregue una dependencia de Databricks Connect (recomendado) o compile en bibliotecas de Spark con ámbito provided.

Opción 1: databricks-connect (recomendado)

Márquelo como provided porque está incluido en el tiempo de ejecución.

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"

Opción 2: spark-sql-api

Puede compilar contra spark-sql-api, pero esto no se recomienda porque la versión de Databricks podría diferir ligeramente. Estas bibliotecas se incluyen en el tiempo de ejecución, por lo que las marca como 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"

Opción 3: Otras bibliotecas de Spark

Puede usar cualquier biblioteca de Apache Spark (spark-core, spark-sql, etc.) con el ámbito provided, siempre y cuando la versión coincida con la versión de Spark que se ejecuta en el clúster. Busque la versión de Spark de su clúster en la sección entorno del sistema de las notas de la versión de Databricks Runtime.

Dependencias de la aplicación

Agregue las bibliotecas necesarias de la aplicación al archivo de compilación. La forma en que los gestione depende de su tipo de computación.

Serverless

El cómputo sin servidor proporciona Databricks Connect y un conjunto limitado de dependencias (consulte las notas de la versión). Empaquete todas las demás bibliotecas del archivo JAR mediante sbt-assembly o Maven Shade Plugin, o agréguelas al entorno sin servidor.

Por ejemplo, para empaquetar una biblioteca en el archivo 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"

Modo de acceso estándar

Databricks Runtime incluye muchas bibliotecas comunes más allá de Spark. Busque la lista completa de bibliotecas y versiones proporcionadas en la sección Entorno del sistema de las notas de lanzamiento de Databricks Runtime para la versión de Databricks Runtime (por ejemplo, Databricks Runtime 17.3 LTS).

En el caso de las bibliotecas proporcionadas por Databricks Runtime, agréguelas como dependencias con el ámbito provided. Por ejemplo, en Databricks Runtime 17.3 LTS, protobuf-java se proporciona:

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"

En el caso de las bibliotecas no proporcionadas por Databricks Runtime, empáquelas en su archivo JAR utilizando sbt-assembly o Maven Shade Plugin, o instálelas como bibliotecas con ámbito de computación.

Modo de acceso dedicado

Databricks Runtime incluye muchas bibliotecas comunes más allá de Spark. Busque la lista completa de bibliotecas y versiones proporcionadas en la sección Entorno del sistema de las notas de lanzamiento de Databricks Runtime para la versión de Databricks Runtime (por ejemplo, Databricks Runtime 17.3 LTS).

En el caso de las bibliotecas proporcionadas por Databricks Runtime, agréguelas como dependencias con el ámbito provided. Por ejemplo, en Databricks Runtime 17.3 LTS, protobuf-java se proporciona:

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"

En el caso de las bibliotecas no proporcionadas por Databricks Runtime, empáquelas en su archivo JAR utilizando sbt-assembly o Maven Shade Plugin, o instálelas como bibliotecas con ámbito de computación.

Requisitos de código

Al escribir el código JAR, siga estos patrones para garantizar la compatibilidad con los trabajos de Databricks.

Utiliza la sesión de Spark de Databricks

Al ejecutar un ARCHIVO JAR en un trabajo, debe usar la sesión de Spark proporcionada por Azure Databricks. En el código siguiente se muestra cómo acceder a la sesión desde tu código.

Java

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

Scala

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

Usar bloques try-finally para la limpieza de trabajos

Si desea que el código se ejecute de forma confiable al final de su trabajo, por ejemplo, para limpiar archivos temporales, use un bloque try-finally. No use un enlace de apagado, ya que no se ejecutan de forma confiable en los trabajos.

Considere un archivo JAR que consta de dos partes:

  • jobBody(), que contiene la parte principal del trabajo.
  • jobCleanup() que debe ejecutarse después de jobBody(), ya sea que esa función se ejecute correctamente o devuelva una excepción.

Por ejemplo, jobBody() crea tablas y jobCleanup() quite esas tablas.

La mejor manera de asegurarse de que se llama al método de limpieza es colocar un bloque try-finally en el código:

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

No intente limpiar con sys.addShutdownHook(jobCleanup) o el código siguiente:

// 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 administra la duración de los contenedores de Spark de una manera que impide que los ganchos de apagado se ejecuten de manera fiable.

Leer parámetros de trabajo

Databricks pasa parámetros al trabajo JAR como una matriz de cadenas en formato JSON. Para acceder a estos parámetros, inspeccione la matriz String que se pasa a la función main.

Para obtener más información sobre los parámetros, consulte Parametrizar trabajos.

Configuración adicional

En función del tipo de computación, es posible que necesitará una configuración adicional.

  • Modo de acceso estándar: por motivos de seguridad, un administrador debe agregar coordenadas y rutas de acceso de Maven para las bibliotecas JAR a una lista de permitidos.
  • Proceso sin servidor: si el trabajo accede a recursos privados (bases de datos, API, almacenamiento), configure las redes con una configuración de conectividad de red (NCC). Consulte Seguridad de red sin servidor.

Pasos siguientes

  • Last updated on