Azure Databricks REST API

На этой странице описан REST API Azure Databricks, как его вызывать и приведены некоторые лучшие практики.

Для полной информации о REST API Databricks см. ссылку на Databricks REST API.

Note

За исключением продвинутых сценариев, Databricks рекомендует использовать SDK Databricks или CLI Databricks вместо REST API Databricks для программного управления объектами Databricks.

REST API рабочего пространства и учётной записи

Azure Databricks предоставляет два набора REST API. API Workspace управляют ресурсами внутри одного рабочего пространства, такими как кластеры, задачи, блокноты и объекты Unity Catalog, и вы вызываете их, используя URL рабочего пространства в качестве хоста. API аккаунта управляют ресурсами по всей учетной записи, такими как настройка пользователей и групп, создание рабочего пространства, настройка сети и выставления счетов, а также настройки Unity Catalog на уровне аккаунта, и вы вызываете их с помощью URL-адреса входа в консоль аккаунта и идентификатора аккаунта.

Для доступных операций в каждом наборе см. ссылку на API рабочего пространства и ссылку на API аккаунта.

Вызовите REST API

Вызов REST API Databricks включает следующие компоненты:

Сведения о том, как формировать запрос к REST API и как разбирать тела ответов в используемом вами инструменте разработки, см. в документации вашего поставщика.

Пример 1: Получить кластеры

Следующий пример вызывает конечную точку Cluster, List для возврата списка доступных кластеров. Предполагается, что переменная среды DATABRICKS_HOST содержит URL-адрес вашего рабочего пространства Databricks, а DATABRICKS_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())

Пример 2: Выполнить задание

В следующем примере выполняется обращение к эндпоинту Job, Run Now, чтобы запустить тестовый запуск существующей задачи. Предполагается, что переменная среды DATABRICKS_HOST содержит URL рабочей области Databricks, а DATABRICKS_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')}")

Пример 3: Вернувшиеся пользователи аккаунта

Следующий пример вызывает эндпоинт Account User, List endpoint, чтобы получить список пользователей в аккаунте Databricks, идентифицируемом с помощью <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())

Лучшие практики

В следующих разделах описываются лучшие практики по производительности по мере роста данных в вашем рабочем пространстве.

Ответы API на страницах LIST

LIST API возвращают результаты в виде страниц вместо одного крупного ответа. Чтобы получить полный набор результатов, запросите первую страницу, затем используйте токен в ответе, чтобы запросить каждую следующую страницу, пока токен не будет возвращен.

Чтобы просмотреть полный набор результатов:

  • Укажите max_results=0 в запросе. Это позволяет серверу выбрать подходящий размер страницы, что эффективнее, чем запрашивать фиксированное количество результатов на страницу.
  • Читайте поле next_page_token из каждого ответа. Чтобы запросить следующую страницу, передайте её значение в page_token параметре запроса вашего следующего запроса.
  • Повторяйте, пока ответ не пропустит next_page_token или не вернёт его как пустое значение. Этот ответ — последняя страница.
  • Не включайте page_token в первый запрос. Добавляйте его только для последующих запросов.

Следующий пример использует этот шаблон для получения всех таблиц в схеме из конечной точки Unity Catalog Table, List endpoint. Тот же цикл работает для любого LIST API. Меняются только конечная точка и имя поля массива в ответе. Например, эндпоинт Grants возвращает результаты в массиве privilege_assignments вместо 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

Обрабатывайте 429 ответов с ограничением скорости

Databricks устанавливает ограничения по скорости для вызовов REST API, чтобы рабочие пространства оставались оперативными при высокой нагрузке. Ограничения устанавливаются на конечную точку и рабочее пространство для поддержки добросовестного использования и доступности. Запрос, превышающий лимит скорости, возвращает HTTP-ответ 429 Too Many Requests .

Корректно обрабатывайте ответы 429, выполняя повторные попытки с экспоненциальной задержкой и джиттером:

  • Экспоненциальная задержка: после 429 попытки подождите перед повторной попыткой и удваивайте время ожидания после каждой последующей 429 попытки. Установите максимальное время ожидания и максимальное количество повторных попыток, чтобы запрос не повторялся бесконечно.
  • Jitter: Добавьте небольшой случайный интервал времени к каждому периоду ожидания. Jitter распределяет повторные попытки от нескольких клиентов, чтобы они не повторялись одновременно и не вызывали повторные всплески трафика.
  • Если в ответе есть Retry-After заголовок, подождите хотя бы столько времени, прежде чем пробовать снова.

Большинство HTTP-клиентских библиотек могут применять такое повторное поведение для вас. Для информации об алгоритме см. Экспоненциальное отступление и джиттер.

Для ограничений скорости, применимых к конкретным API, см. лимиты скорости API в разделе API.

Сократите поля ответа для повышения производительности

Некоторые LIST API возвращают поля, которые дорого вычислять или делают ответы большими. Если эти поля не нужны, используйте параметры запроса, в которых они опущены, чтобы уменьшить размер ответа и снизить задержку.

Например, API Unity Catalog Tables поддерживает следующие параметры:

  • omit_properties=true: Исключает поле properties из каждой таблицы в ответе.
  • omit_columns=true: Исключает поле columns из каждой таблицы в ответе.

Если вы перечисляете таблицы только ради их названия, установка обоих параметров возвращает меньший ответ и ускоряет список таблиц. Проверьте ссылку REST API на параметры обрезания полей, которые поддерживает каждая конечная точка.

Дополнительные ресурсы

  • Last updated on