Partager via

Guide de l’API de mise à l’échelle automatique Lakebase

Important

La mise à l’échelle automatique Lakebase est en version bêta dans les régions suivantes : eastus2, westeurope, westus.

La version Autoscaling de Lakebase est la dernière de Lakebase, offrant l'autoscaling, la mise à l'échelle à zéro, la bifurcation et la restauration instantanée. Pour la comparaison des fonctionnalités avec Lakebase Provisioned, consultez le choix entre les versions.

Cette page fournit une vue d’ensemble de l’API de mise à l’échelle automatique Lakebase, notamment l’authentification, les points de terminaison disponibles et les modèles courants pour l’utilisation de l’API REST, de l’interface CLI Databricks et des kits SDK Databricks (Python, Java, Go).

Pour obtenir la référence complète de l’API, consultez la documentation de l’API Postgres.

Important

L’API Postgres Lakebase est en version bêta. Les points de terminaison d’API, les paramètres et les comportements sont susceptibles de changer.

Authentication

L’API de mise à l’échelle automatique Lakebase utilise l’authentification OAuth au niveau de l’espace de travail pour la gestion de l’infrastructure de projet (création de projets, configuration des paramètres, etc.).

Note

Deux types de connectivité : cette API est destinée à la gestion de la plateforme (création de projets, branches, calculs). Pour l’accès à la base de données (connexion aux données de requête) :

  • Clients SQL (psql, pgAdmin, DBeaver) : utilisez des jetons OAuth Lakebase ou des mots de passe Postgres. Consultez Authentification.
  • API de données (HTTP RESTful) : utilisez des jetons OAuth Lakebase. Consultez l’API de données.
  • Pilotes de langage de programmation (psycopg, SQLAlchemy, JDBC) : utilisez des jetons OAuth Lakebase ou des mots de passe Postgres. Consultez le guide de démarrage rapide.

Pour obtenir une explication complète de ces deux couches d’authentification, consultez architecture d’authentification.

Configurer l’authentification

Authentifiez-vous à l’aide de l’interface CLI Databricks :

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

Suivez les invites de navigateur pour vous connecter. L’interface CLI met en cache votre jeton OAuth à l’adresse ~/.databricks/token-cache.json.

Choisissez ensuite votre méthode d’accès :

Kit de développement logiciel (SDK) Python

Le Kit de développement logiciel (SDK) utilise l’authentification unifiée et gère automatiquement les jetons OAuth :

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Kit de développement logiciel (SDK) Java

Le Kit de développement logiciel (SDK) utilise l’authentification unifiée et gère automatiquement les jetons OAuth :

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

Interface de ligne de commande (CLI)

Les commandes utilisent automatiquement le jeton mis en cache :

databricks postgres list-projects

friser

Générez 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érer en fonction des besoins.

Pour plus d’informations, consultez Autoriser l’accès utilisateur à Databricks avec OAuth.

Points de terminaison disponibles (bêta)

Tous les points de terminaison utilisent le chemin /api/2.0/postgres/de base .

Projets

Opération Méthode Point de terminaison Documentation
Créer un projet POST /projects Créer un projet
Mettre à jour le projet PATCH /projects/{project_id} paramètres généraux
Supprimer le projet DELETE /projects/{project_id} Supprimer un projet
Obtenir un projet GET /projects/{project_id} Obtenir les détails du projet
Répertorier les projets GET /projects Répertorier les projets

Branches

Opération Méthode Point de terminaison Documentation
Créer une branche POST /projects/{project_id}/branches Créer une branche
Mettre à jour la branche PATCH /projects/{project_id}/branches/{branch_id} Mettre à jour les paramètres de branche
Supprimer une branche DELETE /projects/{project_id}/branches/{branch_id} Supprimer une branche
Récupérer une branche GET /projects/{project_id}/branches/{branch_id} Afficher les branches
Répertorier les branches GET /projects/{project_id}/branches Répertorier les branches

Points de terminaison (calculs et réplicas en lecture)

Opération Méthode Point de terminaison Documentation
Création d’un point de terminaison POST /projects/{project_id}/branches/{branch_id}/endpoints Créer une instance de calcul / Créer une réplique de lecture
Mettre à jour le point de terminaison PATCH /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} Modifier une instance de calcul / Modifier une réplique en lecture
Supprimer le point de terminaison DELETE /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} Supprimer une instance de calcul / Supprimer un réplica de lecture
Obtenir un point de terminaison GET /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} Afficher les calculs
Lister les points de terminaison GET /projects/{project_id}/branches/{branch_id}/endpoints Afficher les calculs

Informations d’identification de base de données

Opération Méthode Point de terminaison Documentation
Générer des identifiants de base de données POST /credentials Authentification par jeton OAuth

Opérations

Opération Méthode Point de terminaison Documentation
Opération de récupération GET /projects/{project_id}/operations/{operation_id} Voir l’exemple ci-dessous

Opération Obtenir

Vérifiez l’état d’une opération de longue durée par son nom de ressource.

Kit de développement logiciel (SDK) Python

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

Kit de développement logiciel (SDK) Java

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

Interface de ligne de commande (CLI)

L’interface CLI attend automatiquement que les opérations se terminent par défaut. Utilisez --no-wait pour ignorer l’interrogation :

# Create project without waiting
databricks postgres create-project --no-wait ...

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

friser

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

Format de réponse :

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

Champs:

  • done: false en cours, true une fois terminé
  • response: contient le résultat quand done est true
  • error: contient les détails de l’erreur en cas d’échec de l’opération

Modèles courants

Nommage des ressources

Les ressources suivent un modèle de nommage hiérarchique dans lequel les ressources enfants sont définies par rapport à 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 ressource :

Lors de la création de ressources, vous devez fournir un ID de ressource (par exemple my-app) pour le paramètre project_id, branch_id ou endpoint_id. Cet ID fait partie du chemin d’accès aux ressources dans les appels d’API (par projects/my-app/branches/developmentexemple).

Vous pouvez éventuellement fournir une display_name étiquette plus descriptive à votre ressource. 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 complet 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 (par exemple, « my-app »).

:::

Note

Les ID de ressource ne peuvent pas être modifiés après la création.

Exigences:

  • Doit comporter 1 à 63 caractères
  • Lettres minuscules, chiffres et traits d’union uniquement
  • Impossible de démarrer ou de se terminer par un trait d’union
  • Exemples : my-app, , analytics-dbcustomer-123

Opérations de longue durée (LRO)

Les opérations de création, de mise à jour et de suppression retournent un databricks.longrunning.Operation objet qui fournit un état d’achèvement.

Exemple de réponse d’opération :

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

Interroger pour vérifier l'achèvement à l’aide de GetOperation :

Kit de développement logiciel (SDK) Python

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

Kit de développement logiciel (SDK) Java

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

Interface de ligne de commande (CLI)

L’interface CLI attend automatiquement que les opérations se terminent par défaut. Permet --no-wait de retourner immédiatement :

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

friser

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

Vérifiez toutes les quelques secondes jusqu'à ce que done soit true.

Mettre à jour des masques

Les opérations de mise à jour nécessitent un update_mask paramètre spécifiant les champs à modifier. Cela empêche le remplacement accidentel de champs non liés.

Différences de format :

Méthode Format Example
REST API Paramètre de requête. ?update_mask=spec.display_name
Kit de développement logiciel (SDK) Python Objet FieldMask update_mask=FieldMask(field_mask=["spec.display_name"])
Interface de ligne de commande (CLI) Argument positionnel update-project NAME spec.display_name

SDK et infrastructure en tant que code

  • Last updated on