Azure Databricks REST API

Ez az oldal bemutatja az Azure Databricks REST API-t, annak megnevezését, valamint néhány legjobb gyakorlatot.

A Databricks REST API teljes hivatkozásáért lásd a Databricks REST API referencia címet.

Note

A fejlett forgatókönyvek kivételével a Databricks azt javasolja, hogy a Databricks SDK-kat vagy a Databricks CLI-t használják a Databricks REST API helyett a Databricks objektumok programozott kezelésére.

Munkaterület kontra fiók REST API-k

Az Azure Databricks két REST API-készletet biztosít. A workspace API-k egyetlen workspace-en belül kezelik az erőforrásokat, például klasztereket, feladatokat, jegyzetfüzeteket és Unity Catalog objektumokat, és ezeket a saját munkaterületi URL-jével hívod meg, mint host. A fiók API-k a fiók egészére kiterjedő erőforrásokat kezelik, mint például a felhasználói és csoportos létrehozás, a munkaterület létrehozása, hálózati és számlázási konfiguráció, valamint a fiókszintű Unity katalógus beállítások, és ezeket a fiókkonzol bejelentkezési URL-je és számla azonosítója alapján hívod meg.

Az egyes halmazban elérhető műveletekért lásd a workspace API hivatkozást és a account API hivatkozást.

REST API meghívása

A Databricks REST API hívás az alábbi komponenseket tartalmazza:

  • Attól függően, hogy munkaterület- vagy fiókvégpontról van szó, a következők egyikét:
  • A REST API művelettípus, például GET, POST, PATCH, vagy DELETE.
  • A REST API műveleti útvonala, például /api/2.0/clusters/get.
  • Databricks hitelesítési információk, például egy Databricks OAuth token.
  • Bármilyen kérési hasznos vagy lekérdezési paraméter, amelyet a REST API művelet támogat, például egy klaszter azonosítója.

A REST API kérés strukturálásáról és a válaszraketek elemzéséről a kedvenc fejlesztői eszközödhöz a szolgáltatód dokumentációjában olvashatod meg.

1. példa: Klasztereket szerezz

A következő példa a Cluster, List végpontot hívja, hogy visszaadja az elérhető klaszterek listáját. Feltételezi, hogy a DATABRICKS_HOST környezeti változó a Databricks munkaterület URL-jére van állítva, és DATABRICKS_TOKEN egy Databricks tokenre van állítva.

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élda 2: Feladat futtatása

A következő példa a Job, Run Now végpontot hívja, hogy egy meglévő feladat próbafuttatását indítsa el. Feltételezi, hogy a DATABRICKS_HOST környezeti változó a Databricks munkaterület URL-jére van állítva, és DATABRICKS_TOKEN egy Databricks tokenre van állítva.

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

3. példa: Visszatérő fiókfelhasználók

A következő példa a Account User, List végpontot hívja, hogy visszaadja a Databricks fiókban szereplő felhasználókat, akiket a következők azonosítottak <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())

Bevált gyakorlatok

Az alábbi szakaszok néhány legjobb teljesítménygyakorlatot mutatnak be, ahogy a munkaterületed adatai növekednek.

Az API-válaszok lapozása LIST

LIST Az API-k az eredményeket lapokra bontva adják vissza, nem egyetlen nagy méretű válaszban. A teljes eredményhalmaz megkéréséhez kérd az első oldalt, majd a válaszban a tokent használjuk minden következő oldal megkéréséhez, amíg nem érkezik vissza token.

A teljes eredményhalmaz átnézéséhez:

  • Állítsd max_results=0 be a kérésedet. Ez lehetővé teszi a szerver számára, hogy megfelelő oldalméretet válasszon, ami hatékonyabb, mint egy oldalonként fix számú eredmény kérése.
  • Olvasd ki minden válaszból a next_page_token mezőt. A következő oldal kéréséhez add meg az értékét a page_token következő kérés lekérdezési paraméterében.
  • Ismételd addig, amíg egy válasz nem tartalmazza a(z) next_page_token elemet, vagy üres értékként adja vissza. Ez a válasz az utolsó oldal.
  • Ne vegyük page_token bele az első kérésbe. Csak további kérésekhez add be.

A következő példa ezt a mintát használja, hogy minden táblát a sémában a Unity Catalog Table, List endpointből lehessen szerezni. Ugyanez a kör működik bármely LIST API-nál. Csak a végpont és a tömbmező neve változik a válaszban. Például a Grants végpont egy privilege_assignments tömböt ad vissza a tableshelyett.

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

429 sebességkorlátos válaszokat kezelni

A databricks előírja a REST API hívások sebességkorlátozásait, hogy a munkaterületek nagy terhelés alatt reagálóak maradjanak. Korlátokat alkalmaznak végpontenként és munkaterületenként, hogy támogassa a tisztességes használatot és elérhetőséget. A sebességkorlátot túllépő kérés HTTP 429 Too Many Requests választ ad vissza.

Kezeld 429 a válaszokat elegánsan azzal, hogy exponenciális visszalépéssel és jitterrel próbáld újra:

  • Exponenciális visszalépés: egy 429után várjon újrapróbálkozás előtt, és minden következő 429után duplázza meg a várakozási időt. Állíts be maximális várakozási időt és maximális számú újrapróbálkozást, hogy egy kérés ne próbálkozzon újra határozatlan időre.
  • Jitter: Adj hozzá egy kis véletlenszerű időt minden várakozáshoz. A Jitter több klienstől szétosztja az újrapróbálkozásokat, hogy ne mindegyik egyszerre próbálkozzon, és ismételt forgalmat okozzon.
  • Ha a válasz fejlécet tartalmaz Retry-After , várj legalább ennyi időt, mielőtt újra próbálkoznál.

A legtöbb HTTP klienskönyvtár képes alkalmazni ezt a próbálkozási viselkedést helyetted. Az algoritmus háttérinformációiért lásd: Exponenciális visszahúzás és jitter.

Az API-kra vonatkozó sebességkorlátokról lásd az API sebességkorlátokat az API sebességkorlátok részén.

Válaszmezők levágása a teljesítmény érdekében

Néhány LIST API olyan mezőket ad vissza, amelyek költséges számítása vagy amelyek nagyra teszik a válaszokat. Ha nincs szükséged ezekre a mezőkre, használd azokat a kérésparamétereket, amelyek kihagyják őket, hogy csökkentsd a válaszméretet és javítsd a késleltetést.

Például a Unity Catalog Tables API a következő paramétereket támogatja:

  • omit_properties=true: A válaszban minden táblából kihagyja a properties mezőt.
  • omit_columns=true: A válaszban minden táblából kihagyja a columns mezőt.

Ha csak a nevüket szeretnéd felsorolni, mindkét paraméter beállítása kisebb választ ad és gyorsabban listázza a táblákat. Nézd meg a REST API hivatkozást a mezővágási paraméterekért, amelyeket minden végpont támogat.

További erőforrások

  • Last updated on