Замены и переменные в пакетах ресурсов Databricks

Статья
02/09/2025

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

Совет

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

Подстановки

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

Например, при выполнении bundle validate --output json команды может появиться следующий график:

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

Подстановки можно использовать для ссылки на значения пакета, пакета nametargetи полей рабочей области для создания рабочей области userNameroot_path в файле конфигурации пакета:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Вы также можете создавать подстановки именованных ресурсов. Например, для конвейера, настроенного с именем 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}

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

Вы можете определить простые и сложные пользовательские переменные в пакете, чтобы включить динамическое извлечение значений, необходимых для многих сценариев. Пользовательские переменные объявляются в файлах конфигурации пакета в сопоставлении 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 в проекте пакета, где <target> является целевым объектом рабочей области, например dev. См. Установка значения переменной.

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

Чтобы ссылаться на пользовательскую переменную в конфигурации пакета, используйте подстановку. Например, чтобы ссылаться на переменные 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_.
В файле variables-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/bundles/<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, jobmetastore, 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

Подстановки

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

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

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

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

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

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

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

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