Databricksアセットバンドル設定

この記事では、 Databricks アセット バンドルを定義する Databricks アセット バンドル構成ファイルの構文について説明します。 「Databricks アセット バンドルとは」を参照してください。

バンドル構成ファイルは YAML 形式で表現する必要があり、少なくとも最上位の バンドル マッピングが含まれている必要があります。 各バンドルには、 databricks.ymlという名前のバンドル設定ファイルが少なくとも 1 つ(1 つだけ)含まれている必要があります。 バンドル構成ファイルが複数ある場合は、 databricks.yml ファイルで参照する必要があります。

YAML の詳細については、公式の YAML 仕様 と チュートリアルを参照してください。

バンドル構成ファイルを作成して操作するには、 「Databricks アセット バンドルの開発ワークフロー」を参照してください。

概要

このセクションでは、バンドル構成ファイルのスキーマを視覚的に表現します。 詳細については、「 マッピング」を参照してください。

# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  compute_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

# These are any additional configuration files to include.
include:
  - "<some-file-or-path-glob-to-include>"
  - "<another-file-or-path-glob-to-include>"

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the Experiments API's create experiment request payload reference.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See the Jobs API's create job request payload reference.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the Models API's create model request payload reference.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the Delta Live Tables API's create pipeline request payload reference.

# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    compute_id: string
    default: true | false
    mode: development
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

例

バンドル設定ファイルの例を次に示します。 このバンドルは、databricks.ymlという名前のこのローカルバンドル設定ファイルと同じディレクトリにある hello.py という名前のローカルファイルのリモート展開を指定します。このノートブックは、指定されたクラスター ID を持つリモート クラスターを使用してジョブとして実行されます。 リモート ワークスペースの URL とワークスペース認証資格情報は、 DEFAULTという名前の呼び出し元のローカル構成プロファイルから読み取られます。

注

Databricks では、バンドル構成ファイルの移植性を高めるため、可能な限りdefaultマッピングではなくhostマッピングを使用することをお勧めします。host マッピングを設定すると、Databricks CLI は .databrickscfg ファイル内で一致するプロファイルを検索し、そのプロファイルのフィールドを使用して、使用する Databricks 認証の種類を決定します。一致する host フィールドを持つ複数のプロファイルが .databrickscfg ファイル内に存在する場合は、 profile を使用して、使用する特定のプロファイルを Databricks CLI に指示する必要があります。 例については、このセクションで後述する prod ターゲット宣言を参照してください。

この手法を使用すると、 resources ブロック内のジョブ定義と設定を再利用およびオーバーライドできます。

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

次のバンドル構成ファイルは機能的には同等ですが、モジュール化されていないため、適切に再利用できません。 また、この宣言は、既存のジョブをオーバーライドするのではなく、ジョブにタスクを追加します。

bundle:
  name: hello-bundle

targets:
  dev:
    default: true
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 1234-567890-abcde123
              notebook_task:
                notebook_path: ./hello.py

前のモジュール化された例を次に示しますが、別のリモート ワークスペース URL とワークスペース認証資格情報を使用するプログラム (または論理) 名 prod を持つターゲットが追加されており、呼び出し元の .databrickscfg ファイルの指定されたワークスペース URL と一致する host エントリから読み取られます。 このジョブ は同じノートブックを実行しますが、指定されたクラスター ID を持つ別のリモートクラスターを使用します。 notebook_task notebook_task マッピングが prod マッピング内で明示的にオーバーライドされていない場合は、 resources prod マッピング内で notebook_task マッピングを使用するようにフォールバックするため、マッピング内でマッピングを宣言する必要はありません。

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

dev ターゲット内でこのジョブを検証、デプロイ、実行するには、次のコマンドを実行します。

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

代わりに、 prod ターゲット内でこのジョブを検証、デプロイ、および実行するには、次のコマンドを実行します。

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

以下は前の例ですが、コンポーネントファイルに分割して、さらにモジュール化し、複数のバンドル設定ファイルでの再利用を改善します。 この手法を使用すると、さまざまな定義と設定を再利用できるだけでなく、これらのファイルを、まったく異なる宣言を提供する他のファイルと交換することもできます。

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

bundle.targets.yml:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

その他の例については、 GitHub のバンドル例リポジトリを参照してください。

マッピング

以下のセクションでは、バンドル構成ファイルの構文をトップレベルマッピングで説明します。

バンドル

バンドル構成ファイルには、バンドルのコンテンツと Databricks ワークスペース設定を関連付ける最上位の bundle マッピングが 1 つだけ含まれている必要があります。

この bundle マッピングには、バンドルのプログラム (または論理) 名を指定する name マッピングが含まれている必要があります。 次の例では、プログラム (または論理) 名 hello-bundleのバンドルを宣言します。

bundle:
  name: hello-bundle

bundleマッピングは、最上位のターゲット・マッピング内の1つ以上のターゲットの子にすることもできます。これらの各子 bundle マッピングは、ターゲット・レベルでデフォルト以外のオーバーライドを指定します。 ただし、最上位レベルの bundle マッピングの name 値は、ターゲット・レベルでオーバーライドできません。

コンピュート

bundleマッピングは、子compute_idマッピングを持つことができます。このマッピングにより、バンドル構成ファイルの他の場所で定義されているすべてのクラスターのオーバーライドとして使用するクラスターの ID を指定できます。 このオーバーライドは、本番運用前の開発専用シナリオを対象としています。 compute_idマッピングは、modeマッピングが developmentに設定されているターゲットに対してのみ機能します。compute_id マッピングの詳細については、「ターゲット マッピング」を参照してください。

gitの

バンドルに関連付けられている Git バージョン管理の詳細を取得および上書きできます。 これは、デプロイされたリソースに注釈を付けるのに役立ちます。 たとえば、デプロイする機械学習モデルの説明内にリポジトリの元の URL を含めたい場合があります。

validate、deploy 、 runなどの bundle コマンドを実行するたびに、 bundle コマンドはコマンドの構成ツリーに次のデフォルト設定を設定します。

• bundle.git.origin_urlこれは、 repoのオリジン URL を表します。 これは、複製された repoからコマンドgit config --get remote.origin.urlを実行した場合に得られる値と同じです。 置換 を使用して、 バンドル設定ファイルでこの値を参照できます ( ${bundle.git.origin_url}を参照)。

• bundle.git.branchこれは、 repo内の現在のブランチを表します。 これは、複製された repoからコマンドgit branch --show-currentを実行した場合に得られる値と同じです。 置換 を使用して、 バンドル設定ファイルでこの値を参照できます ( ${bundle.git.branch}を参照)。

• bundle.git.commitこれは、 repo内のHEADコミットを表します。 これは、複製された repoからコマンドgit rev-parse HEADを実行した場合に取得される値と同じです。 置換 を使用して、 バンドル設定ファイルでこの値を参照できます ( ${bundle.git.commit}を参照)。

Git 設定を取得またはオーバーライドするには、バンドルが Git リポジトリに関連付けられているディレクトリ ( git clone コマンドを実行して初期化されるローカルディレクトリなど) 内にある必要があります。 ディレクトリが Git リポジトリに関連付けられていない場合、これらの Git 設定は空です。

必要に応じて、最上位の bundle マッピングの git マッピング内の origin_url と branch の設定を次のように上書きできます。

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

データブリックス CLI バージョン

bundleマッピングには、バンドルに必要な Databricks CLI バージョンを制限するdatabricks_cli_versionマッピングを含めることができます。 これにより、特定のバージョンの Databricks CLI でサポートされていないマッピングを使用することによって発生する問題を防ぐことができます。

Databricks CLI バージョンはセマンティック バージョン管理に準拠しており、 databricks_cli_versionマッピングはバージョン制約の指定をサポートしています。 現在の databricks --version 値がバンドルの databricks_cli_version マッピングで指定された境界内にない場合、バンドルで databricks bundle validate を実行するとエラーが発生します。 次の例は、一般的なバージョン制約の構文を示しています。

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

変数

バンドル設定ファイルには、使用する変数設定を指定するための最上位 variables マッピングを 1 つ含めることができます。 カスタム変数を参照してください。

ワークスペース

バンドル構成ファイルには、使用する既定以外の Databricks ワークスペース設定を指定するための最上位の workspace マッピングを 1 つだけ含めることができます。

この workspace マッピングには、デプロイとワークフロー実行の両方でワークスペース内で使用する既定以外のルートパスを指定するための root_path マッピングを含めることができます。

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

既定では、root_path Databricks CLI では、置換を使用する /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}のデフォルト パスが使用されます。

この workspace マッピングには、デプロイとワークフロー実行の両方でワークスペース内で使用するデフォルト以外のアーティファクトパスを指定する artifact_path マッピングを含めることもできます。

workspace:
  artifact_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts

既定では、artifact_path Databricks CLI では、置換を使用する ${workspace.root}/artifactsのデフォルト パスが使用されます。

..note:: artifact_path マッピングは、Databricks File System (DBFS) パスをサポートしていません。

この workspace マッピングには、デプロイとワークフロー実行の両方でワークスペース内で使用するデフォルト以外のファイルパスを指定するための file_path マッピングを含めることもできます。

workspace:
  file_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files

既定では、file_path Databricks CLI では、置換を使用する ${workspace.root}/filesのデフォルト パスが使用されます。

デフォルトを ${workspace.root}/state のデフォルトパスにマッピングする state_path であり、デプロイに関する Terraform 状態情報を格納するワークスペース内のパスを表します。

workspace マッピングには、使用する Databricks 認証メカニズムを指定するために、次のオプションのマッピングを含めることもできます。このworkspaceマッピング内で指定されていない場合は、最上位のターゲット・マッピング内の1つ以上のターゲットの子としてworkspaceマッピングで指定する必要があります。

重要

Databricks 認証では、次の workspace マッピングの値をハードコーディングする必要があります。 たとえば、${var.*} 構文を使用して、これらのマッピングの値にカスタム変数を指定することはできません。

• profile マッピング (または、Databricks CLI でバンドルの validate、deploy、run、destroy コマンドを実行するときの --profile または -p オプション) では、Databricks 認証のためにこのワークスペースで使用する構成プロファイルの名前を指定します。この構成プロファイルは、Databricks CLI の設定時に作成したプロファイルにマップされます。

  注

  Databricks では、バンドル構成ファイルの移植性を高めるため、profile マッピングの代わりに host マッピング (または Databricks CLI でバンドルの検証、デプロイ、実行、破棄コマンドを実行する際の --profile または -p オプション) を使用することをお勧めします。host マッピングを設定すると、Databricks CLI は .databrickscfg ファイルで一致するプロファイルを検索し、そのプロファイルのフィールドを使用して、使用する Databricks 認証の種類を決定します。.databrickscfg ファイル内に一致するhost フィールドを持つ複数のプロファイルが存在する場合は、profile マッピング (または --profile または -p コマンド ライン オプション) を使用して、使用するプロファイルを Databricks CLI に指示する必要があります。例については、例の prod ターゲット宣言を参照してください。

• host マッピングでは、Databricks ワークスペースの URL を指定します。「ワークスペースのインスタンス名、URL、および ID」を参照してください。

• OAuthマシン間(M2M)認証では、マッピング client_id が使用されます。 または、ローカル環境変数 DATABRICKS_CLIENT_IDでこの値を設定することもできます。 または、 client_id 値を使用して構成プロファイルを作成し、 profile マッピングでプロファイルの名前を指定することもできます (または、Databricks CLI でバンドルの検証、デプロイ、実行、破棄コマンドを実行するときに --profile または -p オプションを使用します)。 OAuthマシン間(M2M)認証を参照してください。

  注

  バンドル構成ファイルでクライアント・シークレット値を指定することはできません。 代わりに、ローカル環境変数 DATABRICKS_CLIENT_SECRETを設定します。 または、構成プロファイルに client_secret 値を追加し、 profile マッピングでプロファイルの名前を指定することもできます (または、Databricks CLI でバンドルの検証、デプロイ、実行、破棄コマンドを実行するときに --profile または -p オプションを使用します)。

• auth_type マッピングでは、特に Databricks CLI が予期しない認証の種類を推測する場合に使用する Databricks 認証の種類を指定します。「 認証タイプ」フィールドを参照してください。

権限

最上位の permissions マッピングでは、バンドルで定義されているすべてのリソースに適用する 1 つ以上のアクセス許可レベルを指定します。 特定のリソースにアクセス許可を適用する場合は、「 特定のリソースのアクセス許可を定義する」を参照してください。

許可される最上位のアクセス許可レベルは、 CAN_VIEW、 CAN_MANAGE、 CAN_RUNです。

バンドル構成ファイルの次の例では、バンドル内の resources で定義されているすべてのジョブ、パイプライン、エクスペリメント、およびモデルに適用される、ユーザー、グループ、およびサービスプリンシパルのアクセス許可レベルを定義します。

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

成果 物

最上位の artifacts マッピングでは、バンドルのデプロイ中に自動的に構築され、後でバンドルの実行で使用できる 1 つ以上の成果物を指定します。 各子アーティファクトは、次のマッピングをサポートしています。

• type は必須です。 デプロイ前にPython wheelファイルを構築するには、このマッピングを whl に設定する必要があります。

• path オプションの、バンドル構成ファイルの場所からPython wheelファイルの setup.py ファイルの場所までの相対パスです。 path が含まれていない場合、 Databricks CLIバンドルのルートでPython wheelファイルの setup.py ファイルを見つけようとします。

• files は、子 source マッピングを含むオプションのマッピングであり、複雑なビルド命令に含める既定以外の場所を指定するために使用できます。 場所は、バンドル構成ファイルの場所からの相対パスとして指定されます。

• build は、デプロイ前にローカルで実行するデフォルト以外のビルドコマンドのオプションセットです。 Python wheel ビルドの場合、Databricks CLI は、ビルドを実行するための Python wheel パッケージのローカル インストールを見つけることができることを前提としており、各バンドル デプロイ中に既定でコマンド python setup.py bdist_wheel を実行します。 複数のビルド コマンドを指定するには、各コマンドを 2 アンパサンド (&&) 文字で区切ります。

artifactsPython wheelDatabricksを使用するサンプル バンドルなどの詳細については、 アセット バンドルを使用した ファイルの開発」 を参照してください。

ヒント

バンドル内の成果物の設定を定義、結合、およびオーバーライドするには、「 Databricks アセット バンドルで成果物設定を動的に定義する」で説明されている手法を使用します。

含める

include 配列は、バンドル内に含める構成ファイルを含むパス glob のリストを指定します。これらのパス glob は、パス glob が指定されているバンドル構成ファイルの場所に対する相対パスです。

Databricks CLI には、バンドル内に既定で構成ファイルは含まれません。 include 配列を使用して、 databricks.yml ファイル自体以外の、バンドルに含めるすべての構成ファイルを指定する必要があります。

この include 配列は、最上位のマッピングとしてのみ表示できます。

バンドル構成ファイルの次の例には、指定された 3 つの構成ファイルが含まれています。 これらのファイルは、バンドル構成ファイルと同じディレクトリにあります。

include:
  - "bundle.artifacts.yml"
  - "bundle.resources.yml"
  - "bundle.targets.yml"

バンドル設定ファイルの次の例には、 bundle で始まり .ymlで終わるファイル名を持つすべてのファイルが含まれています。 これらのファイルは、バンドル構成ファイルと同じディレクトリにあります。

include:
  - "bundle*.yml"

リソース

resourcesマッピングは、バンドルによって使用される Databricks リソースに関する情報を指定します。

このresourcesマッピングは、最上位レベルのマッピングとして表示されるか、最上位レベルのターゲットマッピング内の 1 つ以上のターゲットの子になることができ、サポートされているリソース タイプが 0 個または 1 個含まれます。 各リソース タイプ マッピングには 1 つ以上の個別のリソース宣言が含まれており、それぞれに一意の名前が必要です。 これらの個々のリソース宣言では、YAML で表現された対応するオブジェクトの作成操作のリクエスト ペイロードを使用して、リソースを定義します。 リソースでサポートされるプロパティは、対応するオブジェクトのサポートされるフィールドです。

作成操作要求ペイロードについては、Databricks REST API リファレンスに記載されており、 databricks bundle schemaコマンドはサポートされているすべてのオブジェクト スキーマを出力します。 さらに、バンドル構成ファイル内に不明なリソース プロパティが見つかった場合、 databricks bundle validateコマンドは警告を返します。

次の表に、バンドルでサポートされているリソース タイプと、対応するペイロードに関するドキュメントへのリンクを示します。

リソースタイプ	リソースマッピング
jobs	ジョブ マッピング: POST /api/2.1/jobs/create 追加情報については、 「ジョブ タスク タイプ」を参照し、 「新しいジョブ クラスター設定を上書きする」を参照してください。
pipelines	パイプラインマッピング: POST /api/2.0/pipelines
experiments	エクスペリメントのマッピング: POST /api/2.0/mlflow/エクスペリメント/create
models	モデル マッピング: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoints	モデルサービングエンドポイントマッピング: POST /api/2.0/serving-endpoints
registered_models (Unity Catalog)	Unity Catalogモデルのマッピング: POST /api/2.1/unity-catalog/models

リソース宣言によって参照されるフォルダーおよびファイルへのすべてのパスは、これらのパスが指定されているバンドル構成ファイルの場所を基準としています。

次の例では、リソース キーhello-jobを持つジョブとリソース キーhello-pipelineを持つパイプラインを宣言します。

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

同期

sync 配列は、次のルールに応じて、バンドル展開に含める、またはバンドル展開から除外するファイルまたはパスの glob のリストを指定します。

• バンドルのルートにある .gitignore ファイル内のファイルとパスのグロブのリストに基づいて、 include マッピングには、バンドルのルートを基準としたファイルグロブ、パスグロブ、またはその両方のリストを含めて、明示的に含めることができます。

• バンドルのルート内の .gitignore ファイル内のファイルおよびパスグロブのリスト、および include マッピング内のファイルおよびパスグロブのリストに基づいて、 exclude マッピングには、明示的に除外するバンドルのルートを基準としたファイルグロブ、パスグロブ、またはその両方のリストを含めることができます。

指定されたフォルダーおよびファイルへのすべてのパスは、これらのパスが指定されているバンドル構成ファイルの場所に対する相対パスです。

include および exclude ファイルとパスのパターンの構文は、標準の.gitignoreパターン構文に従います。gitignore パターン形式を参照してください。

たとえば、次の .gitignore ファイルに次のエントリが含まれているとします。

.databricks
my_package/dist

また、バンドル構成ファイルには、次の include マッピングが含まれています。

sync:
  include:
    - my_package/dist/*.whl

次に、ファイル拡張子が *.whl の my_package/dist フォルダー内のすべてのファイルが含まれます。my_package/dist フォルダー内のその他のファイルは含まれません。

ただし、バンドル構成ファイルに次の exclude マッピングも含まれている場合:

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

次に、 my_package/dist フォルダー内のファイル拡張子が *.whlのすべてのファイルが含まれますが、 delete-me.whlという名前のファイルは含まれません。 my_package/dist フォルダー内の他のファイルも含まれません。

sync配列は、特定のターゲットのtargetsマッピングで宣言することもできます。ターゲットで宣言された sync 配列は、最上位の sync 配列宣言とマージされます。 たとえば、前の例を続けると、targets レベルでの次のincludeマッピングは、最上位の sync 配列のincludeマッピングとマージされます。

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

databricks bundle validate --output jsonを実行すると、結果のグラフの関連部分は次のようになります。

"sync": {
  "include": [
    "my_package/dist/*.whl",
    "my_package/dist/delete-me.whl"
  ],
  "exclude": [
    "my_package/dist/delete-me.whl"
  ]
}

ターゲット

targets マッピングでは、Databricks ワークフローを実行する 1 つ以上のコンテキストを指定します。各 ターゲット は、成果物、Databricks ワークスペース設定、Databricks ジョブまたはパイプラインの詳細の一意のコレクションです。

この targets マッピングはオプションですが、強くお勧めします。 指定した場合は、最上位のマッピングとしてのみ表示できます。 targets マッピングが指定されていない場合は、最上位 ワークスペース、成果物、および リソース マッピングの設定が常に使用されます。

targets マッピングは 1 つ以上のターゲット マッピングで構成され、それぞれに固有のプログラム (または論理) 名が必要です。

ターゲット マッピングで workspace、 artifacts、または resources 子マッピングが指定されていない場合、そのターゲットは最上位の workspace、 artifacts、および resources マッピングの設定を使用します。

ターゲット マッピングで workspace、 artifacts、または resources マッピングが指定されており、最上位の workspace、 artifacts、または resources マッピングも存在する場合、競合する設定はターゲット内の設定によってオーバーライドされます。

ターゲットは、最上位 の変数の値をオーバーライドすることもできます。

特に指定しない限り、ターゲットがデフォルトのターゲットであることを指定するには、 default マッピングを追加し、 trueに設定します。 たとえば、 dev という名前のこのターゲットは既定のターゲットです。

targets:
  dev:
    default: true

ターゲットが開発ターゲットとして扱われるように指定するには、 mode マッピングを追加し、 developmentに設定します。 ターゲットが本番運用ターゲットとして扱われるように指定するには、 mode マッピングを追加し、 productionに設定します。 たとえば、 prod という名前のこのターゲットは、本番運用ターゲットとして扱われます。

targets:
  prod:
    mode: production

modeを指定すると、本番運用前および本番運用ワークフローに対応するデフォルト動作のコレクションが提供されます。 詳細については、 「Databricks Asset Bundle のデプロイ モード」を参照してください。 さらに、 「Databricks Asset Bundles ワークフローの実行 ID を指定する」で説明されているように、ターゲットごとにrun_as指定することもできます。

次の例では、2 つのターゲットを宣言します。 最初のターゲットは、プログラム上の (または論理的な) 名前が dev で、既定のターゲットです。 2 番目のターゲットは、プログラム上の (または論理的な) 名前が prod であり、既定のターゲットではありません。 この 2 番目のターゲットは、認証に PROD という名前の Databricks 接続プロファイルを使用します。

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

dev ターゲット内でジョブまたはパイプラインを検証、デプロイ、および実行するには、次のコマンドを実行します。

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run <job-or-pipeline-programmatic-name>

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev <job-or-pipeline-programmatic-name>

代わりに、 prod ターゲット内でこのジョブを検証、デプロイ、および実行するには、次のコマンドを実行します。

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod <job-or-pipeline-programmatic-name>

カスタム変数

カスタム変数を使用して、バンドル構成ファイルをよりモジュール化して再利用できるようにすることができます。 たとえば、既存のクラスターの ID を表す変数を宣言し、バンドル構成ファイルの元のコードを変更せずに、複数のターゲット内で実行されるさまざまなワークフローの異なるクラスター ID にその変数の値を変更したい場合があります。

variablesマッピング内のバンドル設定ファイルで 1 つ以上の変数を宣言できます。変数ごとに、次の形式に従って、オプションの説明、デフォルト値、または ID 値を取得するための検索を設定できます。

variables:
  <variable-name>:
    description: <optional-description>
    default: <optional-default-value>
    lookup:
      <optional-object-type>: <optional-object-name>

たとえば、既定値が 1234-567890-abcde123の my_cluster_id という名前の変数と、既定値が ./hello.pyの my_notebook_path という名前の変数を宣言するには、次のようにします。

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

この宣言の一部として変数の default 値を指定しない場合は、後でコマンドライン、環境変数、またはバンドル設定ファイル内の他の場所で値を指定する必要があります。 これらの方法については、このセクションの後半で説明します。

注

変数値を指定するためにどのアプローチを選択する場合でも、展開段階と実行段階の両方で同じアプローチを使用してください。 そうしないと、デプロイメント時と、その既存のデプロイメントに基づくジョブまたはパイプラインの実行時との間に、予期しない結果が発生する可能性があります。

バンドル設定ファイル内でカスタム変数を参照するには、 置換を使用します。 変数には、 ${var.<variable_name>}という形式を使用します。 たとえば、 my_cluster_id と my_notebook_pathという名前の変数を参照するには、次のようにします。

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

変数の値を設定する

変数に default 値を指定していない場合、または変数の default 値を一時的にオーバーライドする場合は、次のいずれかの方法を使用して、変数の新しい一時値を指定します。

• 変数の値を validate、 deploy、 runなどの bundle コマンドの一部として指定します。これを行うには、オプション --var="<key>=<value>"を使用します。ここで、 <key> は変数の名前、 <value> は変数の値です。 たとえば、 bundle validate コマンドの一部として、 my_cluster_idという名前の変数に 1234-567890-abcde123 の値を指定し、 my_notebook_pathという名前の変数に ./hello.py の値を指定するには、次のコマンドを実行します。

  databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"
  
  # Or:
  databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
  

• 環境変数を設定して、変数の値を指定します。 環境変数の名前は BUNDLE_VAR_で始まる必要があります。 環境変数を設定するには、オペレーティングシステムのマニュアルを参照してください。 たとえば、 my_cluster_idという名前の変数に 1234-567890-abcde123 の値を指定し、 my_notebook_pathという名前の変数に ./hello.py の値を指定するには、 validate、deploy、 runなどの bundle コマンドを呼び出す前に次のコマンドを実行します。

  Linux および macOS の場合:

  export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
  

  ウィンドウズの場合:

  "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
  

  または、 validate、deploy、 runなどの bundle コマンドの一部として変数の値を指定します(LinuxやmacOSの場合など)。

  BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
  

  またはウィンドウズの場合:

  "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
  

• バンドル構成ファイル内で変数の値を指定します。 これを行うには、次の形式に従って、targets マッピング内でvariablesマッピングを使用します。

  variables:
    <variable-name>: <value>
  

  たとえば、2 つの異なるターゲットの my_cluster_id と my_notebook_path という名前の変数の値を指定するには、次のようにします。

  targets:
    dev:
      variables:
        my_cluster_id: 1234-567890-abcde123
        my_notebook_path: ./hello.py
    prod:
      variables:
        my_cluster_id: 2345-678901-bcdef234
        my_notebook_path: ./hello.py
  

前の例では、Databricks CLI は次の順序で変数 my_cluster_id と my_notebook_path の値を検索し、一致する各変数の値を見つけると停止し、その変数の他の場所はスキップします。

1. bundle コマンドの一部として指定された任意の --var オプション内。

2. BUNDLE_VAR_で始まる環境変数セット内。

3. variablesマッピング内、バンドル構成ファイル内のtargetsマッピング内。

4. バンドル構成ファイル内の最上位のvariablesマッピングの中で、その変数の定義のdefault値。

オブジェクトの ID 値を取得する

alert、 cluster_policy、 cluster、 dashboard、 instance_pool、 job、 metastore、 pipeline、 query、 service_principal、および warehouse オブジェクトタイプの場合、カスタム変数のlookupを定義して、次の形式を使用して名前付きオブジェクトの ID を取得できます。

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

変数にルックアップが定義されている場合、指定された名前を持つオブジェクトの ID が変数の値として使用されます。 これにより、オブジェクトの正しい解決済み ID が常に変数に使用されます。

注

指定した名前のオブジェクトが存在しない場合、または指定した名前のオブジェクトが複数ある場合は、エラーが発生します。

たとえば、次の構成では、 ${var.my_cluster_id} 12.2 共有クラスターの ID に置き換えられます。

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}

置換

置換を使用して、バンドル設定ファイルをよりモジュール化して再利用可能にすることができます。

ヒント

ジョブ パラメーター値の動的な値参照を使用して、ジョブ実行に関するコンテキストをジョブ タスクに渡すこともできます。 「ジョブ実行に関するコンテキストをジョブタスクに渡す」を参照してください。

たとえば、 bundle validate --output json コマンドを実行すると、次のようなグラフが表示されます(簡潔にするために、省略記号は省略された内容を示しています)。

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

前の例では、バンドル設定ファイルで someone@example.com 値を置換 ${workspace.current_user.userName}で参照できます。

同様に、以下の置換:

/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

次のようなバンドル構成ファイル (省略記号は、簡潔にするために省略されたコンテンツを示します)。

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

bundle validate --output json コマンドを実行すると、次のグラフに解決されます(省略記号は、簡潔にするために省略された内容を示しています)。

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "profile": "DEFAULT",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

名前付きリソースの代替を作成することもできます。 たとえば、名前my_pipelineで構成されたパイプラインの場合、 ${resources.pipelines.my_pipeline.target} my_pipelineのターゲットの値の代替になります。

有効な置換を決定するには、 REST API リファレンスに記載されているスキーマ階層、またはbundle schemaコマンドの出力を使用できます。

ここでは、一般的に使用される置換をいくつか紹介します。

• ${bundle.name}

• ${bundle.target}  # Use this substitution instead of ${bundle.environment}

• ${workspace.host}

• ${workspace.current_user.short_name}

• ${workspace.current_user.userName}

• ${workspace.file_path}

• ${workspace.root_path}

• ${resources.jobs.<job-name>.id}

• ${resources.models.<model-name>.name}

• ${resources.pipelines.<pipeline-name>.name}