Directus: управление данными и автоматизация процессов строится вокруг вашей существующей базы. По документации проекта, вы подключаете базу данных, и Directus автоматически генерирует готовый к работе REST и GraphQL API. Дальше вы описываете коллекции, права ролей и отдаёте данные наружу — в том числе в отдельный frontend каталога.
Коллекция books, items и граница с frontend
Начнём с терминов. По документации Items API, items — это отдельные единицы данных в вашей базе. Коллекция — их именованная группа. В примере ниже коллекция называется books; это пользовательская коллекция, которую вы создаёте сами. Поля code, title, published тоже заданы вручную для учебного примера и встроенной схемой Directus не являются.
Условный исходник для примера — три записи:
[
{"code": "BOOK_A", "title": "Учебная книга А", "published": true},
{"code": "BOOK_B", "title": "Учебный черновик Б", "published": false},
{"code": "BOOK_C", "title": "Учебная книга В", "published": true}
]
Это ручной учебный вход, составленный для разбора. Сервер при его подготовке не запускался, и результат работы установки здесь не измеряется.
Теперь про разделение слоёв. Data Studio — интерфейс, в котором вы описываете коллекции, поля, связи и права. Frontend каталога — отдельное приложение, которое вы разрабатываете сами и которое обращается к API за данными. Эти два слоя решают разные задачи: в Studio настраивается модель и доступ, в каталоге показываются книги читателю. Смешивать их не стоит: правки схемы и правки вёрстки живут в разных местах.
По главной странице проекта, AI-агенты работают под тем же ролевым контролем доступа, что и люди. Это значит, что права, настроенные для ролей, распространяются и на автоматизированные обращения к API.
Ещё один факт с главной: данные уже лежат в вашей базе, и по ним можно строить графики, метрики и отчёты без выгрузки в другой инструмент. Для каталога это означает, что аналитика по книгам может опираться на ту же коллекцию.
Items Reference: подтверждённый GET и ответ с data
По справочнику Items API подтверждён путь GET /items/{collection}. Документация описывает его так: возвращает список items в указанной коллекции. Ответ приходит объектом с массивом data.
Реальный адрес своей установки задаёт читатель. В примерах ниже база берётся из переменной окружения — подставьте свой хост:
DIRECTUS_BASE_URL="https://your-directus-host.example"
curl "$DIRECTUS_BASE_URL/items/books"
Ожидаемая форма ответа для публичного чтения — ручной эталон, составленный для примера:
{
"data": [
{"code": "BOOK_A", "title": "Учебная книга А"},
{"code": "BOOK_C", "title": "Учебная книга В"}
]
}
Этот JSON вымышленный и составлен автором. Он показывает форму, к которой вы стремитесь, и служит эталоном для сравнения. Сравните фактический ответ своей установки с этим ручным эталоном.
Справочник также описывает управление набором возвращаемых полей и выбор items по заданным условиям. Эти возможности относятся к запросу. Серверное ограничение строк настраивается отдельно, в правах доступа.
Access Control: collection, action, filter, fields
По руководству Access Control, разрешение задаётся на коллекцию и действие. Доступные действия: create, read, update, delete, share. Фильтрующие правила определяют, какие items коллекции пользователь может получить. Политики — это группа разрешений, применяемая к пользователям или ролям.
Ключевое свойство: применение политик аддитивно. Каждая политика добавляет разрешения к существующим и не отнимает их. Отсюда практический вывод для учебного примера: у роли Public должна быть одна проверенная политика на чтение. Другая разрешающая политика, назначенная той же роли, может расширить доступ; проверьте совокупность всех действующих правил.
Публичные разрешения по умолчанию выключены. Административная роль даёт полный неограниченный контроль над проектом. После выдачи Public чтения всей коллекции все её записи, включая черновики, становятся доступны без авторизации, если дополнительные условия на items не настроены.
Соберём матрицу для учебной коллекции books:
| Роль | Действие | Условие на строки | Поля | Состояние |
|---|---|---|---|---|
| Public | read | published = true | code, title | включено |
| Public | create | — | — | выключено |
| Public | update | — | — | выключено |
| Public | delete | — | — | выключено |
| Public | share | — | — | выключено |
| Editor | read | вся коллекция | все поля | включено |
| Editor | create | — | — | включено |
| Editor | update | — | — | включено |
| Editor | delete | — | — | включено |
| Editor | share | — | — | выключено |
Условие published = true описывается словами в настройках фильтра. Синтаксис операторов фильтра не выводите из общих знаний — сверяйтесь с документацией своей версии.
Порядок настройки: начните с выключенных публичных разрешений. Затем включите чтение для Public и сразу задайте серверное условие на строки. После этого ограничьте набор полей до code и title. Действия create, update, delete и share для Public оставьте выключенными.
Серверные права и клиентский filter
Эти два механизма решают разные задачи, и путать их опасно. Серверное условие на items в правах роли определяет, какие строки роль получит в принципе. Параметр фильтра в запросе — это добровольное уточнение со стороны клиента. Клиент может его убрать, и серверное ограничение при этом продолжит действовать.
Проверим на учебном примере. Public получает две записи: BOOK_A и BOOK_C. Editor получает три записи, включая черновик BOOK_B. Разница возникает из-за условия published = true у Public.
Три отрицательные пробы, которые стоит выполнить в своей тестовой установке:
- Запросить черновик BOOK_B без авторизации. Ожидание: черновик не выдаётся.
- Убрать клиентский фильтр из запроса. Ожидание: набор строк не меняется, серверное условие продолжает работать.
- Выполнить публичное изменение записи. Ожидание: изменение отклоняется.
Точный код ошибки заранее не предсказывайте — сверяйтесь с ответом своей установки. Разрешения конфигурируются и реально проверяются в вашей тестовой среде; эта статья результаты такого запуска не имитирует.
Роль Editor и токены
Editor — отдельная роль с собственной политикой на read, create, update и delete для учебной коллекции. Действие share для неё выключено. Административную роль в качестве ограниченного редактора использовать не следует: она даёт полный неограниченный контроль над проектом.
Public означает запрос без авторизации. Токен редактора в код публичного клиента не помещайте: любой, кто откроет frontend, получит этот токен и вместе с ним права Editor. Публичный каталог обращается к API анонимно, и его доступ ограничен политикой Public.
Для проверки прав Editor используйте отдельный запрос с токеном на своей стороне, вне публикуемого кода:
DIRECTUS_BASE_URL="https://your-directus-host.example"
EDITOR_TOKEN="$(cat /run/secrets/directus_editor_token)"
curl -H "Authorization: Bearer $EDITOR_TOKEN" "$DIRECTUS_BASE_URL/items/books"
В примере токен читается из заранее подготовленного файла секрета. Команда не печатает его отдельной строкой; настройки журналирования и запуска своей среды проверьте отдельно. Этот запрос выполняется вне публичного frontend.
Лицензия: название и проверка условий
Лицензионная страница проекта озаглавлена Monospace Sustainable Core License, идентификатор — MSCL-1.0-GPL. Копирайт указан как Copyright 2026 Monospace Inc.
Этого достаточно, чтобы знать, как называется текущий документ и где его искать. Условия своего использования проверяйте по тексту лицензии: сценарии распространения, модификации и встраивания в продукты у разных команд различаются. Финансовые пороги и суммы из сторонних сравнительных обзоров в этот разбор не переносятся — они относятся к другим редакциям документа. Юридические исключения из текста лицензии не стоит читать как разрешение для вашего конкретного случая.
Как разобрать расхождение с эталоном
Для каждой пробы запишите роль запроса, список вернувшихся кодов книг и выполненное действие. Начните с анонимного чтения без сохранённых заголовков авторизации. В ручном эталоне для него есть BOOK_A и BOOK_C. Затем отдельно выполните редакторский запрос. Нельзя сравнивать два результата, если клиент незаметно подставляет один и тот же редакторский токен в обоих случаях.
Если анонимный запрос вернул BOOK_B, проверьте серверное условие и совокупность разрешающих политик. Если не вернулась ни одна книга, сначала убедитесь, что нужные записи есть в коллекции и пользовательская настройка опубликованности заполнена. После исправления повторите исходный запрос без добавления клиентского фильтра: это позволит проверить именно серверное правило выбранной роли. Сохраните полученный список кодов рядом с ожидаемым результатом своего теста.
Частые вопросы
Что такое коллекция books в Directus?
Это пользовательская коллекция, которую вы создаёте сами. Поля code, title и published в примере заданы вручную и встроенной схемой Directus не являются. Коллекция хранит items — отдельные единицы данных в вашей базе. Права на неё настраиваются отдельно для каждой роли.
Какой путь API возвращает список items?
Подтверждённый путь — GET /items/{collection}. Он возвращает список items указанной коллекции, ответ приходит с массивом data. Реальный адрес своей установки подставляет читатель. Форму ответа сравнивайте с ручным эталоном из этой статьи.
Как ограничить публичное чтение только опубликованными записями?
Включите для роли Public действие read на коллекцию books и задайте серверное условие published = true. Ограничьте набор полей до code и title. Действия create, update, delete и share оставьте выключенными. Условие описывается словами в настройках фильтра.
Почему клиентский filter не заменяет права доступа?
Параметр фильтра в запросе задаёт клиент и может его убрать. Серверное условие на items в правах роли действует независимо от запроса. Именно оно определяет, какие строки роль получит. Поэтому ограничение строк настраивается в правах, а фильтр в запросе служит уточнением.
Чем Editor отличается от администратора?
Editor — отдельная роль с собственной политикой на read, create, update и delete для учебной коллекции. Административная роль даёт полный неограниченный контроль над проектом. Для ограниченного редактирования создавайте отдельную роль. Токен редактора храните вне публичного frontend.
