bundle
命令组
注意
此信息适用于 Databricks CLI 版本 0.218.0 及更高版本。 若要查找你的 Databricks CLI 的版本,请运行 databricks -v
。
使用 Databricks CLI 中的 bundle
命令组,能够以编程方式验证、部署和运行 Azure Databricks 工作流,例如 Azure Databricks 作业、增量实时表管道以及 MLOps Stacks。 请参阅什么是 Databricks 资产捆绑包?。
重要
要安装 Databricks CLI,请参阅《安装或更新 Databricks CLI》。 若要配置 Databricks CLI 的身份验证,请参阅 Databricks CLI 的身份验证。
可以通过将 bundle
命令追加到 databricks bundle
中来运行这些命令。 若要显示 bundle
命令的帮助,请运行 databricks bundle -h
。
从项目模板创建捆绑包
若要使用适用于 Python 的默认 Databricks 资产捆绑包模板创建 Databricks 资产捆绑包,请按如下所示运行 bundle init
命令,然后回答屏幕上的提示:
databricks bundle init
若要使用非默认 Databricks 资产捆绑模板创建 Databricks 资产捆绑包,请如下所示运行 bundle init
命令:
databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"
请参阅:
- Databricks 资产捆绑包模板
- 使用 Databricks 资产捆绑包在 Azure Databricks 上开发作业
- 使用 Databricks 资产捆绑包开发增量实时表管道
- 适用于 MLOps Stacks 的 Databricks 资产捆绑包
显示捆绑包配置架构
若要显示 Databricks 资产捆绑包配置架构,请运行 bundle schema
命令,如下所示:
databricks bundle schema
若要将 Databricks 资产捆绑包配置架构输出为 JSON 文件,请运行 bundle schema
命令并将输出重定向到 JSON 文件。 例如,可以在当前目录中生成名为 bundle_config_schema.json
的文件,如下所示:
databricks bundle schema > bundle_config_schema.json
验证捆绑包
要验证捆绑包配置文件在语法上是否正确,请从捆绑包项目根目录运行 bundle validate
命令,如下所示:
databricks bundle validate
默认情况下,此命令会返回捆绑包标识的摘要:
Name: MyBundle
Target: dev
Workspace:
Host: https://my-host.cloud.databricks.com
User: someone@example.com
Path: /Users/someone@example.com/.bundle/MyBundle/dev
Validation OK!
注意
如果资源属性是在捆绑配置文件中定义的,而在相应对象的架构中找不到这些文件,则 bundle validate
命令会输出警告。
将捆绑包的树同步到工作区
使用 bundle sync
命令,将本地文件系统目录中捆绑包的文件更改单向同步到远程 Azure Databricks 工作区中的目录。
注意
bundle sync
命令无法将远程 Azure Databricks 工作区内的目录中的文件更改同步回到本地文件系统中的目录。
databricks bundle sync
命令的工作原理与 databricks sync
命令相同,且都用于提高工作效率。 若需了解命令用法,请参阅同步命令组。
生成捆绑包配置文件
可以使用 bundle generate
命令为 Databricks 工作区中已存在的作业或管道生成资源配置。 此命令会在捆绑包项目的 resources
文件夹中为作业或管道生成一个 *.yml
文件,还会下载作业或管道配置中引用的任何笔记本。 目前,此命令仅支持包含笔记本任务的作业。
重要
bundle generate
命令为方便自动生成资源配置提供。 但是,当此配置包含在捆绑包中并部署时,它将创建一个新资源,并且不会更新现有资源,除非已对资源使用 bundle deployment bind
。
如下所示运行 bundle generate
命令:
databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]
例如,以下命令在包含下列 YAML 的 resources
捆绑包项目文件夹中生成一个新的 hello_job.yml
文件,并将 simple_notebook.py
下载到 src
项目文件夹。
databricks bundle generate job --existing-job-id 6565621249
# This is the contents of the resulting hello_job.yml file.
resources:
jobs:
6565621249:
name: Hello Job
format: MULTI_TASK
tasks:
- task_key: run_notebook
existing_cluster_id: 0704-xxxxxx-yyyyyyy
notebook_task:
notebook_path: ./src/simple_notebook.py
source: WORKSPACE
run_if: ALL_SUCCESS
max_concurrent_runs: 1
绑定捆绑资源
使用 bundle deployment bind
命令,可以将捆绑包定义的作业和管道链接到 Azure Databricks 工作区中的现有作业和管道,以便由 Databricks 资产捆绑包管理它们。 如果绑定了某个资源,工作区中的现有 Databricks 资源将基于在下一次 bundle deploy
之后绑定的捆绑包所定义的配置进行更新。
提示
最好在运行绑定之前确认捆绑工作区。
databricks bundle deployment bind [resource-key] [resource-id]
例如,以下命令将资源 hello_job
绑定到工作区中的远程对应资源。 该命令会输出差异,并允许拒绝资源绑定,但如果确认,捆绑包中对作业定义的任何更新会在下次部署捆绑包时应用于相应的远程作业。
databricks bundle deployment bind hello_job 6565621249
如果要移除捆绑包中作业或管道与其工作区中远程对应项之间的链接,请使用 bundle deployment unbind
。
databricks bundle deployment unbind [resource-key]
部署捆绑包
若要将捆绑包部署到远程工作区,请从捆绑包项目根目录运行 bundle deploy
命令。 如果未指定命令选项,会使用捆绑包配置文件中声明的默认目标。
databricks bundle deploy
若要将捆绑包部署到特定目标,请将 -t
(或 --target
)选项与捆绑包配置文件中声明的目标名称一起设置。 例如,对于使用名称dev
声明的目标:
databricks bundle deploy -t dev
可将捆绑包部署到多个工作区,例如开发、暂存和生产工作区。 从根本上说,root_path
属性决定了捆绑包的唯一标识,它默认为 ~/.bundle/${bundle.name}/${bundle.target}
。 因此,默认情况下,捆绑包的标识由部署者的标识、捆绑包的名称和捆绑包的目标名称组成。 如果这些属性在不同的捆绑包中相同,则这些捆绑包的部署会互相干扰。
此外,捆绑包部署将跟踪通过其 ID 在目标工作区中创建的资源,作为存储在工作区文件系统中的状态。 资源名称不用于在捆绑包部署和资源实例之间关联,因此:
- 如果捆绑包配置中的资源不存在于目标工作区中,则会创建该资源。
- 如果捆绑包配置中的资源存在于目标工作区中,则会在工作区中更新该资源。
- 如果资源已从捆绑包配置中删除,则会从目标工作区中删除该资源(如果之前已部署)。
- 仅当你更改捆绑包名称、捆绑包目标或工作区时,才能忘记资源与捆绑包的关联。 可以运行
bundle validate
来输出包含这些值的摘要。
运行捆绑包
若要运行特定的作业或管道,请使用 bundle run
命令。 必须指定捆绑包配置文件中声明的作业或管道的资源密钥。 默认情况下,将使用捆绑配置文件中声明的环境。 例如,若要在默认环境中运行作业 hello_job
,请运行以下命令:
databricks bundle run hello_job
若要在用名称 dev
声明的目标的上下文中运行具有密钥 hello_job
的作业:
databricks bundle run -t dev hello_job
如果要执行管道验证运行,请使用 --validate-only
选项,如以下示例所示:
databricks bundle run --validate-only my_pipeline
要传递作业参数,请使用 --params
选项,后跟逗号分隔的键值对,其中键是参数名称。 例如,以下命令将作业 hello_job
的名为 message
的参数设置为 HelloWorld
:
databricks bundle run --params message=HelloWorld hello_job
注意
可以使用作业任务选项将参数传递给作业任务,但建议使用 --params
选项传递作业参数。 如果为未定义作业参数的作业指定了作业参数,或者为已定义作业参数的作业指定了任务参数,则会发生错误。
要取消并重启现有作业运行或管道更新,请使用 --restart
选项:
databricks bundle run --restart hello_job
销毁捆绑包
要删除以前部署的作业、管道和项目,请运行 bundle destroy
命令。 以下命令删除捆绑包配置文件中定义的所有以前部署的作业、管道和项目:
databricks bundle destroy
注意
捆绑包的标识由捆绑包名称、捆绑包目标和工作区组成。 如果更改了其中任何一项,然后尝试在部署之前销毁捆绑包,将发生错误。
默认情况下,系统会提示你是否确认要永久删除以前部署的作业、管道和项目。 若要跳过这些提示并执行自动永久删除,请将 --auto-approve
选项添加到 bundle destroy
命令。