Guide d'API d'Autoscaling Lakebase
Cette page fournit une vue d'ensemble de l'API d'autoscaling Lakebase, y compris l'authentification, les Endpoint disponibles et les modèles courants pour travailler avec l'API REST, la CLI Databricks et les SDK Databricks (Python, Java, Go).
Pour la référence complète de l'API, consultez la documentation de l'API Postgres.
L'API Lakebase Postgres est en bêta . Les Endpoint API, les parameters et les comportements peuvent être modifiés.
Authentification
L'API Lakebase Autoscaling utilise l' authentification OAuth au niveau du Workspace pour gérer l'infrastructure de projet (création de projets, configuration des paramètres, etc.).
Deux types de connectivité : cette API est destinée à la gestion de plateforme (création de projets, Branch, computes). Pour l' accès à la base de données (connexion pour interroger les données) :
- Clients SQL (psql, pgAdmin, DBeaver) : utilisez les jetons OAuth Lakebase ou les mots de passe Postgres. Voir Authentification.
- API de données (RESTful HTTP) : utilisez des jetons Lakebase OAuth. Voir Data API.
- **Drivers de langage de programmation** (psycopg, SQLAlchemy, JDBC) : utilisez les jetons OAuth Lakebase ou les mots de passe Postgres. Consultez le Guide de démarrage rapide.
Pour une explication complète de ces deux couches d'authentification, voir l'architecture d'authentification.
Configurer l'authentification
Authentifiez-vous à l'aide de la CLI Databricks :
databricks auth login --host https://your-workspace.cloud.databricks.com
Suivez les invites du navigateur pour la Connexion. La CLI met en cache votre jeton OAuth à l'emplacement ~/.databricks/token-cache.json.
Choisissez ensuite votre méthode d'accès :
- Python SDK
- Java SDK
- CLI
- curl
Le SDK utilise une authentification unifiée et gère automatiquement les jetons OAuth :
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
Le SDK utilise une authentification unifiée et gère automatiquement les jetons OAuth :
import com.databricks.sdk.WorkspaceClient;
WorkspaceClient w = new WorkspaceClient();
Les commandes utilisent automatiquement le jeton mis en cache :
databricks postgres list-projects
Générer un jeton pour les appels d’API directs :
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}"
Les jetons OAuth expirent après une heure. Régénérez si nécessaire.
Pour plus de détails, consultez Autoriser l’accès utilisateur à Databricks avec OAuth.
Endpoints disponibles (Bêta)
Tous les endpoints utilisent le chemin de base /api/2.0/postgres/.
Projets
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Créer un projet |
|
| |
Mettre à jour le projet |
|
| |
Supprimer le projet |
|
| |
Obtenir le projet |
|
| |
Lister les projets |
|
|
Branch
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Créer une branche |
|
| |
Mettre à jour la Branch |
|
| |
Supprimer la Branch |
|
| |
Obtenir la Branch |
|
| |
Lister les Branch |
|
|
Endpoints (Computes et Réplicas en lecture)
Dans l'API, un compute est appelé un Endpoint . Pour un aperçu conceptuel, veuillez consulter Calculs et Endpoints.
Le tableau suivant met en correspondance les concepts de l'interface utilisateur et leurs équivalents API :
Concept d'interface utilisateur | Ressource ou champ d'API | Documentation |
|---|---|---|
Compute principal | Endpoint avec. | |
Réplica en lecture | Endpoint avec. | |
Haute disponibilité |
| |
Identifiants de compute (UID, Nom de la ressource) |
|
Opérations disponibles
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Créer un Endpoint |
|
| |
Mettre à jour l'Endpoint |
|
| Modifier un compute / Modifier un réplica en lecture / Gérer la haute disponibilité |
Supprimer l'Endpoint. |
|
| |
Obtenir un endpoint |
|
| |
Lister les Endpoint |
|
|
Rôles
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Lister les rôles |
|
| |
Créez un rôle |
|
| |
Obtenir un rôle |
|
| |
Mettre à jour le rôle |
|
| |
Supprimer le rôle |
|
|
Catalogues
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Enregistrer la base de données avec Unity Catalog |
|
| |
Obtenir l’enregistrement du catalogue |
|
| |
Supprimer l'enregistrement du catalogue |
|
|
L'enregistrement et la suppression sont des opérations de longue durée. Interrogez l'opération renvoyée jusqu'à done: true. Consultez les opérations de longue durée.
La suppression d’un enregistrement de catalogue ne supprime pas la base de données Postgres sous-jacente.
Tables synchronisées
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Créer une table synchronisée |
|
| |
Obtenir la table synchronisée |
|
| |
Supprimer la table synchronisée |
|
|
Le table_name dans le chemin utilise le format catalog.schema.table.
La création et la suppression sont des opérations de longue durée. Interrogez l'opération renvoyée jusqu'à done: true. Consultez les opérations de longue durée.
La suppression d'une table synchronisée supprime uniquement l'enregistrement Unity Catalog. Supprimez la table Postgres séparément pour libérer de l'espace.
Identifiants de base de données
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Générer les identifiants de la base de données |
|
|
Opérations
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Obtenir l'opération |
|
|
Autorisations
Les autorisations ACL de projet utilisent l'API standard de gestion des autorisations Databricks, et non le chemin de base /api/2.0/postgres/. Définissez le request_object_type sur database-projects et le request_object_id sur l'ID de votre projet (par exemple, my-app).
Opérations | Méthode | Point de terminaison | Documentation |
|---|---|---|---|
Obtenir les autorisations du projet |
|
| |
Mise à jour des autorisations de projet |
|
| |
Remplacer les autorisations de projet |
|
|
Les niveaux d’autorisation accordables pour les projets Lakebase sont CAN_USE et CAN_MANAGE. CAN_CREATE est un niveau hérité et ne peut pas être défini grâce à l'API. Voir les niveaux d'autorisation.
Pour des exemples d'utilisation et des équivalents CLI/SDK/Terraform, voir Accorder des autorisations par programmation.
Obtenir l'opération
Vérifiez l'état d'une opération de longue durée par son nom de ressource.
- Python SDK
- Java SDK
- CLI
- curl
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}")
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());
L'interface CLI attend automatiquement la fin des Opérations par default. Utilisez --no-wait pour ignorer le sondage :
# 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>
# Get operation status
curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq
Format de réponse :
{
"name": "projects/my-project/operations/<operation-id>",
"done": true,
"response": {
"@type": "type.googleapis.com/databricks.postgres.v1.Project",
"name": "projects/my-project",
...
}
}
Champs :
done:falseen cours,trueterminéresponse: Contient le résultat lorsquedoneesttrueerror: Contient les détails de l'erreur si l'opération a échoué
Modèles courants
Dénomination des ressources
Les Ressources suivent un modèle de nommage hiérarchique où les ressources enfant sont limitées à leur parent.
Les projets utilisent ce format :
projects/{project_id}
Les ressources enfants telles que les opérations sont imbriquées sous leur projet parent :
projects/{project_id}/operations/{operation_id}
Cela signifie que vous avez besoin de l'ID de projet parent pour accéder aux Opérations ou à d'autres Ressources enfants.
ID de ressources :
Lorsque vous créez des ressources, vous devez fournir un ID de ressource (tel que my-app) pour le paramètre project_id, branch_id ou endpoint_id. Cet ID fait partie du chemin de ressource dans les appels d'API (par exemple projects/my-app/branches/development).
Vous pouvez éventuellement fournir un display_name pour donner à votre ressource une étiquette plus descriptive. Si vous ne spécifiez pas de nom d'affichage, le système utilise votre ID de ressource comme nom d'affichage.
:::tip Recherche de ressources dans l’interface utilisateur
Pour localiser un projet dans l'interface utilisateur Lakebase, recherchez son nom d'affichage dans la liste des projets. Si vous n'avez pas fourni de nom d'affichage personnalisé lors de la création du projet, recherchez votre project_id (tel que « my-app »).
:::
Les ID de ressources ne peuvent pas être modifiés après la création.
Exigences :
- Doit avoir une longueur de 1 à 63 caractères
- Lettres minuscules, chiffres et tirets uniquement.
- Ne peut pas start ni se terminer par un tiret
- Exemples :
my-app,analytics-db,customer-123
Opérations de longue durée (LRO)
Les Opérations de création, de mise à jour et de suppression renvoient un objet databricks.longrunning.Operation qui fournit un statut d’achèvement.
Exemple de réponse d'opération :
{
"name": "projects/my-project/operations/<operation-id>",
"done": false
}
Interroger pour la complétion à l’aide de GetOperation :
- Python SDK
- Java SDK
- CLI
- curl
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}")
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());
L'interface CLI attend automatiquement la fin des Opérations par default. Utilisez --no-wait pour renvoyer immédiatement :
databricks postgres create-project my-project --no-wait \
--json '{"spec": {"pg_version": 17}}'
# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq '.done'
Interrogez toutes les quelques secondes jusqu'à ce que done soit true.
Mettre à jour les masques
Les Opérations de mise à jour nécessitent un parameter update_mask spécifiant les champs à modifier. Cela empêche d'écraser accidentellement des champs non liés.
Différences de format :
Méthode | Format | Exemple |
|---|---|---|
API REST | parameter de query |
|
SDK Python | Objet FieldMask |
|
CLI | Argument positionnel. |
|
Gestion des erreurs
L'API Lakebase renvoie des codes de statut HTTP standard.
409 : opérations en conflit
Lakebase peut retourner une erreur 409 Conflict pour plusieurs raisons :
- Une opération de maintenance interne est en cours sur le projet.
- Le projet a atteint sa limite d'opérations simultanées.
- Vos propres requêtes API se chevauchent. Par exemple, la création d'une branch avant qu'une création de branch précédente ne soit terminée.
Ce que cela signifie :
Lakebase planifie parfois des opérations de maintenance sur les projets. Si une requête client arrive pendant qu'une de ces Opérations est en cours, Lakebase rejette la nouvelle requête avec une erreur 409 Conflict. Vous pouvez également obtenir cette réponse lorsque le projet est à pleine capacité ou que vos appels API se chevauchent.
C'est un comportement attendu. Les clients doivent être prêts à retenter les requêtes lorsque cette erreur se produit.
Que faire :
Réessayez la requête. Lorsque l'opération interne est terminée ou que la capacité se libère, Lakebase accepte de nouvelles demandes pour le projet.
Utilisez un intervalle exponentiel pour les nouvelles tentatives : attendez un court intervalle avant la première nouvelle tentative, puis doublez le temps d'attente à chaque tentative ultérieure. Un intervalle de départ de 100 millisecondes avec un maximum de 30 secondes constitue un default raisonnable.
- Python SDK
- curl
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()
)
# 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}}'
Un 409 Conflict sur une requête API Lakebase signifie que la requête n'a pas été acceptée, et non qu'elle ait été appliquée. Vérifiez toujours l'état de la ressource après une nouvelle tentative réussie en appelant l'endpoint GET correspondant.