Vervangingen en variabelen in Databricks Asset Bundles

Artikel
02/09/2025

Databricks Asset Bundles ondersteunt vervangingen en aangepaste variabelen, waardoor uw bundelconfiguratiebestanden modulairer en herbruikbaarder worden. Zowel vervangingen als aangepaste variabelen maken dynamisch ophalen van waarden mogelijk, zodat instellingen kunnen worden bepaald op het moment dat een bundel wordt geïmplementeerd en uitgevoerd.

Tip

U kunt ook dynamische waardeverwijzingen gebruiken voor taakparameterwaarden om context door te geven over een taakuitvoering aan taaktaken. Zie Wat is een verwijzing naar dynamische waarden? en Parametersize-taken.

Vervangingen

U kunt vervangingen gebruiken om waarden op te halen van instellingen die veranderen op basis van de context van de bundelimplementatie en uitvoering.

Wanneer u bijvoorbeeld de bundle validate --output json opdracht uitvoert, ziet u mogelijk een grafiek zoals deze:

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

Subsitutions kunnen worden gebruikt om te verwijzen naar de waarden van de bundel name-, bundel target- en werkruimtevelden userName om de werkruimte root_path in het bundelconfiguratiebestand samen te stellen:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

U kunt ook vervangingen voor benoemde resources maken. Bijvoorbeeld, voor de pijplijn die is geconfigureerd met de naam my_pipeline, ${resources.pipelines.my_pipeline.target} is de vervanging voor de waarde van het doel van my_pipeline.

Als u geldige vervangingen wilt bepalen, kunt u de schemahiërarchie gebruiken die wordt beschreven in de REST API-verwijzing of de uitvoer van de bundle schema opdracht.

Hier volgen enkele veelgebruikte vervangingen:

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

Aangepaste variabelen

U kunt zowel eenvoudige als complexe aangepaste variabelen in uw bundel definiëren om dynamisch waarden op te halen die nodig zijn voor veel scenario's. Aangepaste variabelen worden gedeclareerd in uw bundelconfiguratiebestanden binnen de variables-mapping of in een variable-overrides.json-bestand. Voor meer informatie over de toewijzing van variables, zie variabelen in.

De volgende voorbeeldconfiguratie definieert de variabelen my_cluster_id en 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

Als u geen waarde opgeeft default voor een variabele als onderdeel van deze declaratie, moet u deze instellen bij het uitvoeren van bundelopdrachten, via een omgevingsvariabele of elders in uw bundelconfiguratiebestanden, zoals beschreven in de waarde van een variabele instellen.

U kunt ook variabele waarden definiëren en instellen in het .databricks/bundle/<target>/variable-overrides.json-bestand in het bundelproject, waarbij <target> het werkruimtedoel is, zoals dev. Zie De waarde van een variabele instellen.

Verwijzen naar een variabele

Als u wilt verwijzen naar een aangepaste variabele in uw bundelconfiguratie, gebruikt u de variabele vervangen${var.<variable_name>}. Bijvoorbeeld om te verwijzen naar de variabelen my_cluster_id en 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}

De waarde van een variabele instellen

Als u geen waarde hebt opgegeven default voor een variabele of als u de default waarde voor een variabele tijdelijk wilt overschrijven, geeft u de nieuwe tijdelijke waarde van de variabele op met behulp van een van de volgende methoden:

Geef de waarde van de variabele op als onderdeel van een bundle opdracht, zoals validate, deployof run. Hiervoor gebruikt u de optie --var="<key>=<value>", waar <key> de naam van de variabele staat en <value> de waarde van de variabele. Als u bijvoorbeeld als onderdeel van de bundle validate opdracht de waarde van 1234-567890-abcde123 de variabele met de naam my_cluster_idwilt opgeven en de waarde wilt opgeven van ./hello.py de variabele met de naam my_notebook_path, voert u het volgende uit:
```
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"
```
Geef de waarde van de variabele op door een omgevingsvariabele in te stellen. De naam van de omgevingsvariabele moet beginnen met BUNDLE_VAR_. Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem. Als u bijvoorbeeld de waarde van 1234-567890-abcde123 de variabele met de naam my_cluster_idwilt opgeven en de waarde wilt opgeven van ./hello.py de variabele met de naam my_notebook_path, voert u de volgende opdracht uit voordat u een bundle opdracht aanroept, zoals validate, deployof run:

Voor Linux en macOS:
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Voor Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
Of geef de waarde van de variabele op als onderdeel van een bundle opdracht, zoals validate, deployof runbijvoorbeeld voor Linux en macOS:
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
Of voor Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
Geef de waarde van de variabele in uw bundelconfiguratiebestanden op met behulp van de variables mapping binnen de targets mapping, volgens dit formaat:
```
variables:
  <variable-name>: <value>
```
Als u bijvoorbeeld waarden wilt instellen voor de variabelen met de naam my_cluster_id en my_notebook_path voor twee afzonderlijke doelen:
```
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
```
Geef de waarde van de variabele op in het .databricks/bundle/<target>/variable-overrides.json-bestand, met behulp van de volgende indeling:
```
{
  "<variable-name>": "<variable-value>"
}
```
Als u bijvoorbeeld waarden wilt opgeven voor de variabelen met de naam my_cluster_id en my_notebook_path voor het dev-doel, maakt u een bestand .databricks/bundle/dev/variable-overrides.json en stelt u de inhoud ervan in op:
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
U kunt ook complexe variabelen definiëren in het bestand variable-overrides.json.

Notitie

Welke methode u ook kiest om variabele waarden op te geven, gebruik dezelfde benadering tijdens zowel de implementatie- als de uitvoeringsfase. Anders krijgt u mogelijk onverwachte resultaten tussen de tijd van een implementatie en een taak of pijplijnuitvoering die is gebaseerd op die bestaande implementatie.

Prioriteitsvolgorde

De Databricks CLI zoekt naar waarden voor variabelen in de volgende volgorde en stopt wanneer er een waarde voor een variabele wordt gevonden:

Binnen alle --var opties die zijn opgegeven als onderdeel van de bundle opdracht.
Binnen elke omgevingsvariabelenset die beginnen met BUNDLE_VAR_.
In het variables-overrides.json-bestand, indien aanwezig.
Binnen alle variables toewijzingen, tussen de targets toewijzingen binnen uw bundelconfiguratiebestanden.
Elke default waarde voor de definitie van die variabele, onder de toewijzingen op het hoogste niveau variables in uw bundelconfiguratiebestanden.

Een complexe variabele definiëren

Er wordt uitgegaan dat een aangepaste variabele van het type tekenreeks is, tenzij u deze definieert als een complexe variabele. Als u een aangepaste variabele wilt definiëren met een complex type voor uw bundel in uw bundelconfiguratie, stelt u type in op complex.

Notitie

De enige geldige waarde voor de type instelling is complex. Bovendien mislukt de bundelvalidatie als type deze is ingesteld complex op en de default gedefinieerde waarde voor de variabele één waarde is.

In het volgende voorbeeld worden clusterinstellingen gedefinieerd binnen een aangepaste complexe variabele met de naam 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

U kunt ook een complexe variabele definiëren in het bestand .databricks/bundles/<target>/variable-overrides.json, zoals wordt weergegeven in het volgende voorbeeld:

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

De id-waarde van een object ophalen

Voor de alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principalen warehouse objecttypen kunt u een lookup definiëren voor de aangepaste variabele om de id van een benoemd object op te halen met behulp van deze indeling:

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

Als een zoekactie is gedefinieerd voor een variabele, wordt de id van het object met de opgegeven naam gebruikt als de waarde van de variabele. Dit zorgt ervoor dat de juiste opgeloste id van het object altijd wordt gebruikt voor de variabele.

Notitie

Er treedt een fout op als een object met de opgegeven naam niet bestaat of als er meer dan één object is met de opgegeven naam.

In de volgende configuratie ${var.my_cluster_id} wordt bijvoorbeeld vervangen door de id van het gedeelde cluster 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}

Delen via

Vervangingen en variabelen in Databricks Asset Bundles

Vervangingen

Aangepaste variabelen

Verwijzen naar een variabele

De waarde van een variabele instellen

Prioriteitsvolgorde

Een complexe variabele definiëren

De id-waarde van een object ophalen

Feedback

Aanvullende resources