Condividi tramite

Installare Databricks Connect per Python

  • Articolo

Nota

Questo articolo illustra Databricks Connect per Databricks Runtime 13.3 LTS e versioni successive.

Questo articolo descrive come installare Databricks Connect per Python. Consultare Cos’è Databricks Connect?. Per la versione scala di questo articolo, vedere Installare Databricks Connect per Scala.

Requisiti

Per installare Databricks Connect per Python, è necessario soddisfare i requisiti seguenti:

  • Se ci si connette a un ambiente di calcolo serverless, l'area di lavoro deve soddisfare i requisiti per il calcolo serverless.

    Nota

    Il calcolo serverless è supportato in Databricks Connect versione 15.1 e successive. Inoltre, le versioni di Databricks Connect in o versioni precedenti alla versione di Databricks Runtime in serverless sono completamente compatibili. Vedere Note sulla versione. Per verificare se la versione di Databricks Connect è compatibile con il calcolo serverless, vedere Convalidare la connessione a Databricks.

  • Se ci si connette a un cluster, il cluster di destinazione deve soddisfare i requisiti di configurazione del cluster, inclusi i requisiti di versione di Databricks Runtime.

  • È necessario avere Python 3 installato nel computer di sviluppo e la versione secondaria di Python installata nel computer di sviluppo deve soddisfare i requisiti di versione nella tabella seguente.

    Tipo di ambiente di calcolo Versione di Databricks Connect Versione di Python compatibile
    Senza server 15.1 e versioni successive 3.11
    Cluster 15.1 e versioni successive 3.11
    Cluster Da 13.3 LTS a 14.3 LTS 3.10

  • Se si vogliono usare le funzioni definite dall'utente di PySpark, la versione secondaria installata del computer di sviluppo di Python deve corrispondere alla versione secondaria di Python inclusa in Databricks Runtime installata nel cluster o nel calcolo serverless. 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 o il calcolo serverless. Vedere Le note sulla versione di Databricks Runtime e le note sulla compatibilità e sulla versione di calcolo serverless.

Attivare un ambiente virtuale Python

Databricks consiglia vivamente di avere un ambiente virtuale Python attivato per ogni versione di Python usata con Databricks Connect. Gli ambienti virtuali Python consentono di assicurarsi di usare le versioni corrette di Python e Databricks Connetti insieme. Per ulteriori informazioni su questi strumenti e su come attivarli, vedi venv o Poetry.

Installare il client Databricks Connect

Questa sezione descrive come installare il client Databricks Connect con venv o Poetry.

Nota

Se è già installata l'estensione Databricks per Visual Studio Code, non è necessario seguire queste istruzioni di installazione, perché l'estensione Databricks per Visual Studio Code include già il supporto predefinito per Databricks Connect per Databricks Runtime 13.3 LTS e versioni successive. Passare al codice di debug usando Databricks Connect per l'estensione Databricks per Visual Studio Code.

Installare il client Databricks Connect 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 Connect eseguendo il install comando . Usare l'opzione --upgrade per aggiornare qualsiasi installazione client esistente alla versione specificata.

    pip3 install --upgrade "databricks-connect==15.4.*"  # 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.

Andare avanti per Configurare le proprietà di connessione.

Installare il client Databricks Connect con Poetry

  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 Connect eseguendo il add comando .

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

    Nota

    Databricks consiglia di usare la notazione "at-tilde" per specificare databricks-connect@~15.4 invece di databricks-connect==15.4, 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.

Configurare le proprietà di connessione

In questa sezione vengono configurate le proprietà per stabilire una connessione tra Databricks Connect e il cluster Azure Databricks o il calcolo serverless, che include quanto segue:

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.

Configurare una connessione a un cluster

Per configurare una connessione a un cluster, è necessario l'ID del cluster. È possibile ottenere l'ID cluster dall'URL. Vedere URL e ID del cluster.

È possibile configurare la connessione al cluster in uno dei modi seguenti. Databricks Connect cerca le proprietà di configurazione nell'ordine seguente e usa la prima configurazione trovata. Per informazioni sulla configurazione avanzata, vedere Utilizzo avanzato di Databricks Connect per Python.

  1. Metodo remoto della classe DatabricksSession.
  2. Profilo di configurazione di Databricks
  3. Variabile di ambiente DATABRICKS_CONFIG_PROFILE
  4. Variabile di ambiente per ogni proprietà di configurazione
  5. Profilo di configurazione di Databricks denominato DEFAULT

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 stringa di connessione Spark Connect in DatabricksSession.builder.remote().

Anziché specificare queste proprietà di connessione nel codice, Databricks consiglia 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()

Profilo di configurazione di 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()

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()

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()

Profilo di configurazione di 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()

Configurare una connessione a un ambiente di calcolo serverless

Importante

Questa funzionalità è disponibile in anteprima pubblica.

Databricks Connect supporta la connessione al calcolo serverless. Per usare questa funzionalità, è necessario soddisfare i requisiti per la connessione a serverless. Vedere Requisiti.

Importante

Questa funzionalità presenta le limitazioni seguenti:

  • Tutte le limitazioni di Databricks Connect per Python
  • Tutte le limitazioni di calcolo serverless
  • Solo le dipendenze Python incluse come parte dell'ambiente di calcolo serverless possono essere usate per le funzioni definite dall'utente. Vedere Ambiente di sistema. Non è possibile installare dipendenze aggiuntive.
  • Le funzioni definite dall'utente con moduli personalizzati non sono supportate.

È possibile configurare una connessione al calcolo serverless in uno dei modi seguenti:

  • Impostare la variabile DATABRICKS_SERVERLESS_COMPUTE_ID di ambiente locale su auto. Se questa variabile di ambiente è impostata, Databricks Connect ignora .cluster_id

  • In un profilo di configurazione di Databricks locale impostare serverless_compute_id = auto, quindi fare riferimento a tale profilo dal codice Databricks Connect Python.

    [DEFAULT]
host = https://my-workspace.cloud.databricks.com/
serverless_compute_id = auto
token = dapi123...

  • In alternativa, è sufficiente aggiornare il codice Python di Databricks Connect come indicato di seguito:

    from databricks.connect import DatabricksSession as SparkSession

spark = DatabricksSession.builder.serverless(True).getOrCreate()

    from databricks.connect import DatabricksSession as SparkSession

spark DatabricksSession.builder.remote(serverless=True).getOrCreate()

Nota

Si verifica il timeout della sessione di calcolo serverless dopo 10 minuti di inattività. Successivamente, è necessario creare una nuova sessione Spark per connettersi al calcolo serverless. Questo può essere fatto con spark = DatabricksSession.builder.serverless(True).getOrCreate().

Convalidare la connessione a Databricks

Per convalidare l'ambiente, le credenziali predefinite e la connessione al calcolo sono configurate correttamente per Databricks Connect, eseguire il databricks-connect test comando, che ha esito negativo con un codice di uscita diverso da zero e un messaggio di errore corrispondente quando rileva eventuali incompatibilità nella configurazione.

databricks-connect test

È anche possibile convalidare l'ambiente nel codice Python usando validateSession():

DatabricksSession.builder.validateSession(True).getOrCreate()