Databricks SDK per Python
Questo articolo illustra come automatizzare le operazioni in account, aree di lavoro e risorse correlate di Azure Databricks con Databricks SDK per Python. Questo articolo integra la documentazione di Databricks SDK per Python in Read The Docs e gli esempi di codice nel repository Databricks SDK per Python in GitHub.
Nota
Questa funzionalità è in versione beta e può essere usata nell'ambiente di produzione.
Durante il periodo beta, Databricks consiglia di aggiungere una dipendenza dalla versione secondaria specifica di Databricks SDK per Python da cui dipende il codice. Ad esempio, è possibile aggiungere dipendenze nei file, ad requirements.txt
esempio per venv
, o pyproject.toml
per poetry.lock
La poesia. Per altre informazioni sull'aggiunta delle dipendenze, vedere Ambienti virtuali e pacchetti per venv
o Installazione di dipendenze per Poesia.
Operazioni preliminari
È possibile usare Databricks SDK per Python da un notebook di Azure Databricks o dal computer di sviluppo locale.
- Per usare Databricks SDK per Python dall'interno di un notebook di Azure Databricks, passare a Usare Databricks SDK per Python da un notebook di Azure Databricks.
- Per usare Databricks SDK per Python dal computer di sviluppo locale, completare i passaggi descritti in questa sezione.
Prima di iniziare a usare Databricks SDK per Python, il computer di sviluppo deve avere:
- Autenticazione di Azure Databricks configurata.
- Installato Python 3.8 o versione successiva. Per automatizzare le risorse di calcolo di Azure Databricks, Databricks consiglia di avere installato le versioni principali e secondarie di Python che corrispondono a quella installata nella risorsa di calcolo di Azure Databricks di destinazione. Gli esempi di questo articolo si basano sull'automazione dei cluster con Databricks Runtime 13.3 LTS, che include Python 3.10 installato. Per la versione corretta, vedere Versioni delle note sulla versione di Databricks Runtime e compatibilità per la versione di Databricks Runtime del cluster.
- Databricks consiglia di creare e attivare un ambiente virtuale Python per ogni progetto di codice Python usato con Databricks SDK per Python. Gli ambienti virtuali Python consentono di assicurarsi che il progetto di codice usi versioni compatibili dei pacchetti Python e Python(in questo caso, il pacchetto Databricks SDK per Python). Questo articolo illustra come usare venv o Potetry per ambienti virtuali Python.
Creare un ambiente virtuale Python con venv
Dal terminale impostato sulla directory radice del progetto di codice Python eseguire il comando seguente. Questo comando indica di
venv
usare Python 3.10 per l'ambiente virtuale e quindi crea i file di supporto dell'ambiente virtuale in una directory nascosta denominata.venv
all'interno della directory radice del progetto di codice Python.# Linux and macOS python3.10 -m venv ./.venv # Windows python3.10 -m venv .\.venv
Usare
venv
per attivare l'ambiente virtuale. Vedere la documentazione di venv per il comando corretto da usare, in base al sistema operativo e al tipo di terminale. Ad esempio, in macOS che eseguezsh
:source ./.venv/bin/activate
Si sa che l'ambiente virtuale viene attivato quando il nome dell'ambiente virtuale (ad esempio,
.venv
) viene visualizzato tra parentesi immediatamente prima del prompt del terminale.Per disattivare l'ambiente virtuale in qualsiasi momento, eseguire il comando
deactivate
.Si sa che l'ambiente virtuale viene disattivato quando il nome dell'ambiente virtuale non viene più visualizzato tra parentesi prima del prompt del terminale.
Passare a Introduzione a Databricks SDK per Python.
Creare un ambiente virtuale con poesia
Installa Poesia, se non l'hai già fatto.
Dal terminale impostato sulla directory radice del progetto di codice Python eseguire il comando seguente per indicare
poetry
di inizializzare il progetto di codice Python per Poetry.poetry init
La poesia mostra diverse richieste per voi di completare. Nessuno di questi prompt è specifico di Databricks SDK per Python. Per informazioni su queste richieste, vedere init.
Dopo aver completato le richieste, Poetry aggiunge un
pyproject.toml
file al progetto Python. Per informazioni sulpyproject.toml
file, vedere Il file pyproject.toml.Con il terminale ancora impostato sulla directory radice del progetto di codice Python, eseguire il comando seguente. Questo comando indica
poetry
di leggere ilpyproject.toml
file, installare e risolvere le dipendenze, creare unpoetry.lock
file per bloccare le dipendenze e infine creare un ambiente virtuale.poetry install
Dal terminale impostato sulla directory radice del progetto di codice Python eseguire il comando seguente per indicare
poetry
di attivare l'ambiente virtuale e immettere la shell.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 poco prima del prompt del terminale.
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.
Introduzione a Databricks SDK per Python
Questa sezione descrive come iniziare a usare Databricks SDK per Python dal computer di sviluppo locale. Per usare Databricks SDK per Python dall'interno di un notebook di Azure Databricks, passare a Usare Databricks SDK per Python da un notebook di Azure Databricks.
Nel computer di sviluppo con l'autenticazione di Azure Databricks configurata, Python è già installato e l'ambiente virtuale Python già attivato, installare il pacchetto databricks-sdk (e le relative dipendenze) dall'indice dei pacchetti Python (PyPI), come indicato di seguito:
Venv
Usare
pip
per installare ildatabricks-sdk
pacchetto. In alcuni sistemi potrebbe essere necessario sostituirepip3
conpip
, in questo caso e in tutto.pip3 install databricks-sdk
Poesia
poetry add databricks-sdk
Per installare una versione specifica del
databricks-sdk
pacchetto mentre Databricks SDK per Python è in versione beta, vedere la cronologia delle versioni del pacchetto. Ad esempio, per installare la versione0.1.6
:Venv
pip3 install databricks-sdk==0.1.6
Poesia
poetry add databricks-sdk==0.1.6
Suggerimento
Per aggiornare un'installazione esistente del pacchetto Databricks SDK per Python alla versione più recente, eseguire il comando seguente:
Venv
pip3 install --upgrade databricks-sdk
Poesia
poetry add databricks-sdk@latest
Per visualizzare l'SDK di Databricks per python corrente
Version
e altri dettagli, eseguire il comando seguente:Venv
pip3 show databricks-sdk
Poesia
poetry show databricks-sdk
Nell'ambiente virtuale Python creare un file di codice Python che importa Databricks SDK per Python. L'esempio seguente, in un file denominato
main.py
con il contenuto seguente, elenca semplicemente tutti i cluster nell'area di lavoro di Azure Databricks:from databricks.sdk import WorkspaceClient w = WorkspaceClient() for c in w.clusters.list(): print(c.cluster_name)
Eseguire il file di codice Python, presupponendo che un file denominato
main.py
, eseguendo ilpython
comando :Venv
python3.10 main.py
Poesia
Se ci si trova nella shell dell'ambiente virtuale:
python3.10 main.py
Se non si è nella shell dell'ambiente virtuale:
poetry run python3.10 main.py
Nota
Non impostando argomenti nella chiamata precedente a
w = WorkspaceClient()
, Databricks SDK per Python usa il processo predefinito per tentare di eseguire l'autenticazione di Azure Databricks. Per eseguire l'override di questo comportamento predefinito, vedere la sezione di autenticazione seguente.
Autenticare Databricks SDK per Python con l'account o l'area di lavoro di Azure Databricks
Questa sezione descrive come autenticare Databricks SDK per Python dal computer di sviluppo locale all'account o all'area di lavoro di Azure Databricks. Per autenticare Databricks SDK per Python dall'interno di un notebook di Azure Databricks, passare a Usare Databricks SDK per Python da un notebook di Azure Databricks.
Databricks SDK per Python 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 Databricks una sola volta e quindi di usarla tra più strumenti e SDK di Databricks senza ulteriori modifiche alla configurazione dell'autenticazione. Per altre informazioni, inclusi esempi di codice più completi in Python, vedere Autenticazione unificata del client Databricks.
Nota
Databricks SDK per Python non ha ancora implementato l'autenticazione delle identità gestite di Azure.
Alcuni dei modelli di codifica disponibili per inizializzare l'autenticazione di Databricks con Databricks SDK per Python includono:
Usare l'autenticazione predefinita di Databricks eseguendo una delle operazioni seguenti:
- Creare o identificare un profilo di configurazione di Databricks personalizzato con i campi obbligatori per il tipo di autenticazione databricks di destinazione. Impostare quindi la
DATABRICKS_CONFIG_PROFILE
variabile di ambiente sul nome del profilo di configurazione personalizzato. - Impostare le variabili di ambiente necessarie per il tipo di autenticazione di Databricks di destinazione.
Creare quindi un'istanza di un
WorkspaceClient
oggetto con l'autenticazione predefinita di Databricks come indicato di seguito:from databricks.sdk import WorkspaceClient w = WorkspaceClient() # ...
- Creare o identificare un profilo di configurazione di Databricks personalizzato con i campi obbligatori per il tipo di autenticazione databricks di destinazione. Impostare quindi la
Il hardcoded dei campi obbligatori è supportato ma non consigliato, perché rischia di esporre informazioni riservate nel codice, ad esempio i token di accesso personale di Azure Databricks. L'esempio seguente imposta come hardcoded azure Databricks host e valori dei token di accesso per l'autenticazione del token di Databricks:
from databricks.sdk import WorkspaceClient w = WorkspaceClient( host = 'https://...', token = '...' ) # ...
Vedere anche Autenticazione nella documentazione di Databricks SDK per Python.
Usare Databricks SDK per Python da un notebook di Azure Databricks
È possibile chiamare la funzionalità di Databricks SDK per Python da un notebook di Azure Databricks con un cluster Azure Databricks collegato con Databricks SDK per Python installato. Databricks SDK per Python è già installato in tutti i cluster di Azure Databricks che usano Databricks Runtime 13.3 LTS o versione successiva. Per i cluster Di Azure Databricks che usano Databricks Runtime 12.2 LTS e versioni successive, è prima necessario installare Databricks SDK per Python. Vedere Passaggio 1: Installare o aggiornare Databricks SDK per Python.
Per visualizzare il numero di versione di Databricks SDK per Python installato per impostazione predefinita per una versione specifica di Databricks Runtime, vedere la sezione "Librerie Python installate" delle note sulla versione di Databricks Runtime per tale versione di Databricks Runtime.
Databricks SDK per Python 0.6.0 e versioni successive usa l'autenticazione predefinita del notebook di Azure Databricks. L'autenticazione predefinita del notebook di Azure Databricks si basa su un token di accesso personale di Azure Databricks temporaneo generato automaticamente in background per il proprio uso. Azure Databricks elimina questo token temporaneo dopo l'arresto dell'esecuzione del notebook.
Importante
L'autenticazione predefinita del notebook di Azure Databricks funziona solo nel nodo driver del cluster e non in uno dei nodi di lavoro o executor del cluster.
Databricks Runtime 13.3 LTS e versioni successive supporta l'autenticazione predefinita dei notebook di Azure Databricks con Databricks SDK per Python 0.1.7 o versione successiva installata. Databricks Runtime 10.4 LTS e versioni successive supporta l'autenticazione predefinita del notebook di Azure Databricks con Databricks SDK per Python 0.1.10 o versione successiva installata. Databricks consiglia tuttavia di installare o eseguire l'aggiornamento a Databricks SDK per Python 0.6.0 o versione successiva per garantire la massima compatibilità con l'autenticazione predefinita del notebook di Azure Databricks, indipendentemente dalla versione di Databricks Runtime.
È necessario installare o aggiornare Databricks SDK per Python nel cluster Azure Databricks se si vuole chiamare le API a livello di account di Azure Databricks o se si vuole usare un tipo di autenticazione di Azure Databricks diverso dall'autenticazione predefinita del notebook di Azure Databricks, come indicato di seguito:
Tipo di autenticazione | Versioni di Databricks SDK per Python |
---|---|
Autenticazione OAuth da computer a computer (M2M) | 0.18.0 e versioni successive |
Autenticazione da utente a computer (U2M) OAuth | 0.19.0 e versioni successive |
Autenticazione entità servizio di Microsoft Entra | Tutte le versioni |
Autenticazione con interfaccia della riga di comando di Azure | Tutte le versioni |
Autenticazione del token di accesso personale di Databricks | Tutte le versioni |
L'autenticazione delle identità gestite di Azure non è ancora supportata.
L'autenticazione del notebook di Azure Databricks non funziona con i profili di configurazione di Azure Databricks.
Passaggio 1: Installare o aggiornare Databricks SDK per Python
I notebook Python di Azure Databricks possono usare Databricks SDK per Python esattamente come qualsiasi altra libreria Python. Per installare o aggiornare la libreria Databricks SDK per Python nel cluster Azure Databricks collegato, eseguire il
%pip
comando magic da una cella del notebook come indicato di seguito:%pip install databricks-sdk --upgrade
Dopo aver eseguito il
%pip
comando magic, è necessario riavviare Python per rendere disponibile la libreria installata o aggiornata per il notebook. A tale scopo, eseguire il comando seguente da una cella del notebook immediatamente dopo la cella con il%pip
comando magic:dbutils.library.restartPython()
Per visualizzare la versione installata di Databricks SDK per Python, eseguire il comando seguente da una cella del notebook:
%pip show databricks-sdk | grep -oP '(?<=Version: )\S+'
Passaggio 2: Eseguire il codice
Nelle celle del notebook creare codice Python che importa e quindi chiama Databricks SDK per Python. L'esempio seguente usa l'autenticazione predefinita del notebook di Azure Databricks per elencare tutti i cluster nell'area di lavoro di Azure Databricks:
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
for c in w.clusters.list():
print(c.cluster_name)
Quando si esegue questa cella, viene visualizzato un elenco dei nomi di tutti i cluster disponibili nell'area di lavoro di Azure Databricks.
Per usare un tipo di autenticazione di Azure Databricks diverso, vedere Tipi di autenticazione di Azure Databricks supportati e fare clic sul collegamento corrispondente per altri dettagli tecnici.
Usare le utilità di Databricks
È possibile chiamare informazioni di riferimento sulle utilità di Databricks (dbutils) dal codice Databricks SDK per Python in esecuzione nel computer di sviluppo locale o da un notebook di Azure Databricks.
- Dal computer di sviluppo locale, Le utilità di Databricks hanno accesso solo ai
dbutils.fs
gruppi di comandi ,dbutils.secrets
,dbutils.widgets
edbutils.jobs
. - Da un notebook di Azure Databricks collegato a un cluster di Azure Databricks, Le utilità di Databricks hanno accesso a tutti i gruppi di comandi di Databricks Utilities disponibili, non solo
dbutils.fs
,dbutils.secrets
edbutils.widgets
. Inoltre, ildbutils.notebook
gruppo di comandi è limitato a due livelli solo di comandi, ad esempiodbutils.notebook.run
odbutils.notebook.exit
.
Per chiamare Le utilità di Databricks dal computer di sviluppo locale o da un notebook di Azure Databricks, usare dbutils
all'interno WorkspaceClient
di . Questo esempio di codice usa l'autenticazione predefinita del notebook di Azure Databricks per chiamare dbutils
all'interno WorkspaceClient
per elencare i percorsi di tutti gli oggetti nella radice DBFS dell'area di lavoro.
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
d = w.dbutils.fs.ls('/')
for f in d:
print(f.path)
In alternativa, è possibile chiamare dbutils
direttamente. Tuttavia, è possibile usare solo l'autenticazione predefinita del notebook di Azure Databricks. Questo esempio di codice chiama dbutils
direttamente per elencare tutti gli oggetti nella radice DBFS dell'area di lavoro.
from databricks.sdk.runtime import *
d = dbutils.fs.ls('/')
for f in d:
print(f.path)
Non è possibile usare dbutils
da solo o all'interno WorkspaceClient
per accedere ai volumi del catalogo Unity. Usare invece files
all'interno WorkspaceClient
di . In questo esempio di codice viene chiamato files
per WorkspaceClient
stampare il contenuto del file specificato nel volume specificato.
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
resp = w.files.download('/Volumes/main/default/my-volume/sales.csv')
print(str(resp.contents.read(), encoding='utf-8'))
Vedere anche Interazione con dbutils.
Esempi di codice
Gli esempi di codice seguenti illustrano come usare Databricks SDK per Python per creare ed eliminare cluster, eseguire processi ed elencare gruppi a livello di account. Questi esempi di codice usano l'autenticazione predefinita del notebook di Azure Databricks. Per informazioni dettagliate sull'autenticazione predefinita dei notebook di Azure Databricks, vedere Usare Databricks SDK per Python da un notebook di Azure Databricks. Per informazioni dettagliate sull'autenticazione predefinita all'esterno dei notebook, vedere Autenticare Databricks SDK per Python con l'account o l'area di lavoro di Azure Databricks.
Per altri esempi di codice, vedere gli esempi nel repository Databricks SDK per Python in GitHub. Vedere anche:
Informazioni di riferimento sulle API dell'area di lavoro di Databricks
Informazioni di riferimento sulle API dell'account Databricks
Creare un cluster
Questo esempio di codice crea un cluster con la versione di Databricks Runtime e il tipo di nodo del cluster specificati. Questo cluster ha un ruolo di lavoro e il cluster terminerà automaticamente dopo 15 minuti di inattività.
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
print("Attempting to create cluster. Please wait...")
c = w.clusters.create_and_wait(
cluster_name = 'my-cluster',
spark_version = '12.2.x-scala2.12',
node_type_id = 'Standard_DS3_v2',
autotermination_minutes = 15,
num_workers = 1
)
print(f"The cluster is now ready at " \
f"{w.config.host}#setting/clusters/{c.cluster_id}/configuration\n")
Eliminare definitivamente un cluster
Questo esempio di codice elimina definitivamente il cluster con l'ID cluster specificato dall'area di lavoro.
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
c_id = input('ID of cluster to delete (for example, 1234-567890-ab123cd4): ')
w.clusters.permanent_delete(cluster_id = c_id)
Creare un processo
Questo esempio di codice crea un processo di Azure Databricks che esegue il notebook specificato nel cluster specificato. Durante l'esecuzione del codice, ottiene il percorso del notebook esistente, l'ID cluster esistente e le impostazioni del processo correlate dall'utente nel terminale.
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.jobs import Task, NotebookTask, Source
w = WorkspaceClient()
job_name = input("Some short name for the job (for example, my-job): ")
description = input("Some short description for the job (for example, My job): ")
existing_cluster_id = input("ID of the existing cluster in the workspace to run the job on (for example, 1234-567890-ab123cd4): ")
notebook_path = input("Workspace path of the notebook to run (for example, /Users/someone@example.com/my-notebook): ")
task_key = input("Some key to apply to the job's tasks (for example, my-key): ")
print("Attempting to create the job. Please wait...\n")
j = w.jobs.create(
name = job_name,
tasks = [
Task(
description = description,
existing_cluster_id = existing_cluster_id,
notebook_task = NotebookTask(
base_parameters = dict(""),
notebook_path = notebook_path,
source = Source("WORKSPACE")
),
task_key = task_key
)
]
)
print(f"View the job at {w.config.host}/#job/{j.job_id}\n")
Creare un processo che usa l'ambiente di calcolo serverless
Importante
Il calcolo serverless per i flussi di lavoro è disponibile in anteprima pubblica. Per informazioni sull'idoneità e l'abilitazione, vedere Abilitare l'anteprima pubblica di calcolo serverless.
Nell'esempio seguente viene creato un processo che usa l'ambiente di calcolo serverless per i flussi di lavoro:
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.jobs import NotebookTask, Source, Task
w = WorkspaceClient()
j = w.jobs.create(
name = "My Serverless Job",
tasks = [
Task(
notebook_task = NotebookTask(
notebook_path = "/Users/user@databricks.com/MyNotebook",
source = Source("WORKSPACE")
),
task_key = "MyTask",
)
]
)
Elencare i gruppi a livello di account
Questo esempio di codice elenca i nomi visualizzati per tutti i gruppi disponibili all'interno dell'account Azure Databricks.
from databricks.sdk import AccountClient
a = AccountClient()
for g in a.groups.list():
print(g.display_name)
Test in corso
Per testare il codice, usare framework di test Python come pytest. Per testare il codice in condizioni simulate senza chiamare gli endpoint dell'API REST di Azure Databricks o modificare lo stato degli account o delle aree di lavoro di Azure Databricks, usare librerie di simulazione Python come unittest.mock.
Ad esempio, dato il file seguente denominato helpers.py
contenente una create_cluster
funzione che restituisce informazioni sul nuovo cluster:
# helpers.py
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.compute import ClusterDetails
def create_cluster(
w: WorkspaceClient,
cluster_name: str,
spark_version: str,
node_type_id: str,
autotermination_minutes: int,
num_workers: int
) -> ClusterDetails:
response = w.clusters.create(
cluster_name = cluster_name,
spark_version = spark_version,
node_type_id = node_type_id,
autotermination_minutes = autotermination_minutes,
num_workers = num_workers
)
return response
E dato il file seguente denominato main.py
che chiama la create_cluster
funzione:
# main.py
from databricks.sdk import WorkspaceClient
from helpers import *
w = WorkspaceClient()
# Replace <spark-version> with the target Spark version string.
# Replace <node-type-id> with the target node type string.
response = create_cluster(
w = w,
cluster_name = 'Test Cluster',
spark_version = '<spark-version>',
node_type_id = '<node-type-id>',
autotermination_minutes = 15,
num_workers = 1
)
print(response.cluster_id)
Il file seguente denominato test_helpers.py
verifica se la create_cluster
funzione restituisce la risposta prevista. Anziché creare un cluster nell'area di lavoro di destinazione, questo test simula un WorkspaceClient
oggetto, definisce le impostazioni dell'oggetto fittizio e quindi passa l'oggetto fittizio alla create_cluster
funzione. Il test verifica quindi se la funzione restituisce l'ID previsto del nuovo cluster fittizio.
# test_helpers.py
from databricks.sdk import WorkspaceClient
from helpers import *
from unittest.mock import create_autospec # Included with the Python standard library.
def test_create_cluster():
# Create a mock WorkspaceClient.
mock_workspace_client = create_autospec(WorkspaceClient)
# Set the mock WorkspaceClient's clusters.create().cluster_id value.
mock_workspace_client.clusters.create.return_value.cluster_id = '123abc'
# Call the actual function but with the mock WorkspaceClient.
# Replace <spark-version> with the target Spark version string.
# Replace <node-type-id> with the target node type string.
response = create_cluster(
w = mock_workspace_client,
cluster_name = 'Test Cluster',
spark_version = '<spark-version>',
node_type_id = '<node-type-id>',
autotermination_minutes = 15,
num_workers = 1
)
# Assert that the function returned the mocked cluster ID.
assert response.cluster_id == '123abc'
Per eseguire questo test, eseguire il pytest
comando dalla radice del progetto di codice, che dovrebbe produrre risultati di test simili ai seguenti:
$ pytest
=================== test session starts ====================
platform darwin -- Python 3.12.2, pytest-8.1.1, pluggy-1.4.0
rootdir: <project-rootdir>
collected 1 item
test_helpers.py . [100%]
======================== 1 passed ==========================
Risorse aggiuntive
Per altre informazioni, vedi:
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per