Azure Databricks REST API

Ta strona opisuje Azure Databricks REST API, jak je wywołać oraz niektóre najlepsze praktyki.

Pełne odniesienie do API-interfejsu REST Databricks można znaleźć w artykule o API-interfejsie Databricks REST.

Note

Z wyjątkiem zaawansowanych scenariuszy, Databricks zaleca stosowanie SDK Databricks lub CLI Databricks zamiast API REST Databricks do programowego zarządzania obiektami Databricks.

Workspace vs interfejsy REST konta

Azure Databricks udostępnia dwa zestawy REST API. API Workspace zarządzają zasobami wewnątrz jednej przestrzeni roboczej, takimi jak klastry, zadania, notatniki i obiekty Unity Catalog, a wywołujesz je za pomocą adresu URL workspace jako hosta. API konta zarządzają zasobami dla całego konta, takimi jak udostępnianie użytkowników i grup, tworzenie przestrzeni roboczych, konfiguracja sieci i rozliczeń oraz ustawienia katalogu Unity na poziomie konta, a ty wywołujesz je za pomocą adresu logowania do konsoli konta i identyfikatora konta.

Aby poznać dostępne operacje w każdym zestawie, zobacz referencję API w przestrzeni roboczej oraz referencję do API konta.

Wywoływanie interfejsu API REST

Wywołanie API REST Databricks zawiera następujące komponenty:

  • W zależności od tego, czy jest to punkt końcowy obszaru roboczego czy konta, wybierz jedną z opcji:
  • Typ operacji REST API, taki jak GET, POST, PATCH, lub DELETE.
  • Ścieżka operacji REST API, taka jak /api/2.0/clusters/get.
  • Informacje o uwierzytelnianiu Databricks, takie jak token OAuth Databricks.
  • Dowolna treść żądania lub parametry zapytania żądania obsługiwane przez operację interfejsu API REST, takie jak identyfikator klastra.

Aby uzyskać informacje o strukturze żądania REST API oraz jak analizować payloady odpowiedzi dla preferowanego narzędzia deweloperskiego, zapoznaj się z dokumentacją swojego operatora.

Przykład 1: Pobierz klastry

Poniższy przykład wywołuje punkt końcowy Cluster, List, aby zwrócić listę dostępnych klastrów. Zakłada, że zmienna środowiskowa DATABRICKS_HOST jest ustawiona na adres URL obszaru roboczego Databricks, a zmienna DATABRICKS_TOKEN jest ustawiona 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())

Przykład 2: Uruchom zadanie

Poniższy przykład wywołuje punkt końcowy Job, Run Now, aby uruchomić próbę testową istniejącego zadania. Przyjmuje się, że zmienna środowiskowa DATABRICKS_HOST jest ustawiona na adres URL Twojego obszaru roboczego Databricks, a DATABRICKS_TOKEN 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')}")

Przykład 3: Użytkownicy konta zwrotnego

Poniższy przykład wywołuje punkt końcowy Account User, List, aby zwrócić użytkowników na koncie Databricks identyfikowanym przez <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())

Najlepsze rozwiązania

Poniższe sekcje opisują najlepsze praktyki wydajności wraz ze wzrostem danych w Twojej przestrzeni roboczej.

Paginacja odpowiedzi API LIST

LIST Interfejsy API zwracają wyniki w postaci stron zamiast jednej dużej odpowiedzi. Aby uzyskać pełny zestaw wyników, zażądaj pierwszej strony, a następnie użyj tokena w odpowiedzi, aby żądać każdej kolejnej strony, aż token nie zostanie zwrócony.

Aby przejrzeć pełny zestaw wyników:

  • Ustaw max_results=0 w swoim żądaniu. Pozwala to serwerowi wybrać odpowiedni rozmiar strony, co jest bardziej efektywne niż żądanie stałej liczby wyników na stronę.
  • Przeczytaj pole next_page_token z każdej odpowiedzi. Aby zażądać następnej strony, przekaż jej wartość w parametrze page_token zapytania następnego żądania.
  • Powtarzaj, aż odpowiedź pominie next_page_token lub zwróci je jako pustą wartość. Ta odpowiedź to ostatnia strona.
  • Nie uwzględniaj page_token w pierwszej prośbie. Dodaj go tylko do kolejnych zgłoszeń.

Poniższy przykład wykorzystuje ten wzorzec do pobrania wszystkich tabel w schemacie z punktu końcowego Unity Catalog Table, List. Ta sama pętla działa dla każdego LIST API. Zmienia się tylko punkt końcowy i nazwa pola tablicy w odpowiedzi. Na przykład, punkt końcowy Grants zwraca wyniki w tablicy privilege_assignments zamiast 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

Obsłudz 429 odpowiedzi z limitem szybkości

Databricks nakłada limity liczby wywołań REST API, aby zapewnić responsywność obszarów roboczych przy dużym obciążeniu. Limity są stosowane na każdy punkt końcowy i na przestrzeń roboczą, aby wspierać uczciwe wykorzystanie i dostępność. Żądanie przekraczające limit prędkości zwraca odpowiedź HTTP 429 Too Many Requests .

Obsługuj odpowiedzi 429 w sposób bezpieczny, ponawiając próby z wykładniczo wydłużanymi odstępami i losowym opóźnieniem:

  • Wykładnicze wydłużanie czasu między ponownymi próbami: Po 429 odczekaj przed ponowną próbą i podwajaj czas oczekiwania po każdym kolejnym 429. Ustaw maksymalny czas oczekiwania i maksymalną liczbę ponowień, aby żądanie nie było ponawiane w nieskończoność.
  • Jitter: Dodaj do każdego czasu oczekiwania niewielką losową wartość czasu. Jitter rozkłada w czasie ponowienia prób pochodzące od wielu klientów, aby nie wszyscy ponawiali je w tym samym momencie i nie powodowali powtarzających się skoków ruchu.
  • Jeśli odpowiedź zawiera Retry-After nagłówek, poczekaj przynajmniej tyle długo, zanim spróbujesz ponownie.

Większość bibliotek klienckich HTTP może automatycznie stosować ten mechanizm ponawiania. Aby poznać algorytm, zobacz wykładnicze cofnięcie i drżenie.

Informacje o limitach liczby żądań dotyczących poszczególnych interfejsów API znajdziesz w sekcji Limity liczby żądań interfejsu API.

Przytnij pola odpowiedzi, aby zwiększyć wydajność

Niektóre LIST interfejsy API zwracają pola, których obliczenie jest kosztowne obliczeniowo lub które powiększają odpowiedzi. Gdy nie potrzebujesz tych pól, użyj parametrów żądań, które je pomijają, aby zmniejszyć rozmiar odpowiedzi i poprawić opóźnienia.

Na przykład API Unity Catalog Tables obsługuje następujące parametry:

  • omit_properties=true: Pomija pole properties w każdej tabeli w odpowiedzi.
  • omit_columns=true: Pomija pole columns w każdej tabeli w odpowiedzi.

Jeśli wyświetlasz listę tabel wyłącznie po to, aby pobrać ich nazwy, ustawienie obu parametrów zwraca mniejszą odpowiedź i szybciej wyświetla listę tabel. Sprawdź w referencji API REST parametry przycinania pól, które obsługuje każdy punkt końcowy.

Dodatkowe zasoby

  • Last updated on