Ersetzungen und Variablen in Databricks Asset Bundles

Artikel
10/04/2024

Databricks Asset Bundles unterstützt Ersetzungen und benutzerdefinierte Variablen, wodurch Ihre Bündelkonfigurationsdateien modularer und wiederverwendbarer werden. Sowohl Ersetzungen als auch benutzerdefinierte Variablen ermöglichen das dynamische Abrufen von Werten, sodass Einstellungen beim Bereitstellen und Ausführen eines Bundles bestimmt werden können.

Tipp

Sie können auch dynamische Wertverweise für Auftragsparameterwerte verwenden, um Kontext zu einem Auftrag zu übergeben, der an Auftragsaufgaben ausgeführt wird. Siehe Was ist eine dynamische Wertreferenz? und Aufträge parametrisieren.

Substitutions

Sie können Ersetzungen verwenden, um Werte von Einstellungen abzurufen, die sich basierend auf dem Kontext der Bundlebereitstellung ändern und ausgeführt werden.

Wenn Sie beispielsweise den bundle validate --output json-Befehl ausführen, wird möglicherweise ein Diagramm wie folgt angezeigt:

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

Ersetzungen können verwendet werden, um auf die Werte der Bündel name, Bündel target unduserName-Felder des Arbeitsbereichs zu verweisen, um den Arbeitsbereich root_path in der Bündelkonfigurationsdatei zu erstellen:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Sie können auch Ersetzungen für benannte Ressourcen erstellen. Für die konfigurierte Pipeline namens my_pipeline ist ${resources.pipelines.my_pipeline.target} beispielsweise die Ersetzung für den Wert des Ziels von my_pipeline.

Um gültige Ersetzungen zu ermitteln, können Sie die Schemahierarchie, die in der REST-API-Referenz dokumentiert ist, oder die Ausgabe des bundle schema-Befehls verwenden.

Nachfolgend sind einige häufig verwendete Substitutionen aufgeführt:

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

Benutzerdefinierte Variablen

Sie können sowohl einfache als auch komplexe benutzerdefinierte Variablen in Ihrem Bündel definieren, um das dynamische Abrufen von Werten zu ermöglichen, die für viele Szenarien erforderlich sind. Benutzerdefinierte Variablen werden in Ihren Paketkonfigurationsdateien innerhalb der variables-Zuordnung deklarieren. Siehe Variablen.

Die folgende Beispielkonfiguration definiert die Variablen my_cluster_id und 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

Wenn Sie im Rahmen dieser Deklaration keinen default-Wert für eine Variable angeben, müssen Sie ihn festlegen, wenn Sie Paketbefehle ausführen – entweder über eine Umgebungsvariable oder an anderer Stelle in Ihren Paketkonfigurationsdateien, wie unter Festlegen des Werts einer Variablen beschrieben.

Verwenden Sie die Variable Ersetzungen ${var.<variable_name>}, um auf eine benutzerdefinierte Variable in Ihren Paketkonfiguration zu verweisen. So verweisen Sie beispielsweise auf Variablen my_cluster_id und 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}

Festlegen des Werts einer Variablen

Wenn Sie keinen default-Wert für eine Variable angegeben haben oder den default-Wert für eine Variable vorübergehend außer Kraft setzen möchten, geben Sie den neuen temporären Wert der Variablen mithilfe vom einem der folgenden Ansätze an:

Geben Sie den Wert der Variablen als Teil eines bundle-Befehls wie validate, deploy oder run an. Verwenden Sie hierzu die Option --var="<key>=<value>", wobei <key> der Name der Variablen und <value> der Wert der Variablen ist. Beispiel: Führen Sie beispielsweise Folgendes aus, um als Teil des bundle validate-Befehls den Wert 1234-567890-abcde123 für die Variable mit dem Namen my_cluster_idbereitzustellen und den Wert ./hello.py für die Variable mit dem Namen my_notebook_path bereitzustellen:
```
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"
```
Geben Sie den Wert der Variablen an, indem Sie eine Umgebungsvariable festlegen. Der Name der Umgebungsvariablen muss mit BUNDLE_VAR_ beginnen. Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation des Betriebssystems. Um beispielsweise den Wert von 1234-567890-abcde123 für die Variable mit dem Namen my_cluster_id bereitzustellen und den Wert von ./hello.py für die Variable mit dem Namen my_notebook_path bereitzustellen, führen Sie den folgenden Befehl aus, bevor Sie einen bundle-Befehl wie validate, deploy oder run aufrufen:

Für Linux und 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"
```
Oder geben Sie den Wert der Variablen als Teil eines bundle-Befehls wie validate, deploy oder run an, z. B. für Linux und macOS:
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
Oder für Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
Geben Sie den Wert der Variable in den Paketkonfigurationsdateien an. Verwenden Sie hierzu eine variables-Zuordnung innerhalb der targets-Zuordnung im folgenden Format:
```
variables:
  <variable-name>: <value>
```
Um beispielsweise Werte für die Variablen mit den Namen my_cluster_id und my_notebook_path für zwei separate Ziele bereitzustellen:
```
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
```

Hinweis

Unabhängig davon, welchen Ansatz Sie zum Bereitstellen von Variablenwerten wählen, verwenden Sie den gleichen Ansatz sowohl in der Bereitstellungs- als auch in der Ausführungsphase. Andernfalls erhalten Sie möglicherweise unerwartete Ergebnisse zwischen dem Zeitpunkt einer Bereitstellung und einer Auftrags- oder Pipelineausführung, die auf dieser vorhandenen Bereitstellung basiert.

In den vorherigen Beispielen sucht die Databricks-CLI nach Werten für die Variablen my_cluster_id und my_notebook_path in der folgenden Reihenfolge und stoppt, wenn sie einen Wert für jede übereinstimmende Variable findet, und überspringt alle anderen Speicherorte für diese Variable:

Innerhalb aller --var-Optionen, die im Rahmen des bundle-Befehls angegeben werden.
Innerhalb eines beliebigen Umgebungsvariablensatzes, der mit BUNDLE_VAR_ beginnt.
Innerhalb beliebiger variables-Zuordnungen, unter den targets-Zuordnungen in Ihren Paketkonfigurationsdateien.
Ein beliebiger default-Wert für die Definition dieser Variablen unter den variables-Zuordnungen auf oberster Ebene in Ihren Paketkonfigurationsdateien.

Definieren einer komplexen Variablen

Es wird angenommen, dass es eine benutzerdefinierte Variable vom Typ Zeichenkette ist, es sei denn, Sie definieren sie als komplexe Variable. Wenn Sie eine benutzerdefinierte Variable mit einem komplexen Typ für Ihr Paket definieren möchten, legen Sie type in der Paketkonfiguration auf complex fest.

Hinweis

Der einzige gültige Wert für die Einstellung type ist complex. Darüber hinaus ist die Paketüberprüfung nicht erfolgreich, wenn type auf complex festgelegt ist und der für die Variable definierte Standardwert (default) ein einzelner Wert ist.

Im folgenden Beispiel werden Clustereinstellungen in einer benutzerdefinierten komplexen Variablen namens my_cluster definiert:

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

Abrufen des ID-Werts eines Objekts

Für die Objekttypen alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, pipeline, query, service_principal und warehouse können Sie eine lookup für die benutzerdefinierte Variable definieren, um eine benannte Objekt-ID in diesem Format abzurufen:

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

Wenn ein Lookup für eine Variable definiert ist, wird die ID des Objekts mit dem angegebenen Namen als Wert der Variablen verwendet. Dadurch wird sichergestellt, dass die richtige aufgelöste ID des Objekts immer für die Variable verwendet wird.

Hinweis

Wenn ein Objekt mit dem angegebenen Namen nicht vorhanden ist oder mehrere Objekte mit dem angegebenen Namen vorhanden sind, tritt ein Fehler auf.

In der folgenden Konfiguration wird ${var.my_cluster_id} beispielsweise mit der ID des freigegebenen Clusters 12.2 ersetzt.

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}

Freigeben über

Ersetzungen und Variablen in Databricks Asset Bundles

Substitutions

Benutzerdefinierte Variablen

Festlegen des Werts einer Variablen

Definieren einer komplexen Variablen

Abrufen des ID-Werts eines Objekts

Feedback

Zusätzliche Ressourcen