Руководство по API автомасштабирования Lakebase

На этой странице представлен обзор API автомасштабирования Lakebase, включая проверку подлинности, доступные конечные точки и общие шаблоны для работы с REST API, Databricks CLI и пакетами SDK Databricks (Python, Java, Go).

Полный справочник по API см. в документации по API Postgres.

Это важно

API Lakebase Postgres находится в бета-версии. Конечные точки API, параметры и поведение могут быть изменены.

Authentication

API автомасштабирования Lakebase использует проверку подлинности OAuth на уровне рабочей области для управления инфраструктурой проектов (создание проектов, настройка параметров и т. д.).

Замечание

Два типа подключения: этот API предназначен для управления платформами (создание проектов, ветвей, вычислений). Для доступа к базе данных (подключение к данным запроса):

Клиенты SQL (psql, pgAdmin, DBeaver): используйте маркеры OAuth Lakebase или пароли Postgres. См. раздел Аутентификация.
API данных (RESTful HTTP): используйте токены OAuth Lakebase. См. API данных.
Драйверы языка программирования (psycopg, SQLAlchemy, JDBC): использование маркеров OAuth Lakebase или паролей Postgres. Смотрите Quickstart.

Полное описание этих двух уровней проверки подлинности см. в разделе "Архитектура проверки подлинности".

Настройка проверки подлинности

Проверка подлинности с помощью интерфейса командной строки Databricks:

databricks auth login --host https://your-workspace.cloud.databricks.com

Следуйте инструкциям браузера, чтобы войти в систему. Интерфейс командной строки кэширует маркер OAuth по ~/.databricks/token-cache.jsonадресу.

Затем выберите метод доступа:

пакет SDK Python

Пакет SDK использует единую проверку подлинности и автоматически обрабатывает маркеры OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

пакет SDK Java

Пакет SDK использует единую проверку подлинности и автоматически обрабатывает маркеры OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

интерфейс командной строки (CLI)

Команды автоматически используют кэшированный маркер:

databricks postgres list-projects

завиток

Создайте маркер для прямых вызовов API:

export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

curl -X GET "https://your-workspace.cloud.databricks.com/api/2.0/postgres/projects" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Срок действия маркеров OAuth истекает через один час. Пересоздайте по мере необходимости.

Дополнительные сведения см. в статье "Авторизация доступа пользователей к Databricks с помощью OAuth".

Доступные конечные точки (бета-версия)

Все конечные точки используют базовый путь /api/2.0/postgres/.

Проекты

Операция	Метод	Endpoint	Documentation
Создание проекта	`POST`	`/projects`	Создание проекта
Обновление проекта	`PATCH`	`/projects/{project_id}`	общие параметры
Удаление проекта	`DELETE`	`/projects/{project_id}`	Удаление проекта
Получить проект	`GET`	`/projects/{project_id}`	Получение сведений о проекте
Список проектов	`GET`	`/projects`	Список проектов

Ветви

Операция	Метод	Endpoint	Documentation
Создать ветвь	`POST`	`/projects/{project_id}/branches`	Создание ветви
Обновить ветку	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Обновление параметров ветви
Удаление ветви	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Удаление ветви
Получить ветвь	`GET`	`/projects/{project_id}/branches/{branch_id}`	Просмотр ветвей
Список ветвей	`GET`	`/projects/{project_id}/branches`	Список веток

Конечные точки (вычислительные ресурсы и реплики чтения)

В API вычислительная точка называется конечной точкой. Общие сведения см. в разделе "Вычисления и конечные точки".

Следующая таблица сопоставляет понятия пользовательского интерфейса с эквивалентами API:

Концепция пользовательского интерфейса	Ресурс ИЛИ поле API	Documentation
Основное вычисление	Конечная точка с `endpoint_type: ENDPOINT_TYPE_READ_WRITE`	Управление вычислительными ресурсами
Реплика для чтения	Конечная точка с `endpoint_type: ENDPOINT_TYPE_READ_ONLY`	Управление репликами чтения
Высокая доступность	`group` поле (`EndpointGroupSpec`) в спецификации конечной точки	Управление высокой доступностью
Идентификаторы вычислений (UID, имя ресурса)	`uid` и `name` (полный путь к ресурсу) в объекте Endpoint	Идентификаторы вычислений

Доступные операции

Операция	Метод	Endpoint	Documentation
Создать конечную точку	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Создать читаемую реплику
Обновление конечной точки	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Изменение вычислительных ресурсов / Изменение реплики / чтенияУправление высокой доступностью
Удаление конечной точки	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Удалить реплику чтения
Получение конечной точки	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Просмотр вычислений
Перечисление конечных точек	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Просмотр вычислений

Роли

Операция	Метод	Endpoint	Documentation
Список ролей	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Просмотр ролей Postgres
Создание роли	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	Создание роли OAuth \| Создание роли пароля
Получить роль	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Просмотр ролей Postgres
Update role (Обновление роли)	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Обновление роли
Удаление роли	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Удаление роли

Каталоги

Операция	Метод	Endpoint	Documentation
Регистрация базы данных в каталоге Unity	`POST`	`/catalogs`	Регистрация базы данных
Получение регистрации каталога	`GET`	`/catalogs/{catalog_id}`	Проверка состояния регистрации
Удаление регистрации каталога	`DELETE`	`/catalogs/{catalog_id}`	Отмена регистрации базы данных

Замечание

Регистрация и удаление являются длительными операциями. Опросите операцию до тех пор, пока не завершится done: true. См. долговременные операции.

Удаление регистрации каталога не удаляет базовую базу данных Postgres.

Синхронизированные таблицы

Операция	Метод	Endpoint	Documentation
Создание синхронизированной таблицы	`POST`	`/synced_tables`	Создание синхронизированной таблицы
Получение синхронизированной таблицы	`GET`	`/synced_tables/{table_name}`	Проверка состояния синхронизации
Удаление синхронизированной таблицы	`DELETE`	`/synced_tables/{table_name}`	Удаление синхронизированной таблицы

Замечание

В пути table_name используется формат catalog.schema.table.

Создание и удаление являются длительными операциями. Опросите операцию до тех пор, пока не завершится done: true. См. долговременные операции.

При удалении синхронизированной таблицы удаляется только регистрация каталога Unity. Удалите таблицу Postgres отдельно, чтобы освободить место.

Учетные данные базы данных

Операция	Метод	Endpoint	Documentation
Создание учетных данных базы данных	`POST`	`/credentials`	Аутентификация токена OAuth

Операции

Операция	Метод	Endpoint	Documentation
Операция извлечения	`GET`	`/projects/{project_id}/operations/{operation_id}`	См. пример ниже

Разрешения

Разрешения ACL проекта используют стандартный API разрешений Azure Databricks, а не базовый путь /api/2.0/postgres/. Установите request_object_type на database-projects, а request_object_id на идентификатор вашего проекта (например, my-app).

Операция	Метод	Endpoint	Documentation
Получение разрешений проекта	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	Справочник по API разрешений
Обновление разрешений проекта	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	Справочник по API разрешений
Замена разрешений проекта	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	Справочник по API разрешений

Разрешаемые уровни доступа для проектов Lakebase — CAN_USE и CAN_MANAGE. CAN_CREATE является наследуемым уровнем и не может быть задан через API. См. уровни разрешений.

Примеры использования и эквиваленты CLI/SDK/Terraform см. в разделе "Предоставление разрешений" программным способом.

Получение операции

Проверьте состояние длительной операции по имени ресурса.

пакет SDK Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec

w = WorkspaceClient()

# Start an operation (example: create project)
operation = w.postgres.create_project(
    project=Project(spec=ProjectSpec(pg_version=17)),
    project_id="my-project",
)
print(f"Operation started: {operation.name()}")

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

пакет SDK Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation (example: create project)
CreateProjectOperation operation = w.postgres().createProject(
    new CreateProjectRequest()
        .setProjectId("my-project")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setPgVersion(17L)))
);
System.out.println("Operation started: " + operation.getName());

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

интерфейс командной строки (CLI)

Интерфейс командной строки автоматически ожидает завершения операций по умолчанию. Используйте --no-wait для пропуска опроса:

# Create project without waiting
databricks postgres create-project my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

# Later, check the operation status using the operation name from the response
databricks postgres get-operation projects/my-project/operations/<operation-id>

завиток

# Get operation status
curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Формат ответа:

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/databricks.postgres.v1.Project",
    "name": "projects/my-project",
    ...
  }
}

Поля:

done: false во время выполнения, true при завершении
response: содержит результат, если done имеет значение true
error: содержит сведения об ошибке, если операция завершилась ошибкой

Распространенные шаблоны

Именование ресурсов

Ресурсы следуют шаблону иерархического именования, в котором дочерние ресурсы относятся к родительскому элементу.

Проекты используют следующий формат:

projects/{project_id}

Дочерние ресурсы, такие как операции, расположены под родительским проектом.

projects/{project_id}/operations/{operation_id}

Это означает, что для доступа к операциям или другим дочерним ресурсам требуется идентификатор родительского проекта.

Идентификаторы ресурсов:

При создании ресурсов необходимо указать идентификатор ресурса (например my-app) для параметра project_id, branch_id или endpoint_id параметра. Этот идентификатор становится частью пути к ресурсу в вызовах API (например projects/my-app/branches/development).

При необходимости можно предоставить вашему ресурсу более описательную метку, используя display_name. Если отображаемое имя не указано, система использует идентификатор ресурса в качестве отображаемого имени.

:::tip Поиск ресурсов в пользовательском интерфейсе

Чтобы найти проект в пользовательском интерфейсе Lakebase, найдите отображаемое имя в списке проектов. Если при создании проекта не предоставлено пользовательское отображаемое имя, выполните поиск project_id (например, my-app).

:::

Замечание

Идентификаторы ресурсов невозможно изменить после создания.

Требования:

Должно иметь длину 1–63 символов.
Только строчные буквы, цифры и дефисы
Нельзя начинаться или заканчиваться на дефис.
Примеры: my-app, analytics-dbcustomer-123

Длительные операции (LROs — Long-running operations)

Операции создания, обновления и удаления возвращают databricks.longrunning.Operation объект, предоставляющий состояние завершения.

Пример ответа на операцию:

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": false
}

Опрос завершения операции с использованием метода GetOperation:

пакет SDK Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec

w = WorkspaceClient()

# Start an operation
operation = w.postgres.create_project(
    project=Project(spec=ProjectSpec(pg_version=17)),
    project_id="my-project",
)

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

пакет SDK Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation
CreateProjectOperation operation = w.postgres().createProject(
    new CreateProjectRequest()
        .setProjectId("my-project")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setPgVersion(17L)))
);

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

интерфейс командной строки (CLI)

Интерфейс командной строки автоматически ожидает завершения операций по умолчанию. Используйте --no-wait для немедленного возврата:

databricks postgres create-project my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

завиток

# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq '.done'

Опрос проводите каждые несколько секунд, пока done не станет true.

Обновление маски

Для операций обновления требуется параметр, указывающий update_mask , какие поля необходимо изменить. Это предотвращает случайную перезапись несвязанных полей.

Различия в формате:

Метод	Формат	Example
REST API	Параметр запроса	`?update_mask=spec.display_name`
пакет SDK Python	Объект FieldMask	`update_mask=FieldMask(field_mask=["spec.display_name"])`
интерфейс командной строки (CLI)	Позиционный аргумент	`update-project NAME spec.display_name`

Обработка ошибок

API Lakebase возвращает стандартные коды состояния HTTP.

409: конфликтующие операции

Lakebase может возвращать ошибку 409 Conflict по нескольким причинам:

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

Что это означает:

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

Это ожидаемое поведение. Клиенты должны быть готовы повторить запросы при возникновении этой ошибки.

Что делать:

Повторите запрос. После завершения внутренних операций или освобождения ресурсов, Lakebase принимает новые запросы для проекта.

Используйте экспоненциальную паузу для повторных попыток: подождите короткий интервал перед первой попыткой, затем увеличьте ожидание в два раза для каждой последующей попытки. Начальный интервал в 100 миллисекунд с максимальным значением 30 секунд является разумным по умолчанию.

пакет SDK Python

import time
from databricks.sdk import WorkspaceClient
from databricks.sdk.errors import ResourceConflict
from databricks.sdk.service.postgres import Branch, BranchSpec

w = WorkspaceClient()

def retry_on_conflict(fn, max_attempts=5, base_delay=0.1):
    """Retry a Lakebase API call when a conflicting operation is in progress."""
    for attempt in range(max_attempts):
        try:
            return fn()
        except ResourceConflict:
            if attempt == max_attempts - 1:
                raise
            wait = base_delay * (2 ** attempt)
            print(f"Conflicting operation in progress. Retrying in {wait}s...")
            time.sleep(wait)

# Example: create a branch with retry
branch = retry_on_conflict(
    lambda: w.postgres.create_branch(
        parent="projects/my-project",
        branch=Branch(spec=BranchSpec(no_expiry=True)),
        branch_id="my-branch",
    ).wait()
)

завиток

# Retry with exponential backoff on 409 responses
retry_on_conflict() {
  local cmd=("$@")
  local max_attempts=5
  local delay=0.1
  local attempt=0

  while [ $attempt -lt $max_attempts ]; do
    response=$(curl -s -w "\n%{http_code}" "${cmd[@]}")
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')

    if [ "$http_code" -ne 409 ]; then
      echo "$body"
      return 0
    fi

    attempt=$((attempt + 1))
    if [ $attempt -eq $max_attempts ]; then
      echo "Max retries reached. Last response: $body" >&2
      return 1
    fi

    echo "Conflicting operation in progress. Retrying in ${delay}s..." >&2
    sleep "$delay"
    delay=$((delay * 2))
  done
}

# Example: create a branch with retry
retry_on_conflict \
  -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches?branch_id=my-branch" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"no_expiry": true}}'

Замечание

Запрос 409 Conflict API Lakebase означает, что запрос не был принят, а не применен. Всегда проверяйте состояние ресурса после успешного повтора, вызвав соответствующую конечную GET точку.

Пакеты SDK и инфраструктура как код

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-05-15

Руководство по API автомасштабирования Lakebase

Authentication

Настройка проверки подлинности

пакет SDK Python

пакет SDK Java

интерфейс командной строки (CLI)

завиток

Доступные конечные точки (бета-версия)

Проекты

Ветви

Конечные точки (вычислительные ресурсы и реплики чтения)

Доступные операции

Роли

Каталоги

Синхронизированные таблицы

Учетные данные базы данных

Операции

Разрешения

Получение операции

пакет SDK Python

пакет SDK Java

интерфейс командной строки (CLI)

завиток

Распространенные шаблоны

Именование ресурсов

Длительные операции (LROs — Long-running operations)

пакет SDK Python

пакет SDK Java

интерфейс командной строки (CLI)

завиток

Обновление маски

Обработка ошибок

409: конфликтующие операции

пакет SDK Python

завиток

Пакеты SDK и инфраструктура как код

Обратная связь

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