Entwickeln eines Auftrags in Azure Databricks mithilfe von Databricks-Ressourcen-Bundles

Artikel
10/14/2024

Databricks-Ressourcen-Bundle, die auch einfach als Bundles bezeichnet werden, ermöglichen Ihnen die programmgesteuerte Überprüfung, Bereitstellung und Ausführung von Azure Databricks-Ressourcen wie z.B. Aufträge. Weitere Informationen finden Sie unter Was sind Databricks-Ressourcenbundles?

In diesem Artikel wird beschrieben, wie Sie ein Bundle erstellen, um einen Auftrag programmgesteuert zu verwalten. Weitere Informationen finden Sie unter Planen und Orchestrieren von Workflows. In diesen Schritten erstellen Sie das Bundle mithilfe der standardmäßigen Azure Databricks-Bundlevorlage für Python, die aus einem Notebook oder Python-Code besteht, zusammen mit der Definition eines Auftrags für die Ausführung. Anschließend validieren Sie den bereitgestellten Auftrag in Ihrem Azure Databricks-Arbeitsbereich und führen ihn aus.

Tipp

Wenn Sie über vorhandene Jobs verfügen, die mithilfe der Benutzeroberfläche von Azure Databricks-Jobs oder der API erstellt wurden und die Sie in Bundle verschieben möchten, müssen Sie sie als Bundle-Konfigurationsdateien neu erstellen. Dazu empfiehlt Databricks, zunächst ein Bundle mithilfe der nachstehenden Schritte zu erstellen und zu überprüfen, ob das Bundle funktioniert. Anschließend können Sie dem Bundle Auftragsdefinitionen, Notebooks und andere Quellen hinzufügen. Siehe Hinzufügen einer vorhandenen Auftragsdefinition zu einem Bündel.

Anforderungen

Databricks-CLI-Version 0.218.0 oder höher. Führen Sie den Befehl databricks -v aus, um zu überprüfen, welche Version der Databricks-CLI installiert ist. Informationen zum Installieren der Databricks CLI finden Sie unter Installieren oder Aktualisieren der Databricks CLI.
Der Remote-Databricks-Arbeitsbereich muss die Arbeitsbereichsdateien aktiviert haben. Weitere Informationen finden Sie unter Was sind Arbeitsbereichsdateien?.

Erstellen eines Bundles auf der Grundlage einer Projektvorlage

Erstellen Sie zunächst ein Bundle unter Verwendung der Standard-Python-Vorlage für Databricks Asset-Bundles. Informationen zu Projektvorlagen für Bundle finden Sie unter Databricks Asset Bundle-Vorlagen.

Wenn Sie ein Bundle von Grund auf neu erstellen möchten, lesen Sie den Abschnitt Manuelles Erstellen eines Bundles.

Schritt 1: Einrichten der Authentifizierung

In diesem Schritt richten Sie die Authentifizierung zwischen der Databricks CLI auf Ihrem Entwicklungscomputer und Ihrem Azure Databricks-Arbeitsbereich ein. In diesem Artikel wird davon ausgegangen, dass Sie zur Authentifizierung die OAuth-U2M-Authentifizierung (User-to-Machine, Benutzer-zu-Computer) und ein entsprechendes Azure Databricks-Konfigurationsprofil namens DEFAULT verwenden möchten.

Hinweis

Die U2M-Authentifizierung eignet sich für das Testen dieser Schritte in Echtzeit. Bei vollständig automatisierten Workflows empfiehlt Databricks stattdessen die Verwendung der OAuth-M2M-Authentifizierung (Machine-to-Machine, Computer-zu-Computer). Lesen Sie die Anweisungen zur Einrichtung der M2M-Authentifizierung unter Authentifizierung.

Verwenden Sie die Databricks CLI, um die OAuth-Tokenverwaltung lokal zu initiieren, indem Sie den folgenden Befehl für jeden Zielarbeitsbereich ausführen.

Ersetzen Sie <workspace-url> im folgenden Befehl durch Ihre arbeitsbereichsspezifische Azure Databricks-URL, z. B. https://adb-1234567890123456.7.azuredatabricks.net.
```
databricks auth login --host <workspace-url>
```
Die Databricks-CLI fordert Sie auf, die von Ihnen eingegebenen Informationen als Azure Databricks-Konfigurationsprofil zu speichern. Drücken Sie die EINGABETASTE (Enter), um den vorgeschlagenen Profilnamen zu übernehmen, oder geben Sie den Namen eines neuen oder bereits vorhandenen Profils ein. Ist bereits ein Profil mit dem gleichen Namen vorhanden, wird es mit den von Ihnen eingegebenen Informationen überschrieben. Sie können Profile verwenden, um Ihren Authentifizierungskontext schnell über mehrere Arbeitsbereiche hinweg zu wechseln.

Um eine Liste vorhandener Profile abzurufen, führen Sie in der Databricks-CLI den Befehl databricks auth profiles in einem separaten Terminal oder in einer separaten Eingabeaufforderung aus. Um die vorhandenen Einstellungen eines bestimmten Profils anzuzeigen, können Sie den Befehl databricks auth env --profile <profile-name> ausführen.
Führen Sie in Ihrem Webbrowser die Anweisungen auf dem Bildschirm aus, um sich bei Ihrem Azure Databricks-Arbeitsbereich anzumelden.
Führen Sie einen der folgenden Befehle aus, um den aktuellen OAuth-Tokenwert eines Profils und den bevorstehenden Ablaufzeitstempel des Tokens anzuzeigen:
- databricks auth token --host <workspace-url>
- databricks auth token -p <profile-name>
- databricks auth token --host <workspace-url> -p <profile-name>
Wenn Sie über mehrere Profile mit demselben --host-Wert verfügen, müssen Sie möglicherweise die Optionen --host und -p zusammen angeben, damit die Databricks CLI die richtigen übereinstimmenden Informationen des OAuth-Tokens ermitteln kann.

Schritt 2: Initialisieren des Bundles

Initialisieren Sie ein Bundle mit der standardmäßigen Python-Bundle-Projektvorlage.

Verwenden Sie Ihr Terminal oder die Eingabeaufforderung, um zu einem Verzeichnis auf Ihrem lokalen Entwicklungscomputer zu wechseln, welches das generierte Bündel der Vorlage enthält.
Verwenden Sie die Databricks CLI, um den Befehl bundle init auszuführen:
```
databricks bundle init
```
Übernehmen Sie für Template to use den Standardwert default-python, indem Sie Enter drücken.
Lassen Sie für Unique name for this project, den Standardwert von my_project, oder geben Sie einen anderen Wert ein, und drücken Sie dann Enter. Dadurch wird der Name des Stammverzeichnisses für dieses Bündel bestimmt. Dieses Stammverzeichnis wird in Ihrem aktuellen Arbeitsverzeichnis erstellt.
Wählen Sie für Include a stub (sample) notebook yes aus, und drücken Sie Enter.
Wählen Sie für Include a stub (sample) DLT pipeline no aus, und drücken Sie Enter. Dadurch wird die Databricks CLI angewiesen, keine Delta Live Tables-Pipeline in Ihrem Bündel zu definieren.
Wählen Sie für Include a stub (sample) Python package no aus, und drücken Sie Enter. Damit wird die Databricks CLI angewiesen, Ihrem Paket Beispiel-Python-Wheel-Paketdateien und zugehörige Buildanweisungen hinzuzufügen.

Schritt 3: Erkunden des Pakets

Wechseln Sie in das Stammverzeichnis des neu erstellten Bundles, um die von der Vorlage erzeugten Dateien anzuzeigen. Zu den Dateien von besonderem Interesse gehören:

databricks.yml: Diese Datei gibt den programmgesteuerten Namen des Bündels an, enthält einen Verweis auf die Auftragsdefinition und gibt Einstellungen für den Zielarbeitsbereich an.
resources/<project-name>_job.yml: Diese Datei gibt die Auftragseinstellungen an, einschließlich einer Standardnotebookaufgabe.
src/notebook.ipynb: Diese Datei ist ein Beispielnotebook, das beim Ausführen einfach ein RDD initialisiert, das die Zahlen 1 bis 10 enthält.

Für die Anpassung von Jobs entsprechen die Zuordnungen in einer Job-Deklaration dem Anfrage-Payload, ausgedrückt im YAML-Format, der Job-Operation create, wie in POST /api/2.1/jobs/create in der REST-API-Referenz dokumentiert.

Tipp

Sie können die Einstellungen für neue Auftragscluster in Bundles definieren, kombinieren und außer Kraft setzen, indem Sie die unter Außerkraftsetzen von Clustereinstellungen in Databricks-Ressourcenbundles beschriebenen Techniken anwenden.

Schritt 4: Überprüfen der Bundlekonfigurationsdatei des Projekts

In diesem Schritt überprüfen Sie, ob die Bundlekonfiguration gültig ist.

Verwenden Sie im Stammverzeichnis die Databricks CLI, um den bundle validate-Befehl wie folgt auszuführen:
```
databricks bundle validate
```
Wenn eine Zusammenfassung der Bundlekonfiguration zurückgegeben wird, war die Prüfung erfolgreich. Wenn Fehler zurückgegeben werden, müssen Sie sie beheben und dann diesen Schritt wiederholen.

Wenn Sie nach diesem Schritt Änderungen an Ihrem Bundle vornehmen, sollten Sie diesen Schritt wiederholen, um zu überprüfen, ob Ihre Bundlekonfiguration noch gültig ist.

Schritt 5: Bereitstellen des lokalen Projekts im Remotearbeitsbereich

In diesem Schritt stellen Sie die das lokale Notebook in Ihrem Azure Databricks-Remotearbeitsbereich bereit und erstellen dort den Azure Databricks-Auftrag.

Verwenden Sie im Bündelstamm die Databricks CLI, um den bundle deploy-Befehl wie folgt auszuführen:
```
databricks bundle deploy -t dev
```
Überprüfen Sie, ob das lokale Notebook bereitgestellt wurden: Klicken Sie in der Seitenleiste Ihres Azure Databricks-Arbeitsbereichs auf Arbeitsbereich.
Klicken Sie in den Ordner Benutzer ><your-username>> .bundle ><project-name>> dev > files > src. Das Notebook sollte sich in diesem Ordner befinden.
Überprüfen Sie, ob der Auftrag erstellt wurde: Klicken Sie in der Seitenleiste Ihres Azure Databricks-Arbeitsbereichs auf Workflows.
Klicken Sie auf der Registerkarte Aufträge auf [dev <your-username>] <project-name>_job.
Klicken Sie auf die Registerkarte Aufgaben. Es sollte eine Aufgabe vorhanden sein: notebook_task.

Wenn Sie nach diesem Schritt Änderungen an Ihrem Bundle vornehmen, sollten Sie die Schritte 4 bis 5 wiederholen, um zu überprüfen, ob Ihre Bundlekonfiguration noch gültig ist, und dann das Projekt erneut bereitstellen.

Schritt 6: Ausführen des bereitgestellten Projekts

In diesem Schritt lösen Sie einen Lauf des Azure Databricks-Jobs in Ihrem Arbeitsbereich über die Befehlszeile aus.

Verwenden Sie im Stammverzeichnis die Databricks CLI, um den Befehl bundle runwie folgt auszuführen, wobei Sie <project-name> durch den Namen des Projekts aus Schritt 2 ersetzen:
```
databricks bundle run -t dev <project-name>_job
```
Kopieren Sie den Wert von Run URL, der in Ihrem Terminal angezeigt wird, und fügen Sie ihn in Ihren Webbrowser ein, um Ihren Azure Databricks-Arbeitsbereich zu öffnen. Siehe Anzeigen und Ausführen eines mit Databricks Asset Bundle erstellten Auftrags
Klicken Sie auf Ihren Azure Databricks-Arbeitsbereich, nachdem die Auftragsaufgabe erfolgreich abgeschlossen wurde und eine grüne Titelleiste anzeigt, und klicken Sie auf die Auftragsaufgabe, um die Ergebnisse anzuzeigen.

Wenn Sie nach diesem Schritt Änderungen an Ihrem Bundle vornehmen, sollten Sie die Schritte 4 bis 6 wiederholen, um zu überprüfen, ob Ihre Bundlekonfiguration noch gültig ist, das Projekt erneut bereitstellen und dieses Projekt ausführen.

Schritt 7: Bereinigen

In diesem Schritt löschen Sie das bereitgestellte Notebook und den Auftrag aus Ihrem Arbeitsbereich.

Verwenden Sie im Stammverzeichnis die Databricks CLI, um den bundle destroy-Befehl wie folgt auszuführen:
```
databricks bundle destroy -t dev
```
Bestätigen Sie die Anforderung zum Löschen des Auftrags: Wenn Sie aufgefordert werden, die Ressourcen dauerhaft zu löschen, geben Sie y ein, und drücken Sie dann Enter.
Bestätigen Sie die Löschanforderung für das Notebook: Wenn Sie aufgefordert werden, den zuvor bereitgestellten Ordner und alle seine Dateien dauerhaft zu löschen, geben Sie y ein und drücken Sie Enter.
Wenn Sie das Paket auch von Ihrem Entwicklungscomputer löschen möchten, können Sie jetzt das lokale Verzeichnis aus Schritt 2 löschen.

Hinzufügen einer vorhandenen Auftragsdefinition zu einem Bündel

Sie können eine vorhandene Job-Definition als Grundlage verwenden, um einen neuen Job in einer Bundle-Konfigurationsdatei zu definieren. Um eine vorhandene Auftragsdefinition zu erhalten, können Sie sie mithilfe der Benutzeroberfläche manuell abrufen oder sie programmgesteuert mithilfe der Databricks CLI generieren.

Informationen zur Auftragsdefinition in Bundle finden Sie unter Job.

Abrufen einer vorhandenen Auftragsdefinition mithilfe der Benutzeroberfläche

Um die YAML-Darstellung einer bestehenden Job-Definition aus der Azure Databricks Workspace UI zu erhalten:

Klicken Sie in der Seitenleiste Ihres Azure Databricks-Arbeitsbereichs auf Workflows.
Klicken Sie auf der Registerkarte Aufträge auf den Link mit dem Namen des Auftrags.
Klicken Sie neben der Schaltfläche Jetzt ausführen auf den Kebab, und klicken Sie dann auf Zum Code wechseln(YAML).
Fügen Sie die kopierte YAML in die databricks.yml-Datei Ihres Bundles ein oder erstellen Sie eine Konfigurationsdatei für Ihren Job im resources-Verzeichnis Ihres Bundle-Projekts und referenzieren Sie diese in Ihrer databricks.yml-Datei. Siehe (/dev-tools/bundles/settings.md#resources).
Laden Sie alle Python-Dateien und -Notebooks herunter, auf die im bestehenden Auftrag verwiesen wird, und fügen Sie sie der Projektquelle des Bundles hinzu. In der Regel befinden sich Bundle-Artefakte im src Verzeichnis in einem Bundle.

Tipp

Sie können ein vorhandenes Notebook aus einem Azure Databricks-Arbeitsbereich in das .ipynb Format exportieren, in dem Sie in der Azure Databricks-Notebook-Benutzeroberfläche auf File > Export > IPython Notebook klicken.

Nachdem Sie Notebooks, Python-Dateien und andere Artefakte zum Bundle hinzugefügt haben, stellen Sie sicher, dass ihre Auftragsdefinition darauf verweist. Zum Beispiel für ein Notebook mit dem Namen hello.ipynb, das sich im Verzeichnis src des Bundles befindet:
```
resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
      - task_key: hello-task
        notebook_task:
          notebook_path: ../src/hello.ipynb
```

Generieren Sie eine vorhandenen Auftragsdefinition mithilfe der Databricks CLI

So erzeugen Sie programmgesteuert eine Bundle-Konfiguration für einen vorhandenen Auftrag:

Rufen Sie die ID des vorhandenen Auftrags über das seitliche Fenster Auftragsdetails für den Job in der Benutzeroberfläche Jobs ab, oder verwenden Sie den Databricks-CLI-Befehl databricks jobs list.
Führen Sie den bundle generate job Befehl Databricks CLI aus, und legen Sie die Auftrags-ID fest:
```
databricks bundle generate job --existing-job-id 6565621249
```
Dieser Befehl erstellt eine Bundle-Konfigurationsdatei für den Auftrag im resources-Ordner des Bundles und lädt alle referenzierten Artefakte in den src-Ordner herunter.

Tipp

Wenn Sie zuerst bundle deployment bind verwenden, um eine Ressource in einem Bundle an eine im Arbeitsbereich zu binden, wird die Ressource im Arbeitsbereich auf der Grundlage der Konfiguration aktualisiert, die in dem Bundle definiert ist, an das sie nach der nächsten bundle deploy gebunden ist. Weitere Informationen über bundle deployment bind finden Sie unter Binden von Bundle-Ressourcen.

Konfigurieren eines Auftrags, der serverloses Computing verwendet

Die folgenden Beispiele veranschaulichen Bundlekonfigurationen zum Erstellen eines Auftrags, der serverloses Computing verwendet.

Wenn Sie serverloses Computing verwenden möchten, um einen Auftrag auszuführen, der Notebookaufgaben enthält, entfernen Sie die job_clusters-Konfiguration aus der Bundlekonfigurationsdatei.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job-serverless:
      name: retrieve-filter-baby-names-job-serverless
      tasks:
        - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./filter-baby-names.py

  targets:
    development:
      workspace:
        host: <workspace-url>

Wenn Sie serverloses Computing verwenden möchten, um einen Auftrag auszuführen, der Python-Aufgaben enthält, schließen Sie die environments-Konfiguration ein.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: serverless-python-tasks

resources:
jobs:
  serverless-python-job:
    name: serverless-job-with-python-tasks

    tasks:
      - task_key: wheel-task-1
        python_wheel_task:
          entry_point: main
          package_name: wheel_package
        environment_key: Default

    environments:
      - environment_key: Default
        spec:
          client: "1"
          dependencies:
            - workflows_authoring_toolkit==0.0.1

targets:
  development:
    workspace:
      host: <workspace-url>

Weitere Informationen finden Sie unter Ausführen Ihres Azure Databricks-Auftrags mit serverlosem Computing für Workflows.

Freigeben über