Databricks Asset Bundles を使用したジョブの開発

Databricks アセットバンドル (単に バンドル とも呼ばれます) には、デプロイするアーティファクトと、実行するジョブなどの Databricks リソースの設定が含まれており、プログラムで検証、デプロイ、実行できます。「Databricks アセットバンドルとは」を参照してください。

このページでは、ジョブをプログラムで管理するためのバンドルを作成する方法について説明します。LakeFlowジョブを参照してください。 バンドルは、ノートブックとそれを実行するジョブの定義で構成される、 Python 用の Databricks Asset Bundles のデフォルト バンドル テンプレートを使用して作成されます。次に、Databricks ワークスペースでデプロイされたジョブを検証、デプロイ、実行します。

ヒント

Lakeflowジョブ・ユーザー・インターフェースを使用して作成された既存のジョブまたはバンドルに移動するAPIがある場合は、バンドルの構成ファイルでそれらを定義する必要があります。Databricks では、まず次の手順を使用してバンドルを作成し、次にバンドルが機能するかどうかを検証することをお勧めします。その後、追加のジョブ定義、ノートブック、およびその他のソースをバンドルに追加できます。「UI を使用した既存のジョブ定義の取得」を参照してください。

バンドルを最初から作成する場合は、「 バンドルを手動で作成する」を参照してください。

必要条件

• Databricks CLI バージョン 0.218.0 以降。 インストールされている Databricks CLI のバージョンを確認するには、コマンド databricks -vを実行します。 Databricks CLI をインストールするには、「 Databricks CLI のインストールまたは更新」を参照してください。
• テストを実行し、IDE からこのプロジェクトの依存関係をインストールするには、 uvが必要です。
• リモート Databricks ワークスペースでは、ワークスペース ファイルが有効になっている必要があります。 「ワークスペースファイルとは」を参照してください。
• 既存のカタログ。カタログを作成するには、 「カタログの作成」を参照してください。

ステップ 1: 認証を設定する

まず、開発マシン上の Databricks CLI と Databricks ワークスペース間の認証を設定します。このページでは、認証に OAuth ユーザー対マシン (U2M) 認証と、 DEFAULTという名前の対応する Databricks 構成プロファイルを使用することを前提としています。

注記

U2M 認証は、これらの手順をリアルタイムで試すのに適しています。完全に自動化されたワークフローの場合、Databricks では、代わりに OAuth マシン間 (M2M) 認証を使用することをお勧めします。「サービスプリンシパルアクセスをOAuthでDatabricksに許可する」のM2M認証の設定手順を参照してください。

1. Databricks CLI を使用して、ターゲット ワークスペースごとに次のコマンドを実行して、OAuth トークン管理をローカルで開始します。

   次のコマンドで、 <workspace-url> を Databricks ワークスペース インスタンスの URL に置き換えます (例: https://dbc-a1b2345c-d6e7.cloud.databricks.com.

   Bash

   databricks auth login --host <workspace-url>

2. Databricks CLI では、入力した情報を Databricks 構成プロファイルとして保存するように求められます。 Enter キーを押して提案されたプロファイル名を受け入れるか、新規または既存のプロファイルの名前を入力します。同じ名前の既存のプロファイルは、入力した情報で上書きされます。 プロファイルを使用すると、複数のワークスペース間で認証コンテキストをすばやく切り替えることができます。

   既存のプロファイルの一覧を取得するには、別のターミナルまたはコマンド プロンプトで、 Databricks CLI を使用してコマンド databricks auth profilesを実行します。 特定のプロファイルの既存の設定を表示するには、 databricks auth env --profile <profile-name>コマンドを実行します。

3. Webブラウザで、画面の指示に従ってDatabricksワークスペースにログインします。

4. プロファイルの現在の OAuth トークン値とトークンの今後の有効期限のタイムスタンプを表示するには、次のいずれかのコマンドを実行します。

   • databricks auth token --host <workspace-url>
   • databricks auth token -p <profile-name>
   • databricks auth token --host <workspace-url> -p <profile-name>

   同じ--host値を持つプロファイルが複数ある場合、Databricks CLIが正しいOAuthトークン情報を見つけられるように--hostと-pオプションを一緒に指定する必要がある場合があります。

ステップ 2: バンドルを初期化する

デフォルトの Python バンドルプロジェクトテンプレートを使用してバンドルを初期化します。

1. ターミナルまたはコマンド プロンプトを使用して、テンプレートの生成バンドルを格納するローカル開発マシン上のディレクトリに切り替えます。

2. Databricks CLI を使用して、 bundle init コマンドを実行します。

   Bash

   databricks bundle init

3. Template to useの場合は、Enterを押してデフォルト値の default-python のままにします。

4. [ Unique name for this project] では、デフォルト値の my_projectをそのまま使用するか、別の値を入力して Enterキーを押します。 これにより、このバンドルのルートディレクトリの名前が決まります。 このルートディレクトリは、現在の作業ディレクトリに作成されます。

5. Include a job that runs a notebook については、yes を選択して Enter を押してください。

6. Include an ETL pipeline については、no を選択して Enter を押してください。

7. Include a stub (sample) Python package については、no を選択して Enter を押してください。

8. Use serverlessの場合は、[yes] を選択し、Enterキーを押します。これにより、バンドルをサーバレス コンピュートで実行するように Databricks CLI に指示します。

9. Default catalog for any tables created by this project [hive_metastore]には、既存の Unity Catalog カタログの名前を入力します。

10. Use a personal schema for each user working on this project.の場合はyesを選択します。

ステップ 3: バンドルを探索する

テンプレートによって生成されたファイルを表示するには、新しく作成したバンドルのルートディレクトリに切り替えます。 特に関心のあるファイルには、次のものがあります。

• databricks.yml: このファイルは、バンドルのプログラム名を指定し、バンドルのファイルへの参照を含め、カタログとスキーマの変数を定義し、ターゲット ワークスペースの設定を指定します。
• resources/sample_job.job.yml: このファイルは、デフォルトのノートブック タスクを含むジョブの設定を指定します。ジョブ設定については、 「ジョブ」を参照してください。
• src/: このフォルダーにはジョブのソース ファイルが含まれています。
• src/sample_notebook.ipynb: このノートブックはサンプル テーブルを読み取ります。
• tests/: このフォルダーにはサンプルのユニット テストが含まれています。
• README.md: このファイルには、このバンドル テンプレートの使用および開始方法に関する追加情報が含まれています。

ヒント

「ターゲット設定によるオーバーライド」で説明されている手法を使用して、バンドル内の新しいジョブ クラスターの設定を定義、結合、オーバーライドできます。

ステップ 4: バンドル構成を検証する

次に、バンドル構成が有効かどうかを確認します。

1. ルート ディレクトリから、Databricks CLI を使用してbundle validateコマンドを実行します。

   Bash

   databricks bundle validate

2. バンドル構成のサマリーが返された場合、検証は成功しています。 エラーが返された場合は、エラーを修正し、この手順を繰り返します。

ステップ 5: バンドルをリモートのワークスペースにデプロイします

次に、ジョブをリモート Databricks ワークスペースにデプロイし、ワークスペース内でジョブを確認します。

1. バンドル ルートから、Databricks CLI を使用してbundle deployコマンドを実行します。

   Bash

   databricks bundle deploy --target dev

2. ノートブックがデプロイされたことを確認します。

   1. Databricksワークスペースのサイドバーで、 [ワークスペース] をクリックします。
   2. src フォルダ> dev > ファイル> <project-name> > users > <your-username> > .bundle をクリックします。ノートブックはこのフォルダにある必要があります。

3. ジョブが作成されたかどうかを確認します。

   1. Databricks ワークスペースのサイドバーで、 ジョブとパイプライン をクリックします。
   2. 必要に応じて、 ジョブ と 自分が所有 フィルターを選択します。
   3. [dev <your-username> ] sample_job をクリックします。
   4. [タスク] タブをクリックします。 notebook_task が 1 つあるはずです。

この手順の後にバンドルに変更を加えた場合は、手順 4 から 5 を繰り返して、バンドル構成がまだ有効かどうかを確認してから、プロジェクトを再デプロイする必要があります。

ステップ 6: デプロイされたジョブを実行する

次に、コマンド ラインからワークスペースでジョブの実行をトリガーします。

1. ルート ディレクトリから、Databricks CLI を使用してbundle runコマンドを実行します。

   Bash

   databricks bundle run --target dev sample_job

2. ターミナルに表示される Run URL の値をコピーし、この値を Web ブラウザーに貼り付けて Databricks ワークスペースを開きます。「Databricks アセット バンドルで作成されたジョブの表示と実行」を参照してください。

3. Databricks ワークスペースで、ジョブ タスクが正常に完了し、緑色のタイトル バーが表示されたら、ジョブ タスクをクリックして結果を確認します。

この手順の後にバンドルに変更を加えた場合は、手順 4 から 6 を繰り返して、バンドル構成がまだ有効かどうかを確認し、プロジェクトを再デプロイして、再デプロイされたプロジェクトを実行する必要があります。

ステップ 7: 実行テスト

最後に、 pytestを使用してローカルでテストを実行します。

uv run pytest

ステップ8: クリーンアップ

この手順では、デプロイされたノートブックとジョブをワークスペースから削除します。

1. ルート ディレクトリから、Databricks CLI を使用してbundle destroyコマンドを実行します。

   Bash

   databricks bundle destroy --target dev

2. すべてのワークスペース ファイルとディレクトリを永続的に保存するように要求されたら、 yと入力してEnterを押します。

3. 開発マシンからもバンドルを削除する場合は、ローカル プロジェクト ディレクトリを削除できます。