安装适用于 Scala 的 Databricks Connect

本文介绍如何安装适用于 Scala 的 Databricks Connect。 请参阅什么是 Databricks Connect？。 有关本文的 Python 版本，请参阅安装适用于 Python 的 Databricks Connect。

要求

• 目标 Azure Databricks 工作区和群集必须满足 Databricks Connect 群集配置的要求。
• 在开发计算机上安装的 Java 开发工具包 (JDK)。 Databricks 建议使用与 Azure Databricks 群集上的 JDK 版本匹配的 JDK 安装版本。 若要查找群集上的 JDK 版本，请参阅群集的 Databricks Runtime 发行说明的“系统环境”部分。 例如，Zulu 8.70.0.23-CA-linux64 对应 JDK 8。 请参阅 Databricks Runtime 发行说明版本和兼容性。
• 在开发计算机上安装的 Scala。 Databricks 建议使用与 Azure Databricks 群集上的 Scala 版本匹配的 Scala 安装版本。 若要查找群集上的 Scala 版本，请参阅群集的 Databricks Runtime 发行说明的“系统环境”部分。 请参阅 Databricks Runtime 发行说明版本和兼容性。
• 开发计算机上的 Scala 生成工具，例如 sbt。

安装客户端

满足 Databricks Connect 的要求后，请完成以下步骤来设置 Databricks Connect 客户端。

步骤 1：添加对 Databricks Connect 客户端的引用

1. 在 Scala 项目的生成文件（例如 sbt 的 build.sbt、Maven 的 pom.xml 或 Gradle 的 build.gradle）中，将以下引用添加到 Databricks Connect 客户端：

   Sbt

   libraryDependencies += "com.databricks" % "databricks-connect" % "14.0.0"
   

   Maven

   <dependency>
     <groupId>com.databricks</groupId>
     <artifactId>databricks-connect</artifactId>
     <version>14.0.0</version>
   </dependency>
   

   Gradle

   implementation 'com.databricks.databricks-connect:14.0.0'
   

2. 将 14.0.0 替换为与群集上的 Databricks Runtime 版本匹配的 Databricks Connect 库版本。 可以在 Maven 中央存储库中找到 Databricks Connect 库版本号。

第 2 步：配置连接属性

本部分将配置属性以在 Databricks Connect 和远程 Azure Databricks 群集之间建立连接。 这些属性包括用于对群集的 Databricks Connect 进行身份验证的设置。

对于适用于 Databricks Runtime 13.3 LTS 及更高版本的 Databricks Connect，就 Scala 而言，Databricks Connect 包括用于 Java 的 Databricks SDK。 此 SDK 实施 Databricks 客户端统一身份验证标准，这是一种整合且一致的体系结构和编程身份验证方法。 此方法可使 Azure Databricks 的身份验证设置和自动化更加集中和可预测。 借助此方法，你只需配置 Azure Databricks 身份验证一次，然后即可在多个 Azure Databricks 工具和 SDK 中使用该配置，而无需进一步更改身份验证配置。

1. 收集以下配置属性。

   • Azure Databricks 工作区实例名称。 这与群集的服务器主机名值相同；请参阅获取 Azure Databricks 计算资源的连接详细信息。
   • 群集的 ID。 可从 URL 获取群集 ID。 请参阅群集 URL 和 ID。
   • 受支持的 Databricks 身份验证类型所需的任何其他属性。 本部分将通篇介绍这些属性。

2. 在代码中配置连接。 Databricks Connect 按以下顺序搜索配置属性，直到找到这些属性。 找到后，它不再搜索剩余的选项。 下表后面显示了每个选项的详细信息：

   配置属性选项	适用于
   1.DatabricksSession 类的 remote() 方法	仅限 Azure Databricks 个人访问令牌身份验证
   2.一个 Azure Databricks 配置文件	所有 Azure Databricks 身份验证类型
   3.SPARK_REMOTE 环境变量	仅限 Azure Databricks 个人访问令牌身份验证
   4.DATABRICKS_CONFIG_PROFILE 环境变量	所有 Azure Databricks 身份验证类型
   5.每个配置属性具有一个环境变量	所有 Azure Databricks 身份验证类型
   6.一个名为 DEFAULT 的 Azure Databricks 配置文件	所有 Azure Databricks 身份验证类型

   1. DatabricksSession 类的 remote() 方法

      对于仅适用于 Azure Databricks 个人访问令牌身份验证的此选项，请指定工作区实例名称、Azure Databricks 个人访问令牌和群集的 ID。

      可通过多种方式来初始化 DatabricksSession 类，如下所示：

      • 在 DatabricksSession.builder 中设置 host、token 和 clusterId 字段。
      • 使用 Databricks SDK 的 Config 类。
      • 指定 Databricks 配置文件和 clusterId 字段。

      Databricks 不建议在代码中直接指定这些连接属性。 而 Databricks 建议通过环境变量或配置文件来配置属性，如本部分通篇所述。 以下代码示例假定你自己提供建议的 retrieve* 函数的一些实现，以从用户或其他配置存储（例如 Azure 密钥保管库）中获取必要的属性。

      每种方法的代码如下所示：

      // Set the host, token, and clusterId fields in DatabricksSession.builder.
      // If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
      // cluster's ID, you do not also need to set the clusterId field here.
      import com.databricks.connect.DatabricksSession
      
      val spark = DatabricksSession.builder()
        .host(retrieveWorkspaceInstanceName())
        .token(retrieveToken())
        .clusterId(retrieveClusterId())
        .getOrCreate()
      
      // Use the Databricks SDK's Config class.
      // If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
      // cluster's ID, you do not also need to set the clusterId field here.
      import com.databricks.connect.DatabricksSession
      import com.databricks.sdk.core.DatabricksConfig
      
      val config = new DatabricksConfig()
        .setHost(retrieveWorkspaceInstanceName())
        .setToken(retrieveToken())
      val spark = DatabricksSession.builder()
        .sdkConfig(config)
        .clusterId(retrieveClusterId())
        .getOrCreate()
      
      // Specify a Databricks configuration profile along with the clusterId field.
      // If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
      // cluster's ID, you do not also need to set the clusterId field here.
      import com.databricks.connect.DatabricksSession
      import com.databricks.sdk.core.DatabricksConfig
      
      val config = new DatabricksConfig()
        .setProfile("<profile-name>")
      val spark = DatabricksSession.builder()
        .sdkConfig(config)
        .clusterId(retrieveClusterId())
        .getOrCreate()
      

   2. 一个 Azure Databricks 配置文件

      对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及需要使用的支持的 Databricks 身份验证类型所需的任何其他字段。

      每种身份验证类型所需的配置文件字段如下：

      • 适用于 Azure Databricks 个人访问令牌身份验证：host 和 token。

      • 对于 OAuth 用户到计算机 (U2M) 身份验证（在支持的情况下）：host。

      • 对于 Microsoft Entra ID（以前称为 Azure Active Directory）服务主体身份验证：host、azure_tenant_id、azure_client_id、azure_client_secret 和可能的 azure_workspace_resource_id。

      • 适用于 Azure CLI 身份验证：host。

      • 对于 Azure 托管标识身份验证（如果支持）：host、azure_use_msi、azure_client_id 和可能的 azure_workspace_resource_id。

      然后通过 DatabricksConfig 类设置此配置文件的名称。

      可通过多种方式指定 cluster_id，如下所示：

      • 在配置文件中包含 cluster_id 字段，然后只需指定配置文件的名称。
      • 指定配置文件名称和 clusterId 字段。

      如果已使用群集 ID 设置 DATABRICKS_CLUSTER_ID 环境变量，则也无需指定 cluster_id 或 clusterId 字段。

      每种方法的代码如下所示：

      // Include the cluster_id field in your configuration profile, and then
      // just specify the configuration profile's name:
      import com.databricks.connect.DatabricksSession
      import com.databricks.sdk.core.DatabricksConfig
      
      val config = new DatabricksConfig()
        .setProfile("<profile-name>")
        val spark = DatabricksSession.builder()
        .sdkConfig(config)
        .getOrCreate()
      
      // Specify the configuration profile name along with the clusterId field.
      // In this example, retrieveClusterId() assumes some custom implementation that
      // you provide to get the cluster ID from the user or from some other
      // configuration store:
      import com.databricks.connect.DatabricksSession
      import com.databricks.sdk.core.DatabricksConfig
      
      val config = new DatabricksConfig()
        .setProfile("<profile-name>")
      val spark = DatabricksSession.builder()
        .sdkConfig(config)
        .clusterId(retrieveClusterId())
        .getOrCreate()
      

   3. SPARK_REMOTE 环境变量

      对于仅适用于 Azure Databricks 个人访问令牌身份验证的此选项，请将 SPARK_REMOTE 环境变量设置为以下字符串，并将占位符替换为适当的值。

      sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>
      

      然后如下所示初始化 DatabricksSession 类：

      import com.databricks.connect.DatabricksSession
      
      val spark = DatabricksSession.builder().getOrCreate()
      

      若要设置环境变量，请参阅操作系统的文档。

   4. DATABRICKS_CONFIG_PROFILE 环境变量

      对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及需要使用的支持的 Databricks 身份验证类型所需的任何其他字段。

      如果已使用群集 ID 设置 DATABRICKS_CLUSTER_ID 环境变量，则也无需指定 cluster_id。

      每种身份验证类型所需的配置文件字段如下：

      • 适用于 Azure Databricks 个人访问令牌身份验证：host 和 token。

      • 对于 OAuth 用户到计算机 (U2M) 身份验证（在支持的情况下）：host。

      • 对于 Microsoft Entra ID（以前称为 Azure Active Directory）服务主体身份验证：host、azure_tenant_id、azure_client_id、azure_client_secret 和可能的 azure_workspace_resource_id。

      • 适用于 Azure CLI 身份验证：host。

      • 对于 Azure 托管标识身份验证（如果支持）：host、azure_use_msi、azure_client_id 和可能的 azure_workspace_resource_id。

      将 DATABRICKS_CONFIG_PROFILE 环境变量设置为此配置文件的名称。 然后如下所示初始化 DatabricksSession 类：

      import com.databricks.connect.DatabricksSession
      
      val spark = DatabricksSession.builder().getOrCreate()
      

      若要设置环境变量，请参阅操作系统的文档。

   5. 每个配置属性具有一个环境变量

      对于此选项，请设置 DATABRICKS_CLUSTER_ID 环境变量，以及你要使用的受支持的 Databricks 身份验证类型所需的任何其他环境变量。

      每种身份验证类型所需的环境变量如下：

      • 适用于 Azure Databricks 个人访问令牌身份验证：DATABRICKS_HOST 和 DATABRICKS_TOKEN。

      • 对于 OAuth 用户到计算机 (U2M) 身份验证（在支持的情况下）：DATABRICKS_HOST。

      • 对于 Microsoft Entra ID（以前称为 Azure Active Directory）服务主体身份验证：DATABRICKS_HOST、ARM_TENANT_ID、ARM_CLIENT_ID、ARM_CLIENT_SECRET 和可能的 DATABRICKS_AZURE_RESOURCE_ID。

      • 适用于 Azure CLI 身份验证：DATABRICKS_HOST。

      • 对于 Azure 托管标识身份验证（如果支持）：DATABRICKS_HOST、ARM_USE_MSI、ARM_CLIENT_ID 和可能的 DATABRICKS_AZURE_RESOURCE_ID。

      然后如下所示初始化 DatabricksSession 类：

      import com.databricks.connect.DatabricksSession
      
      val spark = DatabricksSession.builder().getOrCreate()
      

      若要设置环境变量，请参阅操作系统的文档。

   6. 一个名为 DEFAULT 的 Azure Databricks 配置文件

      对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及需要使用的支持的 Databricks 身份验证类型所需的任何其他字段。

      如果已使用群集 ID 设置 DATABRICKS_CLUSTER_ID 环境变量，则也无需指定 cluster_id。

      每种身份验证类型所需的配置文件字段如下：

      • 适用于 Azure Databricks 个人访问令牌身份验证：host 和 token。

      • 对于 OAuth 用户到计算机 (U2M) 身份验证（在支持的情况下）：host。

      • 对于 Microsoft Entra ID（以前称为 Azure Active Directory）服务主体身份验证：host、azure_tenant_id、azure_client_id、azure_client_secret 和可能的 azure_workspace_resource_id。

      • 适用于 Azure CLI 身份验证：host。

      • 对于 Azure 托管标识身份验证（如果支持）：host、azure_use_msi、azure_client_id 和可能的 azure_workspace_resource_id。

      将此配置文件命名为 DEFAULT。

      然后如下所示初始化 DatabricksSession 类：

      scala
      import com.databricks.connect.DatabricksSession
      
      val spark = DatabricksSession.builder().getOrCreate()