Share via


Databricks SDK for Java

この記事では、Databricks SDK for Java を使用して、Azure Databricks アカウント、ワークスペース、および関連リソースでの操作を自動化する方法について説明します。 この記事は、Databricks SDK for Java の READMEAPI リファレンスを補足するものです。

Note

この機能はベータ版であり、運用環境で使用しても問題ありません。

ベータ期間中、Databricks では、コードが依存する Databricks SDK for Java の特定のマイナー バージョンへの依存関係をピン留めすることをお勧めします。 たとえば、Maven の pom.xml など、ファイルに依存関係をピン留めできます。 依存関係のピン留めの詳細については、「Introduction to the Dependency Mechanism」(依存関係のメカニズムの概要) を参照してください。

開始する前に

Databricks SDK for Java の使用を開始する前に、開発マシンには次が必要です。

  • Azure Databricks 認証が構成されている。
  • Java 8 以上と互換性のある Java Development Kit (JDK)。 Databricks SDK for Java を使用した継続的インテグレーション (CI) テストは、Java バージョン 8、11、17、および 20 と互換性があります。
  • Java 互換の統合開発環境 (IDE) を推奨します。 Databricks では、IntelliJ IDEA が推奨されています。

Databricks SDK for Java の使用を開始する

  1. プロジェクトの pom.xml ファイルで、Databricks SDK for Java に依存するようにビルド システムに指示します。 これを行うには、pom.xml ファイルの既存の <dependencies> セクションに次の <dependency> を追加します。 <dependencies> セクションが pom.xml ファイル内にまだ存在しない場合は、<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>
    

    Note

    必ず 0.0.1 を最新バージョンの Databricks SDK for Java に置き換えてください。 最新バージョンは、Maven の中央リポジトリにあります。

  2. Databricks SDK for Java に対して宣言された依存関係を取得するようにプロジェクトに指示します。 たとえば、IntelliJ IDEA では、プロジェクトの [Project] (プロジェクト) ツール ウィンドウで、プロジェクトのルート ノードをクリックし、[Reload Project] (プロジェクトの再読み込み) をクリックします。

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

    Note

    WorkspaceClient w = new WorkspaceClient() への前の呼び出しで、引数を設定しないことで、Databricks SDK for Java では、Azure Databricks 認証の実行を試みるために既定のプロセスが使用されます。 この既定の動作をオーバーライドするには、次の 認証 セクションを参照してください。

  4. プロジェクトをビルドする。 たとえば、IntelliJ IDEA でこれを行うには、メイン メニューの「Build > Build Project」をクリックします。

  5. メイン ファイルを実行します。 たとえば、プロジェクトの Main.java ファイルに対して IntelliJ IDEA で実行するには、メイン メニューの「 Run > Run ‘Main’」をクリックします。

  6. クラスターの一覧が表示されます。 たとえば、IntelliJ IDEA では、これは「Run」ツール ウィンドウにあります。 このツール ウィンドウを表示するには、メイン メニューの「View > Tool Windows > Run」をクリックします。

Azure Databricks アカウントまたはワークスペースで Databricks SDK for Java を認証する

Databricks SDK for Java は、Databricks クライアント統合認証標準を実装しています。これは、統合されていて一貫性がある、アーキテクチャとプログラムによる認証アプローチです。 このアプローチは、Azure Databricks を使用した認証の設定と自動化を、より一元的で予測可能なものにするのに役立ちます。 これにより、Databricks 認証を一度構成すれば、それ以上認証構成を変更しなくても、複数の Databricks ツールおよび SDK でその構成を使用できます。 Java のより完全なコード例を含む詳細については、Databricks クライアント統合認証に関するページを参照してください。

Note

Databricks SDK for Java では、まだ Azure マネージド ID 認証が実装されていません。

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 の「Authentication」(認証) も参照してください。

Databricks Utilities と Java と共に Databricks SDK for Java を使用する

Databricks Utilities はヘルパー関数をいくつか備えており、オブジェクト ストレージの効率的な操作、ノートブックのチェーン化とパラメーター化、シークレットの操作を簡単にします。 Databricks は Databricks Utilities for Scala ライブラリを備えています。これを Java コードで呼び出すことで、プログラムで Databricks Utilities にアクセスできます。

Java コードを使用して Databricks Utilities for Scala を呼び出すには、次を行います。

  1. Java プロジェクトで、前のセクションで説明したように、Databricks SDK for Java に対する依存関係を宣言します。

  2. Databricks Utilities for Scala ライブラリに対する依存関係を宣言します。 これを行うには、pom.xml ファイルの既存の <dependencies> セクションに次の <dependency> を追加します。

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

    Note

    必ず 0.1.4 を最新バージョンの Databricks Utilities for Scala ライブラリに置き換えてください。 最新バージョンは、Maven の中央リポジトリにあります。

  3. Databricks Utilities for Scala に対して宣言された依存関係を取得するようにプロジェクトに指示します。 たとえば、IntelliJ IDEA では、プロジェクトの 「Project」ツール ウィンドウで、プロジェクトのルート ノードをクリックし、「Maven > Reload Project」をクリックします。

  4. インポートするコードを追加し、Databricks Utility for Scala を呼び出します。 たとえば、次のコードで Unity Catalog ボリュームが自動化されます。 この例では、ワークスペース内のボリュームのパスに 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. プロジェクトをビルドしてメイン ファイルを実行します。

コード例

次のコード例は、Databricks SDK for Java を使用して、クラスターを作成および削除し、ジョブを作成し、アカウント レベルのグループを一覧表示する方法を示しています。 これらのコード例では、Databricks SDK for Java の既定の Azure Databricks 認証 プロセスを使用しています。

その他のコード例については、GitHub の Databricks SDK for Java リポジトリの examples フォルダーを参照してください。

クラスターの作成

このコード例では、Databricks Runtime バージョンとクラスター ノードの種類を指定してクラスターを作成します。 このクラスターには 1 つのワーカーがあり、クラスターは 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 を使用するクラスターを作成する

Note

JDK 8 は発表全にサポートされています。 JDK 17 は、Databricks Runtime 13.1以降のパブリック プレビュー段階にあります。

このセクションでは、Java Development Kit (JDK) を使用してクラスターを作成する方法について説明します。 JDK 17 を使用してクラスターを作成し、ノートブックとジョブで Java を使用する方法について説明します。

クラスターを作成するときに、次の環境変数を 詳細オプション > Spark > 環境変数 に追加して、ドライバーと実行者の両方に JDK 17 を使用するように指定します。

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

Databricks SDK for Java で Scala を使用する

Databricks SDK for Java で Scala プロジェクトを使用できます。 開始する前に、開発用マシンには以下のものが必要です。

  • Azure Databricks 認証が構成されている。
  • Scala 互換の統合開発環境 (IDE) を推奨します。 Databricks では、Scala プラグインを使用している IntelliJ IDEA を推奨しています。 これらの手順は、IntelliJ IDEA Community Edition 2023.3.6 でテストされました。 別のバージョンまたはエディションの IntelliJ IDEA を使用する場合、次の手順は異なる場合があります。
  • Java 8 以上と互換性のある Java Development Kit (JDK)。 Azure Databricks クラスターでアプリケーションを実行する場合、またはライブラリを使用する場合は、クラスター上の JDK バージョンと一致するバージョンの JDK を使用することを推奨します。 特定の Databricks Runtime に含まれている JDK バージョンを確認するには、「 Databricks Runtime リリース ノートのバージョンと互換性」を参照してください。 IntelliJ IDEA を使用する場合は、Scala プロジェクトの作成時に、既存のローカル JDK インストールを選択するか、新しい JDK をローカルにインストールできます。
  • Scala ビルド ツール。 Databricks では sbt を推奨しています。 IntelliJ IDEA を使用する場合は、Scala プロジェクトの作成時に使用する sbt バージョンを選択できます。
  • Scala。 Azure 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"
    

    Note

    必ず 0.2.0 を最新バージョンの Databricks SDK for Java ライブラリに置き換えてください。 最新バージョンは、Maven の中央リポジトリにあります。

  2. Databricks SDK for Java に対して宣言された依存関係を取得するようにプロジェクトに指示します。 たとえば、IntelliJ IDEA で、「sbt の変更を読み込む」通知アイコンをクリックします。

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

    Note

    val w = new WorkspaceClient() への前の呼び出しで、引数を設定しないことで、Databricks SDK for Java では、Azure Databricks 認証の実行を試みるために既定のプロセスが使用されます。 この既定の動作をオーバーライドするには、次の 認証 セクションを参照してください。

  4. プロジェクトをビルドする。 たとえば、IntelliJ IDEA でこれを行うには、メイン メニューの「Build > Build Project」をクリックします。

  5. メイン ファイルを実行します。 たとえば、プロジェクトの Main.scala ファイルに対して IntelliJ IDEA で実行するには、メイン メニューの「 Run > Run ‘Main.scala’」をクリックします。

  6. クラスターの一覧が表示されます。 たとえば、IntelliJ IDEA では、これは「Run」ツール ウィンドウにあります。 このツール ウィンドウを表示するには、メイン メニューの「View > Tool Windows > Run」をクリックします。

Databricks Utilities と Scala と共に Databricks SDK for Java を使用する

Databricks Utilities はヘルパー関数をいくつか備えており、オブジェクト ストレージの効率的な操作、ノートブックのチェーン化とパラメーター化、シークレットの操作を簡単にします。 Databricks は Databricks Utilities for Scala ライブラリを備えており、Scala によるプログラムで Databricks Utilities にアクセスできます。

Databricks Utilities for Scala を呼び出すには、次を行います。

  1. Scala プロジェクトで、前のセクションで説明したように、Databricks SDK for Java に対する依存関係を宣言します。

  2. Databricks Utilities for Scala ライブラリに対する依存関係を宣言します。 たとえば、プロジェクトの build.sbt ファイルで、ファイルの末尾に次の行を追加し、ファイルを保存します。

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

    Note

    必ず 0.1.4 を最新バージョンの Databricks Utilities for Scala ライブラリに置き換えてください。 最新バージョンは、Maven の中央リポジトリにあります。

  3. Databricks Utilities for Scala に対して宣言された依存関係を取得するようにプロジェクトに指示します。 たとえば、IntelliJ IDEA で、「sbt の変更を読み込む」通知アイコンをクリックします。

  4. インポートするコードを追加し、Databricks Utility for Scala を呼び出します。 たとえば、次のコードで Unity Catalog ボリュームが自動化されます。 この例では、ワークスペース内のボリュームのパスに 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)
      }
    }
    

    Note

    val dbutils = DBUtils.getDBUtils() への前の呼び出しで、引数を設定しないことで、Databricks Utilities for Scala では、Azure Databricks 認証の実行を試みるために既定のプロセスが使用されます。

    この既定の動作をオーバーライドするには、インスタンス化された DatabricksCfg オブジェクトを引数として getDBUtils に渡します。 詳細については、前の認証に関するセクションを参照してください。

    ただし、コードが Databricks Runtime プロジェクトの中で実行される場合、この DatabricksCfg オブジェクトは無視されることに注意してください。 これは、Databricks Runtime の中で実行されるとき、Databricks Utilities for Scala は組み込みの Databricks Utilities に委任するためです。

  5. プロジェクトをビルドしてメイン ファイルを実行します。

テスト

コードをテストするには、JUnit などの Java テスト フレームワークを使用します。 Azure Databricks REST API エンドポイントを呼び出したり、Azure Databricks アカウントまたはワークスペースの状態を変更したりせずに、シミュレートされた条件下でコードをテストするには、Mockito などの Java モック ライブラリを使用します。

たとえば、新しいクラスターに関する情報を返す createCluster 関数を含む、Helpers.java という名前の次のファイルがあるとします。

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

また、createCluster 関数を呼び出す、Main.java という名前の次のファイルがあるとします。

// 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 関数に渡します。 このテストでは次に、関数が、新しいモック クラスターの想定される 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);
  }
}

その他のリソース

詳細については、以下を参照してください: