SDK de Databricks para Java
En este artículo, aprenderá a automatizar las operaciones en cuentas, áreas de trabajo y recursos relacionados de Azure Databricks con el SDK de Databricks para Java. En este artículo se complementa el SDK de Databricks para Java LÉAME, referencia de APIy ejemplos.
Nota:
Esta característica está en fase beta y es posible usarla en producción.
Durante el período beta, Databricks recomienda anclar una dependencia de la versión secundaria específica del SDK de Databricks para Java de la que depende el código. Por ejemplo, puede anclar dependencias en archivos como pom.xml para Maven. Para obtener más información sobre la asignación de dependencias, consulte Introducción al mecanismo de dependencias.
Antes de empezar
Antes de empezar a usar el SDK de Databricks para Java, la máquina de desarrollo debe cumplir con lo siguiente:
- Debe tener configurada la autenticación de Azure Databricks.
- Un kit de desarrollo de Java (JDK) compatible con Java 8 o posterior. Las pruebas de integración continua (CI) con el SDK de Databricks para Java son compatibles con las versiones 8, 11, 17 y 20 de Java.
- Se recomienda un entorno de desarrollo integrado (IDE) compatible con Java. Databricks recomienda IntelliJ IDEA.
Introducción al SDK de Databricks para Java
En el archivo
pom.xmldel proyecto, indique al sistema de compilación que dependa del SDK de Databricks para Java. Para ello, agregue lo siguiente<dependency>a la secciónpom.xmlexistente del archivo<dependencies>. Si la sección<dependencies>aún no existe en el archivopom.xml, también debe agregar el elemento principal<dependencies>al archivopom.xml.Por ejemplo, para abrir el archivo
pom.xmlde su proyecto en IntelliJ IDEA, haga clic en Ver >Herramienta Windows > Proyecto, y luego haga doble clic para abrir your-project-name> src > pom.xml.<dependencies> <dependency> <groupId>com.databricks</groupId> <artifactId>databricks-sdk-java</artifactId> <version>0.0.1</version> </dependency> </dependencies>Nota:
Asegúrese de reemplazar
0.0.1por la versión más reciente del SDK de Databricks para Java. Puede encontrar la versión más reciente en el repositorio central de Maven.Indique al proyecto que tome la dependencia declarada en el SDK de Databricks para Java. Por ejemplo, en IntelliJ IDEA, en la ventana de herramientas del proyecto Project, haga clic con el botón derecho en el proyecto. s nodo raíz y, a continuación, haga clic en Volver a cargar proyecto.
Agregue código para importar el SDK de Databricks para Java y para enumerar todos los clústeres del área de trabajo de Azure Databricks. Por ejemplo, en el archivo
Main.javadel proyecto, el código puede ser el siguiente:import com.databricks.sdk.WorkspaceClient; import com.databricks.sdk.service.compute.ClusterInfo; import com.databricks.sdk.service.compute.ListClustersRequest; public class Main { public static void main(String[] args) { WorkspaceClient w = new WorkspaceClient(); for (ClusterInfo c : w.clusters().list(new ListClustersRequest())) { System.out.println(c.getClusterName()); } } }Nota:
Al no establecer argumentos en la llamada anterior a
WorkspaceClient w = new WorkspaceClient(), el SDK de Databricks para Java utiliza su proceso predeterminado para intentar realizar la autenticación de Azure Databricks. Para invalidar este comportamiento predeterminado, consulte la siguiente sección de autenticación.Compile el proyecto. Por ejemplo, para hacer esto en IntelliJ IDEA, en el menú principal, haga clic en Compilar > Compilar proyecto.
Ejecute el archivo principal. Por ejemplo, para hacer esto en IntelliJ IDEA para el archivo
Main.javadel proyecto, en el menú principal, haga clic en Ejecutar > Ejecutar "Main".Aparecerá la lista de clústeres. Por ejemplo, en IntelliJ IDEA, se encuentra en la ventana de herramientas Ejecutar. Para mostrar esta ventana de herramientas, en el menú principal, haga clic en Ver > Ventanas de herramientas > Ejecutar.
Autenticación del SDK de Databricks para Java con su cuenta o área de trabajo de Azure Databricks
El SDK de Databricks para Java implementa el estándar de autenticación unificada del cliente de Databricks, un enfoque arquitectónico y programático consolidado y coherente para la autenticación. Este enfoque ayuda a configurar y automatizar la autenticación con Azure Databricks de manera más centralizada y predecible. Permite configurar la autenticación de Databricks una vez y, a continuación, usar esa configuración en varias herramientas y SDK de Databricks sin cambios adicionales en la configuración de autenticación. Para obtener más información, incluidos ejemplos de código más completos en Java, consulte Autenticación unificada del cliente de Databricks.
Nota:
El SDK de Databricks para Java aún no ha implementado la autenticación de identidades administradas de Azure.
Entre los patrones de codificación disponibles para inicializar la autenticación de Databricks con el SDK de Databricks para Java se incluyen los siguientes:
Para usar la autenticación predeterminada de Databricks, siga uno de estos procedimientos:
- Cree o identifique un perfil de configuración de Databricks personalizado con los campos necesarios para el tipo de autenticación de Databricks de destino. Luego establezca la variable de entorno
DATABRICKS_CONFIG_PROFILEcon el nombre del perfil de configuración personalizado. - Establezca las variables de entorno necesarias para el tipo de autenticación de Databricks de destino.
A continuación, cree una instancia de un objeto
WorkspaceClient, por ejemplo, con la autenticación predeterminada de Databricks como se indica a continuación:import com.databricks.sdk.WorkspaceClient; // ... WorkspaceClient w = new WorkspaceClient(); // ...- Cree o identifique un perfil de configuración de Databricks personalizado con los campos necesarios para el tipo de autenticación de Databricks de destino. Luego establezca la variable de entorno
Aunque se admite la codificación rígida de los campos obligatorios, no se recomienda porque se corre el riesgo de exponer información confidencial en el código, como los tokens de acceso personal de Azure Databricks. En el ejemplo siguiente se integran como parte del código los valores de host y token de acceso de Azure Databricks para la autenticación de tokens de Databricks:
import com.databricks.sdk.WorkspaceClient; import com.databricks.sdk.core.DatabricksConfig; // ... DatabricksConfig cfg = new DatabricksConfig() .setHost("https://...") .setToken("..."); WorkspaceClient w = new WorkspaceClient(cfg); // ...
Consulte también Autenticación en el SDK de Databricks para Java LÉAME.
Uso de Databricks Utilities y Java con el SDK de Databricks para Java
Databricks Utilities proporciona varias funciones asistentes que facilitan el trabajo con el almacenamiento de objetos de forma eficaz, encadenar y parametrizar cuadernos y trabajar con secretos. Databricks proporciona la biblioteca Databricks Utilities for Scala, a la que se puede llamar con código Java, para permitirle acceder mediante programación a Databricks Utilities.
Para usar código Java para llamar a Databricks Utilities for Scala, siga estos pasos:
En el proyecto de Java, declare una dependencia en el SDK de Databricks para Java, como se describe en la sección anterior.
Declare una dependencia en la biblioteca Databricks Utilities para Scala. Para ello, agregue el siguiente
<dependency>a la sección<dependencies>existente del archivopom.xml:<dependency> <groupId>com.databricks</groupId> <artifactId>databricks-dbutils-scala_2.12</artifactId> <version>0.1.4</version> </dependency>Nota:
Asegúrese de reemplazar
0.1.4por la versión más reciente de la biblioteca Databricks Utilities for Scala. Puede encontrar la versión más reciente en el repositorio central de Maven.Indique al proyecto que tome la dependencia declarada en Databricks Utilities for Scala. Por ejemplo, en IntelliJ IDEA, en la ventana de herramientas Proyecto del proyecto, haga clic en el nodo raíz del proyecto y, a continuación, haga clic en Maven > Reload Project.
Agregue código para realizar la importación y, a continuación, llame a Databricks Utilities for Scala. Por ejemplo, el siguiente código automatiza un volumen de Unity Catalog. En este ejemplo se crea el archivo llamado
zzz_hello.txten la ruta de acceso del volumen dentro del área de trabajo, se leen los datos del archivo y, después, se elimina el archivo:import com.databricks.sdk.core.DatabricksConfig; import com.databricks.sdk.scala.dbutils.DBUtils; public class Main { public static void main(String[] args) { String filePath = "/Volumes/main/default/my-volume/zzz_hello.txt"; String fileData = "Hello, Databricks!"; DBUtils dbutils = DBUtils.getDBUtils(new DatabricksConfig().setProfile("DEFAULT")); dbutils.fs().put(filePath, fileData, true); System.out.println(dbutils.fs().head(filePath, 18)); dbutils.fs().rm(filePath, false); } }Compile su proyecto y ejecute el archivo principal.
Ejemplos de código
En los ejemplos de código siguientes se muestra cómo usar el SDK de Databricks para Java para crear y eliminar clústeres, crear trabajos y enumerar los grupos a nivel de cuenta. Estos ejemplos de código usan el SDK de Databricks para el proceso de autenticación predeterminado de Azure Databricks de Java.
Para más ejemplos de código, consulte la carpeta de ejemplos del repositorio del SDK de Databricks para Java en GitHub.
- Crear un clúster
- Eliminación permanente de un clúster
- Creación de un trabajo
- Enumeración de grupos a nivel de cuenta
Crear un clúster
En este ejemplo de código se crea un clúster con la versión de Databricks Runtime y el tipo de nodo de clúster especificados. Este clúster tiene un trabajo y el clúster se finalizará automáticamente después un tiempo de inactividad de 15 minutos.
import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.compute.CreateCluster;
import com.databricks.sdk.service.compute.CreateClusterResponse;
public class Main {
public static void main(String[] args) {
WorkspaceClient w = new WorkspaceClient();
CreateClusterResponse c = w.clusters().create(
new CreateCluster()
.setClusterName("my-cluster")
.setSparkVersion("12.2.x-scala2.12")
.setNodeTypeId("Standard_DS3_v2")
.setAutoterminationMinutes(15L)
.setNumWorkers(1L)
).getResponse();
System.out.println("View the cluster at " +
w.config().getHost() +
"#setting/clusters/" +
c.getClusterId() +
"/configuration\n");
}
}
Creación de un clúster que use JDK 17
Nota:
JDK 8 es totalmente compatible. JDK 17 está en versión preliminar pública para las versiones 13.1 y posteriores de Databricks Runtime.
En esta sección se proporciona una guía para crear un clúster mediante el kit de desarrollo de Java (JDK). Obtenga información sobre cómo crear un clúster con JDK 17 para usar Java en los cuadernos y trabajos.
Al crear un clúster, especifique que el clúster usa JDK 17 para el controlador y el ejecutor agregando la siguiente variable de entorno a Opciones avanzadas > Spark > Variables de entorno:
JNAME=zulu17-ca-amd64
Eliminación permanente de un usuario
En este ejemplo de código, se elimina permanentemente el clúster con el identificador de clúster especificado del área de trabajo.
import com.databricks.sdk.WorkspaceClient;
import java.util.Scanner;
public class Main {
public static void main(String[] args) {
System.out.println("ID of cluster to delete (for example, 1234-567890-ab123cd4):");
Scanner in = new Scanner(System.in);
String c_id = in.nextLine();
WorkspaceClient w = new WorkspaceClient();
w.clusters().permanentDelete(c_id);
}
}
Creación de un trabajo
En este ejemplo de código, se crea un trabajo de Azure Databricks que ejecuta el cuaderno especificado en el clúster especificado. A medida que se ejecuta el código, obtiene la ruta de acceso del cuaderno existente, el id. de clúster existente y la configuración del trabajo relacionado del usuario en el terminal.
import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.jobs.JobTaskSettings;
import com.databricks.sdk.service.jobs.NotebookTask;
import com.databricks.sdk.service.jobs.NotebookTaskSource;
import com.databricks.sdk.service.jobs.CreateResponse;
import com.databricks.sdk.service.jobs.CreateJob;
import java.util.Scanner;
import java.util.Map;
import java.util.Collection;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
System.out.println("Some short name for the job (for example, my-job):");
Scanner in = new Scanner(System.in);
String jobName = in.nextLine();
System.out.println("Some short description for the job (for example, My job):");
String description = in.nextLine();
System.out.println("ID of the existing cluster in the workspace to run the job on (for example, 1234-567890-ab123cd4):");
String existingClusterId = in.nextLine();
System.out.println("Workspace path of the notebook to run (for example, /Users/someone@example.com/my-notebook):");
String notebookPath = in.nextLine();
System.out.println("Some key to apply to the job's tasks (for example, my-key): ");
String taskKey = in.nextLine();
System.out.println("Attempting to create the job. Please wait...");
WorkspaceClient w = new WorkspaceClient();
Map<String, String> map = Map.of("", "");
Collection<JobTaskSettings> tasks = Arrays.asList(new JobTaskSettings()
.setDescription(description)
.setExistingClusterId(existingClusterId)
.setNotebookTask(new NotebookTask()
.setBaseParameters(map)
.setNotebookPath(notebookPath)
.setSource(NotebookTaskSource.WORKSPACE))
.setTaskKey(taskKey)
);
CreateResponse j = w.jobs().create(new CreateJob()
.setName(jobName)
.setTasks(tasks)
);
System.out.println("View the job at " +
w.config().getHost() +
"/#job/" +
j.getJobId()
);
}
}
Enumeración de grupos a nivel de cuenta
En este ejemplo de código se enumeran los nombres para mostrar de todos los grupos disponibles en la cuenta de Azure Databricks.
import com.databricks.sdk.AccountClient;
import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.service.iam.Group;
import com.databricks.sdk.service.iam.ListAccountGroupsRequest;
public class Main {
public static void main(String[] args) {
AccountClient a = new AccountClient();
for (Group g : a.groups().list((new ListAccountGroupsRequest()))) {
System.out.println(g.getDisplayName());
}
}
}
Uso de Scala con el SDK de Databricks para Java
Puede utilizar proyectos de Scala con el SDK de Databricks para Java. Antes de comenzar, la máquina de desarrollo debe tener:
- Debe tener configurada la autenticación de Azure Databricks.
- Se recomienda un entorno de desarrollo integrado (IDE) compatible con Scala. Databricks recomienda IntelliJ IDEA con el complemento Scala. Estas instrucciones se probaron con IntelliJ IDEA Community Edition 2023.3.6. Si usa otra versión o edición de IntelliJ IDEA, las instrucciones siguientes pueden variar.
- Un kit de desarrollo de Java (JDK) compatible con Java 8 o superior. Si quiere ejecutar las aplicaciones o usar las bibliotecas en un clúster de Azure Databricks, Databricks recomienda usar una versión de JDK que coincida con la versión de JDK en el clúster. Para encontrar la versión de JDK que se incluye con Databricks Runtime específico, consulte Versiones y compatibilidad de las notas de la versión de Databricks Runtime. Si usa IntelliJ IDEA, puede elegir una instalación de JDK local existente o instalar un nuevo JDK localmente durante la creación del proyecto de Scala.
- Una herramienta de compilación de Scala. Databricks recomienda
sbt. Si usa IntelliJ IDEA, puede elegir la versiónsbtque se utilizará durante la creación del proyecto de Scala. - Scala. Si quiere ejecutar las aplicaciones o usar las bibliotecas en un clúster de Azure Databricks, Databricks recomienda usar una versión de Scala que coincida con la versión de Scala en el clúster. Para encontrar la versión de Scala que se incluye con un Databricks Runtime específico, consulte Versiones y compatibilidad de las notas de la versión de Databricks Runtime. Si usa IntelliJ IDEA, puede elegir la versión de Scala que se usará durante la creación del proyecto de Scala.
Para configurar, compilar y ejecutar el proyecto de Scala:
En el archivo
build.sbtdel proyecto, tome una dependencia del SDK de Databricks para la biblioteca de Java agregando la siguiente línea al final del archivo y, a continuación, guárdelo:libraryDependencies += "com.databricks" % "databricks-sdk-java" % "0.2.0"Nota:
Asegúrese de reemplazar
0.2.0con la versión más reciente del SDK de Databricks para la biblioteca de Java. Puede encontrar la versión más reciente en el repositorio central de Maven.Indique al proyecto que tome la dependencia declarada en el SDK de Databricks para Java. Por ejemplo, en IntelliJ IDEA, haga clic en el icono de notificación Cargar cambios sbt.
Agregue código para importar el SDK de Databricks para Java y para enumerar todos los clústeres del área de trabajo de Azure Databricks. Por ejemplo, en el archivo
Main.scaladel proyecto, el código puede ser el siguiente:import com.databricks.sdk.WorkspaceClient import com.databricks.sdk.service.compute.ListClustersRequest object Main { def main(args: Array[String]): Unit = { val w = new WorkspaceClient() w.clusters().list(new ListClustersRequest()).forEach{ elem => println(elem.getClusterName) } } }Nota:
Al no establecer argumentos en la llamada anterior a
val w = new WorkspaceClient(), el SDK de Databricks para Java utiliza su proceso predeterminado para intentar realizar la autenticación de Azure Databricks. Para invalidar este comportamiento predeterminado, consulte la siguiente sección de autenticación.Compile el proyecto. Por ejemplo, para hacer esto en IntelliJ IDEA, en el menú principal, haga clic en Compilar > Compilar proyecto.
Ejecute el archivo principal. Por ejemplo, para hacer esto en IntelliJ IDEA para el archivo
Main.scaladel proyecto, en el menú principal, haga clic en Ejecutar > Ejecutar "Main.scala".Aparecerá la lista de clústeres. Por ejemplo, en IntelliJ IDEA, se encuentra en la ventana de herramientas Ejecutar. Para mostrar esta ventana de herramientas, en el menú principal, haga clic en Ver > Ventanas de herramientas > Ejecutar.
Uso de Databricks Utilities y Scala con el SDK de Databricks para Java
Databricks Utilities proporciona varias funciones asistentes que facilitan el trabajo con el almacenamiento de objetos de forma eficaz, encadenar y parametrizar cuadernos y trabajar con secretos. Databricks proporciona la biblioteca Databricks Utilities for Scala, que le permite acceder mediante programación a Databricks Utilities.
Para llamar a Databricks Utilities for Scala, siga estos pasos:
En el proyecto de Scala, declare una dependencia en el SDK de Databricks para Java, como se describe en la sección anterior.
Declare una dependencia en la biblioteca Databricks Utilities para Scala. Por ejemplo, en el archivo
build.sbtdel proyecto, agregue la siguiente línea al final del archivo y, después, guarde el archivo:libraryDependencies += "com.databricks" % "databricks-dbutils-scala_2.12" % "0.1.4"Nota:
Asegúrese de reemplazar
0.1.4por la versión más reciente de la biblioteca Databricks Utilities for Scala. Puede encontrar la versión más reciente en el repositorio central de Maven.Indique al proyecto que tome la dependencia declarada en Databricks Utilities for Scala. Por ejemplo, en IntelliJ IDEA, haga clic en el icono de notificación Cargar cambios sbt.
Agregue código para realizar la importación y, a continuación, llame a Databricks Utilities for Scala. Por ejemplo, el siguiente código automatiza un volumen de Unity Catalog. En este ejemplo se crea el archivo llamado
zzz_hello.txten la ruta de acceso del volumen dentro del área de trabajo, se leen los datos del archivo y, después, se elimina el archivo:import com.databricks.sdk.scala.dbutils.DBUtils object Main { def main(args: Array[String]): Unit = { val filePath = "/Volumes/main/default/my-volume/zzz_hello.txt" val fileData = "Hello, Databricks!" val dbutils = DBUtils.getDBUtils() dbutils.fs.put( file = filePath, contents = fileData, overwrite = true ) println(dbutils.fs.head(filePath)) dbutils.fs.rm(filePath) } }Nota:
Al no establecer argumentos en la llamada anterior a
val dbutils = DBUtils.getDBUtils(), Databricks Utilities for Scala utiliza su proceso predeterminado para intentar realizar la autenticación de Azure Databricks.Para invalidar este comportamiento predeterminado, pase un objeto
DatabricksCfgdel que se ha creado una instancia como argumento paragetDBUtils. Para más información, consulte la sección sobre autenticación anterior.Sin embargo, tenga en cuenta que si el código se ejecuta dentro Databricks Runtime, este objeto
DatabricksCfgse omite. Esto se debe a que Databricks Utilities for Scala delega a las utilidades de Databricks integradas cuando se ejecutan dentro de Databricks Runtime.Compile su proyecto y ejecute el archivo principal.
Prueba
Para probar el código, use marcos de prueba de Java como JUnit. Para probar el código en condiciones simuladas sin llamar a puntos de conexión de la API de REST de Azure Databricks ni cambiar el estado de las cuentas o áreas de trabajo de Azure Databricks, use bibliotecas simuladas de Java como Mockito.
Por ejemplo, dado el siguiente archivo denominado Helpers.java que contiene una función createCluster que devuelve información sobre el nuevo clúster:
// Helpers.java
import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.compute.CreateCluster;
import com.databricks.sdk.service.compute.CreateClusterResponse;
public class Helpers {
static CreateClusterResponse createCluster(
WorkspaceClient w,
CreateCluster createCluster,
String clusterName,
String sparkVersion,
String nodeTypeId,
Long autoTerminationMinutes,
Long numWorkers
) {
return w.clusters().create(
createCluster
.setClusterName(clusterName)
.setSparkVersion(sparkVersion)
.setNodeTypeId(nodeTypeId)
.setAutoterminationMinutes(autoTerminationMinutes)
.setNumWorkers(numWorkers)
).getResponse();
}
}
Y dado el siguiente archivo denominado Main.java que llama a la función createCluster:
// Main.java
import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.compute.CreateCluster;
import com.databricks.sdk.service.compute.CreateClusterResponse;
public class Main {
public static void main(String[] args) {
WorkspaceClient w = new WorkspaceClient();
// Replace <spark-version> with the target Spark version string.
// Replace <node-type-id> with the target node type string.
CreateClusterResponse c = Helpers.createCluster(
w,
new CreateCluster(),
"My Test Cluster",
"<spark-version>",
"<node-type-id>",
15L,
1L
);
System.out.println(c.getClusterId());
}
}
El siguiente archivo denominado HelpersTest.java comprueba si la función createCluster devuelve la respuesta esperada. En lugar de crear un clúster en el área de trabajo de destino, esta prueba simula un objeto WorkspaceClient, define la configuración del objeto simulado y después pasa el objeto simulado a la función createCluster. A continuación, la prueba comprueba si la función devuelve el nuevo identificador esperado del clúster ficticio.
// HelpersTest.java
import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.mixin.ClustersExt;
import com.databricks.sdk.service.compute.ClusterDetails;
import com.databricks.sdk.service.compute.CreateCluster;
import com.databricks.sdk.support.Wait;
import com.databricks.sdk.service.compute.CreateClusterResponse;
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
import static org.junit.jupiter.api.Assertions.assertEquals;
public class HelpersTest {
@Test
public void testCreateCluster() {
WorkspaceClient mockWorkspaceClient = Mockito.mock(WorkspaceClient.class);
ClustersExt mockClustersExt = Mockito.mock(ClustersExt.class);
CreateCluster mockCreateCluster = new CreateCluster();
Wait<ClusterDetails, CreateClusterResponse> mockWait = Mockito.mock(Wait.class);
CreateClusterResponse mockResponse = Mockito.mock(CreateClusterResponse.class);
Mockito.when(mockWorkspaceClient.clusters()).thenReturn(mockClustersExt);
Mockito.when(mockClustersExt.create(Mockito.any(CreateCluster.class))).thenReturn(mockWait);
Mockito.when(mockWait.getResponse()).thenReturn(mockResponse);
// Replace <spark-version> with the target Spark version string.
// Replace <node-type-id> with the target node type string.
CreateClusterResponse response = Helpers.createCluster(
mockWorkspaceClient,
mockCreateCluster,
"My Test Cluster",
"<spark-version>",
"<node-type-id>",
15L,
1L
);
assertEquals(mockResponse, response);
}
}
Recursos adicionales
Para más información, vea:
- SDK de Databricks para Java LÉAME
- Referencia de la API Databricks SDK para Java
- Ejemplos de código adicionales
- Logging
- Operaciones de larga duración
- Respuestas paginadas