Guida API Lakebase

Questa pagina fornisce una panoramica dell'API Lakebase, inclusa autenticazione, endpoint disponibili e modelli comuni per lavorare con l'API REST, la CLI Databricks e gli SDK Databricks (Python, Java, Go).

Per l'elenco completo delle operazioni e dei loro parametri, consulta il riferimento all'API Postgres.

Annotazioni

Alcune operazioni rimangono in Beta. Il riferimento API di Postgres segna lo stato di ogni operazione.

Authentication

L'API Lakebase utilizza l'autenticazione OAuth a livello di workspace per gestire l'infrastruttura dei progetti (creazione di progetti, configurazione delle impostazioni, ecc.).

Annotazioni

Due tipi di connettività: questa API è destinata alla gestione della piattaforma (creazione di progetti, rami, risorse di calcolo). Per l'accesso al database (connessione all'interrogazione dei dati):

  • Client SQL (psql, pgAdmin, DBeaver): Usare token Lakebase OAuth o password Postgres. Vedere Autenticazione.
  • API dati (RESTful HTTP): Usa i token Lakebase OAuth. Vedere API dati.
  • Driver del linguaggio di programmazione (psycopg, SQLAlchemy, JDBC): Usare token Lakebase OAuth o password Postgres. Vedere Avvio rapido.

Per una spiegazione completa di questi due livelli di autenticazione, vedere Architettura di autenticazione.

Configura l'autenticazione

Eseguire l'autenticazione tramite l'interfaccia della riga di comando di Databricks:

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

Seguire le istruzioni del browser per accedere. L'interfaccia della riga di comando memorizza nella cache il token OAuth in ~/.databricks/token-cache.json.

Scegliere quindi il metodo di accesso:

PYTHON SDK

L'SDK usa l'autenticazione unificata e gestisce automaticamente i token OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

JAVA SDK

L'SDK usa l'autenticazione unificata e gestisce automaticamente i token OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

I comandi usano automaticamente il token memorizzato nella cache:

databricks postgres list-projects

curva

Genera un token e imposta l'URL del tuo workspace per le chiamate API dirette. Gli esempi di curl in tutta la documentazione di Lakebase assumono queste due variabili ambientali:

export WORKSPACE="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

curl -X GET "$WORKSPACE/api/2.0/postgres/projects" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

I token OAuth scadono dopo un'ora. Rigenerare in base alle esigenze.

Per altri dettagli, vedere Autorizzare l'accesso utente a Databricks con OAuth.

Endpoint disponibili

Tutti gli endpoint usano il percorso /api/2.0/postgres/di base .

Progetti

Operation Metodo Punto finale Documentation
Creare un progetto POST /projects Crea un progetto
Aggiornare il progetto PATCH /projects/{project_id} Impostazioni generali
Eliminare un progetto DELETE /projects/{project_id} Elimina un progetto
Ottenere il progetto GET /projects/{project_id} Ottieni i dettagli del progetto
Elencare i progetti GET /projects Elenco dei progetti

Rami

Operation Metodo Punto finale Documentation
Crea ramo POST /projects/{project_id}/branches Crea un branch
Aggiorna il ramo PATCH /projects/{project_id}/branches/{branch_id} Aggiorna le impostazioni del branch
Elimina ramo DELETE /projects/{project_id}/branches/{branch_id} Elimina un branch
Ottenere un ramo GET /projects/{project_id}/branches/{branch_id} Visualizza i branch
Elenco di rami GET /projects/{project_id}/branches Elenca i rami

Istantanee

Operation Metodo Punto finale Documentation
Crea istantanea POST /projects/{project_id}/snapshots Crea un'istantanea
Elimina snapshot DELETE /projects/{project_id}/snapshots/{snapshot_id} Elimina un snapshot
Ottieni snapshot GET /projects/{project_id}/snapshots/{snapshot_id} Recupera ed elenca snapshot
Elencare gli snapshot GET /projects/{project_id}/snapshots Recuperare ed elencare snapshot
Ripristina lo snapshot (crea un branch dallo snapshot) POST /projects/{project_id}/branches Ripristino da una snapshot

Endpoint (Calcoli e repliche di lettura)

Nell'API, un ambiente di calcolo è denominato endpoint. Per una panoramica concettuale, vedere Calcolo ed endpoint.

La tabella seguente esegue il mapping dei concetti dell'interfaccia utente agli equivalenti api:

Concetto di interfaccia utente Risorsa o campo API Documentation
Calcolo primario Endpoint con endpoint_type: ENDPOINT_TYPE_READ_WRITE Gestire le risorse di calcolo
Replica in lettura Endpoint con endpoint_type: ENDPOINT_TYPE_READ_ONLY Gestire le repliche di lettura
Disponibilità elevata group campo (EndpointGroupSpec) sulla specifica endpoint Gestione dell'alta disponibilità
Identificatori di calcolo (UID, Nome risorsa) uid e name (percorso completo della risorsa) sull'oggetto Endpoint Identificatori di computazione

Operazioni disponibili

Operation Metodo Punto finale Documentation
Creare un endpoint POST /projects/{project_id}/branches/{branch_id}/endpoints Crea una replica di lettura
Aggiornare l'endpoint PATCH /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} Modifica un compute / Modifica una replica di lettura / Gestisci l'alta disponibilità
Eliminare un endpoint DELETE /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} Elimina una replica di lettura
Ottenere l'endpoint GET /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} Visualizza compute
Elencare gli endpoint GET /projects/{project_id}/branches/{branch_id}/endpoints Visualizza i compute

Gli endpoint di lettura-scrittura non possono essere cancellati direttamente. Elimina il ramo principale per rimuoverli. Per evitare costi di calcolo mantenendo il branch, imposta spec.disabled a true. Vedi Disabilita o abilita un calcolo.

Ruoli

Operation Metodo Punto finale Documentation
Elencare i ruoli GET /projects/{project_id}/branches/{branch_id}/roles Visualizza i ruoli di Postgres
Creare un ruolo POST /projects/{project_id}/branches/{branch_id}/roles | Crea un ruolo con password
Ottieni ruolo GET /projects/{project_id}/branches/{branch_id}/roles/{role_id} Visualizza i ruoli di Postgres
Aggiornare un ruolo PATCH /projects/{project_id}/branches/{branch_id}/roles/{role_id} Aggiorna un ruolo
Elimina ruolo DELETE /projects/{project_id}/branches/{branch_id}/roles/{role_id} Elimina un ruolo

Pianificazione backup

Un ramo radice ha un unico programma di backup. Solo get e update sono disponibili. Update sostituisce l'intero set di cadenze del programma.

Operation Metodo Punto finale Documentation
Procurati un programma di riserva GET /projects/{project_id}/branches/{branch_id}/snapshot-schedule Crea una pianificazione del backup
Aggiorna il programma di backup PATCH /projects/{project_id}/branches/{branch_id}/snapshot-schedule Crea una pianificazione del backup

Annotazioni

L'aggiornamento è un'operazione di lunga durata. Sondare l'operazione restituita fino a done: true. Vedere Operazioni a esecuzione prolungata.

Cataloghi

Operation Metodo Punto finale Documentation
Registrare il database con il catalogo Unity POST /catalogs Registra un database
Ottenere la registrazione del catalogo GET /catalogs/{catalog_id} Verifica lo stato della registrazione
Eliminare la registrazione del catalogo DELETE /catalogs/{catalog_id} Annulla la registrazione di un database

Annotazioni

La registrazione e l'eliminazione sono operazioni a esecuzione prolungata. Sondare l'operazione restituita fino a done: true. Vedere Operazioni a esecuzione prolungata.

L'eliminazione di una registrazione del catalogo non comporta l'eliminazione del database Postgres sottostante.

Tabelle sincronizzate

Operation Metodo Punto finale Documentation
Creare una tabella sincronizzata POST /synced_tables Crea una tabella sincronizzata
Ottenere una tabella sincronizzata GET /synced_tables/{table_name} Controlla lo stato della sincronizzazione
Eliminare una tabella sincronizzata DELETE /synced_tables/{table_name} Elimina una tabella sincronizzata

Annotazioni

Nel table_name percorso viene utilizzato il formato catalog.schema.table.

La creazione e l'eliminazione sono operazioni a esecuzione prolungata. Sondare l'operazione restituita fino a done: true. Vedere Operazioni a esecuzione prolungata.

L'eliminazione di una tabella sincronizzata rimuove solo la registrazione del catalogo Unity. Eliminare separatamente la tabella Postgres per liberare spazio.

Change Data Feed

Le operazioni di Lakebase Change Data Feed (CDF) si applicano a un ramo. Per dettagli su richieste e risposte, consulta le operazioni CDF nel riferimento API Postgres.

Operation Metodo Documentation
Crea configurazione CDF POST Avvia il flusso dei dati di modifica
Recupera lo stato CDF GET Avvia il flusso dei dati di modifica
Elenca gli stati della CDF GET Avvia il flusso dei dati di modifica
Ottieni la configurazione CDF GET Avvia il flusso dei dati di modifica
Elimina configurazione CDF DELETE Disabilita il CDF di Lakebase

Annotazioni

Crea una configurazione CDF per avviare un feed di dati di modifica. Puoi anche avviare un feed dall'interfaccia di Lakebase. Vedi Avvia il feed dei dati di modifica.

Eliminare una configurazione CDF rimuove permanentemente la configurazione e le sue mappature di tabelle; le tabelle Delta di destinazione nel Catalogo Unity sono conservate.

Credenziali del database

Operation Metodo Punto finale Documentation
Generare credenziali del database POST /credentials Autenticazione tramite token OAuth

Operazioni

Operation Metodo Punto finale Documentation
Operazione Get GET /projects/{project_id}/operations/{operation_id} Vedi esempio qui sotto

Permessi

Le autorizzazioni ACL del progetto usano l'API di standard Azure Databricks Permissions, non il percorso di base /api/2.0/postgres/. Imposta il request_object_type su database-projects e il request_object_id sul tuo ID del progetto (ad esempio, my-app).

Operation Metodo Punto finale Documentation
Ottenere le autorizzazioni per il progetto GET /api/2.0/permissions/database-projects/{project_id} Riferimento dell'API Permissions
Aggiornare le autorizzazioni del progetto PATCH /api/2.0/permissions/database-projects/{project_id} Riferimento dell'API Permissions
Sostituire le autorizzazioni del progetto PUT /api/2.0/permissions/database-projects/{project_id} Riferimento API per i permessi

I livelli di autorizzazione concedibili per i progetti Lakebase sono CAN_USE e CAN_MANAGE. CAN_CREATE è un livello ereditato e non può essere impostato tramite l'API. Vedere Livelli di autorizzazione.

Per esempi di utilizzo e equivalenti dell'interfaccia della riga di comando/SDK/Terraform, vedere Concedere autorizzazioni a livello di codice.

Ottieni l'operazione

Controllare lo stato di un'operazione a esecuzione prolungata in base al nome della risorsa.

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

Il CLI attende automaticamente il completamento delle operazioni per impostazione predefinita. Usare --no-wait per ignorare il polling:

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

curva

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

Formato della risposta:

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

Campi:

  • done: false mentre è in corso, true quando completato
  • response: Contiene il risultato quando done è true
  • error: Contiene dettagli di errore in caso di fallimento dell'operazione

Modelli comuni

Denominazione delle risorse

Le risorse seguono un modello di denominazione gerarchico in cui le risorse figlio sono definite nell'ambito del loro elemento padre.

I progetti usano questo formato:

projects/{project_id}

Le risorse subordinate, come le operazioni, vengono annidate all'interno del progetto padre.

projects/{project_id}/operations/{operation_id}

Ciò significa che è necessario l'ID progetto padre per accedere alle operazioni o ad altre risorse figlio.

ID risorse:

Quando si creano risorse, è necessario specificare un ID risorsa (ad esempio my-app) per il project_idparametro , branch_ido endpoint_id . Questo ID diventa parte del percorso della risorsa nelle chiamate API ,ad esempio projects/my-app/branches/development.

role_id e database_id identificano le risorse API. spec.postgres_role e spec.postgres_database nominano gli oggetti Postgres corrispondenti.

Facoltativamente, è possibile specificare un oggetto display_name per assegnare alla risorsa un'etichetta più descrittiva. Se non si specifica un nome di visualizzazione, il sistema usa l'ID della risorsa come nome di visualizzazione.

Tip

Per localizzare un progetto nell'app Lakebase, cerca il suo nome visualizzato nella lista dei progetti. Se non hai specificato un nome visualizzato personalizzato durante la creazione del progetto, cerca il project_id tuo (ad esempio "my-app").

Annotazioni

Non è possibile modificare gli ID risorsa dopo la creazione.

Requisiti:

  • Deve avere una lunghezza di 1-63 caratteri
  • Solo lettere minuscole, cifre e trattini
  • Impossibile iniziare o terminare con un trattino
  • Esempi: my-app, analytics-db, customer-123

Operazioni di lunga durata (LRO)

Le operazioni di creazione, aggiornamento ed eliminazione restituiscono un databricks.longrunning.Operation oggetto che fornisce uno stato di completamento.

Esempio di risposta all'operazione:

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

Verifica il completamento usando 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

Il CLI attende automaticamente il completamento delle operazioni per impostazione predefinita. Usare --no-wait per restituire immediatamente:

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

curva

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

Eseguire il polling ogni alcuni secondi fino a quando done è true.

Aggiorna le maschere

Le operazioni di aggiornamento richiedono un update_mask parametro che specifica i campi da modificare. In questo modo si evita la sovrascrittura accidentale di campi non correlati.

Differenze di formato:

Metodo Formato Example
REST API Query parameter (Parametro di query) ?update_mask=spec.display_name
PYTHON SDK Oggetto FieldMask update_mask=FieldMask(field_mask=["spec.display_name"])
CLI Argomento posizionale update-project NAME spec.display_name

Gestione degli errori

L'API Lakebase restituisce codici di stato HTTP standard.

409: Operazioni in conflitto

Lakebase può restituire un 409 Conflict errore per diversi motivi:

  • È in corso un'operazione di manutenzione interna sul progetto.
  • Il progetto ha raggiunto il limite di operazioni simultanee.
  • Le richieste API personalizzate si sovrappongono. Ad esempio, la creazione di un ramo prima del completamento della creazione di un ramo precedente.

Cosa significa:

Lakebase talvolta pianifica le operazioni di manutenzione sui progetti. Se una richiesta client arriva mentre una di queste operazioni è in corso, Lakebase rifiuta la nuova richiesta con un 409 Conflict errore. È anche possibile ottenere tale risposta quando il progetto è in fase di capacità o le chiamate API si sovrappongono.

Si tratta di un comportamento previsto. I client devono essere pronti a ripetere le richieste quando si verifica questo errore.

Cosa fare:

Ripetere la richiesta. Quando l'operazione interna viene completata o la capacità libera, Lakebase accetta nuove richieste per il progetto.

Usare il backoff esponenziale per i tentativi: attendere un breve intervallo prima del primo tentativo, quindi raddoppiare l'attesa per ogni tentativo successivo. Un intervallo iniziale di 100 millisecondi con un massimo di 30 secondi è un valore predefinito ragionevole.

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()
)
curva
# 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}}'

Annotazioni

Un 409 Conflict oggetto in una richiesta API Lakebase indica che la richiesta non è stata accettata, non che sia stata applicata. Verificare sempre lo stato della risorsa dopo un nuovo tentativo con esito positivo chiamando l'endpoint corrispondente GET .

SDK e Infrastructure as Code