Azure Databricks REST API

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

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

Note

À l’exception des scénarios avancés, Databricks recommande d’utiliser les SDKs Databricks ou la ligne de commande Databricks plutôt que l’API REST Databricks pour gérer les objets Databricks de manière programmatique.

API REST de l’espace de travail vs API REST du compte

Azure Databricks fournit deux ensembles d’API REST. Les API d’espace de travail gèrent les ressources à l’intérieur d’un seul espace de travail, telles que les clusters, les jobs, les notebooks et les objets du catalogue Unity, et vous les appelez en utilisant votre URL d’espace de travail comme hôte. Les API de compte gèrent les ressources à l’échelle du compte, telles que la provisionnement des utilisateurs et des groupes, la création d’espaces de travail, la configuration réseau et de facturation, ainsi que les paramètres du catalogue Unity au niveau du compte, et vous les appelez via l’URL de connexion de votre console de compte et l’identifiant de compte.

Pour les opérations disponibles dans chaque ensemble, voir la référence API de l’espace de travail et la référence de l’API du compte.

Appeler une API REST

Un appel API REST Databricks comprend les composants suivants :

  • Selon qu’il s’agisse d’un espace de travail ou d’un point de terminaison 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 Databricks OAuth.
  • Tout corps de requête ou paramètre de requête pris en charge par l’opération de l’API REST, comme l’ID d’un cluster.

Pour des informations sur la structure d’une requête API REST et sur la manière d’analyser les charges utiles de réponse pour votre outil développeur préféré, consultez la documentation de votre fournisseur.

Exemple 1 : Obtenir des clusters

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

curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"

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écutez un travail

L’exemple suivant appelle le terminau Job, Run Now pour déclencher un test à blanc d’un travail existant. Il suppose que la variable d’environnement DATABRICKS_HOST est définie sur l’URL de votre espace de travail Databricks et DATABRICKS_TOKEN sur un jeton Databricks.

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"
    }
  }'

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 : Retour des utilisateurs de compte

L’exemple suivant appelle le point de terminaison Account User, List pour renvoyer les utilisateurs du compte Databricks identifié par <account_id>:

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

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 dans votre espace de travail augmentent.

Paginer LIST les réponses de l’API

LIST Les API renvoient des résultats en pages au lieu d’une seule réponse importante. Pour récupérer un ensemble complet de résultats, demandez la première page, puis utilisez le jeton dans la réponse pour demander chaque page suivante jusqu’à ce qu’aucun jeton ne soit retourné.

Pour parcourir un ensemble complet de résultats :

  • Indiquez max_results=0 dans votre demande. 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 next_page_token champ de chaque réponse. Pour demander la page suivante, passez sa valeur dans le page_token paramètre de requête de votre prochaine requête.
  • Répétez jusqu’à ce qu’une réponse l’omette next_page_token ou la renvoie comme une valeur vide. Cette réponse est la dernière page.
  • N’incluez page_token pas dans la première demande. Ajoute-le uniquement pour les demandes de suivi.

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

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 du débit

Databricks impose des limites de débit sur les appels API REST afin de garder les espaces de travail réactifs sous une forte charge. Des limites sont appliquées par terminaison et par espace de travail afin de garantir une utilisation équitable et une disponibilité. Une requête dépassant la limite de débit renvoie une réponse HTTP 429 Too Many Requests .

Gérez 429 les réponses avec grâce en réessayant avec un recul exponentiel et un tremblement :

  • Retrait exponentiel : Après un 429, attendez avant de réessayer, et doublez le temps d’attente après chaque .429 Fixez un temps d’attente maximal et un nombre maximal de tentatives pour qu’une requête ne soit pas réessaie indéfiniment.
  • Jitter : Ajoutez une petite durée aléatoire à chaque délai d’attente. Le jitter répartit les réessais de plusieurs clients afin qu’ils ne réessaient pas tous en même temps et ne provoquent pas des rafales répétées de trafic.
  • Si une réponse inclut un Retry-After en-tête, attendez au moins ce temps avant de réessayer.

La plupart des bibliothèques clients HTTP peuvent appliquer ce comportement de réessai pour vous. Pour un contexte sur l’algorithme, voir Retour exponentiel et jitter.

Pour les limites de taux applicables à des API spécifiques, voir les limites de taux API dans les limites de taux API.

Réduire les champs de réponse pour améliorer les performances

Certaines LIST API renvoient des champs coûteux à calculer ou qui rendent les réponses très volumineuses. 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 des tables de catalogue Unity prend en charge les paramètres suivants :

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

Si vous ne listez les tables que pour récupérer leurs noms, définir les deux paramètres donne une réponse plus petite et liste les tables plus rapidement. Vérifiez la référence de l’API REST pour les paramètres de découpe de champs que chaque point de terminaison supporte.

Ressources additionnelles

  • Last updated on