Api-guide för automatisk skalning i Lakebase

Den här sidan innehåller en översikt över Lakebase Autoscaling API, inklusive autentisering, tillgängliga slutpunkter och vanliga mönster för att arbeta med REST API, Databricks CLI och Databricks SDK:er (Python, Java, Go).

Fullständig API-referens finns i dokumentationen för Postgres API.

Authentication

Lakebase Autoscaling-API:et använder OAuth-autentisering på arbetsytenivå för att hantera projektinfrastruktur (skapa projekt, konfigurera inställningar osv.).

Konfigurera autentisering

Autentisera med Databricks CLI:

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

Följ webbläsarprompterna för att logga in. CLI cachelagrar din OAuth-token på ~/.databricks/token-cache.json.

Välj sedan din åtkomstmetod:

Python SDK

SDK använder enhetlig autentisering och hanterar automatiskt OAuth-token:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

SDK använder enhetlig autentisering och hanterar automatiskt OAuth-token:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

Kommandoradsgränssnitt (CLI)

Kommandon använder automatiskt den cachelagrade token:

databricks postgres list-projects

lockig

Generera en token för direkta API-anrop:

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 upphör att gälla efter en timme. Återskapa vid behov.

Mer information finns i Auktorisera användaråtkomst till Databricks med OAuth.

Tillgängliga slutpunkter (Beta)

Alla slutpunkter använder bassökvägen /api/2.0/postgres/.

Projekt

Grenar

Slutpunkter (beräknings- och läsrepliker)

I API:et kallas en beräkning för en slutpunkt. En konceptuell översikt finns i Beräkning och slutpunkter.

I följande tabell mappas gränssnittsbegreppen till deras API-motsvarigheter:

Tillgängliga åtgärder

Roller

Kataloger

Synkroniserade tabeller

Databasautentiseringsuppgifter

Verksamhet

Behörigheter

Project ACL-behörigheter använder standard Azure Databricks Permissions API, inte bassökvägen /api/2.0/postgres/. Ställ in request_object_type till database-projects och request_object_id till ditt projekt-ID (till exempel my-app).

Behörighetsnivåer som kan beviljas för Lakebase-projekt är CAN_USE och CAN_MANAGE. CAN_CREATE är en ärvd nivå och kan inte anges via API:et. Se Behörighetsnivåer.

Användningsexempel och CLI/SDK/Terraform-motsvarigheter finns i Bevilja behörigheter programmatiskt.

Hämta åtgärd

Kontrollera statusen för en tidskrävande åtgärd med dess resursnamn.

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

Kommandoradsgränssnitt (CLI)

CLI väntar automatiskt på att åtgärderna ska slutföras som standard. Använd --no-wait för att hoppa över avsökning:

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

lockig

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

Svarsformat:

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

Fält:

• done: false under tiden som det pågår, true när den är färdig
• response: Innehåller resultatet när done är true
• error: Innehåller felinformation om åtgärden misslyckades

Vanliga mönster

Resursnamngivning

Resurser följer ett hierarkiskt namngivningsmönster där underordnade resurser är kopplade till sina överordnade resurser.

Projekt använder det här formatet:

projects/{project_id}

Underordnade resurser, såsom operationer, nästlas under deras överordnade projekt.

projects/{project_id}/operations/{operation_id}

Det innebär att du behöver det överordnade projektets ID för att få åtkomst till operationer eller andra underordnade resurser.

Resurs-ID:n

När du skapar resurser måste du ange ett resurs-ID (till exempel my-app) för parametern project_id, branch_ideller endpoint_id . Det här ID:t blir en del av resurssökvägen i API-anrop (till exempel projects/my-app/branches/development).

Du kan också ange en display_name för att ge resursen en mer beskrivande etikett. Om du inte anger något visningsnamn använder systemet ditt resurs-ID som visningsnamn.

:::tips Hitta resurser i användargränssnittet

Om du vill hitta ett projekt i Lakebase-användargränssnittet letar du efter dess visningsnamn i projektlistan. Om du inte angav något anpassat visningsnamn när du skapade projektet söker du efter din project_id (till exempel "my-app").

:::

Krav:

• Måste vara 1–63 tecken långt
• Endast gemener, siffror och bindestreck
• Det går inte att starta eller avsluta med ett bindestreck
• Exempel: my-app, analytics-db, customer-123

Långvariga operationer (LRO)

Åtgärder för att skapa, uppdatera och ta bort returnerar ett databricks.longrunning.Operation objekt som ger en slutförandestatus.

Exempel på åtgärdssvar:

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": false
}

Polling för komplettering med 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());

Kommandoradsgränssnitt (CLI)

CLI väntar automatiskt på att åtgärderna ska slutföras som standard. Använd --no-wait för att returnera omedelbart:

databricks postgres create-project my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

lockig

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

Avsök med några sekunders mellanrum tills done är true.

Uppdatera masker

Uppdateringsåtgärder kräver en update_mask parameter som anger vilka fält som ska ändras. Detta förhindrar att orelaterade fält skrivs över av misstag.

Formatera skillnader:

Felhantering

Lakebase-API:et returnerar standard-HTTP-statuskoder.

409: Motstridiga åtgärder

Lakebase kan returnera ett 409 Conflict fel av flera orsaker:

• En intern underhållsåtgärd pågår i projektet.
• Projektet har nått gränsen för samtidiga åtgärder.
• Dina egna API-begäranden överlappar varandra. Till exempel, skapa en gren innan en tidigare gren har slutfört sin skapandeprocess.

Vad det betyder:

Lakebase schemalägger ibland underhållsåtgärder för projekt. Om en klientbegäran kommer när en av dessa åtgärder pågår avvisar Lakebase den nya begäran med ett 409 Conflict fel. Du kan också få det svaret när projektet har kapacitet eller om API-anropen överlappar varandra.

Det här beteendet är förväntat. Klienter bör vara beredda att försöka begäranden igen när det här felet inträffar.

Vad du ska göra:

Försök igen med begäran. När den interna åtgärden slutförs eller kapaciteten frigörs accepterar Lakebase nya begäranden för projektet.

Använd exponentiell backoff för återförsök: vänta ett kort intervall innan det första återförsöket och dubbla sedan väntan på varje efterföljande försök. Ett startintervall på 100 millisekunder med högst 30 sekunder är en rimlig standard.

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

lockig

# 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:er och infrastruktur som kod

• Python SDK
• Java SDK
• Go SDK
• Deklarativa Automationspaket
• Hantera Lakebase-projekt med paket
• Terraform-provider
• Kom igång med Terraform för Lakebase