Поделиться через

API данных Lakebase

Это важно

Автомасштабирование Lakebase находится в бета-версии в следующих регионах: eastus2, , westeuropewestus.

Автомасштабирование Lakebase — это последняя версия Lakebase с автомасштабированием вычислений, масштабированием до нуля, ветвлением и мгновенным восстановлением. Сравнение функций с Lakebase Provisioned см. в разделе выбора между версиями.

API данных Lakebase — это интерфейс RESTful, совместимый с PostgREST, который позволяет взаимодействовать непосредственно с базой данных Lakebase Postgres с помощью стандартных методов HTTP. Она предлагает конечные точки API, производные от схемы базы данных, позволяя безопасно выполнять операции CRUD (создание, чтение, обновление, удаление) данных без необходимости разработки пользовательской серверной части.

Обзор

API данных автоматически создает конечные точки RESTful на основе схемы базы данных. Каждая таблица в базе данных становится доступной через HTTP-запросы, что позволяет:

  • Запрос данных с помощью HTTP-запросов GET с гибкой фильтрацией, сортировкой и разбивкой на страницы
  • Вставка записей с помощью HTTP-запросов POST
  • Обновление записей с помощью ЗАПРОСОВ HTTP PATCH или PUT
  • Удаление записей с помощью запросов HTTP DELETE
  • Выполнять функции как RPCs с использованием HTTP POST-запросов

Этот подход устраняет необходимость написания и поддержания пользовательского кода API, что позволяет сосредоточиться на логике приложения и схеме базы данных.

Совместимость PostgREST

API данных Lakebase совместим с спецификацией PostgREST . Вы можете:

  • Использование существующих клиентских библиотек и средств PostgREST
  • Следуйте соглашениям PostgREST для фильтрации, упорядочивания и разбиения на страницы
  • Адаптация документации и примеров из сообщества PostgREST

Замечание

API данных Lakebase — это реализация Azure Databricks, предназначенная для обеспечения совместимости со спецификацией PostgREST. Так как API данных является независимой реализацией, некоторые функции PostgREST, которые не применимы к среде Lakebase, не включены. Дополнительные сведения о совместимости компонентов см. в справочнике по совместимости компонентов.

Подробные сведения о функциях API, параметрах запросов и возможностях см. в справочнике по API PostgREST.

Варианты использования

API данных Lakebase идеально подходит для следующих вариантов:

  • Веб-приложения: создание интерфейсов, которые напрямую взаимодействуют с базой данных с помощью HTTP-запросов
  • Микрослужбы: создание упрощенных служб, обращаюющихся к ресурсам базы данных с помощью REST API
  • Бессерверные архитектуры: интеграция с бессерверными функциями и edge-компьютинг платформами
  • Мобильные приложения: предоставление мобильных приложений с прямым доступом к базе данных через интерфейс RESTful
  • Сторонние интеграции: обеспечение безопасного чтения и записи данных внешними системами

Настройка API данных

В этом разделе описано, как настроить API данных, от создания необходимых ролей до выполнения первого запроса API.

Необходимые условия

API данных требует проекта базы данных Lakebase Postgres Autoscaling. Если у вас его нет, см. статью "Начало работы с проектами базы данных".

Подсказка

Если вам нужны примеры таблиц для тестирования API данных, создайте их перед включением API данных. Полный пример схемы см. в примере схемы .

Включение API данных

API данных делает доступ ко всем базам данных через одну роль Postgres с именем authenticator, которая не требует разрешений, кроме входа. При включении API данных через приложение Lakebase эта роль и необходимая инфраструктура создаются автоматически.

Чтобы включить API данных, выполните следующие действия.

  1. Перейдите на страницу API данных в проекте.
  2. Нажмите кнопку "Включить API данных".

Кнопка

Это автоматически выполняет все действия по настройке, включая создание authenticator роли, настройку pgrst схемы и предоставление public схемы через API.

Замечание

Если вам нужно предоставить дополнительные схемы (кроме public), можно изменить предоставленные схемы в параметрах РАСШИРЕННОго API данных.

После включения API данных

После включения API данных приложение Lakebase отображает страницу API данных с двумя вкладками: API и параметры.

Страница API данных с url-адресом API и параметрами безопасности

Вкладка API предоставляет следующие возможности:

  • URL-адрес API: URL-адрес конечной точки REST, используемый в коде приложения и запросах API. Отображаемый URL-адрес не содержит схему, поэтому при выполнении запросов API необходимо добавить имя схемы (например, /public) к URL-адресу.
  • Обновление кэша схемы: кнопка для обновления кэша схемы API после внесения изменений в схему базы данных. См. раздел "Обновить кэш схемы".
  • Защита данных: параметры для включения безопасности на уровне строк Postgres (RLS) для таблиц. См. раздел "Включить безопасность на уровне строк".

Вкладка "Параметры" предоставляет параметры для настройки поведения API, таких как предоставленные схемы, максимальные строки, параметры CORS и многое другое. Дополнительные параметры API данных см. в разделе "Дополнительные параметры API данных".

Пример схемы (необязательно)

В примерах этой документации используется следующая схема. Вы можете создать собственные таблицы или использовать эту пример схемы для тестирования. Выполните эти инструкции SQL с помощью редактора SQL Lakebase или любого клиента 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);

Настройка разрешений пользователя

Необходимо пройти проверку подлинности всех запросов API данных с помощью токенов-носителей OAuth Azure Databricks, которые отправляются через заголовок Authorization. API данных ограничивает доступ к аутентифицированным удостоверениям Azure Databricks, при этом Postgres управляет базовыми разрешениями.

Роль authenticator предполагает удостоверение запрашивающего пользователя при обработке запросов API. Для работы каждое удостоверение Azure Databricks, обращающееся к API данных, должно иметь соответствующую роль Postgres в базе данных. Если необходимо сначала добавить пользователей в учетную запись Azure Databricks, см. статью "Добавление пользователей в учетную запись".

Добавление ролей Postgres

Используйте расширение databricks_auth для создания ролей Postgres, соответствующих идентификации Azure Databricks:

Создайте расширение:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

Добавьте роль Postgres:

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

Подробные инструкции см. в статье "Создание роли OAuth для удостоверения Azure Databricks с помощью SQL".

Это важно

Не используйте учетную запись владельца базы данных (удостоверение Azure Databricks, создавшего проект Lakebase) для доступа к API данных. Для authenticator роли требуется возможность принять свою роль, и это разрешение не может быть предоставлено для учетных записей с повышенными привилегиями.

Если вы пытаетесь предоставить роль authenticatorвладельца базы данных, вы получите следующую ошибку:

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.

Предоставление разрешений пользователям

Теперь, когда вы создали соответствующие роли Postgres для удостоверений Azure Databricks, необходимо предоставить разрешения этим ролям Postgres. Эти разрешения управляют объектами базы данных (схемами, таблицами, последовательностями, функциями), с которыми каждый пользователь может взаимодействовать с помощью запросов API.

Предоставьте разрешения с помощью стандартных инструкций SQL GRANT . В этом примере используется схема public; если вы предоставляете другую схему, замените public на имя вашей схемы.

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

В этом примере предоставляется полный доступ к схеме public для удостоверения user@databricks.com. Замените это фактическим удостоверением Azure Databricks и настройте разрешения на основе ваших требований.

Это важно

Реализуйте безопасность на уровне строк. Разрешения, указанные выше, предоставляют доступ на уровне таблицы, но большинство вариантов использования API требуют ограничений на уровне строк. Например, в мультитенантных приложениях пользователи должны видеть только собственные данные или данные организации. Используйте политики безопасности на уровне строк PostgreSQL (RLS), чтобы обеспечить точное управление доступом на уровне базы данных. См. раздел "Реализация безопасности на уровне строк".

Проверка подлинности

Чтобы получить доступ к API данных, необходимо предоставить маркер OAuth Azure Databricks в заголовке Authorization HTTP-запроса. Удостоверение Azure Databricks с подтвержденной аутентификацией должно иметь соответствующую роль в Postgres (созданную на предыдущих этапах), которая определяет разрешения базы данных.

Получение токена OAuth

Подключитесь к рабочей области в качестве аккаунта Azure Databricks, для которого в предыдущих шагах вы создали роль Postgres, и получите токен OAuth. Инструкции см. в разделе "Проверка подлинности ".

Выполнение запроса

С помощью маркера OAuth и URL-адреса API (доступного на вкладке API в приложении Lakebase), вы можете выполнять запросы API с помощью curl или любого HTTP-клиента. Не забудьте добавить имя схемы (например, /public) в URL-адрес API. Предполагается, что в следующих примерах вы экспортировали переменные среды DBX_OAUTH_TOKEN и REST_ENDPOINT.

Ниже приведен пример вызова с ожидаемыми выходными данными (с помощью примера клиентов или проектов и схемы задач):

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

Пример ответа:

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

Дополнительные примеры и подробные сведения об операциях API см. в разделе справочника по API . Подробные сведения о параметрах запросов и возможностях API см. в справочнике по API PostgREST. Сведения о совместимости, относящиеся к Lakebase, см. в разделе "Совместимость PostgREST".

Прежде чем использовать API, настройте безопасность на уровне строк для защиты данных.

Управление API данных

После включения API данных можно управлять изменениями схемы и параметрами безопасности с помощью приложения Lakebase.

Обновление кэша схемы

При внесении изменений в схему базы данных (добавление таблиц, столбцов или других объектов схемы) необходимо обновить кэш схемы. Это делает изменения сразу же доступными через API данных.

Чтобы обновить кэш схемы, выполните следующие действия.

  1. Перейдите к API данных в разделе серверной части приложения проекта.
  2. Щелкните "Обновить кэш схемы".

Теперь API данных отображает ваши последние изменения в схеме.

Включение безопасности на уровне строк

Приложение Lakebase предоставляет быстрый способ включения безопасности на уровне строк (RLS) для таблиц в базе данных. Если таблицы существуют в схеме, на вкладке API отображается раздел "Защита данных ", в котором показано:

  • Таблицы с включенными RLS
  • Таблицы с отключенной RLS (с предупреждениями)
  • Кнопка Включить RLS для всех таблиц

Это важно

Включение RLS через приложение Lakebase включает безопасность на уровне строк для таблиц. Если служба RLS включена, все строки становятся недоступными пользователям по умолчанию (за исключением владельцев таблиц, ролей с атрибутом BYPASSRLS и суперпользователями, хотя суперпользователи не поддерживаются в Lakebase). Необходимо создать политики RLS, чтобы предоставить доступ к определенным строкам на основе требований безопасности. Сведения о создании политик см. в разделе "Безопасность на уровне строк ".

Чтобы включить RLS для таблиц, выполните приведенные ниже действия.

  1. Перейдите к API данных в разделе серверной части приложения проекта.
  2. В разделе "Защита данных " просмотрите таблицы, не имеющие поддержки RLS.
  3. Нажмите кнопку "Включить RLS" , чтобы включить безопасность на уровне строк для всех таблиц.

Вы также можете включить RLS для отдельных таблиц с помощью SQL. Дополнительные сведения см. в разделе "Безопасность на уровне строк ".

Дополнительные параметры API данных

Раздел "Дополнительные параметры " на вкладке API в приложении Lakebase управляет безопасностью, производительностью и поведением конечной точки API данных.

Открытые схемы

По умолчанию:public

Определяет, какие схемы PostgreSQL предоставляются в качестве конечных точек REST API. По умолчанию доступна только public схема. Если вы используете другие схемы (например, api, v1), выберите их из раскрывающегося списка, чтобы добавить.

Замечание

Применяются разрешения: Добавление схемы здесь предоставляет точки доступа, но роль базы данных, используемая API, по-прежнему должна иметь USAGE привилегии на схему и SELECT привилегии на таблицы.

Максимальное количество строк

По умолчанию: Пустой

Принудительно ограничивает количество строк, возвращаемых в одном ответе API. Это предотвращает случайное снижение производительности от больших запросов. Клиенты должны использовать ограничения разбиения на страницы для получения данных в пределах этого порогового значения. Это также предотвращает непредвиденные затраты на исходящий трафик от больших передач данных.

Разрешенные источники CORS

По умолчанию: Пустое (разрешает все источники)

Определяет, какие веб-домены могут получать данные из API с помощью браузера.

  • Пустой: Разрешает * (любой домен). Полезно для разработки.
  • Производство: Перечислите ваши конкретные домены (например, https://myapp.com), чтобы предотвратить несанкционированным веб-сайтам запросы к вашему API.

Спецификация OpenAPI

По умолчанию: Отключено

Определяет, доступна ли автоматически созданная схема OpenAPI 3 на /openapi.json. Эта схема описывает таблицы, столбцы и конечные точки REST. Если этот параметр включен, его можно использовать для:

  • Создание документации по API (пользовательский интерфейс Swagger, Redoc)
  • Сборка типизированных клиентских библиотек (TypeScript, Python, Go)
  • Импорт API в Postman
  • Интеграция со шлюзами API и другими средствами на основе OpenAPI

Заголовки времени сервера

По умолчанию: Отключено

При активации данных API включает заголовки Server-Timing в каждом ответе. Эти заголовки показывают, сколько разных частей запроса потребовалось для обработки (например, время выполнения базы данных и внутреннее время обработки). Эти сведения можно использовать для отладки медленных запросов, измерения производительности и устранения проблем с задержкой в приложении.

Замечание

После внесения изменений в дополнительные параметры нажмите кнопку "Сохранить ", чтобы применить их.

Безопасность на уровне строк

Политики безопасности на уровне строк (RLS) обеспечивают точное управление доступом путем ограничения доступа пользователей строк в таблице.

Как RLS работает с API данных: когда пользователь выполняет запрос API, роль принимает на себя authenticator удостоверение пользователя. Все политики RLS, определенные для роли этого пользователя, автоматически применяются в PostgreSQL, фильтруя доступные данные. Это происходит на уровне базы данных, поэтому даже если код приложения пытается запрашивать все строки, база данных возвращает только строки, которые пользователь может видеть. Это обеспечивает глубокую защиту без необходимости фильтрации логики в коде приложения.

Почему RLS имеет решающее значение для API: в отличие от прямых подключений к базе данных, где вы управляете контекстом подключения, API HTTP предоставляют базу данных нескольким пользователям через одну конечную точку. Только разрешения на уровне таблицы означают, что если пользователь может получить доступ к clients таблице, он может получить доступ ко всем записям клиента, если только не реализуется фильтрация. Политики RLS гарантируют, что каждый пользователь автоматически видит только свои авторизованные данные.

RLS имеет важное значение для:

  • Многотенантные приложения: изоляция данных между различными клиентами или организациями
  • Данные, принадлежащие пользователям: убедитесь, что пользователи получают доступ только к собственным записям
  • Доступ на основе команд: ограничение видимости участникам команды или определенным группам
  • Требования к соответствию требованиям. Применение ограничений доступа к данным на уровне базы данных

Включение RLS

Вы можете включить RLS с помощью приложения Lakebase или с помощью инструкций SQL. Инструкции по использованию приложения Lakebase см. в разделе "Включение безопасности на уровне строк".

Предупреждение

Если у вас есть таблицы без поддержки RLS, вкладка API в приложении Lakebase отображает предупреждение о том, что пользователи, прошедшие проверку подлинности, могут просматривать все строки в этих таблицах. API данных взаимодействует непосредственно со схемой Postgres, и поскольку API доступен через Интернет, важно обеспечить безопасность на уровне базы данных с помощью защиты на уровне строк PostgreSQL.

Чтобы включить RLS с помощью SQL, выполните следующую команду:

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Создание политик RLS

После включения RLS в таблице необходимо создать политики, определяющие правила доступа. Без политик пользователи не могут получить доступ к любым строкам (все строки скрыты по умолчанию).

Как работают политики: если RLS включена в таблице, пользователи могут видеть только строки, соответствующие по крайней мере одной политике. Все остальные строки отфильтровываются. Владельцы таблиц, роли с BYPASSRLS атрибутом и суперпользователи могут обойти систему безопасности строк (хотя суперпользователи не поддерживаются в Lakebase).

Замечание

В Lakebase current_user возвращает адрес электронной почты прошедшего проверку подлинности пользователя (например, user@databricks.com). Используйте это в политиках RLS, чтобы определить, какой пользователь выполняет запрос.

Базовый синтаксис политики:

CREATE POLICY policy_name ON table_name
  [TO role_name]
  USING (condition);
  • policy_name: описательное имя политики
  • table_name: Таблица, к которой применяется политика
  • TO role_name: Необязательно. Указывает роль для этой политики. Опустить это предложение, чтобы применить политику ко всем ролям.
  • USING (условие): условие, определяющее, какие строки видны

Руководство по RLS

В следующем руководстве используется пример схемы из этой документации (клиенты, проекты, таблицы задач) для реализации безопасности на уровне строк.

Сценарий. У вас есть несколько пользователей, которые должны видеть только назначенных клиентов и связанные проекты. Ограничьте доступ таким образом:

  • alice@databricks.com может просматривать только клиентов с идентификаторами 1 и 2
  • bob@databricks.com может просматривать только клиентов с идентификаторами 2 и 3

Шаг 1. Включение RLS в таблице клиентов

ALTER TABLE clients ENABLE ROW LEVEL SECURITY;

Шаг 2. Создание политики для Алисы

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

Шаг 3. Создание политики для Боба

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

Шаг 4. Тестирование политик

Когда Алиса выполняет запрос API:

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

Ответ (Алиса видит только клиенты 1 и 2):

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

Когда Боб выполняет запрос API:

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

Ответ (Боб видит только клиенты 2 и 3):

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

Общие шаблоны RLS

Эти шаблоны охватывают типичные требования к безопасности ДЛЯ API данных:

Владение пользователем - Ограничивает строки для аутентифицированного пользователя:

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

Изоляция арендатора — ограничивает доступ к строкам в пределах организации пользователя.

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

Членство в команде — ограничивает отображение строк только командами пользователя:

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

Доступ на основе ролей — ограничивает строки на основе членства в роли:

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

Только для чтения для определенных ролей — разные политики для различных операций:

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

Дополнительные ресурсы

Подробные сведения о реализации RLS, включая типы политик, рекомендации по безопасности и расширенные шаблоны, см. в документации по политикам безопасности строк PostgreSQL.

Дополнительные сведения о разрешениях см. в разделе "Управление разрешениями".

Справочник по API

В этом разделе предполагается, что вы выполнили действия по настройке, настроенные разрешения и реализовали безопасность на уровне строк. В следующих разделах приведены справочные сведения об использовании API данных, включая общие операции, расширенные функции, рекомендации по безопасности и сведения о совместимости.

Основные операции

Записи запросов

Получение записей из таблицы с помощью HTTP GET:

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

Пример ответа:

[
  { "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"
  }
]

Фильтрация результатов

Используйте параметры запроса для фильтрации результатов. В этом примере извлекаются клиенты с id, которая больше или равна 2:

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

Пример ответа:

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

Выберите определенные столбцы и соедините таблицы

select Используйте параметр для получения определенных столбцов и соединения связанных таблиц:

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

Пример ответа:

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

Вставка записей

Создайте новые записи с помощью 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"

Записи обновлений

Обновление существующих записей с помощью 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"

Удаление записей

Удаление записей с помощью HTTP DELETE:

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

Дополнительные функции

Постраничная разбивка

Управляйте количеством возвращаемых записей с помощью параметров limit и offset.

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

Сортировка

Сортируйте результаты с помощью order параметра:

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

Сложная фильтрация

Объединение нескольких условий фильтра:

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

Распространенные операторы фильтров:

  • eq -Равно
  • gte - больше или равно
  • lte - меньше или равно
  • neq - не равно
  • like - сопоставление с шаблоном
  • in — соответствует любому значению в списке

Дополнительные сведения о поддерживаемых параметрах запросов и функциях API см. в справочнике по API PostgREST. Сведения о совместимости, относящиеся к Lakebase, см. в разделе "Совместимость PostgREST".

Справочник по совместимости компонентов

В этом разделе перечислены функции PostgREST, которые имеют другое поведение или не поддерживаются в API данных Lakebase.

Проверка подлинности и авторизация

Функция Состояние Сведения
Конфигурация JWT Неприменимо API данных Lakebase использует токены OAuth Azure Databricks вместо проверки подлинности JWT. Параметры конфигурации для JWT (пользовательские секреты, ключи RS256, проверка аудитории) недоступны.

Внедрение ресурсов

Функция Состояние Сведения
Вычисляемые связи Не поддерживается Нестандартные связи, определенные с помощью функций базы данных, возвращающих SETOF или отдельные записи, не поддерживаются. Можно встраивать только связи внешнего ключа.
Встраивание внутреннего соединения (!inner подсказка) Не поддерживается Указание !inner , которое преобразует левые соединения в внутренние соединения для фильтрации родительских строк на основе дочерних критериев, не поддерживается. Пример: ?select=*,clients!inner(*)&clients.id=eq.1

Форматы ответов

Функция Состояние Сведения
Пользовательские обработчики типов мультимедиа Не поддерживается Пользовательские форматы выходных данных через агрегаты PostgreSQL (двоичные форматы, XML, буферы протокола) не поддерживаются.
Удаленные значения NULL Не поддерживается Параметр nulls=stripped типа носителя, который удаляет поля NULL из ответов JSON, не поддерживается. Пример: Accept: application/vnd.pgrst.object+json;nulls=stripped
PostGIS GeoJSON Частично поддерживается Столбцы геометрии PostGIS можно запрашивать, но автоматическое форматирование GeoJSON через заголовок Accept: application/geo+json недоступно.

Разбивка на страницы и подсчет

Функция Состояние Сведения
Запланированное число Не поддерживается Параметр Prefer: count=planned , использующий планировщик запросов PostgreSQL для оценки количества результатов, не поддерживается. Вместо этого используйте Prefer: count=exact.
Предполагаемое число Не поддерживается Параметр Prefer: count=estimated , использующий статистику PostgreSQL для приблизительных счетчиков, не поддерживается. Вместо этого используйте Prefer: count=exact.

Настройки запроса

Функция Состояние Сведения
Предпочтения часового пояса Частично поддерживается Существуют механизмы обработки часового пояса, но заголовок Prefer: timezone=America/Los_Angeles для переопределения часового пояса сервера не поддерживается. Настройте часовой пояс сервера или используйте функции часового пояса уровня базы данных.
Управление транзакцией Не поддерживается Управление транзакциями через заголовки Prefer: tx=commit и Prefer: tx=rollback не поддерживается.
Режимы обработки предпочтений Не поддерживается Параметры Prefer: handling=strict и Prefer: handling=lenient для обработки недопустимых предпочтений не поддерживаются.

Observability

API данных Lakebase реализует собственные функции наблюдаемости. Следующие функции наблюдения PostgREST не поддерживаются:

Функция Состояние Сведения
Раскрытие плана запросов Не поддерживается Заголовок Accept: application/vnd.pgrst.plan+json , предоставляющий выходные данные PostgreSQL EXPLAIN для анализа производительности, не поддерживается.
заголовок Server-Timing Не поддерживается Заголовок Server-Timing, предоставляющий разбивку по времени запроса, не поддерживается. Lakebase реализует собственные функции наблюдаемости.
Распространение заголовков трассировки Не поддерживается Распространение заголовков трассировки X-Request-Id и пользовательских заголовков трассировки для распределенной трассировки не поддерживается. Lakebase реализует собственные функции наблюдаемости.

Расширенная конфигурация

Функция Состояние Сведения
Параметры приложения (GUCs) Не поддерживается Передача пользовательских значений конфигурации в функции базы данных через GUCs PostgreSQL не поддерживается.
Функция предварительного запроса Не поддерживается Конфигурация db-pre-request, которая позволяет задать функцию базы данных для выполнения перед каждым запросом, не поддерживается.

Дополнительные сведения о функциях PostgREST см. в документации по PostgREST.

Вопросы безопасности

API данных применяет модель безопасности базы данных на нескольких уровнях:

  • Проверка подлинности: Для всех запросов требуется действительная аутентификация с использованием токена OAuth
  • Доступ на основе ролей: разрешения на уровне базы данных управляют доступом к таблицам и операциям пользователей.
  • Безопасность на уровне строк: политики RLS применяют детальное управление доступом, ограничивая, какие определенные строки пользователи могут видеть или изменять
  • Контекст пользователя: API предполагает удостоверение пользователя, прошедшего проверку подлинности, обеспечивая правильное применение разрешений и политик базы данных.

Для рабочих развертываний:

  1. Реализуйте безопасность на уровне строк: используйте политики RLS для ограничения доступа к данным на уровне строки. Это особенно важно для мультитенантных приложений и пользовательских данных. См. безопасность на уровне строк.
  2. Предоставьте минимальные разрешения: только предоставить пользователям необходимые разрешения (SELECT, INSERT, , UPDATE) DELETEдля определенных таблиц, а не предоставлять широкий доступ.
  3. Используйте отдельные роли для каждого приложения: создайте выделенные роли для разных приложений или служб, а не совместное использование одной роли.
  4. Регулярно проверяйте доступ: периодически просматривайте предоставленные разрешения и политики RLS, чтобы обеспечить соответствие требованиям безопасности.

Сведения об управлении ролями и разрешениями см. в следующем разделе:

  • Last updated on