Databricks SDK for Java

项目
03/25/2024

本文介绍如何使用 Databricks SDK for Java 在 Azure Databricks 帐户、工作区和相关资源中自动执行操作。本文是对 Databricks SDK for Java README、API 参考和示例的补充。

注意

此功能现提供 Beta 版本，可用于生产环境。

在 Beta 版本期间，Databricks 建议将依赖项固定到代码所依赖的 Databricks SDK for Java 的特定次要版本。例如，可以在文件中固定依赖项，例如 Maven 的 pom.xml。有关固定依赖项的详细信息，请参阅依赖项机制简介。

开始之前

在开始使用 Databricks SDK for Java 之前，开发计算机必须满足以下要求：

已配置 Azure Databricks 身份验证。
与 Java 8 或更高版本兼容的 Java 开发工具包 (JDK)。使用 Databricks SDK for Java 进行的持续集成 (CI) 测试与 Java 版本 8、11、17 和 20 兼容。
建议使用与 Java 兼容的集成开发环境 (IDE)。 Databricks 建议使用 IntelliJ IDEA。

开始使用 Databricks SDK for Java

在项目的 pom.xml 文件中，指示生成系统依赖于 Databricks SDK for Java。为此，将以下 <dependency> 添加到 pom.xml 文件的现有 <dependencies> 部分。如果 pom.xml 文件中尚不存在 <dependencies> 部分，则还必须将 <dependencies> 父元素添加到 pom.xml 文件中。

例如，若要在 IntelliJ IDEA 中打开项目的 pom.xml 文件，请单击“查看”>“工具窗口”>“项目”，然后双击打开“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 中央存储库中找到最新版本。
指示项目采用对 Databricks SDK for Java 的声明依赖项。例如，在 IntelliJ IDEA 中，在项目的“项目”工具窗口中，单击项目的根节点，然后单击“Maven”>“重新加载项目”。
添加代码以导入 Databricks SDK for Java 并列出 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 身份验证。若要替代此默认行为，请参阅下面的身份验证部分。
生成项目。例如，若要在 IntelliJ IDEA 中执行此操作，请从主菜单中单击“生成”>“生成项目”。
运行 main 文件。例如，若要在 IntelliJ IDEA 中为项目的 Main.java 文件执行此操作，请从主菜单中单击“运行”>“运行 'Main'”。
此时会显示群集列表。例如，在 IntelliJ IDEA 中，它位于“运行”工具窗口中。若要显示此工具窗口，请从主菜单中单击“查看”>“工具窗口”>“运行”。

使用 Azure Databricks 帐户或工作区对 Databricks SDK for Java 进行身份验证

Databricks SDK for Java 实施 Databricks 客户端统一身份验证标准，这是一种整合且一致的体系结构和编程身份验证方法。此方法有助于使 Azure Databricks 的身份验证设置和自动化更加集中和可预测。借助此方法，你只需配置 Databricks 身份验证一次，然后即可在多个 Databricks 工具和 SDK 中使用该配置，而无需进一步更改身份验证配置。有关详细信息，包括更完整的 Java 代码示例，请参阅 Databricks 客户端统一身份验证。

注意

Databricks SDK for Java 尚未实现 Azure 托管标识身份验证。

使用 Databricks SDK for Java 初始化 Databricks 身份验证的一些可用编码模式包括：

通过以下操作之一使用 Databricks 默认身份验证：
- 使用必填字段为目标 Databricks 身份验证类型创建或标识自定义 Databricks 配置文件。然后将 DATABRICKS_CONFIG_PROFILE 环境变量设置为该自定义配置文件的名称。
- 为目标 Databricks 身份验证类型设置所需的环境变量。
然后实例化一个具有 Databricks 默认身份验证的 WorkspaceClient 对象，如下所示：
```
import com.databricks.sdk.WorkspaceClient;
// ...
WorkspaceClient w = new WorkspaceClient();
// ...
```
支持但不建议对必填字段进行硬编码，因为这可能会透露代码中的敏感信息，例如 Azure Databricks 个人访问令牌。以下示例对用于 Databricks 令牌身份验证的 Azure 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 README 中的身份验证。

将 Databricks 实用工具和 Java 与用于 Java 的 Databricks SDK 配合使用

Databricks 实用工具提供多个帮助程序函数，使用户可以轻松地有效地处理对象存储、链接和参数化笔记本，以及处理机密。 Databricks 提供了适用于 Scala 的 Databricks 实用工具库，可以使用 Java 代码调用该库，以便以编程方式访问 Databricks 实用工具。

若要使用 Java 代码调用适用于 Scala 的 Databricks 实用工具，请执行以下操作：

在 Java 项目中，声明对 Databricks SDK for Java 的依赖项，如上一部分所述。
声明对适用于 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 替换为最新版本的适用于 Scala 的 Databricks 实用工具库。可在 Maven 中央存储库中找到最新版本。
指示项目采用对适用于 Scala 的 Databricks 实用工具的声明依赖项。例如，在 IntelliJ IDEA 中，在项目的“项目”工具窗口中，单击项目的根节点，然后单击“Maven”>“重新加载项目”。

添加代码以导入，然后调用适用于 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);
  }
}

生成项目并运行主文件。

代码示例

以下代码示例演示如何使用 Databricks SDK for Java 创建和删除群集、创建作业以及列出帐户级组。这些代码示例使用 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 完全受支持。对于 Databricks Runtime 版本 13.1 及更高版本，JDK 17 以公共预览形式提供。

本部分提供了使用 Java 开发工具包 (JDK) 创建群集的指南。了解如何使用 JDK 17 创建群集，以在笔记本和作业中使用 Java。

创建群集时，指定对驱动程序和执行程序都使用 JDK 17 的群集，方法是将以下环境变量添加到“高级选项”>“Spark”>“环境变量”：

JNAME=zulu17-ca-amd64

永久删除群集

此代码示例从工作区中永久删除具有指定群集 ID 的群集。

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 作业。此代码运行时，它会从终端上的用户获取现有笔记本的路径、现有群集 ID 和相关作业设置。

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

将 Scala 与 Databricks SDK for Java 结合使用

可以将 Scala 项目与 Databricks SDK for Java 结合使用。在开始之前，开发机器必须具备：

已配置 Azure Databricks 身份验证。
建议使用与 Scala 兼容的集成开发环境 (IDE)。 Databricks 建议使用带Scala 插件的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，可以选择要在 Scala 项目创建期间使用的sbt版本。
scala。如果要在 Azure Databricks 群集上运行应用程序或使用库，Databricks 建议使用与群集上的 Scala 版本匹配的 Scala 版本。要查找特定 Databricks Runtime 中附带的 Scala 版本，请参阅 Databricks Runtime 发行说明版本与兼容性。如果使用 IntelliJ IDEA，可以选择要在 Scala 项目创建期间使用的 Scala 版本。

要配置、生成和运行 Scala 项目：

在项目的build.sbt文件中，将以下行添加到文件末尾，然后保存文件，从而依赖于 Databricks SDK for Java 库：
```
libraryDependencies += "com.databricks" % "databricks-sdk-java" % "0.2.0"
```
注意

必须将0.2.0替换为最新版本的 Databricks SDK for Java 库。可在 Maven 中央存储库中找到最新版本。
指示项目采用对 Databricks SDK for Java 的声明依赖项。例如，在 IntelliJ IDEA 中，点击“加载 sbt 更改”通知图标。
添加代码以导入 Databricks SDK for Java 并列出 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 身份验证。若要替代此默认行为，请参阅下面的身份验证部分。
生成项目。例如，若要在 IntelliJ IDEA 中执行此操作，请从主菜单中单击“生成”>“生成项目”。
运行 main 文件。例如，要在 IntelliJ IDEA 中为项目的Main.scala文件执行此操作，请从主菜单中点击“运行>”“运行 'Main.scala'”。
此时会显示群集列表。例如，在 IntelliJ IDEA 中，它位于“运行”工具窗口中。若要显示此工具窗口，请从主菜单中单击“查看”>“工具窗口”>“运行”。

将 Databricks 实用工具和 Scala 与 Databricks SDK for Java 配合使用

Databricks 实用工具提供多个帮助程序函数，使用户可以轻松地有效地处理对象存储、链接和参数化笔记本，以及处理机密。 Databricks 提供了适用于 Scala 的 Databricks 实用工具库，以便能够使用 Scala 以编程方式访问 Databricks 实用工具。

若要调用适用于 Scala 的 Databricks 实用工具，请执行以下操作：

在 Scala 项目中，声明对 Databricks SDK for Java 的依赖项，如上一部分所述。
声明对适用于 Scala 的 Databricks 实用工具的依赖项。例如，在项目的 build.sbt 文件中，将以下行添加到文件末尾，然后保存该文件：
```
libraryDependencies += "com.databricks" % "databricks-dbutils-scala_2.12" % "0.1.4"
```
注意

请务必将 0.1.4 替换为最新版本的适用于 Scala 的 Databricks 实用工具库。可在 Maven 中央存储库中找到最新版本。
指示项目采用对适用于 Scala 的 Databricks 实用工具的声明依赖项。例如，在 IntelliJ IDEA 中，点击“加载 sbt 更改”通知图标。
添加代码以导入，然后调用适用于 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 实用工具将使用其默认进程来尝试执行 Azure Databricks 身份验证。

若要重写此默认行为，请将实例化的 DatabricksCfg 对象作为参数传递给 getDBUtils。有关详细信息，请参阅前面的身份验证部分。

但是，请注意，如果代码在 Databricks Runtime 内部运行，则会忽略此 DatabricksCfg 对象。这是因为在 Databricks Runtime 内部运行时，适用于 Scala 的 Databricks 实用工具会委托给内置 Databricks 实用工具。
生成项目并运行主文件。

其他资源

有关详细信息，请参阅：

Databricks SDK for Java README
Databricks SDK for Java API 参考
其他代码示例
日志记录
长期运行的操作
分页响应