Condividi tramite

Installare i Connessione di Databricks per Python

  • Articolo

Nota

Questo articolo illustra databricks Connessione per Databricks Runtime 13.0 e versioni successive.

Questo articolo descrive come installare databricks Connessione per Python. Vedere Che cos'è Databricks Connessione?. Per la versione scala di questo articolo, vedere Installare Databricks Connessione per Scala.

Requisiti

  • L'area di lavoro e il cluster di Azure Databricks di destinazione devono soddisfare i requisiti per la configurazione del cluster per Databricks Connessione.

  • È necessario installare Python 3 nel computer di sviluppo e la versione secondaria dell'installazione di Python client deve corrispondere alla versione secondaria di Python del cluster Azure Databricks. Per trovare la versione secondaria di Python del cluster, vedere la sezione "Ambiente di sistema" delle note sulla versione di Databricks Runtime per il cluster. Vedere Versioni e compatibilità delle note sulla versione di Databricks Runtime.

    Nota

    Se si vogliono usare le funzioni definite dall'utente pySpark, è importante che la versione secondaria del computer di sviluppo del computer di sviluppo corrisponda alla versione secondaria di Python inclusa in Databricks Runtime installata nel cluster.

  • Databricks Connessione versione principale e secondaria del pacchetto deve corrispondere alla versione di Databricks Runtime. Databricks consiglia di usare sempre il pacchetto più recente di Databricks Connessione che corrisponde alla versione di Databricks Runtime. Ad esempio, quando si usa un cluster Databricks Runtime 14.0, è necessario usare anche la 14.0 versione del databricks-connect pacchetto.

    Nota

    Per un elenco delle versioni disponibili di Databricks Connessione aggiornamenti della manutenzione, vedere le note sulla versione di Databricks Connessione.

    L'uso del pacchetto più recente di Databricks Connessione che corrisponde alla versione di Databricks Runtime non è un requisito. Per Databricks Runtime 13.3 LTS e versioni successive, è possibile usare il pacchetto databricks Connessione su tutte le versioni di Databricks Runtime in o versioni successive alla versione del pacchetto di databricks Connessione. Tuttavia, se si vogliono usare le funzionalità disponibili nelle versioni successive di Databricks Runtime, è necessario aggiornare di conseguenza il pacchetto databricks Connessione.

  • Databricks consiglia vivamente di avere un ambiente virtuale Python attivato per ogni versione di Python usata con Databricks Connessione. Gli ambienti virtuali Python consentono di assicurarsi di usare le versioni corrette di Python e Databricks Connessione insieme. Ciò consente di ridurre o ridurre la risoluzione dei problemi tecnici correlati. Vedere come attivare un ambiente virtuale Python per venv o Poesia nelle sezioni seguenti. Per altre informazioni su questi strumenti, vedere venv o Poetry.

Attivare un ambiente virtuale Python con venv

Se si usa venv nel computer di sviluppo e il cluster esegue Python 3.10, è necessario creare un venv ambiente con tale versione. Il comando di esempio seguente genera gli script per attivare un venv ambiente con Python 3.10 e questo comando inserisce tali script all'interno di una cartella nascosta denominata .venv all'interno della directory di lavoro corrente:

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

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

Per usare questi script per attivare questo venv ambiente, vedere Funzionamento di venvs.

Andare avanti per Configurare il client.

Attivare un ambiente virtuale Python con Poesia

  1. Installa Poesia, se non l'hai già fatto.

  2. Se si usa Poetry nel computer di sviluppo e il cluster esegue Python 3.10, è necessario creare un ambiente virtuale Poetry con tale versione. Dalla directory radice del progetto di codice Python esistente, indicare poetry di inizializzare il progetto di codice Python per Poetry eseguendo il comando seguente:

    poetry init

  3. La poesia mostra diverse richieste per voi di completare. Nessuno di questi prompt è specifico di Databricks Connessione. Per informazioni su queste richieste, vedere init.

  4. Dopo aver completato le richieste, Poetry aggiunge un pyproject.toml file al progetto Python. Per informazioni sul pyproject.toml file, vedere Il file pyproject.toml.

  5. Dalla directory radice del progetto di codice Python, indicare poetry di leggere il pyproject.toml file, risolvere le dipendenze e installarle, creare un poetry.lock file per bloccare le dipendenze e infine creare un ambiente virtuale. A tale scopo, usare il comando seguente:

    poetry install

  6. Dalla directory radice del progetto di codice Python, indicare poetry di attivare l'ambiente virtuale e immettere la shell. A tale scopo, usare il comando seguente:

    poetry shell

Si sa che l'ambiente virtuale è attivato e che la shell viene immessa quando il nome dell'ambiente virtuale viene visualizzato tra parentesi appena prima del prompt del terminale, ad esempio (my-project-py3.10).

Per disattivare l'ambiente virtuale e uscire dalla shell in qualsiasi momento, eseguire il comando exit.

Si saprà che è stata chiusa la shell quando il nome dell'ambiente virtuale non viene più visualizzato tra parentesi prima del prompt del terminale.

Per altre informazioni sulla creazione e la gestione di ambienti virtuali Di poesia, vedere Gestione degli ambienti.

Configurare il client

Suggerimento

Se è già installata l'estensione Databricks per Visual Studio Code, non è necessario seguire queste istruzioni di installazione.

L'estensione Databricks per Visual Studio Code include già il supporto predefinito per Databricks Connessione per Databricks Runtime 13.0 e versioni successive. Passare a Eseguire il debug del codice usando Databricks Connessione per l'estensione Databricks per Visual Studio Code.

Dopo aver soddisfatto i requisiti per Databricks Connessione, completare i passaggi seguenti per configurare il client di databricks Connessione.

Passaggio 1: Installare il client di databricks Connessione

In questa sezione viene descritto come installare il client di databricks Connessione con venv o Poetry.

Installare il client di Connessione Databricks con venv

  1. Dopo aver attivato l'ambiente virtuale, disinstallare PySpark, se è già installato, eseguendo il uninstall comando . Questa operazione è necessaria perché il databricks-connect pacchetto è in conflitto con PySpark. Per informazioni dettagliate, vedere Installazioni di PySpark in conflitto. Per verificare se PySpark è già installato, eseguire il show comando .

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Con l'ambiente virtuale ancora attivato, installare il client databricks Connessione eseguendo il install comando . Usare l'opzione --upgrade per aggiornare qualsiasi installazione client esistente alla versione specificata.

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

    Nota

    Databricks consiglia di aggiungere la notazione "dot-asterisk" per specificare databricks-connect==X.Y.* invece di databricks-connect=X.Y, per assicurarsi che il pacchetto più recente sia installato. Anche se questo non è un requisito, consente di assicurarsi di poter usare le funzionalità supportate più recenti per tale cluster.

Passare al passaggio 2: Configurare le proprietà di connessione.

Installare il client di databricks Connessione con Poesia

  1. Dopo aver attivato l'ambiente virtuale, disinstallare PySpark, se è già installato, eseguendo il remove comando . Questa operazione è necessaria perché il databricks-connect pacchetto è in conflitto con PySpark. Per informazioni dettagliate, vedere Installazioni di PySpark in conflitto. Per verificare se PySpark è già installato, eseguire il show comando .

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Con l'ambiente virtuale ancora attivato, installare il client databricks Connessione eseguendo il add comando .

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

    Nota

    Databricks consiglia di usare la notazione "at-tilde" per specificare databricks-connect@~14.0 invece di databricks-connect==14.0, per assicurarsi che il pacchetto più recente sia installato. Anche se questo non è un requisito, consente di assicurarsi di poter usare le funzionalità supportate più recenti per tale cluster.

Passaggio 2: Configurare le proprietà di connessione

In questa sezione vengono configurate le proprietà per stabilire una connessione tra Databricks Connessione e il cluster Azure Databricks remoto. Queste proprietà includono le impostazioni per autenticare databricks Connessione con il cluster.

Per Databricks Connessione per Databricks Runtime 13.1 e versioni successive, Databricks Connessione include Databricks SDK per Python. Questo SDK implementa lo standard di autenticazione unificata del client Databricks, un approccio architetturale e programmatico consolidato e coerente all'autenticazione. Questo approccio consente di configurare e automatizzare l'autenticazione con Azure Databricks più centralizzato e prevedibile. Consente di configurare l'autenticazione di Azure Databricks una sola volta e quindi di usarla in più strumenti e SDK di Azure Databricks senza ulteriori modifiche alla configurazione dell'autenticazione.

Nota

  • L'autenticazione da utente a computer (U2M) OAuth è supportata in Databricks SDK per Python 0.19.0 e versioni successive. Potrebbe essere necessario aggiornare la versione installata del progetto di codice di Databricks SDK per Python alla versione 0.19.0 o successiva per usare l'autenticazione U2M OAuth. Vedere Introduzione all'SDK di Databricks per Python.

    Per l'autenticazione U2M OAuth, è necessario usare l'interfaccia della riga di comando di Databricks per eseguire l'autenticazione prima di eseguire il codice Python. Vedere l'esercitazione.

  • L'autenticazione OAuth da computer a computer (M2M) OAuth da computer a computer (M2M) è supportata in Databricks SDK per Python 0.18.0 e versioni successive. Potrebbe essere necessario aggiornare la versione installata del progetto di codice di Databricks SDK per Python alla versione 0.18.0 o successiva per usare l'autenticazione OAuth M2M. Vedere Introduzione all'SDK di Databricks per Python.

  • Databricks SDK per Python non ha ancora implementato l'autenticazione delle identità gestite di Azure.

  • Databricks Connessione per Databricks Runtime 13.0 supporta solo l'autenticazione del token di accesso personale di Azure Databricks per l'autenticazione.

  1. Raccogliere le proprietà di configurazione seguenti.

  2. Configurare la connessione all'interno del codice. Databricks Connessione cerca le proprietà di configurazione nell'ordine seguente finché non le trova. Dopo averli trovati, smette di eseguire la ricerca nelle opzioni rimanenti. I dettagli per ogni opzione vengono visualizzati dopo la tabella seguente:

    Opzione proprietà di configurazione Si applica a
    1. Metodo DatabricksSession della remote() classe Solo autenticazione del token di accesso personale di Azure Databricks
    2. Un profilo di configurazione di Azure Databricks Tutti i tipi di autenticazione di Azure Databricks
    3. Variabile di SPARK_REMOTE ambiente Solo autenticazione del token di accesso personale di Azure Databricks
    4. Variabile di DATABRICKS_CONFIG_PROFILE ambiente Tutti i tipi di autenticazione di Azure Databricks
    5. Variabile di ambiente per ogni proprietà di configurazione Tutti i tipi di autenticazione di Azure Databricks
    6. Profilo di configurazione di Azure Databricks denominato DEFAULT Tutti i tipi di autenticazione di Azure Databricks

    1. Metodo DatabricksSession della remote() classe

      Per questa opzione, che si applica solo all'autenticazione del token di accesso personale di Azure Databricks, specificare il nome dell'istanza dell'area di lavoro, il token di accesso personale di Azure Databricks e l'ID del cluster.

      È possibile inizializzare la DatabricksSession classe in diversi modi, come indicato di seguito:

      • Impostare i hostcampi , tokene cluster_id in DatabricksSession.builder.remote().
      • Usare la classe di Config Databricks SDK.
      • Specificare un profilo di configurazione di Databricks insieme al cluster_id campo .
      • Impostare il Connessione stringa di connessione Spark in DatabricksSession.builder.remote().

      Databricks non consiglia di specificare direttamente queste proprietà di connessione nel codice. Databricks consiglia invece di configurare le proprietà tramite variabili di ambiente o file di configurazione, come descritto in questa sezione. Gli esempi di codice seguenti presuppongono che vengano fornite alcune implementazioni delle funzioni proposte retrieve_* per ottenere le proprietà necessarie dall'utente o da un altro archivio di configurazione, ad esempio Azure KeyVault.

      Il codice per ognuno di questi approcci è il seguente:

      # 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. Un profilo di configurazione di Azure Databricks

      Per questa opzione, creare o identificare un profilo di configurazione di Azure Databricks contenente il campo cluster_id e tutti gli altri campi necessari per il tipo di autenticazione di Databricks che si vuole usare.

      I campi del profilo di configurazione necessari per ogni tipo di autenticazione sono i seguenti:

      Impostare quindi il nome di questo profilo di configurazione tramite la Config classe .

      È possibile specificare cluster_id in alcuni modi, come indicato di seguito:

      • Includere il cluster_id campo nel profilo di configurazione e quindi specificare solo il nome del profilo di configurazione.
      • Specificare il nome del profilo di configurazione insieme al cluster_id campo .

      Se la variabile di ambiente è già stata impostata DATABRICKS_CLUSTER_ID con l'ID del cluster, non è necessario specificare cluster_idanche .

      Il codice per ognuno di questi approcci è il seguente:

      # 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. Variabile di SPARK_REMOTE ambiente

      Per questa opzione, che si applica solo all'autenticazione del token di accesso personale di Azure Databricks, impostare la SPARK_REMOTE variabile di ambiente sulla stringa seguente, sostituendo i segnaposto con i valori appropriati.

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

      Inizializzare quindi la DatabricksSession classe come segue:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo.

    4. Variabile di DATABRICKS_CONFIG_PROFILE ambiente

      Per questa opzione, creare o identificare un profilo di configurazione di Azure Databricks contenente il campo cluster_id e tutti gli altri campi necessari per il tipo di autenticazione di Databricks che si vuole usare.

      Se la variabile di ambiente è già stata impostata DATABRICKS_CLUSTER_ID con l'ID del cluster, non è necessario specificare cluster_idanche .

      I campi del profilo di configurazione necessari per ogni tipo di autenticazione sono i seguenti:

      Impostare la DATABRICKS_CONFIG_PROFILE variabile di ambiente sul nome di questo profilo di configurazione. Inizializzare quindi la DatabricksSession classe come segue:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo.

    5. Variabile di ambiente per ogni proprietà di configurazione

      Per questa opzione, impostare la DATABRICKS_CLUSTER_ID variabile di ambiente e tutte le altre variabili di ambiente necessarie per il tipo di autenticazione databricks che si vuole usare.

      Le variabili di ambiente necessarie per ogni tipo di autenticazione sono le seguenti:

      Inizializzare quindi la DatabricksSession classe come segue:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo.

    6. Profilo di configurazione di Azure Databricks denominato DEFAULT

      Per questa opzione, creare o identificare un profilo di configurazione di Azure Databricks contenente il campo cluster_id e tutti gli altri campi necessari per il tipo di autenticazione di Databricks che si vuole usare.

      Se la variabile di ambiente è già stata impostata DATABRICKS_CLUSTER_ID con l'ID del cluster, non è necessario specificare cluster_idanche .

      I campi del profilo di configurazione necessari per ogni tipo di autenticazione sono i seguenti:

      Assegnare al profilo di configurazione il nome DEFAULT.

      Inizializzare quindi la DatabricksSession classe come segue:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

  3. Convalidare l'ambiente e la connessione al cluster Databricks

    • Il comando seguente verificherà che l'ambiente, le credenziali predefinite e la connessione al cluster siano tutte configurate correttamente per Databricks Connessione.

      databricks-connect test

      Questo comando seleziona le credenziali predefinite configurate nell'ambiente, ad esempio il DEFAULT profilo di configurazione o tramite variabili di ambiente.

      Il comando ha esito negativo con un codice di uscita diverso da zero e un messaggio di errore corrispondente quando rileva eventuali incompatibilità nell'installazione.

    • Inoltre, è anche possibile usare la pyspark shell inclusa come parte di Databricks Connessione per Python. Avviare la shell eseguendo:

      pyspark

      Viene visualizzata la shell Spark, ad esempio:

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

      >>> Al prompt eseguire un semplice comando PySpark, ad esempio spark.range(1,10).show(). Se non sono presenti errori, la connessione è stata completata correttamente.

      Se la connessione è stata eseguita correttamente, per arrestare la shell Spark, premere Ctrl + d o Ctrl + zoppure eseguire il comando quit() o exit().

      Per altri dettagli sul databricks-connect file binario, vedere Utilizzo avanzato di Databricks Connessione per Python