Databricks SDK pour Python
Databricks recommande les Declarative Automation Bundles pour la création, le développement, le déploiement et le test de jobs et autres ressources Databricks en tant que code source. Consultez Que sont les Declarative Automation Bundles ?
Dans cet article, vous apprendrez à automatiser les opérations Databricks et à accélérer le développement avec le SDK Databricks pour Python. Cet article complète la documentation du SDK Databricks pour Python sur Read The Docs et les exemples de code dans le repository du SDK Databricks pour Python sur GitHub.
Le SDK Databricks pour Python est en Bêta et peut être utilisé en production.
Pendant la période Bêta, Databricks vous recommande de pin une dépendance sur la version mineure spécifique du SDK Databricks pour Python dont votre code dépend. Par exemple, vous pouvez pin des dépendances dans des fichiers tels que requirements.txt pour venv, ou pyproject.toml et poetry.lock pour Poetry. Pour plus d'informations sur l'épinglage des dépendances, consultez Environnements virtuels et packages pour venv, ou Installation des dépendances pour Poetry.
Exigences
Vous pouvez utiliser le SDK Databricks pour Python à partir d'un notebook Databricks ou depuis votre machine de développement locale.
- Pour utiliser le SDK Databricks pour Python depuis un notebook Databricks, passez à la section Utiliser le SDK Databricks pour Python depuis un notebook Databricks.
- Pour utiliser le SDK Databricks pour Python depuis votre machine de développement locale, suivez les étapes de cette section.
Pour utiliser le SDK Databricks pour Python, votre machine de développement doit avoir :
- Databricks authentication configured.
- Python 3.8 ou version ultérieure installée. Pour automatiser les ressources de compute Databricks, Databricks recommande que vous ayez les versions majeure et mineure de Python installées qui correspondent à celles installées sur votre ressource de compute Databricks cible. Les exemples de cet article reposent sur l'automatisation de clusters avec Databricks Runtime 13.3 LTS, sur lequel Python 3.10 est installé. Pour la bonne version, consultez les notes de version et la compatibilité de Databricks Runtime pour la version de Databricks Runtime de votre cluster.
- Databricks vous recommande de créer et d'activer un environnement virtuel Python pour chaque projet Python que vous utilisez avec le Databricks SDK pour Python. Les environnements virtuels Python permettent de s’assurer que votre projet de code utilise des versions compatibles de Python et de packages Python (dans ce cas, le package Databricks SDK for Python). Pour plus d'informations sur les environnements virtuels Python, consultez venv ou Poetry.
Démarrer avec le SDK Databricks pour Python
Cette section explique comment start avec le SDK Databricks pour Python à partir de votre machine de développement locale. Pour utiliser le SDK Databricks pour Python à partir d'un Notebook Databricks, reportez-vous à Utiliser le SDK Databricks pour Python à partir d'un Notebook Databricks.
- Sur votre machine de développement avec l'authentification Databricks configurée, Python déjà installé et votre environnement virtuel Python déjà activé, installez le package databricks-sdk (et ses dépendances) à partir du Python Package Index (PyPI), comme suit :
- Venv
- Poetry
Utilisez pip pour installer le package databricks-sdk. (Sur certains systèmes, vous pourriez avoir besoin de remplacer pip3 par pip, ici et partout.)
pip3 install databricks-sdk
poetry add databricks-sdk
Pour installer une version spécifique du package databricks-sdk lorsque le Databricks SDK pour Python est en version Bêta, consultez l' historique des versions du package. Par exemple, pour installer la version 0.1.6:
- Venv
- Poetry
pip3 install databricks-sdk==0.1.6
poetry add databricks-sdk==0.1.6
Pour mettre à niveau une installation existante du package Databricks SDK pour Python vers la dernière version, exécutez la commande suivante :
- Venv
- Poetry
pip3 install --upgrade databricks-sdk
poetry add databricks-sdk@latest
Pour afficher le Version actuel du package Databricks SDK pour Python et d'autres détails, exécutez la commande suivante :
- Venv
- Poetry
pip3 show databricks-sdk
poetry show databricks-sdk
-
Dans votre environnement virtuel Python, créez un fichier de code Python qui importe le SDK Databricks pour Python. L'exemple suivant, dans un fichier nommé
main.pyavec le contenu ci-dessous, répertorie simplement tous les clusters dans votre Workspace Databricks :Pythonfrom databricks.sdk import WorkspaceClient
w = WorkspaceClient()
for c in w.clusters.list():
print(c.cluster_name) -
Exécutez votre fichier de code Python, en supposant un fichier nommé
main.py, en exécutant la commandepython:
- Venv
- Poetry
python3.10 main.py
Si vous êtes dans le Shell de l'environnement virtuel :
python3.10 main.py
Si vous n'êtes pas dans le shell de l'environnement virtuel :
poetry run python3.10 main.py
By not setting any arguments in the preceding call to w = WorkspaceClient(), the Databricks SDK for Python uses its default process for trying to perform Databricks authentication. To override this default behavior, see the following authentication section.
Authentifiez le SDK Databricks pour Python avec votre compte ou Workspace Databricks
Cette section décrit comment authentifier le SDK Databricks pour Python depuis votre machine de développement locale vers votre compte ou workspace Databricks. Pour authentifier le SDK Databricks pour Python à partir d'un Notebook Databricks, passez à Utiliser le SDK Databricks pour Python à partir d'un Notebook Databricks.
Le SDK Databricks pour Python met en œuvre la norme d' authentification unifiée Databricks , une approche architecturale et programmatique consolidée et cohérente de l'authentification. Cette approche contribue à rendre la configuration et l'automatisation de l'authentification avec Databricks plus centralisées et prévisibles. Il vous permet de configurer l'authentification Databricks une seule fois, puis d'utiliser cette configuration sur plusieurs outils Databricks et SDK sans modifications supplémentaires de la configuration de l'authentification. Pour plus d’informations, y compris des exemples de code plus complets en Python, consultez Authentification unifiée Databricks.
Parmi les modèles de codage disponibles pour initialiser l'authentification Databricks avec le SDK Databricks pour Python figurent :
-
Utilisez l'authentification par default de Databricks en procédant comme suit :
- Créez ou identifiez un profil de configuration Databricks personnalisé avec les champs requis pour le type d'authentification Databricks cible. Définissez ensuite la variable d'environnement
DATABRICKS_CONFIG_PROFILEsur le nom du profil de configuration personnalisé. - Définissez les variables d'environnement requises pour le type d'authentification Databricks cible.
Instanciez ensuite par exemple un objet
WorkspaceClientavec l'authentification default de Databricks comme suit :Pythonfrom databricks.sdk import WorkspaceClient
w = WorkspaceClient()
# ... - Créez ou identifiez un profil de configuration Databricks personnalisé avec les champs requis pour le type d'authentification Databricks cible. Définissez ensuite la variable d'environnement
-
Le codage en dur des champs obligatoires est pris en charge mais non recommandé, car il risque d'exposer des informations sensibles dans votre code, tels que les jetons d'accès personnel Databricks. L'exemple suivant code en dur les valeurs d'hôte Databricks et de jeton d'accès pour l'authentification par jeton Databricks :
Pythonfrom databricks.sdk import WorkspaceClient
w = WorkspaceClient(
host = 'https://...',
token = '...'
)
# ...
Voir aussi Authentification dans la documentation du Databricks SDK pour Python.
Utilisez le SDK Databricks pour Python à partir d’un Notebook Databricks
Vous pouvez appeler les fonctionnalités du SDK Databricks pour Python depuis un Notebook Databricks qui possède un cluster Databricks attaché avec le SDK Databricks pour Python installé. Il est installé par default sur tous les clusters Databricks qui utilisent Databricks Runtime 13.3 LTS ou une version supérieure. Pour les clusters Databricks qui utilisent Databricks Runtime 12.2 LTS et versions antérieures, vous devez d'abord installer le SDK Databricks pour Python. Consultez Étape 1 : Installer ou mettre à niveau le SDK Databricks pour Python.
Pour consulter la version du Databricks SDK pour Python installée pour une version spécifique de Databricks Runtime, consultez la section Bibliothèques Python installées des notes de publication de Databricks Runtime pour cette version.
Databricks vous recommande d'installer la dernière version disponible du SDK depuis PiPy, mais au minimum d'installer ou de mettre à niveau vers le SDK Databricks pour Python 0.6.0 ou supérieur, car l'authentification par default du Notebook Databricks est utilisée par la version 0.6.0 et supérieure sur toutes les versions de Databricks Runtime.
Databricks Runtime 15.1 est le premier Databricks Runtime à avoir une version du SDK Databricks pour Python (0.20.0) installée qui prend en charge l'authentification Notebook par default sans mise à niveau requise.
Le tableau suivant présente le support de l'authentification des Notebooks pour Databricks SDK pour Python et les versions de Databricks Runtime :
SDK/Databricks Runtime | 10.4 LTS | 11.3 LTS | 12.3 LTS | 13.3 LTS | 14.3 LTS | 15.1 et versions ultérieures |
|---|---|---|---|---|---|---|
0.1.7 et versions antérieures | ||||||
0.1.10 | ✓ | ✓ | ✓ | ✓ | ✓ | |
0.6.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
0.20.0 et supérieur | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
L’authentification par default du Notebook Databricks repose sur un jeton d’accès personnel Databricks temporaire que Databricks génère automatiquement en arrière-plan pour son propre usage. Databricks supprime ce jeton temporaire après que le notebook a cessé de s'exécuter.
- L’authentification Databricks notebook par default ne fonctionne que sur le nœud driver du cluster et non sur les nœuds worker ou executor du cluster.
- L'authentification des Notebooks Databricks ne fonctionne pas avec les profils de configuration Databricks.
- L’authentification des notebooks Databricks ne fonctionne pas avec Databricks Container Services.
Si vous souhaitez appeler les API au niveau du compte Databricks ou si vous souhaitez utiliser un type d'authentification Databricks autre que l'authentification par default du Notebook Databricks, les types d'authentification suivants sont également pris en charge :
Type d'authentification | Versions de Databricks SDK pour Python |
|---|---|
Toutes les versions | |
0,1,9 et au-dessus | |
Toutes les versions |
Étape 1 : Installer ou mettre à niveau le SDK Databricks pour Python
Le SDK Databricks pour Python est installé by default sur tous les clusters Databricks qui utilisent Databricks Runtime 13.3 LTS ou une version ultérieure.
-
Les notebooks Python Databricks peuvent utiliser le SDK Databricks pour Python tout comme n'importe quelle autre bibliothèque Python. Pour installer ou mettre à niveau la bibliothèque Databricks SDK pour Python sur le cluster Databricks attaché, exécutez la commande magique
%pipà partir d'une cellule de notebook comme suit :Python%pip install databricks-sdk --upgrade -
Après avoir exécuté la commande magique
%pip, vous devez redémarrer Python pour rendre la bibliothèque installée ou mise à niveau disponible pour le notebook. Pour ce faire, exécutez la commande suivante à partir d'une cellule de Notebook immédiatement après la cellule contenant la commande magique%pip:Pythondbutils.library.restartPython() -
Pour afficher la version installée du SDK Databricks pour Python, exécutez la commande suivante à partir d'une cellule de Notebook :
Python%pip show databricks-sdk | grep -oP '(?<=Version: )\S+'
Étape 2 : Exécutez votre code
Dans vos cellules de Notebook, créez du code Python qui importe et appelle ensuite le SDK Databricks pour Python. L'exemple suivant utilise l'authentification default des Notebook Databricks pour lister tous les clusters de votre Workspace Databricks :
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
for c in w.clusters.list():
print(c.cluster_name)
Lorsque vous exécutez cette cellule, une liste des noms de tous les clusters disponibles dans votre Workspace Databricks apparaît.
Pour utiliser un autre type d'authentification Databricks, consultez les Méthodes d'autorisation et cliquez sur le lien correspondant pour plus de détails techniques.
Utiliser les utilitaires Databricks
Vous pouvez utiliser les Databricks Utilities du Databricks SDK pour le code Python exécuté sur votre machine de développement locale ou depuis un Notebook Databricks.
- Depuis votre machine de développement locale, Databricks Utilities n'a accès qu'aux groupes de commandes
dbutils.fs,dbutils.secrets,dbutils.widgetsetdbutils.jobs. - Depuis un Notebook Databricks attaché à un cluster Databricks, Databricks Utilities a accès à tous les groupes de commandes Databricks Utilities disponibles, mais le groupe de commandes
dbutils.notebookest limité à deux niveaux de commandes seulement, par exempledbutils.notebook.runoudbutils.notebook.exit.
Pour appeler les Utilitaires Databricks depuis votre machine de développement locale ou un notebook Databricks, utilisez dbutils dans WorkspaceClient. Cet exemple de code utilise l'authentification default de notebook Databricks pour appeler dbutils dans WorkspaceClient afin de lister les chemins d'accès de tous les objets dans la racine DBFS du Workspace.
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
d = w.dbutils.fs.ls('/')
for f in d:
print(f.path)
Sinon, vous pouvez appeler dbutils directement. Cependant, vous êtes limité à l'utilisation de l'authentification Notebook Databricks par default uniquement. Cet exemple de code appelle directement dbutils pour lister tous les objets dans la racine DBFS du workspace.
from databricks.sdk.runtime import *
d = dbutils.fs.ls('/')
for f in d:
print(f.path)
Pour accéder aux volumes Unity Catalog, utilisez files dans WorkspaceClient. Consultez Gérer les fichiers dans les volumes Unity Catalog. Vous ne pouvez pas utiliser dbutils seul ni dans WorkspaceClient pour accéder aux volumes.
Voir aussi Interaction avec dbutils.
Exemples de code
Les exemples de code suivants montrent comment utiliser le SDK Databricks pour Python pour créer et supprimer des clusters, exécuter des jobs et lister les groupes au niveau du compte. Ces exemples de code utilisent l'authentification de notebook Databricks default. Pour plus de détails sur l'authentification de notebook Databricks par default, consultez Utiliser le SDK Databricks pour Python à partir d'un Notebook Databricks. Pour plus de détails sur l'authentification default en dehors des notebooks, consultez Authentifier le SDK Databricks pour Python avec votre compte ou Workspace Databricks.
Pour des exemples de code supplémentaires, consultez les exemples dans le repository du SDK Python Databricks sur GitHub. Voir aussi :
Créer un cluster
Cet exemple de code crée un cluster avec la version spécifiée de Databricks Runtime et le type de nœud de cluster. Ce cluster a un Worker, et le cluster sera automatiquement arrêté après 15 minutes d’inactivité.
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 = 'i3.xlarge',
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")
Supprimer définitivement un cluster
Cet exemple de code supprime définitivement le cluster avec l'ID de cluster spécifié du Workspace.
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)
Créer un Job
Cet exemple de code crée un Job Databricks qui exécute le notebook spécifié sur le cluster spécifié. Lorsque le code s’exécute, il obtient le chemin d’accès du notebook existant, l’ID du cluster existant et les paramètres de Job associés de l’utilisateur au terminal.
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")
Créez un Job qui utilise le compute serverless
L'exemple suivant crée un job qui utilise Compute Serverless pour les Jobs:
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/someone@example.com/MyNotebook",
source = Source("WORKSPACE")
),
task_key = "MyTask",
)
]
)
Gérer les fichiers dans les volumes Unity Catalog
Cet exemple de code démontre divers appels à la fonctionnalité files au sein de WorkspaceClient pour accéder à un volume Unity Catalog. Pour plus d'information, veuillez consulter la documentation complète du SDK.
Le SDK Databricks pour Python offre deux façons d'upload et de download des fichiers. upload_from et download_to sont recommandés pour les chemins de fichiers locaux. upload et download sont recommandés pour les données en mémoire et les interfaces de Stream. Les quatre méthodes prennent en charge les fichiers jusqu'à la taille maximale prise en charge par le stockage cloud sous-jacent lors de l'utilisation du SDK v0.72.0 ou d'une version plus récente.
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 (method 1: recommended when your data is in a local file path)
w.files.upload_from(volume_file_path, upload_file_path, overwrite=True)
# Upload a file to a volume (method 2: recommended when your data is in-memory, or not a local file)
with open(upload_file_path, "rb") as f:
w.files.upload(volume_file_path, io.BytesIO(f.read()), 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)
# Download a file from a volume (method 1: recommended when data needs to be stored in a local file; fastest)
w.files.download_to(volume_file_path, local_download_path)
# Download a file from a volume (method 2: recommended when you need the data in-memory)
resp = w.files.download(volume_file_path)
chunk_size = 8192
with resp.contents as f:
while True:
chunk = f.read(chunk_size)
if not chunk:
break
print(f"Read {len(chunk)} characters")
# 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)
Lister les groupes au niveau du compte
Cet exemple de code liste les noms d'affichage de tous les groupes disponibles dans le compte Databricks.
L'authentification native du Notebook n'est pas prise en charge pour AccountClient, vous devez donc définir les informations d'identification dans le constructeur pour exécuter cet exemple dans un Notebook.
from databricks.sdk import AccountClient
a = AccountClient()
for g in a.groups.list():
print(g.display_name)
Test
Pour tester votre code, utilisez des frameworks de test Python tels que pytest. Pour tester votre code dans des conditions simulées sans appeler les Endpoint de l'API REST Databricks ni modifier l'état de vos comptes ou Workspace Databricks, utilisez des bibliothèques de simulation Python telles que unittest.mock.
Databricks Labs fournit un plugin pytest pour simplifier les tests d'intégration avec Databricks et un plugin pylint pour garantir la qualité du code.
Le fichier d'exemple suivant nommé helpers.py contient une fonction create_cluster qui renvoie des informations sur le nouveau 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
Étant donné le fichier suivant nommé main.py qui appelle la fonction create_cluster :
# 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)
Le fichier suivant nommé test_helpers.py teste si la fonction create_cluster renvoie la réponse attendue. Plutôt que de créer un cluster dans le Workspace cible, ce test simule un objet WorkspaceClient, définit les paramètres de l'objet simulé, puis transmet l'objet simulé à la fonction create_cluster. Le test vérifie ensuite si la fonction renvoie l'ID attendu du nouveau cluster simulé.
# 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'
Pour exécuter ce test, exécutez la commande pytest depuis la racine du projet de code, ce qui devrait produire des résultats de test similaires à ceux-ci :
$ 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 ==========================
Dépannage
Cette section décrit des solutions aux problèmes courants avec le SDK Databricks pour Python.
Pour signaler des problèmes ou tout autre commentaire, créez un problème GitHub pour le SDK Databricks pour Python.
Erreur : Impossible d'analyser la réponse
Si vous recevez l'erreur suivante lorsque vous tentez d'utiliser le SDK Databricks pour Python, cela indique presque toujours un problème avec votre configuration d'authentification.
Error: unable to parse response. This is likely a bug in the Databricks SDK for Python or the underlying REST API.
Si vous rencontrez cette erreur, vérifiez ce qui suit :
- Assurez-vous que votre hôte Databricks est correctement configuré.
- Confirmez que la méthode d’authentification dispose des autorisations requises pour l’opération d’API que vous tentez d’effectuer.
- Si vous êtes derrière un pare-feu d'entreprise, assurez-vous qu'il ne bloque ni ne redirige le trafic API.
Une cause fréquente de cette erreur est le Link privé qui redirige le SDK vers une page de connexion, que le SDK ne peut pas traiter. Cela se produit généralement en essayant d'accéder à un Workspace compatible Link privé, configuré sans accès Internet public, à partir d'un réseau différent de celui auquel appartient l'Endpoint Virtual Private Cloud (VPC).
Pour plus de détails, consultez :
Ressources supplémentaires
Pour plus d'informations, voir :