在声明性自动化捆绑包中配置作业参数

捆绑变量和作业参数在声明性自动化捆绑包中协同工作，以允许在运行时替代特定于环境的默认值。捆绑变量在配置中定义，并在部署期间解析。作业参数在作业运行时解析，因此可以在不重新部署的情况下重写默认值。

绑定变量或作业参数

根据值必须更改时选择是使用变量还是作业参数：

如果值更改...	使用	Example
每个环境（开发、测试、生产）	捆绑变量	群集大小，仓库 ID
每次任务执行	作业参数	处理日期，源表
每个任务，当不存在作业参数时	任务 `base_parameters`	特定于任务的文件路径

使用变量设置作业参数默认值

Databricks 建议使用捆绑变量作为作业参数的默认值。这为你提供了可在运行时重写的环境特定的默认值。

在以下示例中，参数 catalog 默认 biz_dev 为开发部署。默认为生产部署使用 biz_prod。

# databricks.yml
variables:
  default_catalog:
    description: Environment-specific catalog
    default: dev_catalog

targets:
  dev:
    variables:
      default_catalog: biz_dev
  prod:
    variables:
      default_catalog: biz_prod

resources:
  jobs:
    etl_pipeline:
      name: etl_pipeline
      parameters:
        - name: catalog
          default: ${var.default_catalog}
        - name: processing_date
          default: '{{job.start_time.iso_date}}'
        - name: mode
          default: incremental
      tasks:
        - task_key: process_data
          notebook_task:
            notebook_path: ./notebooks/process.py

局限性

捆绑验证不允许同一作业中的作业级别 parameters 和任务级别 base_parameters 。此限制来自 API。如果添加作业级 parameters 块，则也会将所有任务级别移动到作业级别 base_parameters 。

resources:
  jobs:
    my_job:
      parameters:
        - name: catalog
          default: dev
        - name: schema
          default: default
      tasks:
        - task_key: task1
          notebook_task:
            notebook_path: ./notebook.py

如果需要特定于任务的参数且没有作业级 parameters 块，请对任务使用 base_parameters 。添加任何作业级参数后，将所有任务参数移动到作业级别。

在运行时重写参数

若要在运行作业时覆盖作业参数值，请传递新值：

CLI

使用双连字符（--）指示命令标志是作业参数。请参阅传递作业参数

databricks bundle run my_job -- --catalog=prod --mode=full_refresh

REST API

{
  "job_id": 123,
  "job_parameters": {
    "catalog": "prod",
    "mode": "full_refresh"
  }
}

UI

在 Databricks 工作区中打开任务。
单击“立即运行”。
选择使用不同参数运行的选项。

请参阅运行具有不同设置的作业。

故障排除

以下部分可能有助于解决使用作业参数的一些常见问题。

参数值在运行时不会更改

捆绑包变量在部署时进行解析。如果需要在运行时重写某个值，请将其定义为作业参数，并将捆绑变量定义为其默认值，而不是 ${var.name} 任务代码或任务配置中的引用。部署后，可以在不重新部署的情况下，在执行时可以覆盖作业参数的默认值。

笔记本中不可用的参数

如果作业参数在笔记本中不可用，请验证以下所有内容：

参数在作业 parameters 部分中定义。
笔记本电脑使用 dbutils.widgets.get("name") 来访问每个参数。
参数名称完全匹配，包括大小写。
添加或重命名参数后重新部署了捆绑包。

其他资源

Last updated on 2026-05-24