Installera Databricks Anslut för Python

  • Artikel

Kommentar

Den här artikeln beskriver Databricks Anslut för Databricks Runtime 13.0 och senare.

I den här artikeln beskrivs hur du installerar Databricks Anslut för Python. Se Vad är Databricks Anslut?. Scala-versionen av den här artikeln finns i Installera Databricks Anslut för Scala.

Krav

  • Din Azure Databricks-målarbetsyta och ditt kluster måste uppfylla kraven för klusterkonfiguration för Databricks Anslut.

  • Du måste installera Python 3 på utvecklingsdatorn och den lägre versionen av python-klientens installation måste vara samma som den lägre Python-versionen av Azure Databricks-klustret. Information om hur du hittar den lägre Python-versionen av klustret finns i avsnittet "Systemmiljö" i Viktig information om Databricks Runtime för klustret. Se Viktig information om versioner och kompatibilitet för Databricks Runtime.

    Kommentar

    Om du vill använda PySpark-UDF:er är det viktigt att utvecklingsdatorns installerade delversion av Python matchar den delversion av Python som ingår i Databricks Runtime som är installerad i klustret.

  • Databricks-Anslut större och mindre paketversion bör matcha din Databricks Runtime-version. Databricks rekommenderar att du alltid använder det senaste paketet med Databricks Anslut som matchar din Databricks Runtime-version. När du till exempel använder ett Databricks Runtime 14.0-kluster bör du också använda 14.0 versionen av databricks-connect paketet.

    Kommentar

    Se Viktig information om Databricks Anslut för en lista över tillgängliga Databricks-Anslut-versioner och underhållsuppdateringar.

    Att använda det senaste paketet med Databricks Anslut som matchar din Databricks Runtime-version är inte ett krav. För Databricks Runtime 13.3 LTS och senare kan du använda Databricks Anslut-paketet mot alla versioner av Databricks Runtime vid eller över versionen av Databricks Anslut-paketet. Men om du vill använda funktioner som är tillgängliga i senare versioner av Databricks Runtime måste du uppgradera Databricks-Anslut paketet i enlighet med detta.

  • Databricks rekommenderar starkt att du har en virtuell Python-miljö aktiverad för varje Python-version som du använder med Databricks Anslut. Virtuella Python-miljöer hjälper dig att se till att du använder rätt versioner av Python och Databricks Anslut tillsammans. Detta kan bidra till att minska eller förkorta lösningen av relaterade tekniska problem. Se hur du aktiverar en virtuell Python-miljö för venv eller Poesi i följande avsnitt. Mer information om dessa verktyg finns i venv eller poesi.

Aktivera en virtuell Python-miljö med venv

Om du använder venv på utvecklingsdatorn och klustret kör Python 3.10 måste du skapa en venv miljö med den versionen. Följande exempelkommando genererar skripten för att aktivera en venv miljö med Python 3.10, och det här kommandot placerar sedan dessa skript i en dold mapp med namnet .venv i den aktuella arbetskatalogen:

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

# Windows
python3.10 -m venv .\.venv

Information om hur du använder dessa skript för att aktivera den här venv miljön finns i Så här fungerar venvs.

Gå vidare till Konfigurera klienten.

Aktivera en virtuell Python-miljö med Poetry

  1. Installera Poetry, om du inte redan har gjort det.

  2. Om du använder Poesi på utvecklingsdatorn och klustret kör Python 3.10 måste du skapa en virtuell poesimiljö med den versionen. Från rotkatalogen för ditt befintliga Python-kodprojekt instruerar du poetry dig att initiera Python-kodprojektet för Poetry genom att köra följande kommando:

    poetry init

  3. Poesi visar flera uppmaningar som du kan slutföra. Ingen av dessa uppmaningar är specifika för Databricks Anslut. Information om dessa frågor finns i init.

  4. När du har slutfört anvisningarna lägger Poetry till en pyproject.toml fil i Python-projektet. Information om filen finns i pyproject.toml filen pyproject.toml.

  5. Från rotkatalogen i python-kodprojektet instruerar du poetry dig att läsa pyproject.toml filen, lösa beroendena och installera dem, skapa en poetry.lock fil för att låsa beroendena och slutligen skapa en virtuell miljö. Gör detta genom att köra följande kommando:

    poetry install

  6. Från rotkatalogen för python-kodprojektet instruerar du poetry att aktivera den virtuella miljön och ange gränssnittet. Gör detta genom att köra följande kommando:

    poetry shell

Du vet att din virtuella miljö är aktiverad och gränssnittet anges när namnet på den virtuella miljön visas inom parenteser precis före terminalen, till exempel (my-project-py3.10).

Om du vill inaktivera den virtuella miljön och avsluta gränssnittet när som helst kör du kommandot exit.

Du vet att du har avslutat gränssnittet när den virtuella miljöns namn inte längre visas inom parenteser precis före terminalprompten.

Mer information om hur du skapar och hanterar virtuella poesimiljöer finns i Hantera miljöer.

Konfigurera klienten

Dricks

Om du redan har Databricks-tillägget för Visual Studio Code installerat behöver du inte följa de här installationsanvisningarna.

Databricks-tillägget för Visual Studio Code har redan inbyggt stöd för Databricks Anslut för Databricks Runtime 13.0 och senare. Hoppa vidare till Felsökningskod med hjälp av Databricks Anslut för Databricks-tillägget för Visual Studio Code.

När du uppfyller kraven för Databricks Anslut utför du följande steg för att konfigurera Databricks Anslut-klienten.

Steg 1: Installera Databricks Anslut-klienten

I det här avsnittet beskrivs hur du installerar Databricks Anslut-klienten med venv eller poesi.

Installera Databricks Anslut-klienten med venv

  1. När den virtuella miljön är aktiverad avinstallerar du PySpark, om den redan är installerad, genom att uninstall köra kommandot . Detta krävs eftersom paketet står i databricks-connect konflikt med PySpark. Mer information finns i PySpark-installationer i konflikt. Kör kommandot för att kontrollera om PySpark redan är installerat show .

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. När den virtuella miljön fortfarande är aktiverad installerar du Databricks Anslut-klienten genom att install köra kommandot . Använd alternativet --upgrade för att uppgradera en befintlig klientinstallation till den angivna versionen.

    pip3 install --upgrade "databricks-connect==14.0.*"  # Or X.Y.* to match your cluster version.

    Kommentar

    Databricks rekommenderar att du lägger till notationen "dot-asterisk" för att ange databricks-connect==X.Y.* i stället för databricks-connect=X.Y, för att se till att det senaste paketet är installerat. Detta är inte ett krav, men det hjälper dig att se till att du kan använda de senaste funktionerna som stöds för klustret.

Gå vidare till Steg 2: Konfigurera anslutningsegenskaper.

Installera Databricks Anslut-klienten med Poetry

  1. När den virtuella miljön är aktiverad avinstallerar du PySpark, om den redan är installerad, genom att remove köra kommandot . Detta krävs eftersom paketet står i databricks-connect konflikt med PySpark. Mer information finns i PySpark-installationer i konflikt. Kör kommandot för att kontrollera om PySpark redan är installerat show .

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. När den virtuella miljön fortfarande är aktiverad installerar du Databricks Anslut-klienten genom att add köra kommandot .

    poetry add databricks-connect@~14.0  # Or X.Y to match your cluster version.

    Kommentar

    Databricks rekommenderar att du använder notationen "at-tilde" för att ange databricks-connect@~14.0 i stället för databricks-connect==14.0, för att se till att det senaste paketet är installerat. Detta är inte ett krav, men det hjälper dig att se till att du kan använda de senaste funktionerna som stöds för klustret.

Steg 2: Konfigurera anslutningsegenskaper

I det här avsnittet konfigurerar du egenskaper för att upprätta en anslutning mellan Databricks Anslut och ditt fjärranslutna Azure Databricks-kluster. Dessa egenskaper omfattar inställningar för att autentisera Databricks Anslut med klustret.

För Databricks Anslut för Databricks Runtime 13.1 och senare innehåller Databricks Anslut Databricks SDK för Python. Denna SDK implementerar Databricks-klientens enhetliga autentiseringsstandard, en konsoliderad och konsekvent arkitektur- och programmatisk metod för autentisering. Den här metoden gör det mer centraliserat och förutsägbart att konfigurera och automatisera autentisering med Azure Databricks. Det gör att du kan konfigurera Azure Databricks-autentisering en gång och sedan använda den konfigurationen över flera Azure Databricks-verktyg och SDK:er utan ytterligare autentiseringskonfigurationsändringar.

Kommentar

  1. Samla in följande konfigurationsegenskaper.

  2. Konfigurera anslutningen i koden. Databricks Anslut söker efter konfigurationsegenskaper i följande ordning tills de hittas. När den hittar dem slutar den att söka igenom de återstående alternativen. Informationen för varje alternativ visas efter följande tabell:

    Alternativ för konfigurationsegenskaper Gäller för
    1. Klassens DatabricksSessionremote() metod Endast autentisering med personlig åtkomsttoken i Azure Databricks
    2. En Azure Databricks-konfigurationsprofil Alla autentiseringstyper för Azure Databricks
    3. Miljövariabeln SPARK_REMOTE Endast autentisering med personlig åtkomsttoken i Azure Databricks
    4. Miljövariabeln DATABRICKS_CONFIG_PROFILE Alla autentiseringstyper för Azure Databricks
    5. En miljövariabel för varje konfigurationsegenskap Alla autentiseringstyper för Azure Databricks
    6. En Azure Databricks-konfigurationsprofil med namnet DEFAULT Alla autentiseringstyper för Azure Databricks

    1. Klassens DatabricksSessionremote() metod

      För det här alternativet, som endast gäller för autentisering med personlig åtkomsttoken i Azure Databricks, anger du namnet på arbetsytans instans, azure Databricks personliga åtkomsttoken och klustrets ID.

      Du kan initiera klassen på DatabricksSession flera sätt på följande sätt:

      • Ange fälten host, tokenoch cluster_id i DatabricksSession.builder.remote().
      • Använd Databricks SDK:s Config klass.
      • Ange en Databricks-konfigurationsprofil tillsammans med fältet cluster_id .
      • Ange Spark-Anslut anslutningssträng i DatabricksSession.builder.remote().

      Databricks rekommenderar inte att du direkt anger dessa anslutningsegenskaper i koden. I stället rekommenderar Databricks att du konfigurerar egenskaper via miljövariabler eller konfigurationsfiler, enligt beskrivningen i det här avsnittet. I följande kodexempel förutsätts att du tillhandahåller en viss implementering av de föreslagna retrieve_* funktionerna själv för att hämta nödvändiga egenskaper från användaren eller från något annat konfigurationsarkiv, till exempel Azure KeyVault.

      Koden för var och en av dessa metoder är följande:

      # Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(
  host       = f"https://{retrieve_workspace_instance_name()}",
  token      = retrieve_token(),
  cluster_id = retrieve_cluster_id()
).getOrCreate()

# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  host       = f"https://{retrieve_workspace_instance_name()}",
  token      = retrieve_token(),
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  profile    = "<profile-name>",
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Set the Spark Connect connection string in DatabricksSession.builder.remote.
from databricks.connect import DatabricksSession

workspace_instance_name = retrieve_workspace_instance_name()
token                   = retrieve_token()
cluster_id              = retrieve_cluster_id()

spark = DatabricksSession.builder.remote(
  f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
).getOrCreate()

    2. En Azure Databricks-konfigurationsprofil

      För det här alternativet skapar eller identifierar du en Azure Databricks-konfigurationsprofil som innehåller fältet cluster_id och andra fält som behövs för den Databricks-autentiseringstyp som du vill använda.

      De obligatoriska konfigurationsprofilfälten för varje autentiseringstyp är följande:

      Ange sedan namnet på den här konfigurationsprofilen via Config klassen.

      Du kan ange cluster_id på några sätt på följande sätt:

      • Inkludera fältet cluster_id i konfigurationsprofilen och ange sedan bara konfigurationsprofilens namn.
      • Ange namnet på konfigurationsprofilen tillsammans med fältet cluster_id .

      Om du redan har angett DATABRICKS_CLUSTER_ID miljövariabeln med klustrets ID behöver du inte heller ange cluster_id.

      Koden för var och en av dessa metoder är följande:

      # Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()

# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  profile    = "<profile-name>",
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

    3. Miljövariabeln SPARK_REMOTE

      För det här alternativet, som endast gäller för autentisering med personlig åtkomsttoken i Azure Databricks, anger du SPARK_REMOTE miljövariabeln till följande sträng och ersätter platshållarna med lämpliga värden.

      sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>

      Initiera sedan klassen enligt DatabricksSession följande:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

    4. Miljövariabeln DATABRICKS_CONFIG_PROFILE

      För det här alternativet skapar eller identifierar du en Azure Databricks-konfigurationsprofil som innehåller fältet cluster_id och andra fält som behövs för den Databricks-autentiseringstyp som du vill använda.

      Om du redan har angett DATABRICKS_CLUSTER_ID miljövariabeln med klustrets ID behöver du inte heller ange cluster_id.

      De obligatoriska konfigurationsprofilfälten för varje autentiseringstyp är följande:

      DATABRICKS_CONFIG_PROFILE Ange miljövariabeln till namnet på den här konfigurationsprofilen. Initiera sedan klassen enligt DatabricksSession följande:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

    5. En miljövariabel för varje konfigurationsegenskap

      För det här alternativet anger DATABRICKS_CLUSTER_ID du miljövariabeln och eventuella andra miljövariabler som krävs för den Databricks-autentiseringstyp som du vill använda.

      De miljövariabler som krävs för varje autentiseringstyp är följande:

      Initiera sedan klassen enligt DatabricksSession följande:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

    6. En Azure Databricks-konfigurationsprofil med namnet DEFAULT

      För det här alternativet skapar eller identifierar du en Azure Databricks-konfigurationsprofil som innehåller fältet cluster_id och andra fält som behövs för den Databricks-autentiseringstyp som du vill använda.

      Om du redan har angett DATABRICKS_CLUSTER_ID miljövariabeln med klustrets ID behöver du inte heller ange cluster_id.

      De obligatoriska konfigurationsprofilfälten för varje autentiseringstyp är följande:

      Ge den här konfigurationsprofilen DEFAULTnamnet .

      Initiera sedan klassen enligt DatabricksSession följande:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

  3. Verifiera din miljö och anslutningen till Databricks-klustret

    • Följande kommando kontrollerar att din miljö, standardautentiseringsuppgifter och anslutning till klustret är korrekt konfigurerade för Databricks Anslut.

      databricks-connect test

      Det här kommandot hämtar standardautentiseringsuppgifterna som konfigurerats i miljön (till exempel konfigurationsprofilen DEFAULT eller via miljövariabler).

      Kommandot misslyckas med en slutkod som inte är noll och ett motsvarande felmeddelande när det identifierar eventuell inkompatibilitet i installationen.

    • Du kan också använda gränssnittet pyspark som ingår som en del av Databricks Anslut för Python. Starta gränssnittet genom att köra:

      pyspark

      Spark-gränssnittet visas till exempel:

      Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 13.0
      /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>

      >>> Kör ett enkelt PySpark-kommando i kommandotolken, till exempel spark.range(1,10).show(). Om det inte finns några fel har du anslutit.

      Om du har anslutit kan du stoppa Spark-gränssnittet genom att trycka Ctrl + d på eller Ctrl + z, eller köra kommandot quit() eller exit().

      Mer information om binärfilen finns i databricks-connect Avancerad användning av Databricks Anslut för Python