Condividi tramite


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 venvo 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

  1. 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
    
  2. 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 esegue zsh:

    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

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

  2. 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
    
  3. 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.

  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. Con il terminale ancora impostato sulla directory radice del progetto di codice Python, eseguire il comando seguente. Questo comando indica poetry di leggere il pyproject.toml file, installare e risolvere le dipendenze, creare un poetry.lock file per bloccare le dipendenze e infine creare un ambiente virtuale.

    poetry install
    
  6. 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.

  1. 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 il databricks-sdk pacchetto. In alcuni sistemi potrebbe essere necessario sostituire pip3 con pip, 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 versione 0.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
    
  2. 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)
    
  3. Eseguire il file di codice Python, presupponendo che un file denominato main.py, eseguendo il python 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()
    # ...
    
  • 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

  1. 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
    
  2. 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()
    
  3. 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.fsgruppi di comandi , dbutils.secrets, dbutils.widgetse dbutils.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.secretse dbutils.widgets. Inoltre, il dbutils.notebook gruppo di comandi è limitato a due livelli solo di comandi, ad esempio dbutils.notebook.run o dbutils.notebook.exit.

Per chiamare Le utilità di Databricks dal computer di sviluppo locale o da un notebook di Azure Databricks, usare dbutils all'interno WorkspaceClientdi . 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 WorkspaceClientdi . 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:

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: