Databricks Asset Bundle 配置

本文描述 Databricks 資產組合組態檔的語法，它們用來定義 Databricks 資產組合。 請參閱什麼是 Databricks Asset Bundles？。

若要建立和使用套件組合，請參閱 開發 Databricks 資產套件組合。

databricks.yml

套件組合必須包含一個（且只有一個）名為 databricks.yml 的設定檔，位於套件組合專案資料夾的根目錄。 databricks.yml 是定義套件組合的主要組態檔，但它可以在對應中 include 參考其他組態檔，例如資源組態檔。 套件組合組態是以 YAML 表示。 如需 YAML 的詳細資訊，請參閱官方 YAML 規格。

最簡單的 databricks.yml 定義套件組合名稱，其位於所需的最上層對應 套件組合內，以及目標部署。

bundle:
  name: my_bundle

targets:
  dev:
    default: true

如需所有最上層對應的詳細資訊，請參閱 對應。

小提示

Databricks 資產套件組合的 Python 支援可讓您在 Python 中定義資源。 請參閱 Python 中的套件組合組態。

規格

下列 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
  deployment: Map
  git:
    origin_url: string
    branch: string

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

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

# 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 default artifact settings if not otherwise overridden in
# the targets top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    dynamic_version: boolean
    executable: string
    files:
      - source: string
    path: string
    type: string

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

# These are the default workspace settings if not otherwise overridden in
# the 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. 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
  resource_path: string
  root_path: string
  state_path: string

# These are the permissions to apply to resources 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 resource settings if not otherwise overridden in
# the targets top-level mapping.
resources:
  apps:
    <unique-app-name>:
      # See the REST API create request payload reference for apps.
  clusters:
    <unique-cluster-name>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <unique-dashboard-name>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <unique-experiment-name>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <unique-job-name>:
      # See REST API create request payload reference for jobs.
  model_serving_endpoint:
    <unique-model-serving-endpoint-name>:
    # See the model serving endpoint request payload reference.
  models:
    <unique-model-name>:
      # See the REST API create request payload reference for models (legacy).
  pipelines:
    <unique-pipeline-name>:
      # See the REST API create request payload reference for :re[LDP] (pipelines).
  quality_monitors:
    <unique-quality-monitor-name>:
    # See the quality monitor request payload reference.
  registered_models:
    <unique-registered-model-name>:
    # See the registered model request payload reference.
  schemas:
    <unique-schema-name>:
      # See the Unity Catalog schema request payload reference.
  secret_scopes:
    <unique-secret-scope-name>:
      # See the secret scope request payload reference.
  volumes:
    <unique-volume-name>:
    # See the Unity Catalog volume request payload reference.

# 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.
    default: boolean
    git: Map
    mode: string
    permissions:
      # See the preceding "permissions" syntax.
    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讀取的。

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 的目標，該目標使用不同的遠端工作區 URL 和工作區驗證憑證，這些憑證會從呼叫者檔案中符合指定工作區 URL 的 .databrickscfg 項目的 host 條目中讀取。 此作業會執行相同的筆記本，但是會使用具有指定叢集 ID 的不同遠端叢集。

備註

Databricks 建議您盡可能使用 host 對應來取代 default 對應，因為這樣會讓您的套件組合設定檔更具可攜性。 指定host對應會指示 Databricks CLI 在.databrickscfg檔案中尋找相符的配置檔，然後使用該配置檔的字段來決定使用哪種類型的 Databricks 驗證。 如果有多個具有相符 host 欄位的設定檔存在，則必須使用 --profile 套件組合命令上的 選項來指定要使用的設定檔。

請注意，如果未在 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 驗證、部署和執行此作業。 如需套件組合生命週期的詳細資訊，請參閱 開發 Databricks 資產套件組合。

# 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:
  - '*.yml'

# hello-job.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

# 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

對應

下列各節說明套件組合組態最上層對應。 如需組態參考，請參閱 組態參考。

• 套件
• run_as
• 包括
• 同步
• 文物
• 變數
• 工作區
• 權限
• 資源
• 目標

組合

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

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

bundle:
  name: hello-bundle

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

群集識別碼

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

cluster_id 覆寫僅用於開發設計的情境，且僅支援那些將其 mode 映射設為 development的目標。 如需更多關於target 對應的資訊，請參閱 目標。

運算識別碼

備註

此設定已被取代。 請改用 cluster_id 。

bundle 對應可以有子系 compute_id 對應。 此對應可讓您指定叢集的 ID，以覆寫套件組態檔中其他地方定義的叢集。

git

您可以擷取並覆寫與套件組合相關聯的 Git 版本控制詳細數據，這對於傳播稍後可用來識別資源的部署元數據很有用。 例如，您可以追蹤 CI/CD 所部署作業的存放庫來源。

每當您執行類似 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}。

若要擷取或覆寫 Git 設定，您的套件組合必須位於與 Git 存放庫相關聯的目錄中，例如透過執行 git clone 命令初始化的本機目錄。 如果目錄未與 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_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

run_as

使用 run_as 設定來指定 user_name 或 service_principal_name 以執行套件組合。 它可讓您將用來部署套件組合作業或管線的身分識別與用來執行作業或管線的身分識別分開。

請參閱 為 Databricks 資產套件工作流程指定作業識別。

包括

include 陣列會指定包含組態檔的路徑通配符清單，這些檔案將納入套件組合中。 這些路徑通配符是相對於指定這些路徑通配符的套件組合設定檔的位置。

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

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

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

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

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

include:
  - 'bundle*.yml'

同步

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

包含和排除

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 對應的資料夾中錨定的檔案和目錄。 如果一或多個路徑值將目錄周游至套件組合根目錄的上階，則會動態決定根路徑，以確保資料夾結構保持不變。 例如，如果套件組合根資料夾命名為 my_bundle，則 databricks.yml 中的此組態會同步位於套件組合根目錄上方一層的 common 資料夾，以及套件組合根本身：

sync:
  paths:
    - ../common
    - .

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

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

文物

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

• Python 轉輪組建需要 type。 若要在部署之前建置 Python 轉輪檔案，請將此值設定為 whl。 若要建置其他成品，不需要指定此設定。
• path 是選擇性路徑。 路徑相對於套件組合組態檔的位置。 針對 Python 轉輪組建，它是 Python 轉輪檔案 setup.py 的路徑。 如果不包括 path，Databricks CLI 會嘗試在套件根目錄中尋找 Python 輪子檔案的 setup.py。
• files 是選擇性的對應，其中包含子 source 對應，您可以使用此對應來指定建置成品。 路徑相對於套件組合組態檔的位置。
• build 是一組選擇性的非預設建置命令，您想要在部署之前在本機執行。 對於 Python Wheel 組建，Databricks CLI 會假設它可以找到 Python wheel 套件的本機安裝來執行組建，而且它預設會在每個套件組合部署期間執行命令 python setup.py bdist_wheel。 若要指定多個建置命令，請使用雙 & 符號 (&&) 字元分隔每個命令。
• dynamic_version 可讓套件組合根據滾輪檔案的時間戳來更新轉輪版本。 然後可以部署新代碼，而不需要更新setup.py或pyproject.toml中的版本。 此設定僅在 type 設定為 whl 時有效。

下列範例組態會使用詩歌來建置滾輪。 如需用來 artifacts 建置轉輪的完整範例套件組合，請參閱 使用 Databricks 資產套件組合建置 Python 轉輪檔案。

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

如需建置 JAR 並將其上傳至 Unity Catalog 的範例組態，請參閱 將 JAR 檔案上傳至 Unity Catalog 的範例配置。

小提示

您可以定義、合併及覆寫套件組合中成品的設定，如 在 Databricks 資產組合中定義成品設定中所述。

變數

這個捆包設定檔可以包含一個頂層 variables 對應項，其中定義了自訂變數。 針對每個變數，請設定選用描述、預設值，並決定自訂變數是否為複雜類型，或是需要查閱取得標識元值，請使用下列格式：

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>

備註

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

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

如需自定義變數和替代的詳細資訊，請參閱 Databricks 資產組合中的替代和變數。

工作空間

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

重要

Valid 的 Databricks 工作區路徑可以由 /Workspace 開頭，對於成品，/Volumes 也是可支援的。 自訂工作區路徑會自動加上 /Workspace，因此如果您在自訂路徑中使用任何工作區路徑替代，例如 ${workspace.file_path}，則不需要在路徑前面加上 /Workspace 。

根目錄路徑

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

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

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

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

備註

映射 artifact_path 不支援 Databricks 檔案系統（DBFS）路徑。

檔案路徑

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

workspace:
  file_path: /Workspace/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.*}。

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

  備註

  Databricks 建議您使用 host 對應 (或在透過 Databricks CLI 執行套件組合驗證、部署、執行和終結命令時使用 --profile 或 -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 執行 bundle 的驗證、部署、執行和終結命令時，使用 --profile 或 -p 選項。 請參閱 使用 OAuth 授權能無人值守存取 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 映射來指定配置檔的名稱，或者在使用 Databricks CLI 執行 bundle 的驗證、部署、執行和終結命令時，使用 --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 執行 bundle validate, deploy, run, 和 destroy 命令時，使用 --profile 或 -p 選項）。 請參閱 MS Entra 服務主體驗證。

  備註

  您無法在套件組合設定檔中指定 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_use_msi、azure_client_id和azure_workspace_resource_id值建立配置檔，然後使用profile對應來指定配置檔的名稱（或在使用 Databricks CLI 執行 bundle validate, deploy, run, 和 destroy 命令時，使用 --profile 或 -p 選項）。 請參閱 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 推斷非預期的驗證類型的情況下。 請參閱 授權存取 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

資源

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

此 resources 對應可以顯示為最上層對應，或者它可以是最上層目標對應中一或多個 目標的 子系，並且包含零或其中一個 支持的資源類型。 每個資源類型對應都包括一或多個個別的資源宣告，且每個宣告都必須有唯一的名稱。 這些個別資源宣告會使用對應物件的建立作業要求承載，以 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 資產組合資源和套件組合組態範例。

目標

targets 映射指定用於執行 Azure Databricks 工作流程的一個或多個環境。 每個 目標 都是工件、Azure Databricks 工作區設置和 Azure Databricks 作業或管線詳細資訊的獨特集合。

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

這個 targets 對應是可選擇的，但強烈建議使用。 如果有指定，它只能作為最上層映射出現。

如果在對應中未指定這些設定，則會使用最上層工作區、成品和targets的對應設定，但目標中的設定會覆蓋任何衝突的設定。

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

預設

若要指定套件組合命令的目標預設值，請將 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

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

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

模式和預設值

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

小提示

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

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