Databricks SDK för Java

  • Artikel

I den här artikeln får du lära dig hur du automatiserar åtgärder i Azure Databricks-konton, arbetsytor och relaterade resurser med Databricks SDK för Java. Den här artikeln kompletterar Databricks SDK för Java README, API-referens och exempel.

Kommentar

Den här funktionen är i Beta och är okej att använda i produktion.

Under betaperioden rekommenderar Databricks att du fäster ett beroende på den specifika delversionen av Databricks SDK för Java som koden är beroende av. Du kan till exempel fästa beroenden i filer som pom.xml för Maven. Mer information om hur du fäster beroenden finns i Introduktion till beroendemekanismen.

Innan du börjar

Innan du börjar använda Databricks SDK för Java måste utvecklingsdatorn ha:

  • Azure Databricks-autentisering har konfigurerats.
  • Ett Java Development Kit (JDK) som är kompatibelt med Java 8 eller senare. Testning av kontinuerlig integrering (CI) med Databricks SDK för Java är kompatibelt med Java-versionerna 8, 11, 17 och 20.
  • En Java-kompatibel integrerad utvecklingsmiljö (IDE) rekommenderas. Databricks rekommenderar IntelliJ IDEA.

Kom igång med Databricks SDK för Java

  1. I projektets pom.xml fil instruerar du byggsystemet att vara beroende av Databricks SDK för Java. Det gör du genom att lägga till följande <dependency> i pom.xml filens befintliga <dependencies> avsnitt. Om avsnittet <dependencies> inte redan finns i pom.xml filen måste du också lägga till det <dependencies> överordnade elementet i pom.xml filen.

    Om du till exempel vill öppna projektets pom.xml fil i IntelliJ IDEA klickar du på Visa > verktyget Windows > Project och dubbelklickar sedan på för att öppna ditt projektnamn> src > pom.xml.

    <dependencies>
  <dependency>
    <groupId>com.databricks</groupId>
    <artifactId>databricks-sdk-java</artifactId>
    <version>0.0.1</version>
  </dependency>
</dependencies>

    Kommentar

    Ersätt 0.0.1 med den senaste versionen av Databricks SDK för Java. Du hittar den senaste versionen på den centrala Maven-lagringsplatsen.

  2. Instruera projektet att ta det deklarerade beroendet av Databricks SDK för Java. I IntelliJ IDEA högerklickar du till exempel på projektets rotnod i projektets projektverktygsfönster och klickar sedan på Läs in projektet igen.

  3. Lägg till kod för att importera Databricks SDK för Java och för att lista alla kluster på din Azure Databricks-arbetsyta. I ett projekts Main.java fil kan koden till exempel vara följande:

    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());
    }
  }
}

    Kommentar

    Genom att inte ange några argument i föregående anrop till WorkspaceClient w = new WorkspaceClient()använder Databricks SDK för Java sin standardprocess för att försöka utföra Azure Databricks-autentisering. Information om hur du åsidosätter det här standardbeteendet finns i följande autentiseringsavsnitt .

  4. Skapa ditt projekt. Om du till exempel vill göra detta i IntelliJ IDEA klickar du på Skapa > byggprojekt på huvudmenyn.

  5. Kör huvudfilen. Om du till exempel vill göra detta i IntelliJ IDEA för ett projekts Main.java fil klickar du på Kör " > Main" på huvudmenyn.

  6. Listan över kluster visas. I IntelliJ IDEA finns det till exempel i fönstret Kör verktyg. Om du vill visa det här verktygsfönstret går du till huvudmenyn och klickar på Visa > verktyg Windows > Kör.

Autentisera Databricks SDK för Java med ditt Azure Databricks-konto eller din arbetsyta

Databricks SDK för Java implementerar Databricks-klientens enhetliga autentiseringsstandard, en konsoliderad och konsekvent arkitektur- och programmatisk metod för autentisering. Med den här metoden kan du konfigurera och automatisera autentisering med Azure Databricks mer centraliserad och förutsägbar. Det gör att du kan konfigurera Databricks-autentisering en gång och sedan använda den konfigurationen över flera Databricks-verktyg och SDK:er utan ytterligare autentiseringskonfigurationsändringar. Mer information, inklusive mer kompletta kodexempel i Java, finns i Databricks-klientens enhetliga autentisering.

Kommentar

Databricks SDK för Java har ännu inte implementerat Azure-hanterad identitetsautentisering.

Några av de tillgängliga kodningsmönstren för att initiera Databricks-autentisering med Databricks SDK för Java är:

  • Använd Databricks standardautentisering genom att göra något av följande:

    • Skapa eller identifiera en anpassad Databricks-konfigurationsprofil med de obligatoriska fälten för databricks-målautentiseringstypen. Ange DATABRICKS_CONFIG_PROFILE sedan miljövariabeln till namnet på den anpassade konfigurationsprofilen.
    • Ange nödvändiga miljövariabler för databricks-målautentiseringstypen.

    Instansiera till exempel ett WorkspaceClient objekt med Databricks standardautentisering på följande sätt:

    import com.databricks.sdk.WorkspaceClient;
// ...
WorkspaceClient w = new WorkspaceClient();
// ...

  • Hårdkodning av obligatoriska fält stöds men rekommenderas inte, eftersom det riskerar att exponera känslig information i koden, till exempel personliga åtkomsttoken för Azure Databricks. I följande exempel hårdkodas Värden för Azure Databricks och åtkomsttokenvärden för Databricks-tokenautentisering:

    import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost("https://...")
  .setToken("...");
WorkspaceClient w = new WorkspaceClient(cfg);
// ...

Se även Autentisering i Databricks SDK för Java README.

Använda Databricks Utilities och Java med Databricks SDK för Java

Databricks Utilities innehåller flera hjälpfunktioner som gör det enkelt att arbeta med objektlagring effektivt, kedja och parametrisera notebook-filer och arbeta med hemligheter. Databricks tillhandahåller ett Databricks Utilities for Scala-bibliotek , som du kan anropa med Java-kod, så att du kan komma åt Databricks Utilities programmatiskt.

Om du vill använda Java-kod för att anropa Databricks Utilities för Scala gör du följande:

  1. I ditt Java-projekt deklarerar du ett beroende av Databricks SDK för Java, enligt beskrivningen i föregående avsnitt.

  2. Deklarera ett beroende av Databricks Utilities för Scala-biblioteket. Det gör du genom att lägga till följande <dependency> i pom.xml filens befintliga <dependencies> avsnitt:

    <dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-dbutils-scala_2.12</artifactId>
  <version>0.1.4</version>
</dependency>

    Kommentar

    Ersätt 0.1.4 med den senaste versionen av Databricks Utilities för Scala-biblioteket. Du hittar den senaste versionen på den centrala Maven-lagringsplatsen.

  3. Instruera projektet att ta det deklarerade beroendet av Databricks Utilities för Scala. I IntelliJ IDEA går du till exempel till projektverktygets fönster, klickar på projektets rotnod och klickar sedan på Maven > Läs in projektet igen.

  4. Lägg till kod för import och anropa sedan Databricks-verktyget för Scala. Följande kod automatiserar till exempel en Unity Catalog-volym. Det här exemplet skapar en fil med namnet zzz_hello.txt i volymens sökväg på arbetsytan, läser data från filen och tar sedan bort filen:

    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);
  }
}

  5. Skapa projektet och kör huvudfilen.

Kodexempel

Följande kodexempel visar hur du använder Databricks SDK för Java för att skapa och ta bort kluster, skapa jobb och lista grupper på kontonivå. Dessa kodexempel använder Databricks SDK för Javas standardprocess för Azure Databricks-autentisering.

Ytterligare kodexempel finns i exempelmappen i Databricks SDK för Java-lagringsplatsen i GitHub.

Skapa ett kluster

Det här kodexemplet skapar ett kluster med den angivna Databricks Runtime-versionen och klusternodtypen. Det här klustret har en arbetare och klustret avslutas automatiskt efter 15 minuters inaktivitetstid.

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");
  }
}

Skapa ett kluster som använder JDK 17

Kommentar

JDK 8 stöds fullt ut. JDK 17 finns i offentlig förhandsversion för Databricks Runtime version 13.1 och senare.

Det här avsnittet innehåller en guide för att skapa ett kluster med hjälp av Java Development Kit (JDK). Lär dig hur du skapar ett kluster med JDK 17 för att använda Java i dina notebook-filer och jobb.

När du skapar ett kluster anger du att klustret använder JDK 17 för både drivrutinen och kören genom att lägga till följande miljövariabel i Advanced Options > Spark > Environment Variables:

JNAME=zulu17-ca-amd64

Ta bort ett kluster permanent

Det här kodexemplet tar bort klustret permanent med det angivna kluster-ID:t från arbetsytan.

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);
  }
}

Skapa ett jobb

Det här kodexemplet skapar ett Azure Databricks-jobb som kan användas för att köra den angivna notebook-filen i det angivna klustret. När den här koden körs hämtar den den befintliga notebook-filens sökväg, det befintliga kluster-ID:t och relaterade jobbinställningar från användaren i terminalen.

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()
    );
  }
}

Visa en lista över grupper på kontonivå

I det här kodexemplet visas visningsnamnen för alla tillgängliga grupper i Azure Databricks-kontot.

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());
    }
  }
}

Använda Scala med Databricks SDK för Java

Du kan använda Scala-projekt med Databricks SDK för Java. Innan du börjar måste utvecklingsdatorn ha:

  • Azure Databricks-autentisering har konfigurerats.
  • En Scala-kompatibel integrerad utvecklingsmiljö (IDE) rekommenderas. Databricks rekommenderar IntelliJ IDEA med Scala-plugin-programmet. Dessa instruktioner har testats med IntelliJ IDEA Community Edition 2023.3.6. Om du använder en annan version eller utgåva av IntelliJ IDEA kan följande instruktioner variera.
  • Ett Java Development Kit (JDK) som är kompatibelt med Java 8 eller senare. Om du vill köra dina program eller använda dina bibliotek i ett Azure Databricks-kluster rekommenderar Databricks att du använder en version av JDK som matchar JDK-versionen i klustret. Information om hur du hittar JDK-versionen som ingår i en specifik Databricks Runtime finns i Versionsanmärkningsversioner och kompatibilitet för Databricks Runtime. Om du använder IntelliJ IDEA kan du välja en befintlig lokal JDK-installation eller installera ett nytt JDK lokalt när Scala-projektet skapas.
  • Ett Scala-byggverktyg. Databricks rekommenderar sbt. Om du använder IntelliJ IDEA kan du välja vilken version som sbt ska användas när Scala-projektet skapas.
  • Scala. Om du vill köra dina program eller använda dina bibliotek i ett Azure Databricks-kluster rekommenderar Databricks att du använder en version av Scala som matchar Scala-versionen i klustret. Information om hur du hittar Scala-versionen som ingår i en specifik Databricks Runtime finns i Viktig information om versioner och kompatibilitet för Databricks Runtime. Om du använder IntelliJ IDEA kan du välja den Scala-version som ska användas när Scala-projektet skapas.

Så här konfigurerar, skapar och kör du Ditt Scala-projekt:

  1. I projektets build.sbt fil tar du ett beroende av Databricks SDK för Java-biblioteket genom att lägga till följande rad i slutet av filen och sedan spara filen:

    libraryDependencies += "com.databricks" % "databricks-sdk-java" % "0.2.0"

    Kommentar

    Ersätt 0.2.0 med den senaste versionen av Databricks SDK för Java-biblioteket. Du hittar den senaste versionen på den centrala Maven-lagringsplatsen.

  2. Instruera projektet att ta det deklarerade beroendet av Databricks SDK för Java. I IntelliJ IDEA klickar du till exempel på meddelandeikonen Läs in sbt-ändringar .

  3. Lägg till kod för att importera Databricks SDK för Java och för att lista alla kluster på din Azure Databricks-arbetsyta. I ett projekts Main.scala fil kan koden till exempel vara följande:

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

    Kommentar

    Genom att inte ange några argument i föregående anrop till val w = new WorkspaceClient()använder Databricks SDK för Java sin standardprocess för att försöka utföra Azure Databricks-autentisering. Information om hur du åsidosätter det här standardbeteendet finns i följande autentiseringsavsnitt .

  4. Skapa ditt projekt. Om du till exempel vill göra detta i IntelliJ IDEA klickar du på Skapa > byggprojekt på huvudmenyn.

  5. Kör huvudfilen. Om du till exempel vill göra detta i IntelliJ IDEA för ett projekts Main.scala fil klickar du på Kör Kör > Main.scala på huvudmenyn.

  6. Listan över kluster visas. I IntelliJ IDEA finns det till exempel i fönstret Kör verktyg. Om du vill visa det här verktygsfönstret går du till huvudmenyn och klickar på Visa > verktyg Windows > Kör.

Använda Databricks Utilities och Scala med Databricks SDK för Java

Databricks Utilities innehåller flera hjälpfunktioner som gör det enkelt att arbeta med objektlagring effektivt, kedja och parametrisera notebook-filer och arbeta med hemligheter. Databricks tillhandahåller ett Databricks Utilities för Scala-bibliotek så att du kan komma åt Databricks Utilities via programmering med Scala.

Om du vill anropa Databricks Utilities för Scala gör du följande:

  1. I Ditt Scala-projekt deklarerar du ett beroende av Databricks SDK för Java, enligt beskrivningen i föregående avsnitt.

  2. Deklarera ett beroende av Databricks Utilities för Scala-biblioteket. I till exempel projektets build.sbt fil lägger du till följande rad i slutet av filen och sparar sedan filen:

    libraryDependencies += "com.databricks" % "databricks-dbutils-scala_2.12" % "0.1.4"

    Kommentar

    Ersätt 0.1.4 med den senaste versionen av Databricks Utilities för Scala-biblioteket. Du hittar den senaste versionen på den centrala Maven-lagringsplatsen.

  3. Instruera projektet att ta det deklarerade beroendet av Databricks Utilities för Scala. I IntelliJ IDEA klickar du till exempel på meddelandeikonen Läs in sbt-ändringar .

  4. Lägg till kod för import och anropa sedan Databricks-verktyget för Scala. Följande kod automatiserar till exempel en Unity Catalog-volym. Det här exemplet skapar en fil med namnet zzz_hello.txt i volymens sökväg på arbetsytan, läser data från filen och tar sedan bort filen:

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

    Kommentar

    Genom att inte ange några argument i föregående anrop till val dbutils = DBUtils.getDBUtils()använder Databricks Utilities for Scala sin standardprocess för att försöka utföra Azure Databricks-autentisering.

    Om du vill åsidosätta det här standardbeteendet skickar du ett instansierat DatabricksCfg objekt som ett argument till getDBUtils. Mer information finns i föregående autentiseringsavsnitt .

    Observera dock att om koden körs i Databricks Runtime ignoreras det här DatabricksCfg objektet. Det beror på att Databricks Utilities for Scala delegerar till de inbyggda Databricks-verktygen när de körs i Databricks Runtime.

  5. Skapa projektet och kör huvudfilen.

Testning

Om du vill testa koden använder du Java-testramverk som JUnit. Om du vill testa koden under simulerade förhållanden utan att anropa Azure Databricks REST API-slutpunkter eller ändra tillståndet för dina Azure Databricks-konton eller arbetsytor använder du Java-modellbibliotek som Mockito.

Till exempel med följande fil med namnet Helpers.java som innehåller en createCluster funktion som returnerar information om det nya klustret:

// 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();
  }
}

Och med följande fil med namnet Main.java som anropar createCluster funktionen:

// 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());
  }
}

Följande fil med namnet HelpersTest.java testar om createCluster funktionen returnerar det förväntade svaret. I stället för att skapa ett kluster på målarbetsytan hånar det här testet ett WorkspaceClient objekt, definierar inställningarna för det simulerade objektet och skickar sedan det simulerade objektet till createCluster funktionen. Testet kontrollerar sedan om funktionen returnerar det nya simulerade klustrets förväntade ID.

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

Ytterligare resurser

Mer information finns i: