Ersetzungen und Variablen in Databricks Asset Bundles

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.

Ersetzungen

Sie können Ersetzungen verwenden, um Werte von Einstellungen abzurufen, die sich basierend auf dem Kontext der Bundlebereitstellung und -ausführung ändern können. Beispielsweise können Unterschriften verwendet werden, um auf die Werte der Bündel-, Bündelnametarget- und Arbeitsbereichsfelder userName zu verweisen, um den Arbeitsbereich root_path in der Bündelkonfigurationsdatei zu erstellen:

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Wenn someone@example.com dieses Bundle bereitgestellt wird, wird es im Stammpfad /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/devbereitgestellt.

Sie können auch Ersetzungen für benannte Ressourcen erstellen. Beispielsweise können Sie für die folgende Pipelinedefinition den Wert des Pipelineziels verwenden ${resources.pipelines.my_pipeline.target} :

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/my_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

Um gültige Ersetzungen zu ermitteln, verwenden Sie den Bundlekonfigurationsverweis, den Ressourcenkonfigurationsverweis oder die Schemahierarchie entsprechender Objekte, die in der REST-API-Referenz dokumentiert sind, oder die Ausgabe des bundle schema Befehls.

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.domain_friendly_name}
• ${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. Eigene Variablen werden in den Bundle-Konfigurationsdateien innerhalb der variables-Zuordnung oder in einer variable-overrides.json-Datei deklariert. Informationen zur variables-Zuordnung finden Sie unter 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 Wert für eine Variable angeben default , müssen Sie ihn festlegen, wenn Sie Bündelbefehle, über eine Umgebungsvariable, an anderer Stelle innerhalb der Bündelkonfigurationsdateien oder in der .databricks/bundle/<target>/variable-overrides.json Datei im Bundleprojekt ausführen. Weitere Informationen finden Sie unter Festlegen des Werts einer Variablen.

Verweisen auf eine Variable

Verwenden Sie die Variable substitution${var.<variable_name>}, um auf eine benutzerdefinierte Variable in Ihrer Paketkonfiguration zu verweisen. Die folgende Konfiguration verweist beispielsweise auf die 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 Wert für eine Variable festgelegt haben oder den default Wert für eine Variable vorübergehend außer Kraft setzen default möchten, geben Sie den neuen temporären Wert der Variablen mithilfe einer der folgenden Ansätze an.

• Geben Sie den Wert der Variablen als Teil eines bundle Befehls an, z. B. validate, deploy oder run. Verwenden Sie dazu die Option --var="<key>=<value>", wobei <key> es sich um den Namen der Variablen handelt 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 Umgebungsvariable muss mit BUNDLE_VAR_ beginnen. Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation Ihres 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
  

  Für 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 an, wie z. B. validate, deploy oder run, beispielsweise 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 Variablen in Ihren Paketkonfigurationsdateien mithilfe der variables Zuordnung innerhalb der targets Zuordnung an, und folgen Sie diesem Format:

  variables:
    <variable-name>: <value>
  

  Wenn Sie beispielsweise Werte für die Variablen mit dem Namen my_cluster_id und my_notebook_path für zwei separate Ziele festlegen möchten:

  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
  

• Geben Sie den Wert der Variablen in der .databricks/bundle/<target>/variable-overrides.json Datei mithilfe des folgenden Formats an:

  {
    "<variable-name>": "<variable-value>"
  }
  

  Um z. B. Werte für die Variablen mit dem Namen my_cluster_id und my_notebook_path für das Dev-Ziel bereitzustellen, erstellen Sie eine Datei .databricks/bundle/dev/variable-overrides.json, und legen Sie deren Inhalt auf Folgendes fest:

  {
    "my_cluster_id": "1234-567890-abcde123",
    "my_notebook_path": "./hello.py"
  }
  

  Sie können auch komplexe Variablen in der variable-overrides.json Datei definieren.

Rangfolge

Die Databricks CLI sucht in der folgenden Reihenfolge nach Werten für Variablen, die beendet werden, wenn ein Wert für eine Variable gefunden wird:

1. Innerhalb aller --var-Optionen, die im Rahmen des bundle-Befehls angegeben werden.
2. Innerhalb eines beliebigen Umgebungsvariablensatzes, der mit BUNDLE_VAR_ beginnt.
3. In der Datei variables-overrides.json, falls vorhanden.
4. Innerhalb beliebiger variables-Zuordnungen, unter den targets-Zuordnungen in Ihren Paketkonfigurationsdateien.
5. Jeder default Wert für die Definition dieser Variablen unter den Zuordnungen auf oberster Ebene variables innerhalb der Bündelkonfigurationsdateien.

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. Um eine benutzerdefinierte Variable mit einem komplexen Typ für Ihr Bündel in der Bundlekonfiguration zu definieren, legen Sie type auf complexfest.

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

Sie können auch eine komplexe Variable in der datei .databricks/bundle/<target>/variable-overrides.json definieren, wie im folgenden Beispiel gezeigt:

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

Abrufen des ID-Werts eines Objekts

Für die Objekttypen alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal und warehouse können Sie eine lookup für die benutzerdefinierte Variable definieren, um die ID eines benannten Objekts mithilfe dieses Formats zu erhalten.

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.

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}

Ausgabeersetzung und Variablenwerte

Um sicherzustellen, dass Ihre Ersetzungen und Variablen korrekt angegeben und von Databricks Asset Bundles analysiert werden, führen Sie aus databricks bundle validate. Siehe "databricks bundle validate". Verwenden Sie die --output json Option, um Werte anzuzeigen, die beim Bereitstellen eines Bundles verwendet werden:

databricks bundle validate --output json

Zum Beispiel, für ein Paket mit der Variable my_cluster_id, die in einer Aufgabe verwendet wird.

bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

Die databricks bundle validate Schemaausgabe wäre wie folgt:

{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}