適用於 Java 的 Databricks SDK

在本文中，您將瞭解如何使用適用於 Java 的 Databricks SDK，將 Azure Databricks 帳戶、工作區和相關資源的作業自動化。 本文補充適用於 Java 自述檔、 API 參考和 範例的 Databricks SDK。

注意

這項功能在 Beta 中，而且可在生產環境中使用。

在 Beta 期間，Databricks 建議您將相依性釘選到程式代碼相依的特定 Databricks SDK for Java 次要版本。 例如，您可以在 Maven 等 pom.xml 檔案中釘選相依性。 如需釘選相依性的詳細資訊，請參閱 相依性機制簡介。

開始之前

開始使用適用於 Java 的 Databricks SDK 之前，您的開發電腦必須具有：

• 已設定 Azure Databricks 驗證 。
• 與 Java 8 或更高版本相容的 Java 開發工具套件 （JDK）。 使用 Databricks SDK for Java 進行持續整合 （CI） 測試，與 Java 版本 8、11、17 和 20 相容。
• 建議使用Java相容的整合開發環境 （IDE）。 Databricks 建議 IntelliJ IDEA。

開始使用適用於 Java 的 Databricks SDK

1. 在專案的檔案中 pom.xml ，指示建置系統相依於適用於 Java 的 Databricks SDK。 若要這樣做，請將下列內容 <dependency> 新增至 pom.xml 檔案的現有 <dependencies> 區段。 <dependencies>如果區段不存在於pom.xml檔案中，您也必須將<dependencies>父元素新增至pom.xml檔案。

   例如，若要在 IntelliJ IDEA 中開啟項目的 pom.xml 檔案，請按兩下 [檢視 > 工具 Windows > 專案]，然後按兩下以開啟 your-project-name> src > pom.xml。

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

   注意

   請務必將 取代 0.0.1 為最新版的 Databricks SDK for Java。 您可以在 Maven 中央存放庫中找到最新版本。

2. 指示您的專案對適用於 Java 的 Databricks SDK 採用宣告的相依性。 例如，在 IntelliJ IDEA 中，於專案的 [專案 ] 工具視窗中，以滑鼠右鍵按兩下專案的根節點，然後按兩下 [ 重載專案]。

3. 新增程式代碼以匯入適用於 Java 的 Databricks SDK，並列出 Azure Databricks 工作區中的所有叢集。 例如，在項目的 Main.java 檔案中，程序代碼可能如下所示：

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

   注意

   透過上述呼叫 WorkspaceClient w = new WorkspaceClient()中未設定任何自變數，Databricks SDK for Java 會使用其預設程式嘗試執行 Azure Databricks 驗證。 若要覆寫此預設行為，請參閱下列 驗證 一節。

4. 建立您的專案。 例如，若要在 IntelliJ IDEA 中執行這項操作，請在主功能表中按兩下 [建 > 置建置專案]。

5. 執行您的主要檔案。 例如，若要在 IntelliJ IDEA 中針對專案的 Main.java 檔案執行這項操作，請在主功能表中按兩下 [ 執行 > 'Main']。

6. 叢集清單隨即出現。 例如，在 IntelliJ IDEA 中，這是在 [ 執行 工具] 視窗中。 若要顯示此工具視窗，請從主功能表單擊 [ 檢視 > 工具窗口 > 執行]。

使用 Azure Databricks 帳戶或工作區驗證適用於 Java 的 Databricks SDK

適用於 Java 的 Databricks SDK 會 實作 Databricks 用戶端統一驗證 標準，這是驗證的合並且一致的架構和程序設計方法。 這種方法有助於使用 Azure Databricks 更集中且可預測的方式來設定和自動化驗證。 它可讓您設定 Databricks 驗證一次，然後在多個 Databricks 工具和 SDK 之間使用該組態，而不需要進一步的驗證組態變更。 如需詳細資訊，包括 Java 中更完整的程式代碼範例，請參閱 Databricks 用戶端整合驗證。

注意

Databricks SDK for Java 尚未實 作 Azure 受控識別驗證。

使用適用於 Java 的 Databricks SDK 初始化 Databricks 驗證的一些可用編碼模式包括：

• 執行下列其中一項動作，使用 Databricks 預設驗證：

  • 建立或識別具有目標 Databricks 驗證類型所需字段的自定義 Databricks 組態配置檔 。 然後將環境變數設定 DATABRICKS_CONFIG_PROFILE 為自定義組態配置檔的名稱。
  • 設定目標 Databricks 驗證類型所需的環境變數。

  然後具現化 ，例如 WorkspaceClient 具有 Databricks 預設驗證的物件，如下所示：

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

• 支援硬式編碼所需的字段，但不建議這麼做，因為它可能會暴露程序代碼中的敏感性資訊，例如 Azure Databricks 個人存取令牌。 下列範例硬式編碼 Azure Databricks 主機和 Databricks 令牌驗證的存取令牌值：

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

另 請參閱 Databricks SDK for Java 自述檔中的驗證 。

搭配 Databricks SDK for Java 使用 Databricks 公用程式和 Java

Databricks 公用程式 提供數個協助程式函式，可讓您輕鬆地有效地使用物件記憶體、鏈結和參數化筆記本，以及處理秘密。 Databricks 提供 適用於 Scala 的 Databricks 公用程式連結庫，您可以使用 Java 程式代碼呼叫，讓您以程式設計方式存取 Databricks 公用程式。

若要使用 Java 程式代碼呼叫 Databricks Utilities for Scala，請執行下列動作：

1. 在您的 Java 專案中，宣告 Databricks SDK for Java 的相依性，如上一節所述。

2. 宣告適用於 Scala 連結庫的 Databricks 公用程式相依性。 若要這樣做，請將下列內容 <dependency> 新增至 pom.xml 檔案的現有 <dependencies> 區段：

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

   注意

   請務必將 取代 0.1.4 為最新版的 Databricks Utilities for Scala 連結庫。 您可以在 Maven 中央存放庫中找到最新版本。

3. 指示您的專案對適用於 Scala 的 Databricks 公用程式採用宣告的相依性。 例如，在 IntelliJ IDEA 中，在專案的 [專案 ] 工具視窗中，按兩下專案的根節點，然後按兩下 [Maven > 重載專案]。

4. 新增程式代碼以匯入，然後呼叫適用於 Scala 的 Databricks 公用程式。 例如，下列程式代碼會將 Unity 目錄磁碟區自動化。 此範例會在工作區內的磁碟區路徑中建立名為 zzz_hello.txt 的檔案、從檔案讀取數據，然後刪除檔案：

   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. 建置專案並執行您的主要檔案。

程式碼範例

下列程式代碼範例示範如何使用適用於 Java 的 Databricks SDK 來建立和刪除叢集、建立作業，以及列出帳戶層級群組。 這些程式代碼範例會使用 Databricks SDK for Java 的預設 Azure Databricks 驗證 程式。

如需其他程式代碼範例，請參閱 GitHub 中 Databricks SDK for Java 存放庫中的 examples 資料夾。

• 建立叢集
  • 建立使用 JDK 17 的叢集
• 永久刪除叢集
• 建立作業
• 列出帳戶層級群組

建立叢集

此程式代碼範例會建立具有指定 Databricks Runtime 版本和叢集節點類型的叢集。 此叢集有一個背景工作角色，且叢集會在閑置時間 15 分鐘後自動終止。

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

建立使用 JDK 17 的叢集

注意

完全支援 JDK 8。 JDK 17 是 Databricks Runtime 13.1 版和更新版本的公開預覽版。

本節提供使用 Java 開發工具包 （JDK） 建立叢集的指南。 瞭解如何使用 JDK 17 建立叢集，以在筆記本和作業中使用 Java。

當您建立叢集時，請將下列環境變數新增至 進階選項 > Spark > 環境變數，以指定叢集針對驅動程式和執行程式使用 JDK 17：

JNAME=zulu17-ca-amd64

永久刪除叢集

此程式代碼範例會從工作區中永久刪除具有指定叢集標識符的叢集。

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

建立作業

此程式代碼範例會建立 Azure Databricks 作業，可用來在指定的叢集上執行指定的筆記本。 當此程式代碼執行時，它會從終端機的使用者取得現有的筆記本路徑、現有的叢集標識碼和相關作業設定。

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

列出帳戶層級群組

此程式代碼範例會列出 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());
    }
  }
}

搭配適用於 Java 的 Databricks SDK 使用 Scala

您可以使用 Scala 專案搭配 Databricks SDK for Java。 開始之前，您的開發計算機必須具有：

• 已設定 Azure Databricks 驗證 。
• 建議使用 Scala 相容的整合開發環境 （IDE）。 Databricks 建議使用 Scala 外掛程式的 IntelliJ IDEA。 這些指示已使用 IntelliJ IDEA Community Edition 2023.3.6 進行測試。 如果您使用不同版本的 IntelliJ IDEA，下列指示可能會有所不同。
• 與 Java 8 或更新版本相容的 Java 開發工具套件 （JDK）。 如果您想要在 Azure Databricks 叢集上執行應用程式或使用連結庫，Databricks 建議您使用符合叢集上 JDK 版本的 JDK 版本。 若要尋找特定 Databricks Runtime 隨附的 JDK 版本，請參閱 Databricks Runtime 版本資訊版本和相容性。 如果您使用 IntelliJ IDEA，您可以選擇現有的本機 JDK 安裝，或在 Scala 專案建立期間在本機安裝新的 JDK。
• Scala 建置工具。 Databricks 建議 sbt。 如果您使用 IntelliJ IDEA，您可以選擇在 sbt Scala 專案建立期間要使用的版本。
• Scala。 如果您想要在 Azure Databricks 叢集上執行應用程式或使用連結庫，Databricks 建議您使用符合叢集上 Scala 版本的 Scala 版本。 若要尋找特定 Databricks Runtime 隨附的 Scala 版本，請參閱 Databricks Runtime 版本資訊版本和相容性。 如果您使用 IntelliJ IDEA，您可以選擇 Scala 專案建立期間要使用的 Scala 版本。

若要設定、建置和執行 Scala 專案：

1. 在專案的檔案中 build.sbt ，將下列程式代碼行新增至檔案結尾，然後儲存盤案，以相依於 Databricks SDK for Java 連結庫：

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

   注意

   請務必將 取代 0.2.0 為最新版的 Databricks SDK for Java 連結庫。 您可以在 Maven 中央存放庫中找到最新版本。

2. 指示您的專案對適用於 Java 的 Databricks SDK 採用宣告的相依性。 例如，在 IntelliJ IDEA 中，按兩下 [ 載入 sbt 變更 通知] 圖示。

3. 新增程式代碼以匯入適用於 Java 的 Databricks SDK，並列出 Azure Databricks 工作區中的所有叢集。 例如，在項目的 Main.scala 檔案中，程序代碼可能如下所示：

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

   注意

   透過上述呼叫 val w = new WorkspaceClient()中未設定任何自變數，Databricks SDK for Java 會使用其預設程式嘗試執行 Azure Databricks 驗證。 若要覆寫此預設行為，請參閱下列 驗證 一節。

4. 建立您的專案。 例如，若要在 IntelliJ IDEA 中執行這項操作，請在主功能表中按兩下 [建 > 置建置專案]。

5. 執行您的主要檔案。 例如，若要在專案的 Main.scala 檔案的 IntelliJ IDEA 中執行這項操作，請在主功能表中，按兩下 [ 執行 > 執行 'Main.scala']。

6. 叢集清單隨即出現。 例如，在 IntelliJ IDEA 中，這是在 [ 執行 工具] 視窗中。 若要顯示此工具視窗，請從主功能表單擊 [ 檢視 > 工具窗口 > 執行]。

搭配適用於 Java 的 Databricks SDK 使用 Databricks 公用程式和 Scala

Databricks 公用程式 提供數個協助程式函式，可讓您輕鬆地有效地使用物件記憶體、鏈結和參數化筆記本，以及處理秘密。 Databricks 提供 適用於 Scala 的 Databricks 公用程式連結庫，可讓您以程序設計方式使用 Scala 存取 Databricks 公用程式。

若要呼叫適用於 Scala 的 Databricks 公用程式，請執行下列動作：

1. 在您的 Scala 專案中，宣告與 Databricks SDK for Java 相依性，如上一節所述。

2. 宣告適用於 Scala 連結庫的 Databricks 公用程式相依性。 例如，在專案的 build.sbt 檔案中，將下列這一行新增至檔案結尾，然後儲存盤案：

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

   注意

   請務必將 取代 0.1.4 為最新版的 Databricks Utilities for Scala 連結庫。 您可以在 Maven 中央存放庫中找到最新版本。

3. 指示您的專案對適用於 Scala 的 Databricks 公用程式採用宣告的相依性。 例如，在 IntelliJ IDEA 中，按兩下 [ 載入 sbt 變更 通知] 圖示。

4. 新增程式代碼以匯入，然後呼叫適用於 Scala 的 Databricks 公用程式。 例如，下列程式代碼會將 Unity 目錄磁碟區自動化。 此範例會在工作區內的磁碟區路徑中建立名為 zzz_hello.txt 的檔案、從檔案讀取數據，然後刪除檔案：

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

   注意

   透過上述呼叫 val dbutils = DBUtils.getDBUtils()中未設定任何自變數，適用於 Scala 的 Databricks Utilities 會使用其預設程式嘗試執行 Azure Databricks 驗證。

   若要覆寫此預設行為，請將具現化 DatabricksCfg 物件當做自變數傳遞至 getDBUtils。 如需詳細資訊，請參閱上述 驗證 一節。

   不過請注意，如果您的程式代碼是在 Databricks Runtime 內執行，則會忽略此 DatabricksCfg 物件。 這是因為在 Databricks Runtime 內執行時，適用於 Scala 的 Databricks 公用程式委派給內建 Databricks 公用程式。

5. 建置專案並執行您的主要檔案。

測試

若要測試程序代碼，請使用Java測試架構，例如 JUnit。 若要在不呼叫 Azure Databricks REST API 端點或變更 Azure Databricks 帳戶或工作區的狀態的情況下，在模擬條件下測試程式代碼，請使用 Java 模擬連結庫，例如 Mockito。

例如，假設下列名為 Helpers.java 的檔案，其中包含 createCluster 傳回新叢集相關信息的函式：

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

並指定下列名為 的檔案，該檔案會 Main.java 呼叫 函 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());
  }
}

下列名為 HelpersTest.java 的檔案會測試函 createCluster 式是否傳回預期的回應。 此測試會模擬 WorkspaceClient 物件、定義模擬對象的設定，然後將模擬物件傳遞至 createCluster 函式，而不是在目標工作區中建立叢集。 然後測試會檢查函式是否傳回新模擬叢集的預期標識碼。

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

其他資源

如需詳細資訊，請參閱

• 適用於 Java 自述檔的數據bricks SDK
• 適用於 Java API 的 Databricks SDK 參考
• 其他程式代碼範例
• Logging
• 長時間執行的作業
• 編頁回應