Debuggen von Code mithilfe von Databricks Connect für die Databricks-Erweiterung für Visual Studio Code

In diesen Artikeln wird beschrieben, wie Sie Code mithilfe der Databricks Connect-Integration in der Databricks-Erweiterung für Visual Studio Code debuggen. Weitere Informationen finden Sie unter Was ist die Databricks-Erweiterung für Visual Studio Code?.

In diesem Artikel wird davon ausgegangen, dass Sie die Databricks-Erweiterung für Visual Studio Code bereits installiert und eingerichtet haben. Weitere Informationen finden Sie unter Installieren der Databricks-Erweiterung für Visual Studio Code.

Hinweis

Dieses Feature ist experimentell.

Die Databricks Connect-Integration in der Databricks-Erweiterung für Visual Studio Code unterstützt nur einen Teil des Databricks-Clientstandard für einheitliche Authentifizierung. Weitere Informationen finden Sie unter Einrichten der Authentifizierung für die Databricks-Erweiterung für VS Code.

Die Databricks-Erweiterung für Visual Studio Code umfasst Databricks Connect. Sie können Databricks Connect innerhalb der Databricks-Erweiterung für Visual Studio Code verwenden, um einzelne Python-Dateien (.py) und Python Jupyter-Notebooks (.ipynb) auszuführen und schrittweise zu debuggen. Die Databricks-Erweiterung für Visual Studio Code umfasst Databricks Connect für Databricks Runtime 13.0 und höher. Frühere Versionen von Databricks Connect werden nicht unterstützt.

Anforderungen

Bevor Sie Databricks Connect aus der Databricks-Erweiterung für Visual Studio Code verwenden können, müssen Sie zunächst die Anforderungen für Databricks Connect erfüllen. Zu diesen Anforderungen gehören beispielsweise ein Arbeitsbereich, der mit Unity Catalog aktiviert wurde, ein Cluster mit Databricks Runtime 13.0 oder höher und einem Einzelbenutzer- oder freigegebenen Clusterzugriffsmodus sowie eine lokal installierte Version von Python, deren Haupt- und Nebenversion mit den im Cluster installierten Python-Versionen übereinstimmen.

Schritt 1: Erstellen einer virtuellen Python-Umgebung

Erstellen und aktivieren Sie eine virtuelle Python-Umgebung für Ihr Python-Codeprojekt. Mit virtuellen Python-Umgebungen können Sie sicherstellen, dass Ihr Codeprojekt kompatible Versionen von Python und Python-Paketen verwendet (in diesem Fall das Databricks Connect-Paket). In den Anweisungen und Beispielen in diesem Artikel wird venv oder Poetry für virtuelle Python-Umgebungen verwendet. Databricks hat das Databricks Connect-Paket nicht vollständig mit anderen Typen von virtuellen Python-Umgebungen wie Conda getestet.

Erstellen einer virtuellen Python-Umgebung mithilfe von venv

1. In Ihrem Visual Studio Code-Terminal (Ansicht > Terminal), das auf das Stammverzeichnis Ihres Python-Codeprojekts festgelegt ist, weisen Sie venv an, Python für die virtuelle Umgebung zu verwenden. Erstellen Sie dann die unterstützenden Dateien der virtuellen Umgebung in einem ausgeblendeten Verzeichnis namens .venv im Stammverzeichnis Ihres Python-Codeprojekts, indem Sie den folgenden Befehl ausführen:

   # Linux and macOS
   python3.10 -m venv ./.venv
   # Windows
   python3.10 -m venv .\.venv
   

   Der vorherige Befehl verwendet Python 3.10, das der Haupt- und Nebenversion von Python entspricht, das die Databricks Runtime 13.0 verwendet. Verwenden Sie unbedingt die Haupt- und Nebenversion von Python, die der installierten Python-Version Ihres Clusters entspricht.

2. Wenn Visual Studio Code eine mit der folgenden vergleichbare Meldung anzeigt: „Wir haben festgestellt, dass eine neue Umgebung erstellt wurde. Möchten Sie sie für den Arbeitsbereichsordner auswählen?“ klicken Sie auf Ja.

3. Verwenden Sie venv, um die virtuelle Umgebung zu aktivieren. In der venv-Dokumentation finden Sie den richtigen Befehl für Ihr Betriebssystem und Ihren Terminaltyp. Beispiel: Unter macOS zsh:

   source ./.venv/bin/activate
   

   Sie wissen, dass Ihre virtuelle Umgebung aktiviert ist, wenn der Name der virtuellen Umgebung (z. B. .venv) direkt vor der Terminalaufforderung in Klammern angezeigt wird.

   Sie können die virtuelle Umgebung jederzeit deaktivieren, indem Sie den Befehl deactivate ausführen.

   Sie wissen, dass Ihre virtuelle Umgebung deaktiviert ist, wenn der Name der virtuellen Umgebung nicht mehr direkt vor der Terminalaufforderung in Klammern angezeigt wird.

Fahren Sie mit Schritt 2: Aktualisieren Ihres Python-Codes, um einen Debugkontext einzurichten fort.

Erstellen einer virtuellen Python-Umgebung mithilfe von Poetry

1. Installieren Sie Poetry, wenn Sie dies noch nicht getan haben.

2. Legen Sie im Visual Studio Code-Terminal (Ansicht > Terminal) das Stammverzeichnis Ihres vorhandenen Python-Codeprojekts fest, und weisen Sie poetry an, Ihr Python-Codeprojekt für Poetry zu initialisieren, indem Sie den folgenden Befehl ausführen:

   poetry init
   

3. Poetry zeigt mehrere Eingabeaufforderungen an. Keine dieser Eingabeaufforderungen gelten speziell für die Databricks-Erweiterung für Visual Studio Code oder für Databricks Connect. Informationen zu diesen Eingabeaufforderungen finden Sie unter init.

4. Nachdem Sie die Eingabeaufforderungen abgeschlossen haben, fügt Poetry Ihrem Python-Projekt eine Datei vom Typ pyproject.toml hinzu. Informationen zur Datei pyproject.toml finden Sie unter Datei „pyproject.toml“.

5. Wenn das Visual Studio Code-Terminal weiterhin auf das Stammverzeichnis Ihres Python-Codeprojekts festgelegt ist, weisen Sie poetry an, die pyproject.toml Datei zu lesen, die Abhängigkeiten aufzulösen und zu installieren sowie eine Datei vom Typ poetry.lock zum Sperren der Abhängigkeiten und schließlich eine virtuelle Umgebung zu erstellen. Führen Sie zu diesem Zweck den folgenden Befehl aus:

   poetry install
   

6. Weisen Sie Visual Studio Code wie folgt an, den Python-Interpreter zu verwenden, der in der virtuellen Umgebung für dieses Python-Projekt enthalten ist:

   1. Ermitteln Sie den vollständigen Pfad zum Python-Interpreter, der sich in der virtuellen Umgebung für dieses Python-Projekt befindet, indem Sie den folgenden Befehl aus dem Stammverzeichnis des Projekts ausführen:

      poetry env info
      

   2. Kopieren Sie den vollständigen Pfad, der in der Ausgabe des Felds Virtualenv > Executable angezeigt wird, z. B. den vollständigen Pfad, der pypoetry/virtualenvs enthält.

   3. Geben Sie in der Befehlspalette (Ansicht > Befehlspalette) den Befehl >Python: Select Interpreter ein.

   4. Geben Sie den vollständigen Pfad zum Python-Interpreter ein, den Sie gerade kopiert haben.

7. Wenn das Visual Studio Code-Terminal weiterhin auf das Stammverzeichnis Ihres Python-Codeprojekts festgelegt ist, weisen Sie poetry an, die virtuelle Umgebung zu aktivieren und die Shell aufzurufen. Führen Sie zu diesem Zweck den folgenden Befehl aus:

   poetry shell
   

   Sie wissen, dass Ihre virtuelle Umgebung aktiviert ist und die Shell aufgerufen wurde, wenn der Name der virtuellen Umgebung direkt vor der Terminalaufforderung in Klammern angezeigt wird.

   Sie können die virtuelle Umgebung jederzeit deaktivieren und die Shell beenden, indem Sie den Befehl exit ausführen.

   Sie wissen, dass Sie die Shell beendet haben, wenn der Name der virtuellen Umgebung nicht mehr direkt vor der Terminalaufforderung in Klammern angezeigt wird.

   Weitere Informationen zum Erstellen und Verwalten von virtuellen Poetry-Umgebungen finden Sie unter Verwalten von Umgebungen.

Schritt 2: Aktualisieren Ihres Python-Codes, um einen Debugkontext einzurichten

Um einen Debugkontext zwischen Databricks Connect und Ihrem Cluster einzurichten, muss Ihr Python-Code die DatabricksSession-Klasse durch den Aufruf von DatabricksSession.builder.getOrCreate() initialisieren.

Beachten Sie, dass es nicht erforderlich ist, Einstellungen wie den Instanzennamen Ihres Arbeitsbereichs, ein Zugriffstoken oder die ID und Portnummer Ihres Clusters anzugeben, wenn Sie die DatabricksSession-Klasse initialisieren. Databricks Connect ruft diese Informationen aus den Konfigurationsdetails ab, die Sie bereits weiter oben in diesem Artikel über die Databricks-Erweiterung für Visual Studio Code angegeben haben.

Weitere Informationen zum Initialisieren der DatabricksSession-Klasse finden Sie in den Codebeispielen zu Databricks Connect.

Wichtig

Wenn Sie die Databricks-Erweiterung für Visual Studio Code verwenden, um den Authentifizierungstyp auf persönliche Zugriffstoken festzulegen, legt die Erweiterung eine zugehörige SPARK_REMOTE-Umgebungsvariable mit Debugkontexteinstellungen für die Verwendung durch Databricks Connect fest. Zu diesen Debugkontexteinstellungen gehören der zugehörige Arbeitsbereichsinstanzname, das persönliche Zugriffstoken und die Cluster-ID.

In Databricks Connect können Sie die Klasse DatabricksSession oder SparkSession zusammen mit SPARK_REMOTE und der Authentifizierung mit persönlichem Zugriffstoken verwenden, um den Debugkontext schnell und einfach programmgesteuert einzurichten. Für andere unterstützte Azure Databricks-Authentifizierungstypen können Sie nur die DatabricksSession-Klasse verwenden, um den Debugkontext einzurichten.

Weitere Informationen finden Sie unter Einrichten des Clients in der Dokumentation zu Databricks Connect.

Schritt 3: Aktivieren von Databricks Connect

Gehen Sie wie folgt vor, während die Erweiterung geöffnet und der Abschnitt Arbeitsbereich für Ihr Codeprojekt konfiguriert ist:

1. Klicken Sie in der Statusleiste von Visual Studio Code auf die rote Schaltfläche Databricks Connect deaktiviert.

2. Wenn der Abschnitt Cluster noch nicht in der Erweiterung konfiguriert ist, wird eine mit der folgenden vergleichbare Meldung angezeigt: „Fügen Sie einen Cluster an, um Databricks Connect zu verwenden.“ Klicken Sie auf Cluster anfügen, und wählen Sie einen Cluster aus, der die Anforderungen für Databricks Connect erfüllt.

3. Wenn der Abschnitt Cluster konfiguriert ist, der Cluster jedoch nicht mit Databricks Connect kompatibel ist, klicken Sie auf die rote Schaltfläche Databricks Connect deaktiviert, klicken Sie auf Cluster anfügen, und wählen Sie einen kompatiblen Cluster aus.

4. Wenn das Databricks Connect-Paket (und seine Abhängigkeiten) noch nicht installiert ist, wird die folgende Meldung angezeigt: „Für das interaktive Debuggen und die automatische Vervollständigung benötigen Sie Databricks Connect. Möchten Sie es in der Umgebung <environment-name> installieren?“ Klicken Sie auf Installieren.

5. In der Statusleiste von Visual Studio Code wird die Schaltfläche Databricks Connect aktiviert angezeigt.

   Wenn weiterhin die rote Schaltfläche Databricks Connect deaktiviert angezeigt wird, klicken Sie darauf, und führen Sie die Anweisungen auf dem Bildschirm aus, damit die Schaltfläche Databricks Connect aktiviert angezeigt wird.

6. Nachdem die Schaltfläche Databricks Connect aktiviert angezeigt wurde, können Sie Databricks Connect verwenden.

Hinweis

Sie müssen den Abschnitt Synchronisierungsziel der Erweiterung nicht konfigurieren, damit Ihr Codeprojekt Databricks Connect nutzen kann.

Wenn Sie Poetry verwenden, können Sie die Dateien pyproject.toml und poetry.lock mit dem installierten Databricks Connect-Paket (und dessen Abhängigkeiten) synchronisieren, indem Sie den folgenden Befehl ausführen. Ersetzen Sie 13.3.2 unbedingt durch die Version des Databricks Connect-Pakets, die mit der Version übereinstimmt, die von der Datenbricks-Erweiterung für Visual Studio Code für Ihr Projekt installiert wurde.

poetry add databricks-connect==13.3.2

Schritt 4: Ausführen oder Debuggen Ihres Python-Codes

Nachdem Sie Databricks Connect für Ihr Codeprojekt aktiviert haben, können Sie Ihre Python-Datei oder Ihr Python-Notebook wie folgt ausführen oder debuggen.

So können Sie eine Python-Datei (.py) ausführen oder debuggen:

1. Öffnen Sie in Ihrem Codeprojekt die Python-Datei, die Sie ausführen oder debuggen möchten.

2. Legen Sie Debugbreakpoints in der Python-Datei fest.

3. Klicken Sie in der Titelleiste des Datei-Editors auf den Dropdownpfeil neben dem Wiedergabesymbol (Ausführen oder Debuggen). Wählen Sie dann in der Dropdownliste Python-Datei debuggen aus. Diese Option unterstützt das schrittweise Debuggen, Breakpoints, Überwachungsausdrücke, Aufrufstapel und ähnliche Funktionen. Diese Option verwendet Databricks Connect, um Python-Code lokal auszuführen, PySpark-Code auf dem Cluster im Remotearbeitsbereich auszuführen und Remoteantworten zurück an Visual Studio Code zum lokalen Debuggen zu senden.

   Hinweis

   Weitere Optionen, die das Debuggen nicht unterstützen, sind:

   • Ausführen einer Python-Datei zur Verwendung von Databricks Connect, um die Datei oder das Notebooks zu verwenden – jedoch ohne Debugunterstützung. Diese Option sendet die Datei an den Remotearbeitsbereich, führt den Python- und PySpark-Code der Datei auf dem Remotecluster im Arbeitsbereich aus und sendet die Remoteantwort an das Visual Studio Code-Terminal.
   • Datei in Databricks hochladen und ausführen, um die Datei an den Remotearbeitsbereich zu senden, den Python- und PySpark-Code der Datei im Remotecluster im Arbeitsbereich auszuführen und die Remoteantwort an das Visual Studio Code-Terminal zu senden. Bei dieser Option wird Databricks Connect nicht verwendet.
   • Run File as Workflow on Databricks, um die Datei an den Remotearbeitsbereich zu senden, den Python- und PySpark-Code der Datei in dem Cluster auszuführen, der einem automatisierten Azure Databricks-Auftrag zugeordnet ist, und die Ergebnisse an einen Editor in Visual Studio Code zu senden. Bei dieser Option wird Databricks Connect nicht verwendet.

   

   Falls verfügbar, wird mit der Option Aktuelle Datei in interaktivem Fenster ausführen versucht, die Datei lokal in einem speziellen interaktiven Visual Studio Code-Editor auszuführen. Diese Option wird von Databricks nicht empfohlen.

So können Sie ein Python Jupyter-Notebook ausführen oder debuggen (.ipynb):

1. Öffnen Sie in Ihrem Codeprojekt das Python Jupyter-Notebook, das Sie ausführen oder debuggen möchten. Stellen Sie sicher, dass die Python-Datei das Jupyter-Notebookformat und die Erweiterung .ipynb aufweist.

   Tipp

   Sie können ein neues Python Jupyter-Notebook erstellen, indem Sie den Befehl >Erstellen: Neues Jupyter-Notebook in der Befehlspalette ausführen.

2. Klicken Sie auf Alle Zellen ausführen, um alle Zellen ohne Debuggen auszuführen, auf Zelle ausführen, um eine einzelne entsprechende Zelle ohne Debuggen auszuführen, oder auf Nach Zeile ausführen, um eine einzelne Zelle zeilenweise mit eingeschränktem Debuggen auszuführen, wobei Variablenwerte im Bereich Jupyter angezeigt werden (Ansicht > Ansicht öffnen > Jupyter).

   Legen Sie zum vollständigen Debuggen innerhalb einer einzelnen Zelle Breakpoints fest, und klicken Sie dann im Menü neben der Schaltfläche Ausführen der Zelle auf Zelle debuggen.

   Nachdem Sie auf eine dieser Optionen geklickt haben, werden Sie möglicherweise aufgefordert, fehlende Python Jupyter Notebook-Paketabhängigkeiten zu installieren. Klicken Sie darauf, um es zu installieren.

   Weitere Informationen finden Sie unter Jupyter-Notebooks in VS Code.