Share via

Instalowanie Połączenie usługi Databricks dla języka Python

  • Artykuł

Uwaga

W tym artykule opisano Połączenie databricks dla środowiska Databricks Runtime 13.0 lub nowszego.

W tym artykule opisano sposób instalowania usługi Databricks Połączenie dla języka Python. Zobacz Co to jest usługa Databricks Połączenie?. Aby zapoznać się z wersją tego artykułu, zobacz Install Databricks Połączenie for Scala (Instalowanie usługi Databricks Połączenie dla języka Scala).

Wymagania

  • Docelowy obszar roboczy i klaster usługi Azure Databricks muszą spełniać wymagania dotyczące konfiguracji klastra dla usługi Databricks Połączenie.

  • Musisz zainstalować język Python 3 na komputerze deweloperskim, a wersja pomocnicza instalacji klienta języka Python musi być taka sama jak wersja pomocniczego języka Python klastra usługi Azure Databricks. Aby znaleźć pomocniczą wersję środowiska Python klastra, zapoznaj się z sekcją "Środowisko systemowe" w informacjach o wersji środowiska Databricks Runtime dla klastra. Zobacz Databricks Runtime release notes versions and compatibility (Wersje i zgodność środowiska Databricks Runtime).

    Uwaga

    Jeśli chcesz użyć funkcji zdefiniowanej przez użytkownika PySpark, ważne jest, aby zainstalowana wersja pomocnicza języka Python na maszynie deweloperskiej była zgodna z wersją pomocniczą języka Python dołączoną do środowiska Databricks Runtime zainstalowanego w klastrze.

  • Wersja pakietu głównego i pomocniczego usługi Databricks Połączenie powinna być zgodna z wersją środowiska Databricks Runtime. Usługa Databricks zaleca, aby zawsze używać najnowszego pakietu usługi Databricks Połączenie zgodnego z wersją środowiska Databricks Runtime. Na przykład w przypadku korzystania z klastra Databricks Runtime 14.0 należy również użyć 14.0 wersji databricks-connect pakietu.

    Uwaga

    Zapoznaj się z informacjami o wersji usługi Databricks Połączenie, aby uzyskać listę dostępnych wersji usługi Databricks Połączenie i aktualizacji konserwacji.

    Korzystanie z najnowszego pakietu usługi Databricks Połączenie zgodnego z wersją środowiska Databricks Runtime nie jest wymagane. W przypadku środowiska Databricks Runtime 13.3 LTS lub nowszego można użyć pakietu Połączenie usługi Databricks we wszystkich wersjach środowiska Databricks Runtime w wersji pakietu Połączenie usługi Databricks lub nowszej. Jeśli jednak chcesz użyć funkcji dostępnych w nowszych wersjach środowiska Databricks Runtime, musisz odpowiednio uaktualnić pakiet usługi Databricks Połączenie.

  • Usługa Databricks zdecydowanie zaleca aktywowanie środowiska wirtualnego języka Python dla każdej wersji języka Python używanej z usługą Databricks Połączenie. Środowiska wirtualne języka Python pomagają upewnić się, że używasz poprawnych wersji języka Python i usługi Databricks Połączenie razem. Może to pomóc zmniejszyć lub skrócić rozwiązywanie powiązanych problemów technicznych. Zobacz, jak aktywować środowisko wirtualne języka Python dla venv programu lub poezję w poniższych sekcjach. Aby uzyskać więcej informacji na temat tych narzędzi, zobacz venv lub Poezja.

Aktywowanie środowiska wirtualnego języka Python za pomocą venv

Jeśli używasz venv na komputerze deweloperskim, a klaster korzysta z języka Python 3.10, musisz utworzyć venv środowisko w tej wersji. Następujące przykładowe polecenie generuje skrypty, aby aktywować venv środowisko za pomocą języka Python 3.10, a to polecenie umieszcza te skrypty w ukrytym folderze o nazwie .venv w bieżącym katalogu roboczym:

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

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

Aby użyć tych skryptów do aktywowania tego venv środowiska, zobacz Jak działają venvs.

Przejdź do sekcji Konfigurowanie klienta.

Aktywowanie środowiska wirtualnego języka Python za pomocą poezji

  1. Zainstaluj poezję, jeśli jeszcze tego nie zrobiono.

  2. Jeśli używasz poezji na maszynie deweloperów, a klaster korzysta z języka Python 3.10, musisz utworzyć środowisko wirtualne Poezja w tej wersji. Z katalogu głównego istniejącego projektu kodu w języku Python poinstruuj poetry , aby zainicjować projekt kodu języka Python dla poezji, uruchamiając następujące polecenie:

    poetry init

  3. Poezja wyświetla kilka monitów o ukończenie. Żadne z tych monitów nie są specyficzne dla usługi Databricks Połączenie. Aby uzyskać informacje o tych monitach, zobacz init.

  4. Po zakończeniu monitów poezja dodaje pyproject.toml plik do projektu języka Python. Aby uzyskać informacje o pyproject.toml pliku, zobacz plik pyproject.toml.

  5. Z katalogu głównego projektu kodu języka Python poinstruuj poetry , aby odczytać pyproject.toml plik, rozwiązać zależności i zainstalować je, utworzyć poetry.lock plik, aby zablokować zależności, a na koniec utworzyć środowisko wirtualne. Aby to zrobić, uruchom następujące polecenie:

    poetry install

  6. Z katalogu głównego projektu kodu języka Python poinstruuj poetry , aby aktywować środowisko wirtualne i wprowadzić powłokę. Aby to zrobić, uruchom następujące polecenie:

    poetry shell

Będziesz wiedzieć, że środowisko wirtualne jest aktywowane, a powłoka jest wprowadzana, gdy nazwa środowiska wirtualnego jest wyświetlana w nawiasach tuż przed monitem terminalu, na przykład (my-project-py3.10).

Aby dezaktywować środowisko wirtualne i zamknąć powłokę w dowolnym momencie, uruchom polecenie exit.

Będziesz wiedzieć, że powłoka została zakończona, gdy nazwa środowiska wirtualnego nie będzie już wyświetlana w nawiasach tuż przed monitem terminalu.

Aby uzyskać więcej informacji na temat tworzenia środowisk wirtualnych poezji i zarządzania nimi, zobacz Zarządzanie środowiskami.

Konfigurowanie klienta

Napiwek

Jeśli masz już zainstalowane rozszerzenie usługi Databricks dla programu Visual Studio Code, nie musisz wykonywać tych instrukcji konfiguracji.

Rozszerzenie databricks dla programu Visual Studio Code ma już wbudowaną obsługę usługi Databricks Połączenie dla środowiska Databricks Runtime 13.0 lub nowszego. Przejdź do sekcji Debugowanie kodu przy użyciu usługi Databricks Połączenie dla rozszerzenia usługi Databricks dla programu Visual Studio Code.

Po spełnieniu wymagań dotyczących usługi Databricks Połączenie wykonaj następujące kroki, aby skonfigurować klienta usługi Databricks Połączenie.

Krok 1. Instalowanie klienta usługi Databricks Połączenie

W tych sekcjach opisano sposób instalowania klienta usługi Databricks Połączenie z venv lub Poezja.

Instalowanie klienta usługi Databricks Połączenie za pomocą oprogramowania venv

  1. Po aktywowaniu środowiska wirtualnego odinstaluj narzędzie PySpark, jeśli jest już zainstalowane, uruchamiając uninstall polecenie . Jest to wymagane, ponieważ databricks-connect pakiet powoduje konflikt z narzędziem PySpark. Aby uzyskać szczegółowe informacje, zobacz Konflikt instalacji PySpark. Aby sprawdzić, czy program PySpark jest już zainstalowany, uruchom show polecenie .

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Po aktywowaniu środowiska wirtualnego zainstaluj klienta usługi Databricks Połączenie, uruchamiając install polecenie . --upgrade Użyj opcji , aby uaktualnić dowolną istniejącą instalację klienta do określonej wersji.

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

    Uwaga

    Usługa Databricks zaleca dołączenie notacji "kropka-gwiazdka", aby określić databricks-connect==X.Y.* zamiast databricks-connect=X.Y, aby upewnić się, że zainstalowano najnowszy pakiet. Chociaż nie jest to wymagane, pomaga upewnić się, że możesz używać najnowszych obsługiwanych funkcji dla tego klastra.

Przejdź do kroku 2. Konfigurowanie właściwości połączenia.

Instalowanie klienta usługi Databricks Połączenie za pomocą poezji

  1. Po aktywowaniu środowiska wirtualnego odinstaluj narzędzie PySpark, jeśli jest już zainstalowane, uruchamiając remove polecenie . Jest to wymagane, ponieważ databricks-connect pakiet powoduje konflikt z narzędziem PySpark. Aby uzyskać szczegółowe informacje, zobacz Konflikt instalacji PySpark. Aby sprawdzić, czy program PySpark jest już zainstalowany, uruchom show polecenie .

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Po aktywowaniu środowiska wirtualnego zainstaluj klienta usługi Databricks Połączenie, uruchamiając add polecenie .

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

    Uwaga

    Usługa Databricks zaleca użycie notacji "at-tilde", aby określić databricks-connect@~14.0 zamiast databricks-connect==14.0, aby upewnić się, że najnowszy pakiet jest zainstalowany. Chociaż nie jest to wymagane, pomaga upewnić się, że możesz używać najnowszych obsługiwanych funkcji dla tego klastra.

Krok 2. Konfigurowanie właściwości połączenia

W tej sekcji skonfigurujesz właściwości w celu nawiązania połączenia między usługą Databricks Połączenie a zdalnym klastrem usługi Azure Databricks. Te właściwości obejmują ustawienia uwierzytelniania usługi Databricks Połączenie w klastrze.

W przypadku usługi Databricks Połączenie dla środowiska Databricks Runtime 13.1 lub nowszego usługa Databricks Połączenie zawiera zestaw SDK usługi Databricks dla języka Python. Ten zestaw SDK implementuje ujednolicony standard uwierzytelniania klienta usługi Databricks, skonsolidowane i spójne podejście architektoniczne i programowe do uwierzytelniania. Takie podejście sprawia, że konfigurowanie i automatyzowanie uwierzytelniania za pomocą usługi Azure Databricks jest bardziej scentralizowane i przewidywalne. Umożliwia ona skonfigurowanie uwierzytelniania usługi Azure Databricks raz, a następnie użycie tej konfiguracji w wielu narzędziach i zestawach SDK usługi Azure Databricks bez dalszych zmian konfiguracji uwierzytelniania.

Uwaga

  • Uwierzytelnianie typu użytkownik-komputer (U2M) protokołu OAuth jest obsługiwane w zestawie SDK usługi Databricks dla języka Python w wersji 0.19.0 lub nowszej. Może być konieczne zaktualizowanie zainstalowanej wersji zestawu SDK usługi Databricks dla języka Python do wersji 0.19.0 lub nowszej w celu użycia uwierzytelniania OAuth U2M. Zobacz Wprowadzenie do zestawu SDK usługi Databricks dla języka Python.

    W przypadku uwierzytelniania OAuth U2M należy użyć interfejsu wiersza polecenia usługi Databricks do uwierzytelnienia przed uruchomieniem kodu w języku Python. Zobacz Samouczek.

  • Uwierzytelnianie OAuth maszynowo-maszynowe (M2M) uwierzytelnianie maszynowo-maszynowe OAuth (M2M) jest obsługiwane w zestawie SDK usługi Databricks dla języka Python w wersji 0.18.0 lub nowszej. Aby użyć uwierzytelniania OAuth M2M, może być konieczne zaktualizowanie zainstalowanej wersji zestawu SDK usługi Databricks dla języka Python do wersji 0.18.0 lub nowszej. Zobacz Wprowadzenie do zestawu SDK usługi Databricks dla języka Python.

  • Zestaw SDK usługi Databricks dla języka Python nie zaimplementował jeszcze uwierzytelniania tożsamości zarządzanych platformy Azure.

  • Usługa Databricks Połączenie dla środowiska Databricks Runtime 13.0 obsługuje tylko uwierzytelnianie osobistego tokenu dostępu usługi Azure Databricks.

  1. Zbierz następujące właściwości konfiguracji.

  2. Skonfiguruj połączenie w kodzie. Usługa Databricks Połączenie wyszukuje właściwości konfiguracji w następującej kolejności do momentu ich znalezienia. Po znalezieniu ich przestanie przeszukiwać pozostałe opcje. Szczegóły każdej opcji zostaną wyświetlone po poniższej tabeli:

    Opcja właściwości konfiguracji Dotyczy
    1. DatabricksSession Metoda klasy remote() Uwierzytelnianie tylko osobistego tokenu dostępu w usłudze Azure Databricks
    2. Profil konfiguracji usługi Azure Databricks Wszystkie typy uwierzytelniania usługi Azure Databricks
    3. Zmienna SPARK_REMOTE środowiskowa Uwierzytelnianie tylko osobistego tokenu dostępu w usłudze Azure Databricks
    4. Zmienna DATABRICKS_CONFIG_PROFILE środowiskowa Wszystkie typy uwierzytelniania usługi Azure Databricks
    5. Zmienna środowiskowa dla każdej właściwości konfiguracji Wszystkie typy uwierzytelniania usługi Azure Databricks
    6. Profil konfiguracji usługi Azure Databricks o nazwie DEFAULT Wszystkie typy uwierzytelniania usługi Azure Databricks

    1. DatabricksSession Metoda klasy remote()

      W przypadku tej opcji, która ma zastosowanie tylko do uwierzytelniania osobistego tokenu dostępu usługi Azure Databricks, określ nazwę wystąpienia obszaru roboczego, osobisty token dostępu usługi Azure Databricks oraz identyfikator klastra.

      Klasę DatabricksSession można zainicjować na kilka sposobów w następujący sposób:

      • hostUstaw pola , tokeni cluster_id w pliku DatabricksSession.builder.remote().
      • Użyj klasy zestawu SDK Config usługi Databricks.
      • Określ profil konfiguracji usługi Databricks wraz z polem cluster_id .
      • Ustaw Połączenie parametry połączenia Spark w pliku DatabricksSession.builder.remote().

      Usługa Databricks nie zaleca bezpośredniego określania tych właściwości połączenia w kodzie. Zamiast tego usługa Databricks zaleca konfigurowanie właściwości za pomocą zmiennych środowiskowych lub plików konfiguracji, zgodnie z opisem w tej sekcji. W poniższych przykładach kodu założono, że udostępniasz implementację proponowanych retrieve_* funkcji samodzielnie, aby uzyskać niezbędne właściwości od użytkownika lub z innego magazynu konfiguracji, takiego jak Azure KeyVault.

      Kod dla każdego z tych podejść jest następujący:

      # 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. Profil konfiguracji usługi Azure Databricks

      W przypadku tej opcji utwórz lub zidentyfikuj profil konfiguracji usługi Azure Databricks zawierający pole cluster_id i inne pola, które są niezbędne dla typu uwierzytelniania usługi Databricks, którego chcesz użyć.

      Wymagane pola profilu konfiguracji dla każdego typu uwierzytelniania są następujące:

      Następnie ustaw nazwę tego profilu konfiguracji za pomocą Config klasy .

      Możesz określić cluster_id na kilka sposobów w następujący sposób:

      • Uwzględnij cluster_id pole w profilu konfiguracji, a następnie po prostu określ nazwę profilu konfiguracji.
      • Określ nazwę profilu konfiguracji wraz z polem cluster_id .

      Jeśli zmienna DATABRICKS_CLUSTER_ID środowiskowa jest już ustawiona przy użyciu identyfikatora klastra, nie trzeba również określać zmiennej cluster_id.

      Kod dla każdego z tych podejść jest następujący:

      # 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. Zmienna SPARK_REMOTE środowiskowa

      W przypadku tej opcji, która dotyczy tylko uwierzytelniania osobistego tokenu dostępu usługi Azure Databricks, ustaw SPARK_REMOTE zmienną środowiskową na następujący ciąg, zastępując symbole zastępcze odpowiednimi wartościami.

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

      Następnie zainicjuj klasę DatabricksSession w następujący sposób:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

    4. Zmienna DATABRICKS_CONFIG_PROFILE środowiskowa

      W przypadku tej opcji utwórz lub zidentyfikuj profil konfiguracji usługi Azure Databricks zawierający pole cluster_id i inne pola, które są niezbędne dla typu uwierzytelniania usługi Databricks, którego chcesz użyć.

      Jeśli zmienna DATABRICKS_CLUSTER_ID środowiskowa jest już ustawiona przy użyciu identyfikatora klastra, nie trzeba również określać zmiennej cluster_id.

      Wymagane pola profilu konfiguracji dla każdego typu uwierzytelniania są następujące:

      Ustaw zmienną DATABRICKS_CONFIG_PROFILE środowiskową na nazwę tego profilu konfiguracji. Następnie zainicjuj klasę DatabricksSession w następujący sposób:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

    5. Zmienna środowiskowa dla każdej właściwości konfiguracji

      Dla tej opcji ustaw zmienną DATABRICKS_CLUSTER_ID środowiskową i wszelkie inne zmienne środowiskowe, które są niezbędne dla typu uwierzytelniania usługi Databricks, którego chcesz użyć.

      Wymagane zmienne środowiskowe dla każdego typu uwierzytelniania są następujące:

      Następnie zainicjuj klasę DatabricksSession w następujący sposób:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

    6. Profil konfiguracji usługi Azure Databricks o nazwie DEFAULT

      W przypadku tej opcji utwórz lub zidentyfikuj profil konfiguracji usługi Azure Databricks zawierający pole cluster_id i inne pola, które są niezbędne dla typu uwierzytelniania usługi Databricks, którego chcesz użyć.

      Jeśli zmienna DATABRICKS_CLUSTER_ID środowiskowa jest już ustawiona przy użyciu identyfikatora klastra, nie trzeba również określać zmiennej cluster_id.

      Wymagane pola profilu konfiguracji dla każdego typu uwierzytelniania są następujące:

      Nadaj nazwę temu profilowi DEFAULTkonfiguracji .

      Następnie zainicjuj klasę DatabricksSession w następujący sposób:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

  3. Weryfikowanie środowiska i połączenia z klastrem usługi Databricks

    • Następujące polecenie sprawdzi, czy środowisko, domyślne poświadczenia i połączenie z klastrem są poprawnie skonfigurowane dla usługi Databricks Połączenie.

      databricks-connect test

      To polecenie pobiera domyślne poświadczenia skonfigurowane w środowisku (takie jak DEFAULT profil konfiguracji lub zmienne środowiskowe).

      Polecenie kończy się niepowodzeniem z kodem zakończenia innym niż zero i odpowiadającym mu komunikatem o błędzie podczas wykrywania niezgodności w instalacji.

    • Ponadto możesz również użyć powłoki dołączonej pyspark do usługi Databricks Połączenie dla języka Python. Uruchom powłokę, uruchamiając polecenie:

      pyspark

      Zostanie wyświetlona powłoka Spark, na przykład:

      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'.
>>>

      >>> W wierszu polecenia uruchom proste polecenie PySpark, takie jak spark.range(1,10).show(). Jeśli nie ma żadnych błędów, połączenie zostało pomyślnie nawiązane.

      Jeśli połączenie zostało pomyślnie nawiązane, aby zatrzymać powłokę Spark, naciśnij klawisz Ctrl + d lub Ctrl + z, lub uruchom polecenie quit() lub exit().

      Aby uzyskać więcej informacji na databricks-connect temat pliku binarnego, zobacz Zaawansowane użycie usługi Databricks Połączenie dla języka Python