Azure Databricks REST API

Esta página describe la API REST de Azure Databricks, cómo llamarla y algunas buenas prácticas.

Para referencia completa de la API REST de Databricks, consulte la referencia de la API REST de Databricks.

Nota:

Con la excepción de escenarios avanzados, Databricks recomienda usar los SDKs de Databricks o la CLI de Databricks en lugar de la API REST de Databricks para gestionar programáticamente los objetos de Databricks.

API REST de espacio de trabajo vs cuenta

Azure Databricks proporciona dos conjuntos de APIs REST. Las APIs de espacio de trabajo gestionan recursos dentro de un único espacio de trabajo, como clústeres, trabajos, cuadernos y objetos del Catálogo de Unity, y los llamas usando la URL de tu espacio de trabajo como anfitriona. Las APIs de cuenta gestionan recursos a nivel de cuenta, como la provisión de usuarios y grupos, creación de espacios de trabajo, configuración de red y facturación, y ajustes de Unity Catalog a nivel de cuenta, y los llamas usando la URL de inicio de sesión de tu consola de cuenta e ID de cuenta.

Para las operaciones disponibles en cada conjunto, consulte la referencia de la API del espacio de trabajo y la referencia de la API de la cuenta.

Llamada a una API REST

Una llamada a la API REST de Databricks incluye los siguientes componentes:

Para información sobre cómo estructurar una solicitud de API REST y cómo analizar las cargas útiles de respuesta para tu herramienta de desarrollo preferida, consulta la documentación de tu proveedor.

Ejemplo 1: Consigue clústeres

El siguiente ejemplo llama al Cluster, List endpoint para obtener una lista de clústeres disponibles. Asume que la variable de entorno DATABRICKS_HOST está establecida en la URL de tu espacio de trabajo de Databricks y que DATABRICKS_TOKEN está establecida en un token de 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())

Ejemplo 2: Ejecutar un trabajo

El siguiente ejemplo llama al endpoint Job, Run Now para activar un ensayo general de un trabajo existente. Supone que la variable de entorno DATABRICKS_HOST está configurada con la URL de tu espacio de trabajo de Databricks y que DATABRICKS_TOKEN está configurada con un token de 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')}")

Ejemplo 3: Devolver usuarios de cuentas

El siguiente ejemplo invoca el endpoint Account User, List para devolver los usuarios de la cuenta de Databricks identificada por <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())

procedimientos recomendados

Las siguientes secciones describen algunas buenas prácticas de rendimiento a medida que crecen los datos en tu espacio de trabajo.

Paginar LIST respuestas de la API

LIST Las APIs devolven resultados en páginas en lugar de una única respuesta grande. Para recuperar un conjunto completo de resultados, solicita la primera página y luego usa el token en la respuesta para solicitar cada página posterior hasta que no se devuelva ningún token.

Para recorrer el conjunto completo de resultados:

  • Establece max_results=0 en tu solicitud. Esto permite al servidor elegir un tamaño de página apropiado, lo cual es más eficiente que solicitar un número fijo de resultados por página.
  • Lee el next_page_token campo de cada respuesta. Para solicitar la siguiente página, pasa su valor en el page_token parámetro de consulta de tu siguiente petición.
  • Repite hasta que una respuesta la omita next_page_token o la devuelva como valor vacío. Esa respuesta es la última página.
  • No incluyas page_token en la primera solicitud. Añádelo solo para solicitudes de seguimiento.

El siguiente ejemplo utiliza este patrón para recuperar todas las tablas de un esquema desde el extremo de la Tabla de Catálogo de Unity, Lista. El mismo bucle funciona para cualquier LIST API. Solo cambian el extremo y el nombre del campo del array en la respuesta. Por ejemplo, el endpoint Grants devuelve los resultados en una matriz privilege_assignments en lugar de 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

Gestionar 429 respuestas con límite de tasa

Databricks aplica límites de velocidad en las llamadas a API REST para mantener los espacios de trabajo responsivos bajo una carga elevada. Se aplican límites por endpoint y por espacio de trabajo para facilitar un uso y disponibilidad justos. Una petición que supera el límite de tasa devuelve una respuesta HTTP 429 Too Many Requests .

Gestiona 429 las respuestas con elegancia intentando de nuevo con un retroceso exponencial y un tremor:

  • Retroceso exponencial: Después de un 429, espera antes de volver a intentarlo y duplica el tiempo de espera tras cada .429 Establece un tiempo máximo de espera y un número máximo de intentos para que una solicitud no se vuelva a intentar indefinidamente.
  • Jitter: Añade una pequeña cantidad aleatoria de tiempo a cada tiempo de espera. El jitter dispersa los intentos de varios clientes para que no se reintenten todos al mismo tiempo y provoquen ráfagas repetidas de tráfico.
  • Si una respuesta incluye un Retry-After encabezado, espera al menos ese tiempo antes de volver a intentarlo.

La mayoría de las bibliotecas de cliente HTTP pueden aplicar este comportamiento de reintento por usted. Para contexto sobre el algoritmo, véase Retroceso exponencial y jitter.

Para los límites de tasa que se aplican a APIs específicas, véanse los límites de tasa de la API en los límites de tasa de la API.

Reducir los campos de respuesta para mejorar el rendimiento

Algunas LIST APIs devolven campos que son caros de calcular o que hacen que las respuestas sean grandes. Cuando no necesites estos campos, usa los parámetros de solicitud que los omiten para reducir el tamaño de la respuesta y mejorar la latencia.

Por ejemplo, la API de Tablas de Catálogo de Unity soporta los siguientes parámetros:

  • omit_properties=true: Omite el campo properties de cada tabla en la respuesta.
  • omit_columns=true: Omite el campo columns de cada tabla de la respuesta.

Si solo listas tablas para recuperar sus nombres, establecer ambos parámetros devuelve una respuesta más pequeña y lista tablas más rápido. Consulta la referencia de la API REST para los parámetros de recorte de campos que soporta cada endpoint.

Recursos adicionales

  • Last updated on