Azure Databricks REST API

Tato stránka popisuje Azure Databricks REST API, jak jej volat a některé osvědčené postupy.

Pro úplnou referenci pro Databricks REST API viz odkaz na Databricks REST API.

Note

S výjimkou pokročilých scénářů Databricks doporučuje používat Databricks SDK nebo Databricks CLI místo Databricks REST API pro programovou správu Databricks objektů.

Pracovní prostor vs REST API pro účet

Azure Databricks poskytuje dvě sady REST API. API pracovních prostor spravují zdroje uvnitř jednoho pracovního prostoru, jako jsou clustery, úlohy, zápisníky a objekty Unity Catalog, a vy je voláte pomocí URL vašeho pracovního prostoru jako hostitele. Rozhraní API účtu spravují prostředky na úrovni účtu, jako je zřizování uživatelů a skupin, vytváření pracovních prostorů, konfigurace sítě a fakturace a nastavení služby Unity Catalog na úrovni účtu, a voláte je pomocí své přihlašovací adresy URL ke konzoli účtu a ID účtu.

Pro operace dostupné v každé sadě viz odkaz na API pracovního prostoru a odkaz na API účtu.

Zavolat REST API

Volání Databricks REST API obsahuje následující komponenty:

Pro informace o tom, jak strukturovat požadavek REST API a jak parsovat payloady pro váš preferovaný vývojářský nástroj, navštivte dokumentaci vašeho poskytovatele.

Příklad 1: Získejte shluky

Následující příklad volá endpoint Cluster, List pro vrácení seznamu dostupných clusterů. Předpokládá se, že proměnná prostředí DATABRICKS_HOST je nastavena na adresu URL vašeho pracovního prostoru Databricks a proměnná DATABRICKS_TOKEN je nastavena na token 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())

Příklad 2: Spuskut úkol

Následující příklad volá endpoint Job, Run Now k zahájení suchého testu existující úlohy. Předpokládá se, že proměnná prostředí DATABRICKS_HOST je nastavena na adresu URL vašeho pracovního prostoru Databricks a DATABRICKS_TOKEN je nastavena na token 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')}")

Příklad 3: Vrátit uživatele účtu

Následující příklad volá koncový bod Account User, List k vrácení seznamu uživatelů v účtu Databricks identifikovaném pomocí <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())

Osvědčené postupy

Následující sekce popisují některé osvědčené postupy v oblasti výkonu, jak se data ve vašem pracovním prostoru zvyšují.

Stránkování LIST odpovědí API

LIST API vrací výsledky na stránkách místo jedné velké odpovědi. Pro získání kompletní sady výsledků požádejte o první stránku, poté použijte token v odpovědi k požadavku na každou následující stránku, dokud žádný token není vrácen.

Pro prohledání kompletní sady výsledků:

  • Nastavte max_results=0 ve svém požadavku. To umožňuje serveru zvolit vhodnou velikost stránky, což je efektivnější než požadavek na pevný počet výsledků na stránku.
  • Přečtěte si next_page_token pole z každé odpovědi. Pro požadavek na další stránku zadejte její hodnotu do parametru page_token dotazu vašeho dalšího požadavku.
  • Opakujte, dokud odpověď nevynechá next_page_token nebo nevrátí hodnotu jako prázdnou. Tato odpověď je poslední stránkou.
  • Do prvního požadavku nezahrnujte page_token. Přidejte ho pouze pro následné žádosti.

Následující příklad používá tento vzor k získání každé tabulky ve schématu z endpointu Unity Catalog Table, List. Stejný cyklus funguje pro jakékoli LIST API. Mění se pouze koncový bod a název pole pole v odpovědi. Například Grantsův koncový bod vrací pole privilege_assignments místo 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

Zvládněte 429 reakcí s limitem rychlosti

Databricks vynucuje omezení rychlosti u volání REST API, aby pracovní prostory zůstaly responzivní i při vysoké zátěži. Limity jsou aplikovány na každý koncový bod a na pracovní prostor, aby se podpořilo spravedlivé používání a dostupnost. Požadavek, který překročí limit rychlosti, vrátí 429 Too Many Requests HTTP odpověď.

Reagujte s grácií tím, že to zkusíte 429 znovu s exponenciálním odstupem a třesem:

  • Exponenciální prodleva: Po chybě 429 počkejte před dalším pokusem a po každém dalším selhání 429 dobu čekání zdvojnásobte. Nastavte maximální čekací dobu a maximální počet opakování, aby se požadavek neopakoval donekonečna.
  • Jitter: Přidej k každému čekání malý náhodný čas. Jitter časově rozkládá opakované pokusy u více klientů, aby je všichni neopakovali ve stejný okamžik a nezpůsobovali tak opakované špičky provozu.
  • Pokud odpověď obsahuje hlavičku Retry-After , počkejte alespoň tolik, než to zkusíte znovu.

Většina HTTP klientských knihoven vám toto chování při opakovaném pokusu může aplikovat. Informace o algoritmu naleznete v článku Exponenciální backoff a jitter.

Pro limity rychlosti, které se vztahují na konkrétní API, viz limity API v API rate limitech.

Omezte pole odpovědi kvůli výkonu

Některá LIST API vracejí pole, která jsou nákladná na výpočet nebo která vytvářejí velké odpovědi. Když tato pole nepotřebujete, použijte parametry požadavků, které je vynechávají, abyste snížili velikost odpovědi a zlepšili latenci.

Například API Unity Catalog Tables podporuje následující parametry:

  • omit_properties=true: Vynechá pole properties z každé tabulky v odpovědi.
  • omit_columns=true: Vynechá pole columns z každé tabulky v odpovědi.

Pokud tabulky uvádíte jen proto, abyste získali jejich názvy, nastavení obou parametrů vrátí menší odezvu a tabulky zobrazí rychleji. Zkontrolujte v REST API referenci parametry ořezávání polí, které každý koncový bod podporuje.

Dodatečné zdroje

  • Last updated on