Api-handleiding voor Automatisch schalen van Lakebase

Deze pagina bevat een overzicht van de Lakebase Automatische schaalaanpassings-API, waaronder verificatie, beschikbare eindpunten en algemene patronen voor het werken met de REST API, Databricks CLI en Databricks SDK's (Python, Java, Go).

Zie de Postgres-API-documentatie voor de volledige API-naslaginformatie.

Authenticatie

De Automatische schaalaanpassings-API van Lakebase maakt gebruik van OAuth-verificatie op werkruimteniveau voor het beheren van de projectinfrastructuur (projecten maken, instellingen configureren, enzovoort).

authenticatie instellen

Verifiëren met behulp van de Databricks CLI:

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

Volg de browserprompts om u aan te melden. De CLI slaat uw OAuth-token op in ~/.databricks/token-cache.jsonde cache.

Kies vervolgens uw toegangsmethode:

Python SDK

De SDK maakt gebruik van geïntegreerde verificatie en verwerkt automatisch OAuth-tokens:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

De SDK maakt gebruik van geïntegreerde verificatie en verwerkt automatisch OAuth-tokens:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI (Command Line Interface)

Opdrachten maken automatisch gebruik van het token in de cache:

databricks postgres list-projects

curl

Genereer een token voor directe API-aanroepen:

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-tokens verlopen na één uur. Genereer indien nodig opnieuw.

Zie Gebruikerstoegang tot Databricks autoriseren met OAuth voor meer informatie.

Beschikbare eindpunten (bèta)

Alle eindpunten gebruiken het basispad /api/2.0/postgres/.

Projecten

Vertakkingen

Eindpunten (berekeningen en leesreplica's)

In de API wordt een rekenproces een eindpunt genoemd. Zie Computes en eindpunten voor een conceptueel overzicht.

De volgende tabel wijst UI-concepten toe aan hun API-equivalenten:

Beschikbare bewerkingen

Rollen

Catalogi

Gesynchroniseerde tabellen

Databasegegevens

Operationeel beheer

Machtigingen

Project ACL-machtigingen maken gebruik van de standaard API voor Azure Databricks machtigingen, niet het basispad /api/2.0/postgres/. Stel de request_object_type in op database-projects en request_object_id op uw project-id (bijvoorbeeld my-app).

De toe te kennen machtigingsniveaus voor Lakebase-projecten zijn CAN_USE en CAN_MANAGE. CAN_CREATE is een overgenomen niveau en kan niet worden ingesteld via de API. Zie Machtigingsniveaus.

Zie Machtigingen programmatisch verlenen voor gebruiksvoorbeelden en CLI/SDK/Terraform-equivalenten.

Bewerking ophalen

Controleer de status van een langdurige bewerking met behulp van de naam van de bron.

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

CLI (Command Line Interface)

De CLI wacht automatisch totdat bewerkingen standaard zijn voltooid. Gebruik --no-wait dit om polling over te slaan:

# 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

Antwoordindeling:

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

Velden:

• done: false tijdens uitvoering, true wanneer voltooid
• response: Bevat het resultaat wanneer done is true
• error: Bevat foutdetails als de bewerking is mislukt

Algemene patronen

Naamgeving van hulpbronnen

Resources volgen een hiërarchisch naamgevingspatroon waarbij onderliggende resources binnen de context van hun bovenliggende resources worden geplaatst.

Projecten gebruiken deze indeling:

projects/{project_id}

Onderliggende hulpmiddelen, zoals bewerkingen, worden geplaatst onder het hoofdproject.

projects/{project_id}/operations/{operation_id}

Dit betekent dat u de ouderproject-id nodig hebt voor toegang tot bewerkingen of andere onderliggende resources.

Resource-ID's:

Bij het maken van resources moet u een resource-id (zoals my-app) opgeven voor de project_id, branch_idof endpoint_id parameter. Deze id maakt deel uit van het resourcepad in API-aanroepen (zoals projects/my-app/branches/development).

U kunt eventueel een display_name beschrijvend label opgeven om uw resource een meer beschrijvend label te geven. Als u geen weergavenaam opgeeft, gebruikt het systeem uw resource-id als weergavenaam.

:::tip resources zoeken in de gebruikersinterface

Als u een project wilt zoeken in de gebruikersinterface van Lakebase, zoekt u de weergavenaam in de lijst met projecten. Als u geen aangepaste weergavenaam hebt opgegeven bij het maken van het project, zoekt u naar uw project_id (zoals 'mijn-app').

:::

Vereisten:

• Moet 1-63 tekens lang zijn
• Alleen kleine letters, cijfers en afbreekstreepjes
• Kan niet beginnen of eindigen met een afbreekstreepje
• Voorbeelden: my-app, analytics-dbcustomer-123

Langlopende bewerkingen (LROs)

Met de bewerkingen voor maken, bijwerken en verwijderen wordt een databricks.longrunning.Operation object geretourneerd dat de voltooiingsstatus biedt.

Voorbeeld van een bewerkingsantwoord:

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

Peiling voor voltooiing met 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());

CLI (Command Line Interface)

De CLI wacht automatisch totdat bewerkingen standaard zijn voltooid. Gebruik --no-wait dit om onmiddellijk terug te keren:

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'

Poll om de paar seconden totdat donetrue is.

Maskers bijwerken

Bijwerkbewerkingen vereisen een update_mask parameter die aangeeft welke velden moeten worden gewijzigd. Dit voorkomt dat niet-gerelateerde velden per ongeluk worden overschreven.

Verschillen in opmaak:

Foutafhandeling

De Lakebase-API retourneert standaard HTTP-statuscodes.

409: Conflicterende bewerkingen

Lakebase kan om verschillende redenen een 409 Conflict fout retourneren:

• Er wordt een interne onderhoudsbewerking uitgevoerd op het project.
• Het project heeft de limiet voor gelijktijdige bewerkingen bereikt.
• Uw eigen API-aanvragen overlappen. U kunt bijvoorbeeld een vertakking maken voordat de creatie van een eerdere vertakking is voltooid.

Wat betekent het:

Lakebase plant soms onderhoudswerkzaamheden voor projecten. Als een clientaanvraag binnenkomt terwijl een van deze bewerkingen wordt uitgevoerd, weigert Lakebase de nieuwe aanvraag met een 409 Conflict fout. Mogelijk krijgt u dat antwoord ook wanneer het project capaciteit heeft of als uw API-aanroepen elkaar overlappen.

Dit is te verwachten gedrag. Clients moeten bereid zijn om aanvragen opnieuw uit te voeren wanneer deze fout optreedt.

Wat u moet doen:

Probeer de aanvraag opnieuw. Wanneer de interne bewerking is voltooid of capaciteit vrij is, accepteert Lakebase nieuwe aanvragen voor het project.

Gebruik exponentieel uitstel voor nieuwe pogingen: wacht een kort interval voor de eerste nieuwe poging en verdubbel de wachttijd bij elke volgende poging. Een begininterval van 100 milliseconden met een maximum van 30 seconden is een redelijke standaardwaarde.

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

SDK's en infrastructuur als code

• Python SDK
• Java SDK
• Go-SDK
• Declaratieve Automatisering-bundels
• Lakebase-projecten beheren met Bundels
• Terraform-provider
• Aan de slag met Terraform voor Lakebase