`bundle` コマンドグループ

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

Note

この情報は、Databricks CLI バージョン 0.205 以降に適用されます。 Databricks CLI は Public Preview です。

Databricks CLI の使用には、Databricks ライセンスおよび使用状況データのプロビジョニングを含むDatabricks のプライバシーに関する通知が適用されます。

Databricks CLI の bundle コマンドグループを使用すると、Azure Databricks ワークフロー (Azure Databricks ジョブ、Delta Live Tables パイプライン、MLOps スタックなど) の検証、デプロイ、実行をプログラムで行うことができます。「Databricks アセットバンドルとは」をご覧ください。

bundle コマンドは、databricks bundle に追加して実行します。 bundle コマンドのヘルプを表示するには、databricks bundle -h を実行してください。

プロジェクトテンプレートからバンドルを作成する

Python 用の既定の Databricks アセットバンドルテンプレートを使用して Databricks アセットバンドルを作成するには、次のように bundle init コマンドを実行し、画面上のプロンプトに応答します。

databricks bundle init

カスタム Databricks アセットバンドルテンプレートを使用して Databricks アセットバンドルを作成するには、次のように bundle init コマンドを実行します。

databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"

バンドル構成スキーマを表示する

Databricks アセットバンドル構成スキーマを表示するには、以下のように bundle schema コマンドを実行します。

databricks bundle schema

Databricks アセットバンドル構成スキーマを JSON ファイルとして出力するには、bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトします。たとえば、現在のディレクトリ内に bundle_config_schema.json というファイルを生成するには、以下のようにします。

databricks bundle schema > bundle_config_schema.json

バンドルを検証する

バンドル構成ファイルの構文が正しいことを検証するには、次のようにバンドルプロジェクトルートから bundle validate コマンドを実行します。

databricks bundle validate

既定では、このコマンドは以下のようなバンドル ID のサマリーを返します。

Name: MyBundle
Target: dev
Workspace:
  Host: https://my-host.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/MyBundle/dev

Validation OK!

Note

bundle validate コマンドは、対応するオブジェクトのスキーマ内に見つからないバンドル構成ファイルでリソースプロパティが定義されている場合に警告を出力します。

バンドルの ID とリソースの概要のみを出力する場合は、バンドルの概要を使用します。

バンドルのツリーをワークスペースに同期する

ローカルファイルシステムディレクトリ内でバンドルのファイルに加えた変更内容を、一方向の同期でリモート Azure Databricks ワークスペース内のディレクトリに反映するには、bundle sync コマンドを実行します。

Note

bundle sync コマンドは、リモート Azure Databricks ワークスペース内のディレクトリからローカルファイルシステム内のディレクトリにファイルの変更を同期することはできません。

databricks bundle sync コマンドは、生産性向上のために用意されているものであり、databricks sync コマンドと同じように機能します。コマンドの使用法については、「sync コマンドグループを参照してください。

バンドル構成ファイルを生成する

bundle generate コマンドを使用すると、Databricks ワークスペースに既に存在する job、pipeline、または dashboard のリソース構成を生成できます。このコマンドは、ジョブ、パイプライン、またはダッシュボードの *.yml ファイルをバンドルプロジェクトの resources フォルダーに生成し、構成で参照されているノートブックなどのファイルもダウンロードします。

ジョブまたはパイプラインの構成を生成する

重要

bundle generate コマンドは、リソース構成を自動生成するために便宜上提供されます。ただし、このジョブまたはパイプライン構成がバンドルに含まれてデプロイされると、新しいリソースが作成され、 bundle deployment bind が最初に使用されていない限り、既存のリソースは更新されません。バンドルリソースバインドを参照してください。

ジョブまたはパイプラインの構成を生成するには、次のように bundle generate コマンドを実行します。

databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]

Note

現在、このコマンドでは、ノートブックタスクを含むジョブのみがサポートされています。

たとえば、次のコマンドでは、以下の YAML を含む resources バンドルプロジェクトフォルダーに新しい hello_job.yml ファイルが生成され、simple_notebook.py が src プロジェクトフォルダーにダウンロードされます。

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

# This is the contents of the resulting hello_job.yml file.
resources:
  jobs:
    6565621249:
      name: Hello Job
      format: MULTI_TASK
      tasks:
        - task_key: run_notebook
          existing_cluster_id: 0704-xxxxxx-yyyyyyy
          notebook_task:
            notebook_path: ./src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

ダッシュボード構成の生成

ワークスペース内の既存のダッシュボードの構成を生成するには、 bundle generateを実行し、ダッシュボードの ID またはワークスペースパスを指定します。

databricks bundle generate dashboard --existing-id [dashboard-id]

databricks bundle generate dashboard --existing-path [dashboard-workspace-path]

ダッシュボードのワークスペースパスは、ワークスペース UI からコピーできます。

たとえば、次のコマンドは、以下の YAML を含む resources バンドルプロジェクトフォルダーに新しいbaby_gender_by_county.dashboard.yml ファイルを生成し、baby_gender_by_county.lvdash.json ファイルを src プロジェクトフォルダーにダウンロードします。

databricks bundle generate dashboard --existing-path "/Workspace/Users/someone@example.com/baby_gender_by_county.lvdash.json"

# This is the contents of the resulting baby_gender_by_county.dashboard.yml file.
resources:
  dashboards:
    baby_gender_by_county:
      display_name: "Baby gender by county"
      warehouse_id: aae11o8e6fe9zz79
      file_path: ../src/baby_gender_by_county.lvdash.json

ヒント

既にダッシュボードをデプロイした後に.lvdash.json ファイルを更新するには、bundle generate dashboardを実行して既存のダッシュボードリソースのファイルを生成するときに、--resource オプションを使用します。ダッシュボードの更新プログラムを継続的にポーリングして取得するには、 --force オプションと --watch オプションを使用します。

バンドルリソースをバインドする

bundle deployment bind コマンドを使うと、バンドルで定義されたジョブとパイプラインを Azure Databricks ワークスペース内の既存のジョブおよびパイプラインにリンクし、Databricks アセットバンドルの管理対象にすることができます。リソースをバインドする場合、ワークスペース内の既存の Azure Databricks リソースは、次の bundle deploy の後に、バインドされているバンドルで定義された構成に基づいて更新されます。

ヒント

バインドを実行する前に、ワークスペース内のバンドルを確認することをお勧めします。

databricks bundle deployment bind [resource-key] [resource-id]

たとえば、次のコマンドを実行すると、リソース hello_job をワークスペース内のリモートの対応するリソースにバインドできます。このコマンドは差分を出力し、ユーザーはリソースのバインドを拒否できますが、承認した場合は、次にバンドルがデプロイされる際に、バンドル内のジョブ定義に対するすべての更新が対応するリモートジョブに適用されます。

databricks bundle deployment bind hello_job 6565621249

バンドル内のジョブまたはパイプラインと、ワークスペース内のリモートの対応するジョブまたはパイプラインとの間のリンクを削除したい場合は、bundle deployment unbind を使います。

databricks bundle deployment unbind [resource-key]

バンドルの概要を出力する

bundle summary コマンドは、Databricks ワークスペース内のリソースに簡単に移動できるように、リソースのディープリンクなど、バンドルの ID とリソースの概要を出力します。

databricks bundle summary

次の出力例は、ジョブとパイプラインを定義する my_pipeline_bundle という名前のバンドルの概要です。

Name: my_pipeline_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/my_pipeline/dev
Resources:
  Jobs:
    my_project_job:
      Name: [dev someone] my_project_job
      URL:  https://myworkspace.cloud.databricks.com/jobs/206000809187888?o=6051000018419999
  Pipelines:
    my_project_pipeline:
      Name: [dev someone] my_project_pipeline
      URL:  https://myworkspace.cloud.databricks.com/pipelines/7f559fd5-zztz-47fa-aa5c-c6bf034b4f58?o=6051000018419999

バンドルをデプロイする

バンドルをリモートワークスペースにデプロイするには、バンドルプロジェクトルートから bundle deploy コマンドを実行します。コマンドオプションが指定されていない場合は、バンドル構成ファイル内で宣言されている既定のターゲットが使用されます。

databricks bundle deploy

特定のターゲットにバンドルをデプロイするには、バンドル構成ファイル内で宣言されているターゲットの名前と共に -t (または --target) オプションを設定します。たとえば、dev という名前で宣言されたターゲットの場合、

databricks bundle deploy -t dev

バンドルは、開発、ステージング、運用ワークスペースなど、複数のワークスペースにデプロイできます。基本的に、root_path はバンドルの一意識別子を決定するプロパティで、既定では ~/.bundle/${bundle.name}/${bundle.target} です。そのため、既定では、バンドルの ID は、デプロイ担当者の ID、バンドルの名前、バンドルのターゲット名で構成されます。これらが異なるバンドル間で同一である場合、これらのバンドルのデプロイは相互に干渉します。

さらに、バンドルのデプロイでは、ターゲットワークスペースに作成されたリソースが、ID ごとにワークスペースファイルシステムに保存されている状態として追跡されます。リソース名は、バンドルのデプロイとリソースインスタンスの間の関連付けに使用されないため、次のようになります。

バンドル構成のリソースがターゲットワークスペースに存在しない場合は、自動的に作成されます。
バンドル構成のリソースがターゲットワークスペースに存在する場合は、ワークスペース内で更新されます。
リソースがバンドル構成から削除された場合、以前にデプロイされていた場合は、ターゲットワークスペースからも削除されます。
リソースとバンドルの関連付けを解除できるのは、バンドル名、バンドルのターゲット、またはワークスペースを変更した場合のみです。 bundle validate を実行すると、これらの値を含む概要を出力できます。

バンドルを実行する

特定のジョブまたはパイプラインを実行するには、bundle run コマンドを使用します。バンドル構成ファイル内で宣言されているジョブまたはパイプラインのリソースキーを指定する必要があります。既定では、バンドル構成ファイル内で宣言された環境が使用されます。たとえば、既定の環境でジョブ hello_job を実行するには、次のコマンドを実行します:

databricks bundle run hello_job

dev という名前で宣言されたターゲットのコンテキスト内で、キー hello_job を指定してジョブを実行するには、次のようにします。

databricks bundle run -t dev hello_job

パイプライン検証の実行を行う場合は、次の例に示すように、この --validate-only オプションを使用します:

databricks bundle run --validate-only my_pipeline

ジョブパラメーターを渡すには、--params オプションを使用し、その後にコンマ区切りのキーと値のペアを指定します。キーはパラメーター名です。たとえば、次のコマンドでは、message という名前のパラメーターをジョブ hello_job の HelloWorld に設定します。

databricks bundle run --params message=HelloWorld hello_job

Note

ジョブタスクオプションを使用するとジョブタスクにパラメーターを渡すことができますが、--params オプションはジョブパラメーターを渡すための推奨される方法です。ジョブパラメーターが定義されていないジョブにジョブパラメーターが指定されている場合、あるいはジョブパラメーターが定義されているジョブにタスクパラメーターが指定されている場合、エラーが発生します。

既存のジョブの実行またはパイプラインの更新をキャンセルして再開するには、--restart オプションを使用します。

databricks bundle run --restart hello_job

バンドルを破棄する

警告

バンドルを破棄すると、バンドルの以前にデプロイされたジョブ、パイプライン、成果物が完全に削除されます。この削除操作は元に戻すことができません。

以前にデプロイされたジョブ、パイプライン、成果物を削除するには、bundle destroy コマンドを実行します。以下のコマンドは、バンドル構成ファイルで定義されているジョブ、パイプライン、成果物で以前にデプロイされたものをすべて削除します。

databricks bundle destroy

Note

バンドルの ID は、バンドル名、バンドルのターゲット、ワークスペースで構成されます。これらのいずれかを変更した後、デプロイする前にバンドルを破棄しようとすると、エラーが発生します。

既定では、以前にデプロイされたジョブ、パイプライン、成果物の完全な削除を確認するメッセージが表示されます。これらのプロンプトをスキップし、自動的に完全削除を実行するには、--auto-approve オプションを bundle destroy コマンドに追加します。

次の方法で共有

`bundle` コマンドグループ

プロジェクトテンプレートからバンドルを作成する

バンドル構成スキーマを表示する

バンドルを検証する

バンドルのツリーをワークスペースに同期する

バンドル構成ファイルを生成する

ジョブまたはパイプラインの構成を生成する

ダッシュボード構成の生成

バンドルリソースをバインドする

バンドルの概要を出力する

バンドルをデプロイする

バンドルを実行する

バンドルを破棄する

フィードバック

その他のリソース

次の方法で共有

bundle コマンド グループ

プロジェクト テンプレートからバンドルを作成する

バンドル構成スキーマを表示する

バンドルを検証する

バンドルのツリーをワークスペースに同期する

バンドル構成ファイルを生成する

ジョブまたはパイプラインの構成を生成する

ダッシュボード構成の生成

バンドル リソースをバインドする

バンドルの概要を出力する

バンドルをデプロイする

バンドルを実行する

バンドルを破棄する

フィードバック

その他のリソース

`bundle` コマンドグループ

プロジェクトテンプレートからバンドルを作成する

バンドルリソースをバインドする