Installare Databricks Connect per Python

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.

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:

• Nome dell'istanza dell'area di lavoro di Azure Databricks. Si tratta del valore Nome host server per il calcolo. Vedere Ottenere i dettagli della connessione per una risorsa di calcolo di Azure Databricks.
• Qualsiasi altra proprietà necessaria per il tipo di autenticazione di Databricks che si vuole usare.

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:

• Per l'autenticazione del token di accesso personale di Azure Databricks: host e token.
• Per l'autenticazione da computer a computer OAuth (M2M) (dove supportato): host, client_ide client_secret.
• Per l'autenticazione da utente a computer (U2M) OAuth (dove supportato): host.
• Per l'autenticazione dell'entità hostservizio Microsoft Entra ID (in precedenza Azure Active Directory): , azure_tenant_id, azure_client_id, azure_client_secrete possibilmente azure_workspace_resource_id.
• Per l'autenticazione dell'interfaccia della riga di comando di Azure: host.
• Per l'autenticazione delle identità gestite di Azure (dove supportato): host, azure_use_msi, azure_client_ide possibilmente azure_workspace_resource_id.

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:

• Per l'autenticazione del token di accesso personale di Azure Databricks: host e token.
• Per l'autenticazione da computer a computer OAuth (M2M) (dove supportato): host, client_ide client_secret.
• Per l'autenticazione da utente a computer (U2M) OAuth (dove supportato): host.
• Per l'autenticazione dell'entità hostservizio Microsoft Entra ID (in precedenza Azure Active Directory): , azure_tenant_id, azure_client_id, azure_client_secrete possibilmente azure_workspace_resource_id.
• Per l'autenticazione dell'interfaccia della riga di comando di Azure: host.
• Per l'autenticazione delle identità gestite di Azure (dove supportato): host, azure_use_msi, azure_client_ide possibilmente azure_workspace_resource_id.

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:

• Per l'autenticazione del token di accesso personale di Azure Databricks: DATABRICKS_HOST e DATABRICKS_TOKEN.
• Per l'autenticazione da computer a computer OAuth (M2M) (dove supportato): DATABRICKS_HOST, DATABRICKS_CLIENT_IDe DATABRICKS_CLIENT_SECRET.
• Per l'autenticazione da utente a computer (U2M) OAuth (dove supportato): DATABRICKS_HOST.
• Per l'autenticazione dell'entità DATABRICKS_HOSTservizio Microsoft Entra ID (in precedenza Azure Active Directory): , ARM_TENANT_ID, ARM_CLIENT_ID, ARM_CLIENT_SECRETe possibilmente DATABRICKS_AZURE_RESOURCE_ID.
• Per l'autenticazione dell'interfaccia della riga di comando di Azure: DATABRICKS_HOST.
• Per l'autenticazione delle identità gestite di Azure (dove supportato): DATABRICKS_HOST, ARM_USE_MSI, ARM_CLIENT_IDe possibilmente DATABRICKS_AZURE_RESOURCE_ID.

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:

• Per l'autenticazione del token di accesso personale di Azure Databricks: host e token.
• Per l'autenticazione da computer a computer OAuth (M2M) (dove supportato): host, client_ide client_secret.
• Per l'autenticazione da utente a computer (U2M) OAuth (dove supportato): host.
• Per l'autenticazione dell'entità hostservizio Microsoft Entra ID (in precedenza Azure Active Directory): , azure_tenant_id, azure_client_id, azure_client_secrete possibilmente azure_workspace_resource_id.
• Per l'autenticazione dell'interfaccia della riga di comando di Azure: host.
• Per l'autenticazione delle identità gestite di Azure (dove supportato): host, azure_use_msi, azure_client_ide possibilmente azure_workspace_resource_id.

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

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

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

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