Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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:
- Ihre URL zum Databricks-Arbeitsbereich
- Ihre Login-URL und Konto-ID Ihrer Databricks-Kontokonsole
- Der REST-API-Operationstyp, z. B.
GET,POST,PATCHoderDELETE. - 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_tokenaus jeder Antwort. Um die nächste Seite anzufordern, übergeben Sie ihren Wert im Abfrageparameterpage_tokenIhrer nächsten Anfrage, und behalten Sie alle anderen Anfrageparameter unverändert bei. - Wiederholen Sie dies, bis eine Antwort
next_page_tokenweglässt odernext_page_tokenals leeren Wert zurückgibt. Diese Antwort ist die letzte Seite. Fordern Sie weiterhin Seiten an, auch wenn eine Seite keine Ergebnisse enthält. -
page_tokennicht 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 weiteren429. 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-Afterenthä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 daspropertiesFeld aus jeder Tabelle in der Antwort weg. -
omit_columns=true: Lässt dascolumnsFeld 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.