Sostituzioni e variabili personalizzate nei bundle di asset di Databricks

Articolo
02/08/2025

I bundle di asset di Databricks supportano sostituzioni e variabili personalizzate, che rendono i file di configurazione del bundle più modulari e riutilizzabili. Sia le sostituzioni che le variabili personalizzate consentono il recupero dinamico dei valori in modo che le impostazioni possano essere determinate al momento dell’implementazione e dell'esecuzione di un bundle.

Suggerimento

È anche possibile usare riferimenti a valori dinamici per i valori dei parametri del processo per passare il contesto relativo a un'esecuzione del processo alle attività del processo. Vedere Configurare i parametri del task e Che cos'è un valore dinamico di riferimento?

Sostituzioni

È possibile usare le sostituzioni per recuperare i valori delle impostazioni che cambiano in base al contesto dell’implementazione e dell'esecuzione del bundle.

Ad esempio, quando si esegue il comandobundle validate --output json, è possibile che venga visualizzato un grafico simile al seguente:

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

Le sostituzioni possono essere usate per fare riferimento ai valori dei campi bundle name, bundle target e dell'area di lavoro userName per costruire l'area di lavoro root_path nel file di configurazione del bundle:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

È anche possibile creare sostituzioni per le risorse denominate. Ad esempio, per la pipeline configurata con il nome my_pipeline, ${resources.pipelines.my_pipeline.target} è la sostituzione del valore della destinazione di my_pipeline.

Per determinare le sostituzioni valide, è possibile usare la gerarchia dello schema documentata nel riferimento all'API REST o nell'output del comando bundle schema.

Di seguito sono riportati alcune sostituzioni di uso comune:

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

Variabili personalizzate

Nel bundle è possibile definire variabili personalizzate semplici e complesse per abilitare il recupero dinamico dei valori necessari per molti scenari. Le variabili personalizzate vengono dichiarate nei file di configurazione del bundle all'interno del mapping variables o in un file di variable-overrides.json. Per informazioni sul mapping variables, vedere variabili .

La seguente configurazione di esempio definisce le variabili my_cluster_id e 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

Se non si specifica un valore default per una variabile come parte di questa dichiarazione, è necessario impostarlo durante l'esecuzione di comandi bundle, tramite una variabile di ambiente o altrove all'interno dei file di configurazione del bundle, come descritto in Impostare il valore di una variabile.

È anche possibile definire e impostare i valori delle variabili nel file di .databricks/bundle/<target>/variable-overrides.json nel progetto bundle, dove <target> è la destinazione dell'area di lavoro, ad esempio dev. Vedere Impostare il valore di una variabile.

Fare riferimento a una variabile

Per fare riferimento a una variabile personalizzata all'interno della configurazione del bundle, usare la sostituzione della variabile ${var.<variable_name>}. Ad esempio, per fare riferimento alle variabili my_cluster_id e 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}

Impostare un valore della variabile

Se non è stato specificato un valore defaultper una variabile o se si desidera eseguire temporaneamente l'override del valore default per una variabile, specificare il nuovo valore temporaneo della variabile usando uno degli approcci seguenti:

Specificare il valore della variabile come parte di un comando bundle, ad esempio validate, deploy o run. A tale scopo, usare l'opzione --var="<key>=<value>", dove <key> è il nome della variabile e <value> è il valore della variabile. Ad esempio, come parte del comando bundle validate, per fornire il valore di 1234-567890-abcde123 alla variabile denominata my_cluster_id e per fornire il valore di ./hello.py alla variabile denominata my_notebook_path, eseguire:
```
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"
```
Specificare il valore della variabile impostando una variabile di ambiente. I nomi delle variabili di ambiente devono iniziare con BUNDLE_VAR_. Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo. Ad esempio, per fornire il valore di 1234-567890-abcde123 alla variabile denominata my_cluster_id e il valore di ./hello.py alla variabile denominata my_notebook_path, eseguire il seguente comando prima di attivare un comando bundle, come validate, deploy oppure run:

Per Linux e macOS:
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Per Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
In alternativa, specificare il valore della variabile come parte di un comandobundle, ad esempio validate, deploy o run, per Linux e macOS:
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
Oppure per Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
Specificare il valore della variabile all'interno dei file di configurazione del bundle usando il mapping variables all'interno del mapping targets, seguendo questo formato:
```
variables:
  <variable-name>: <value>
```
Ad esempio, per impostare i valori per le variabili denominate my_cluster_id e my_notebook_path per due destinazioni separate:
```
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
```
Specificare il valore della variabile all'interno del file .databricks/bundle/<target>/variable-overrides.json, usando il formato seguente:
```
{
  "<variable-name>": "<variable-value>"
}
```
Ad esempio, per fornire valori per le variabili denominate my_cluster_id e my_notebook_path per la destinazione di sviluppo, creare un file .databricks/bundle/dev/variable-overrides.json e impostarne il contenuto su:
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
È anche possibile definire variabili complesse nel file variable-overrides.json.

Nota

Indipendentemente da quale sia l’approccio scelto per fornire valori di variabile, usare lo stesso approccio sia durante le fasi di distribuzione che in quelle di esecuzione. In caso contrario, è possibile ottenere risultati imprevisti tra il tempo di una distribuzione e un processo o un'esecuzione della pipeline basata su tale distribuzione esistente.

Ordine di precedenza

L'interfaccia della riga di comando di Databricks cerca i valori delle variabili nell'ordine seguente, arrestando quando trova un valore per una variabile:

All'interno di qualsiasi opzione --var specificata come parte del comando bundle.
All'interno di tutte le variabili di ambiente impostate che iniziano con BUNDLE_VAR_.
All'interno del file variables-overrides.json, se esistente.
All'interno di qualsiasi mapping variables, tra i mapping targets all'interno dei file di configurazione del bundle.
Qualsiasi valore default per la definizione di tale variabile, tra i mapping variables di primo livello all'interno dei file di configurazione del bundle.

Definire una variabile complessa

Si presuppone che una variabile personalizzata sia di tipo stringa, a meno che non venga definita come variabile complessa. Per definire una variabile complessa personalizzata per il tuo bundle nella sua configurazione, imposta type su complex.

Nota

L'unico valore valido per l'impostazione type è complex. Inoltre, la convalida del bundle ha esito negativo se type è impostata su complex e l'oggetto default definito per la variabile è un singolo valore.

Nell'esempio seguente le impostazioni del cluster vengono definite all'interno di una variabile complessa personalizzata denominata 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

È anche possibile definire una variabile complessa nel file .databricks/bundles/<target>/variable-overrides.json, come illustrato nell'esempio seguente:

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

Recuperare il valore ID di un oggetto

Per alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principale warehouse tipi di oggetto , è possibile definire un lookup per la variabile personalizzata per recuperare l'ID di un oggetto denominato usando questo formato:

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

Se viene definita una ricerca per una variabile, l'ID dell'oggetto con il nome specificato viene usato come valore della variabile. In questo modo, l'ID risolto corretto dell'oggetto viene sempre usato per la variabile.

Nota

Si verifica un errore se un oggetto con il nome specificato non esiste o se è presente più di un oggetto con il nome specificato.

Nella configurazione seguente, ad esempio, ${var.my_cluster_id} verrà sostituito dall'ID del cluster condiviso 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}

Condividi tramite

Sostituzioni e variabili personalizzate nei bundle di asset di Databricks

Sostituzioni

Variabili personalizzate

Fare riferimento a una variabile

Impostare un valore della variabile

Ordine di precedenza

Definire una variabile complessa

Recuperare il valore ID di un oggetto

Commenti e suggerimenti

Risorse aggiuntive