Compartir vía

Api de datos de Lakebase

Importante

El escalado automático de Lakebase está en Beta en las siguientes regiones: eastus2, westeurope, westus.

El escalado automático de Lakebase es la versión más reciente de Lakebase con proceso de escalado automático, escalado a cero, bifurcación y restauración instantánea. Para ver la comparación de características con Lakebase Provisioned, consulte Elección entre versiones.

Lakebase Data API es una interfaz RESTful compatible con PostgREST que permite interactuar directamente con la base de datos de Lakebase Postgres mediante métodos HTTP estándar. Ofrece puntos de conexión de API derivados del esquema de la base de datos, lo que permite operaciones CRUD seguras (Crear, Leer, Actualizar, Eliminar) en los datos sin necesidad de desarrollo de back-end personalizado.

Información general

Data API genera automáticamente puntos de conexión RESTful en función del esquema de la base de datos. Cada tabla de la base de datos es accesible a través de solicitudes HTTP, lo que le permite:

  • Consulta de datos mediante solicitudes HTTP GET con filtrado flexible, ordenación y paginación
  • Insertar registros mediante solicitudes HTTP POST
  • Actualización de registros mediante solicitudes HTTP PATCH o PUT
  • Eliminación de registros mediante solicitudes HTTP DELETE
  • Ejecución de funciones como RPC mediante solicitudes HTTP POST

Este enfoque elimina la necesidad de escribir y mantener código de API personalizado, lo que le permite centrarse en la lógica de la aplicación y el esquema de la base de datos.

Compatibilidad con PostgREST

La API de datos de Lakebase es compatible con la especificación PostgREST . Ustedes pueden:

  • Uso de las herramientas y bibliotecas cliente postgREST existentes
  • Siga las convenciones postgREST para filtrar, ordenar y paginar
  • Adaptar la documentación y ejemplos de la comunidad PostgREST

Nota:

Lakebase Data API es la implementación de Azure Databricks diseñada para ser compatible con la especificación PostgREST. Dado que Data API es una implementación independiente, no se incluyen algunas características de PostgREST que no son aplicables al entorno de Lakebase. Para obtener más información sobre la compatibilidad de características, consulte Referencia de compatibilidad de características.

Para obtener detalles completos sobre las características de api, los parámetros de consulta y las funcionalidades, consulte la referencia de la API PostgREST.

Casos de uso

La API de datos de Lakebase es ideal para:

  • Aplicaciones web: cree front-ends que interactúen directamente con la base de datos a través de solicitudes HTTP.
  • Microservicios: creación de servicios ligeros que acceden a los recursos de base de datos a través de las API REST
  • Arquitecturas sin servidor: integración con funciones sin servidor y plataformas informáticas perimetrales
  • Aplicaciones móviles: proporcionar a las aplicaciones móviles acceso directo a la base de datos a través de una interfaz RESTful
  • Integraciones de terceros: habilitar sistemas externos para leer y escribir datos de forma segura

Configuración de Data API

Esta sección le guía a través de la configuración de Data API, desde la creación de roles necesarios para realizar la primera solicitud de API.

Prerrequisitos

Data API requiere un proyecto de base de datos de escalado automático de Postgres de Lakebase. Si no tiene una, consulte Introducción a los proyectos de base de datos.

Sugerencia

Si necesita tablas de ejemplo para probar data API, créelas antes de habilitar Data API. Consulte Esquema de ejemplo para obtener un esquema de ejemplo completo.

Habilitación de Data API

Data API hace que todas las bases de datos accedan a través de un único rol de Postgres denominado authenticator, que no requiere permisos excepto para iniciar sesión. Al habilitar Data API a través de la aplicación Lakebase, este rol y la infraestructura necesaria se crean automáticamente.

Para habilitar la API de datos:

  1. Vaya a la página Data API del proyecto.
  2. Haga clic en Habilitar DATA API.

Botón Habilitar API de datos

Esto realiza automáticamente todos los pasos de configuración, incluida la creación del authenticator rol, la configuración del pgrst esquema y la exposición del public esquema a través de la API.

Nota:

Si necesita exponer esquemas adicionales (más allá de public), puede modificar los esquemas expuestos en la configuración avanzada de la API de datos.

Después de habilitar Data API

Después de habilitar Data API, la aplicación Lakebase muestra la página Data API con dos pestañas: API y Configuración.

Página api de datos que muestra las opciones de seguridad y dirección URL de API

La pestaña API proporciona:

  • DIRECCIÓN URL de LA API: la dirección URL del punto de conexión de REST que se usará en el código de la aplicación y las solicitudes de API. La dirección URL que se muestra no incluye el esquema, por lo que debe anexar el nombre del esquema (por ejemplo, /public) a la dirección URL al realizar solicitudes de API.
  • Actualizar caché de esquemas: un botón para actualizar la caché de esquemas de la API después de realizar cambios en el esquema de la base de datos. Consulte Actualizar caché de esquemas.
  • Proteger los datos: opciones para habilitar la seguridad de nivel de fila (RLS) de Postgres para las tablas. Consulte Habilitación de la seguridad de nivel de fila.

La pestaña Configuración proporciona opciones para configurar el comportamiento de la API, como esquemas expuestos, filas máximas, configuración de CORS, etc. Consulte Configuración avanzada de La API de datos.

Esquema de ejemplo (opcional)

En los ejemplos de esta documentación se usa el esquema siguiente. Puede crear sus propias tablas o usar este esquema de ejemplo para realizar pruebas. Ejecute estas instrucciones SQL mediante el Editor sql de Lakebase o cualquier 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);

Configuración de permisos de usuario

Debe autenticar todas las solicitudes de Data API mediante tokens de autenticación de OAuth de Azure Databricks, enviados por el encabezado Authorization. Data API restringe el acceso a identidades de Azure Databricks autenticadas, con Postgres que rige los permisos subyacentes.

El authenticator rol asume la identidad del usuario solicitante al procesar solicitudes de API. Para que esto funcione, cada identidad de Azure Databricks que tenga acceso a Data API debe tener un rol de Postgres correspondiente en la base de datos. Si primero necesita agregar usuarios a su cuenta de Azure Databricks, consulte Incorporación de usuarios a su cuenta.

Adición de roles de Postgres

Use la databricks_auth extensión para crear roles de Postgres que correspondan a identidades de Azure Databricks:

Cree la extensión:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Agregue un rol de Postgres:

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

Para obtener instrucciones detalladas, consulte Creación de un rol de OAuth para una identidad de Azure Databricks mediante SQL.

Importante

No use la cuenta de propietario de la base de datos (la identidad de Azure Databricks que creó el proyecto Lakebase) para acceder a la API de Datos. El authenticator rol requiere la capacidad de asumir el rol y ese permiso no se puede conceder para las cuentas con privilegios elevados.

Si intenta conceder el rol de propietario de la base de datos a authenticator, recibirá este error:

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.

Concesión de permisos a los usuarios

Ahora que ha creado los roles de Postgres correspondientes para las identidades de Azure Databricks, debe conceder permisos a esos roles de Postgres. Estos permisos controlan con qué objetos de base de datos (esquemas, tablas, secuencias, funciones) cada usuario puede interactuar a través de solicitudes de API.

Conceda permisos mediante instrucciones SQL GRANT estándar. En este ejemplo se usa el public esquema; si expone un esquema diferente, reemplace por public el nombre del 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";

En este ejemplo se concede acceso completo al esquema public para la identidad user@databricks.com. Reemplace esto por la identidad real de Azure Databricks y ajuste los permisos en función de sus requisitos.

Importante

Implementar la seguridad de nivel de fila: los permisos anteriores conceden acceso de nivel de tabla, pero la mayoría de los casos de uso de api requieren restricciones de nivel de fila. Por ejemplo, en aplicaciones multiinquilino, los usuarios solo deben ver sus propios datos o los datos de su organización. Use directivas de seguridad de nivel de fila (RLS) de PostgreSQL para aplicar el control de acceso específico en el nivel de base de datos. Consulte Implementar la seguridad a nivel de fila.

Autenticación

Para acceder a la Data API, debe proporcionar un token OAuth de Azure Databricks en el encabezado de la solicitud HTTP Authorization. La identidad autenticada de Azure Databricks debe tener un rol de Postgres correspondiente (creado en los pasos anteriores) que defina sus permisos de base de datos.

Obtención de un token de OAuth

Conéctese a su área de trabajo con la identidad de Azure Databricks para la cual creó un rol de Postgres en los pasos anteriores, y obtenga un token OAuth. Consulte Autenticación para obtener instrucciones.

Realización de una solicitud

Con el token de OAuth y la dirección URL de API (disponible en la pestaña API de la aplicación Lakebase), puede realizar solicitudes de API mediante curl o cualquier cliente HTTP. Recuerde anexar el nombre del esquema (por ejemplo, /public) a la dirección URL de la API. En los ejemplos siguientes se supone que ha exportado las DBX_OAUTH_TOKEN variables de entorno y REST_ENDPOINT .

Aquí tienes una llamada de ejemplo con la salida esperada (usando el esquema de clientes/proyectos/tareas de ejemplo):

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

Respuesta de ejemplo:

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

Para obtener más ejemplos e información detallada sobre las operaciones de API, consulte la sección Referencia de API . Para más información sobre los parámetros de consulta y las funcionalidades de API, consulte la referencia de la API postgREST. Para obtener información de compatibilidad específica de Lakebase, consulte Compatibilidad de PostgREST.

Antes de usar la API ampliamente, configure la seguridad de nivel de fila para proteger los datos.

Administración de la API de datos

Después de habilitar Data API, puede administrar los cambios de esquema y la configuración de seguridad a través de la aplicación Lakebase.

Actualizar caché de esquemas

Al realizar cambios en el esquema de la base de datos (agregar tablas, columnas u otros objetos de esquema), debe actualizar la caché de esquemas. Esto hace que los cambios estén disponibles inmediatamente a través de Data API.

Para actualizar la caché de esquemas:

  1. Vaya a Data API en la sección Back-end de la aplicación del proyecto.
  2. Haga clic en Actualizar caché de esquemas.

Data API ahora refleja los cambios de esquema más recientes.

Habilita la seguridad a nivel de fila

La aplicación Lakebase proporciona una manera rápida de habilitar la seguridad de nivel de fila (RLS) para las tablas de la base de datos. Cuando existen tablas en el esquema, la pestaña API muestra una sección Proteger los datos que muestra:

  • Tablas con RLS habilitado
  • Tablas con RLS desactivado (con advertencias)
  • Un botón Habilitar RLS para habilitar RLS para todas las tablas

Importante

Al habilitar RLS a través de la aplicación Lakebase, se activa la seguridad de nivel de fila para las tablas. Cuando se habilita RLS, todas las filas se vuelven inaccesibles a los usuarios de forma predeterminada (excepto para los propietarios de tablas, los roles con el atributo BYPASSRLS y los superusuarios, aunque los superusuarios no son compatibles con Lakebase). Debe crear directivas de seguridad a nivel de fila (RLS) para conceder acceso a filas específicas en función de sus requisitos de seguridad. Consulte Seguridad de nivel de fila para obtener información sobre cómo crear directivas.

Para habilitar RLS para las tablas:

  1. Vaya a Data API en la sección Back-end de la aplicación del proyecto.
  2. En la sección Proteger los datos , revise las tablas que no tienen habilitado RLS.
  3. Haga clic en Habilitar RLS para habilitar la seguridad de nivel de fila para todas las tablas.

También puede habilitar RLS para tablas individuales mediante SQL. Consulte Seguridad de nivel de fila para obtener más información.

Configuración avanzada de La API de datos

La sección Configuración avanzada de la pestaña API de la aplicación Lakebase controla la seguridad, el rendimiento y el comportamiento del punto de conexión de Data API.

Esquemas expuestos

Predeterminado:public

Define qué esquemas de PostgreSQL se exponen como puntos de conexión de la API REST. De forma predeterminada, solo se puede acceder al public esquema. Si usa otros esquemas (por ejemplo, api, v1), selecciónelos en la lista desplegable para agregarlos.

Nota:

Se aplican permisos: Al agregar un esquema aquí se exponen los puntos de conexión, pero el rol de base de datos usado por la API debe tener USAGE privilegios en el esquema y SELECT privilegios en las tablas.

Número máximo de filas

Predeterminado: Vacío

Aplica un límite estricto en el número de filas que se devuelven en una única respuesta de API. Esto evita una degradación accidental en el rendimiento de las consultas grandes. Los clientes deben usar límites de paginación para recuperar datos dentro de este umbral. Esto también evita costos de salida inesperados de transferencias de datos de gran tamaño.

Orígenes permitidos de CORS

Valor predeterminado: Vacío (permite todos los orígenes)

Controla qué dominios web pueden capturar datos de la API mediante un explorador.

  • Vacío: Permite * (cualquier dominio). Útil para el desarrollo.
  • Producción: Enumere los dominios específicos (por ejemplo, https://myapp.com) para evitar que sitios web no autorizados consulten la API.

Especificación de OpenAPI

Predeterminado: Deshabilitado

Controla si un esquema openAPI 3 generado automáticamente está disponible en /openapi.json. Este esquema describe las tablas, las columnas y los puntos de conexión REST. Cuando está habilitado, puede usarlo para:

  • Generación de documentación de API (interfaz de usuario de Swagger, Redoc)
  • Desarrollar bibliotecas cliente tipadas (TypeScript, Python, Go)
  • Importación de la API en Postman
  • Integración con puertas de enlace de API y otras herramientas basadas en OpenAPI

Encabezados temporales del servidor

Predeterminado: Deshabilitado

Cuando está habilitada, la Data API incluye Server-Timing encabezados en cada respuesta. Estos encabezados muestran cuánto tiempo tardaron diferentes partes de la solicitud en procesarse (por ejemplo, tiempo de ejecución de la base de datos y tiempo de procesamiento interno). Puede usar esta información para depurar consultas lentas, medir el rendimiento y solucionar problemas de latencia en la aplicación.

Nota:

Después de realizar cambios en cualquier configuración avanzada, haga clic en Guardar para aplicarlos.

Seguridad a nivel de fila

Las directivas de seguridad de nivel de fila (RLS) proporcionan un control de acceso específico mediante la restricción de las filas a las que los usuarios pueden acceder en una tabla.

Funcionamiento de RLS con Data API: cuando un usuario realiza una solicitud de API, el authenticator rol asume la identidad del usuario. Las directivas de RLS definidas para el rol de ese usuario se aplican automáticamente mediante PostgreSQL, filtrando los datos a los que pueden acceder. Esto sucede en el nivel de base de datos, por lo que incluso si el código de aplicación intenta consultar todas las filas, la base de datos solo devuelve las filas que el usuario puede ver. Esto proporciona seguridad de defensa en profundidad sin necesidad de filtrar la lógica en el código de la aplicación.

Por qué RLS es fundamental para las API: a diferencia de las conexiones directas de base de datos en las que se controla el contexto de conexión, las API HTTP exponen la base de datos a varios usuarios a través de un único punto de conexión. Los permisos de nivel de tabla solo significan que si un usuario puede acceder a la clients tabla, puede acceder a todos los registros de cliente a menos que implemente el filtrado. Las directivas de RLS garantizan que cada usuario vea automáticamente solo sus datos autorizados.

RLS es esencial para:

  • Aplicaciones multiarrendatario: Aislar datos entre diferentes clientes u organizaciones
  • Datos propiedad del usuario: asegúrese de que los usuarios solo acceden a sus propios registros.
  • Acceso basado en equipo: limitar la visibilidad a los miembros del equipo o grupos específicos
  • Requisitos de cumplimiento: exigir restricciones de acceso a datos en el nivel de base de datos

Habilitación de RLS

Puede habilitar RLS a través de la aplicación Lakebase o mediante instrucciones SQL. Para obtener instrucciones sobre cómo usar la aplicación Lakebase, consulte Habilitación de la seguridad de nivel de fila.

Advertencia

Si tiene tablas sin RLS habilitadas, la pestaña API de la aplicación Lakebase muestra una advertencia que los usuarios autenticados pueden ver todas las filas de esas tablas. Data API interactúa directamente con el esquema de Postgres y, dado que la API es accesible a través de Internet, es fundamental aplicar la seguridad en el nivel de base de datos mediante la seguridad de nivel de fila de PostgreSQL.

Para habilitar RLS mediante SQL, ejecute el siguiente comando:

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Creación de directivas de RLS

Después de habilitar RLS en una tabla, debe crear directivas que definan reglas de acceso. Sin directivas, los usuarios no pueden acceder a ninguna fila (todas las filas están ocultas de forma predeterminada).

Funcionamiento de las directivas: cuando RLS está habilitado en una tabla, los usuarios solo pueden ver las filas que coinciden con al menos una directiva. Todas las demás filas se filtran. Los propietarios de tablas, los roles con el BYPASSRLS atributo y los superusuarios pueden omitir el sistema de seguridad de filas (aunque los superusuarios no se admiten en Lakebase).

Nota:

En Lakebase, current_user devuelve la dirección de correo electrónico del usuario autenticado (por ejemplo, user@databricks.com). Úselo en las directivas de RLS para identificar qué usuario realiza la solicitud.

Sintaxis de directiva básica:

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • policy_name: un nombre descriptivo para la directiva
  • table_name: tabla a la que se va a aplicar la directiva
  • TO role_name: opcional. Especifica el rol de esta directiva. Omita esta cláusula para aplicar la directiva a todos los roles.
  • USING (condición): condición que determina qué filas están visibles

Tutorial de RLS

En el tutorial siguiente se usa el esquema de ejemplo de esta documentación (clientes, proyectos, tablas de tareas) para mostrar cómo implementar la seguridad de nivel de fila.

Escenario: Usted tiene varios usuarios que solo deben ver sus clientes asignados y proyectos relacionados. Restringir el acceso para que:

  • alice@databricks.com solo puede ver clientes con identificadores 1 y 2
  • bob@databricks.com solo puede ver clientes con identificadores 2 y 3

Paso 1: Habilitar RLS en la tabla de clientes

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Paso 2: Crear una directiva para Alice

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

Paso 3: Crear una directiva para Bob

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

Paso 4: Probar las directivas

Cuando Alice realiza una solicitud de API:

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

Respuesta (Alice solo ve los clientes 1 y 2):

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

Cuando Bob realiza una solicitud de API:

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

Respuesta (Bob solo ve los clientes 2 y 3):

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

Patrones comunes de RLS

Estos patrones cubren los requisitos de seguridad típicos de Data API:

Propiedad del usuario : restringe las filas al usuario autenticado:

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

Aislamiento de inquilinos : restringe las filas a la organización del usuario:

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

Pertenencia al equipo : restringe las filas a los equipos del usuario:

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

Acceso basado en roles: Restringe las filas según la pertenencia a roles.

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

Solo lectura para roles específicos - Políticas diferentes para distintas operaciones:

-- 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 adicionales

Para obtener información completa sobre la implementación de RLS, incluidos los tipos de directiva, los procedimientos recomendados de seguridad y los patrones avanzados, consulte la documentación de directivas de seguridad de filas de PostgreSQL.

Para obtener más información sobre los permisos, consulte Administración de permisos.

Referencia de API

En esta sección se supone que ha completado los pasos de configuración, los permisos configurados y la seguridad de nivel de fila implementada. En las secciones siguientes se proporciona información de referencia para usar Data API, incluidas las operaciones comunes, las características avanzadas, las consideraciones de seguridad y los detalles de compatibilidad.

Operaciones básicas

Consultar registros

Recuperar registros de una tabla mediante HTTP GET:

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

Respuesta de ejemplo:

[
  { "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 los resultados

Use parámetros de consulta para filtrar los resultados. En este ejemplo se recuperan clientes con id mayor o igual que 2:

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

Respuesta de ejemplo:

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

Selecciona columnas específicas y une tablas

Use el select parámetro para recuperar columnas específicas y combinar tablas relacionadas:

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

Respuesta de ejemplo:

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

Insertar registros

Cree nuevos registros mediante 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"

Actualizar registros

Actualice los registros existentes mediante 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"

Eliminar registros

Eliminar registros mediante HTTP DELETE:

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

Características avanzadas

Paginación

Controle el número de registros devueltos mediante los limit parámetros y offset :

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

Ordenación

Ordene los resultados mediante el order parámetro :

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

Filtrado complejo

Combinar varias condiciones de filtro:

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

Operadores de filtro comunes:

  • eq - es igual a
  • gte - mayor o igual que
  • lte - menor o igual que
  • neq : no es igual
  • like : coincidencia de patrones
  • in : coincide con cualquier valor de la lista.

Para obtener más información sobre los parámetros de consulta y las características de API admitidos, consulte la referencia de la API postgREST. Para obtener información de compatibilidad específica de Lakebase, consulte Compatibilidad de PostgREST.

Referencia de compatibilidad de funcionalidades

En esta sección se enumeran las características de PostgREST que tienen un comportamiento diferente o que no se admiten en la API de datos de Lakebase.

Autenticación y autorización

Característica Estado Detalles
Configuración de JWT No aplicable La API de datos de Lakebase usa tokens de OAuth de Azure Databricks en lugar de la autenticación JWT. Las opciones de configuración específicas de JWT (secretos personalizados, claves RS256, validación de audiencia) no están disponibles.

Inserción de recursos

Característica Estado Detalles
Relaciones calculadas No está soportado No se admiten las relaciones personalizadas definidas a través de funciones de base de datos que devuelven SETOF o registros únicos. Solo se pueden incorporar relaciones de clave externa.
Inserción de combinación interna (!inner sugerencia) No está soportado No se admite la sugerencia !inner que convierte uniones izquierdas en uniones internas para filtrar filas primarias en base a criterios secundarios. Ejemplo: ?select=*,clients!inner(*)&clients.id=eq.1

Formatos de respuesta

Característica Estado Detalles
Controladores de tipos de medios personalizados No está soportado No se admiten formatos de salida personalizados a través de agregados de PostgreSQL (formatos binarios, XML, búferes de protocolo).
Nulos eliminados No está soportado No se admite el nulls=stripped parámetro de tipo multimedia que quita campos NULL de las respuestas JSON. Ejemplo: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON Compatibilidad parcial Las columnas de geometría PostGIS se pueden consultar, pero el formato GeoJSON automático a través del encabezado Accept: application/geo+json no está disponible.

Paginación y recuento

Característica Estado Detalles
Recuento planeado No está soportado La opción Prefer: count=planned que utiliza el planificador de consultas de PostgreSQL para estimar los recuentos de resultados no está soportada. En su lugar, use Prefer: count=exact.
Recuento estimado No está soportado No se admite la Prefer: count=estimated opción que usa estadísticas de PostgreSQL para recuentos aproximados. En su lugar, use Prefer: count=exact.

Preferencias de solicitud

Característica Estado Detalles
Preferencia de zona horaria Compatibilidad parcial Existe el control de zona horaria, pero no se admite el Prefer: timezone=America/Los_Angeles encabezado para invalidar la zona horaria del servidor. Configure la zona horaria del servidor o use funciones de zona horaria de nivel de base de datos.
Control de transacciones No está soportado No se admite el control de transacciones a través de los encabezados Prefer: tx=commit y Prefer: tx=rollback.
Modos de control de preferencias No está soportado No se admiten las opciones Prefer: handling=strict y Prefer: handling=lenient para controlar cómo se manejan las preferencias no válidas.

Observability

Lakebase Data API implementa sus propias características de observabilidad. No se admiten las siguientes características de observabilidad postgREST:

Característica Estado Detalles
Exposición del plan de consulta No está soportado El encabezado que expone la salida de PostgreSQL EXPLAIN para el análisis de rendimiento no se admite.
encabezado Server-Timing No está soportado No se admite el encabezado Server-Timing que proporciona el desglose de tiempo de solicitud. Lakebase implementa sus propias características de observabilidad.
Propagación de encabezados de seguimiento No está soportado No se admite la propagación de X-Request-Id y encabezados de rastreo personalizado para el seguimiento distribuido. Lakebase implementa sus propias características de observabilidad.

Configuración avanzada

Característica Estado Detalles
Configuración de la aplicación (GUCs) No está soportado No se admite el paso de valores de configuración personalizados a las funciones de base de datos a través de GUCs de PostgreSQL.
Función de solicitud previa No está soportado Configuración db-pre-request que permite especificar una función de base de datos que se va a ejecutar antes de que no se admita cada solicitud.

Para obtener más información sobre las características de PostgREST, consulte la documentación de PostgREST.

Consideraciones de seguridad

Data API aplica el modelo de seguridad de la base de datos en varios niveles:

  • Autenticación: todas las solicitudes requieren autenticación de token de OAuth válida
  • Acceso basado en roles: los permisos de nivel de base de datos controlan a qué tablas y operaciones pueden acceder los usuarios
  • Seguridad de nivel de fila: las directivas de RLS aplican un control de acceso específico, lo que restringe las filas específicas que los usuarios pueden ver o modificar.
  • Contexto de usuario: la API asume la identidad del usuario autenticado, lo que garantiza que los permisos y directivas de la base de datos se aplican correctamente.

Para implementaciones de producción:

  1. Implementar la seguridad de nivel de fila: use directivas de RLS para restringir el acceso a los datos en el nivel de fila. Esto es especialmente importante para las aplicaciones multiinquilino y los datos propiedad del usuario. Vea Seguridad de nivel de fila.
  2. Conceder permisos mínimos: conceda solo los permisos que necesitan los usuarios (SELECT, INSERT, UPDATE, DELETE) en tablas específicas en lugar de conceder acceso amplio.
  3. Usar roles independientes por aplicación: cree roles dedicados para diferentes aplicaciones o servicios en lugar de compartir un solo rol.
  4. Auditar el acceso periódicamente: revise periódicamente los permisos concedidos y las directivas de RLS para asegurarse de que cumplen los requisitos de seguridad.

Para obtener información sobre cómo administrar roles y permisos, consulte:

  • Last updated on