Lakebase API-Leitfaden

Diese Seite bietet einen Überblick über die Lakebase-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).

Für die vollständige Liste der Operationen und ihrer Parameter siehe die Postgres API-Referenz.

Authentifizierung

Die Lakebase-API verwendet OAuth-Authentifizierung auf Arbeitsflächenebene zur Verwaltung der Projektinfrastruktur (Projekterstellung, Konfiguration 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

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

Projekte

Verzweigungen

Endpunkte (Computes und Lesereplikate)

In der API wird eine Berechnung als Endpunkt bezeichnet. Eine konzeptionelle Übersicht finden Sie unter Computes und Endpunkte.

Die folgende Tabelle ordnet UI-Konzepte ihren API-Entsprechungen zu:

Verfügbare Vorgänge

Rollen

Kataloge

Synchronisierte Tabellen

Datenübertragung ändern

Die Lakebase Change Data Feed (CDF)-Operationen sind auf einen Zweig beschränkt. Für Details zur Anfrage und Antwort siehe die CDF-Operationen in der Postgres API-Referenz.

Datenbank-Zugangsdaten

Operationen

Berechtigungen

Project ACL-Berechtigungen verwenden die standard Azure Databricks Permissions API und nicht den /api/2.0/postgres/ Basispfad. Legen Sie die request_object_type auf database-projects und request_object_id auf Ihre Projekt-ID fest (z. B. my-app).

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

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

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

cURL

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

Antwortformat:

{
  "name": "projects/my-project/operations/<operation-id>",
  "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 ein display_name bereitstellen, um Ihrer Ressource eine aussagekräftige Beschriftung zu geben. 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 App zu finden, suchen Sie in der Projektliste nach seinem 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/<operation-id>",
  "done": false
}

Abfrage zum Abschluss mithilfe von GetOperation:

Python SDK

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

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

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

cURL

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

Lakebase kann aus mehreren Gründen einen 409 Conflict Fehler zurückgeben:

• Ein interner Wartungsvorgang wird im Projekt ausgeführt.
• Das Projekt hat seine Kapazitätsgrenze für gleichzeitige Vorgänge erreicht.
• Ihre eigenen API-Anforderungen überlappen sich. Zum Beispiel das Erstellen einer Verzweigung, bevor eine vorherige Verzweigungserstellung abgeschlossen ist.

Was dies bedeutet:

Lakebase plant manchmal Wartungsvorgänge für Projekte. Wenn eine Clientanforderung eingeht, während eine dieser Vorgänge ausgeführt wird, lehnt Lakebase die neue Anforderung mit einem 409 Conflict Fehler ab. Sie erhalten möglicherweise auch diese Antwort, wenn das Projekt ausgelastet ist oder sich Ihre API-Aufrufe überlappen.

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 oder Kapazität freigegeben wird, 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