Aller au contenu principal
Dernière mise à jour le

API REST Databricks

Cette page décrit l’API REST Databricks, comment l’appeler et quelques bonnes pratiques.

Pour une référence complète sur l’API REST Databricks, consultez la référence de l’API REST Databricks.

remarque

À l’exception des scénarios avancés, Databricks recommande d’utiliser les SDK Databricks ou la CLI Databricks plutôt que l’API REST Databricks pour gérer les objets Databricks par programmation.

APIs REST Workspace vs Account​

Databricks fournit deux ensembles d'APIs REST. Les APIs de workspace gèrent les ressources au sein d'un seul workspace, telles que les clusters, les jobs, les notebooks et les objets Unity Catalog ; vous les appelez en utilisant votre URL de workspace comme hôte. Les APIs de compte gèrent les ressources à l'échelle du compte, telles que le provisionnement des utilisateurs et des groupes, la création de Workspace, la configuration du réseau et de la facturation, ainsi que les paramètres Unity Catalog au niveau du compte ; vous les appelez en utilisant votre URL de connexion à la console de compte et votre ID de compte.

Pour les opérations disponibles dans chaque ensemble, consultez la référence de l’API Workspace et la référence de l’API Account.

Appeler une API REST​

Un appel d’API REST Databricks comprend les composants suivants :

  • Selon qu’il s’agit d’un endpoint de workspace ou de compte, soit :

  • Le type d’opération de l’API REST, tel que GET, POST, PATCH ou DELETE.

  • Le chemin d’opération de l’API REST, tel que /api/2.0/clusters/get.

  • Informations d’authentification Databricks, telles qu’un jeton OAuth Databricks.

  • Toute charge utile de requête ou tout paramètre de query de requête pris en charge par l’opération de l’API REST, tel que l’ID d’un cluster.

Pour plus d’informations sur la façon de structurer une requête API REST et d’analyser les charges utiles de réponse pour votre outil de développement préféré, consultez la documentation de votre fournisseur.

Exemple 1 : Obtenir les clusters​

L’exemple suivant appelle le Cluster, List Endpoint pour renvoyer une liste des clusters disponibles. Il suppose que la variable d’environnement DATABRICKS_HOST est définie sur l’URL de votre workspace Databricks et que DATABRICKS_TOKEN est définie sur un jeton Databricks.

Bash
curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"
Python
import requests
import os

headers = {"Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}"}
response = requests.get(f"{os.getenv('DATABRICKS_HOST')}/api/2.0/clusters/list", headers=headers)

print(response.json())

Exemple 2 : Exécuter un job​

L’exemple suivant appelle l’ endpoint Job, Run Now pour Trigger une exécution à blanc d’un Job existant. Il suppose que la variable d’environnement DATABRICKS_HOST est définie sur votre URL de workspace Databricks et que DATABRICKS_TOKEN est définie sur un jeton Databricks.

Bash
curl -X POST "$DATABRICKS_HOST/api/2.1/jobs/run-now" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": 45678,
    "notebook_params": {
      "dry_run": "true",
      "start_date": "2026-08-27"
    }
  }'
Python
import requests
import os

url = f"{os.getenv('DATABRICKS_HOST')}/api/2.1/jobs/run-now"
headers = {
    "Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}",
    "Content-Type": "application/json"
}
payload = {
    "job_id": 45678,
    "notebook_params": {"dry_run": "true", "start_date": "2026-08-27"}
}

response = requests.post(url, headers=headers, json=payload)
print(f"Run ID: {response.json().get('run_id')}")

Exemple 3 : Renvoyer les utilisateurs du compte​

L’exemple suivant appelle l’ endpoint Account User, List pour renvoyer les utilisateurs du compte Databricks identifié par <account_id>:

Bash
curl -X GET '<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users' \
  --header "Authorization: Bearer $OAUTH_TOKEN"
Python
import requests
import os

url = "<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users"
headers = {"Authorization": f"Bearer {os.getenv('OAUTH_TOKEN')}"}

response = requests.get(url, headers=headers)
print(response.json())

Bonnes pratiques​

Les sections suivantes décrivent certaines bonnes pratiques de performance à mesure que les données de votre workspace augmentent.

Paginer les réponses de l’API LIST​

Les API LIST renvoient les résultats par pages plutôt que sous la forme d’une seule réponse volumineuse. Pour récupérer un ensemble de résultats complet, demandez la première page, puis utilisez le jeton contenu dans la réponse pour demander chaque page suivante jusqu’à ce qu’aucun jeton ne soit renvoyé.

Pour parcourir un ensemble complet de résultats :

  • Définissez max_results=0 dans votre requête. Cela permet au serveur de choisir une taille de page appropriée, ce qui est plus efficace que de demander un nombre fixe de résultats par page.
  • Lisez le champ next_page_token de chaque réponse. Pour demander la page suivante, transmettez sa valeur dans le paramètre de requête page_token de votre prochaine demande.
  • Répétez jusqu’à ce qu’une réponse omette next_page_token ou la renvoie comme une valeur vide. Cette réponse est la dernière page.
  • N’incluez pas page_token dans la première demande. Ajoutez-le uniquement pour les demandes de suivi.

L'exemple suivant utilise ce modèle pour récupérer chaque table d'un schéma à partir du Unity Catalog Table, List endpoint. La même boucle fonctionne pour n'importe quelle API LIST. Seuls le endpoint et le nom du champ de tableau dans la réponse changent. Par exemple, le Grants endpoint renvoie des résultats dans un tableau privilege_assignments au lieu de tables.

Python
import requests

base_url = "https://example.cloud.databricks.com"  # No trailing slash
bearer_token = "<your-personal-access-token>"
catalog_name = "main"
schema_name = "default"


def list_tables(base_url, bearer_token, catalog_name, schema_name):
    endpoint = f"{base_url}/api/2.1/unity-catalog/tables"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    params = {
        "catalog_name": catalog_name,
        "schema_name": schema_name,
        "max_results": 0,  # Let the server choose the page size.
    }

    tables = []
    while True:
        response = requests.get(endpoint, headers=headers, params=params)
        response.raise_for_status()
        body = response.json()

        tables.extend(body.get("tables", []))

        # Stop when the response no longer includes a page token.
        page_token = body.get("next_page_token")
        if not page_token:
            break
        params["page_token"] = page_token

    return tables

Gérer les réponses 429 de limitation de débit​

Databricks applique des limites de débit aux appels d’API REST afin de maintenir la réactivité des workspaces en cas de forte charge. Les limites sont appliquées par Endpoint et par Workspace afin de garantir une utilisation équitable et la disponibilité. Une requête qui dépasse la limite de débit renvoie une réponse HTTP 429 Too Many Requests.

Gérez les réponses 429 avec élégance en effectuant une nouvelle tentative avec un intervalle exponentiel et une gigue :

  • Exponential backoff : Après un 429, patientez avant de réessayer, et doublez le temps d'attente après chaque 429 suivant. Définissez une durée d’attente maximale et un nombre maximal de nouvelles tentatives afin qu’une requête ne soit pas réessayée indéfiniment.
  • Jitter : ajoutez un court laps de temps aléatoire à chaque attente. Le jitter répartit les tentatives de connexion de plusieurs clients afin qu’ils ne réessayent pas tous au même moment, ce qui éviterait des pics de trafic répétés.
  • Si une réponse inclut un en-tête Retry-After, attendez au moins cette durée avant de réessayer.

La plupart des bibliothèques clientes HTTP peuvent appliquer ce comportement de nouvelle tentative pour vous. Pour en savoir plus sur l’algorithme, consultez Exponential backoff and jitter.

Pour les limites de débit qui s’appliquent à des APIs spécifiques, consultez les limites de débit de l’API dans API rate limits.

Tronquer les champs de réponse pour améliorer les performances​

Certaines API LIST renvoient des champs coûteux à calculer ou qui alourdissent les réponses. Lorsque vous n’avez pas besoin de ces champs, utilisez les paramètres de requête qui les omettent pour réduire la taille de la réponse et améliorer la latence.

Par exemple, l'API Unity Catalog Tables prend en charge les paramètres suivants :

  • omit_properties=true: omet le champ properties de chaque table dans la réponse.
  • omit_columns=true: omet le champ columns de chaque table dans la réponse.

Si vous listez des tables uniquement pour récupérer leurs noms, la définition des deux parameters permet d’obtenir une réponse plus petite et de lister les tables plus rapidement. Consultez la référence de l’API REST pour connaître les parameters de tronquage de champ pris en charge par chaque endpoint.

Ressources supplémentaires​

Sur cette page