Partilhar via

API de Dados 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.

A API de Dados Lakebase é uma interface RESTful compatível com PostgREST que lhe permite interagir diretamente com a sua base de dados Lakebase Postgres usando métodos HTTP padrão. Oferece endpoints API derivados do esquema da sua base de dados, permitindo operações CRUD (Crear, Ler, Atualizar, Eliminar) seguras nos seus dados sem necessidade de desenvolvimento backend personalizado.

Visão geral

A API de Dados gera automaticamente endpoints RESTful com base no esquema da sua base de dados. Cada tabela na sua base de dados torna-se acessível através de pedidos HTTP, permitindo-lhe:

  • Consultar dados usando pedidos HTTP GET com filtragem, ordenação e paginação flexíveis
  • Inserir registos usando pedidos HTTP POST
  • Atualizar registos usando HTTP PATCH ou pedidos PUT
  • Eliminar registos usando pedidos HTTP DELETE
  • Executar funções como RPCs usando requisições HTTP POST

Esta abordagem elimina a necessidade de escrever e manter código API personalizado, permitindo-lhe focar-se na lógica da aplicação e no esquema da base de dados.

Compatibilidade PostgREST

A API de Dados Lakebase é compatível com a especificação PostgREST . É possível:

  • Utilizar bibliotecas e ferramentas clientes PostgREST existentes
  • Siga as convenções do PostgREST para filtragem, ordenação e paginação
  • Adaptar documentação e exemplos da comunidade PostgREST

Observação

A API de Dados Lakebase é a implementação do Azure Databricks, concebida para ser compatível com a especificação PostgREST. Como a API de dados é uma implementação independente, algumas funcionalidades do PostgREST que não são aplicáveis ao ambiente Lakebase não estão incluídas. Para detalhes sobre compatibilidade de funcionalidades, consulte Referência de compatibilidade de funcionalidades.

Para detalhes completos sobre funcionalidades da API, parâmetros de consulta e capacidades, consulte a referência da API PostgREST.

Casos de uso

A API de Dados Lakebase é ideal para:

  • Aplicações web: Construa frontends que interajam diretamente com a sua base de dados através de pedidos HTTP
  • Microserviços: Criar serviços leves que acedam a recursos de base de dados através de APIs REST
  • Arquiteturas Serverless: Integrar com funções serverless e plataformas de edge computing
  • Aplicações móveis: Fornecer aplicações móveis com acesso direto à base de dados através de uma interface RESTful
  • Integrações de terceiros: Permitir que sistemas externos leiam e escrevam dados de forma segura

Configurar a API de Dados

Esta secção orienta-o na configuração da Data API, desde a criação de funções obrigatórias até à realização do seu primeiro pedido de API.

Pré-requisitos

A API de Dados requer um projeto de base de dados Lakebase Postgres Autoscaling. Se não tiveres uma, vê Começar com projetos de bases de dados.

Sugestão

Se precisar de tabelas de exemplo para testar a Data API, crie-as antes de ativar a Data API. Consulte Esquema de exemplo para um esquema de exemplo completo.

Ativar a API de Dados

A API de Dados faz todo o acesso à base de dados através de um único papel Postgres chamado authenticator, que não requer permissões exceto para iniciar sessão. Quando ativa a API de Dados através da aplicação Lakebase, este papel e a infraestrutura necessária são criados automaticamente.

Para ativar a API de Dados:

  1. Navegue até à página da API de Dados no seu projeto.
  2. Clique em Ativar API de Dados.

Botão Ativar API de Dados

Isto executa automaticamente todos os passos de configuração, incluindo a criação da authenticator função, a configuração do pgrst esquema e a disponibilização do public esquema através da API.

Observação

Se precisar de expor esquemas adicionais (para além de public), pode modificar os esquemas expostos nas definições da Advanced Data API.

Após ativar a API de Dados

Depois de ativar a API de dados, a aplicação Lakebase mostra a página da API de dados com dois separadores: API e Definições.

Página API de dados que mostra URL da API e opções de segurança

O separador da API fornece:

  • URL da API: A URL do endpoint REST para usar no seu código de aplicação e nos pedidos da API. A URL apresentada não inclui o esquema, por isso deve adicionar o nome do esquema (por exemplo, /public) ao URL ao fazer pedidos de API.
  • Atualizar cache de esquema: Um botão para atualizar a cache de esquema da API depois de fazer alterações ao esquema da sua base de dados. Veja Atualizar a cache do esquema.
  • Proteja os seus dados: Opções para ativar a segurança ao nível de linha (RLS) do Postgres para as suas tabelas. Veja Ativar segurança ao nível da linha.

O separador Definições oferece opções para configurar o comportamento da API, como esquemas expostos, número máximo de linhas, definições de CORS e mais. Consulte Definições Avançadas da API de Dados.

Esquema de exemplo (opcional)

Os exemplos nesta documentação utilizam o seguinte esquema. Pode criar as suas próprias tabelas ou usar este esquema de exemplo para testes. Execute estas instruções SQL usando o Lakebase SQL Editor ou qualquer cliente SQL:

-- Create clients table
CREATE TABLE clients (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  company TEXT,
  phone TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create projects table with foreign key to clients
CREATE TABLE projects (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT,
  client_id INTEGER NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
  status TEXT DEFAULT 'active',
  start_date DATE,
  end_date DATE,
  budget DECIMAL(10,2),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create tasks table with foreign key to projects
CREATE TABLE tasks (
  id SERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  description TEXT,
  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  status TEXT DEFAULT 'pending',
  priority TEXT DEFAULT 'medium',
  assigned_to TEXT,
  due_date DATE,
  estimated_hours DECIMAL(5,2),
  actual_hours DECIMAL(5,2),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Insert sample data
INSERT INTO clients (name, email, company, phone) VALUES
  ('Acme Corp', 'contact@acme.com', 'Acme Corporation', '+1-555-0101'),
  ('TechStart Inc', 'hello@techstart.com', 'TechStart Inc', '+1-555-0102'),
  ('Global Solutions', 'info@globalsolutions.com', 'Global Solutions Ltd', '+1-555-0103');

INSERT INTO projects (name, description, client_id, status, start_date, end_date, budget) VALUES
  ('Website Redesign', 'Complete overhaul of company website with modern design', 1, 'active', '2024-01-15', '2024-06-30', 25000.00),
  ('Mobile App Development', 'iOS and Android app for customer management', 1, 'planning', '2024-07-01', '2024-12-31', 50000.00),
  ('Database Migration', 'Migrate legacy system to cloud database', 2, 'active', '2024-02-01', '2024-05-31', 15000.00),
  ('API Integration', 'Integrate third-party services with existing platform', 3, 'completed', '2023-11-01', '2024-01-31', 20000.00);

INSERT INTO tasks (title, description, project_id, status, priority, assigned_to, due_date, estimated_hours, actual_hours) VALUES
  ('Design Homepage', 'Create wireframes and mockups for homepage', 1, 'in_progress', 'high', 'Sarah Johnson', '2024-03-15', 16.00, 8.00),
  ('Setup Development Environment', 'Configure local development setup', 1, 'completed', 'medium', 'Mike Chen', '2024-02-01', 4.00, 3.50),
  ('Database Schema Design', 'Design new database structure', 3, 'completed', 'high', 'Alex Rodriguez', '2024-02-15', 20.00, 18.00),
  ('API Authentication', 'Implement OAuth2 authentication flow', 4, 'completed', 'high', 'Lisa Wang', '2024-01-15', 12.00, 10.50),
  ('User Testing', 'Conduct usability testing with target users', 1, 'pending', 'medium', 'Sarah Johnson', '2024-04-01', 8.00, NULL),
  ('Performance Optimization', 'Optimize database queries and caching', 3, 'in_progress', 'medium', 'Alex Rodriguez', '2024-04-30', 24.00, 12.00);

Configurar permissões de utilizador

Deve autenticar todas as requisições da API de Dados usando os tokens de acesso OAuth do Azure Databricks, que são enviados no cabeçalho Authorization. A API de dados restringe o acesso a identidades autenticadas do Azure Databricks, com o Postgres a governar as permissões subjacentes.

O authenticator papel assume a identidade do utilizador solicitante ao processar pedidos de API. Para que isto funcione, cada identidade Azure Databricks que acede à API de dados deve ter um papel Postgres correspondente na sua base de dados. Se precisar de adicionar utilizadores à sua conta Azure Databricks primeiro, veja Adicionar utilizadores à sua conta.

Adicionar funções do Postgres

Use a databricks_auth extensão para criar papéis Postgres que correspondam às identidades do Azure Databricks:

Crie a extensão:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Adicione uma função no Postgres:

SELECT databricks_create_role('user@databricks.com', 'USER');

Para instruções detalhadas, consulte Criar um papel OAuth para uma identidade Azure Databricks usando SQL.

Importante

Não uses a conta do proprietário da tua base de dados (a identidade Azure Databricks que criou o projeto Lakebase) para aceder à API de dados. A authenticator função exige a capacidade de assumir o seu cargo, e essa permissão não pode ser concedida para contas com privilégios elevados.

Se tentar atribuir o papel de proprietário da base de dados a authenticator, recebe este erro:

ERROR:  permission denied to grant role "db_owner_user@databricks.com"
DETAIL:  Only roles with the ADMIN option on role "db_owner_user@databricks.com" may grant this role.

Conceder permissões aos utilizadores

Agora que criou os papéis Postgres correspondentes para as suas identidades Azure Databricks, precisa de conceder permissões a esses papéis Postgres. Estas permissões controlam com que objetos da base de dados (esquemas, tabelas, sequências, funções) cada utilizador pode interagir através de pedidos de API.

Conceder permissões usando instruções SQL GRANT padrão. Este exemplo usa o public esquema; se estiveres a expor um esquema diferente, substitui public pelo nome do teu esquema:

-- Allow authenticator to assume the identity of the user
GRANT "user@databricks.com" TO authenticator;

-- Allow user@databricks.com to access everything in public schema
GRANT USAGE ON SCHEMA public TO "user@databricks.com";
GRANT SELECT, UPDATE, INSERT, DELETE ON ALL TABLES IN SCHEMA public TO "user@databricks.com";
GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO "user@databricks.com";
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO "user@databricks.com";

Este exemplo concede à identidade user@databricks.com acesso total ao esquema public. Substitua isto pela identidade real do Azure Databricks e ajuste as permissões de acordo com os seus requisitos.

Importante

Implementar segurança ao nível da linha: As permissões acima concedem acesso ao nível da tabela, mas a maioria dos casos de uso da API exige restrições ao nível da linha. Por exemplo, em aplicações multi-inquilino, os utilizadores devem ver apenas os seus próprios dados ou os dados da sua organização. Utilize políticas de segurança ao nível de linha (RLS) do PostgreSQL para impor um controlo de acesso detalhado ao nível da base de dados. Ver Implementar segurança ao nível da linha.

Autenticação

Para aceder à API de dados, deve fornecer um token Azure Databricks OAuth no Authorization cabeçalho do seu pedido HTTP. A identidade autenticada do Azure Databricks deve ter um papel Postgres correspondente (criado nos passos anteriores) que defina as permissões da base de dados.

Obtenha um token OAuth

Efetue a ligação ao seu espaço de trabalho como a identidade do Azure Databricks para a qual criou uma função do Postgres nos passos anteriores e obtenha um token OAuth. Consulte Autenticação para instruções.

Fazer um pedido

Com o seu token OAuth e URL da API (disponível no separador API na aplicação Lakebase), pode fazer pedidos API usando curl ou qualquer cliente HTTP. Lembre-se de adicionar o nome do esquema (por exemplo, /public) à URL da API. Os exemplos seguintes assumem que exportaste as variáveis de ambiente DBX_OAUTH_TOKEN e REST_ENDPOINT.

Aqui está uma chamada de exemplo com a saída esperada (usando o esquema de exemplos de clientes/projetos/tarefas):

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name,projects(id,name)&id=gte.2"

Resposta de exemplo:

[
  { "id": 2, "name": "TechStart Inc", "projects": [{ "id": 3, "name": "Database Migration" }] },
  { "id": 3, "name": "Global Solutions", "projects": [{ "id": 4, "name": "API Integration" }] }
]

Para mais exemplos e informações detalhadas sobre operações da API, consulte a secção de referência da API . Para detalhes completos sobre parâmetros de consulta e capacidades da API, consulte a referência da API PostgREST. Para informações específicas de compatibilidade do Lakebase, veja compatibilidade PostgREST.

Antes de usar a API extensivamente, configure a segurança ao nível da linha para proteger os seus dados.

Gerir a API de Dados

Depois de ativar a API de dados, pode gerir alterações de esquema e definições de segurança através da aplicação Lakebase.

Atualizar a cache do esquema

Quando faz alterações ao esquema da sua base de dados (adicionando tabelas, colunas ou outros objetos de esquema), precisa de atualizar a cache do esquema. Isto torna as suas alterações imediatamente disponíveis através da API de dados.

Para atualizar a cache do esquema:

  1. Navegue para API de Dados na secção Backend da Aplicação do seu projeto.
  2. Clique em atualizar cache do esquema.

A API de Dados agora reflete as suas últimas alterações de esquema.

Ativar a segurança ao nível das linhas

A aplicação Lakebase oferece uma forma rápida de ativar a segurança ao nível da linha (RLS) para tabelas na sua base de dados. Quando existem tabelas no seu esquema, o separador da API mostra uma secção Proteger os seus dados que mostra:

  • Tabelas com RLS ativado
  • Tabelas com RLS desativado (com avisos)
  • Um botão Ativar RLS para ativar RLS em todas as tabelas

Importante

Ativar o RLS através da aplicação Lakebase ativa a segurança ao nível das linhas para as suas tabelas. Quando o RLS está ativado, todas as linhas tornam-se inacessíveis aos utilizadores por defeito (exceto os proprietários das tabelas, os papéis com o atributo BYPASSRLS e os superutilizadores — embora os superutilizadores não sejam suportados no Lakebase). Deve criar políticas RLS para conceder acesso a linhas específicas com base nos seus requisitos de segurança. Consulte Segurança ao nível das linhas para informações sobre a criação de políticas.

Para ativar o RLS nas suas tabelas:

  1. Navegue até a API de Dados na seção Backend da Aplicação do seu projeto.
  2. Na secção Proteger os seus dados , reveja as tabelas que não têm RLS ativado.
  3. Clique em Ativar RLS para ativar a segurança ao nível das linhas para todas as tabelas.

Também pode ativar o RLS para tabelas individuais usando SQL. Consulte Segurança ao nível de linha para mais detalhes.

Definições avançadas da API de Dados

A secção de definições avançadas no separador da API na aplicação Lakebase controla a segurança, o desempenho e o comportamento do endpoint da sua API de dados.

Esquemas expostos

Padrão:public

Define quais os esquemas PostgreSQL expostos como endpoints da API REST. Por defeito, apenas o public esquema está acessível. Se utilizar outros esquemas (por exemplo, api, v1), selecione-os na lista suspensa para os adicionar.

Observação

Aplicam-se permissões: Adicionar um esquema aqui expõe os endpoints, mas o papel de base de dados usado pela API deve continuar a ter USAGE privilégios sobre o esquema e SELECT privilégios nas tabelas.

Máximo de linhas

Padrão: Vazio

Impõe um limite rígido ao número de linhas a devolver numa única resposta da API. Isto previne degradação acidental do desempenho devido a consultas grandes. Os clientes devem usar limites de paginação para recuperar dados dentro deste limite. Isto também evita custos inesperados de saída devido a grandes transferências de dados.

Origens permitidas pelo CORS

Padrão: Vazio (Permite todas as origens)

Controla quais domínios web podem obter dados da sua API através de um navegador.

  • Vazio: Permite * (qualquer domínio). Útil para desenvolvimento.
  • Produção: Liste os seus domínios específicos (por exemplo, https://myapp.com) para evitar que sites não autorizados consultem a sua API.

Especificação de OpenAPI

Padrão: Desativado

Controla se um esquema OpenAPI 3 gerado automaticamente está disponível em /openapi.json. Este esquema descreve as tuas tabelas, colunas e endpoints REST. Quando ativado, pode usá-lo para:

  • Gerar documentação de API (Swagger UI, Redoc)
  • Construir bibliotecas clientes tipadas (TypeScript, Python, Go)
  • Importa a tua API para o Postman
  • Integrar com gateways de API e outras ferramentas baseadas em OpenAPI

Cabeçalhos de temporização do servidor

Padrão: Desativado

Quando ativada, a API de Dados inclui Server-Timing cabeçalhos em cada resposta. Estes cabeçalhos mostram quanto tempo diferentes partes do pedido demoraram a ser processadas (por exemplo, tempo de execução da base de dados e tempo de processamento interno). Pode usar esta informação para depurar consultas lentas, medir o desempenho e resolver problemas de latência na sua aplicação.

Observação

Depois de fazer alterações a quaisquer definições avançadas, clique em Guardar para as aplicar.

Segurança ao nível das linhas

As políticas de segurança ao nível das linhas (RLS) fornecem controlo de acesso detalhado ao restringir quais linhas os utilizadores podem aceder numa tabela.

Como o RLS funciona com a API de dados: Quando um utilizador faz um pedido de API, o authenticator papel assume a identidade desse utilizador. Quaisquer políticas RLS definidas para o papel desse utilizador são automaticamente aplicadas pelo PostgreSQL, filtrando os dados a que podem aceder. Isto acontece ao nível da base de dados, por isso, mesmo que o código da aplicação tente consultar todas as linhas, a base de dados só devolve as linhas que o utilizador pode ver. Isto proporciona segurança de defesa aprofundada sem exigir lógica de filtragem no código da sua aplicação.

Porque é que o RLS é fundamental para APIs: Ao contrário das ligações diretas a bases de dados, onde controla o contexto da ligação, as APIs HTTP expõem a sua base de dados a múltiplos utilizadores através de um único endpoint. As permissões ao nível da tabela significam que, se um utilizador conseguir aceder à clients tabela, pode aceder a todos os registos do cliente, a menos que implemente filtragem. As políticas RLS garantem que cada utilizador veja automaticamente apenas os seus dados autorizados.

O RLS é essencial para:

  • Aplicações multi-tenant: Isolamento de dados entre diferentes clientes ou organizações
  • Dados pertencentes aos utilizadores: Garantir que os utilizadores acedam apenas aos seus próprios registos
  • Acesso baseado em equipa: Limitar a visibilidade aos membros da equipa ou a grupos específicos
  • Requisitos de conformidade: Aplicar restrições de acesso a dados ao nível da base de dados

Ativar RLS

Pode ativar o RLS através da aplicação Lakebase ou usando instruções SQL. Para instruções sobre como usar a aplicação Lakebase, consulte Ativar segurança ao nível da linha.

Advertência

Se tiver tabelas sem RLS ativado, o separador da API na aplicação Lakebase mostra um aviso de que os utilizadores autenticados podem ver todas as linhas dessas tabelas. A API de Dados interage diretamente com o seu esquema Postgres e, como a API é acessível pela internet, é crucial impor a segurança ao nível da base de dados usando a segurança ao nível das linhas do PostgreSQL.

Para ativar o RLS usando SQL, execute o seguinte comando:

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Criar políticas RLS

Depois de ativar o RLS numa tabela, deve criar políticas que definam regras de acesso. Sem políticas, os utilizadores não podem aceder a nenhuma linha (todas as linhas estão ocultas por defeito).

Como funcionam as políticas: Quando o RLS está ativado numa tabela, os utilizadores só podem ver linhas que correspondem a pelo menos uma política. Todas as outras linhas são filtradas. Os proprietários das tabelas, as funções com o atributo BYPASSRLS e os superusuários podem contornar o sistema de segurança por linhas (embora não sejam suportados no Lakebase).

Observação

No Lakebase, current_user devolve o endereço de email do utilizador autenticado (por exemplo, user@databricks.com). Use isto nas suas políticas RLS para identificar qual o utilizador que está a fazer o pedido.

Sintaxe básica de políticas:

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • policy_name: Um nome descritivo para a apólice
  • table_name: A tabela em que aplicar a política
  • PARA role_name: Opcional. Especifica o papel desta política. Omita esta cláusula para aplicar a política a todos os cargos.
  • USING (condição): A condição que determina quais linhas estão visíveis

Tutorial de RLS

O tutorial seguinte utiliza o esquema de exemplo desta documentação (clientes, projetos, tabelas de tarefas) para mostrar como implementar segurança ao nível das linhas.

Cenário: Há vários utilizadores que devem ver apenas os seus clientes atribuídos e os projetos relacionados. Restringa o acesso para que:

  • alice@databricks.com Só pode ver clientes com IDs 1 e 2
  • bob@databricks.com Só consegue ver clientes com IDs 2 e 3

Passo 1: Ativar o RLS na tabela do cliente

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Passo 2: Criar uma política para a Alice

CREATE POLICY alice_clients ON clients
  TO "alice@databricks.com"
  USING (id IN (1, 2));

Passo 3: Criar uma política para o Bob

CREATE POLICY bob_clients ON clients
  TO "bob@databricks.com"
  USING (id IN (2, 3));

Passo 4: Teste as políticas

Quando a Alice faz um pedido de API:

# Alice's token in the Authorization header
curl -H "Authorization: Bearer $ALICE_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name"

Resposta (a Alice só atende os clientes 1 e 2):

[
  { "id": 1, "name": "Acme Corp" },
  { "id": 2, "name": "TechStart Inc" }
]

Quando o Bob faz um pedido de API:

# Bob's token in the Authorization header
curl -H "Authorization: Bearer $BOB_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name"

Resposta (Bob só vê os clientes 2 e 3):

[
  { "id": 2, "name": "TechStart Inc" },
  { "id": 3, "name": "Global Solutions" }
]

Padrões comuns do RLS

Estes padrões cobrem os requisitos típicos de segurança para a Data API:

Propriedade do utilizador - Restringe linhas ao utilizador autenticado:

CREATE POLICY user_owned_data ON tasks
  USING (assigned_to = current_user);

Isolamento de locatário - Restringe as linhas à organização do utilizador:

CREATE POLICY tenant_data ON clients
  USING (tenant_id = (
    SELECT tenant_id
    FROM user_tenants
    WHERE user_email = current_user
  ));

Adesão à equipa - Restringe as linhas às equipas do utilizador:

CREATE POLICY team_projects ON projects
  USING (client_id IN (
    SELECT client_id
    FROM team_clients
    WHERE team_id IN (
      SELECT team_id
      FROM user_teams
      WHERE user_email = current_user
    )
  ));

Acesso baseado em funções - Restringe as linhas com base na pertença à função:

CREATE POLICY manager_access ON tasks
  USING (
    status = 'pending' OR
    pg_has_role(current_user, 'managers', 'member')
  );

Apenas leitura para funções específicas - Políticas diferentes para diferentes operações:

-- Allow all users to read their assigned tasks
CREATE POLICY read_assigned_tasks ON tasks
  FOR SELECT
  USING (assigned_to = current_user);

-- Only managers can update tasks
CREATE POLICY update_tasks ON tasks
  FOR UPDATE
  TO "managers"
  USING (true);

Recursos adicionais

Para informações abrangentes sobre a implementação do RLS, incluindo tipos de políticas, melhores práticas de segurança e padrões avançados, consulte a documentação de Políticas de Segurança PostgreSQL Row.

Para mais informações sobre permissões, consulte Gerir permissões.

Referência da API

Esta secção assume que completou os passos de configuração, configurou permissões e implementou segurança ao nível da linha. As secções seguintes fornecem informações de referência para a utilização da API de dados, incluindo operações comuns, funcionalidades avançadas, considerações de segurança e detalhes de compatibilidade.

Operações básicas

Registos de consulta

Recuperar registos de uma tabela usando HTTP GET:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients"

Resposta de exemplo:

[
  { "id": 1, "name": "Acme Corp", "email": "contact@acme.com", "company": "Acme Corporation", "phone": "+1-555-0101" },
  {
    "id": 2,
    "name": "TechStart Inc",
    "email": "hello@techstart.com",
    "company": "TechStart Inc",
    "phone": "+1-555-0102"
  }
]

Filtrar resultados

Use parâmetros de consulta para filtrar resultados. Este exemplo recupera clientes com id maior ou igual a 2:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?id=gte.2"

Resposta de exemplo:

[
  { "id": 2, "name": "TechStart Inc", "email": "hello@techstart.com" },
  { "id": 3, "name": "Global Solutions", "email": "info@globalsolutions.com" }
]

Selecione colunas específicas e junte tabelas

Use o select parâmetro para recuperar colunas específicas e juntar tabelas relacionadas:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?select=id,name,projects(id,name)&id=gte.2"

Resposta de exemplo:

[
  { "id": 2, "name": "TechStart Inc", "projects": [{ "id": 3, "name": "Database Migration" }] },
  { "id": 3, "name": "Global Solutions", "projects": [{ "id": 4, "name": "API Integration" }] }
]

Inserir registos

Crie novos registos usando HTTP POST:

curl -X POST \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Client",
    "email": "newclient@example.com",
    "company": "New Company Inc",
    "phone": "+1-555-0104"
  }' \
  "$REST_ENDPOINT/public/clients"

Registos de atualizações

Atualizar registos existentes usando HTTP PATCH:

curl -X PATCH \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1-555-0199"}' \
  "$REST_ENDPOINT/public/clients?id=eq.1"

Excluir registros

Eliminar registos usando HTTP DELETE:

curl -X DELETE \
  -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/clients?id=eq.5"

Funcionalidades avançadas

Paginação

Controla o número de registos devolvidos utilizando os parâmetros limit e offset.

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?limit=10&offset=0"

Classificação

Ordene os resultados usando o order parâmetro:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?order=due_date.desc"

Filtragem complexa

Combine múltiplas condições de filtro:

curl -H "Authorization: Bearer $DBX_OAUTH_TOKEN" \
  "$REST_ENDPOINT/public/tasks?status=eq.in_progress&priority=eq.high"

Operadores de filtro comuns:

  • eq - igual a
  • gte - maior que ou igual a
  • lte - menor ou igual
  • neq - não é igual
  • like - correspondência de padrões
  • in - corresponde a qualquer valor na lista

Para mais informações sobre parâmetros de consulta suportados e funcionalidades da API, consulte a referência da API PostgREST. Para informações específicas de compatibilidade do Lakebase, veja compatibilidade PostgREST.

Referência de compatibilidade de funcionalidades

Esta secção lista funcionalidades do PostgREST que apresentam comportamentos diferentes ou que não são suportadas na API de Dados do Lakebase.

Autenticação e autorização

Característica Situação Detalhes
Configuração JWT Não aplicável A API de Dados Lakebase utiliza tokens OAuth do Azure Databricks em vez de autenticação JWT. As opções de configuração específicas do JWT (segredos personalizados, chaves RS256, validação de audiência) não estão disponíveis.

Incorporação de recursos

Característica Situação Detalhes
Relações computadas Não suportado Relações personalizadas definidas através de funções de base de dados que retornam SETOF ou registos únicos não são suportadas. Apenas podem ser incorporadas relações de chave estrangeiras.
Embedding de junção interna (!inner dica) Não suportado A !inner dica que converte left joins em inner joins para filtrar linhas principais com base nos critérios dos filhos não é suportada. Exemplo: ?select=*,clients!inner(*)&clients.id=eq.1

Formatos de resposta

Característica Situação Detalhes
Manipuladores personalizados de tipos de media Não suportado Formatos de saída personalizados através de agregados PostgreSQL (formatos binários, XML, buffers de protocolo) não são suportados.
Nulos removidos Não suportado O nulls=stripped parâmetro de tipo media que remove campos nulos das respostas JSON não é suportado. Exemplo: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON Parcialmente suportado As colunas de geometria PostGIS podem ser consultadas, mas a formatação automática GeoJSON via Accept: application/geo+json no cabeçalho não está disponível.

Paginação e contagem

Característica Situação Detalhes
Contagem planeada Não suportado A Prefer: count=planned opção que utiliza o planeador de consultas do PostgreSQL para estimar contagens de resultados não é suportada. Utilize Prefer: count=exact em substituição.
Contagem estimada Não suportado A Prefer: count=estimated opção que utiliza estatísticas PostgreSQL para contagens aproximadas não é suportada. Utilize Prefer: count=exact em substituição.

Preferências de pedido

Característica Situação Detalhes
Preferência de fuso horário Parcialmente suportado A gestão do fuso horário existe, mas o Prefer: timezone=America/Los_Angeles cabeçalho para sobrepor o fuso horário do servidor não é suportado. Configure o fuso horário do servidor ou utilize funções de fuso horário ao nível da base de dados.
Controlo de transações Não suportado O controlo de transação via cabeçalho Prefer: tx=commit e Prefer: tx=rollback não é suportado.
Modos de tratamento por preferência Não suportado As Prefer: handling=strict opções e Prefer: handling=lenient para controlar como as preferências inválidas são tratadas não são suportadas.

Observability

A API Lakebase Data implementa as suas próprias funcionalidades de observabilidade. As seguintes funcionalidades de observabilidade do PostgREST não são suportadas:

Característica Situação Detalhes
Exposição ao plano de consulta Não suportado O Accept: application/vnd.pgrst.plan+json cabeçalho que expõe a saída do PostgreSQL EXPLAIN para análise de desempenho não é suportado.
Server-Timing cabeçalho Não suportado O cabeçalho Server-Timing que fornece a divisão do tempo dos pedidos não é suportado. O Lakebase implementa as suas próprias características de observabilidade.
Propagação do cabeçalho de rastreio Não suportado A propagação do cabeçalho X-Request-Id e de cabeçalhos de rastreio personalizados para rastreamento distribuído não é suportada. O Lakebase implementa as suas próprias características de observabilidade.

Configuração avançada

Característica Situação Detalhes
Definições de aplicação (GUCs) Não suportado Não é suportado passar valores de configuração personalizados para funções de base de dados através de GUCs PostgreSQL.
Função pré-requisição Não suportado A db-pre-request configuração que permite especificar a execução de uma função de base de dados antes de cada pedido não é suportada.

Para mais informações sobre as funcionalidades do PostgREST, consulte a documentação do PostgREST.

Considerações de segurança

A API de Dados reforça o modelo de segurança da sua base de dados em vários níveis:

  • Autenticação: Todos os pedidos requerem autenticação válida do token OAuth
  • Acesso baseado em funções: Permissões ao nível da base de dados controlam quais tabelas e operações os utilizadores podem aceder
  • Segurança ao nível das linhas: As políticas RLS aplicam controlos de acesso detalhados, restringindo quais as linhas específicas que os utilizadores podem ver ou modificar
  • Contexto do utilizador: A API assume a identidade do utilizador autenticado, garantindo que as permissões e políticas da base de dados se aplicam corretamente

Para implementações em produção:

  1. Implementar segurança ao nível da linha: Utilizar políticas RLS para restringir o acesso aos dados ao nível da linha. Isto é especialmente importante para aplicações multi-inquilinos e dados pertencentes aos utilizadores. Consulte segurança a nível de linha.
  2. Conceder permissões mínimas: Conceder apenas as permissões de que os utilizadores precisam (SELECT, INSERT, UPDATE, DELETE) em tabelas específicas, em vez de conceder acesso amplo.
  3. Use papéis separados por aplicação: Crie papéis dedicados para diferentes aplicações ou serviços em vez de partilhar um único papel.
  4. Audite o acesso regularmente: Revise periodicamente as permissões concedidas e as políticas RLS para garantir que correspondem aos seus requisitos de segurança.

Para informações sobre gestão de funções e permissões, veja:

  • Last updated on