Databricks アセットバンドルを使用して Azure Databricks でジョブを開発する

[アーティクル]
10/14/2024

Databricks アセットバンドル (単にバンドルとも呼ばれます) には、デプロイする成果物と、実行するジョブなどの Azure Databricks のリソース用の設定が含まれています。バンドルを使用すると、これらをプログラムで検証、デプロイ、実行できます。「Databricks アセットバンドルとは」をご覧ください。

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

ヒント

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

要件

Databricks CLI バージョン 0.218.0 以降。お使いのインストールされている Databricks CLI のバージョンをチェックするには、databricks -v コマンドを実行します。 Databricks CLI をインストールするには、「Databricks CLI のインストールまたは更新」を参照してください。
リモート Databricks ワークスペースでは、ワークスペースファイルが有効になっている必要があります。「ワークスペースファイルとは」を参照してください。

プロジェクトテンプレートを使用してバンドルを作成する

まず、Databricks アセットバンドルのデフォルト Python テンプレートを使用してバンドルを作成します。バンドルテンプレートの詳細については、「Databricks アセットバンドルプロジェクトテンプレート」を参照してください。

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

手順 1: 認証を設定する

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

Note

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

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

次のコマンド内では、<workspace-url> を Azure Databricks ワークスペース単位の URL (例: https://adb-1234567890123456.7.azuredatabricks.net) に置き換えます。
```
databricks auth login --host <workspace-url>
```
Databricks CLI では、入力した情報を Azure Databricks 構成プロファイルとして保存するように求められます。 Enter キーを押して提案されたプロファイル名を受け入れるか、新規または既存のプロファイル名を入力します。同じ名前の既存のプロファイルは、入力した情報で上書きされます。プロファイルを使用すると、複数のワークスペース間で認証コンテキストをすばやく切り替えることができます。

既存のプロファイルの一覧を取得するには、別のターミナルまたはコマンドプロンプト内で、Databricks CLI を使用してコマンド databricks auth profiles を実行します。特定のプロファイルの既存の設定を表示するには、コマンド databricks auth env --profile <profile-name> を実行します。
Web ブラウザー内で、画面の指示に従って Azure 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 を押します。これにより、サンプル Python ホイールパッケージファイルまたは関連するビルド手順をバンドルに追加しないことを Databricks CLI に指示します。

手順 3: バンドルを調べる

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

databricks.yml: このファイルでは、バンドルのプログラム名が指定され、ジョブ定義への参照が含まれ、ターゲットワークスペースに関する設定が指定されます。
resources/<project-name>_job.yml: このファイルでは、既定のノートブックタスクを含むジョブの設定を指定します。
src/notebook.ipynb: このファイルは、1 から 10 までの数値を含む RDD を実行時に初期化するだけのサンプルノートブックです。

ジョブをカスタマイズする場合、ジョブ宣言内のマッピングは、REST API リファレンスの POST /api/2.1/jobs/create に記載されているジョブ作成操作の要求ペイロードに対応し、YAML 形式で表されます。

ヒント

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

手順 4: プロジェクトのバンドル構成ファイルを検証する

この手順では、そのバンドル設定が有効かどうかを確認します。

ルートディレクトリから、次のように Databricks CLI を使って bundle validate コマンドを実行します。
```
databricks bundle validate
```
バンドル構成の概要が返されたら、検証が成功したことになります。エラーが返される場合は、エラーを修正してから、この手順を繰り返します。

この手順の後、お使いのバンドルに何か変更を加える場合はこの手順を繰り返し、お使いのバンドル構成がまだ有効かどうかをチェックする必要があります。

手順 5: ローカルプロジェクトをリモートワークスペースにデプロイする

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

バンドルのルートから、次のように Databricks CLI を使って bundle deploy コマンドを実行します。
```
databricks bundle deploy -t dev
```
そのローカルノートブックがデプロイされたかどうかをチェックします。お使いの Azure Databricks ワークスペースのサイドバー内で、[ワークスペース] をクリックします。
Users ><your-username>> .bundle ><project-name>> dev > files > src フォルダーをクリックします。そのノートブックはこのフォルダー内に存在する必要があります。
ジョブが作成されたかどうかを確認します: Azure Databricks ワークスペースのサイドバーで、[ワークフロー] をクリックします。
[ジョブ] タブの [dev <your-username>] <project-name>_job をクリックします。.
[タスク] タブをクリックします。notebook_task という 1 つのタスクがあるはずです。

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

手順 6: デプロイされたプロジェクトを実行する

この手順では、コマンドラインからお使いのワークスペースで Azure Databricks ジョブの実行をトリガーします。

ルートディレクトリから、Databricks CLI を使って、bundle run コマンドを次のように実行します。<project-name> は手順 2 のプロジェクトの名前に置き換えます。
```
databricks bundle run -t dev <project-name>_job
```
お使いのターミナル内に表示される "Run URL" の値をコピーし、この値を Web ブラウザーに貼り付けて、お使いの Azure Databricks ワークスペースを開きます。「Databricks アセットバンドルを使用して作成されたジョブの表示と実行」を参照してください。
Azure Databricks ワークスペースで、ジョブタスクが正常に完了し、緑色のタイトルバーが表示されたら、ジョブタスクをクリックして結果を確認します。

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

手順 7: クリーンアップする

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

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

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

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

バンドル内のジョブ定義については、「ジョブ」を参照してください。

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

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

Azure Databricks ワークスペースのサイドバーで、[ワークフロー] をクリックします。
[ジョブ] タブで、ジョブの [名前] リンクをクリックします。
[今すぐ実行] ボタンの横にあるケバブをクリックし、[Switch to code (YAML)] (コード (YAML) に切り替え) をクリックします。
バンドルの databricks.yml ファイルにコピーした YAML を追加するか、バンドルプロジェクトの resources ディレクトリにジョブの構成ファイルを作成し、それを databricks.yml ファイルから参照します。「(/dev-tools/bundles/settings.md#resources)」を参照してください。
既存のジョブで参照されるすべての Python ファイルとノートブックをダウンロードし、バンドルのプロジェクトソースに追加します。通常、バンドルの成果物はバンドルの src ディレクトリ内にあります。

ヒント

Azure Databricks ノートブックのユーザーインターフェイスから [ファイル] > [エクスポート] > [IPython Notebook] をクリックして、Azure Databricks ワークスペースから既存のノートブックを .ipynb 形式でエクスポートできます。

ノートブック、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 フォルダーに作成し、参照されるすべての成果物を src フォルダーにダウンロードできます。

ヒント

最初に bundle deployment bind を使用してバンドル内のリソースをワークスペース内のリソースにバインドする場合、ワークスペース内のリソースは、次の bundle deploy の後に、バインドされているバンドルで定義された構成に基づいて更新されます。 bundle deployment bind の詳細については、「バンドルリソースをバインドする」を参照してください。

サーバーレスコンピューティングを使用するジョブを構成する

次の例では、サーバーレスコンピューティングを使用するジョブを作成するためのバンドル構成を示します。

サーバーレスコンピューティングを使用してノートブックタスクを含むジョブを実行するには、バンドル構成ファイルから 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>

「ワークフローのサーバーレスコンピューティングを使用した Azure Databricks ジョブの実行」を参照してください。

次の方法で共有

Databricks アセットバンドルを使用して Azure Databricks でジョブを開発する

要件

プロジェクトテンプレートを使用してバンドルを作成する

手順 1: 認証を設定する

手順 2: バンドルを初期化する

手順 3: バンドルを調べる

手順 4: プロジェクトのバンドル構成ファイルを検証する

手順 5: ローカルプロジェクトをリモートワークスペースにデプロイする

手順 6: デプロイされたプロジェクトを実行する

手順 7: クリーンアップする

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

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

Databricks CLI を使用して既存のジョブ定義を生成する

サーバーレスコンピューティングを使用するジョブを構成する

フィードバック

その他のリソース

次の方法で共有

Databricks アセット バンドルを使用して Azure Databricks でジョブを開発する

要件

プロジェクト テンプレートを使用してバンドルを作成する

手順 1: 認証を設定する

手順 2: バンドルを初期化する

手順 3: バンドルを調べる

手順 4: プロジェクトのバンドル構成ファイルを検証する

手順 5: ローカル プロジェクトをリモート ワークスペースにデプロイする

手順 6: デプロイされたプロジェクトを実行する

手順 7: クリーン アップする

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

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

Databricks CLI を使用して既存のジョブ定義を生成する

サーバーレス コンピューティングを使用するジョブを構成する

フィードバック

その他のリソース

Databricks アセットバンドルを使用して Azure Databricks でジョブを開発する

プロジェクトテンプレートを使用してバンドルを作成する

手順 5: ローカルプロジェクトをリモートワークスペースにデプロイする

手順 7: クリーンアップする

サーバーレスコンピューティングを使用するジョブを構成する