Condividi tramite

Guida all'API di scalabilità automatica di Lakebase

Importante

La scalabilità automatica di Lakebase è disponibile nelle aree seguenti: eastus, eastus2, centralus, southcentralus, westus, westus2, canadacentral, brazilsouth, northeurope, uksouth, westeurope, australiaeast, centralindia, southeastasia.

La scalabilità automatica di Lakebase è la versione più recente di Lakebase, con calcolo autoscalabile, scalabilità fino a zero, ramificazione e ripristino immediato. Se sei un utente provisioning di Lakebase, vedere Lakebase provisioning.

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 e degli SDK di Databricks (Python, Java, Go).

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 del linguaggio di programmazione (psycopg, SQLAlchemy, JDBC): usare token OAuth di Lakebase o password 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

Ruoli

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

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

Autorizzazioni

Le autorizzazioni ACL di progetto usano l'API autorizzazioni standard di Azure Databricks, non il /api/2.0/postgres/ percorso di base. Impostare request_object_type su database-projects e request_object_id sull'ID del progetto.

Operation Metodo Punto finale Documentation
Ottenere le autorizzazioni per il progetto GET /api/2.0/permissions/database-projects/{project_id} Informazioni di riferimento sulle API per le autorizzazioni
Aggiornare le autorizzazioni del progetto PATCH /api/2.0/permissions/database-projects/{project_id} Informazioni di riferimento sulle API per le autorizzazioni
Sostituire le autorizzazioni del progetto PUT /api/2.0/permissions/database-projects/{project_id} Informazioni di riferimento sulle API per le autorizzazioni

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.

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

Il 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

SDK e infrastruttura come codice

  • Last updated on