bundle-Befehlsgruppe

Hinweis

Diese Informationen gelten für Databricks CLI-Versionen 0.205 und höher. Die Databricks CLI befindet sich in der öffentlichen Vorschau.

Die Verwendung von Databricks CLI unterliegt der Datenbricks-Lizenz - und Databricks-Datenschutzerklärung, einschließlich der Bestimmungen zu Nutzungsdaten.

Die bundle-Befehlsgruppe der Databricks CLI ermöglicht Ihnen die programmgesteuerte Überprüfung, Bereitstellung und Ausführung von Azure Databricks-Workflows wie Azure Databricks-Aufträge, Delta Live Tables-Pipelines und MLOps Stacks. Weitere Informationen finden Sie unter Was sind Databricks-Ressourcenbundles?.

Sie führen bundle-Befehle aus, indem Sie sie an databricks bundle anfügen. Führen Sie databricks bundle -h aus, um Hilfe zum bundle-Befehl anzuzeigen.

Erstellen eines Bündels auf der Grundlage einer Projektvorlage

Führen Sie den bundle init Befehl wie folgt aus, um ein Databricks Asset Bundle-Paket mit der Standardvorlage "Databricks Asset Bundle" für Python zu erstellen, und beantworten Sie dann die Eingabeaufforderungen auf dem Bildschirm:

databricks bundle init

Um ein Databricks-Objektbundle mit einer benutzerdefinierten Databricks Asset Bundle-Vorlage zu erstellen, führen Sie den bundle init Befehl wie folgt aus:

databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"

Weitere Informationen:

• Vorlagen für Databricks-Ressourcenpakete
• Entwickeln eines Auftrags in Azure Databricks mithilfe von Databricks-Ressourcen-Bundles
• Entwickeln von Delta Live Tables-Pipelines mit Databricks-Ressourcenbundles
• Databricks-Ressourcenbundles für MLOps Stacks

Anzeigen des Bündelkonfigurationsschemas

Führen Sie den bundle schema Befehl wie folgt aus, um das Paketkonfigurationsschema anzuzeigen:

databricks bundle schema

Wenn Sie das Konfigurationsschema des Databricks-Ressourcenbundles als JSON-Datei ausgeben möchten, können Sie den bundle schema-Befehl ausführen und die Ausgabe an eine JSON-Datei umleiten. Gehen Sie beispielsweise wie folgt vor, um eine Datei namens bundle_config_schema.json im aktuellen Verzeichnis zu erstellen:

databricks bundle schema > bundle_config_schema.json

Überprüfen eines Bündels

Führen Sie den bundle validate- Befehl im Stammverzeichnis des Bundle-Projekts aus, um zu überprüfen, ob Ihre Bundle-Konfigurationsdateien syntaktisch korrekt sind:

databricks bundle validate

Standardmäßig gibt dieser Befehl eine Zusammenfassung der Paketidentität zurück:

Name: MyBundle
Target: dev
Workspace:
  Host: https://my-host.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/MyBundle/dev

Validation OK!

Hinweis

Der bundle validate-Befehl gibt Warnungen aus, wenn Ressourceneigenschaften in den Paketkonfigurationsdateien definiert sind, die im Schema des entsprechenden Objekts nicht gefunden werden.

Wenn Sie nur eine Zusammenfassung der Identität und Ressourcen des Bundles ausgeben möchten, verwenden Sie die Bundlezusammenfassung.

Synchronisieren der Struktur eines Bündels mit einem Arbeitsbereich

Verwenden Sie den Befehl bundle sync, um eine unidirektionale Synchronisierung der Dateiänderungen eines Bündels innerhalb eines lokalen Dateisystemverzeichnisses mit einem Verzeichnis innerhalb eines Azure Databricks-Remotearbeitsbereichs durchzuführen.

Hinweis

Mit bundle sync-Befehlen können Dateiänderungen aus einem Verzeichnis innerhalb eines Azure Databricks-Remotearbeitsbereichs nicht mit einem Verzeichnis innerhalb eines lokalen Dateisystems synchronisiert werden.

databricks bundle sync-Befehle funktionieren auf die gleiche Weise wie databricks sync-Befehle und werden zur Verbesserung der Produktivität bereitgestellt. Informationen zur Befehlssyntax finden Sie unter Synchronisierungsbefehlsgruppe.

Generieren einer Bündelkonfigurationsdatei

Sie können den bundle generate Befehl verwenden, um die Ressourcenkonfiguration für einen Auftrag, eine Pipeline oder ein Dashboard zu generieren, die bereits in Ihrem Databricks-Arbeitsbereich vorhanden sind. Dieser Befehl generiert eine *.yml Datei für den Auftrag, die Pipeline oder das resources Dashboard im Ordner des Bündelprojekts und lädt auch alle Dateien herunter, z. B. Notizbücher, auf die in der Konfiguration verwiesen wird.

Erstellen von Auftrags- oder Pipelinekonfigurationen

Wichtig

Der bundle generate-Befehl wird aus Benutzerfreundlichkeit bereitgestellt, um die Ressourcenkonfiguration automatisch zu generieren. Wenn diese Auftrags- oder Pipelinekonfiguration jedoch im Bundle enthalten und bereitgestellt wird, wird eine neue Ressource erstellt und die vorhandene Ressource nur aktualisiert, wenn bundle deployment bind sie zuerst verwendet wurde. Siehe Binden von Bundleressourcen.

Führen Sie den bundle generate Befehl wie folgt aus, um eine Konfiguration für einen Auftrag oder eine Pipeline zu generieren:

databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]

Hinweis

Derzeit werden nur Aufträge mit Notebookaufgaben von diesem Befehl unterstützt.

Der folgende Befehl generiert z. B. eine neue hello_job.yml-Datei im resources-Paketprojektordner, der das folgende YAML enthält, und lädt simple_notebook.py in den src-Projektordner herunter.

databricks bundle generate job --existing-job-id 6565621249

# This is the contents of the resulting hello_job.yml file.
resources:
  jobs:
    6565621249:
      name: Hello Job
      format: MULTI_TASK
      tasks:
        - task_key: run_notebook
          existing_cluster_id: 0704-xxxxxx-yyyyyyy
          notebook_task:
            notebook_path: ./src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

Dashboardkonfiguration generieren

Führen Sie bundle generatezum Generieren der Konfiguration für ein vorhandenes Dashboard im Arbeitsbereich die ID oder den Arbeitsbereichspfad für das Dashboard aus:

databricks bundle generate dashboard --existing-id [dashboard-id]

databricks bundle generate dashboard --existing-path [dashboard-workspace-path]

Sie können den Arbeitsbereichspfad für ein Dashboard über die Arbeitsbereichs-UI kopieren.

Der folgende Befehl generiert z. B. eine neue baby_gender_by_county.dashboard.yml Datei im resources Paketprojektordner, der das folgende YAML enthält, und lädt die baby_gender_by_county.lvdash.json Datei in den src Projektordner herunter.

databricks bundle generate dashboard --existing-path "/Workspace/Users/someone@example.com/baby_gender_by_county.lvdash.json"

# This is the contents of the resulting baby_gender_by_county.dashboard.yml file.
resources:
  dashboards:
    baby_gender_by_county:
      display_name: "Baby gender by county"
      warehouse_id: aae11o8e6fe9zz79
      file_path: ../src/baby_gender_by_county.lvdash.json

Tipp

Wenn Sie die .lvdash.json Datei aktualisieren möchten, nachdem Sie bereits ein Dashboard bereitgestellt haben, verwenden Sie die --resource Option, wenn Sie diese bundle generate dashboard Datei für die vorhandene Dashboardressource generieren. Um Updates für ein Dashboard kontinuierlich abzurufen und abzurufen, verwenden Sie die --force optionen --watch .

Binden von Bündelressourcen

Mit dem bundle deployment bind-Befehl können Sie in Paketen definierte Aufträge und Pipelines mit vorhandenen Aufträgen und Pipelines im Azure Databricks-Arbeitsbereich verknüpfen, sodass sie von Databricks-Ressourcenpaketen verwaltet werden. Wenn Sie eine Ressource binden, werden vorhandene Azure Databricks-Ressourcen im Arbeitsbereich basierend auf der Konfiguration aktualisiert, die in dem Bündel definiert ist, an das sie nach dem nächsten bundle deploy gebunden ist.

Tipp

Es ist ratsam, den Bundle im Arbeitsbereich vor dem Ausführen der Bindung zu bestätigen.

databricks bundle deployment bind [resource-key] [resource-id]

Der folgenden Befehl bindet die Ressource hello_job beispielsweise an das Remote-Gegenstück im Arbeitsbereich. Der Befehl gibt einen Diff aus und ermöglicht es Ihnen, die Ressourcenbindung zu verweigern, aber wenn bestätigt, werden alle Aktualisierungen der Auftragsdefinition im Bündel auf den entsprechenden Remoteauftrag angewendet, wenn das Bündel das nächste Mal bereitgestellt wird.

databricks bundle deployment bind hello_job 6565621249

Verwenden Sie bundle deployment unbind, wenn Sie die Verknüpfung zwischen dem Auftrag oder der Pipeline in einem Paket und dessen Remotegegenstück in einem Arbeitsbereich entfernen möchten.

databricks bundle deployment unbind [resource-key]

Ausgabe einer Bundlezusammenfassung

Der bundle summary Befehl gibt eine Zusammenfassung der Identität und Ressourcen eines Bundles aus, einschließlich Deep-Links für Ressourcen, sodass Sie einfach zur Ressource im Databricks-Arbeitsbereich navigieren können.

databricks bundle summary

Die folgende Beispielausgabe ist die Zusammenfassung eines Bundles, my_pipeline_bundle das einen Auftrag und eine Pipeline definiert:

Name: my_pipeline_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/my_pipeline/dev
Resources:
  Jobs:
    my_project_job:
      Name: [dev someone] my_project_job
      URL:  https://myworkspace.cloud.databricks.com/jobs/206000809187888?o=6051000018419999
  Pipelines:
    my_project_pipeline:
      Name: [dev someone] my_project_pipeline
      URL:  https://myworkspace.cloud.databricks.com/pipelines/7f559fd5-zztz-47fa-aa5c-c6bf034b4f58?o=6051000018419999

Tipp

Sie können auch zum Navigieren zu einer Ressource im Databricks-Arbeitsbereich verwenden bundle open . Siehe Öffnen einer Bündelressource.

Bereitstellen eines Bündels

Um ein Bündel im Remotearbeitsbereich bereitzustellen, führen Sie den bundle deploy Befehl aus dem Paketprojektstamm aus. Wenn keine Befehlsoptionen angegeben sind, wird das Standardziel verwendet, das in den Bündelkonfigurationsdateien deklariert ist.

databricks bundle deploy

Um das Bundle für ein bestimmtes Ziel bereitzustellen, legen Sie die -t Option (oder --target) zusammen mit dem Namen des Ziels fest, wie in den Bündelkonfigurationsdateien deklariert. Beispielsweise für ein Ziel, das mit dem Namen „dev“ deklariert wird:

databricks bundle deploy -t dev

Ein Bündel kann für mehrere Arbeitsbereiche wie Entwicklung, Staging und Produktionsarbeitsbereiche bereitgestellt werden. Grundsätzlich bestimmt die root_path Eigenschaft die eindeutige Identität eines Bündels, die standardmäßig festgelegt auf ~/.bundle/${bundle.name}/${bundle.target} wird. Daher besteht die Identität eines Bündels standardmäßig aus der Identität des Bereitstellers, dem Namen des Bündels und dem Zielnamen des Bündels. Wenn diese in verschiedenen Bündeln identisch sind, stören sich die Bereitstellung dieser Bündel gegenseitig.

Darüber hinaus verfolgt eine Bündelbereitstellung die Ressourcen, die sie im Zielarbeitsbereich erstellt, anhand ihrer IDs als Zustand, der im Arbeitsbereichsdateisystem gespeichert ist. Ressourcennamen werden nicht verwendet, um zwischen einer Bündelbereitstellung und einer Ressourceninstanz zu korrelieren, also:

• Wenn eine Ressource in der Bündelkonfiguration nicht im Zielarbeitsbereich vorhanden ist, wird sie erstellt.
• Wenn eine Ressource in der Paketkonfiguration im Zielarbeitsbereich vorhanden ist, wird sie im Arbeitsbereich aktualisiert.
• Wenn eine Ressource aus der Bündelkonfiguration entfernt wird, wird sie aus dem Zielarbeitsbereich entfernt, wenn sie zuvor bereitgestellt wurde.
• Die Zuordnung einer Ressource mit einem Bündel kann nur vergessen werden, wenn Sie den Bündelnamen, das Bündelziel oder den Arbeitsbereich ändern. Sie können bundle validate ausführen, um eine Zusammenfassung mit diesen Werten auszugeben.

Ausführen eines Auftrags oder einer Pipeline

Um einen bestimmten Auftrag oder eine bestimmte Pipeline auszuführen, verwenden Sie den bundle run-Befehl. Sie müssen den in den Bündelkonfigurationsdateien deklarierten Ressourcenschlüssel des Auftrags oder die dort deklarierte Pipeline angeben. Standardmäßig wird die in den Bündelkonfigurationsdateien deklarierte Umgebung verwendet. Um beispielsweise einen Auftrag hello_job in der Standardumgebung auszuführen, führen Sie den folgenden Befehl aus:

databricks bundle run hello_job

So führen Sie einen Auftrag mit einem Schlüssel „hello_job“ im Kontext eines Ziels aus, das mit dem Namen „dev“ deklariert wurde:

databricks bundle run -t dev hello_job

Wenn Sie eine Pipelinevalidierung ausführen möchten, verwenden Sie die --validate-only-Option, wie im folgenden Beispiel gezeigt:

databricks bundle run --validate-only my_pipeline

Um Auftragsparameter zu übergeben, verwenden Sie die Option --params gefolgt von kommagetrennten Schlüsselwertpaaren, wobei der Schlüssel der Parametername ist. Beispielsweise legt der folgende Befehl den Parameter mit dem Namen message auf HelloWorld für den Auftrag hello_job fest:

databricks bundle run --params message=HelloWorld hello_job

Hinweis

Sie können Parameter an Auftragsaufgaben übergeben, indem Sie die Auftragsaufgabenoptionen verwenden, aber die --params-Option ist die empfohlene Methode zum Übergeben von Auftragsparametern. Ein Fehler tritt auf, wenn Auftragsparameter für einen Auftrag angegeben werden, für die keine Auftragsparameter definiert sind, oder wenn Vorgangsparameter für einen Auftrag angegeben werden, für den Auftragsparameter definiert sind.

Um eine vorhandene Auftragsausführung oder ein vorhandenes Pipelineupdate abzubrechen und neu zu starten, verwenden Sie die Option --restart:

databricks bundle run --restart hello_job

Öffnen einer Bundleressource

Um zu einer Bündelressource im Arbeitsbereich zu navigieren, führen Sie den bundle open Befehl aus dem Projektstamm des Bundles aus, und geben Sie die zu öffnende Ressource an. Wenn kein Ressourcenschlüssel angegeben ist, gibt dieser Befehl eine Liste der Ressourcen des Bundles aus, aus denen Sie auswählen möchten.

databricks bundle open [resource-key]

Beispielsweise startet der folgende Befehl einen Browser und navigiert zum baby_gender_by_county-Dashboard im Bundle im Databricks-Arbeitsbereich, der für das Bundle konfiguriert ist:

databricks bundle open baby_gender_by_county

Zerstören eines Bündels

Warnung

Durch das Löschen eines Bündels werden die zuvor bereitgestellten Aufträge, Pipelines und Artefakte eines Bundles endgültig gelöscht. Diese Aktion kann nicht rückgängig gemacht werden.

Um zuvor bereitgestellte Aufträge, Pipelines und Artefakte zu löschen, führen Sie den bundle destroy-Befehl aus. Der folgende Befehl löscht alle zuvor bereitgestellten Aufträge, Pipelines und Artefakte, die in den Bündelkonfigurationsdateien definiert sind:

databricks bundle destroy

Hinweis

Die Identität eines Bündels besteht aus dem Bündelnamen, dem Bündelziel und dem Arbeitsbereich. Wenn Sie eines dieser Elemente geändert haben und dann versuchen, ein Bündel vor der Bereitstellung zu zerstören, tritt ein Fehler auf.

Standardmäßig werden Sie aufgefordert, das dauerhafte Löschen der zuvor bereitgestellten Aufträge, Pipelines und Artefakte zu bestätigen. Um diese Eingabeaufforderungen zu überspringen und automatisch dauerhaft zu löschen, fügen Sie dem bundle destroy-Befehl die Option --auto-approve hinzu.