Guia da API de Autoscaling do Lakebase

Importante

O Autoscaling Lakebase está disponível nas seguintes regiões: eastus, eastus2, centralus, southcentralus, westus, westus2, canadacentral, brazilsouth, northeurope, uksouth, westeurope, australiaeast, centralindia, southeastasia.

O Autoscaling do Lakebase é a versão mais recente do Lakebase, com computação autoescalável, escala até zero, ramificação e restauração instantânea. Se é utilizador do Lakebase Provisioned, consulte Lakebase Provisioned.

Esta página fornece uma visão geral da API de Autoscaling do Lakebase, incluindo autenticação, endpoints disponíveis e padrões comuns para trabalhar com a API REST, CLI do Databricks e SDKs do Databricks (Python, Java, Go).

Para a referência completa da API, consulte a documentação da API Postgres.

Importante

A API do Lakebase Postgres está em fase Beta. Os endpoints, parâmetros e comportamentos da API estão sujeitos a alterações.

Authentication

A API Lakebase Autoscaling utiliza autenticação OAuth ao nível do espaço de trabalho para gerir a infraestrutura de projetos (criação de projetos, configuração de definições, etc.).

Observação

Dois tipos de conectividade: Esta API destina-se à gestão de plataformas (criação de projetos, branches, computações). Para acesso à base de dados (ligação a dados de consulta):

Clientes SQL (psql, pgAdmin, DBeaver): Utilize tokens OAuth do Lakebase ou palavras-passe do Postgres. Consulte Autenticação.
API de Dados (HTTP RESTful): Use tokens de OAuth do Lakebase. Ver Data API.
Controladores de linguagens de programação (psycopg, SQLAlchemy, JDBC): Utilize tokens Lakebase OAuth ou palavras-passe Postgres. Veja Quickstart.

Para uma explicação completa destas duas camadas de autenticação, veja Arquitetura de autenticação.

Configurar a autenticação

Autentique usando a CLI Databricks:

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

Siga as instruções do navegador para iniciar sessão. A CLI armazena em cache o seu token OAuth em ~/.databricks/token-cache.json.

Depois escolhe o teu método de acesso:

Python SDK

O SDK utiliza autenticação unificada e gere automaticamente os tokens OAuth:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

SDK de Java

O SDK utiliza autenticação unificada e gere automaticamente os tokens OAuth:

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

Os comandos usam automaticamente o token em cache:

databricks postgres list-projects

encaracolar

Gerar um token para chamadas diretas de API:

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

Os tokens OAuth expiram após uma hora. Regenerar conforme necessário.

Para mais detalhes, consulte Autorizar o acesso do utilizador a Databricks com OAuth.

Endpoints disponíveis (Beta)

Todos os endpoints utilizam o caminho base /api/2.0/postgres/.

Projetos

Funcionamento	Método	Ponto final	Documentation
Criar o projeto	`POST`	`/projects`	Criar um projeto
Atualizar projeto	`PATCH`	`/projects/{project_id}`	Configurações gerais
Excluir projeto	`DELETE`	`/projects/{project_id}`	Eliminar um projeto
Obter projeto	`GET`	`/projects/{project_id}`	Obtenha detalhes do projeto
Listar projetos	`GET`	`/projects`	Listar projetos

Filiais

Funcionamento	Método	Ponto final	Documentation
Criar ramo	`POST`	`/projects/{project_id}/branches`	Criar uma ramificação
Atualizar ramo	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	Atualizar as configurações da filial
Excluir ramo	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	Eliminar uma ramificação
Obtém ramo	`GET`	`/projects/{project_id}/branches/{branch_id}`	Ver ramificações
Listar ramos	`GET`	`/projects/{project_id}/branches`	Lista de ramos

Endpoints (Computa e Lê Réplicas)

Funcionamento	Método	Ponto final	Documentation
Criar ponto de extremidade	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Criar um cálculo / Criar uma réplica de leitura
Atualizar endpoint	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Editar um cálculo / Editar uma réplica lida
Excluir ponto de extremidade	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Eliminar um cálculo / Eliminar uma réplica de leitura
Obter endpoint	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	Visualização computa
Listar pontos finais	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	Visualização computa

Papéis

Funcionamento	Método	Ponto final	Documentation
Listar funções	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Ver funções dos Postgres
Criar papel	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	Criar uma função OAuth \|
Obter papel	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Ver funções dos Postgres
Atualizar função	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Atualizar um papel
Eliminar função	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	Eliminar uma função

Credenciais de Base de Dados

Funcionamento	Método	Ponto final	Documentation
Gerar credencial de base de dados	`POST`	`/credentials`	Autenticação de token OAuth

Operações

Funcionamento	Método	Ponto final	Documentation
Comece a operar	`GET`	`/projects/{project_id}/operations/{operation_id}`	Ver exemplo abaixo

Permissões

As permissões ACL do projeto utilizam a API de permissões padrão do Azure Databricks, e não o /api/2.0/postgres/ caminho base. Defina o request_object_type para database-projects e request_object_id para o ID do projeto.

Funcionamento	Método	Ponto final	Documentation
Obtenha permissões de projeto	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	Referência da API de permissões
Atualizar permissões do projeto	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	Referência da API de permissões
Substituir permissões de projeto	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	Referência da API de permissões

Os níveis de autorização concedíveis para projetos Lakebase são CAN_USE e CAN_MANAGE. CAN_CREATE é um nível herdado e não pode ser definido através da API. Ver Níveis de permissões.

Para exemplos de utilização e equivalentes a CLI/SDK/Terraform, veja Conceder permissões programáticamente.

Entrar em operação

Verifique o estado de uma operação de longa duração pelo nome do seu recurso.

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

SDK de 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(...);
System.out.println("Operation started: " + operation.getName());

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

CLI

O CLI espera automaticamente que as operações sejam concluídas por padrão. Uso --no-wait para saltar votações:

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

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

encaracolar

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

Formato da resposta:

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

Campos:

done: false enquanto está em progresso, true quando concluído
response: Contém o resultado quando done é true
error: Contém detalhes de erro caso a operação tenha falhado

Padrões comuns

Nomenclatura de recursos

Os recursos seguem um padrão hierárquico de nomenclatura onde os recursos filhos são atribuídos ao seu progenitor.

Os projetos utilizam este formato:

projects/{project_id}

Recursos filhos, como operações, estão integrados no projeto principal:

projects/{project_id}/operations/{operation_id}

Isto significa que precisa do ID do projeto pai para aceder a operações ou outros recursos filhos.

IDs de Recursos:

Ao criar recursos, deve fornecer um ID de recurso (como my-app) para o project_id, branch_id, ou endpoint_id parâmetro. Este ID torna-se parte do caminho de recurso nas chamadas de API (como projects/my-app/branches/development).

Podes, opcionalmente, fornecer um display_name rótulo mais descritivo ao teu recurso. Se não especificar um nome de visualização, o sistema usa o seu ID de recurso como nome de visualização.

:::dica Encontrar recursos na interface do utilizador

Para localizar um projeto na interface do Lakebase, procure o seu nome de exibição na lista de projetos. Se não forneceu um nome de visualização personalizado ao criar o projeto, procure pelo seu project_id (como "my-app").

:::

Observação

Os IDs dos Recursos não podem ser alterados após a criação.

Requisitos:

Deve ter entre 1 e 63 caracteres
Apenas letras minúsculas, dígitos e hífens
Não pode começar nem terminar com um hífen
Exemplos: my-app, analytics-db, customer-123

Operações de longa duração (LROs)

As operações de criar, atualizar e eliminar devolvem um databricks.longrunning.Operation objeto que fornece um estado de conclusão.

Exemplo de resposta à operação:

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

Inquérito para conclusão usando o 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}")

SDK de Java

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

CLI

O CLI espera automaticamente que as operações sejam concluídas por padrão. Use --no-wait para devolver imediatamente:

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

encaracolar

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

Consulta a cada poucos segundos até done ser true.

Atualizar máscaras

As operações de atualização requerem um update_mask parâmetro que especifique quais os campos a modificar. Isto evita acidentalmente sobrescrever campos não relacionados.

Diferenças de formato:

Método	Formato	Example
API REST	Parâmetro de consulta	`?update_mask=spec.display_name`
Python SDK	Objeto FieldMask	`update_mask=FieldMask(field_mask=["spec.display_name"])`
CLI	Argumento posicional	`update-project NAME spec.display_name`

Tratamento de erros

A API do Lakebase devolve códigos de estado HTTP padrão.

409: Operações conflitantes

Mensagem de erro:

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

O que significa:

A Lakebase por vezes agenda operações internas de manutenção em projetos. Se um pedido de cliente chegar enquanto uma destas operações internas está em curso, o Lakebase pode rejeitar o novo pedido com um 409 Conflict erro.

Este é um comportamento esperado. Os clientes devem estar preparados para tentar novamente os pedidos quando este erro ocorrer.

O que fazer:

Repita o pedido. Quando a operação interna termina, a Lakebase aceita novos pedidos para o projeto.

Usa a política de recuo exponencial para novas tentativas: espera um curto intervalo antes da primeira repetição e, em seguida, duplica o tempo de espera a cada nova tentativa. Um intervalo inicial de 100 milissegundos com um máximo de 30 segundos é um padrão razoável.

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

encaracolar

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

Observação

A 409 Conflict num pedido API Lakebase significa que o pedido não foi aceite, não que tenha sido aplicado. Verifique sempre o estado do recurso após uma tentativa bem-sucedida, chamando o endpoint correspondente GET .

SDKs e infraestrutura como código

Comentários

Esta página foi útil?

Last updated on 2026-03-28

Partilhar via

Guia da API de Autoscaling do Lakebase

Authentication

Configurar a autenticação

Python SDK

SDK de Java

CLI

encaracolar

Endpoints disponíveis (Beta)

Projetos

Filiais

Endpoints (Computa e Lê Réplicas)

Papéis

Credenciais de Base de Dados

Operações

Permissões

Entrar em operação

Python SDK

SDK de Java

CLI

encaracolar

Padrões comuns

Nomenclatura de recursos

Operações de longa duração (LROs)

Python SDK

SDK de Java

CLI

encaracolar

Atualizar máscaras

Tratamento de erros

409: Operações conflitantes

Python SDK

encaracolar

SDKs e infraestrutura como código

Comentários

Recursos adicionais