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.

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, gibt es entweder:
  • Ihre URL zum Databricks-Arbeitsbereich
  • Ihre Login-URL und Konto-ID Ihrer Databricks-Kontokonsole
• 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:

• Setzen Sie max_results=0 in Ihre Anfrage ein. Dadurch kann der Server eine passende Seitengröße auswählen, was effizienter ist, als eine feste Anzahl von Ergebnissen pro Seite anzufordern.
• Lies das Feld next_page_token aus jeder Antwort. Um die nächste Seite anzufordern, geben Sie ihren Wert im page_token Abfrageparameter Ihrer nächsten Anfrage ein.
• 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.
• page_token nicht in die erste Anfrage einfügen. Füge es nur für Folgeanfragen hinzu.

Das folgende Beispiel verwendet dieses Muster, um jede Tabelle in einem Schema aus dem Unity Catalog Table, List-Endpunkt abzurufen. Die gleiche Schleife funktioniert für jede LIST API. Nur der Endpunkt und der Name des Array-Feldes in der Antwort ändern sich. Zum Beispiel gibt der Grants-Endpunkt Ergebnisse in einem privilege_assignments-Array statt in tables zurück.

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

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 staffelt die erneuten Versuche mehrerer Clients zeitlich, sodass sie nicht alle im selben Moment erneut versuchen und wiederholt Verkehrsspitzen im Datenverkehr 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

• Databricks-SDKs
• Databricks-CLI
• API-Ratenbeschränkungen
• REST-API-Referenz