Guia da API de Autoscaling do Lakebase

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.

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

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

Filiais

Endpoints (Computa e Lê Réplicas)

Papéis

Credenciais de Base de Dados

Operações

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.

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

:::

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:

SDKs e infraestrutura como código

• Python SDK
• SDK Java
• SDK Go
• Pacotes de Ativos da Databricks
• Gerir projetos Lakebase com Bundles
• Fornecedor Terraform
• Comece com o Terraform para a Lakebase