Databricks Asset Bundles を使用して Databricks でジョブを開発

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

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

ヒント

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

Databricks CLIを使用してバンドルによってデプロイされたジョブを実行するだけでなく、DatabricksジョブUIでこれらのジョブを表示および実行することもできます。「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://dbc-a1b2345c-d6e7.cloud.databricks.com）。
```
databricks 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 コマンドを実行します。
```
databricks 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 は、バンドルにサンプルの Delta Live Tables パイプラインを定義しないように指示されます。
Include a stub (sample) Python packageの場合は、[no] を選択し、Enterキーを押します。これにより、 Databricks CLI は、サンプル Python wheel パッケージファイルや関連するビルド手順をバンドルに追加しないように指示されます。

ステップ 3: バンドルを調べる

テンプレートによって生成されたファイルを表示するには、新しく作成したバンドルのルートディレクトリに切り替え、このディレクトリを任意の IDE (Visual Studio Code など) で開きます。特に関心のあるファイルには、次のものがあります。

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 コマンドを実行します。
```
databricks bundle validate
```
バンドル構成のサマリーが返された場合、検証は成功しています。エラーが返された場合は、エラーを修正し、この手順を繰り返します。

この手順の後にバンドルに変更を加えた場合は、この手順を繰り返して、バンドル構成がまだ有効かどうかを確認する必要があります。

ステップ 5: ローカルプロジェクトをリモートワークスペースに配置する

この手順では、ローカルノートブックをリモート Databricks ワークスペースにデプロイし、ワークスペース内に Databricks ジョブを作成します。

バンドルルートから、Databricks CLI を使用して、次のように bundle deploy コマンドを実行します。
```
databricks 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 のプロジェクトの名前に置き換えます。
```
databricks bundle run -t dev <project-name>_job
```
ターミナルに表示される Run URL の値をコピーし、この値を Web ブラウザーに貼り付けて Databricks ワークスペースを開きます。
Databricks ワークスペースで、ジョブタスクが正常に完了し、緑色のタイトルバーが表示されたら、ジョブタスクをクリックして結果を確認します。

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

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

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

ルートディレクトリから、Databricks CLI を使用して、次のように bundle destroy コマンドを実行します。
```
databricks bundle destroy
```
ジョブの削除要求を確認する: リソースを完全に破棄するように求められたら、「 y 」と入力して Enterキーを押します。
ノートブックの削除要求を確認する: 以前にデプロイしたフォルダーとそのすべてのファイルを完全に破棄するように求められたら、「 y 」と入力して Enterキーを押します。
開発マシンからバンドルも削除する場合は、ステップ 2 からローカルディレクトリを削除できます。

既存のジョブ定義をバンドルに追加する

既存のジョブをベースとして使用して、バンドル構成ファイルでジョブを定義できます。既存のジョブ定義を取得するには、UI を使用して手動で取得するか、Databricks CLI を使用してプログラムで生成します。

バンドル内のジョブ定義に関する情報については、ジョブを参照してください。

UI を使用して既存のジョブ定義を取得する

Databricks ワークスペース UI から既存のジョブ定義の YAML 表現を取得するには、次のようにします。

Databricks ワークスペースのサイドバーで、 [ワークフロー] をクリックします。
[ジョブ] タブで、ジョブの [名前] リンクをクリックします。
[ 今すぐ実行 ] ボタンの横にあるケバブをクリックし、[ コードに切り替え (YAML)] をクリックします。
[作成] タブで、[コピー] をクリックして、ジョブ定義の YAML をローカルクリップボードにコピーします。

バンドル設定ファイルで、コピーした YAML を、ジョブが定義されているバンドル設定に追加します。

resources:
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      <job-yaml>

targets:
  dev:
    resources:
      jobs:
        <some-unique-programmatic-identifier-for-this-job>:
          <job-yaml>

次に、既存のジョブで参照されている Python ファイルとノートブックをダウンロードして、バンドルのプロジェクトソースに追加します。通常、バンドル成果物はバンドル内の 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 を設定します。

databricks bundle generate job --existing-job-id 6565621249

このコマンドは、バンドルの [ resources ] フォルダにジョブのバンドル設定ファイルを作成します。

ヒント

最初に bundle deployment bind を使用してバンドル内のリソースをワークスペース内のリソースにバインドすると、ワークスペース内のリソースは、バインド先のバンドルで定義された設定に基づいて更新されます。次の bundle deploy以降。 bundle deployment bindに関する情報については、「Bind bundle リソース」を参照してください。

サーバレスコンピュートを使用するジョブの設定

次の例は、サーバレスコンピュートを使用するジョブを作成するためのバンドル設定を示しています。

サーバレスコンピュートを使用して、ノートブックタスクを含むジョブを実行するには、バンドル設定ファイルから job_clusters 設定を省略します。

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job-serverless:
      name: retrieve-filter-baby-names-job-serverless
      tasks:
        - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./filter-baby-names.py

  targets:
    development:
      workspace:
        host: <workspace-url>

サーバレスコンピュートを使用して、 Python タスクを含むジョブを実行するには、environments設定を含めます。

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: serverless-python-tasks

resources:
jobs:
  serverless-python-job:
    name: serverless-job-with-python-tasks

    tasks:
      - task_key: wheel-task-1
        python_wheel_task:
          entry_point: main
          package_name: wheel_package
        environment_key: Default

    environments:
      - environment_key: Default
        spec:
          client: "1"
          dependencies:
            - workflows_authoring_toolkit==0.0.1

targets:
  development:
    workspace:
      host: <workspace-url>

「ワークフロー用サーバレスコンピュートを使用してDatabricksジョブを実行する」を参照してください。