Condividi tramite

Databricks SDK per Python

  • Articolo

Nota

Databricks consiglia i bundle di asset di Databricks per la creazione, lo sviluppo, la distribuzione e il test di processi e altre risorse di Databricks come codice sorgente. Consultare Che cosa sono i Databricks Asset Bundle?.

Questo articolo illustra come automatizzare le operazioni di Azure Databricks e accelerare lo sviluppo 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

Databricks SDK per Python è in versione beta e può essere usato 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 esempio requirements.txt per venv, o pyproject.toml per poetry.lock per Poetry. Per altre informazioni sull'aggiunta delle dipendenze, consultare Ambienti virtuali e pacchetti per venv o Installazione di dipendenze per Poetry.

Operazioni preliminari

È possibile usare Databricks SDK per Python da un notebook di Azure Databricks o dal computer di sviluppo locale.

Prima di iniziare a usare Databricks SDK per Python, il computer di sviluppo deve avere:

  • Autenticazione di Azure Databricks configurata.
  • Python 3.8 o versione successiva installata. 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, consultare 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 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). Per ulteriori informazioni sugli ambienti virtuali Python, vedere venv o Poetry.

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

    Eseguire pip per installare il pacchetto databricks-sdk. (In alcuni sistemi potrebbe essere necessario sostituire pip3 con pip, in questo caso e dappertutto).

    pip3 install databricks-sdk

    Poetry

    poetry add databricks-sdk

    Per installare una versione specifica del pacchetto databricks-sdk mentre Databricks SDK per Python è in versione beta, consultare la cronologia delle versioni del pacchetto. Ad esempio, per installare la versione 0.1.6:

    Venv

    pip3 install databricks-sdk==0.1.6

    Poetry

    poetry add databricks-sdk==0.1.6

    Per aggiornare un'installazione esistente del pacchetto Databricks SDK per Python alla versione più recente, usare il comando seguente:

    Venv

    pip3 install --upgrade databricks-sdk

    Poetry

    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

    Poetry

    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 comando python:

    Venv

    python3.10 main.py

    Poetry

    Se ci si trova nella shell dell'ambiente virtuale:

    python3.10 main.py

    Se non ci si trova 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, consultare 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, consultare 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 variabile di ambiente DATABRICKS_CONFIG_PROFILE 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 oggetto WorkspaceClient con l'autenticazione predefinita di Databricks come indicato di seguito:

    from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

  • L’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 = '...'
)
# ...

Consultare 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. È installato per impostazione predefinita in tutti i cluster di Azure Databricks che usano Databricks Runtime 13.3 LTS o nelle versioni successive. Per i cluster Di Azure Databricks che usano Databricks Runtime 12.2 LTS e nelle versioni successive, è prima necessario installare Databricks SDK per Python. Vedere Passaggio 1: Installare o aggiornare Databricks SDK per Python.

Per vedere la versione di Databricks SDK per Python installata per una specifica versione di Databricks Runtime, consultare la sezione Librerie Python installate delle note di rilascio di Databricks Runtime per quella versione.

Databricks consiglia di installare la versione più recente disponibile dell'SDK da PiPy, ma con un'installazione minima o un aggiornamento a Databricks SDK per Python 0.6.0 o versione successiva, l'autenticazione predefinita del notebook di Azure Databricks viene usata dalla versione 0.6.0 e successive in tutte le versioni di Databricks Runtime.

Nota

Databricks Runtime 15.1 è il primo Databricks Runtime ad avere una versione di Databricks SDK per Python (0.20.0) installata che supporta l'autenticazione predefinita dei notebook senza alcun aggiornamento necessario.

La tabella seguente illustra il supporto dell'autenticazione dei notebook per Databricks SDK per python e le versioni di Databricks Runtime:

SDK/DBR 10,4 LTS 11,3 LTS 12.3 LTS 13,3 LTS 14.3 LTS 15.1 e versioni successive
0.1.7 e versioni precedenti
0.1.10 ✓ ✓ ✓ ✓ ✓
0.6.0 ✓ ✓ ✓ ✓ ✓ ✓
0.20.0 e versioni successive ✓ ✓ ✓ ✓ ✓ ✓

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.
  • L'autenticazione del notebook di Azure Databricks non funziona con i profili di configurazione di Azure Databricks.

Se si desidera chiamare le API a livello di account di Azure Databricks o se si vuole usare un tipo di autenticazione databricks diverso dall'autenticazione predefinita del notebook di Databricks, sono supportati anche i seguenti tipi di autenticazione:

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 ID Tutte le versioni
Autenticazione con interfaccia della riga di comando di Azure Tutte le versioni
Autenticazione con token di accesso personale di Databricks Tutte le versioni

Autenticazione delle identità gestite di Azure non è ancora supportata.

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 comando magic %pip da una cella del notebook come indicato di seguito:

    %pip install databricks-sdk --upgrade

  2. Dopo aver eseguito il comando magic %pip, è 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 comando magic %pip:

    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, consultare Metodi di autenticazione di Azure Databricks e fare clic sul collegamento corrispondente per altri dettagli tecnici.

Usa 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 gruppi di comandi dbutils.fs, dbutils.secrets, dbutils.widgets e 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.secrets e dbutils.widgets. Inoltre, il gruppo di comandi dbutils.notebook è 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 di WorkspaceClient. Questo esempio di codice usa l'autenticazione predefinita del notebook di Azure Databricks per chiamare dbutils all'interno di 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)

Per accedere ai volumi del catalogo Unity, usare files all'interno di WorkspaceClient. Consultare Gestire file nei volumi nel catalogo Unity. Non è possibile usare dbutils da solo o all'interno di WorkspaceClient per accedere ai volumi.

Consultare 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, consultare Usare Databricks SDK per Python da un notebook di Azure Databricks. Per informazioni dettagliate sull'autenticazione predefinita all'esterno dei notebook, consultare Autenticare Databricks SDK per Python con l'account o l'area di lavoro di Azure Databricks.

Per altri esempi di codice, consultare 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 in modo definitivo 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

Nell'esempio seguente viene creato un processo che usa l'ambiente di calcolo serverless per i processi:

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",
   )
  ]
)

Gestisce i file nei volumi nel catalogo Unity

Questo esempio di codice illustra varie chiamate alle funzionalità filesall'interno di WorkspaceClient per accedere a un volume del catalogo Unity.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Define volume, folder, and file details.
catalog            = 'main'
schema             = 'default'
volume             = 'my-volume'
volume_path        = f"/Volumes/{catalog}/{schema}/{volume}" # /Volumes/main/default/my-volume
volume_folder      = 'my-folder'
volume_folder_path = f"{volume_path}/{volume_folder}" # /Volumes/main/default/my-volume/my-folder
volume_file        = 'data.csv'
volume_file_path   = f"{volume_folder_path}/{volume_file}" # /Volumes/main/default/my-volume/my-folder/data.csv
upload_file_path   = './data.csv'

# Create an empty folder in a volume.
w.files.create_directory(volume_folder_path)

# Upload a file to a volume.
with open(upload_file_path, 'rb') as file:
  file_bytes = file.read()
  binary_data = io.BytesIO(file_bytes)
  w.files.upload(volume_file_path, binary_data, overwrite = True)

# List the contents of a volume.
for item in w.files.list_directory_contents(volume_path):
  print(item.path)

# List the contents of a folder in a volume.
for item in w.files.list_directory_contents(volume_folder_path):
  print(item.path)

# Print the contents of a file in a volume.
resp = w.files.download(volume_file_path)
print(str(resp.contents.read(), encoding='utf-8'))

# Delete a file from a volume.
w.files.delete(volume_file_path)

# Delete a folder from a volume.
w.files.delete_directory(volume_folder_path)

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

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, è possibile usare librerie di simulazione di Python, ad esempio unittest.mock.

Suggerimento

Databricks Labs fornisce un plug-in pytest per semplificare i test di integrazione con Databricks e un plug-in pylint per garantire la qualità del codice.

Il file di esempio seguente denominato helpers.py contiene 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

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 funzione create_cluster restituisce la risposta prevista. Anziché creare un cluster nell'area di lavoro di destinazione, questo test simula un oggetto WorkspaceClient, definisce le impostazioni dell'oggetto fittizio e quindi passa l'oggetto fittizio alla funzione create_cluster. 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 comando pytest 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: