Podstawianie i zmienne w pakietach zasobów usługi Databricks

Artykuł
02/09/2025

Pakiety zasobów usługi Databricks obsługują podstawianie i zmienne niestandardowe, dzięki czemu pliki konfiguracji pakietu będą bardziej modułowe i wielokrotnego użytku. Zarówno podstawianie, jak i zmienne niestandardowe umożliwiają dynamiczne pobieranie wartości, dzięki czemu ustawienia można określić w momencie wdrażania i uruchamiania pakietu.

Napiwek

Można również użyć odwołań do wartości dynamicznych dla wartości parametrów zadania, aby przekazać kontekst uruchomienia zadania do podzadań. Zobacz Co to jest odwołanie do wartości dynamicznej? i Sparametryzuj zadania.

Zastępstwa

Za pomocą podstawień można pobrać wartości ustawień, które zmieniają się w zależności od kontekstu wdrożenia pakietu i uruchomienia.

Na przykład po uruchomieniu bundle validate --output json polecenia może zostać wyświetlony wykres podobny do następującego:

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

Substytucje mogą być użyte do odwoływania się do wartości pól pakietu name, pakietu targeti obszaru roboczego userName w celu skonstruowania obszaru roboczego root_path w pliku konfiguracyjnym pakietu.

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Można również tworzyć podstawienia dla nazwanych zasobów. Na przykład dla potoku skonfigurowanego przy użyciu nazwy my_pipeline, ${resources.pipelines.my_pipeline.target} jest podstawianie wartości docelowej my_pipeline.

Aby określić prawidłowe podstawienia, można użyć hierarchii schematu udokumentowanej w dokumentacji interfejsu API REST lub wyników polecenia bundle schema.

Poniżej przedstawiono niektóre często używane podstawianie:

${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}

Zmienne niestandardowe

W pakiecie można zdefiniować zarówno proste, jak i złożone zmienne niestandardowe, aby umożliwić dynamiczne pobieranie wartości wymaganych w wielu scenariuszach. Zmienne własne są deklarowane w plikach konfiguracji pakietu w ramach mapowania variables lub w pliku variable-overrides.json. Aby uzyskać informacje na temat mapowania variables, zobacz zmienne .

Poniższa przykładowa konfiguracja definiuje zmienne my_cluster_id i 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

Jeśli nie podasz wartości default dla zmiennej w ramach tej deklaracji, musisz ustawić ją podczas wykonywania poleceń pakietu, za pomocą zmiennej środowiskowej lub gdzie indziej w plikach konfiguracji pakietu zgodnie z opisem w Ustaw wartość zmiennej.

Można również definiować i ustawiać wartości zmiennych w pliku .databricks/bundle/<target>/variable-overrides.json w projekcie pakietu, gdzie <target> jest obiektem docelowym obszaru roboczego, takim jak dev. Zobacz Ustaw wartość zmiennej.

Referencja do zmiennej

Aby odwołać się do zmiennej niestandardowej w ramach konfiguracji pakietu, użyj podstawianie. Aby na przykład odwołać się do zmiennych my_cluster_id i 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}

Ustawianie wartości zmiennej

Jeśli nie podano default wartości zmiennej lub jeśli chcesz tymczasowo zastąpić default wartość zmiennej, podaj nową wartość tymczasową zmiennej przy użyciu jednej z następujących metod:

Podaj wartość zmiennej w ramach bundle polecenia, takiego jak validate, deploylub run. W tym celu użyj opcji --var="<key>=<value>", gdzie <key> jest nazwą zmiennej, a <value> jest wartością zmiennej. Na przykład w ramach bundle validate polecenia, aby podać wartość 1234-567890-abcde123 zmiennej o nazwie , i podać wartość my_cluster_id zmiennej o nazwie ./hello.pymy_notebook_path, uruchom:
```
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"
```
Podaj wartość zmiennej, ustawiając zmienną środowiskową. Nazwa zmiennej środowiskowej musi zaczynać się od BUNDLE_VAR_. Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego. Aby na przykład podać wartość 1234-567890-abcde123 zmiennej o nazwie , i podać wartość my_cluster_id zmiennej o nazwie ./hello.pymy_notebook_path, uruchom następujące polecenie przed wywołaniem bundle polecenia takiego jak validate, deploylub run:

W przypadku systemów Linux i macOS:
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Dla systemu Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
Możesz też podać wartość zmiennej w ramach bundle polecenia, takiego jak validate, deploylub run, na przykład dla systemów Linux i macOS:
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
Lub dla systemu Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
Podaj wartość zmiennej w plikach konfiguracji pakietu przy użyciu mapowania variables w ramach mapowania targets, korzystając z następującego formatu:
```
variables:
  <variable-name>: <value>
```
Aby na przykład ustawić wartości zmiennych o nazwie my_cluster_id i my_notebook_path dla dwóch oddzielnych obiektów docelowych:
```
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
```
Podaj wartość zmiennej w pliku .databricks/bundle/<target>/variable-overrides.json przy użyciu następującego formatu:
```
{
  "<variable-name>": "<variable-value>"
}
```
Aby na przykład podać wartości zmiennych o nazwie my_cluster_id i my_notebook_path dla obiektu docelowego dewelopera, utwórz plik .databricks/bundle/dev/variable-overrides.json i ustaw jego zawartość na:
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
Można również zdefiniować złożone zmienne w pliku variable-overrides.json.

Uwaga

Niezależnie od wybranego podejścia do podawania wartości zmiennych należy użyć tego samego podejścia zarówno podczas wdrażania, jak i etapów uruchamiania. W przeciwnym razie mogą wystąpić nieoczekiwane wyniki między czasem wdrożenia a uruchomieniem zadania lub potoku opartego na tym istniejącym wdrożeniu.

Kolejność pierwszeństwa

Interfejs wiersza polecenia usługi Databricks wyszukuje wartości zmiennych w następującej kolejności, zatrzymując się po znalezieniu wartości zmiennej:

W ramach dowolnych --var opcji określonych jako część bundle polecenia.
W dowolnym zestawie zmiennych środowiskowych rozpoczynających się od BUNDLE_VAR_.
W pliku variables-overrides.json, jeśli istnieje.
W ramach wszelkich variables mapowań między targets mapowaniami w plikach konfiguracji pakietu.
Dowolna default wartość definicji tej zmiennej wśród mapowań najwyższego poziomu variables w plikach konfiguracji pakietu.

Definiowanie zmiennej złożonej

Przyjmuje się, że zmienna niestandardowa jest ciągiem typu, chyba że zostanie zdefiniowana jako zmienna zespolona. Aby zdefiniować zmienną niestandardową o złożonym typie dla swojego pakietu w konfiguracji pakietu, ustaw type na complex.

Uwaga

Jedyną prawidłową wartością ustawienia type jest complex. Ponadto sprawdzanie poprawności pakietu kończy się niepowodzeniem, jeśli type jest ustawiona na complex, a default zdefiniowana dla zmiennej jest pojedynczą wartością.

W poniższym przykładzie ustawienia klastra są definiowane w niestandardowej zmiennej złożonej o nazwie 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

Można również zdefiniować zmienną złożoną w pliku .databricks/bundles/<target>/variable-overrides.json, jak pokazano w poniższym przykładzie:

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

Pobieranie wartości identyfikatora obiektu

W przypadku alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principali typów obiektów warehouse można zdefiniować lookup dla zmiennej niestandardowej w celu pobrania identyfikatora nazwanego obiektu przy użyciu tego formatu:

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

Jeśli wyszukiwanie jest zdefiniowane dla zmiennej, identyfikator obiektu o określonej nazwie jest używany jako wartość zmiennej. Gwarantuje to, że prawidłowy rozpoznany identyfikator obiektu jest zawsze używany dla zmiennej.

Uwaga

Błąd występuje, jeśli obiekt o określonej nazwie nie istnieje lub jeśli istnieje więcej niż jeden obiekt o określonej nazwie.

Na przykład w poniższej konfiguracji ${var.my_cluster_id} zostanie zastąpiony identyfikatorem udostępnionego klastra 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}

Udostępnij za pośrednictwem

Podstawianie i zmienne w pakietach zasobów usługi Databricks

Zastępstwa

Zmienne niestandardowe

Referencja do zmiennej

Ustawianie wartości zmiennej

Kolejność pierwszeństwa

Definiowanie zmiennej złożonej

Pobieranie wartości identyfikatora obiektu

Opinia

Dodatkowe zasoby