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

  • [アーティクル]

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 認証のセットアップ手順をご参照ください。

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

    次のコマンド内では、<workspace-url> を Azure Databricks ワークスペース単位の URL (例: https://adb-1234567890123456.7.azuredatabricks.net) に置き換えます。

    databricks auth login --host <workspace-url>

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

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

  3. Web ブラウザー内で、画面の指示に従って Azure 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 コマンドを実行します：

    databricks bundle init

  3. Template to use は Enter キーを押して default-python の既定値のままにします。

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

  5. Include a stub (sample) notebook の場合は、yes を選択し、Enter を押します。

  6. Include a stub (sample) DLT pipeline の場合は、no を選択し、Enter を押します。 すると、Databricks CLI でバンドル内にサンプル Delta Live Tables パイプラインを定義しないように指示されます。

  7. 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: プロジェクトのバンドル構成ファイルを検証する

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

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

    databricks bundle validate

  2. バンドル構成の概要が返されたら、検証が成功したことになります。 エラーが返される場合は、エラーを修正してから、この手順を繰り返します。

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

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

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

  1. バンドルのルートから、次のように Databricks CLI を使って bundle deploy コマンドを実行します。

    databricks bundle deploy -t dev

  2. そのローカル ノートブックがデプロイされたかどうかをチェックします。お使いの Azure Databricks ワークスペースのサイドバー内で、[ワークスペース] をクリックします。

  3. Users ><your-username>> .bundle ><project-name>> dev > files > src フォルダーをクリックします。 そのノートブックはこのフォルダー内に存在する必要があります。

  4. ジョブが作成されたかどうかを確認します: Azure Databricks ワークスペースのサイドバーで、[ワークフロー] をクリックします。

  5. [ジョブ] タブの [dev <your-username>] <project-name>_job をクリックします。.

  6. [タスク] タブをクリックします。notebook_task という 1 つのタスクがあるはずです。

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

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

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

  1. ルート ディレクトリから、Databricks CLI を使って、bundle run コマンドを次のように実行します。<project-name> は手順 2 のプロジェクトの名前に置き換えます。

    databricks bundle run -t dev <project-name>_job

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

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

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

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

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

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

    databricks bundle destroy -t dev

  2. ジョブの削除要求を確認します: リソースを完全に破棄するように求められたら、「y」と入力し、Enter キーを押します。

  3. ノートブックの削除要求を確認します。以前にデプロイしたフォルダーとそのすべてのファイルを完全に破棄するように求められたら、「y」と入力し、Enter キーを押します。

  4. 開発マシンからもバンドルを削除する場合は、ここで手順 2 のローカル ディレクトリを削除できます。

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

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

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

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

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

  1. Azure Databricks ワークスペースのサイドバーで、[ワークフロー] をクリックします。

  2. [ジョブ] タブで、ジョブの [名前] リンクをクリックします。

  3. [今すぐ実行] ボタンの横にあるケバブをクリックし、[Switch to code (YAML)] (コード (YAML) に切り替え) をクリックします。

  4. バンドルの databricks.yml ファイルにコピーした YAML を追加するか、バンドル プロジェクトの resources ディレクトリにジョブの構成ファイルを作成し、それを databricks.yml ファイルから参照します。 「(/dev-tools/bundles/settings.md#resources)」を参照してください。

  5. 既存のジョブで参照されるすべての 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 を使用して既存のジョブ定義を生成する

既存のジョブのバンドル構成をプログラムで生成するには、次の手順を実行します。

  1. ジョブ UI のジョブの [ジョブの詳細] サイド パネルから既存のジョブの ID を取得するか、Databricks CLI databricks jobs list コマンドを使用します。

  2. 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 ジョブの実行」を参照してください。