Замены и переменные в декларативных пакетах автоматизации

Декларативные пакеты автоматизации (ранее известные как наборы ресурсов Databricks) поддерживают подстановки и пользовательские переменные, что делает файлы конфигурации пакета более модульными и повторно используемыми. Как подстановки, так и пользовательские переменные обеспечивают динамическое извлечение значений, чтобы можно было определить параметры во время развертывания и запуска пакета.

Совет

Вы также можете использовать динамические ссылки на значения параметров задания, чтобы передавать информацию о выполнении задания задачам. См. ссылки на динамические значения и задания параметризации.

Подстановки

Вы можете использовать подстановки для получения значений параметров, которые могут изменяться в зависимости от контекста развертывания пакета и запуска. Например, подстановки можно использовать для обращения к значениям полей пакетa name, пакетa target и рабочей области userName, чтобы создать рабочую область root_path в конфигурационном файле пакета.

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Если someone@example.com этот пакет развернут, он будет развернут в корневом пути /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev.

Вы также можете создавать замены для именованных ресурсов. Например, для следующего определения конвейера можно использовать ${resources.pipelines.my_pipeline.target} для значения целевого объекта конвейера:

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/my_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

Чтобы определить допустимые замены, используйте ссылку на конфигурацию пакета, ссылку на конфигурацию ресурсов или иерархию схемы соответствующих объектов, описанных в справочнике REST API, или выходные данные bundle schema команды.

Совет

Полный список подстановок, доступных для ресурсов, см. в репозитории GitHub Databricks CLI out.fields.txt.

Ниже приведены некоторые часто используемые подстановки:

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.domain_friendly_name}
${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}

Пользовательские переменные

Вы можете определить простые и сложные пользовательские переменные в пакете, чтобы включить динамическое извлечение значений, необходимых для многих сценариев. Пользовательские переменные объявляются в файлах конфигурации пакета в сопоставлении variables или в файле variable-overrides.json. Сведения о сопоставлении variables см. в переменных .

В следующем примере конфигурации определяются переменные my_cluster_id и my_notebook_path:

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 значение переменной в рамках этого объявления, необходимо задать ее при выполнении команд пакета, используя переменную среды, в других местах в файлах конфигурации пакета или в .databricks/bundle/<target>/variable-overrides.json файле проекта пакета. См. раздел "Задать значение переменной".

Ссылка на переменную

Чтобы ссылаться на пользовательскую переменную в конфигурации пакета, используйте подстановку. Например, следующая конфигурация ссылается на переменные my_cluster_id и my_notebook_path:

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.pymy_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.pymy_notebook_path, выполните следующую команду перед вызовом bundle такой команды, как validate, deployилиrun:

Для 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"
```
Или укажите значение переменной как часть bundle команды, например validate, deployили run, например, для 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/bundle/<target>/variable-overrides.json файле, используя следующий формат:
```
{
  "<variable-name>": "<variable-value>"
}
```
Например, чтобы указать значения переменных с именем my_cluster_id и my_notebook_path для целевого объекта разработки, создайте файл .databricks/bundle/dev/variable-overrides.json и задайте его содержимое следующим образом:
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
Можно также определить сложные переменные в файле variable-overrides.json.

Примечание.

Какой бы подход ни был выбран для предоставления значений переменных, используйте один и тот же подход во время развертывания и выполнения этапов. В противном случае могут возникнуть непредвиденные результаты между моментом развертывания и запуском задания или конвейера, который основан на этом развертывании.

Порядок приоритета

Интерфейс командной строки Databricks ищет значения переменных в следующем порядке, остановившись при поиске значения переменной:

В любых параметрах --var, указанных как часть команды bundle.
В любом наборе переменных среды, начинающихся с BUNDLE_VAR_.
В файле variable-overrides.json, если он существует.
В любых variables сопоставлениях среди targets сопоставлений в файлах конфигурации вашего пакета.
Любое значение default для определения той переменной внутри сопоставлений верхнего уровня variables в файлах конфигурации вашего пакета.

Определение сложной переменной

Пользовательская переменная считается строкой типа, если она не определена как сложная переменная. Чтобы определить пользовательскую переменную со сложным типом для вашего пакета в конфигурации пакета, присвойте type значение complex.

Примечание.

Единственным допустимым значением type параметра является complex. Кроме того, проверка пакета завершается ошибкой, если 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

Можно также определить сложную переменную в файле .databricks/bundle/<target>/variable-overrides.json, как показано в следующем примере:

{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

Получение значения идентификатора объекта

Для типов объектов alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, 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}

Значения подстановок и переменных на выходе

Чтобы убедиться, что замены и переменные правильно указаны и проанализированы декларативными пакетами автоматизации, выполните команду databricks bundle validate. См. databricks bundle validate. Чтобы просмотреть значения, которые будут использоваться при развертывании пакета, используйте этот --output json параметр:

databricks bundle validate --output json

Например, для пакета с переменной my_cluster_id , определенной и используемой в задаче задания:

bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

Выходная схема данных databricks bundle validate будет следующей:

{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-16

Замены и переменные в декларативных пакетах автоматизации

Подстановки

Пользовательские переменные

Ссылка на переменную

Установка значения переменной

Порядок приоритета

Определение сложной переменной

Получение значения идентификатора объекта

Значения подстановок и переменных на выходе

Обратная связь

Дополнительные ресурсы