Przewodnik po interfejsie API skalowania automatycznego w usłudze Lakebase

Ważne

Autoskalowanie bazy danych Lakebase to najnowsza wersja bazy danych Lakebase, która umożliwia skalowanie automatyczne, skalowanie do zera, rozgałęzianie i natychmiastowe przywracanie. Aby uzyskać informacje o obsługiwanych regionach, zobacz Dostępność regionów. Jeśli jesteś użytkownikiem usługi Lakebase Provisioned, zobacz Lakebase Provisioned.

Ta strona zawiera omówienie interfejsu API automatycznego skalowania usługi Lakebase, w tym uwierzytelniania, dostępnych punktów końcowych i typowych wzorców pracy z interfejsem API REST, interfejsem wiersza polecenia usługi Databricks i zestawami SDK usługi Databricks (Python, Java, Go).

Aby uzyskać pełną dokumentację interfejsu API, zobacz dokumentację interfejsu API bazy danych Postgres.

Ważne

Interfejs API Postgres w Lakebase jest w wersji beta. Punkty końcowe interfejsu API, parametry i zachowania mogą ulec zmianie.

Authentication

Interfejs API automatycznego skalowania usługi Lakebase używa uwierzytelniania OAuth na poziomie obszaru roboczego do zarządzania infrastrukturą projektu (tworzenie projektów, konfigurowanie ustawień itp.).

Uwaga / Notatka

Dwa typy łączności: ten interfejs API służy do zarządzania platformą (tworzenie projektów, gałęzi, obliczeń). Aby uzyskać dostęp do bazy danych (nawiązywanie połączenia z danymi):

Klienci SQL (psql, pgAdmin, DBeaver): użyj tokenów OAuth bazy danych Lakebase lub haseł Postgres. Zobacz Uwierzytelnianie.
Interfejs API danych (RESTful HTTP): użyj tokenów OAuth bazy danych Lakebase. Zobacz Interfejs API danych.
Sterowniki języka programowania (psycopg, SQLAlchemy, JDBC): użyj tokenów OAuth bazy danych Lakebase lub haseł Postgres. Zobacz Szybki start.

Aby uzyskać pełne wyjaśnienie tych dwóch warstw uwierzytelniania, zobacz Architektura uwierzytelniania.

Konfigurowanie uwierzytelniania

Uwierzytelnianie przy użyciu interfejsu wiersza polecenia usługi Databricks:

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

Postępuj zgodnie z monitami przeglądarki, aby się zalogować. Interfejs wiersza polecenia buforuje token OAuth pod adresem ~/.databricks/token-cache.json.

Następnie wybierz metodę dostępu:

zestaw SDK Python

Zestaw SDK używa ujednoliconego uwierzytelniania i automatycznie obsługuje tokeny OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

zestaw SDK Java

Zestaw SDK używa ujednoliconego uwierzytelniania i automatycznie obsługuje tokeny OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

Polecenia automatycznie używają buforowanego tokenu:

databricks postgres list-projects

skręt

Wygeneruj token dla bezpośrednich wywołań interfejsu 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}"

Tokeny OAuth wygasają po godzinie. W razie potrzeby wygeneruj ponownie.

Aby uzyskać więcej informacji, zobacz Autoryzowanie dostępu użytkowników do usługi Databricks przy użyciu protokołu OAuth.

Dostępne punkty końcowe (wersja beta)

Wszystkie punkty końcowe używają ścieżki /api/2.0/postgres/podstawowej .

Projekty

Operation	Metoda	Endpoint	Dokumentacja
Tworzenie projektu	`POST`	`/projects`	Utwórz projekt
Aktualizowanie projektu	`PATCH`	`/projects/{project_id}`	Ustawienia ogólne
Usuwanie projektu	`DELETE`	`/projects/{project_id}`	Usuwanie projektu
Pobierz projekt	`GET`	`/projects/{project_id}`	Uzyskaj szczegóły projektu
Lista projektów	`GET`	`/projects`	Wyświetlanie listy projektów

Gałęzie

Operation	Metoda	Endpoint	Dokumentacja
Utworzyć odgałęzienie	`POST`	`/projects/{project_id}/branches`	Tworzenie gałęzi
Aktualizuj gałąź	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Aktualizowanie ustawień gałęzi
Usuń gałąź	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Usuwanie gałęzi
Pobieranie gałęzi	`GET`	`/projects/{project_id}/branches/{branch_id}`	Wyświetlanie gałęzi
Wyświetl gałęzie	`GET`	`/projects/{project_id}/branches`	Lista gałęzi

Punkty końcowe (obliczenia i repliki do odczytu)

W interfejsie API obliczenia są nazywane punktem końcowym. Aby zapoznać się z omówieniem pojęć, zobacz Obliczenia i punkty końcowe.

W poniższej tabeli przedstawiono mapowanie pojęć interfejsu użytkownika na ich odpowiedniki w API:

Koncepcja interfejsu użytkownika	Zasób lub pole interfejsu API	Dokumentacja
Podstawowe obliczenia	Punkt końcowy z `endpoint_type: ENDPOINT_TYPE_READ_WRITE`	Zarządzanie obliczeniami
Replika do odczytu	Punkt końcowy z `endpoint_type: ENDPOINT_TYPE_READ_ONLY`	Zarządzanie replikami do odczytu
Wysoka dostępność	`group` pole (`EndpointGroupSpec`) w specyfikacji punktu końcowego	Zarządzanie wysoką dostępnością
Identyfikatory obliczeniowe (UID, Nazwa zasobu)	`uid` i `name` (pełna ścieżka zasobu) w obiekcie Endpoint	Identyfikatory obliczeniowe

Dostępne operacje

Operation	Metoda	Endpoint	Dokumentacja
Tworzenie punktu końcowego	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Utwórz replikę do odczytu
Aktualizowanie punktu końcowego	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Edytuj jednostkę obliczeniową / Edytowanie repliki do odczytu / Zarządzanie wysoką dostępnością
Usuń punkt końcowy	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Usuń replikę do odczytu
Pobierz punkt końcowy	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Wyświetlanie obliczeń
Wymień punkty końcowe	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Wyświetlanie obliczeń

Ról

Operation	Metoda	Endpoint	Dokumentacja
Wyświetlanie listy ról	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Wyświetlanie ról bazy danych Postgres
Tworzenie roli	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	Tworzenie roli OAuth \| Tworzenie roli hasła
Pobierz rolę	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Wyświetlanie ról bazy danych Postgres
Aktualizowanie roli	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Aktualizowanie roli
Usuwanie roli	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Usuwanie roli

Katalogi

Operation	Metoda	Endpoint	Dokumentacja
Zarejestruj bazę danych w katalogu Unity	`POST`	`/catalogs`	Rejestrowanie bazy danych
Pobierz rejestrację katalogu	`GET`	`/catalogs/{catalog_id}`	Sprawdzanie stanu rejestracji
Usuń rejestrację katalogu	`DELETE`	`/catalogs/{catalog_id}`	Wyrejestrowywanie bazy danych

Uwaga / Notatka

Rejestrowanie i usuwanie to długotrwałe operacje. Monitoruj zwróconą operację do chwili done: true. Zobacz Długotrwałe operacje.

Usunięcie rejestracji katalogu nie powoduje usunięcia bazowej bazy danych Postgres.

Zsynchronizowane tabele

Operation	Metoda	Endpoint	Dokumentacja
Tworzenie zsynchronizowanej tabeli	`POST`	`/synced_tables`	Tworzenie zsynchronizowanej tabeli
Pobieranie zsynchronizowanej tabeli	`GET`	`/synced_tables/{table_name}`	Sprawdzanie stanu synchronizacji
Usuwanie zsynchronizowanej tabeli	`DELETE`	`/synced_tables/{table_name}`	Usuwanie zsynchronizowanej tabeli

Uwaga / Notatka

Element table_name w ścieżce używa formatu catalog.schema.table.

Operacje tworzenia i usuwania są długotrwałe. Monitoruj zwróconą operację do chwili done: true. Zobacz Długotrwałe operacje.

Usunięcie zsynchronizowanej tabeli powoduje usunięcie rejestracji w katalogu Unity Catalog. Usuń tabelę Postgres oddzielnie, aby zwolnić miejsce.

Poświadczenia bazy danych

Operation	Metoda	Endpoint	Dokumentacja
Generowanie poświadczeń bazy danych	`POST`	`/credentials`	Uwierzytelnianie tokenu OAuth

Operacji

Operation	Metoda	Endpoint	Dokumentacja
Operacja pobierania	`GET`	`/projects/{project_id}/operations/{operation_id}`	Zobacz przykład poniżej

Uprawnienia

Uprawnienia listy ACL projektu używają standardowego interfejsu API uprawnień Azure Databricks, a nie ścieżki podstawowej /api/2.0/postgres/. Ustaw request_object_type na database-projects i request_object_id na identyfikator projektu (na przykład my-app).

Operation	Metoda	Endpoint	Dokumentacja
Uzyskiwanie uprawnień projektu	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	Dokumentacja interfejsu API uprawnień
Aktualizowanie uprawnień projektu	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	Dokumentacja interfejsu API uprawnień
Zastąp uprawnienia projektu	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	Dokumentacja interfejsu API uprawnień

Poziomy uprawnień możliwych do udzielenia dla projektów Lakebase to CAN_USE i CAN_MANAGE. CAN_CREATE jest dziedziczony poziom i nie można go ustawić za pośrednictwem interfejsu API. Zobacz Poziomy uprawnień.

Przykłady użycia i odpowiedniki interfejsu wiersza polecenia/zestawu SDK/narzędzia Terraform można znaleźć w temacie Programowe udzielanie uprawnień.

Pobieranie operacji

Sprawdź stan długotrwałej operacji według nazwy zasobu.

zestaw SDK Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Start an operation (example: create project)
operation = w.postgres.create_project(...)
print(f"Operation started: {operation.name}")

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

zestaw 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(...);
System.out.println("Operation started: " + operation.getName());

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

CLI

Interfejs wiersza polecenia automatycznie czeka na ukończenie operacji domyślnie. Użyj polecenia --no-wait , aby pominąć sondowanie:

# Create project without waiting
databricks postgres create-project --no-wait ...

# Later, check the operation status
databricks postgres get-operation projects/my-project/operations/abc123

skręt

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

Format odpowiedzi:

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

Pola:

done: false w toku, true po zakończeniu
response: zawiera wynik, gdy done jest true
error: zawiera szczegóły błędu, jeśli operacja nie powiodła się

Często używane wzorce

Nazewnictwo zasobów

Zasoby są zgodne ze wzorcem nazewnictwa hierarchicznego, w którym zasoby podrzędne są ograniczone do ich elementu nadrzędnego.

Projekty używają tego formatu:

projects/{project_id}

Zasoby podrzędne, takie jak operacje, są zagnieżdżone w ramach projektu nadrzędnego.

projects/{project_id}/operations/{operation_id}

Oznacza to, że potrzebujesz identyfikatora projektu nadrzędnego, aby uzyskać dostęp do operacji lub innych zasobów podrzędnych.

Identyfikatory zasobów:

Podczas tworzenia zasobów należy podać identyfikator zasobu (na przykład my-app) dla parametru project_id, branch_idlub endpoint_id . Ten identyfikator staje się częścią ścieżki zasobu w wywołaniach interfejsu API (takich jak projects/my-app/branches/development).

Opcjonalnie możesz podać element , display_name aby nadać zasobowi bardziej opisową etykietę. Jeśli nie określisz nazwy wyświetlanej, system używa identyfikatora zasobu jako nazwy wyświetlanej.

:::tip Znajdowanie zasobów w interfejsie użytkownika

Aby zlokalizować projekt w interfejsie użytkownika usługi Lakebase, wyszukaj jego nazwę wyświetlaną na liście projektów. Jeśli podczas tworzenia projektu nie ustanowisz własnej nazwy wyświetlanej, wyszukaj nazwę project_id (np. "my-app").

:::

Uwaga / Notatka

Nie można zmienić identyfikatorów zasobów po utworzeniu.

Wymagania:

Musi mieć długość od 1 do 63 znaków
Małe litery, cyfry i łączniki tylko
Nie można zaczynać ani kończyć myślnikiem
Przykłady: my-app, , analytics-dbcustomer-123

Długotrwałe operacje (LROs)

Operacje tworzenia, aktualizowania i usuwania zwracają databricks.longrunning.Operation obiekt, który zapewnia stan ukończenia.

Przykładowa odpowiedź operacji:

{
  "name": "projects/my-project/operations/abc123",
  "done": false
}

Sonduj pod kątem ukończenia przy użyciu polecenia GetOperation:

zestaw SDK Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Start an operation
operation = w.postgres.create_project(...)

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

zestaw 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(...);

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

CLI

Interfejs wiersza polecenia automatycznie czeka na ukończenie operacji domyślnie. Użyj polecenia --no-wait , aby natychmiast zwrócić:

databricks postgres create-project --no-wait ...

skręt

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

Sonduj co kilka sekund, aż done stanie się true.

Aktualizuj maski

Operacje aktualizacji wymagają parametru update_mask określającego pola do zmodyfikowania. Zapobiega to przypadkowemu zastępowaniu niepowiązanych pól.

Różnice w formatach:

Metoda	Format	Example
interfejs API REST	Parametr zapytania	`?update_mask=spec.display_name`
zestaw SDK Python	Obiekt FieldMask	`update_mask=FieldMask(field_mask=["spec.display_name"])`
CLI	Argument pozycyjny	`update-project NAME spec.display_name`

Obsługa błędów

Interfejs API usługi Lakebase zwraca standardowe kody stanu HTTP.

409: Operacje powodujące konflikt

Usługa Lakebase może z kilku powodów zwrócić błąd 409 Conflict.

Operacja konserwacji wewnętrznej jest w toku w projekcie.
Projekt osiągnął limit operacji współbieżnych.
Twoje własne żądania interfejsu API nakładają się na siebie. Na przykład utworzenie gałęzi przed zakończeniem tworzenia poprzedniej gałęzi.

Co to znaczy:

Lakebase czasami planuje operacje konserwacyjne w projektach. Jeśli żądanie klienta zostanie odebrane, gdy jedna z tych operacji jest w toku, usługa Lakebase odrzuca nowe żądanie z błędem 409 Conflict . Możesz również uzyskać taką odpowiedź, gdy projekt osiągnął swoją pojemność lub wywołania interfejsu API zachodzą na siebie.

Jest to oczekiwane zachowanie. Klienci powinni być przygotowani do ponawiania żądań po wystąpieniu tego błędu.

Co zrobić:

Spróbuj ponownie wysłać żądanie. Po zakończeniu operacji wewnętrznej lub zwolnieniu się zasobów, Lakebase akceptuje nowe żądania dla projektu.

Użyj wycofywania wykładniczego dla ponownych prób: poczekaj krótki interwał przed pierwszą ponowną próbą, a następnie dwukrotnie zaczekaj na każdą kolejną próbę. Interwał początkowy wynoszący 100 milisekund z maksymalnie 30 sekundami jest rozsądnym ustawieniem domyślnym.

zestaw 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()
)

skręt

# 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}}'

Uwaga / Notatka

Element 409 Conflict w żądaniu interfejsu API usługi Lakebase oznacza, że żądanie nie zostało zaakceptowane, a nie zastosowane. Zawsze sprawdź stan zasobu po pomyślnym ponowieniu próby, wywołując odpowiedni GET punkt końcowy.

Zestawy SDK i infrastruktura jako kod

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-19

Udostępnij za pośrednictwem

Przewodnik po interfejsie API skalowania automatycznego w usłudze Lakebase

Authentication

Konfigurowanie uwierzytelniania

zestaw SDK Python

zestaw SDK Java

CLI

skręt

Dostępne punkty końcowe (wersja beta)

Projekty

Gałęzie

Punkty końcowe (obliczenia i repliki do odczytu)

Dostępne operacje

Ról

Katalogi

Zsynchronizowane tabele

Poświadczenia bazy danych

Operacji

Uprawnienia

Pobieranie operacji

zestaw SDK Python

zestaw SDK Java

CLI

skręt

Często używane wzorce

Nazewnictwo zasobów

Długotrwałe operacje (LROs)

zestaw SDK Python

zestaw SDK Java

CLI

skręt

Aktualizuj maski

Obsługa błędów

409: Operacje powodujące konflikt

zestaw SDK Python

skręt

Zestawy SDK i infrastruktura jako kod

Opinia

Dodatkowe zasoby