Databricks Asset Bundles を使用して Databricks でジョブを開発
Databricks アセットバンドル (単に バンドル とも呼ばれます) には、デプロイするアーティファクトと、実行するジョブなどの Databricks リソースの設定が含まれており、プログラムで検証、デプロイ、実行できます。 「Databricks アセットバンドルとは」を参照してください。
この記事では、ジョブをプログラムで管理するためのバンドルを作成する方法について説明します。 「Databricks のオーケストレーションの概要」を参照してください。バンドルは、 のDatabricks Asset Bundles デフォルト バンドル テンプレートを使用して作成されます。このテンプレートは、ノートブックとそれを実行するジョブの定義を組み合わせたもので構成されます。Pythonその後、デプロイされたジョブを Databricks ワークスペースで検証、デプロイ、実行します。
Databricks ジョブのユーザー インターフェイスまたは API を使用して作成された既存のジョブをバンドルに移動する場合は、バンドルの構成ファイルで定義する必要があります。 Databricks では、まず次の手順を使用してバンドルを作成し、次にバンドルが機能するかどうかを検証することをお勧めします。 その後、追加のジョブ定義、ノートブック、およびその他のソースをバンドルに追加できます。 バンドルへの既存のジョブ定義の追加を参照してください。
必要条件
- Databricks CLI バージョン 0.218.0 以降。 インストールされている Databricks CLI のバージョンを確認するには、コマンド
databricks -v
を実行します。 Databricks CLI をインストールするには、「 Databricks CLI のインストールまたは更新」を参照してください。 - リモート Databricks ワークスペースでは、ワークスペース ファイルが有効になっている必要があります。 「ワークスペースファイルとは」を参照してください。
プロジェクト テンプレートを使用したバンドルの作成
まず、 Databricks Asset Bundles デフォルト Python テンプレートを使用してバンドルを作成します。 バンドルテンプレートの詳細については、「アセットバンドルプロジェクトテンプレートDatabricks」を参照してください。
バンドルを最初から作成する場合は、「 バンドルを手動で作成する」を参照してください。
ステップ 1: 認証を設定する
この手順では、開発用マシン上の Databricks CLI と Databricks ワークスペースの間の認証を設定します。 この記事では、OAuth ユーザーマシン (U2M) 認証と、認証に DEFAULT
という名前の対応する Databricks 構成プロファイルを使用することを前提としています。
U2M認証は、これらの手順をリアルタイムで試すのに適しています。 完全に自動化されたワークフローの場合、Databricks では、代わりに OAuth マシン間 (M2M) 認証を使用することをお勧めします。 「認証」のM2M認証の設定手順を参照してください。
-
Databricks CLI を使用して、ターゲット ワークスペースごとに次のコマンドを実行して、OAuth トークン管理をローカルで開始します。
次のコマンドで、
<workspace-url>
を Databricks ワークスペース インスタンスの URL に置き換えます (例:https://1234567890123456.7.gcp.databricks.com
.Bashdatabricks auth login --host <workspace-url>
-
Databricks CLI では、入力した情報を Databricks 構成プロファイルとして保存するように求められます。
Enter
キーを押して提案されたプロファイル名を受け入れるか、新規または既存のプロファイルの名前を入力します。同じ名前の既存のプロファイルは、入力した情報で上書きされます。 プロファイルを使用すると、複数のワークスペース間で認証コンテキストをすばやく切り替えることができます。既存のプロファイルのリストを取得するには、別のターミナルまたはコマンドプロンプトでDatabricks CLIを使用してコマンド
databricks auth profiles
を実行します。特定のプロファイルの既存の設定を表示するには、コマンドdatabricks auth env --profile <profile-name>
を実行します。 -
Webブラウザで、画面の指示に従ってDatabricksワークスペースにログインします。
-
以下のいずれかのコマンドを実行して、プロファイルの現在の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 バンドルプロジェクトテンプレートを使用してバンドルを初期化します。
-
ターミナルまたはコマンド プロンプトを使用して、テンプレートの生成バンドルを格納するローカル開発マシン上のディレクトリに切り替えます。
-
Databricks CLI を使用して、
bundle init
コマンドを実行します。Bashdatabricks bundle init
-
Template to use
の場合は、Enter
を押してデフォルト値のdefault-python
のままにします。 -
[
Unique name for this project
] では、デフォルト値のmy_project
をそのまま使用するか、別の値を入力してEnter
キーを押します。 これにより、このバンドルのルートディレクトリの名前が決まります。 このルートディレクトリは、現在の作業ディレクトリに作成されます。 -
Include a stub (sample) notebook
については、yes
を選択してEnter
を押してください。 -
Include a stub (sample) DLT pipeline
の場合は、[no
] を選択し、Enter
キーを押します。これにより、Databricks CLI は、バンドルにサンプル DLT パイプラインを定義しないように指示されます。 -
Include a stub (sample) Python package
の場合は、[no
] を選択し、Enter
キーを押します。これにより、 Databricks CLI は、サンプル Python wheel パッケージファイルや関連するビルド手順をバンドルに追加しないように指示されます。
ステップ 3: バンドルを探索する
テンプレートによって生成されたファイルを表示するには、新しく作成したバンドルのルートディレクトリに切り替えます。 特に関心のあるファイルには、次のものがあります。
databricks.yml
: このファイルは、バンドルのプログラム名を指定し、ジョブ定義への参照を含め、ターゲット ワークスペースに関する設定を指定します。resources/<project-name>_job.yml
: このファイルは、デフォルトのノートブックタスクを含むジョブの設定を指定します。src/notebook.ipynb
: このファイルは、実行すると、1 から 10 までの数字を含む RDD を単純に初期化するサンプル ノートブックです。
ジョブをカスタマイズする場合、ジョブ宣言のマッピングは、 リファレンスのPOST /api/2.1/job/create に記載されているように、ジョブ作成操作のリクエストペイロード (YAML 形式で表される)RESTAPI に対応します。
バンドル内の新しいジョブ クラスターの設定を定義、結合、およびオーバーライドするには、「Databricks アセット バンドルでのクラスター設定のオーバーライド」で説明されている手法を使用します。
ステップ 4: プロジェクトのバンドル設定ファイルを検証する
この手順では、バンドル構成が有効かどうかを確認します。
-
ルート ディレクトリから、Databricks CLI を使用して、次のように
bundle validate
コマンドを実行します。Bashdatabricks bundle validate
-
バンドル構成のサマリーが返された場合、検証は成功しています。 エラーが返された場合は、エラーを修正し、この手順を繰り返します。
この手順の後にバンドルに変更を加えた場合は、この手順を繰り返して、バンドル構成がまだ有効かどうかを確認する必要があります。
手順 5: ローカル プロジェクトをリモート ワークスペースにデプロイする
この手順では、ローカル ノートブックをリモート Databricks ワークスペースにデプロイし、ワークスペース内に Databricks ジョブを作成します。
-
バンドル ルートから、Databricks CLI を使用して、次のように
bundle deploy
コマンドを実行します。Bashdatabricks bundle deploy -t dev
-
ローカルノートブックがデプロイされたかどうかを確認する: Databricks ワークスペースのサイドバーで、[ ワークスペース ]をクリックします。
-
src フォルダ> dev > ファイル>
<project-name>
> users ><your-username>
> .bundle をクリックします。ノートブックはこのフォルダにある必要があります。 -
ジョブが作成されたかどうかを確認する: Databricks ワークスペースのサイドバーで、 [ワークフロー] をクリックします。
-
[ジョブ] タブで、[ 開発
<your-username>
]<project-name>_job
をクリックします。 -
「タスク」 タブをクリックします。 ノートブック という 1 つのタスクがあるはずです。
この手順の後にバンドルに変更を加えた場合は、手順 4 から 5 を繰り返して、バンドル構成がまだ有効かどうかを確認してから、プロジェクトを再デプロイする必要があります。
ステップ 6: デプロイされたプロジェクトを実行する
この手順では、コマンド ラインからワークスペース内の Databricks ジョブの実行をトリガーします。
-
ルート ディレクトリから、Databricks CLI を使用して次のように
bundle run
コマンドを実行します。<project-name>
を手順 2 のプロジェクトの名前に置き換えます。Bashdatabricks bundle run -t dev <project-name>_job
-
ターミナルに表示される
Run URL
の値をコピーし、この値を Web ブラウザーに貼り付けて Databricks ワークスペースを開きます。 「Databricks アセット バンドルを使用して作成されたジョブの表示と実行」を参照してください -
Databricks ワークスペースで、ジョブ タスクが正常に完了し、緑色のタイトル バーが表示されたら、ジョブ タスクをクリックして結果を確認します。
この手順の後にバンドルに変更を加えた場合は、手順 4 から 6 を繰り返して、バンドル構成がまだ有効かどうかを確認し、プロジェクトを再デプロイして、再デプロイされたプロジェクトを実行する必要があります。
ステップ 7: クリーンアップ
この手順では、デプロイされたノートブックとジョブをワークスペースから削除します。
-
ルート ディレクトリから、Databricks CLI を使用して、次のように
bundle destroy
コマンドを実行します。Bashdatabricks bundle destroy -t dev
-
ジョブの削除要求を確認する: リソースを完全に破棄するように求められたら、「
y
」と入力してEnter
キーを押します。 -
ノートブックの削除要求を確認する: 以前にデプロイしたフォルダーとそのすべてのファイルを完全に破棄するように求められたら、「
y
」と入力してEnter
キーを押します。 -
開発マシンからバンドルも削除する場合は、ステップ 2 からローカル ディレクトリを削除できます。
既存のジョブ定義をバンドルに追加する
既存のジョブをベースとして使用して、バンドル構成ファイルでジョブを定義できます。 既存のジョブ定義を取得するには、UI を使用して手動で取得するか、Databricks CLI を使用してプログラムで生成します。
バンドル内のジョブ定義に関する情報については、 ジョブを参照してください。
UI を使用して既存のジョブ定義を取得する
Databricks ワークスペース UI から既存のジョブ定義の YAML 表現を取得するには、次のようにします。
-
Databricks ワークスペースのサイドバーで、 [ワークフロー] をクリックします。
-
[ジョブ] タブで、ジョブ の [名前 ] リンクをクリックします。
-
[ 今すぐ実行 ] ボタンの横にあるケバブをクリックし、[ コードに切り替え (YAML)] をクリックします。
-
コピーした YAML をバンドルの
databricks.yml
ファイルに追加するか、バンドル プロジェクトのresources
ディレクトリにジョブの構成ファイルを作成し、databricks.yml
ファイルから参照します。 (/dev-tools/bundles/settings.md#リソース)を参照してください。 -
既存のジョブで参照されている Python ファイルとノートブックをダウンロードして、バンドルのプロジェクト ソースに追加します。 通常、bundle アーティファクトはバンドル内の
src
ディレクトリにあります。
ワークスペースから既存のノートブックを 形式にエクスポートするには、Databricks .ipynb
ノートブック ユーザー インターフェイスから[ファイル] > [IPython ノートブック>エクスポート] Databricksをクリックします。
ノートブック、Python ファイル、およびその他のアーティファクトをバンドルに追加したら、ジョブ定義がそれらを適切に参照していることを確認してください。 たとえば、バンドルの src
ディレクトリにある hello.ipynb
という名前のノートブックの場合、次のようになります。
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
notebook_task:
notebook_path: ../src/hello.ipynb
Databricks CLI を使用して既存のジョブ定義を生成する
既存のジョブのバンドル設定をプログラムで生成するには、次のようにします。
-
ジョブ UI のジョブ の詳細 サイドパネルから既存のジョブの ID を取得するか、 Databricks CLI
databricks jobs list
コマンドを使用します。 -
bundle generate job
Databricks CLI コマンドを実行し、ジョブ ID を設定します。Bashdatabricks bundle generate job --existing-job-id 6565621249
このコマンドは、バンドルの [
resources
] フォルダにジョブのバンドル設定ファイルを作成し、参照されているアーティファクトをsrc
フォルダにダウンロードします。
最初に bundle deployment bind
を使用してバンドル内のリソースをワークスペース内のリソースにバインドすると、ワークスペース内のリソースは、バインド先のバンドルで定義された設定に基づいて更新されます。次の bundle deploy
以降。 bundle deployment bind
に関する情報については、「Bind bundle リソース」を参照してください。