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. 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 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 la cuenta

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:

  • Lee el next_page_token campo de cada respuesta. Para solicitar la siguiente página, pasa su valor en el parámetro de consulta page_token de tu siguiente petición y mantén todos los demás parámetros iguales.
  • Repite hasta que una respuesta la omita next_page_token o la devuelva como valor vacío. Esa respuesta es la última página. Sigue solicitando páginas aunque una no contenga resultados.
  • No incluyas page_token en la primera solicitud. Añádelo solo para solicitudes de seguimiento.

El parámetro que controla el tamaño de la página varía según la API. Por ejemplo, algunas APIs usan max_results, otras usan page_size, y otras usan limit. Consulta la referencia de la API REST para ver los parámetros que soporta cada endpoint.

Nota:

Algunas APIs antiguas de Unity Catalog LIST solo devolven resultados en páginas cuando especificas max_results. Configura max_results=0 para que el servidor elija el tamaño de la página, o fija un valor positivo para solicitar un tamaño de página. Para más información, consulte Paginar las operaciones de la API de REST de Unity Catalog.

Administrar respuestas 429 de límite de frecuencia

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:

  • Retraso exponencial: Tras un 429, espera antes de volver a intentarlo y duplica el tiempo de espera tras cada 429 posterior. 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 en 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

  • Se actualizó por última vez el