Leitfaden für die Automatische Skalierung der Lakebase-API

Diese Seite bietet eine Übersicht über die Lakebase Autoscaling-API, einschließlich Authentifizierung, verfügbarer Endpunkte und gängiger Muster für die Arbeit mit der REST-API, der Databricks CLI und den Databricks SDKs (Python, Java, Go).

Die vollständige API-Referenz finden Sie in der Dokumentation zur Postgres-API.

Authentifizierung

Die Lakebase Autoscaling-API verwendet die OAuth-Authentifizierung auf Arbeitsbereichsebene zum Verwalten der Projektinfrastruktur (Erstellen von Projekten, Konfigurieren von Einstellungen, usw.).

Einrichten der Authentifizierung

Authentifizieren mithilfe der Databricks CLI:

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

Folgen Sie den Browseraufforderungen, um sich anzumelden. Die CLI speichert Ihr OAuth-Token unter ~/.databricks/token-cache.json.

Wählen Sie dann Ihre Zugriffsmethode aus:

Python SDK

Das SDK verwendet einheitliche Authentifizierung und verarbeitet automatisch OAuth-Token:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java-SDK

Das SDK verwendet einheitliche Authentifizierung und verarbeitet automatisch OAuth-Token:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

Befehlszeilenschnittstelle (CLI)

Befehle verwenden automatisch das zwischengespeicherte Token:

databricks postgres list-projects

cURL

Generieren Sie ein Token für direkte API-Aufrufe:

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

OAuth-Token laufen nach einer Stunde ab. Regenerieren Sie nach Bedarf.

Weitere Details finden Sie unter Autorisieren des Benutzerzugriffs auf Databricks mit OAuth.

Verfügbare Endpunkte (Beta)

Alle Endpunkte verwenden den Basispfad /api/2.0/postgres/.

Projekte

Zweige

Endpunkte (Berechnet und Lesen von Replikaten)

Rollen

Datenbank-Zugangsdaten

Operationen

Berechtigungen

Project-ACL-Berechtigungen verwenden die standardmäßige Azure Databricks-Berechtigungs-API, nicht den /api/2.0/postgres/ Basispfad. Setzen Sie die request_object_type auf database-projects und request_object_id auf die Projekt-ID.

Die zulässigen Berechtigungsstufen für Lakebase-Projekte sind CAN_USE und CAN_MANAGE. CAN_CREATE ist eine geerbte Ebene und kann nicht über die API festgelegt werden. Siehe Berechtigungsstufen.

Für Verwendungsbeispiele und entsprechende CLI/SDK/Terraform-Kommandos siehe Erteilen von Berechtigungen programmgesteuert.

Vorgang abrufen

Überprüfen Sie den Status eines lang andauernden Vorgangs anhand des Ressourcennamens.

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

Befehlszeilenschnittstelle (CLI)

Die CLI wartet automatisch, bis Vorgänge standardmäßig abgeschlossen sind. Verwenden Sie --no-wait zum Überspringen des Abfragens.

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

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

cURL

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

Antwortformat:

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

Felder:

• done: false während der Bearbeitung, true nach Abschluss
• response: Enthält das Ergebnis, wenn donetrue ist.
• error: Enthält Fehlerdetails, wenn der Vorgang fehlgeschlagen ist.

Allgemeine Muster

Ressourcen-Namensgebung

Ressourcen folgen einem hierarchischen Benennungsmuster, bei dem untergeordnete Ressourcen ihren übergeordneten Elementen zugeordnet sind.

Projekte verwenden dieses Format:

projects/{project_id}

Untergeordnete Ressourcen wie Vorgänge werden unter ihrem übergeordneten Projekt geschachtelt:

projects/{project_id}/operations/{operation_id}

Dies bedeutet, dass Sie die übergeordnete Projekt-ID für den Zugriff auf Vorgänge oder andere untergeordnete Ressourcen benötigen.

Ressourcen-IDs:

Beim Erstellen von Ressourcen müssen Sie eine Ressourcen-ID angeben (z. B. my-app) für die Parameter project_id, branch_id oder endpoint_id. Diese ID wird Teil des Ressourcenpfads in API-Aufrufen (z. B. projects/my-app/branches/development).

Sie können optional Ihrer Ressource eine display_name aussagekräftige Beschriftung vergeben. Wenn Sie keinen Anzeigenamen angeben, verwendet das System Ihre Ressourcen-ID als Anzeigenamen.

:::tipp: Suchen von Ressourcen auf der Benutzeroberfläche

Um ein Projekt in der Lakebase-Benutzeroberfläche zu finden, suchen Sie in der Projektliste nach dem Anzeigenamen. Wenn Sie beim Erstellen des Projekts keinen benutzerdefinierten Anzeigenamen angegeben haben, suchen Sie nach Ihrem project_id (z. B. "my-app").

:::

Requirements:

• Muss 1 bis 63 Zeichen lang sein
• Nur Kleinbuchstaben, Ziffern und Bindestriche
• Kann nicht mit einem Bindestrich beginnen oder enden
• Beispiele: my-app, , analytics-dbcustomer-123

Lang andauernde Vorgänge (LROs)

Erstellen, Aktualisieren und Löschen geben ein databricks.longrunning.Operation Objekt zurück, das einen Abschlussstatus bereitstellt.

Beispiel-Vorgangsantwort:

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

Abfrage zum Abschluss mithilfe von 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());

Befehlszeilenschnittstelle (CLI)

Die CLI wartet automatisch, bis Vorgänge standardmäßig abgeschlossen sind. Verwenden Sie --no-wait, um sofort zurückzukehren:

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

cURL

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

Alle paar Sekunden abfragen, bis donetrue ist.

Aktualisieren von Masken

Aktualisierungsvorgänge erfordern einen update_mask Parameter, der angibt, welche Felder geändert werden sollen. Dadurch wird verhindert, dass nicht verknüpfte Felder versehentlich überschrieben werden.

Formatunterschiede:

Fehlerbehandlung

Die Lakebase-API gibt standardmäßige HTTP-Statuscodes zurück.

409: Widersprüchliche Vorgänge

Fehlermeldung:

project already has running conflicting operations, scheduling of new ones is prohibited

Was dies bedeutet:

Lakebase plant manchmal interne Wartungsvorgänge für Projekte. Wenn eine Clientanforderung eingeht, während einer dieser internen Vorgänge ausgeführt wird, kann Lakebase die neue Anforderung mit einem 409 Conflict Fehler ablehnen.

Dieses Verhalten wird erwartet. Clients sollten darauf vorbereitet sein, Anforderungen erneut auszuführen, wenn dieser Fehler auftritt.

Was ist zu tun:

Wiederholen Sie die Anforderung. Wenn der interne Vorgang abgeschlossen ist, akzeptiert Lakebase neue Anforderungen für das Projekt.

Verwenden Sie eine exponentielle Backoff-Strategie für Wiederholungen: Warten Sie ein kurzes Intervall, bevor Sie den ersten Wiederholungsversuch ausführen, und verdoppeln Sie dann die Wartezeit bei jedem nachfolgenden Versuch. Ein Startintervall von 100 Millisekunden mit maximal 30 Sekunden ist ein vernünftiger Standardwert.

Python SDK

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

cURL

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

SDKs und Infrastruktur als Code

• Python SDK
• Java SDK
• Go SDK
• Deklarative Automatisierungspakete
• Verwalten von Lakebase-Projekten mit Bundles
• Terraform-Anbieter
• Erste Schritte mit Terraform für Lakebase