Azure Databricks REST API

Diese Seite beschreibt die Azure Databricks REST API, den Aufruf und einige Best Practices.

Für eine vollständige Referenz für die Databricks REST API siehe Databricks REST API-Referenz.

Note

Mit Ausnahme fortgeschrittener Szenarien empfiehlt Databricks, die Databricks SDKs oder die Databricks CLI anstelle der Databricks REST API zur programmatischen Verwaltung von Databricks-Objekten zu verwenden.

Vergleich von Workspace- und Account-REST-APIs

Azure Databricks bietet zwei Sätze von REST-APIs an. Workspace-APIs verwalten Ressourcen innerhalb eines einzelnen Arbeitsbereichs, wie Cluster, Jobs, Notizbücher und Unity-Catalog-Objekte, und Sie rufen sie mit Ihrer Workspace-URL als Host auf. Konto-APIs verwalten kontoweite Ressourcen wie Benutzer- und Gruppenbereitstellung, Workspace-Erstellung, Netzwerk- und Abrechnungskonfiguration sowie Unity Catalog-Einstellungen auf Kontoebene, und Sie rufen sie über die Login-URL und Konto-ID Ihrer Kontokonsole auf.

Für die in jedem Set verfügbaren Operationen siehe die Workspace-API-Referenz und die Account-API-Referenz.

Aufrufen einer REST-API

Ein Databricks REST API-Aufruf umfasst die folgenden Komponenten:

  • Je nachdem, ob es sich um einen Arbeitsbereich oder einen Kontoendpunkt handelt, gilt entweder:
  • Der REST-API-Operationstyp, z. B. GET, POST, PATCH oder DELETE.
  • Der REST-API-Operationspfad, wie zum Beispiel /api/2.0/clusters/get.
  • Databricks-Authentifizierungsinformationen , wie zum Beispiel ein Databricks OAuth-Token.
  • Jede Anfragenutzlast oder Anfrageparameter, die von der REST-API-Operation unterstützt werden, wie z. B. die ID eines Clusters.

Informationen dazu, wie eine REST-API-Anfrage strukturiert wird und wie Antwortnutzdaten für Ihr bevorzugtes Entwicklertool geparst werden, finden Sie in der Dokumentation Ihres Anbieters.

Beispiel 1: Clustern abholen

Das folgende Beispiel ruft den Cluster-Listen-Endpunkt auf, um eine Liste verfügbarer Cluster zurückzugeben. Es wird angenommen, dass die DATABRICKS_HOST Umgebungsvariable auf die URL Ihres Databricks-Arbeitsbereichs gesetzt ist und DATABRICKS_TOKEN auf ein Databricks-Token gesetzt ist.

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())

Beispiel 2: Einen Job ausführen

Das folgende Beispiel ruft den Endpunkt Job, Run Now auf, um einen Dry Run eines bestehenden Jobs auszulösen. Es wird angenommen, dass die DATABRICKS_HOST Umgebungsvariable auf die URL Ihres Databricks-Arbeitsbereichs gesetzt ist und DATABRICKS_TOKEN auf ein Databricks-Token gesetzt ist.

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

Beispiel 3: Zurückkehrende Kontonutzer

Das folgende Beispiel ruft den Endpunkt Account User, List auf, um Benutzer in dem durch <account_id> identifizierten Databricks-Konto aufzulisten:

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())

Bewährte Methoden

Die folgenden Abschnitte beschreiben einige Best Practices für die Performance, während die Daten in Ihrem Arbeitsbereich wachsen.

Paginate-API-Antworten LIST

LIST APIs liefern Ergebnisse in Seiten statt einer einzigen großen Antwort zurück. Um eine vollständige Ergebnismenge abzurufen, fordern Sie die erste Seite an und verwenden Sie dann das Token in der Antwort, um jede weitere Seite anzufordern, bis kein Token zurückgegeben wird.

Um eine vollständige Ergebnismenge durchzublättern:

  • Lies das Feld next_page_token aus jeder Antwort. Um die nächste Seite anzufordern, übergeben Sie ihren Wert im Abfrageparameter page_token Ihrer nächsten Anfrage, und behalten Sie alle anderen Anfrageparameter unverändert bei.
  • Wiederholen Sie dies, bis eine Antwort next_page_token weglässt oder next_page_token als leeren Wert zurückgibt. Diese Antwort ist die letzte Seite. Fordern Sie weiterhin Seiten an, auch wenn eine Seite keine Ergebnisse enthält.
  • page_token nicht in die erste Anfrage einfügen. Füge es nur für Folgeanfragen hinzu.

Der Parameter, der die Seitengröße steuert, variiert je nach API. Zum Beispiel verwenden max_resultseinige APIs , andere verwenden page_size, und wieder andere verwenden limit. Überprüfen Sie die REST-API-Referenz auf die Parameter, die jeder Endpunkt unterstützt.

Note

Einige ältere LIST-APIs von Unity Catalog liefern Ergebnisse nur in Seiten zurück, wenn Sie max_results angeben. Legen Sie max_results=0 fest, damit der Server die Seitengröße wählen kann, oder legen Sie einen positiven Wert fest, um eine Seitengröße anzufordern. Weitere Informationen finden Sie unter REST-API-Operationen des Unity Catalog paginieren.

Umgang mit 429-Rate-Limit-Antworten

Databricks setzt Ratenbeschränkungen für REST-API-Aufrufe durch, um Arbeitsbereiche auch unter hoher Last responsiv zu halten. Für jeden Endpunkt und pro Arbeitsbereich werden Begrenzungen angewendet, um eine faire Nutzung und Verfügbarkeit zu unterstützen. Eine Anfrage, die das Ratenlimit überschreitet, gibt eine HTTP-Antwort 429 Too Many Requests zurück.

Behandeln Sie 429-Antworten ordnungsgemäß, indem Sie den Vorgang mit exponentiellem Backoff und Jitter wiederholen:

  • Exponentieller Rückschritt: Nach einem 429, warten Sie vor einem erneuten Versuch und verdoppeln Sie die Wartezeit nach jedem weiteren 429. Setze eine maximale Wartezeit und eine maximale Anzahl von Wiederholungen, damit eine Anfrage nicht unbegrenzt erneut versucht.
  • Jitter: Füge jeder Wartezeit eine kleine zufällige Zeit hinzu. Jitter verteilt die Wiederholungsversuche mehrerer Clients so, dass sie nicht alle gleichzeitig erfolgen und wiederholte Datenverkehrsspitzen verursachen.
  • Wenn eine Antwort einen Header Retry-After enthält, warte mindestens so lange, bevor du es erneut versuchst.

Die meisten HTTP-Client-Bibliotheken können dieses Retry-Verhalten für dich anwenden. Für Hintergrundinformationen zum Algorithmus siehe Exponentielles Backoff und Jitter.

Für die Rate-Limits, die für bestimmte APIs gelten, siehe die API-Rate-Limits in API-Rate-Limits.

Antwortfelder zur Leistungssteigerung kürzen

Einige LIST APIs geben Felder zurück, deren Berechnung aufwendig ist oder die die Antworten umfangreich machen. Wenn Sie diese Felder nicht benötigen, verwenden Sie die Anfrageparameter, die sie weglassen, um die Antwortgröße zu reduzieren und die Latenz zu verbessern.

Zum Beispiel unterstützt die Unity Catalog Tables API folgende Parameter :

  • omit_properties=true: Lässt das properties Feld aus jeder Tabelle in der Antwort weg.
  • omit_columns=true: Lässt das columns Feld aus jeder Tabelle in der Antwort weg.

Wenn du Tabellen nur auflistest, um deren Namen abzurufen, gibt das Setzen beider Parameter eine kleinere Antwort zurück und listet Tabellen schneller auf. Überprüfen Sie die REST API-Referenz auf die Feldtrimming-Parameter, die jeder Endpunkt unterstützt.

Weitere Ressourcen