Azure Databricks REST API

Den här sidan beskriver Azure Databricks REST API, hur man kallar det och några bästa praxis.

För fullständig referens för Databricks REST API, se Databricks REST API-referens.

Note

Med undantag för avancerade scenarier rekommenderar Databricks att använda Databricks SDK:er eller Databricks CLI istället för Databricks REST API för att programmatiskt hantera Databricks-objekt.

Arbetsyta kontra konto: REST-API:er

Azure Databricks tillhandahåller två uppsättningar REST-API:er. Workspace-API:er hanterar resurser inom en enda arbetsyta, såsom kluster, jobb, notebooks och Unity Catalog-objekt, och du anropar dem med din workspace-URL som värd. Konto-API:er hanterar kontoövergripande resurser, såsom användar- och gruppprovisionering, skapande av arbetsytor, nätverks- och faktureringskonfiguration samt kontonivå-inställningar i Unity-katalogen, och du anropar dem med din kontokonsols inloggnings-URL och konto-ID.

För de operationer som finns tillgängliga i varje uppsättning, se arbetsytans API-referens och kontots API-referens.

Anropa ett REST-API

Ett Databricks REST API-anrop inkluderar följande komponenter:

  • Beroende på om det är en arbetsyta eller kontoterminal, antingen:
  • REST API-operationstypen, såsom GET, , , PATCH, eller DELETEPOST.
  • REST API:s operationsvägar, såsom /api/2.0/clusters/get.
  • Databricks-autentiseringsinformation , såsom en Databricks OAuth-token.
  • Alla nyttolaster i begäran eller frågeparametrar i begäran som stöds av REST API-åtgärden, till exempel ID för ett kluster.

För information om hur man strukturerar en REST API-förfrågan och hur man tolkar responspayloads för ditt föredragna utvecklarverktyg, se din leverantörs dokumentation.

Exempel 1: Hämta kluster

Följande exempel anropar Cluster, List-endpointen för att returnera en lista över tillgängliga kluster. Den antar att miljövariabeln DATABRICKS_HOST är inställd på din Databricks-workspace-URL och DATABRICKS_TOKEN är satt på en Databricks-token.

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

Exempel 2: Kör ett jobb

Följande exempel anropar Job, Run Now-endpointen för att trigga en torrkörning av ett befintligt jobb. Den antar att miljövariabeln DATABRICKS_HOST är inställd på din Databricks-workspace-URL och DATABRICKS_TOKEN är satt på en Databricks-token.

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

Exempel 3: Användare med återvändande konto

Följande exempel anropar Account User, List endpoint för att hämta användare i Databricks-kontot som identifieras av <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())

Metodtips

Följande avsnitt beskriver några bästa prestandapraxis i takt med att datan i din arbetsplats växer.

Paginate LIST API-svar

LIST API:er returnerar resultat i sidor istället för ett enda stort svar. För att hämta en komplett resultatuppsättning, begär den första sidan och använd sedan token i svaret för att begära varje efterföljande sida tills ingen token returneras.

För att bläddra igenom en komplett resultatuppsättning:

  • Skriv max_results=0 in din begäran. Detta låter servern välja en lämplig sidstorlek, vilket är mer effektivt än att begära ett fast antal resultat per sida.
  • Läs next_page_token fältet från varje svar. För att begära nästa sida, skicka dess värde i frågeparametern page_token för din nästa förfrågan.
  • Upprepa tills ett svar utelämnar next_page_token eller returnerar det som ett tomt värde. Det svaret är sista sidan.
  • Inkludera page_token inte i den första förfrågan. Lägg till det endast för uppföljningsförfrågningar.

Följande exempel använder detta mönster för att hämta varje tabell i ett schema från Unity Catalog Table, List-endpointen. Samma loop fungerar för alla LIST API:er. Endast ändpunkten och namnet på arrayfältet i svaret ändras. Till exempel returnerar endpointen Grants resultat i en privilege_assignments-array i stället för 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

Hantera 429-svar om frekvensbegränsning

Databricks upprätthåller hastighetsbegränsningar på REST API-anrop för att hålla arbetsytorna responsiva under tung belastning. Begränsningar tillämpas per slutpunkt och per arbetsyta för att stödja rättvis användning och tillgänglighet. En begäran som överskrider hastighetsgränsen returnerar ett HTTP-svar 429 Too Many Requests .

Hantera 429-svar smidigt genom att försöka igen med exponentiellt ökande väntetid och jitter:

  • Exponentiell tillbakagång: Efter en 429, vänta innan du försöker igen, och dubbla väntetiden efter varje efterföljande 429. Sätt en maximal väntetid och ett maxantal försök så att en begäran inte försöker igen på obestämd tid.
  • Jitter: Lägg till en liten slumpmässig tid på varje väntan. Jitter fördelar omförsök över tid från flera klienter så att de inte alla gör nya försök samtidigt och orsakar återkommande trafiktoppar.
  • Om ett svar innehåller en Retry-After rubrik, vänta minst så länge innan du försöker igen.

De flesta HTTP-klientbibliotek kan tillämpa detta återförsöksbeteende åt dig. För bakgrund om algoritmen, se Exponential backoff and jitter.

För de hastighetsgränser som gäller för specifika API:er, se API-hastighetsgränser i API-hastighetsgränser.

Begränsa svarsfält för bättre prestanda

Vissa LIST API:er returnerar fält som är dyra att beräkna eller som gör svaren stora. När du inte behöver dessa fält, använd de begäranarparametrar som utelämnar dem för att minska svarsstorleken och förbättra latensen.

Till exempel stöder Unity Catalog Tables API följande parametrar:

  • omit_properties=true: Utelämnar properties fältet från varje tabell i svaret.
  • omit_columns=true: Utelämnar columns fältet från varje tabell i svaret.

Om du listar tabeller bara för att hämta deras namn, ger inställningen av båda parametrarna ett mindre svar och listar tabeller snabbare. Kontrollera REST API-referensen för de fälttrimmningsparametrar som varje slutpunkt stödjer.

Ytterligare resurser

  • Last updated on