Sdílet prostřednictvím

Instalace Připojení Databricks pro Python

  • Článek

Poznámka:

Tento článek se zabývá Připojení Databricks pro Databricks Runtime 13.0 a vyšší.

Tento článek popisuje, jak nainstalovat Databricks Připojení pro Python. Podívejte se, co je Databricks Připojení?. Informace o verzi Scala tohoto článku najdete v tématu Instalace Připojení Databricks pro Scala.

Požadavky

  • Váš cílový pracovní prostor a cluster Azure Databricks musí splňovat požadavky na konfiguraci clusteru pro Připojení Databricks.

  • Na vývojový počítač musíte nainstalovat Python 3 a podverze klientské instalace Pythonu musí být stejná jako podverze pythonové verze vašeho clusteru Azure Databricks. Pokud chcete najít podverzi Pythonu vašeho clusteru, přečtěte si část Systémové prostředí poznámky k verzi databricks Runtime pro váš cluster. Viz poznámky k verzi databricks Runtime a verze kompatibility.

    Poznámka:

    Pokud chcete používat funkce definované uživatelem PySpark, je důležité, aby nainstalovaná podverze Pythonu vašeho vývojového počítače odpovídala podverzi Pythonu, která je součástí modulu Databricks Runtime nainstalovaného v clusteru.

  • Verze hlavního a podverze balíčku Databricks Připojení by měla odpovídat vaší verzi Databricks Runtime. Databricks doporučuje vždy používat nejnovější balíček databricks Připojení, který odpovídá vaší verzi Databricks Runtime. Pokud například používáte cluster Databricks Runtime 14.0, měli byste také použít 14.0 verzi databricks-connect balíčku.

    Poznámka:

    Seznam dostupných verzí Databricks Připojení aktualizací a aktualizací údržby najdete v Připojení poznámkách k verzi Databricks.

    Použití nejnovějšího balíčku Databricks Připojení, který odpovídá vaší verzi Databricks Runtime, není požadavek. Pro Databricks Runtime 13.3 LTS a vyšší můžete použít balíček Databricks Připojení pro všechny verze Databricks Runtime v nebo vyšší verzi balíčku Databricks Připojení. Pokud ale chcete používat funkce, které jsou k dispozici v novějších verzích databricks Runtime, musíte odpovídajícím způsobem upgradovat balíček Databricks Připojení.

  • Databricks důrazně doporučuje, abyste pro každou verzi Pythonu, kterou používáte s Připojení Databricks, aktivovalo virtuální prostředí Pythonu. Virtuální prostředí Pythonu pomáhají zajistit, abyste společně používali správné verze Pythonu a Databricks Připojení. To může pomoct snížit nebo zkrátit řešení souvisejících technických problémů. V následujících částech se dozvíte, jak aktivovat virtuální prostředí Pythonu pro venv básně nebo básně. Další informace o těchto nástrojích naleznete v tématu venv nebo Báseň.

Aktivace virtuálního prostředí Pythonu pomocí venv

Pokud používáte venv na vývojovém počítači a váš cluster používá Python 3.10, musíte vytvořit prostředí s danou venv verzí. Následující ukázkový příkaz vygeneruje skripty pro aktivaci venv prostředí pomocí Pythonu 3.10 a tento příkaz pak tyto skripty umístí do skryté složky pojmenované .venv v aktuálním pracovním adresáři:

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

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

Pokud chcete tyto skripty použít k aktivaci tohoto venv prostředí, přečtěte si, jak venvs fungují.

Přeskočte dopředu a nastavte klienta.

Aktivace virtuálního prostředí Pythonu pomocí poetie

  1. Nainstalujte básně, pokud jste to ještě neudělali.

  2. Pokud na vývojovém počítači používáte poetii a cluster používá Python 3.10, musíte vytvořit virtuální prostředí básně s danou verzí. V kořenovém adresáři existujícího projektu kódu Pythonu spusťte následující příkaz, který poetry inicializuje projekt kódu Pythonu pro básně:

    poetry init

  3. Básně zobrazuje několik výzev k dokončení. Žádná z těchto výzev není specifická pro Připojení Databricks. Informace o těchto výzev najdete v tématu init.

  4. Po dokončení výzev přidá do projektu Pythonu soubor.pyproject.toml Informace o pyproject.toml souboru naleznete v souboru pyproject.toml.

  5. Z kořenového adresáře projektu kódu Pythonu dejte pokyn poetry ke čtení pyproject.toml souboru, vyřešte závislosti a nainstalujte je, vytvořte poetry.lock soubor pro uzamčení závislostí a nakonec vytvořte virtuální prostředí. Provedete to spuštěním následujícího příkazu:

    poetry install

  6. V kořenovém adresáři projektu kódu Pythonu požádejte poetry o aktivaci virtuálního prostředí a zadání prostředí. Provedete to spuštěním následujícího příkazu:

    poetry shell

Budete vědět, že je vaše virtuální prostředí aktivováno a prostředí se zadá, když se název virtuálního prostředí zobrazí v závorkách těsně před výzvou k terminálu, například (my-project-py3.10).

Pokud chcete virtuální prostředí deaktivovat a kdykoli ukončit prostředí, spusťte příkaz exit.

Budete vědět, že jste ukončili prostředí, když se název virtuálního prostředí už nezobrazuje v závorkách těsně před výzvou terminálu.

Další informace o vytváření a správě virtuálních prostředí básní najdete v tématu Správa prostředí.

Nastavení klienta

Tip

Pokud už máte nainstalované rozšíření Databricks pro Visual Studio Code, nemusíte postupovat podle těchto pokynů k nastavení.

Rozšíření Databricks pro Visual Studio Code už má integrovanou podporu pro Databricks Připojení pro Databricks Runtime 13.0 a vyšší. Přeskočte k ladění kódu pomocí databricks Připojení pro rozšíření Databricks pro Visual Studio Code.

Jakmile splníte požadavky Připojení Databricks, proveďte následující kroky a nastavte klienta Připojení Databricks.

Krok 1: Instalace klienta Připojení Databricks

Tato část popisuje, jak nainstalovat klienta Databricks Připojení venv nebo básní.

Instalace klienta Připojení Databricks s venv

  1. Po aktivaci virtuálního prostředí odinstalujte PySpark spuštěním uninstall příkazu. To je povinné, protože databricks-connect balíček je v konfliktu s PySpark. Podrobnosti najdete v tématu Konfliktní instalace PySpark. Pokud chcete zkontrolovat, jestli je PySpark už nainstalovaný, spusťte show příkaz.

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Pokud je vaše virtuální prostředí stále aktivované, nainstalujte klienta Připojení Databricks spuštěním install příkazu. --upgrade Pomocí možnosti upgradujte jakoukoli existující instalaci klienta na zadanou verzi.

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

    Poznámka:

    Databricks doporučuje, abyste místo něj databricks-connect==X.Y.*databricks-connect=X.Ypřipojili notaci dot-asterisk, abyste měli jistotu, že je nainstalovaný nejnovější balíček. I když to není požadavek, pomůže vám to zajistit, abyste pro tento cluster mohli používat nejnovější podporované funkce.

Přeskočte dopředu ke kroku 2: Konfigurace vlastností připojení.

Instalace klienta Připojení Databricks s básní

  1. Po aktivaci virtuálního prostředí odinstalujte PySpark spuštěním remove příkazu. To je povinné, protože databricks-connect balíček je v konfliktu s PySpark. Podrobnosti najdete v tématu Konfliktní instalace PySpark. Pokud chcete zkontrolovat, jestli je PySpark už nainstalovaný, spusťte show příkaz.

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Pokud je vaše virtuální prostředí stále aktivované, nainstalujte klienta Připojení Databricks spuštěním add příkazu.

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

    Poznámka:

    Databricks doporučuje, abyste místo databricks-connect@~14.0databricks-connect==14.0toho použili notaci at-tilde, abyste měli jistotu, že je nainstalovaný nejnovější balíček. I když to není požadavek, pomůže vám to zajistit, abyste pro tento cluster mohli používat nejnovější podporované funkce.

Krok 2: Konfigurace vlastností připojení

V této části nakonfigurujete vlastnosti pro navázání připojení mezi Připojení Databricks a vzdáleným clusterem Azure Databricks. Mezi tyto vlastnosti patří nastavení pro ověření Připojení Databricks ve vašem clusteru.

Pro Databricks Připojení pro Databricks Runtime 13.1 a novější obsahuje Databricks Připojení sadu Databricks SDK pro Python. Tato sada SDK implementuje standard sjednoceného ověřování klienta Databricks, konsolidovaný a konzistentní přístup k ověřování prostřednictvím architektury a kódu programu. Díky tomuto přístupu je nastavení a automatizace ověřování pomocí Azure Databricks centralizovanější a předvídatelnější. Umožňuje nakonfigurovat ověřování Azure Databricks jednou a pak tuto konfiguraci použít napříč několika nástroji a sadami SDK Azure Databricks bez dalších změn konfigurace ověřování.

Poznámka:

  • Ověřování uživateleM (U2M) OAuth se podporuje v sadě Databricks SDK pro Python 0.19.0 a novější. Možná budete muset aktualizovat nainstalovanou verzi sady Databricks SDK pro Python na verzi 0.19.0 nebo vyšší, aby bylo možné použít ověřování OAuth U2M. Viz Začínáme se sadou Databricks SDK pro Python.

    Pro ověřování OAuth U2M musíte před spuštěním kódu Pythonu použít rozhraní příkazového řádku Databricks k ověření. Podívejte se na kurz.

  • Ověřování OAuth typu machine-to-machine (M2M) ověřování OAuth na počítači (M2M) je podporováno v sadě Databricks SDK pro Python 0.18.0 a vyšší. Abyste mohli použít ověřování OAuth M2M, budete možná muset aktualizovat nainstalovanou verzi sady Databricks SDK pro Python na verzi 0.18.0 nebo vyšší. Viz Začínáme se sadou Databricks SDK pro Python.

  • Sada Databricks SDK pro Python zatím neimplementovala ověřování spravovaných identit Azure.

  • Databricks Připojení pro Databricks Runtime 13.0 podporuje pouze ověřování osobního přístupového tokenu Azure Databricks pro ověřování.

  1. Shromážděte následující vlastnosti konfigurace.

    • Název instance pracovního prostoru Azure Databricks. Je to stejné jako hodnota názvu hostitele serveru pro váš cluster. Podrobnosti o připojení pro výpočetní prostředek Azure Databricks najdete v tématu Získání podrobností o připojení.
    • ID clusteru. ID clusteru můžete získat z adresy URL. Viz adresa URL a ID clusteru.
    • Všechny další vlastnosti, které jsou nezbytné pro podporovaný typ ověřování Databricks, který chcete použít. Tyto vlastnosti jsou popsány v této části.

  2. Nakonfigurujte připojení v kódu. Databricks Připojení vyhledá vlastnosti konfigurace v následujícím pořadí, dokud je nenajde. Jakmile je najde, přestane prohledávat zbývající možnosti. Podrobnosti o jednotlivých možnostech se zobrazí za následující tabulkou:

    Možnost vlastností konfigurace Platí pro
    1. Metoda DatabricksSession třídy remote() Pouze ověřování tokenů pat azure Databricks
    2. Konfigurační profil Azure Databricks Všechny typy ověřování Azure Databricks
    3. Proměnná SPARK_REMOTE prostředí Pouze ověřování tokenů pat azure Databricks
    4. Proměnná DATABRICKS_CONFIG_PROFILE prostředí Všechny typy ověřování Azure Databricks
    5. Proměnná prostředí pro každou vlastnost konfigurace Všechny typy ověřování Azure Databricks
    6. Konfigurační profil Azure Databricks s názvem DEFAULT Všechny typy ověřování Azure Databricks

    1. DatabricksSession Metoda třídy remote()

      Pro tuto možnost, která se vztahuje pouze na ověřování osobního přístupového tokenu Azure Databricks, zadejte název instance pracovního prostoru, osobní přístupový token Azure Databricks a ID clusteru.

      Třídu můžete inicializovat DatabricksSession několika způsoby následujícím způsobem:

      • Nastavte pole hosta tokencluster_id pole v DatabricksSession.builder.remote().
      • Použijte třídu sady Databricks SDK Config .
      • Zadejte konfigurační profil Databricks spolu s polem cluster_id .
      • Nastavte Připojení připojovací řetězec Sparku v DatabricksSession.builder.remote()souboru .

      Databricks nedoporučuje přímo zadávat tyto vlastnosti připojení v kódu. Databricks místo toho doporučuje konfigurovat vlastnosti prostřednictvím proměnných prostředí nebo konfiguračních souborů, jak je popsáno v této části. Následující příklady kódu předpokládají, že zadáte určitou implementaci navrhovaných retrieve_* funkcí sami, abyste získali potřebné vlastnosti od uživatele nebo z jiného úložiště konfigurace, jako je Azure KeyVault.

      Kód pro každý z těchto přístupů je následující:

      # 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. Konfigurační profil Azure Databricks

      Pro tuto možnost vytvořte nebo identifikujte konfigurační profil Azure Databricks obsahující pole cluster_id a všechna další pole, která jsou nezbytná pro typ ověřování Databricks, který chcete použít.

      Pole požadovaného konfiguračního profilu pro každý typ ověřování jsou následující:

      • Pro ověřování osobního přístupového tokenu Azure Databricks: host a token.
      • Pro ověřování M2M (machine-to-machine) OAuth (kde je podporováno): host, client_ida client_secret.
      • Pro ověřování uživatele AAuth (U2M) (kde je to podporováno): host
      • Pro ověřování hostinstančního objektu služby Microsoft Entra ID (dříve Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secreta případně azure_workspace_resource_id.
      • Pro ověřování Azure CLI: host.
      • Ověřování spravovaných identit Azure (kde je podporováno): host, azure_use_msi, azure_client_id, a případně azure_workspace_resource_id.

      Potom nastavte název tohoto konfiguračního profilu prostřednictvím Config třídy.

      Můžete zadat cluster_id několika způsoby následujícím způsobem:

      • Do konfiguračního cluster_id profilu zahrňte pole a zadejte název konfiguračního profilu.
      • Zadejte název konfiguračního profilu spolu s polem cluster_id .

      Pokud jste již nastavili proměnnou DATABRICKS_CLUSTER_ID prostředí s ID clusteru, nemusíte také zadávat cluster_id.

      Kód pro každý z těchto přístupů je následující:

      # 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. Proměnná SPARK_REMOTE prostředí

      Pro tuto možnost, která se vztahuje pouze na ověřování tokenů pat pro Azure Databricks, nastavte SPARK_REMOTE proměnnou prostředí na následující řetězec a nahraďte zástupné symboly příslušnými hodnotami.

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

      Pak inicializovat DatabricksSession třídu následujícím způsobem:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

    4. Proměnná DATABRICKS_CONFIG_PROFILE prostředí

      Pro tuto možnost vytvořte nebo identifikujte konfigurační profil Azure Databricks obsahující pole cluster_id a všechna další pole, která jsou nezbytná pro typ ověřování Databricks, který chcete použít.

      Pokud jste již nastavili proměnnou DATABRICKS_CLUSTER_ID prostředí s ID clusteru, nemusíte také zadávat cluster_id.

      Pole požadovaného konfiguračního profilu pro každý typ ověřování jsou následující:

      • Pro ověřování osobního přístupového tokenu Azure Databricks: host a token.
      • Pro ověřování M2M (machine-to-machine) OAuth (kde je podporováno): host, client_ida client_secret.
      • Pro ověřování uživatele AAuth (U2M) (kde je to podporováno): host
      • Pro ověřování hostinstančního objektu služby Microsoft Entra ID (dříve Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secreta případně azure_workspace_resource_id.
      • Pro ověřování Azure CLI: host.
      • Ověřování spravovaných identit Azure (kde je podporováno): host, azure_use_msi, azure_client_id, a případně azure_workspace_resource_id.

      Nastavte proměnnou DATABRICKS_CONFIG_PROFILE prostředí na název tohoto konfiguračního profilu. Pak inicializovat DatabricksSession třídu následujícím způsobem:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

    5. Proměnná prostředí pro každou vlastnost konfigurace

      Pro tuto možnost nastavte proměnnou DATABRICKS_CLUSTER_ID prostředí a všechny další proměnné prostředí, které jsou nezbytné pro typ ověřování Databricks, který chcete použít.

      Požadované proměnné prostředí pro každý typ ověřování jsou následující:

      • Pro ověřování osobního přístupového tokenu Azure Databricks: DATABRICKS_HOST a DATABRICKS_TOKEN.
      • Pro ověřování M2M (machine-to-machine) OAuth (kde je podporováno): DATABRICKS_HOST, DATABRICKS_CLIENT_IDa DATABRICKS_CLIENT_SECRET.
      • Pro ověřování uživatele AAuth (U2M) (kde je to podporováno): DATABRICKS_HOST
      • Pro ověřování DATABRICKS_HOSTinstančního objektu služby Microsoft Entra ID (dříve Azure Active Directory): , ARM_TENANT_ID, ARM_CLIENT_IDARM_CLIENT_SECRETa případně DATABRICKS_AZURE_RESOURCE_ID.
      • Pro ověřování Azure CLI: DATABRICKS_HOST.
      • Ověřování spravovaných identit Azure (kde je podporováno): DATABRICKS_HOST, ARM_USE_MSI, ARM_CLIENT_ID, a případně DATABRICKS_AZURE_RESOURCE_ID.

      Pak inicializovat DatabricksSession třídu následujícím způsobem:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

    6. Konfigurační profil Azure Databricks s názvem DEFAULT

      Pro tuto možnost vytvořte nebo identifikujte konfigurační profil Azure Databricks obsahující pole cluster_id a všechna další pole, která jsou nezbytná pro typ ověřování Databricks, který chcete použít.

      Pokud jste již nastavili proměnnou DATABRICKS_CLUSTER_ID prostředí s ID clusteru, nemusíte také zadávat cluster_id.

      Pole požadovaného konfiguračního profilu pro každý typ ověřování jsou následující:

      • Pro ověřování osobního přístupového tokenu Azure Databricks: host a token.
      • Pro ověřování M2M (machine-to-machine) OAuth (kde je podporováno): host, client_ida client_secret.
      • Pro ověřování uživatele AAuth (U2M) (kde je to podporováno): host
      • Pro ověřování hostinstančního objektu služby Microsoft Entra ID (dříve Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secreta případně azure_workspace_resource_id.
      • Pro ověřování Azure CLI: host.
      • Ověřování spravovaných identit Azure (kde je podporováno): host, azure_use_msi, azure_client_id, a případně azure_workspace_resource_id.

      Pojmenujte tento konfigurační profil DEFAULT.

      Pak inicializovat DatabricksSession třídu následujícím způsobem:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

  3. Ověření prostředí a připojení ke clusteru Databricks

    • Následující příkaz ověří, že vaše prostředí, výchozí přihlašovací údaje a připojení ke clusteru jsou správně nastavené pro databricks Připojení.

      databricks-connect test

      Tento příkaz vybere výchozí přihlašovací údaje nakonfigurované v prostředí (například DEFAULT konfigurační profil nebo prostřednictvím proměnných prostředí).

      Příkaz selže s nenulovým ukončovacím kódem a odpovídající chybovou zprávou, když zjistí případné nekompatibilitu v instalačním programu.

    • Kromě toho můžete také použít pyspark prostředí, které je součástí Připojení Databricks pro Python. Spuštěním následujícího příkazu spusťte prostředí:

      pyspark

      Zobrazí se prostředí Spark, například:

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

      Na příkazovém >>> řádku spusťte jednoduchý příkaz PySpark, například spark.range(1,10).show(). Pokud nedošlo k žádným chybám, úspěšně jste se připojili.

      Pokud jste se úspěšně připojili, zastavte prostředí Spark, stiskněte Ctrl + d nebo Ctrl + znebo spusťte příkaz quit() nebo exit().

      Další podrobnosti o binárním databricks-connect souboru najdete v tématu Pokročilé využití služby Databricks Připojení pro Python.