Databricks Asset Bundle 組態

本文章說明定義 Databricks Asset Bundle 之 Databricks Asset Bundle 組態檔的語法。 請參閱什麼是 Databricks Asset Bundle？

套件組合設定檔必須以 YAML 格式表示，而且至少必須包含最上層套件組合對應。 每個套件組合都必須至少包含一個名為 databricks.yml 的套件組合設定檔 (且只有一個)。 如果有多個套件組合設定檔，這些設定檔必須是使用 include 對應參考的 databricks.yml 檔案。

如需 YAML 的詳細資訊，請參閱官方 YAML 規格和教學課程。

若要建立和使用套件組合設定檔，請參閱 Databricks Asset Bundle 開發。

概觀

本章節提供套件組合設定檔結構描述的視覺化表示法。 如需詳細資料，請參閱對應。

# 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:
  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.

範例

注意

如需示範套件組合功能和常見套件組合使用案例的設定範例，請參閱套件組合設定範例和 GitHub 中的套件組合組態範例存放庫。

下列範例套件組合設定會指定名為 hello.py 的本機檔案；該檔案位於與此名為 databricks.yml 的本機套件組合設定檔相同的目錄中。 它會使用具有指定叢集 ID 的遠端叢集來執行此筆記本作為作業。 遠端工作區 URL 和工作區驗證認證是從呼叫者名為 DEFAULT 的本機組態設定檔讀取。

Databricks 建議您盡可能使用 host 對應來取代 default 對應，因為這樣會讓您的套件組合設定檔更具可攜性。 設定 host 對應會指示 Databricks CLI 在 .databrickscfg 檔案中尋找相符的設定檔，然後使用該設定檔的欄位來判斷要使用的 Databricks 驗證類型。 如果您的 .databrickscfg 檔案中有多個具有相符 host 欄位的設定檔，就必須使用 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

下列範例會新增名稱為 prod 的目標；該目標使用不同的遠端工作區 URL 和工作區驗證認證，這些認證會從呼叫者 .databrickscfg 檔案的相符 host 項目，透過指定的工作區 URL 讀取。 此作業會執行相同的筆記本，但是會使用具有指定叢集 ID 的不同遠端叢集。 請注意，如果未在 prod 對應中明確覆寫 notebook_task 對應，就不需要在 prod 對應內宣告 notebook_task 對應，因為它會回復為使用最上層 resources 對應內的 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

對應

下列章節會依最上層對應來描述套件組合設定檔語法。

• bundle
• variables
• workspace
• 權限
• artifacts
• include
• resources
• sync
• targets

bundle

套件組合設定檔必須只包含一個最上層 bundle 對應，以關聯套件組合的內容和 Azure Databricks 工作區設定。

這個 bundle 對應必須包含指定套件組合之程式設計 (或邏輯) 名稱的 name 對應。 下列範例會宣告具有程式設計 (或邏輯) 名稱 hello-bundle 的套件組合。

bundle:
  name: hello-bundle

bundle 對應也可以是最上層 targets 對應中一或多個目標的子系 。 每個子系 bundle 對應都會在目標層級指定任何非預設覆寫。 但是，無法在目標層級覆寫最上層 bundle 對應的 name 值。

cluster_id

bundle 對應可以有子系 cluster_id 對應。 此對應可讓您指定叢集的 ID，以作為套件組合設定檔中其他地方定義的叢集覆寫。 如需如何擷取叢集 ID 的資訊，請參閱叢集 URL 和 ID。

cluster_id 覆寫適用於僅限開發的案例，而且只支援其 mode 對應設定為 development 的目標。 如需 target 對應的詳細資訊，請參閱 targets。

compute_id

注意

此設定已被取代。 請改用 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，此值就會與您取得的值相同。 您可以使用替代將此值與套件組合設定檔一起參考，例如 ${bundle.git.origin_url}。
• bundle.git.branch，表示存放庫中的最新分支。 如果您從複製的存放庫執行命令 git branch --show-current，此值就會與您取得的值相同。 您可以使用替代將此值與套件組合設定檔一起參考，例如 ${bundle.git.branch}。
• bundle.git.commit，表示存放庫中的 HEAD 認可 。 如果您從複製的存放庫執行命令 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>

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

套件組合設定檔可以包含定義自訂變數所在的一個最上層 variables 對應。 針對每個變數，請設定選擇性描述、預設值、自訂變數是否為複雜類型，或是查詢以使用下列格式擷取 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>

注意

除非 type 設定為 complex，否則變數會假設為類型 string。 請參閱定義複雜變數。

若要參考套件組合組態內的自訂變數，請使用替代 ${var.<variable_name>}。

如需自訂變數變數和替代的詳細資訊，請參閱 Databricks Asset Bundle 中的替代和變數。

workspace

套件組合設定檔只能包含一個最上層 workspace 對應，以指定要使用的任何非預設 Azure Databricks 工作區設定。

重要

有效的 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 的預設路徑，而該路徑會使用替代。

注意

對應 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 對應中指定為最上層 targets 對應中一或多個目標的子系。

重要

您必須針對 Azure Databricks 驗證的下列 workspace 對應，將值硬式編碼。 例如，您無法使用 ${var.*} 語法來指定這些對應值的自訂變數。

• profile 對應 (或透過 Databricks CLI 執行套件組合驗證、部署、執行和終結命令時的 --profile 或 -p) 會指定要搭配此工作區使用的組態設定檔名稱，以進行 Azure Databricks 驗證。 此組態設定檔會對應至您在設定 Databricks CLI 時建立的設定檔。

  注意

  Databricks 建議您使用 host 對應 (或在透過 Databricks CLI 執行套件組合驗證、部署、執行和終結命令時使用 --profile 或 -p 選項)，而不是 profile 對應，因為這樣會讓您的套件組合設定檔更具可攜性。 設定 host 對應會指示 Databricks CLI 在 .databrickscfg 檔案中尋找相符的設定檔，然後使用該設定檔的欄位來判斷要使用的 Databricks 驗證類型。 如果您的 .databrickscfg 檔案中有多個具有相符 host 欄位的設定檔，就必須使用 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 的存取進行驗證。

  注意

  您無法在套件組合設定檔中指定 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 服務主體驗證。

  注意

  您無法在套件組合設定檔中指定 Azure 用戶端密碼值。 請改為設定本機環境變數 ARM_CLIENT_SECRET。 或者，您可以新增 azure_client_secret 值到組態設定檔，然後使用 profile 對應來指定設定檔名稱 (或在透過 Databricks CLI 執行套件組合驗證、部署、執行和終結命令時使用 --profile 或 -p 選項)。

• 對於 Azure 受控識別驗證，會使用對應 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 受控識別驗證。

• azure_environment 對應會為一組特定 API 端點指定 Azure 環境類型 (例如 Public、UsGov、China 和 Germany)。 預設值是 PUBLIC。 或者，您可以在本機環境變數 ARM_ENVIRONMENT 中設定此值。 或者，您可以新增 azure_environment 值到組態設定檔，然後使用 profile 對應來指定設定檔名稱 (或在透過 Databricks CLI 執行套件組合驗證、部署、執行和終結命令時使用 --profile 或 -p 選項)。

• azure_login_app_id 對應無法運作，且保留供內部使用。

• auth_type 對應會指定要使用的 Azure Databricks 驗證類型，特別是在 Databricks CLI 推斷非預期之驗證類型的情況下。 請參閱對 Azure Databricks 資源的存取進行驗證。

權限

最上層 permissions 對應會指定一或多個權限等級，以套用至套件組合中定義的所有資源。 如果您想要將權限套用至特定資源，請參閱為特定資源定義權限。

允許的最上層權限等級為 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

最上層 artifacts 對應會指定一或多個成品，這些成品會在套件組合部署期間自動建置，且稍後可在套件組合執行中使用。 每個子系成品都支援下列對應：

• 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。 若要指定多個建置命令，請使用雙 & 符號 (&&) 字元分隔每個命令。

如需詳細資訊，包括使用 artifacts 的範例套件組合，請參閱使用 Databricks Asset Bundle 開發 Python Wheel 檔案。

提示

您可以使用在 Databricks Asset Bundle 中動態定義成品設定中所述的技巧來定義、合併和覆寫套件組合中成品的設定。

include

include 陣列會指定路徑 Glob 的清單，其中包含要包括在套件組合中的設定檔。 這些路徑 Glob 是相對於指定路徑 Glob 之套件組合設定檔的位置。

Databricks CLI 預設不會在套件組合中包括任何設定檔。 您必須使用 include 陣列指定要包括在套件組合內的任何和所有設定檔，而不是 databricks.yml 檔案本身。

此 include 陣列只能顯示為最上層對應。

下列範例組態包括三個設定檔。 這些檔案位於與套件組合設定檔相同的資料夾中：

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

下列範例組態包括檔案名稱開頭為 bundle 且結尾為 .yml 的所有檔案。 這些檔案位於與套件組合設定檔相同的資料夾中：

include:
  - "bundle*.yml"

resources

resources 對應會指定套件組合所使用的 Azure Databricks 資源相關資訊。

此 resources 對應可以顯示為最上層對應，也可以是最上層 targets 對應中一或多個目標的子系，並且包含零或其中一個支援的資源類型。 每個資源類型對應都包括一或多個個別的資源宣告，且每個宣告都必須有唯一的名稱。 這些個別資源宣告會使用對應物件的建立作業要求承載 (以 YAML 表示)，以定義資源。 資源支援的屬性是對應物件的支援欄位。

建立作業要求承載記錄在 Databricks REST API 參考中，而 databricks bundle schema 命令會輸出所有支援的物件結構描述。 此外，如果套件組合設定檔中找到未知的資源屬性，databricks bundle validate 命令會傳回警告。

下表列出套件組合的支援資源類型，以及其對應承載的文件連結。

資源類型	資源對應
簇	叢集對應： POST /api/2.1/clusters/create
擋泥板	儀錶板對應： POST /api/2.0/preview/sql/dashboards
實驗	實驗對應：POST /api/2.0/mlflow/experiment/create
job	作業對應：POST /api/2.1/jobs/create 如需其他資訊，請參閱作業工作類型和覆寫新的作業叢集設定。
管線	管線對應： POST /api/2.0/pipelines
機型	模型對應：POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint	提供端點對應的模型： POST /api/2.0/service-endpoints
registered_model (Unity 目錄)	Unity 目錄模型對應： POST /api/2.1/unity-catalog/models
schema (Unity 目錄)	Unity 目錄架構對應： POST /api/2.1/unity-catalog/schemas

資源宣告所參考之資料夾和檔案的所有路徑，都相對於指定這些路徑的套件組合設定檔位置。

叢集

叢集資源可讓您建立所有用途的叢集。 下列範例會建立名為 my_cluster 的叢集，並將該叢集設定為用來在 my_job 中執行筆記本的叢集：

bundle:
  name: clusters

resources:
  clusters:
    my_cluster:
      num_workers: 2
      node_type_id: "i3.xlarge"
      autoscale:
        min_workers: 2
        max_workers: 7
      spark_version: "13.3.x-scala2.12"
      spark_conf:
        "spark.executor.memory": "2g"

  jobs:
    my_job:
      tasks:
        - task_key: test_task
          existing_cluster_id: ${resources.clusters.my_cluster.id}
          notebook_task:
            notebook_path: "./src/my_notebook.py"

儀表板

儀錶板資源可讓您管理套件組合中的 AI/BI 儀錶板。 如需 AI/BI 儀錶板的相關信息，請參閱 儀錶板。

下列範例包含並將範例 NYC計程車車程分析 儀錶板部署到 Databricks 工作區。

resources:
  dashboards:
    nyc_taxi_trip_analysis:
      display_name: "NYC Taxi Trip Analysis"
      file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
      warehouse_id: ${var.warehouse_id}

如果您使用 UI 來修改儀錶板，除非您使用 明確更新 bundle generate它，否則透過 UI 所做的修改不會套用至本機套件組合中的儀錶板 JSON 檔案。 您可以使用 --watch 選項持續輪詢和擷取儀錶板的變更。 請參閱 產生套件組合組態檔。

此外，如果您嘗試部署套件組合，其中包含與遠端工作區中不同的儀錶板 JSON 檔案，則會發生錯誤。 若要使用本機工作區強制部署並覆寫遠端工作區中的儀錶板，請使用 --force 選項。 請參閱 部署套件組合。

job

下列範例會宣告具有 hello-job 資源金鑰的作業：

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

管線

下列範例會宣告具有 hello-pipeline 資源金鑰的管線：

resources:
  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

schema

架構資源類型可讓您為工作流程和管線中建立做為套件組合一部分的數據表和其他資產定義 Unity 目錄架構。 結構描述與其他資源類型不同，具有下列限制：

• 結構描述資源的擁有者一律是部署使用者，而且無法變更。 如果在套件組合中指定 run_as，結構描述上的作業將會略過它。
• 只有對應結構描述物件建立 API 支援的欄位可用於 schema 資源。 例如，enable_predictive_optimization 不受支援，因為它只能在更新 API 上使用。

下列範例會宣告具有資源金鑰 my_pipeline 的管線，該管線會建立具有金鑰 my_schema 作為目標的 Unity 目錄結構描述：

resources:
  pipelines:
    my_pipeline:
      name: test-pipeline-{{.unique_id}}
      libraries:
        - notebook:
            path: ./nb.sql
      development: true
      catalog: main
      target: ${resources.schemas.my_schema.id}

  schemas:
    my_schema:
      name: test-schema-{{.unique_id}}
      catalog_name: main
      comment: This schema was created by DABs.

Databricks Asset Bundles 不支援最上層授與對應，因此如果您想要設定結構描述的授與，請在 schemas 對應中定義結構描述的授與：

schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - CAN_MANAGE
        - principal: my_team
          privileges:
            - CAN_READ
      catalog_name: main
      comment: "my schema with grants"

sync

sync 對應可讓您設定哪些檔案是套件組合部署的一部分。

include 和 exclude

sync 對應內的 include 和 exclude 對應會根據下列規則，指定要在套件組合部署中包括或排除的檔案或資料夾清單：

• 根據套件組合根目錄中 .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 對應宣告合併。 例如，續上述範例，targets 層級上的下列 include 對應會與最上層 sync 對應中的 include 對應合併：

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

paths

sync 對應可以包含指定同步至工作區之本機路徑的 paths 對應。 paths 對應可讓您在套件組合間共用常用檔案，而且可用來同步位於套件組合根目錄外部的檔案。 (套件組合根目錄是 databricks.yml 檔案的位置。) 當您擁有託管多個套件組合的單一存放庫，且想要共用程式庫、程式碼檔案或組態時，此方法特別實用。

指定的路徑必須相對於設定 paths 對應所在之資料夾錨定的檔案和目錄。 如果一或多個路徑值將目錄向上周遊至套件組合根目錄的上階，則會動態決定根路徑，以確保資料夾結構保持不變。 例如，如果套件組合根資料夾命名為 my_bundle，則 databricks.yml 中的此組態會同步位於套件組合根目錄上方一層的 common 資料夾，以及套件組合根本身：

sync:
  paths:
    - ../common
    - .

此套件組合的部署會尺\產生工作區中的下列資料夾結構：

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

targets

targets 對應會指定要在其中執行 Azure Databricks 工作流程的一或多個內容。 每個 target 都是成品、Azure Databricks 工作區設定和 Azure Databricks 作業或管線詳細資料的唯一集合。

targets 對應是由一或多個目標對應所組成，每個對應都必須有唯一的程式設計 (或邏輯) 名稱。

這個 targets 對應為選用，但強烈建議使用。 如果指定，它只能顯示為最上層對應。

如果未在 targets 對應中指定這些設定，則會使用最上層 workspace、artifacts 和 resources 對應中的設定，但任何衝突的設定都會由目標內的設定覆寫。

目標也可以覆寫任何最上層 variables 的值。

預設值

若要指定套件組合命令的目標預設，請將 default 對應設定為 true。 例如，這個名為 dev 的目標是預設目標：

targets:
  dev:
    default: true

如果未設定預設目標，或您想要驗證、部署及執行特定目標內的作業或管線，請使用套件組合命令的 -t 選項。

下列命令會在 dev 和 prod 目標內驗證、部署和執行 my_job：

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

下列範例會宣告兩個目標。 第一個目標具有名稱 dev，而且是在未針對套件組合命令指定目標時使用的預設目標。 第二個目標具有名稱 prod，而且只會在已針對套件組合命令指定此目標時使用。

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

mode 和 presets

為了方便輕鬆開發和 CI/CD 最佳做法，Databricks Asset Bundle 會針對設定生產前和生產工作流程預設行為的目標，提供部署模式。 某些行為也可以設定。 如需詳細資料，請參閱 Databricks Asset Bundle 部署模式。

提示

若要為套件組合設定執行身分識別，您可以為每個目標指定 run_as，如為 Databricks Asset Bundle 工作流程指定執行身分識別中所述。

若要指定將某個目標視為開發目標，請將 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，則會將排程取消暫停。