Konfigurationen für Databricks-Ressourcenpakete

In diesem Artikel wird die Syntax für Konfigurationsdateien für Databricks-Ressourcenpakete beschrieben, die Databricks-Ressourcenpakete definieren. Weitere Informationen finden Sie unter Was sind Databricks-Ressourcenpakete?.

Eine Paketkonfigurationsdatei muss im YAML-Format ausgedrückt werden und mindestens die bundle-Zuordnung der obersten Ebene enthalten. Jedes Paket muss mindestens eine (und nur eine) Paketkonfigurationsdatei mit dem Namen databricks.yml enthalten. Wenn mehrere Paketkonfigurationsdateien vorhanden sind, müssen sie von der Datei databricks.yml referenziert werden.

Weitere Informationen zu YAML finden Sie in der offiziellen YAML-Spezifikation und im Tutorial.

Informationen zum Erstellen und Verwenden von Paketkonfigurationsdateien finden Sie unter Workflow für Entwicklung von Databricks-Ressourcenpaketen.

• Übersicht
• Beispiele
• Zuordnungen
• Benutzerdefinierte Variablen
• Ersetzungen

Übersicht

In diesem Abschnitt finden Sie eine visuelle Darstellung des Schemas von Paketkonfigurationsdateien. Weitere Informationen finden Sie unter Zuordnungen.

# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  compute_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

# These are any additional configuration files to include.
include:
  - "<some-file-or-path-glob-to-include>"
  - "<another-file-or-path-glob-to-include>"

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the Experiments API's create experiment request payload reference.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See the Jobs API's create job request payload reference.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the Models API's create model request payload reference.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the Delta Live Tables API's create pipeline request payload reference.

# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    compute_id: string
    default: true | false
    mode: development
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

Beispiele

Im Folgenden finden Sie eine beispielhafte Paketkonfigurationsdatei. Dieses Paket gibt die Remotebereitstellung einer lokalen Datei mit dem Namen hello.py an, die sich im selben Verzeichnis wie diese lokale Paketkonfigurationsdatei namens databricks.yml befindet. Es führt dieses Notebook als Auftrag aus, indem der Remotecluster mit der angegebenen Cluster-ID verwendet wird. Die URL des Remotearbeitsbereichs und die Anmeldeinformationen für die Arbeitsbereichsauthentifizierung werden aus dem lokalen Konfigurationsprofil des Aufrufers mit dem Namen DEFAULT gelesen.

Hinweis

Databricks empfiehlt, nach Möglichkeit die host-Zuordnung anstelle der default-Zuordnung zu verwenden, da Ihre Paketkonfigurationsdateien dadurch portierbarer werden. Durch Festlegen der host-Zuordnung wird die Databricks CLI angewiesen, ein übereinstimmende Profil in Ihrer .databrickscfg-Datei zu suchen und dann die Felder dieses Profils zu verwenden, um zu bestimmen, welcher Databricks-Authentifizierungstyp verwendet werden soll. Wenn mehrere Profile mit einem übereinstimmenden host-Feld in Ihrer .databrickscfg-Datei vorhanden sind, müssen Sie profile verwenden, um die Databricks CLI anzuweisen, welches bestimmte Profil verwendet werden soll. Ein Beispiel finden Sie in der prod-Zieldeklaration weiter unten in diesem Abschnitt.

Mit dieser Technik können Sie die Auftragsdefinitionen und -einstellungen innerhalb des resources-Blocks wiederverwenden und überschreiben:

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

Obwohl die folgende Paketkonfigurationsdatei funktionell gleichwertig ist, ist sie nicht modularisiert, was keine gute Wiederverwendung ermöglicht. Außerdem fügt diese Deklaration eine Aufgabe an den Auftrag an, anstatt den vorhandenen Auftrag zu überschreiben:

bundle:
  name: hello-bundle

targets:
  dev:
    default: true
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 1234-567890-abcde123
              notebook_task:
                notebook_path: ./hello.py

Es folgt das vorherige modularisierte Beispiel, aber mit einem hinzugefügten Ziel mit dem programmgesteuerten (oder logischen) Namen prod, das eine andere Remotearbeitsbereichs-URL und Anmeldeinfos für die Arbeitsbereichauthentifizierung verwendet, die aus dem übereinstimmenden .databrickscfg-Eintrag des Aufrufers mit der angegebenen Arbeitsbereichs-URL host gelesen werden. Dieser Auftrag führt dasselbe Notebook aus, verwendet jedoch einen anderen Remotecluster mit der angegebenen Cluster-ID. Beachten Sie, dass Sie die notebook_task-Zuordnung innerhalb der prod-Zuordnung nicht deklarieren müssen, da sie auf die Verwendung der notebook_task-Zuordnung innerhalb der Zuordnung der obersten Ebene resources zurückfällt, wenn die notebook_task-Zuordnung nicht explizit in der prod-Zuordnung überschrieben wird.

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

Führen Sie die folgenden Befehle aus, um diesen Auftrag innerhalb des dev-Ziels zu überprüfen, bereitzustellen und auszuführen:

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

Führen Sie stattdessen die folgenden Befehle aus, um diesen Auftrag innerhalb des prod-Ziels zu überprüfen, bereitzustellen und auszuführen:

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

Im Folgenden sehen Sie das vorherige Beispiel, das jedoch in Komponentendateien aufgeteilt wurde, um noch mehr Modularisierung und bessere Wiederverwendung über mehrere Paketkonfigurationsdateien hinweg zu fördern. Mit diesem Verfahren können Sie nicht nur verschiedene Definitionen und Einstellungen wiederverwenden, sondern auch eine dieser Dateien durch andere Dateien austauschen, die völlig unterschiedliche Deklarationen bieten:

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

bundle.targets.yml:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

Weitere Beispiele finden Sie im Paketbeispielrepository auf GitHub.

Zuordnungen

In den folgenden Abschnitten wird die Syntax von Paketkonfigurationsdateien anhand der Zuordnung der obersten Ebene beschrieben.

• bundle
• variables
• Arbeitsbereich
• Berechtigungen
• artifacts
• include
• resources
• sync
• targets

bundle

Eine Paketkonfigurationsdatei darf nur eine bundle-Zuordnung auf oberster Ebene enthalten, die den Inhalten des Pakets und den Azure Databricks-Arbeitsbereichseinstellungen zugeordnet ist.

Diese bundle-Zuordnung muss eine name-Zuordnung enthalten, die einen programmgesteuerten (oder logischen) Namen für das Paket angibt. Im folgenden Beispiel wird ein Paket mit dem programmgesteuerten (oder logischen) Namen hello-bundle deklariert.

bundle:
  name: hello-bundle

Eine bundle-Zuordnung kann auch ein untergeordnetes Element eines oder mehrerer Ziele in der Zuordnung von Zielen der obersten Ebene sein. Jede dieser untergeordneten bundle-Zuordnungen gibt alle nicht standardmäßigen Überschreibungen auf Zielebene an. Der name-Wert der bundle-Zuordnung auf oberster Ebene kann jedoch nicht auf Zielebene überschrieben werden.

compute_id

Die bundle-Zuordnung kann über eine untergeordnete compute_id-Zuordnung verfügen. Mit dieser Zuordnung können Sie die ID eines Clusters angeben, der als Überschreibung für alle an anderer Stelle in der Paketkonfigurationsdatei definierten Cluster verwendet werden soll. Diese Überschreibung ist für reine Entwicklungsszenarien vor der Produktion vorgesehen. Die compute_id-Zuordnung funktioniert nur für das Ziel, dessen mode-Zuordnung auf development festgelegt ist. Weitere Informationen zur compute_id-Zuordnung finden Sie unter Zielzuordnung.

git

Sie können Git-Versionsverwaltungsdetails abrufen und überschreiben, die Ihrem Paket zugeordnet sind. Dies ist nützlich, um Ihre bereitgestellten Ressourcen zu kommentieren. Sie können beispielsweise die Ursprungs-URL Ihres Repositorys in die Beschreibung eines von Ihnen bereitgestellten Machine Learning-Modells einschließen.

Wenn Sie einen bundle-Befehl wie validate, deploy oder run ausführen, füllt der bundle-Befehl die Konfigurationsstruktur des Befehls mit den folgenden Standardeinstellungen auf:

• bundle.git.origin_url, die die Ursprungs-URL des Repositorys darstellt. Dies ist der gleiche Wert, den Sie erhalten würden, wenn Sie den Befehl git config --get remote.origin.url aus Ihrem geklonten Repository ausführen würden. Sie können Ersetzungen verwenden, um auf diesen Wert mit Ihren Paketkonfigurationsdateien zu verweisen, wie ${bundle.git.origin_url}.
• bundle.git.branch, der den aktuellen Branch innerhalb des Repositorys darstellt. Dies ist der gleiche Wert, den Sie erhalten würden, wenn Sie den Befehl git branch --show-current aus Ihrem geklonten Repository ausführen würden. Sie können Ersetzungen verwenden, um auf diesen Wert mit Ihren Paketkonfigurationsdateien zu verweisen, wie ${bundle.git.branch}.
• bundle.git.commit, der den HEAD-Commit innerhalb des Repositorys darstellt. Dies ist der gleiche Wert, den Sie erhalten würden, wenn Sie den Befehl git rev-parse HEAD aus Ihrem geklonten Repository ausführen würden. Sie können Ersetzungen verwenden, um auf diesen Wert mit Ihren Paketkonfigurationsdateien zu verweisen, wie ${bundle.git.commit}.

Zum Abrufen oder Überschreiben von Git-Einstellungen muss sich Ihr Bundle in einem Verzeichnis befinden, das einem Git-Repository zugeordnet ist, z. B. einem lokalen Verzeichnis, das durch Ausführen des git clone-Befehls initialisiert wird. Wenn das Verzeichnis nicht einem Git-Repository zugeordnet ist, sind diese Git-Einstellungen leer.

Sie können die Einstellungen origin_url und branch in der git-Zuordnung Ihrer bundle-Zuordnung auf oberster Ebene bei Bedarf wie folgt überschreiben:

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

databricks_cli_version

Die bundle-Zuordnung kann eine databricks_cli_version-Zuordnung enthalten, die die für das Paket erforderliche Databricks CLI-Version einschränkt. Dies kann Probleme verhindern, die durch die Verwendung von Zuordnungen verursacht werden, die in einer bestimmten Version der Databricks CLI nicht unterstützt werden.

Die Databricks CLI-Version folgt der semantischen Versionsverwaltung, und die databricks_cli_version-Zuordnung unterstützt die Angabe von Versionseinschränkungen. Wenn sich der aktuelle Wert von databricks --version nicht innerhalb der Grenzen befindet, die in der databricks_cli_version-Zuordnung des Pakets angegeben sind, tritt ein Fehler auf, wenn databricks bundle validate im Paket ausgeführt wird. Die folgenden Beispiele veranschaulichen allgemeine Syntax zur Versionseinschränkung:

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

variables

Die Paketeinstellungsdatei kann eine variables-Zuordnung auf oberster Ebene enthalten, um die zu verwendenden Variableneinstellungen anzugeben. Weitere Informationen finden Sie unter Benutzerdefinierte Variablen.

workspace

Die Paketkonfigurationsdatei darf nur eine workspace-Zuordnung auf oberster Ebene enthalten, um alle nicht standardmäßigen Azure Databricks-Arbeitsbereichseinstellungen anzugeben, die verwendet werden sollen.

Diese workspace-Zuordnung kann eine root_path-Zuordnung enthalten, um einen nicht standardmäßigen Stammpfad anzugeben, der innerhalb des Arbeitsbereichs sowohl für Bereitstellungen als auch für Workflowausführungen verwendet werden soll, z. B.:

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

Standardmäßig verwendet die Databricks CLI für root_path den Standardpfad von /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, der Ersetzungen verwendet.

Diese workspace-Zuordnung kann auch eine artifact_path-Zuordnung enthalten, um einen nicht standardmäßigen Artefaktpfad anzugeben, der innerhalb des Arbeitsbereichs sowohl für Bereitstellungen als auch für Workflowausführungen verwendet werden soll, z. B.:

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

Standardmäßig verwendet die Databricks CLI für artifact_path den Standardpfad von ${workspace.root}/artifacts, der Ersetzungen verwendet.

.. Hinweis: Die artifact_path-Zuordnung unterstützt keine Databricks File System (DBFS)-Pfade.

Diese workspace-Zuordnung kann auch eine file_path-Zuordnung enthalten, um einen nicht standardmäßigen Dateipfad anzugeben, der innerhalb des Arbeitsbereichs sowohl für Bereitstellungen als auch für Workflowausführungen verwendet werden soll, z. B.:

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

Standardmäßig verwendet die Databricks CLI für file_path den Standardpfad von ${workspace.root}/files, der Ersetzungen verwendet.

Die state_path-Zuordnung ist standardmäßig auf den Standardpfad von ${workspace.root}/state und stellt den Pfad innerhalb Ihres Arbeitsbereichs dar, um Terraform-Statusinformationen zu Bereitstellungen zu speichern.

Die workspace-Zuordnung kann auch die folgenden optionalen Zuordnungen enthalten, um den zu verwendenden Azure Databricks-Authentifizierungsmechanismus anzugeben. Wenn sie innerhalb dieser workspace-Zuordnung nicht angegeben werden, müssen sie in einer workspace-Zuordnung als untergeordnetes Element eines oder mehrerer Ziele in der Zuordnung der Ziele auf oberster Ebene angegeben werden.

Wichtig

Sie müssen Werte für die folgenden workspace-Zuordnungen für die Azure Databricks-Authentifizierung hartcodieren. Zum Beispiel können Sie keine benutzerdefinierten Variablen für die Werte dieser Zuordnungen mithilfe der ${var.*}-Syntax angeben.

• Die profile-Zuordnung gibt (oder die Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI geben) den Namen eines Konfigurationsprofils an, das mit diesem Arbeitsbereich für die Azure Databricks-Authentifizierung verwendet werden soll. Dieses Konfigurationsprofil wird dem Profil zugeordnet, das Sie beim Einrichten der Databricks CLI erstellt haben.

  Hinweis

  Databricks empfiehlt, die host-Zuordnung (oder die Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) anstelle der profile-Zuordnung zu verwenden, da diese Ihre Bündelkonfigurationsdateien portierbarer macht. Durch Festlegen der host-Zuordnung wird die Databricks CLI angewiesen, ein übereinstimmende Profil in Ihrer .databrickscfg-Datei zu suchen und dann die Felder dieses Profils zu verwenden, um zu bestimmen, welcher Databricks-Authentifizierungstyp verwendet werden soll. Wenn mehrere Profile mit einem übereinstimmenden host-Feld in Ihrer .databrickscfg-Datei vorhanden sind, dann müssen Sie die profile-Zuordnung (oder die --profile- oder -p-Befehlszeilenoptionen) verwenden, um die Databricks-CLI anzuweisen, welches Profil verwendet werden soll. Ein Beispiel finden Sie in der prod-Zieldeklaration in den Beispielen.

• Die host-Zuordnung gibt die URL für Ihren Azure Databricks-Arbeitsbereich an. Weitere Informationen finden Sie unter Arbeitsbereichsspezifische URL.

• Für die OAuth-Computer-zu-Computer-Authentifizierung (M2M) wird die client_id-Zuordnung verwendet. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariable DATABRICKS_CLIENT_ID festlegen. Alternativ können Sie ein Konfigurationsprofil mit dem client_id-Wert erstellen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben. OAuth-Computer-zu-Computer-Authentifizierung (M2M)

  Hinweis

  Sie können keinen Wert für das Azure Databricks-OAuth-Geheimnis in der Bündelkonfigurationsdatei angeben. Legen Sie stattdessen die lokale Umgebungsvariable DATABRICKS_CLIENT_SECRET fest. Alternativ können Sie dem Konfigurationsprofil den client_secret-Wert hinzufügen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben.

• Für die Azure CLI-Authentifizierung wird die azure_workspace_resource_id-Zuordnung verwendet. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariable DATABRICKS_AZURE_RESOURCE_ID festlegen. Alternativ können Sie ein Konfigurationsprofil mit dem azure_workspace_resource_id-Wert erstellen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben. Weitere Informationen finden Sie unter Azure CLI-Authentifizierung.

• Für die Authentifizierung des Azure-Clientgeheimnisses mit Dienstprinzipalen werden die Zuordnungen azure_workspace_resource_id, azure_tenant_id und azure_client_id verwendet. Alternativ können Sie diese Werte in den lokalen Umgebungsvariablen DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_ID bzw ARM_CLIENT_ID festlegen. Alternativ können Sie ein Konfigurationsprofil mit den Werten azure_workspace_resource_id, azure_tenant_id und azure_client_id erstellen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben. Siehe Microsoft Entra ID-Dienstprinzipalauthentifizierung.

  Hinweis

  Sie können keinen Wert für den geheimen Azure-Clientschlüssel in der Paketkonfigurationsdatei angeben. Legen Sie stattdessen die lokale Umgebungsvariable ARM_CLIENT_SECRET fest. Alternativ können Sie dem Konfigurationsprofil den azure_client_secret-Wert hinzufügen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben.

• Für die kennwortlose Authentifizierung der von Azure verwalteten Identitäten werden die Zuordnungen azure_use_msi, azure_client_id und azure_workspace_resource_id verwendet. Alternativ können Sie diese Werte in den lokalen Umgebungsvariablen ARM_USE_MSI, ARM_CLIENT_ID bzw DATABRICKS_AZURE_RESOURCE_ID festlegen. Alternativ können Sie ein Konfigurationsprofil mit den Werten azure_use_msi, azure_client_id und azure_workspace_resource_id erstellen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben. Siehe Authentifizierung von von Azure verwalteten Identitäten.

• Die azure_environment-Zuordnung gibt den Azure-Umgebungstyp (z. B. Öffentlich, UsGov, China und Deutschland) für eine bestimmte Gruppe von API-Endpunkten an. Der Standardwert ist PUBLIC. Alternativ können Sie diesen Wert in der lokalen Umgebungsvariable ARM_ENVIRONMENT festlegen. Alternativ können Sie dem Konfigurationsprofil den azure_environment-Wert hinzufügen und dann den Namen des Profils mit der profile-Zuordnung (oder mithilfe der Optionen --profile oder -p beim Ausführen der Befehle „bundle validate“, „bundle deploy“, „bundle run“ und „bundle destroy“ mit der Databricks-CLI) angeben.

• Die azure_login_app_id-Zuordnung ist nicht betriebsbereit und für die interne Verwendung reserviert.

• Die auth_type-Zuordnung gibt den zu verwendenden Azure Databricks-Authentifizierungstyp an, insbesondere in Fällen, in denen die Databricks CLI einen unerwarteten Authentifizierungstyp ableiten soll. Weitere Informationen finden Sie unter Feld für Authentifizierungstyp.

Berechtigungen

Die permissions-Zuordnung auf oberster Ebene gibt eine oder mehrere Berechtigungsstufen an, die auf alle im Paket definierten Ressourcen angewendet werden sollen. Wenn Sie Berechtigungen auf eine bestimmte Ressource anwenden möchten, lesen Sie Definieren von Berechtigungen für eine bestimmte Ressource.

Zulässige Berechtigungsstufen auf oberster Ebene sind CAN_VIEW, CAN_MANAGE und CAN_RUN.

Im folgenden Beispiel in einer Paketkonfigurationsdatei werden Berechtigungsstufen für einen Benutzer/eine Benutzerin, eine Gruppe und einen Dienstprinzipal definiert. Diese Stufen werden auf alle Aufträge, Pipelines, Experimente und Modelle angewendet, die in resources im Paket definiert sind:

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

artifacts

Die artifacts-Zuordnung auf oberster Ebene gibt ein oder mehrere Artefakte an, die automatisch während Paketbereitstellungen erstellt werden und später in Paketausführungen verwendet werden können. Jedes untergeordnete Artefakt unterstützt die folgenden Zuordnungen:

• type ist erforderlich. Um vor der Bereitstellung eine Python-Wheel-Datei zu erstellen, muss diese Zuordnung auf whl festgelegt werden.
• path ist ein optionaler relativer Pfad vom Speicherort der Paketkonfigurationsdatei zum Speicherort der setup.py-Datei für die Python-Wheel-Datei. Wenn path nicht enthalten ist, versucht die Databricks CLI, die setup.py-Datei der Python-Wheel-Datei im Stammverzeichnis des Pakets zu finden.
• files ist eine optionale Zuordnung, die eine untergeordnete source-Zuordnung enthält, mit der Sie nicht standardmäßige Speicherorte für komplexe Buildanweisungen angeben können. Speicherorte werden als relative Pfade vom Speicherort der Paketkonfigurationsdatei aus angegeben.
• build ist ein optionaler Satz nicht standardmäßiger Buildbefehle, die Sie vor der Bereitstellung lokal ausführen möchten. Bei Python-Wheel-Builds geht die Databricks CLI davon aus, dass sie eine lokale Installation des Python-wheel-Pakets zum Ausführen von Builds finden kann, und führt den Befehl python setup.py bdist_wheel standardmäßig während jeder Paketbereitstellung aus. Um mehrere Buildbefehle anzugeben, trennen Sie jeden Befehl durch doppelte kaufmännische Und-Zeichen (&&).

Weitere Informationen, einschließlich eines Beispielpakets, das artifacts verwendet, finden Sie unter Entwickeln einer Python-Wheel-Datei mit Databricks-Ressourcenpaketen.

Tipp

Sie können die Einstellungen für Artefakte in Paketen definieren, kombinieren und überschreiben, indem Sie die unter Dynamisches Definieren von Artefakteinstellungen in Databricks-Ressourcenpaketen beschriebenen Techniken verwenden.

include

Das include-Array gibt eine Liste der Pfad-Globs an, die Konfigurationsdateien enthalten, die in das Paket eingeschlossen werden sollen. Diese Pfadglobs sind relativ zum Speicherort der Paketkonfigurationsdatei, in der die Pfadglobs angegeben sind.

Die Databricks-CLI enthält keine Konfigurationsdateien standardmäßig innerhalb des Bündels. Sie müssen das include-Array verwenden, um alle Konfigurationsdateien anzugeben, die nicht in die databricks.yml-Datei selbst eingeschlossen werden sollen.

Dieses include-Array kann nur als Zuordnung auf oberster Ebene erscheinen.

Das folgende Beispiel in einer Paketkonfigurationsdatei enthält die drei angegebenen Konfigurationsdateien. Diese Dateien befinden sich im selben Verzeichnis wie die Paketkonfigurationsdatei:

include:
  - "bundle.artifacts.yml"
  - "bundle.resources.yml"
  - "bundle.targets.yml"

Das folgende Beispiel in einer Paketkonfigurationsdatei enthält alle Dateien mit Dateinamen, die mit bundle beginnen und mit .yml enden. Diese Dateien befinden sich im selben Verzeichnis wie die Paketkonfigurationsdatei:

include:
  - "bundle*.yml"

resources

Das resources-Mapping gibt Informationen zu den Azure Databricks-Ressourcen an, die vom Bundle verwendet werden.

Dieses resources-Mapping kann als Mapping auf oberster Ebene oder als untergeordnetes Element eines oder mehrerer Ziele im Mapping von Zielen auf oberster Ebene angezeigt und null oder einen der unterstützten Ressourcentypen enthalten. Jedes Ressourcentypmapping enthält eine oder mehrere einzelne Ressourcendeklarationen, die jeweils einen eindeutigen Namen haben müssen. Diese einzelnen Ressourcendeklarationen verwenden die Anforderungsnutzlast des Erstellungsvorgangs für das entsprechende Objekt, ausgedrückt in YAML, um die Ressource zu definieren. Die unterstützten Eigenschaften für eine Ressource sind die unterstützten Felder des entsprechenden Objekts.

Die Anforderungsnutzlasten des Erstellungsvorgangs sind in der Referenz zur Databricks-REST-API dokumentiert. Der databricks bundle schema-Befehl gibt alle unterstützten Objektschemas zurück. Darüber hinaus gibt der databricks bundle validate-Befehl Warnungen zurück, wenn unbekannte Ressourceneigenschaften in Bundlekonfigurationsdateien gefunden werden.

In der folgenden Tabelle sind unterstützte Ressourcentypen für Bundles und Links zu Dokumentationen zu den entsprechenden Nutzlasten aufgeführt.

Ressourcentyp	Ressourcenmappings
jobs	Auftragsmappings: POST /api/2.1/jobs/create Weitere Informationen finden Sie unter Auftragsaufgabentypen und Außerkraftsetzung neuer Auftragsclustereinstellungen.
pipelines	Pipelinemappings: POST /api/2.0/pipelines
experiments	Experimentmappings: POST /api/2.0/mlflow/experiments/create
models	Modellmappings: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoints	Endpunktmapping der Modellbereitstellung: POST /api/2.0/serving-endpoints
registered_models (Unity Catalog)	Unity Catalog-Modellmappings: POST /api/2.1/unity-catalog/models

Alle Pfade zu Ordnern und Dateien, auf die von Ressourcendeklarationen verwiesen wird, sind relativ zum Speicherort der Bundlekonfigurationsdatei, in der diese Pfade angegeben sind.

Im folgenden Beispiel wird ein Auftrag mit dem Ressourcenschlüssel hello-job und einer Pipeline mit dem Ressourcenschlüssel hello-pipeline deklariert:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

sync

Das sync-Array gibt eine Liste von Datei- oder Pfad-Globs an, die in Bündelbereitstellungen eingeschlossen oder von Bündelbereitstellungen ausgeschlossen werden sollen, abhängig von den folgenden Regeln:

• Basierend auf einer beliebigen Liste von Datei- und Pfad-Globs in einer .gitignore-Datei im Stammverzeichnis des Pakets kann die include-Zuordnung eine Liste von Datei-Globs, Pfad-Globs oder beidem enthalten, relativ zum Stamm des Pakets, die explizit eingeschlossen werden sollen.
• Basierend auf einer beliebigen Liste von Datei- und Pfad-Globs in einer .gitignore-Datei im Stammverzeichnis des Pakets sowie der Liste der Datei- und Pfad-Globs in der include-Zuordnung kann die exclude-Zuordnung eine Liste von Datei-Globs, Pfad-Globs oder beidem enthalten, relativ zum Stamm des Pakets, die explizit ausgeschlossen werden sollen.

Alle Pfade zu angegebenen Ordnern und Dateien sind relativ zum Speicherort der Paketkonfigurationsdatei, in der diese Pfade angegeben werden.

Die Syntax für include Datei exclude- und Pfadmuster folgt der Standardmustersyntax .gitignore. Siehe gitignore Musterformat.

Beispielsweise, wenn die folgende .gitignore-Datei die folgenden Einträge enthält:

.databricks
my_package/dist

Außerdem enthält die Paketkonfigurationsdatei die folgende include-Zuordnung:

sync:
  include:
    - my_package/dist/*.whl

Dann sind alle Dateien im my_package/dist-Ordner mit der Dateierweiterung *.whl enthalten. Alle anderen Dateien im my_package/dist-Ordner sind nicht enthalten.

Wenn allerdings die Paketkonfigurationsdatei auch die folgende exclude-Zuordnung enthält:

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

Dann sind alle Dateien im my_package/dist-Ordner mit der Dateierweiterung *.whl enthalten, mit Ausnahme der Datei namens delete-me.whl. Alle anderen Dateien im my_package/dist-Ordner sind ebenfalls nicht enthalten.

Das sync Array kann auch in der targets Zuordnung für ein bestimmtes Ziel deklariert werden. Alle in einem Ziel deklarierte sync-Arrays werden mit allen sync-Arraydeklarationen auf oberster Ebene zusammengeführt. Wenn Sie beispielsweise mit dem vorherigen Beispiel fortfahren, wird die folgende include-Zuordnung auf der targets-Ebene mit der include-Zuordnung im sync-Array auf oberster Ebene zusammengeführt:

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

Wenn Sie databricks bundle validate --output json ausführen, sieht der relevante Teil des resultierenden Graphs wie folgt aus:

"sync": {
  "include": [
    "my_package/dist/*.whl",
    "my_package/dist/delete-me.whl"
  ],
  "exclude": [
    "my_package/dist/delete-me.whl"
  ]
}

targets

Die targets-Zuordnung gibt einen oder mehrere Kontexte an, in denen Azure Databricks-Workflows ausgeführt werden sollen. Jedes Ziel ist eine eindeutige Sammlung von Artefakten, Azure Databricks-Arbeitsbereichseinstellungen und Azure Databricks-Auftrags- oder Pipelinedetails.

Diese targets-Zuordnung ist optional, wird aber dringend empfohlen. Wenn sie angegeben ist, kann sie nur als Zuordnung auf oberster Ebene angezeigt werden. Wenn die targets-Zuordnung nicht angegeben wird, werden immer die Einstellungen in den Arbeitsbereich-, Artefakte- und Ressourcen-Zuordnungen der obersten Ebene verwendet.

Die targets-Zuordnung besteht aus mindestens einer Zielzuordnung, die jeweils über einen eindeutigen programmgesteuerten (oder logischen) Namen verfügen muss.

Wenn eine Zielzuordnung keine workspace, artifacts oder resources untergeordneten Zuordnungen angibt, verwendet dieses Ziel die Einstellungen in den Zuordnungen workspace, artifacts und resources der obersten Ebene.

Wenn eine Zielzuordnung eine workspace-, artifacts oder resources-Zuordnung angibt und auch eine workspace-, artifacts- oder resources-Zuordnung auf oberster Ebene vorhanden ist, werden alle in Konflikt stehenden Einstellungen von den Einstellungen innerhalb des Ziels überschrieben.

Ein Ziel kann auch die Werte aller Variablen der obersten Ebene überschreiben.

Um anzugeben, dass ein Ziel das Standardziel ist, sofern nicht anders angegeben, fügen Sie die default-Zuordnung hinzu, und legen Sie sie auf true fest. Dieses Ziel mit dem Namen dev ist beispielsweise das Standardziel:

targets:
  dev:
    default: true

Um anzugeben, dass ein Ziel als Entwicklungsziel behandelt wird, fügen Sie die mode-Zuordnung hinzu, die auf development festgelegt ist. Um anzugeben, dass ein Ziel als Produktionsziel behandelt wird, fügen Sie die mode-Zuordnung hinzu, die auf production festgelegt ist. Beispielsweise wird dieses Ziel mit dem Namen prod als Produktionsziel behandelt:

targets:
  prod:
    mode: production

Die Angabe von mode stellt eine Auflistung der entsprechenden Standardverhaltensweisen für Präproduktions- und Produktionsworkflows bereit. Weitere Informationen finden Sie unter Bereitstellungsmodi für Databricks-Ressourcenpakete. Darüber hinaus können Sie für jedes Ziel run_as angeben, wie in Angeben einer Ausführungsidentität für einen Databricks Asset Bundles-Workflow beschrieben.

Im folgenden Beispiel werden zwei Ziele deklariert. Das erste Ziel hat den programmgesteuerten (oder logischen) Namen dev und ist das Standardziel. Das zweite Ziel hat den programmgesteuerten (oder logischen) Namen prod und ist nicht das Standardziel. Dieses zweite Ziel verwendet ein Azure Databricks-Verbindungsprofil namens PROD für die Authentifizierung:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

Führen Sie die folgenden Befehle aus, um Jobs oder Pipelines innerhalb des dev-Ziels zu überprüfen, bereitzustellen und auszuführen:

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run <job-or-pipeline-programmatic-name>

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev <job-or-pipeline-programmatic-name>

Führen Sie stattdessen die folgenden Befehle aus, um diesen Auftrag innerhalb des prod-Ziels zu überprüfen, bereitzustellen und auszuführen:

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod <job-or-pipeline-programmatic-name>

Custom variables

Sie können benutzerdefinierte Variablen verwenden, um Ihre Paketkonfigurationsdatei modularer und wiederverwendbarer zu gestalten. Beispielsweise können Sie eine Variable deklarieren, welche die ID eines vorhandenen Clusters darstellt, und dann den Wert dieser Variablen in andere Cluster-IDs für verschiedene Workflowausführungen an mehreren Zielen ändern, ohne den ursprünglichen Code Ihrer Paketkonfigurationsdateien zu ändern.

Sie können eine oder mehrere Variable in den Bündelkonfigurationsdateien innerhalb der variables-Zuordnung deklarieren. Für jede Variable können Sie eine optionale Beschreibung, einen Standardwert oder einen Lookup festlegen, um einen ID-Wert abzurufen, und zwar in diesem Format:

variables:
  <variable-name>:
    description: <optional-description>
    default: <optional-default-value>
    lookup:
      <optional-object-type>: <optional-object-name>

So deklarieren Sie beispielsweise eine Variable namens my_cluster_id mit dem Standardwert 1234-567890-abcde123 und eine Variable namens my_notebook_path mit dem Standardwert ./hello.py:

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 für eine Variable keinen default-Wert angeben, müssen Sie den Wert später an der Befehlszeile, über eine Umgebungsvariable oder an anderer Stelle in Ihren Paketkonfigurationsdateien angeben. Diese Ansätze werden weiter unten in diesem Abschnitt beschrieben.

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.

Verwenden Sie Ersetzungen, um auf Ihre benutzerdefinierten Variablen in Ihren Paketkonfigurationsdateien zu verweisen. Verwenden Sie für Variablen das Format ${var.<variable_name>}. So verweisen Sie beispielsweise auf Variablen mit dem Namen 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
  

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:

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

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}

Substitutions

Sie können Ersetzungen verwenden, um Ihre Paketkonfigurationsdateien modularer und wiederverwendbarer zu gestalten.

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 Übergeben des Kontexts zu Auftragsausführungen in Auftragsaufgaben.

Wenn Sie beispielsweise den bundle validate --output json-Befehl ausführen, wird möglicherweise ein Diagramm wie dieses angezeigt (die Auslassungspunkte geben aus Gründen der Kürze den weggelassenen Inhalt an):

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

Im vorherigen Beispiel können Sie auf den Wert someone@example.com in Ihrer Paketkonfigurationsdatei mit der Ersetzung ${workspace.current_user.userName} verweisen.

In ähnlicher Weise werden die folgenden Ersetzungen verwendet:

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

In einer Paketkonfigurationsdatei wie der folgenden (Auslassungspunkte weisen auf Inhalte hin, die der Übersichtlichkeit halber weggelassen wurden):

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Würde in das folgende Diagramm aufgelöst, wenn Sie den bundle validate --output json-Befehl ausführen (die Auslassungspunkte geben aus Gründen der Kürze den ausgelassenen Inhalt an):

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "profile": "DEFAULT",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

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}