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

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 sdk Databricks (Python, Java, Go).

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

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

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 :

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

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

Branches

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

Dans l’API, un calcul est appelé point de terminaison. Pour obtenir une vue d’ensemble conceptuelle, consultez Calculs et points de terminaison.

Le tableau suivant mappe les concepts de l’interface utilisateur à leurs équivalents d’API :

Opérations disponibles

Rôles

Catalogues

Tables synchronisées

Informations d’identification de base de données

Opérations

Autorisations

Les autorisations ACL du projet utilisent l’API standard Azure Databricks Permissions, et non pas le chemin d’accès de base . Définissez request_object_type sur database-projects et request_object_id sur l’ID de votre projet (par exemple, my-app).

Les niveaux d’autorisation pouvant être accordés pour les projets Lakebase sont CAN_USE et CAN_MANAGE. CAN_CREATE est un niveau hérité et ne peut pas être défini via l’API. Consultez les niveaux d’autorisation.

Pour obtenir des exemples d’utilisation et des équivalents CLI/SDK/Terraform, consultez Accorder des autorisations par programmation.

Opération Obtenir

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

SDK Python

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

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

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

friser

# 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: 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 »).

:::

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/<operation-id>",
  "done": false
}

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

SDK Python

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

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

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 my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

friser

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

Gestion des erreurs

L’API Lakebase retourne des codes d’état HTTP standard.

409 : Opérations en conflit

Lakebase peut retourner une 409 Conflict erreur 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 demandes d’API se chevauchent. Par exemple, créer une branche avant que la création d'une branche précédente ne soit terminée.

Signification :

Lakebase planifie parfois des opérations de maintenance sur des projets. Si une demande cliente arrive alors qu’une de ces opérations est en cours, Lakebase rejette la nouvelle demande avec une 409 Conflict erreur. Vous pouvez également obtenir cette réponse lorsque le projet est en capacité ou que vos appels d’API se chevauchent.

Ce comportement est normal. Les clients doivent être prêts à réessayer les demandes lorsque cette erreur se produit.

Que faire :

Relancez la requête. Une fois l’opération interne terminée ou la capacité libérée, Lakebase accepte de nouvelles demandes pour le projet.

Utilisez une interruption exponentielle pour les nouvelles tentatives : attendez un court intervalle avant la première nouvelle tentative, puis doublez l’attente sur chaque tentative suivante. Un intervalle de départ de 100 millisecondes avec un maximum de 30 secondes est une valeur par défaut raisonnable.

SDK Python

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

friser

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

SDK et infrastructure en tant que code

• sdk Python
• Java SDK
• Kit de développement logiciel (SDK) Go
• Ensembles d'automatisation déclarative
• Gérer des projets Lakebase avec des bundles
• Fournisseur Terraform
• Prise en main de Terraform pour Lakebase