Databricks アセット バンドルの構成

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

バンドルを作成して使用するには、Databricks Asset Bundles 開発を参照してください。

概要

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

各トップレベル マッピングの詳細については、「マッピングの」を参照してください。

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

仕様

次の YAML は、Databricks アセット バンドルの構成仕様を提供します。

# This is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  cluster_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 or complex

# 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:
  clusters:
    <some-unique-programmatic-identifier-for-this-cluster>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <some-unique-programmatic-identifier-for-this-dashboard>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See REST API create request payload reference for jobs.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the REST API create request payload reference for models.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the REST API create request payload reference for Delta Live Tables (pipelines).
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema 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>"
  paths:
    - "<some-file-or-path-to-synchronize>"

# 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.
    cluster_id: string
    default: true | false
    mode: development
    presets:
      <preset>: <value>
    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.

例

Note

バンドル機能と一般的なバンドルのユース ケースを示す構成例については、「バンドルの構成例」と、GitHub のバンドル例のリポジトリに関するページを参照してください。

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

バンドル構成ファイルの移植性を高めるために、Databricks では可能な限り host マッピングの代わりに default マッピングを使用することをお勧めします。 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 を持つターゲットを追加します。これは、ワークスペース URL が指定された呼び出し元の .databrickscfg ファイルの一致する host エントリから読み取られます。 このジョブでは同じノートブックを実行しますが、指定されたクラスター ID を持つ別のリモート クラスターを使用します。 notebook_task マッピング内で prod マッピングが明示的にオーバーライドされていない場合は、最上位レベルの notebook_task マッピング内で resources マッピングを使用するようにフォールバックされるため、notebook_task マッピング内で prod を宣言する必要はないことに注目してください。

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

マッピング

次のセクションでは、最上位レベルのマッピングに基づいて、バンドル構成ファイルの構文について説明します。

• bundle
• variables
• ワークスペース
• アクセス許可
• artifacts
• include
• resources
• sync
• <ターゲット>

バンドル

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

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

bundle:
  name: hello-bundle

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

cluster_id

bundle マッピングには子 cluster_id マッピングを含めることができます。 このマッピングを使用すると、バンドル構成ファイル内の他の場所で定義されたクラスターに対するオーバーライドとして使用するクラスターの ID を指定できます。 クラスターの ID を取得する方法については、「クラスターの URL と ID」を参照してください。

cluster_id オーバーライドは開発専用のシナリオを対象としており、mode マッピングが development に設定されているターゲットでのみサポートされます。 target マッピングの詳細については、「ターゲット」を参照してください。

compute_id

Note

この設定は非推奨です。 代わりに cluster_id を使用してください。

bundle マッピングには子 compute_id マッピングを含めることができます。 このマッピングを使用すると、バンドル構成ファイル内の他の場所で定義されたクラスターに対するオーバーライドとして使用するクラスターの ID を指定できます。

git

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

bundle、validate、deploy などの run コマンドを実行するたびに、bundle コマンドでコマンドの構成ツリーに次の既定の設定が取り込まれます。

• bundle.git.origin_url。リポジトリの元の URL を表します。 これは、クローンされたリポジトリからコマンド git config --get remote.origin.url を実行した場合に得られるものと同じ値です。 substitutions を使用して、バンドル構成ファイルでこの値を ${bundle.git.origin_url} として参照できます。
• bundle.git.branch。リポジトリ内の現在のブランチを表します。 これは、クローンされたリポジトリからコマンド git branch --show-current を実行した場合に得られるものと同じ値です。 substitutions を使用して、バンドル構成ファイルでこの値を ${bundle.git.branch} として参照できます。
• bundle.git.commit。リポジトリ内の HEAD コミットを表します。 これは、クローンされたリポジトリからコマンド git rev-parse HEAD を実行した場合に得られるものと同じ値です。 substitutions を使用して、バンドル構成ファイルでこの値を ${bundle.git.commit} として参照できます。

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

次のように、必要に応じて、最上位レベルの origin_url マッピングの branch マッピング内の git と bundle の設定をオーバーライドできます。

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

databricks_cli_version

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 つ含めることができます。 次の形式に従って、変数ごとに、省略可能な説明、既定値、カスタム変数が複合型なのか、または参照なのかを ID 値を取得して設定します：

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

Note

変数は、stringが type に設定されていない限り、complex 型であると見なされます。 「複合変数を定義する」を参照してください。

バンドル構成内でカスタム変数を参照するには、置換を使用します ${var.<variable_name>}。

カスタム変数と置換の詳細については、「Databricks Asset Bundles の サブスクリプションと変数」を参照してください。

ワークスペース

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

重要

有効な Databricks ワークスペース パスは、 /Workspace または /Volumesで始まります。 カスタム ワークスペース パスには自動的に /Workspace のプレフィックスが付けられます。そのため、 ${workspace.file_path}などのカスタム パスでワークスペース パスの置換を使用する場合は、パスの先頭に /Workspace を追加する必要はありません。

root_path

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

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

既定では、root_path の場合、Databricks CLI では、/Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}を使用する、 の既定のパスが使われます。

artifact_path

この workspace マッピングには、デプロイとワークフローの実行の両方にワークスペース内で使用する既定以外の成果物パスを指定するための artifact_path マッピングを含めることもできます。以下に例を示します。

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

既定では、artifact_path の場合、Databricks CLI では、${workspace.root}/artifactsを使用する、 の既定のパスが使われます。

Note

artifact_path マッピングでは Databricks ファイル システム (DBFS) パスはサポートされていません。

file_path

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

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

既定では、file_path の場合、Databricks CLI では、${workspace.root}/filesを使用する、 の既定のパスが使われます。

state_path

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

その他のワークスペース マッピング

workspace マッピングには、次の省略可能なマッピングを含め、使用する Azure Databricks 認証メカニズムを指定することもできます。 この workspace マッピング内で指定されていない場合は、最上位レベルのworkspace マッピング内の 1 つまたは複数のターゲットの子として、 マッピングで指定する必要があります。

重要

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

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

  Note

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

• host マッピングでは、Azure Databricks ワークスペースの URL を指定します。 「ワークスペース単位のURL」を参照してください。

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

  Note

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

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

• サービス プリンシパルを使用した Azure クライアント シークレット認証では、マッピング azure_workspace_resource_id、azure_tenant_id、および azure_client_id が使用されます。 代わりに、これらの値をそれぞれローカル環境変数 DATABRICKS_AZURE_RESOURCE_ID、ARM_TENANT_ID、および ARM_CLIENT_ID で設定することもできます。 または、azure_workspace_resource_id、azure_tenant_id、azure_client_id 値を使用して構成プロファイルを作成してから、profile マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの --profile または -p オプションを使用して) プロファイルの名前を指定できます。 「MS Entra サービス プリンシパルの認証」を参照してください。

  Note

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

• Azure マネージド ID 認証では、マッピング azure_use_msi、azure_client_id、azure_workspace_resource_id が使用されます。 代わりに、これらの値をそれぞれローカル環境変数 ARM_USE_MSI、ARM_CLIENT_ID、および DATABRICKS_AZURE_RESOURCE_ID で設定することもできます。 または、azure_use_msi、azure_client_id、azure_workspace_resource_id 値を使用して構成プロファイルを作成してから、profile マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの --profile または -p オプションを使用して) プロファイルの名前を指定できます。 「Azure マネージド ID 認証」を参照してください。

• azure_environment マッピングでは、特定の API エンドポイントのセットに対して Azure 環境の種類 (Public、UsGov、China、Germany など) を指定します。 既定値は PUBLIC です。 代わりに、ローカル環境変数 ARM_ENVIRONMENT でこの値を設定することもできます。 または、azure_environment 値を構成プロファイルに追加してから、profile マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの --profile または -p オプションを使用して) プロファイルの名前を指定できます。

• azure_login_app_id マッピングは非運用であり、内部使用のために予約されています。

• auth_type マッピングでは、特に Databricks CLI で予期しない認証の種類が推測された場合に、使用する Azure Databricks 認証の種類を指定します。 「Azure 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 ホイール ファイルを構築するには、このマッピングを whl に設定する必要があります。
• path は、バンドル構成ファイルの場所から Python ホイール ファイルの setup.py ファイルの場所への、省略可能な相対パスです。 path が含まれていない場合、Databricks CLI は、バンドルのルートで Python ホイール ファイルの setup.py ファイルの検索を試行します。
• files は省略可能なマッピングであり、複雑なビルド手順に含める既定以外の場所を指定するために使用できる source 子マッピングが含まれています。 場所は、バンドル構成ファイルの場所からの相対パスとして指定されます。
• build は、デプロイの前にローカルで実行する既定以外のビルド コマンドの省略可能なセットです。 Python ホイール ビルドの場合、Databricks CLI は、ビルドを実行する Python wheel パッケージのローカル インストールを検出できると想定して、各バンドルのデプロイ中に既定でコマンド python setup.py bdist_wheel を実行します。 複数のビルド コマンドを指定するには、各コマンドを二重アンパサンド (&&) 文字で区切ります。

次の構成例では、詩を使用してホイールを構築します。

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

artifactsを使用する完全なサンプル バンドルについては、「Databricks Asset Bundlesを使用した Python ホイール ファイルの開発」を参照してください。

ヒント

Databricks Asset Bundlesでの成果物設定の定義に関する ページの説明に従って、バンドル内の成果物の設定を定義、結合、およびオーバーライドできます。

インクルード

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 マッピングには、バンドルに使われる Azure Databricks リソースに関する情報を指定します。

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

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

次の構成例では、ジョブ リソースを定義します。

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

バンドルでサポートされるリソースの詳細と、一般的な構成と例については、「databricks Asset Bundles リソースの と バンドルの構成例参照してください。

sync

sync マッピングによって、どのファイルをバンドルデプロイメントの一部にするかを設定できます。

Include (包含) と Exclude (除外)

include マッピング内の exclude と sync マッピングは、以下のルールに従って、バンドル展開に含める、またはバンドル展開から除外するファイルまたはフォルダのリストを指定します。

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

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

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

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

.databricks
my_package/dist

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

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

その後、ファイル拡張子が my_package/dist の *.whl フォルダー内のすべてのファイルが含まれます。 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 マッピング宣言とマージされます。 引き続き前の例を使用した場合、たとえば、include レベルでの次の targets マッピングは、最上位レベルの include マッピングの sync マッピングとマージされます。

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

パス

sync マッピングは、ワークスペースに同期するローカル パスを指定する paths マッピングを含めることができます。 paths マッピングを使用することで、バンドル間で共通ファイルを共有でき、バンドル ルートの外部にあるファイルを同期するために使用できます。 （バンドルルートはdatabricks.ymlファイルの場所です。）これには、複数のバンドルをホストする単一のリポジトリがあり、ライブラリ、コードファイル、または設定を共有したい場合に特に便利です。

指定したパスは、paths マッピングが設定されているフォルダーに固定されているファイルとディレクトリに対する相対パスであることが必要です。 1つ以上のパス値が、バンドルルートの祖先までディレクトリを走査する場合、ルートパスは、フォルダ構造が無傷のままであることを保証するために動的に決定されます。 例えば、バンドルルートフォルダが my_bundle という名前の場合、databricks.yml のこの設定では、バンドルルートの1つ上の階層にある common フォルダとバンドルルート自体を同期します。

sync:
  paths:
    - ../common
    - .

このバンドルを配置すると、ワークスペース内の次のフォルダー構造になります。

common/
  common_file.txt
my_bundle/
  databricks.yml
  src/
    ...

ターゲット

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

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

この targets マッピングは省略可能ですが、強くお勧めします。 指定されている場合、最上位レベルのマッピングとしてのみ表示できます。

最上位レベルの workspace、artifacts、および resources マッピングは、targets マッピングで指定されていない場合に使用されますが、競合する設定はターゲット内の設定によりオーバーライドされます。

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

default

バンドル コマンドのターゲットの既定値の指定には、default マッピングを true に設定します。 たとえば、dev という名前のこのターゲットは既定のターゲットです。

targets:
  dev:
    default: true

既定のターゲットが構成されていない場合、または特定のターゲット内でジョブまたはパイプラインを検証、配置、実行する場合は、バンドル コマンドの -t オプションを使用します。

my_job および dev ターゲット内で、prod を検証、配置、実行するには、次のコマンドを実行します。

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

次の例では、2 つのターゲットを宣言します。 最初のターゲットには dev という名前があり、バンドル コマンドにターゲットが指定されていない場合に使用される既定のターゲットです。 2 番目のターゲットは prod 名前があり、このターゲットがバンドル コマンドに指定されている場合にのみ使用されます。

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

モードとプリセット

開発と CI/CD のベスト プラクティスを容易にするために、Databricks アセット バンドルは、運用前ワークフローと運用ワークフローの既定の動作を設定するターゲットのデプロイ モードが用意されています。 一部の動作も構成可能です。 詳細については、「Databricks アセット バンドルのデプロイ モード」を参照してください。

ヒント

バンドルにランIDを設定するには、「run_as」の説明に従って、ターゲットごとに を指定することができます。

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

targets:
  prod:
    mode: production

presets マッピングを使用して、一部の動作のカスタマイズができます。 使用可能なプリセットの一覧は、「カスタム プリセット」を参照してください。 次の例は、すべての運用リソースにプレフィックスを付けてタグ付けするカスタマイズされた運用ターゲットを示します。

targets:
  prod:
    mode: production
    presets:
      name_prefix: "production_"  # prefix all resource names with production_
      tags:
        prod: true

mode と presets の両方が設定されている場合には、プリセットは既定のモード動作をオーバーライドします。 個々のリソースの設定では、プリセットをオーバーライドします。 たとえば、スケジュールが UNPAUSED に設定されていても、trigger_pause_status プリセットが PAUSED に設定されている場合には、スケジュールは一時使用されません。