Databricks 資產配套組態

發行項
06/27/2024

本文說明定義 Databricks 資產套件組合的 Databricks 資產組合組態檔語法。請參閱什麼是 Databricks 資產套件組合？

套件組合組態檔必須以 YAML 格式表示，而且至少必須包含最上層套件組合對應。每個套件組合至少必須包含一個名為的套件組合組態檔 databricks.yml（且只有一個）。如果有多個套件組合組態檔，則必須由 databricks.yml 檔案參考。

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

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

概觀
範例
對應
自訂變數
替代

概述

本節提供套件組合組態檔架構的可視化表示法。如需詳細資訊，請參閱對應。

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

例子

以下是套件組合組態檔範例。此套件組合會指定本機 hello.py 檔案的遠端部署，該檔案位於與名為之本機套件組合組態檔 databricks.yml相同的目錄中。它會使用具有指定叢集標識符的遠端叢集，以作業形式執行此筆記本。遠端工作區 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

以下是先前的模組化範例，但使用不同遠端工作區 URL 和工作區驗證認證來新增具有程式設計（或邏輯）名稱 prod 的目標，這些認證會從呼叫端檔案的 .databrickscfg 相符 host 專案與指定的工作區 URL 讀取。此作業會執行相同的筆記本，但使用不同的遠端叢集搭配指定的叢集標識碼。請注意，如果您未在對應中明確覆寫對應，則不需要在對應內宣告notebook_task對應，因為它會回復為使用notebook_task最上層resources對應內的prod對應notebook_taskprod。

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 中的套件組合範例存放庫。

映射

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

捆
variables
工作
permissions
artifacts
include
resources
sync
目標

捆

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

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

bundle:
  name: hello-bundle

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

compute_id

對應 bundle 可以有子 compute_id 對應。此對應可讓您指定叢集的標識碼，以做為套件組合組態檔中其他地方所定義之任何和所有叢集的覆寫。此覆寫適用於生產環境之前的僅限開發案例。對應 compute_id 僅適用於其 mode 對應設定為 development的目標。如需對應 compute_id 的詳細資訊，請參閱目標對應。

git

您可以擷取並覆寫與套件組合相關聯的 Git 版本控制詳細數據。這適用於標註已部署的資源。例如，您可能想要在所部署機器學習模型的描述中包含存放庫的原始 URL。

每當您執行 bundle 、或 run之類的validatedeploy命令時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_version 限制套件組合所需 Databricks CLI 版本的對應。這可以防止使用特定版本的 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 對應，以指定要使用的變數設定。請參閱自定義變數。

工作

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

此 workspace 對應可以包含 root_path 對應，以指定要在工作區內用於部署和工作流程執行的非預設根路徑，例如：

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

根據預設，Databricks root_path 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

根據預設，Databricks artifact_path CLI 會使用的預設路徑 ${workspace.root}/artifacts，其會使用替代。

..注意：對應 artifact_path 不支援 Databricks 檔案系統（DBFS）路徑。

此 workspace 對應也可以包含 file_path 對應，以指定要在工作區內用於部署和工作流程執行的非預設檔案路徑，例如：

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

根據預設，Databricks file_path CLI 會使用的預設路徑 ${workspace.root}/files，其會使用替代。

對應 state_path 預設為的預設路徑 ${workspace.root}/state ，並代表工作區中用來儲存部署的 Terraform 狀態資訊的路徑。

此 workspace 對應也可以包含下列選擇性對應，以指定要使用的 Azure Databricks 驗證機制。如果未在此 workspace 對應中指定它們，則必須在對應中 workspace 指定為最上層目標對應中一或多個目標的子系。

重要

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

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

注意

Databricks 建議您在執行套件組合驗證、部署、執行和終結命令時，使用 Databricks CLI 來使用 host 對應（或 --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 （或使用 --profile 或 -p 選項在執行套件組合時驗證、部署、執行和終結命令與 Databricks CLI）。請參閱使用服務主體向 Azure Databricks 進行驗證。

注意

您無法在套件組合組態檔中指定 Azure Databricks OAuth 秘密值。請改為設定本機環境變數 DATABRICKS_CLIENT_SECRET。或者，您可以將值新增 client_secret 至組態配置檔，然後使用對應來指定配置檔的名稱 profile （或使用 --profile 或 -p 選項在執行套件組合時驗證、部署、執行和終結命令與 Databricks CLI）。
針對 Azure CLI 驗證，會使用對應 azure_workspace_resource_id 。或者，您可以在本機環境變數 DATABRICKS_AZURE_RESOURCE_ID中設定此值。或者，您可以使用值建立組態配置檔 azure_workspace_resource_id ，然後使用對應來指定配置檔的名稱 profile （或使用 --profile 或 -p 選項在執行套件組合時驗證、部署、執行和終結命令與 Databricks CLI）。請參閱 Azure CLI 驗證。
針對使用服務主體的 Azure 用戶端密碼驗證，會使用對應 azure_workspace_resource_id、 azure_tenant_id和 azure_client_id 。或者，您可以分別在本機環境變數 DATABRICKS_AZURE_RESOURCE_ID、 ARM_TENANT_ID和 ARM_CLIENT_ID中設定這些值。或者，您可以使用、 azure_tenant_id和值建立組態設定檔azure_workspace_resource_id，然後使用對應來指定配置檔的名稱profile（或使用 --profile 或 -p 選項在執行套件組合驗證、部署、執行和終結命令時使用 Databricks azure_client_id CLI）。請參閱 Microsoft Entra ID 服務主體驗證。

注意

您無法在套件組合元件組態檔中指定 Azure 客戶端密碼值。請改為設定本機環境變數 ARM_CLIENT_SECRET。或者，您可以將值新增 azure_client_secret 至組態配置檔，然後使用對應來指定配置檔的名稱 profile （或使用 --profile 或 -p 選項在執行套件組合時驗證、部署、執行和終結命令與 Databricks CLI）。
針對 Azure 受控識別驗證，會使用對應 azure_use_msi、 azure_client_id和 azure_workspace_resource_id 。或者，您可以分別在本機環境變數 ARM_USE_MSI、 ARM_CLIENT_ID和 DATABRICKS_AZURE_RESOURCE_ID中設定這些值。或者，您可以使用、 azure_client_id和值建立組態設定檔azure_use_msi，然後使用對應來指定配置檔的名稱profile（或使用 --profile 或 -p 選項在執行套件組合驗證、部署、執行和終結命令時使用 Databricks azure_workspace_resource_id CLI）。請參閱 Azure 受控識別驗證。
對應 azure_environment 會指定一組特定 API 端點的 Azure 環境類型（例如 Public、UsGov、China 和 Germany）。預設值是 PUBLIC。或者，您可以在本機環境變數 ARM_ENVIRONMENT中設定此值。或者，您可以將值新增 azure_environment 至組態配置檔，然後使用對應來指定配置檔的名稱 profile （或使用 --profile 或 -p 選項在執行套件組合時驗證、部署、執行和終結命令與 Databricks CLI）。
此 azure_login_app_id 對應為非運作狀態，並保留供內部使用。
對應 auth_type 會指定要使用的 Azure Databricks 驗證類型，特別是在 Databricks CLI 推斷非預期的驗證類型的情況下。請參閱 [ 驗證類型] 欄位。

權限

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

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的範例套件組合，請參閱使用 Databricks 資產套件組合開發 Python 滾輪檔案。

提示

您可以使用 Databricks 資產組合中動態定義成品設定中所述的技術，定義、合併及覆寫套件組合中成品的設定。

包括

數位會 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 會指定套件組合所使用的 Azure Databricks 資源相關信息。

此 resources 對應可以顯示為最上層對應，或者它可以是最上層目標對應中一或多個目標的子系，並且包含零或其中一個支持的資源類型。每個資源類型對應都包含一或多個個別的資源宣告，每個宣告都必須有唯一的名稱。這些個別資源宣告會使用對應物件的建立作業要求承載，以 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/experiment/create
`models`	模型對應： POST /api/2.0/mlflow/registered-models/create
`model_serving_endpoints`	提供端點對應的模型： POST /api/2.0/service-endpoints
`registered_models` （Unity 目錄）	Unity 目錄模型對應： 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 檔案中的任何檔案和路徑 Glob 清單，對應 include 可以包含相對於套件組合根目錄的檔案 Glob、路徑 glob 或兩者的清單，明確包含。
根據套件組合根目錄中 .gitignore 檔案中的任何檔案和路徑 Glob 清單，加上對應中的 include 檔案和路徑 Glob 清單，對應 exclude 可以包含檔案 Glob、路徑 glob 或兩者的清單，相對於套件組合的根目錄，明確排除。

指定資料夾和檔案的所有路徑都與指定這些路徑的套件組合組態檔位置相對。

和 exclude 檔案和路徑模式的語法include遵循標準.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

然後，除了名為delete-me.whl的檔案之外，資料夾中所有my_package/dist擴展名為的*.whl檔案都包含在內。資料夾中的任何其他檔案 my_package/dist 也不包含。

數位也可以 sync 在特定目標的對應中 targets 宣告。目標中宣告的任何 sync 陣列會與任何最上層 sync 陣列宣告合併。例如，繼續上述範例，層級的targets下列include對應會與include最上層sync陣列中的對應合併：

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 會指定要在其中執行 Azure Databricks 工作流程的一或多個內容。每個目標都是成品、Azure Databricks 工作區設定和 Azure Databricks 作業或管線詳細數據的唯一集合。

此 targets 對應是選擇性的，但強烈建議使用。如果指定，它只能顯示為最上層對應。 targets如果未指定對應，則一律會使用最上層工作區、成品和資源對應中的設定。

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

如果目標對應未指定 workspace、 artifacts或 resources 子對應，則該目標會使用最上層 workspace、 artifacts和 resources 對應中的設定。

如果目標對應指定workspace、artifacts、或對應，而且最上層workspace、 artifacts或 resources resources 對應也存在，則目標內的設定會覆寫任何衝突的設定。

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

若要指定目標為預設目標，除非另有指定，否則請新增 default 對應，並將設定為 true。例如，此名為 dev 的目標是預設目標：

targets:
  dev:
    default: true

若要指定目標視為開發目標，請新增 mode 對應，並將設定為 development。若要指定將目標視為生產目標，請新增 mode 對應，並將設定為 production。例如，這個名為 prod 的目標會被視為生產目標：

targets:
  prod:
    mode: production

mode指定會為生產前和生產工作流程提供對應的預設行為集合。如需詳細資訊，請參閱 Databricks Asset Bundle 部署模式。此外，您可以為每個目標指定run_as，如指定 Databricks 資產組合工作流程的執行身分識別中所述。

下列範例會宣告兩個目標。第一個目標具有的程式設計（或邏輯）名稱 dev ，且是預設目標。第二個目標具有的程序設計（或邏輯）名稱 prod ，而不是預設目標。第二個目標會使用名為 PROD 的 Azure 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>

自訂變數

您可以使用自定義變數，讓您的套件組合元件組合組態檔更模組化且可重複使用。例如，您可以宣告代表現有叢集標識碼的變數，然後想要針對多個目標內的各種工作流程執行，將該變數的值變更為不同的叢集標識符，而不需變更套件組合組態檔的原始程序代碼。

自定義變數會在對應的套件組合組態檔中 variables 宣告。針對每個變數，使用下列格式設定選擇性描述、預設值、類型或查閱以擷取標識碼值：

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

注意

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

例如，若要宣告名為且預設值為的1234-567890-abcde123變數my_cluster_id，以及名為 my_notebook_path 的變數，其預設值./hello.py為：

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_notebook_path的my_cluster_id變數：

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 變數的值，請使用下列其中一種方法提供變數的新暫存值：

提供變數的值做為命令的一 bundle 部分，例如 validate、 deploy或 run。若要這樣做，請使用選項 --var="<key>=<value>"，其中 <key> 是變數的名稱，而 <value> 是變數的值。例如，在命令中 bundle validate ，若要將的值 1234-567890-abcde123 提供給名為 my_cluster_id的變數，並將的值 ./hello.py 提供給名為 my_notebook_path的變數，請執行：
```
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_開頭。若要設定環境變數，請參閱作業系統的檔。例如，若要將的值1234-567890-abcde123提供給名為my_cluster_id的變數，並將的值./hello.py提供給名為my_notebook_path的變數，請在呼叫 bundle 、 deploy或 run等validate命令之前執行下列命令：

針對 Linux 和 macOS：
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
若為 Windows：
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
或者，提供變數的值做為、deploy、或 run等validate命令的一bundle部分，例如 Linux 和 macOS：
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
或適用於 Windows：
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```

在您的套件組合組態檔中提供變數的值。若要這樣做，請使用 variables 對應內的 targets 對應，請遵循下列格式：

variables:
  <variable-name>: <value>

例如，為名為 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_idmy_notebook_path的值，並在找到每個相符變數的值時停止，略過該變數的任何其他位置：

在任何 --var 指定為命令一部分的選項內 bundle 。
在任何以開頭 BUNDLE_VAR_的環境變數集合內。
在任何 variables 對應中， targets 在套件組合組態檔內的對應之間。
該變數定義的任何 default 值，在套件組合組態檔內的最上層 variables 對應中。

定義複雜變數

若要為套件組合定義具有複雜類型的自訂變數，請在套件組合元件中設定 type 為 complex 。

注意

設定complex的唯一type有效值為。此外，如果 type 設定為 complex ，且 default 針對變數定義的是單一值，則套件組合驗證會失敗。

在下列範例中，叢集設定定義於名為 my_cluster的自定義複雜變數內：

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

擷取對象的標識碼值

alert針對、cluster_policy、cluster、、dashboardinstance_pooljobmetastorepipelinequery、service_principal、和 warehouse 物件類型，您可以為自定義變數定義，lookup以使用此格式擷取具名物件的識別碼：

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

如果為變數定義查閱，則會使用具有指定名稱的物件標識碼做為變數的值。這可確保對象的正確解析標識符一律用於變數。

注意

如果具有指定名稱的物件不存在，或有多個具有指定名稱的物件，就會發生錯誤。

例如，在下列組態中，${var.my_cluster_id}將會由12.2共用叢集的標識碼取代。

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",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

在上述範例中，您可以使用替代 ${workspace.current_user.userName}來參考套件組合組態檔中的值someone@example.com。

同樣地，下列替代專案：

/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}

共用方式為