Průvodce rozhraním API pro automatické škálování LakeBase

Tato stránka obsahuje přehled rozhraní API pro automatické škálování LakeBase, včetně ověřování, dostupných koncových bodů a běžných vzorů pro práci s rozhraním REST API, rozhraním příkazového řádku Databricks a sadami SDK Databricks (Python, Java, Go).

Kompletní referenční informace k rozhraní API najdete v dokumentaci k rozhraní Postgres API.

Důležité

Rozhraní Api Postgres Lakebase je v beta verzi. Koncové body, parametry a chování rozhraní API se můžou změnit.

Autentizace

Rozhraní API pro automatické škálování Lakebase používá ověřování OAuth na úrovni pracovního prostoru ke správě infrastruktury projektu (vytváření projektů, konfigurace nastavení atd.).

Poznámka:

Dva typy připojení: Toto rozhraní API je určené pro správu platforem (vytváření projektů, větví, výpočetních prostředků). Přístup k databázi (připojení k datům dotazů):

Klienti SQL (psql, pgAdmin, DBeaver): Použijte tokeny OAuth Lakebase nebo hesla Postgres. Viz Ověřování.
Rozhraní API pro data (RESTful HTTP): Použijte tokeny Lakebase OAuth. Podívejte se na Data API.
Ovladače programovacího jazyka (psycopg, SQLAlchemy, JDBC): Použijte tokeny Lakebase OAuth nebo hesla Postgres. Viz Rychlý start.

Úplné vysvětlení těchto dvou vrstev ověřování najdete v tématu Architektura ověřování.

Nastavení ověřování

Ověřování pomocí rozhraní příkazového řádku Databricks:

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

Podle pokynů prohlížeče se přihlaste. Rozhraní příkazového řádku ukládá token OAuth do mezipaměti na adrese ~/.databricks/token-cache.json.

Pak zvolte metodu přístupu:

Python SDK

Sada SDK používá jednotné ověřování a automaticky zpracovává tokeny OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

Sada SDK používá jednotné ověřování a automaticky zpracovává tokeny OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

Příkazy automaticky používají token uložený v mezipaměti:

databricks postgres list-projects

kroucení

Vygenerujte token pro přímá volání rozhraní 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}"

Platnost tokenů OAuth vyprší po jedné hodině. Podle potřeby vygenerovat znovu.

Další podrobnosti najdete v tématu Autorizace přístupu uživatelů k Databricks pomocí OAuth.

Dostupné koncové body (beta verze)

Všechny koncové body používají základní cestu /api/2.0/postgres/.

Projekty

Operation	Metoda	Endpoint	Documentation
Vytvoření projektu	`POST`	`/projects`	Vytvoření projektu
Aktualizace projektu	`PATCH`	`/projects/{project_id}`	Obecná nastavení
Odstranit projekt	`DELETE`	`/projects/{project_id}`	Odstranění projektu
Získání projektu	`GET`	`/projects/{project_id}`	Získání podrobností o projektu
Výpis projektů	`GET`	`/projects`	Výpis projektů

Větve

Operation	Metoda	Endpoint	Documentation
Vytvářet větve	`POST`	`/projects/{project_id}/branches`	Vytvoření větve
Aktualizovat větev	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Aktualizace nastavení větve
Odstranit větev	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Odstranění větve
Získání větve	`GET`	`/projects/{project_id}/branches/{branch_id}`	Zobrazení větví
Seznam větví	`GET`	`/projects/{project_id}/branches`	Výpis větví

Koncové body (výpočetní jednotky a repliky pro čtení)

V rozhraní API se výpočetní prostředky označují jako koncový bod. Koncepční přehled najdete v tématu Výpočty a koncové body.

Následující tabulka mapuje koncepty uživatelského rozhraní na jejich ekvivalenty rozhraní API:

Koncept uživatelského rozhraní	Prostředek nebo pole rozhraní API	Documentation
Primární výpočetní jednotka	Koncový bod s `endpoint_type: ENDPOINT_TYPE_READ_WRITE`	Správa výpočetních prostředků
Replika pro čtení	Koncový bod s `endpoint_type: ENDPOINT_TYPE_READ_ONLY`	Správa replik pro čtení
Vysoká dostupnost	`group` pole (`EndpointGroupSpec`) ve specifikaci koncového bodu	Správa vysoké dostupnosti
Identifikátory výpočetních prostředků (UID, název prostředku)	`uid` a `name` (úplná cesta k prostředku) u objektu koncového bodu	Výpočetní identifikátory

Dostupné operace

Operation	Metoda	Endpoint	Documentation
Vytvoření koncového bodu	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Vytvoření repliky pro čtení
Aktualizace koncového bodu	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Úprava výpočetní úlohy / Úprava repliky pro čtení / Správa vysoké dostupnosti
Odstranění koncového bodu	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Odstranit repliku pro čtení
Získání koncového bodu	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Zobrazit výpočty
Výpis koncových bodů	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Zobrazit výpočty

Role

Operation	Metoda	Endpoint	Documentation
Výpis rolí	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Zobrazení rolí Postgres
Vytvoření role	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	Vytvořte roli OAuth \| Vytvořte roli hesla
Získat roli	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Zobrazení rolí Postgres
Aktualizace role	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Aktualizovat roli
Odstranění role	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Odstranění role

Katalogy

Operation	Metoda	Endpoint	Documentation
Registrace databáze v Katalogu Unity	`POST`	`/catalogs`	Zaregistrujte databázi
Získání registrace katalogu	`GET`	`/catalogs/{catalog_id}`	Kontrola stavu registrace
Smazat registraci katalogu	`DELETE`	`/catalogs/{catalog_id}`	Zrušení registrace databáze

Poznámka:

Registrace a odstranění jsou dlouhotrvající operace. Provádějte dotazování na vrácenou operaci, dokud nenastane done: true. Viz dlouhotrvající operace.

Odstraněním registrace katalogu se neodstraní podkladová databáze Postgres.

Synchronizované tabulky

Operation	Metoda	Endpoint	Documentation
Vytvoření synchronizované tabulky	`POST`	`/synced_tables`	Vytvoření synchronizované tabulky
Získání synchronizované tabulky	`GET`	`/synced_tables/{table_name}`	Kontrola stavu synchronizace
Odstranění synchronizované tabulky	`DELETE`	`/synced_tables/{table_name}`	Odstranění synchronizované tabulky

Poznámka:

V table_name cestě se používá formát catalog.schema.table.

Vytváření a odstraňování jsou dlouhotrvající operace. Provádějte dotazování na vrácenou operaci, dokud nenastane done: true. Viz dlouhotrvající operace.

Odstranění synchronizované tabulky odebere jenom registraci katalogu Unity. Pusťte tabulku Postgres samostatně, abyste uvolnili místo.

Přihlašovací údaje databáze

Operation	Metoda	Endpoint	Documentation
Generování přihlašovacích údajů databáze	`POST`	`/credentials`	Ověřování tokenů OAuth

Operace

Operation	Metoda	Endpoint	Documentation
Načtení operace	`GET`	`/projects/{project_id}/operations/{operation_id}`	Podívejte se na příklad níže.

Oprávnění

Oprávnění projektu seznamu ACL používají standard Azure Databricks Permissions API, nikoli základní cestu /api/2.0/postgres/. request_object_type Nastavte na database-projects a request_object_id na ID projektu (napříkladmy-app).

Operation	Metoda	Endpoint	Documentation
Získání oprávnění k projektu	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	Referenční informace k rozhraní API pro oprávnění
Aktualizace oprávnění projektu	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	Referenční informace k rozhraní API pro oprávnění
Nahrazení oprávnění projektu	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	Referenční informace k rozhraní API pro oprávnění

Udělovatelné úrovně oprávnění pro projekty Lakebase jsou CAN_USE a CAN_MANAGE. CAN_CREATE je zděděná úroveň a nelze ji nastavit prostřednictvím rozhraní API. Viz úrovně oprávnění.

Příklady použití a ekvivalenty rozhraní příkazového řádku, sady SDK nebo Terraformu najdete v tématu Udělení oprávnění programově.

Získání operace

Zkontrolujte stav dlouhotrvající operace podle názvu zdroje.

Python SDK

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}")

Java SDK

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

Rozhraní příkazového řádku automaticky čeká na dokončení operací ve výchozím nastavení. Umožňuje --no-wait přeskočit dotazování:

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

kroucení

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

Formát odpovědi:

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

Pole:

done: false probíhá, true až bude dokončeno
response: Obsahuje výsledek, pokud done je true
error: Obsahuje podrobnosti o chybě, pokud operace selhala.

Obvyklé scénáře

Pojmenování zdrojů

Prostředky se řídí hierarchickým pojmenováním, ve kterém jsou podřízené prostředky podřízeny nadřazenému objektu.

Projekty používají tento formát:

projects/{project_id}

Podřízené prostředky, jako jsou operace, jsou vnořené do nadřazeného projektu:

projects/{project_id}/operations/{operation_id}

To znamená, že pro získání přístupu k operacím nebo jiným podřízeným prostředkům potřebujete ID nadřazeného projektu.

ID prostředků:

Při vytváření prostředků musíte zadat ID prostředku (například my-app) pro project_idparametr , branch_idnebo endpoint_id parametr. Tento identifikátor se stane součástí cesty prostředku při volání rozhraní API (například projects/my-app/branches/development).

Volitelně můžete poskytnout display_name, abyste svému prostředku dali popisnější označení. Pokud nezadáte zobrazovaný název, systém použije jako zobrazovaný název ID vašeho prostředku.

:::tip Vyhledání zdrojů v uživatelském rozhraní

Pokud chcete vyhledat projekt v uživatelském rozhraní Lakebase, vyhledejte jeho zobrazovaný název v seznamu projektů. Pokud jste při vytváření projektu nezadali vlastní zobrazovaný název, vyhledejte název projektu s označením project_id (například "my-app").

:::

Poznámka:

ID prostředků nelze po vytvoření změnit.

Požadavky:

Musí mít délku 1 až 63 znaků.
Pouze malá písmena, číslice a pomlčky
Nejde začínat ani končit spojovníkem
Příklady: my-app, analytics-db, customer-123

Dlouhotrvající operace (LRO)

Operace vytvoření, aktualizace a odstranění vrací databricks.longrunning.Operation objekt, který poskytuje stav dokončení.

Příklad odpovědi operace:

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

Dotazování na dokončení pomocí GetOperation:

Python SDK

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}")

Java SDK

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

Rozhraní příkazového řádku automaticky čeká na dokončení operací ve výchozím nastavení. Použijte --no-wait pro okamžité vrácení:

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

kroucení

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

Dotazování každých několik sekund, dokud done nebude true.

Aktualizace masek

Operace aktualizace vyžadují update_mask parametr určující pole, která se mají upravit. Tím zabráníte náhodnému přepsání nesouvisejících polí.

Rozdíly ve formátu:

Metoda	Formát	Example
REST API	Parametr dotazu	`?update_mask=spec.display_name`
Python SDK	FieldMask – objekt	`update_mask=FieldMask(field_mask=["spec.display_name"])`
CLI	Poziční argument	`update-project NAME spec.display_name`

Zpracování chyb

Rozhraní API Lakebase vrátí standardní stavové kódy HTTP.

409: Konfliktní operace

Lakebase může vrátit 409 Conflict chybu z několika důvodů:

V projektu probíhá interní operace údržby.
Projekt dosáhl svého limitu souběžných operací.
Vaše vlastní požadavky rozhraní API se překrývají. Například situace, kdy je větev vytvořena před dokončením předchozího vytvoření větve.

Význam:

Lakebase někdy plánuje operace údržby u projektů. Pokud požadavek klienta dorazí, zatímco jedna z těchto operací probíhá, Lakebase odmítne nový požadavek s chybou 409 Conflict . Můžete také obdržet tuto odpověď, když projekt dosáhl své kapacity nebo se volání rozhraní API překrývají.

Toto chování je očekávané. Klienti by měli být připraveni opakovat žádosti, když dojde k této chybě.

Co dělat:

Zkuste požadavek zopakovat. Po dokončení interní operace nebo uvolnění kapacity přijímá Lakebase nové žádosti o projekt.

Použijte exponenciální zpoždění pro opakované pokusy: počkejte krátký interval před prvním opakovaným pokusem a potom zdvojnásobte čekací dobu na každý další pokus. Výchozí interval 100 milisekund s maximem 30 sekund je rozumný.

Python SDK

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

kroucení

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

Poznámka:

Požadavek 409 Conflict na rozhraní API Lakebase znamená, že požadavek nebyl přijat, a ne to, že byl použit. Stav prostředku vždy ověřte po úspěšném opakování voláním odpovídajícího GET koncového bodu.

Sady softwarových vývojových sad (SDK) a infrastruktura-jako-kód

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-15

Průvodce rozhraním API pro automatické škálování LakeBase

Autentizace

Nastavení ověřování

Python SDK

Java SDK

CLI

kroucení

Dostupné koncové body (beta verze)

Projekty

Větve

Koncové body (výpočetní jednotky a repliky pro čtení)

Dostupné operace

Role

Katalogy

Synchronizované tabulky

Přihlašovací údaje databáze

Operace

Oprávnění

Získání operace

Python SDK

Java SDK

CLI

kroucení

Obvyklé scénáře

Pojmenování zdrojů

Dlouhotrvající operace (LRO)

Python SDK

Java SDK

CLI

kroucení

Aktualizace masek

Zpracování chyb

409: Konfliktní operace

Python SDK

kroucení

Sady softwarových vývojových sad (SDK) a infrastruktura-jako-kód

Váš názor

Další materiály