Guia da API de Autoscaling do Lakebase

Importante

A Lakebase Autoscaling está em Beta nas seguintes regiões: eastus2, westeurope, westus.

O Autoscaling do Lakebase é a versão mais recente do Lakebase com computação automática, escala até zero, ramificação e restauração instantânea. Para comparação de funcionalidades com o Lakebase Provisioned, veja a escolha entre versões.

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

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): Use tokens LakeBase OAuth ou palavras-passe Postgres. Consulte Autenticação.
API de dados (HTTP RESTful): Utilize tokens LakeBase OAuth. 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

Branches

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`	Visualizar cálculos

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

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

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

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

Branches

Endpoints (Computa e Lê Réplicas)

Credenciais de Base de Dados

Operaçõ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

Recursos adicionais

SDKs e infraestrutura como código

Feedback

Recursos adicionais