Partage via


SDK Databricks pour Python

Remarque

Databricks recommande databricks Asset Bundles pour la création, le développement, le déploiement et le test de travaux et d’autres ressources Databricks en tant que code source. Consultez Que sont les packs de ressources Databricks ?.

Dans cet article, vous allez apprendre à automatiser les opérations Azure Databricks et à accélérer le développement avec le Kit de développement logiciel (SDK) Databricks pour Python. Cet article complète la documentation du Kit de développement logiciel (SDK) Databricks pour Python sur Read The Docs et les exemples de code dans le référentiel du SDK Databricks pour Python dans GitHub.

Remarque

Le Kit de développement logiciel (SDK) Databricks pour Python est en version bêta et peut être utilisé en production.

Pendant la période bêta, Databricks vous recommande d’épingler une dépendance à la version mineure spécifique du SDK Databricks pour Python dont dépend votre code. Par exemple, vous pouvez épingler 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.

Avant de commencer

Vous pouvez utiliser le Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Azure Databricks ou de votre ordinateur de développement local.

Avant de commencer à utiliser le kit SDK Databricks pour Python, assurez-vous que votre ordinateur de développement dispose des éléments suivants :

  • L’authentification Azure Databricks configurée
  • Python 3.8 ou ultérieur installé. Pour automatiser les ressources de calcul Azure Databricks, Databricks recommande d’installer les versions principales et mineures de Python qui correspondent à celle installée sur votre ressource de calcul Azure Databricks cible. Les exemples de cet article s’appuient sur l’automatisation des clusters avec Databricks Runtime 13.3 LTS, sur lequel Python 3.10 est installé. Pour obtenir la version correcte, consultez Versions des notes de publication de Databricks Runtime et compatibilité pour la version 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 Kit de développement logiciel (SDK) Databricks pour Python. Les environnements virtuels Python vous permettent de vous assurer que votre projet de code utilise des versions compatibles des packages Python et Python (dans ce cas, le package Databricks SDK pour Python). Pour plus d’informations sur les environnements virtuels Python, consultez venv ou Poetry.

Bien démarrer avec le kit SDK Databricks pour Python

Cette section explique comment prendre en main le Kit de développement logiciel (SDK) Databricks pour Python à partir de votre ordinateur de développement local. Pour utiliser le Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Azure Databricks, passez directement à Utiliser le Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Azure Databricks.

  1. Sur votre machine de développement avec l’authentification Azure 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 de l’index de package Python (PyPI), comme suit :

    Venv

    Utilisez pip pour installer le package databricks-sdk. (Sur certains systèmes, vous devrez peut-être remplacer pip3 par pip, ici et durant toute la procédure.)

    pip3 install databricks-sdk
    

    Poetry

    poetry add databricks-sdk
    

    Pour installer une version spécifique du package databricks-sdk pendant que le kit SDK Databricks pour Python est en phase bêta, consultez l’historique des mises en production du package. Par exemple, pour installer la version 0.1.6 :

    Venv

    pip3 install databricks-sdk==0.1.6
    

    Poetry

    poetry add databricks-sdk==0.1.6
    

    Pour mettre à niveau une installation existante du package SDK Databricks pour Python vers la dernière version, exécutez la commande suivante :

    Venv

    pip3 install --upgrade databricks-sdk
    

    Poetry

    poetry add databricks-sdk@latest
    

    Pour afficher la Version actuelle du package du kit SDK Databricks pour Python et d’autres détails, exécutez la commande suivante :

    Venv

    pip3 show databricks-sdk
    

    Poetry

    poetry show databricks-sdk
    
  2. Dans votre environnement virtuel Python, créez un fichier de code Python qui importe le Kit de développement logiciel (SDK) Databricks pour Python. L’exemple suivant, qui se trouve dans un fichier nommé main.py avec le contenu suivant, dresse simplement la liste de tous les clusters de l’espace de travail Azure Databricks :

    from databricks.sdk import WorkspaceClient
    
    w = WorkspaceClient()
    
    for c in w.clusters.list():
      print(c.cluster_name)
    
  3. Exécutez votre fichier de code Python, en exécutant la commande python dans l’hypothèse d’un fichier nommé main.py :

    Venv

    python3.10 main.py
    

    Poetry

    Si vous êtes dans l’interpréteur de commandes de l’environnement virtuel :

    python3.10 main.py
    

    Si vous n’êtes pas dans l’interpréteur de commandes de l’environnement virtuel :

    poetry run python3.10 main.py
    

    Remarque

    En ne définissant aucun argument dans l'appel précédent à w = WorkspaceClient(), le SDK Databricks pour Python utilise son processus par défaut pour tenter d'effectuer l'authentification Azure Databricks. Pour remplacer ce comportement par défaut, consultez la section d’authentification suivante.

Authentification du kit SDK Databricks pour Python avec un compte ou un espace de travail Azure Databricks

Cette section explique comment authentifier le Kit de développement logiciel (SDK) Databricks pour Python à partir de votre ordinateur de développement local sur votre compte ou espace de travail Azure Databricks. Pour authentifier le Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Azure Databricks, passez directement à Utiliser le Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Azure Databricks.

Le kit SDK Databricks pour Python implémente la norme d’authentification unifiée du client Databricks, une approche architecturale et programmatique consolidée et cohérente pour l’authentification. Cette approche permet de rendre la configuration et l’automatisation de l’authentification avec Azure Databricks plus centralisées et prévisibles. Elle vous permet de configurer une fois l’authentification Databricks, puis d’utiliser cette configuration sur plusieurs outils Databricks et kits de développement logiciel sans modifier la configuration de l’authentification. Pour plus d’informations, notamment des exemples de code plus complets dans Python, consultez Authentification unifiée du client Databricks.

Remarque

Le SDK Databricks pour Python n’a pas encore implémenté l’authentification avec des identités managées Azure.

Voici quelques-uns des modèles de codage disponibles pour initialiser l’authentification Databricks avec le kit SDK Databricks pour Python :

  • Utilisez l’authentification par défaut de Databricks en effectuant l’une des opérations suivantes :

    • Créez ou identifiez un profil de configuration Databricks personnalisé avec les champs requis pour le type d’authentification Databricks cible. Ensuite, définissez la variable d’environnement DATABRICKS_CONFIG_PROFILE sur le nom du profil de configuration personnalisé.
    • Définissez les variables d’environnement requises pour le type d’authentification Databricks cible.

    Instanciez ensuite un objet WorkspaceClient avec l’authentification par défaut Databricks comme suit :

    from databricks.sdk import WorkspaceClient
    
    w = WorkspaceClient()
    # ...
    
  • Le codage des champs requis effectué de manière irréversible est pris en charge, mais non recommandé, car il risque d’exposer des informations sensibles dans votre code, telles que les jetons d’accès personnels Azure Databricks. L’exemple suivant montre le codage de l’hôte Azure Databricks et des valeurs de jeton d’accès effectué de manière irréversible pour l’authentification par jeton Databricks :

    from databricks.sdk import WorkspaceClient
    
    w = WorkspaceClient(
      host  = 'https://...',
      token = '...'
    )
    # ...
    

Consultez également Authentification dans la documentation du Kit de développement logiciel (SDK) Databricks pour Python.

Utiliser le Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Azure Databricks

Vous pouvez appeler la fonctionnalité de Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Azure Databricks qui a un cluster Azure Databricks attaché avec le SDK Databricks pour Python installé. Il est installé par défaut sur tous les clusters Azure Databricks qui utilisent Databricks Runtime 13.3 LTS ou une version ultérieure. Pour les clusters Azure Databricks qui utilisent Databricks Runtime 12.2 LTS et les versions antérieures, vous devez d’abord installer le kit de développement logiciel (SDK) Databricks pour Python. Consultez Étape 1 : Installer ou mettre à niveau le SDK Databricks pour Python.

Pour connaître la version du SDK Databricks 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 à partir de PiPy, mais au minimum d’installer ou de mettre à niveau vers SDK Databricks pour Python 0.6.0 ou version ultérieure, car l’authentification par défaut du notebook Azure Databricks est utilisée par la version 0.6.0 et ultérieure sur toutes les versions de Databricks Runtime.

Remarque

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 de notebook par défaut sans mise à niveau requise.

Le tableau suivant décrit la prise en charge de l’authentification des notebooks pour les versions du SDK Databricks pour Python et Databricks Runtime :

SDK/DBR 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 versions ultérieures

L’authentification par défaut des notebooks Azure Databricks s’appuie sur un jeton d’accès personnel Azure Databricks temporaire généré automatiquement en arrière-plan par Azure Databricks pour sa propre utilisation. Azure Databricks supprime ce jeton temporaire après l’arrêt de l’exécution du notebook.

Important

  • L’authentification par défaut du notebook Azure Databricks fonctionne uniquement sur le nœud pilote du cluster, mais pas sur les nœuds de travail ou d’exécution du cluster.
  • L’authentification des notebooks Azure Databricks ne fonctionne pas avec les profils de configuration Azure Databricks.

Si vous souhaitez appeler des API au niveau du compte Azure Databricks ou si vous souhaitez utiliser un type d’authentification Databricks autre que l’authentification par défaut du notebook Databricks, les types d’authentification suivants sont également pris en charge :

Type d’authentification Versions du SDK Databricks pour Python
Authentification OAuth machine à machine (M2M) 0.18.0 et versions ultérieures
Authentification utilisateur à machine (U2M) OAuth 0.19.0 et versions ultérieures
Authentification du principal de service Microsoft Entra ID Toutes les versions
Authentification Azure CLI Toutes les versions
Authentification par jeton d’accès personnel Databricks Toutes les versions

L’authentification par identités managées Azure n’est pas encore prise en charge.

Étape 1 : Installer ou mettre à niveau le SDK Databricks pour Python

  1. Les notebooks Python Azure Databricks peuvent utiliser le Kit de développement logiciel (SDK) Databricks pour Python comme n’importe quelle autre bibliothèque Python. Pour installer ou mettre à niveau le SDK Databricks pour Python sur le cluster Azure Databricks attaché, exécutez la commande magic %pip à partir d’une cellule de notebook comme suit :

    %pip install databricks-sdk --upgrade
    
  2. Après avoir exécuté la commande magic %pip, vous devez redémarrer Python afin que la bibliothèque installée ou mise à niveau soit accessible au notebook. Pour ce faire, exécutez la commande suivante à partir d’une cellule de notebook immédiatement après la cellule avec la commande magic %pip:

    dbutils.library.restartPython()
    
  3. Pour afficher la version installée du SDK Databricks pour Python, exécutez la commande suivante à partir d’une cellule de notebook :

    %pip show databricks-sdk | grep -oP '(?<=Version: )\S+'
    

Étape 2 : exécuter votre code

Dans vos cellules de notebook, créez du code Python qui importe, puis appelle le Kit de développement logiciel (SDK) Databricks pour Python. L’exemple suivant utilise l’authentification par défaut des notebooks Azure Databricks pour répertorier tous les clusters de votre espace de travail Azure 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 espace de travail Azure Databricks s’affiche.

Pour utiliser un autre type d’authentification Azure Databricks, consultez Méthodes d’authentification Azure Databricks, puis cliquez sur le lien correspondant pour obtenir des détails techniques supplémentaires.

Utiliser les utilitaires Databricks

Vous pouvez appeler Référence des utilitaires Databricks (dbutils) à partir du code du Kit de développement logiciel (SDK) Databricks pour Python s’exécutant sur votre ordinateur de développement local ou à partir d’un notebook Azure Databricks.

  • À partir de votre ordinateur de développement local, Databricks Utilities a accès uniquement aux groupes de commandes dbutils.fs, dbutils.secrets, dbutils.widgets et dbutils.jobs.
  • À partir d’un notebook Azure Databricks attaché à un cluster Azure Databricks, Databricks Utilities a accès à tous les groupes de commandes Databricks Utilities disponibles, pas seulement dbutils.fs, dbutils.secretset dbutils.widgets. En outre, le groupe de commandes dbutils.notebook est limité à deux niveaux de commandes uniquement, par exemple dbutils.notebook.run ou dbutils.notebook.exit.

Pour appeler des utilitaires Databricks à partir de votre machine de développement locale ou d’un notebook Azure Databricks, utilisez dbutils dans WorkspaceClient. Cet exemple de code utilise l’authentification par défaut des notebooks Azure Databricks pour appeler dbutils dans WorkspaceClient afin de lister les chemins d’accès de tous les objets à la racine DBFS de l’espace de travail.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
d = w.dbutils.fs.ls('/')

for f in d:
  print(f.path)

Vous pouvez également appeler dbutils directement. Toutefois, vous êtes limité à l’utilisation de l’authentification par défaut des notebooks Azure Databricks uniquement. Cet exemple de code appelle dbutils directement pour répertorier tous les objets à la racine DBFS de l’espace de travail.

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. Voir Gérer des fichiers dans des volumes Unity Catalog. Vous ne pouvez pas utiliser dbutils seul ou dans WorkspaceClient pour accéder aux volumes.

Voir aussi Interaction avec dbutils.

Exemples de code

Les exemples de code suivants montrent comment utiliser le kit SDK Databricks pour Python afin de créer et supprimer des clusters, exécuter des travaux et répertorier les groupes de niveau de comptes. Ces exemples de code utilisent l’authentification par défaut des notebooks Azure Databricks. Pour plus d’informations sur l’authentification par défaut des notebooks Azure Databricks, consultez Utiliser le Kit de développement logiciel (SDK) Databricks pour Python à partir d’un notebook Azure Databricks. Pour plus d’informations sur l’authentification par défaut en dehors des notebooks, consultez Authentifier le Kit de développement logiciel (SDK) Databricks pour Python avec votre compte ou espace de travail Azure Databricks.

Pour obtenir d’autres exemples de code, consultez les exemples du référentiel du kit SDK Databricks pour Python sur GitHub. Voir aussi :

Créer un cluster

Cet exemple de code crée un cluster avec la version Databricks Runtime et le type de nœud de cluster spécifiés. Ce cluster possède un Worker et s’arrête automatiquement après 15 minutes de temps 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             = '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")

Supprimer définitivement un cluster

Cet exemple de code supprime définitivement de l’espace de travail le cluster possédant l’ID spécifié.

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 travail

Cet exemple de code crée un travail Azure Databricks qui exécute le notebook spécifié sur le cluster indiqué. Il récupère le chemin du notebook existant, l’ID de cluster existant et les paramètres de travail associés auprès de l’utilisateur sur le 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éer un travail qui utilise un calcul serverless

L’exemple suivant crée un travail qui utilise Calcul serverless pour les travaux:

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

Gérer les fichiers dans les volumes de catalogue Unity

Cet exemple de code illustre différents appels aux files fonctionnalités au sein WorkspaceClient pour accéder à un volume de catalogue 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)

Répertorier les groupes au niveau du compte

Cet exemple de code répertorie les noms complets de tous les groupes disponibles dans le compte Azure Databricks.

from databricks.sdk import AccountClient

a = AccountClient()

for g in a.groups.list():
  print(g.display_name)

Test

Pour tester votre code, utilisez des infrastructures de test Python comme pytest. Pour tester votre code dans des conditions simulées sans appeler des points de terminaison d’API REST d’Azure Databricks ni modifier l’état de vos comptes ou espaces de travail Azure Databricks, utilisez des bibliothèques fictives Python comme unittest.mock.

Conseil

Databricks Labs fournit un plug-in pytest pour simplifier les tests d’intégration avec Databricks et un plug-in pylint pour garantir la qualité du code.

L’exemple de fichier nommé helpers.py suivant contient une create_cluster fonction qui retourne 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 create_cluster fonction :

# 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 retourne la réponse attendue. Au lieu de créer un cluster dans l’espace de travail cible, ce test simule un objet WorkspaceClient, définit les paramètres de l’objet fictif, puis transmet l’objet fictif à la fonction create_cluster. Le test vérifie ensuite si la fonction retourne l’ID attendu du nouveau cluster fictif.

# 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, qui doit produire des résultats de test similaires à ce qui suit :

$ 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 ==========================

Ressources supplémentaires

Pour plus d'informations, consultez les pages suivantes :