Databricks Connect-Tutorial

In diesem Artikel werden die ersten Schritte mit Databricks Connect unter Verwendung von Python und PyCharm veranschaulicht.

Mit Databricks Connect können Sie beliebte IDEs wie PyCharm, Notebookserver und andere benutzerdefinierte Anwendungen mit Azure Databricks-Clustern verbinden.

Hinweis

Dieser Artikel behandelt Databricks Connect für Databricks Runtime 13.0 und höher.

Weitere Informationen zu Databricks Connect für Databricks Runtime 13.0 und höher finden Sie in der Referenz zu Databricks Connect.

Weitere Informationen zu Databricks Connect für frühere Databricks Runtime-Versionen finden Sie unter Databricks Connect für Databricks Runtime 12.2 LTS und früher.

Anforderungen

In diesem praktischen Tutorial wird Folgendes vorausgesetzt:

• Sie haben PyCharm installiert.

• Sie verfügen über einen Azure Databricks-Arbeitsbereich und über ein entsprechendes Konto, und diese sind für Unity Catalog aktiviert. Weitere Informationen finden Sie unter Erste Schritte mit Unity Catalog und Aktivieren eines Arbeitsbereichs für Unity Catalog.

• Der Arbeitsbereich enthält einen Azure Databricks-Cluster. In dem Cluster ist mindestens Databricks Runtime 13.0 installiert. Der Cluster verfügt außerdem über einen Clusterzugriffsmodus vom Typ „Zugewiesen“ oder „Freigegeben“. Weitere Informationen finden Sie unter Zugriffsmodi.

• Auf Ihrem Entwicklungscomputer ist Python 3 installiert, und die Nebenversion Ihrer Python-Clientinstallation ist mit der Python-Nebenversion Ihres Azure Databricks-Clusters identisch. In der folgenden Tabelle sind die mit der jeweiligen Databricks Runtime-Version installierten Python-Versionen aufgeführt.

  Databricks Runtime-Version	Python-Version
  13.2 ML, 13.2	3.10
  13.1 ML, 13.1	3.10
  13.0 ML, 13.0	3.10

Führen Sie zum Bearbeiten dieses Tutorials die folgenden Schritte aus:

Schritt 1: Erstellen eines persönlichen Zugriffstokens

In diesem Tutorial werden die Authentifizierung mit persönlichem Zugriffstoken von Azure Databricks und ein Konfigurationsprofil von Azure Databricks für die Authentifizierung bei Ihrem Azure Databricks-Arbeitsbereich verwendet. Wenn Sie bereits über ein persönliches Azure Databricks-Zugriffstoken und über ein entsprechendes Azure Databricks-Konfigurationsprofil verfügen, können Sie direkt mit Schritt 3 fortfahren.

So erstellen Sie ein persönliches Zugriffstoken

1. Klicken Sie in Ihrem Azure Databricks-Arbeitsbereich in der oberen Leiste auf Ihren Azure Databricks-Benutzernamen, und wählen Sie dann im Dropdownmenü die Option Benutzereinstellungen aus.

2. Klicken Sie auf der Registerkarte Zugriffstoken auf Neues Token generieren.

3. (Optional) Geben Sie einen Kommentar ein, durch den Sie dieses Token in Zukunft identifizieren können, und ändern Sie die standardmäßige Lebensdauer des Tokens von 90 Tagen. Wenn Sie ein Token ohne Gültigkeitsdauer erstellen möchten (nicht empfohlen), lassen Sie das Feld Lebensdauer (Tage) leer.

4. Klicken Sie auf Generate (Generieren) .

5. Kopieren Sie das angezeigte Token an einen sicheren Speicherort, und klicken Sie auf Fertig.

   Achten Sie darauf, den kopierten Token an einem sicheren Ort zu speichern. Geben Sie das kopierte Token nicht an andere Personen weiter. Wenn Sie das kopierte Token verlieren, können Sie das gleiche Token nicht erneut generieren. Stattdessen müssen Sie erneut das Verfahren zum Erstellen eines neuen Tokens durchlaufen. Wenn Sie das kopierte Token verlieren oder glauben, dass das Token kompromittiert wurde, empfiehlt Databricks dringend, dass Sie das Token sofort aus Ihrem Arbeitsbereich löschen. Klicken Sie hierzu auf der Registerkarte Zugriffstoken auf die Schaltfläche X neben dem Token.

   Hinweis

   Wenn Sie in Ihrem Arbeitsbereich keine Token erstellen oder verwenden können, liegt dies möglicherweise daran, dass Ihr Arbeitsbereichsadministrator Token deaktiviert hat oder Ihnen keine Berechtigung zum Erstellen oder Verwenden von Token erteilt hat. Wenden Sie sich an Ihren Arbeitsbereichsadministrator oder lesen Sie:

   • Aktivieren oder Deaktivieren der Authentifizierung mit persönlichen Zugriffstoken für den Arbeitsbereich
   • Berechtigungen für persönliche Zugriffstoken

Schritt 2: Erstellen eines Authentifizierungskonfigurationsprofils

Erstellen Sie ein Azure Databricks-Authentifizierungskonfigurationsprofil, um erforderliche Informationen zu Ihrem persönlichen Zugriffstoken auf Ihrem lokalen Computer zu speichern. Azure Databricks-Entwicklertools und -SDKs können dieses Konfigurationsprofil verwenden, um sich schnell bei Ihrem Azure Databricks-Arbeitsbereich zu authentifizieren.

So erstellen Sie ein Profil

1. Erstellen Sie auf Ihrem Computer im Stammverzeichnis des Benutzers bzw. der Benutzerin eine Datei namens .databrickscfg, falls diese Datei noch nicht vorhanden ist. Für Linux und macOS lautet der Pfad ~/.databrickscfg. Für Windows lautet der Pfad %USERPROFILE%\.databrickscfg.

2. Verwenden Sie einen Text-Editor, um dieser Datei das folgende Konfigurationsprofil hinzuzufügen, und speichern Sie die Datei anschließend:

   [<some-unique-profile-name>]
   host = <my-workspace-url>
   token = <my-personal-access-token-value>
   cluster_id = <my-cluster-id>
   

   Ersetzen Sie die folgenden Platzhalter:

   • Ersetzen Sie <some-unique-profile-name> durch einen eindeutigen Namen für dieses Profil. Dieser Name muss innerhalb der Datei .databrickscfg eindeutig sein.
   • Ersetzen Sie <my-workspace-url> durch die URL Ihres Azure Databricks-Arbeitsbereichs (beginnend mit https://). Siehe Arbeitsbereichsnamen, URLs und IDs.
   • Ersetzen Sie <my-personal-access-token-value> durch den Wert Ihres persönlichen Azure Databricks-Zugriffstokens. Siehe Authentifizieren mit persönlichen Azure Databricks-Zugriffstoken.
   • Ersetzen Sie <my-cluster-id> durch die ID Ihres Azure Databricks-Clusters. Weitere Informationen finden Sie unter Cluster-URL und -ID.

   Beispiele:

   [DEFAULT]
   host = https://my-workspace-url.com
   token = dapi...
   cluster_id = abc123...
   

   Hinweis

   Die obigen Felder host und token sind für die Authentifizierung mit persönlichem Zugriffstoken von Azure Databricks vorgesehen. Hierbei handelt es sich um die gängigste Art der Azure Databricks-Authentifizierung. Einige Databricks-Entwicklertools und -SDKs verwenden in manchen Szenarien auch das Feld cluster_id. Informationen zu weiteren unterstützten Azure Databricks-Authentifizierungstypen und -szenarien finden Sie in der Dokumentation Ihres Tools oder SDK oder unter Einheitliche Databricks-Clientauthentifizierung.

Schritt 3: Erstellen des Projekts

1. Starten Sie PyCharm.
2. Klicken Sie auf Datei > Neues Projekt.
3. Klicken Sie unter Speicherort auf das Ordnersymbol, und folgen Sie den Anweisungen auf dem Bildschirm, um den Pfad zu Ihrem neuen Python-Projekt anzugeben.
4. Erweitern Sie Python-Interpreter: Neue Umgebung.
5. Klicken Sie auf die Option Neue Umgebung mit.
6. Wählen Sie in der Dropdownliste die Option Virtualenv aus.
7. Übernehmen Sie unter Speicherort den vorgeschlagenen Pfad zum Ordner venv.
8. Verwenden Sie unter Basisinterpreter die Dropdownliste, oder klicken Sie auf die Auslassungspunkte, um den Pfad zum Python-Interpreter aus den vorherigen Anforderungen anzugeben.
9. Klicken Sie auf Erstellen.

Schritt 4: Hinzufügen des Databricks Connect-Pakets

1. Klicken Sie im Hauptmenü von PyCharm auf Ansicht > Toolfenster > Python-Pakete.
2. Geben Sie im Suchfeld databricks-connectein.
3. Klicken Sie in der Liste PyPI-Repository auf databricks-connect.
4. Wählen Sie in Dropdownliste Neueste des Ergebnisbereichs die Version aus, die der Databricks Runtime-Version Ihres Clusters entspricht. Wenn in Ihrem Cluster also beispielsweise Databricks Runtime 13.2 installiert ist, wählen Sie 13.2.0 aus.
5. Klicken Sie auf Installieren.
6. Nach der Installation des Pakets können Sie das Fenster Python-Pakete schließen.

Schritt 5: Hinzufügen von Code

1. Klicken Sie im Toolfenster Projekt mit der rechten Maustaste auf den Stammordner des Projekts, und klicken Sie anschließend auf Neu > Python-Datei.

2. Geben Sie main.py ein, und klicken Sie auf Python-Datei.

3. Geben Sie den folgenden Code in die Datei ein, und speichern Sie sie:

   from databricks.connect import DatabricksSession
   
   spark = DatabricksSession.builder.getOrCreate()
   
   df = spark.read.table("samples.nyctaxi.trips")
   df.show(5)
   

Schritt 6: Debuggen des Codes

1. Starten Sie den Zielcluster in Ihrem Azure Databricks-Remotearbeitsbereich.
2. Klicken Sie im obigen Code auf den Bundsteg neben df.show(5), um einen Haltepunkt festzulegen.
3. Klicken Sie nach dem Start des Clusters im Hauptmenü auf Ausführen > Debuggen. Wählen Sie main > Debuggen aus, wenn Sie dazu aufgefordert werden.
4. Erweitern Sie im Toolfenster Debuggen (Ansicht > Toolfenster > Debuggen) im Bereich Variablen der Registerkarte Debugger die Variablenknoten df und spark, um sich Informationen zu den Variablen df und spark des Codes anzusehen.
5. Klicken Sie auf der Randleiste des Toolfensters Debuggen auf den grünen Pfeil (Programm fortsetzen).
6. Im Bereich Konsole der Registerkarte Debugger werden die ersten fünf Zeilen von samples.nyctaxi.trips angezeigt.

Nächste Schritte

Weitere Informationen zu Databricks Connect sowie ein komplexeres Codebeispiel zum Experimentieren finden Sie in der Referenz zu Databricks Connect. Dieser Referenzartikel enthält Informationen zu folgenden Themen:

• Unterstützte Azure Databricks-Authentifizierungstypen neben der Authentifizierung mit persönlichem Azure Databricks-Zugriffstoken
• Verwenden von SparkShell und IDEs zusätzlich zu PyCharm verwenden (beispielsweise JupyterLab, eine klassische Jupyter Notebook-Instanz, Visual Studio Code oder Eclipse mit PyDev)
• Migrieren von Databricks Connect für Databricks Runtime 12.2 LTS und niedrigeren Versionen zu Databricks Connect für Databricks Runtime 13.0 und höheren Versionen
• Zugreifen auf Databricks-Hilfsprogramme mithilfe von Databricks Connect
• Problembehandlungen
• Einschränkungen von Databricks Connect