Azure Databricks REST API

Questa pagina descrive l'API REST di Azure Databricks, come chiamarla e alcune best practice.

Per un riferimento completo all'API REST di Databricks, vedi riferimento all'API REST di Databricks.

Nota

Ad eccezione di scenari avanzati, Databricks raccomanda di utilizzare gli SDK Databricks o la CLI Databricks invece dell'API REST di Databricks per gestire programmaticamente gli oggetti Databricks.

API REST dello spazio di lavoro rispetto a quelle dell'account

Azure Databricks fornisce due insiemi di API REST. Le API di workspace gestiscono risorse all'interno di un unico workspace, come cluster, job, notebook e oggetti del Catalogo Unity, e le chiami usando l'URL del workspace come host. Le API dell’account gestiscono risorse dell’intero account, come il provisioning di utenti e gruppi, la creazione di workspace, la configurazione della rete e della fatturazione e le impostazioni di Unity Catalog a livello di account, e vengono chiamate utilizzando il tuo URL di accesso alla console dell’account e ID account.

Per le operazioni disponibili in ogni insieme, vedi il riferimento API dello spazio di lavoro e il riferimento all'API dell'account.

Chiamare un'API REST

Una chiamata API REST di Databricks include i seguenti componenti:

Per informazioni su come strutturare una richiesta API REST e su come analizzare i payload di risposta per il tuo strumento di sviluppo preferito, consulta la documentazione del tuo provider.

Esempio 1: Ottenere cluster

Il seguente esempio chiama l'endpoint Cluster, List per restituire un elenco dei cluster disponibili. Presume che la variabile di ambiente DATABRICKS_HOST sia impostata sull'URL del tuo workspace Databricks e che DATABRICKS_TOKEN sia impostata su un 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())

Esempio 2: Esegui un lavoro

L'esempio seguente invoca l'endpoint Job, Run Now per avviare un'esecuzione di prova di un job esistente. Presume che la variabile d'ambiente DATABRICKS_HOST sia impostata sull'URL del tuo workspace Databricks e che DATABRICKS_TOKEN sia impostata su un 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')}")

Esempio 3: Recuperare gli utenti dell'account

Il seguente esempio chiama l'endpoint Account User, List per restituire gli utenti nell'account Databricks identificati da <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())

Procedure consigliate

Le sezioni seguenti descrivono alcune best practice sulle prestazioni man mano che i dati nel tuo spazio di lavoro crescono.

Paginazione LIST delle risposte API

LIST Le API restituiscono risultati in pagine invece di una singola risposta ampia. Per recuperare un set completo di risultati, richiedi la prima pagina, poi usa il token nella risposta per richiedere ogni pagina successiva finché non viene restituito alcun token.

Per scorrere un set completo di risultati:

  • Imposta max_results=0 nella tua richiesta. Questo permette al server di scegliere una dimensione di pagina appropriata, il che è più efficiente rispetto a richiedere un numero fisso di risultati per pagina.
  • Leggi il next_page_token campo di ogni risposta. Per richiedere la pagina successiva, passa il suo valore nel page_token parametro di query della tua prossima richiesta.
  • Ripeti finché una risposta non la omette next_page_token o la restituisce come valore vuoto. Quella risposta è l'ultima pagina.
  • Non includere page_token nella prima richiesta. Aggiungilo solo per richieste di follow-up.

L'esempio seguente utilizza questo schema per recuperare ogni tabella in uno schema dalla Unity Catalog Table, endpoint List. Lo stesso ciclo funziona per qualsiasi LIST API. Solo l'endpoint e il nome del campo dell'array nella risposta cambiano. Ad esempio, l'endpoint Grants restituisce i risultati in un array privilege_assignments invece di 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

Gestire 429 risposte al limite di velocità

Databricks applica limiti di velocità sulle chiamate API REST per mantenere gli spazi di lavoro reattivi sotto carichi elevati. Vengono applicati limiti per endpoint e per ogni spazio di lavoro per supportare un uso e una disponibilità equosi. Una richiesta che supera il limite di velocità restituisce una risposta HTTP 429 Too Many Requests .

Gestisci 429 le risposte con grazia riprovando con un retrocesso esponenziale e un tremolamento:

  • Retrocesso esponenziale: Dopo un 429, attendi prima di riprovare e raddoppia il tempo di attesa dopo ogni successivo 429. Imposta un tempo massimo di attesa e un numero massimo di tentativi in modo che una richiesta non riprovi all'infinito.
  • Jitter: Aggiungi una piccola quantità casuale di tempo a ogni attesa. Il jitter distribuisce i tentativi da più client in modo che non riprovino tutti nello stesso momento e non causino ripetuti scarichi di traffico.
  • Se una risposta include un Retry-After header, aspetta almeno quel tempo prima di riprovare.

La maggior parte delle librerie client HTTP può applicare automaticamente questo comportamento di nuovo tentativo. Per informazioni di base sull'algoritmo, vedi Indietro esponenziale e jitter.

Per i limiti di velocità che si applicano a specifiche API, vedi i limiti di velocità API nei limiti di velocità API.

Riduci i campi di risposta per migliorare le prestazioni

Alcune LIST API restituiscono campi costosi da calcolare o che rendono le risposte grandi. Quando non hai bisogno di questi campi, usa i parametri di richiesta che li omettono per ridurre la dimensione della risposta e migliorare la latenza.

Ad esempio, l'API delle Tabelle del Catalogo Unity supporta i seguenti parametri:

  • omit_properties=true: Omette il properties campo da ogni tabella nella risposta.
  • omit_columns=true: Omette il columns campo da ogni tabella nella risposta.

Se elenchi le tabelle solo per recuperare i loro nomi, impostare entrambi i parametri restituisce una risposta più piccola e elenchi le tabelle più velocemente. Controlla il riferimento API REST per i parametri di ritaglio del campo supportati da ogni endpoint.

Risorse aggiuntive

  • Last updated on