Guida all'API di scalabilità automatica di Lakebase

Importante

La scalabilità automatica di Lakebase si trova in Beta nelle aree seguenti: eastus2, westeurope, westus.

Lakebase Autoscaling è la versione più recente di Lakebase con calcolo autoscalante, riduzione a zero, ramificazione e ripristino istantaneo. Per il confronto delle funzionalità con Lakebase Provisioned, vedere scegliere tra le versioni.

Questa pagina offre una panoramica dell'API di scalabilità automatica di Lakebase, tra cui autenticazione, endpoint disponibili e modelli comuni per l'uso dell'API REST, dell'interfaccia della riga di comando di Databricks, degli SDK di Databricks (Python, Java, Go) e Terraform.

Per informazioni di riferimento complete sull'API, vedere la documentazione dell'API Postgres.

Importante

L'API Postgres di Lakebase è in versione beta. Gli endpoint, i parametri e i comportamenti dell'API sono soggetti a modifiche.

Authentication

L'API di scalabilità automatica di Lakebase usa l'autenticazione OAuth a livello di area di lavoro per la gestione dell'infrastruttura del progetto (creazione di progetti, configurazione delle impostazioni e così via).

Annotazioni

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

Client SQL (psql, pgAdmin, DBeaver): usare token OAuth di LakeBase o password Postgres. Vedere Autenticazione.
API dati (HTTP RESTful): usare i token OAuth di LakeBase. Vedere API dati.
Driver dei linguaggi di programmazione (psycopg, SQLAlchemy, JDBC): usare i token OAuth di LakeBase o le password di Postgres. Vedere Avvio rapido.

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

Configurare 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

Generare un token per le chiamate API dirette:

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

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

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

Progetti

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

Branch

Operation	Metodo	Punto finale	Documentation
Crea ramo	`POST`	`/projects/{project_id}/branches`	Creare un ramo
Aggiorna il ramo	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Aggiornare le impostazioni del ramo
Elimina ramo	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Eliminare un ramo
Ottenere un ramo	`GET`	`/projects/{project_id}/branches/{branch_id}`	Visualizzare i rami
Elenco di rami	`GET`	`/projects/{project_id}/branches`	Elencare i rami

Endpoint (nodi di calcolo e repliche di lettura)

Operation	Metodo	Punto finale	Documentation
Creare un endpoint	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Creare un ambiente di calcolo / Creare una replica di lettura
Aggiornare l'endpoint	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Modificare un ambiente di calcolo / Modificare una replica in lettura
Eliminare un endpoint	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Eliminare un ambiente di calcolo / Eliminare una replica di lettura
Ottenere l'endpoint	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Visualizzare i calcoli
Elencare gli endpoint	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Visualizzare i calcoli

Credenziali del database

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

Operazioni

Operation	Metodo	Punto finale	Documentation
Operazione Get	`GET`	`/projects/{project_id}/operations/{operation_id}`	Vedere l'esempio seguente

Operazione Recupera

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

Python SDK

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

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

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

curva

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

Formato risposta:

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

Campi:

done: false in corso, true al termine
response: contiene il risultato quando done è true
error: contiene i dettagli dell'errore se l'operazione non è riuscita

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 risorsa:

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.

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 Ricerca di risorse nell'interfaccia utente

Per individuare un progetto nell'interfaccia utente di Lakebase, cercare il nome visualizzato nell'elenco 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.

Requirements:

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 a esecuzione prolungata (LRO)

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

Risposta dell'operazione di esempio:

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

Effettuare il polling per completare usando GetOperation:

Python SDK

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

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

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

CLI

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

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

curva

# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/abc123" \
  -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`

Condividi tramite

Guida all'API di scalabilità automatica di Lakebase

Authentication

Configurare l'autenticazione

Python SDK

Java SDK

CLI

curva

Endpoint disponibili (Beta)

Progetti

Branch

Endpoint (nodi di calcolo e repliche di lettura)

Credenziali del database

Operazioni

Operazione Recupera

Python SDK

Java SDK

CLI

curva

Modelli comuni

Denominazione delle risorse

Operazioni a esecuzione prolungata (LRO)

Python SDK

Java SDK

CLI

curva

Aggiorna le maschere

Risorse aggiuntive

SDK e infrastruttura come codice

Commenti e suggerimenti

Risorse aggiuntive