Databricks 資產配套組態
本文說明定義 Databricks 資產套件組合的 Databricks 資產組合組態檔語法。 請參閱 什麼是 Databricks 資產套件組合?
套件組合組態檔必須以 YAML 格式表示,而且至少必須包含最上層 套件組合 對應。 每個套件組合至少必須包含一個名為的套件組合組態檔 databricks.yml
(且只有一個)。 如果有多個配套組態檔,則必須使用include
對應來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.
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>"
# 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.
例子
注意
如需示範套件組合功能和常見套件組合使用案例的組態範例,請參閱 GitHub 中的套件組合組態範例和套件組合範例存放庫。
下列範例套件組合組態會指定名為 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
下列範例會新增具有名稱 prod
的目標,該目標使用不同的遠端工作區 URL 和工作區驗證認證,這些認證會從呼叫端檔案的 .databrickscfg
相符 host
專案與指定的工作區 URL 讀取。 此作業會執行相同的筆記本,但使用不同的遠端叢集搭配指定的叢集標識碼。 請注意,如果您未在對應中明確覆寫對應,則不需要在對應內宣告notebook_task
對應,因為它會回復為使用notebook_task
最上層resources
對應內的prod
對應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
對應,以關聯套件組合的內容和 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
之類的validate
deploy
命令時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 工作區設定。
root_path
此 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}
,其會使用 替代。
artifact_path
此 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) 路徑。
file_path
此 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
對應 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
選項在執行套件組合驗證、部署、執行和終結命令時使用 Databricksazure_client_id
CLI)。 請參閱 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_client_id
和 值建立組態設定檔azure_use_msi
,然後使用對應來指定配置檔的名稱profile
(或使用--profile
或-p
選項在執行套件組合驗證、部署、執行和終結命令時使用 Databricksazure_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 會假設它可以找到 Pythonwheel
套件的本機安裝來執行組建,而且它會在每個套件組合部署期間預設執行 命令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
命令會傳回警告。
下表列出套件組合的支持資源類型,以及其對應承載的文件連結。
資源類型 | 資源對應 |
---|---|
工作 | 作業對應: POST /api/2.1/jobs/create 如需詳細資訊,請參閱 作業工作類型 並 覆寫新的作業叢集設定。 |
管道 | 管線對應: POST /api/2.0/pipelines/create |
實驗 | 實驗對應: POST /api/2.0/mlflow/experiment/create |
機型 | 模型對應: POST /api/2.0/mlflow/registered-models/create |
model_serving_endpoint | 提供端點對應的模型: POST /api/2.0/service-endpoints/create |
registered_model (Unity 目錄) | Unity 目錄模型對應: POST /api/2.1/unity-catalog/models/create |
架構 (Unity 目錄) | Unity 目錄架構對應: POST /api/2.1/unity-catalog/schemas/create |
資源宣告所參考之資料夾和檔案的所有路徑,都相對於指定這些路徑的套件組合組態檔位置。
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
資源 schema
類型可讓您在工作流程和管線中定義數據表和其他資產的 Unity 目錄架構,這些資產會建立為套件組合的一部分。 架構與其他資源類型不同,具有下列限制:
- 架構資源的擁有者一律是部署使用者,而且無法變更。 如果在
run_as
套件組合中指定,架構上的作業將會忽略它。 - 只有對應 Schemas 物件建立 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.
同步
對應 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_id
my_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
、、dashboard
instance_pool
job
metastore
pipeline
query
、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}
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應