Directus — это open‑source платформа для управления данными, которая превращает любую SQL‑базу в headless CMS, предоставляя автоматическую REST и GraphQL API и удобный веб-интерфейс для управления контентом.
Она устанавливается поверх существующей базы данных и не требует её миграции — Directus быстро строит схему, интерфейс и API на лету, позволяя пользователям работать с данными через визуальную Data Studio.
В статье я рассмотрю пример базовой настройки Directus.
Установка Directus
Развернём мы Directus в Amvera Cloud, где Directus является преднастроенным сервисом.
Преднастроенные сервисы нам дают возможность развернуть и обновлять Directus одним действием из интерфейса, а также бесплатный домен с SSL.
Переходим в личный кабинет Amvera Cloud (при регистрации будет 111 р. на тест, что позволит начать без пополнения аккаунта).
В панели снизу выбираем Directus.
Вводим название и выбираем тариф.
В переменных окружения обязательно введите key, secret — случайные значения и admin_email, admin_pass — данные администратора.
Ожидаем запуска сервиса около 1 минуты. Готово, мы имеем рабочий сервис и можем приступить к работе.
Переходим к проекту, открываем раздел «Домены».
Активируем бесплатный домен с SSL.
Кликаем по доступному домену и переходим в интерфейс Directus.
Вы должны попасть на страницу входа. Здесь мы получаем доступ к веб-интерфейсу Data Studio — визуальному рабочему пространству для управления данными. При первом входе используйте учётные данные администратора (ADMIN_EMAIL/ADMIN_PASSWORD).
После авторизации интерфейс предлагает модули для настройки коллекций, просмотра и редактирования контента, управления ролями и автоматизацией.
Создание коллекции в Directus
Коллекции в Directus — это аналоги таблиц в реляционной базе данных. Они представляют собой структурированные наборы данных, где:
Каждая коллекция представляет собой подобие таблицы в БД (например: products, users, articles), каждый элемент такой коллекции является записью в таблице (например: конкретный товар, пользователь).
Поля коллекции выполняют аналогичную роль, как и колонки таблицы (например: title, price).
Функционал нашего проекта будет представлять собой две коллекции, посредством связи которых мы будем принимать и использовать данные из одной коллекции в другой.
В одной коллекции будут создаваться пользователи (авторы статей), а во второй пользователи смогут создавать свои статьи, ссылаясь на cвои профиля из первой коллекции.
Для создания коллекции нажимаем Create Collection, после чего открывается окно, где нужно ввести yказание коллекции (пример — “articles”) и указать тип нашей коллекции:
Singleton — это особый тип коллекции в Directus, которая всегда содержит только одну запись. Такие коллекции используются для хранения единичных сущностей (настройки, глобальные параметры, конфигурации). Они доступны через специальный API-endpoint без указания ID.
Так как в нашей коллекции мы будем создавать множественные записи, то Singletion оставляем выключенным.
Далее переходим к настройке дополнительных полей при создании коллекции в Directus во вкладке «Optional Fields»
Стандартные системные поля:
Поле status имеет тип данных String. Используется для workflow (например: «черновик», «опубликовано», «архив»), можно редактировать через API/интерфейс.
Поле sort имеет тип данных Integer. Используется для ручной сортировки записей (перетаскиванием в интерфейсе), можно редактировать напрямую.
Поля метаданных:
Опция date_created добавляет поле date_created (DateTime), в котором указывается дата создания коллекции. Автоматически заполняется при первом сохранении записи.
Опция user_created добавляет поле user_created (User), отображающая связь с пользователем‑создателем. Заполняется при создании записи (берётся текущий авторизованный пользователь). Отображается как ссылка на профиль пользователя, например: «Admin», в расширенном виде — с аватаркой и email (в интерфейсе Directus), в API — как ID пользователя или вложенный объект (зависит от запроса).
Опция date_updated добавляет поле date_updated (DateTime) и обновляется при каждом изменении записи.
Опция user_updated добавляет поле user_updated (User). Показывает последнего редактора.
Важно отметить, что все поля с префиксом date_ и user_ нельзя редактировать вручную. Отображаются в интерфейсе как read-only.
Так как в нашей коллекции мы хотим обеспечить базовый функционал управления контентом, то включаем поля: status для контроля публикации (черновик/опубликовано/архив), sort для ручной сортировки материалов, date_created/user_created для отслеживания автора и времени создания, а date_updated/user_updated — для мониторинга изменений.
Эти поля автоматически добавляют структуру, аудит-логи и гибкость в работу с записями, не требуя ручного ввода данных. Для коллекции статей такой набор оптимален, так как покрывает основные потребности редакторов (управление видимостью, порядком) и администраторов (анализ активности).
Далее сохраняемся, и перед нами открывается вкладка со всеми полями нашей коллекции.
Для рассмотренного нами проекта создадим поля title, excerpt, content, image.
Нажимаем «Create field», где перед нами открывается окно с настройками и определением типов создаваемого нами поля.
Поочерёдно создаём поля:
В графе Key указываем системное имя поля (обязательное, латиница, без пробелов). Именно оно в дальнейшем используется в API, пример: /items/articles?fields=title
Default Value является значением, которое будет автоматически подставлено при создании нового элемента, если поле осталось пустым. Оставляем его пустым, так как в дальнейшем мы будем самостоятельно заполнять заголовок статьи.
На уровне интерфейса можно задать Default Value в JSON‑формате в разделе Schema, Default Value при создании или редактировании поля.
Теперь добавленное нами поле отображается вместе с добавленными ранее полями «по умолчанию».
Аналогично добавляем поля:
excerpt со значениями Interface: Textarea или Input, Type: text — в нём будет отображаться краткое описание статьи.
content со значениями Interface: Rich Text или WYSIWYG, Type: text — здесь будет находиться основной HTML-контент статьи Directus.
image со значениями Interface: File, Type: uuid — данное поле позволяет прикрепить иллюстрации.
После того как мы закончили с настройкой полей в коллекции Articles, создаём вторую коллекцию с названием Authors.
Для этого перейди в Settings/Data Model/Collections. Нажмите Create Collection и настройте следующим образом:
После этого переходим к добавлению пользовательских полей
Создаём поля:
name — Key: name, Interface: Input, Type: string, Required: включаем и Default Value оставляем пустым, чтобы гарантировать уникальное и обязательное имя без автоматических значений.
bio — Key: bio, Interface: Textarea, Type: text, Required выключаем, Default Value нам также не нужен. Данное поле мы будем использовать для необязательного, но удобного многострочного описания без предустановленного текста.
avatar — Key: avatar, Interface: File, Type: uuid (связь с directus_files), Required / Default: по желанию. В этом поле пользователь сможет прикреплять изображение, но не делать его обязательным, если пользователь хочет оставить его пустым.
Итоговая структура коллекции должна выглядеть следующим образом:
После этого перейдите в раздел Content. Он позволяет работать с реальными данными, просматривать список записей коллекции (Explorer), фильтровать и сортировать их, открывать элемент и редактировать конкретные поля, включая связи и вложенные интерфейсы.
Отсюда мы переходим к нашей коллекции Authors. Здесь мы будем создавать собственные записи.
Для этого нажимаем Create Item. Там мы видим поля name — обязательно заполнить и bio, avatar — можно оставить пустыми.
После сохранения на экране должна появиться следующая запись:
Как мы можем увидеть, появились user_created и date_created, заполненные автоматически.
Реализация M2O-интерфейса в Directus
Для связи наших коллекций мы будем использовать интерфейс Many‑to‑One (M2O) — он используется для связи, когда много элементов одной коллекции относятся к одному элементу другой.
В вашем проекте коллекция articles создадим поле author, которое будет являться Many‑to‑One, и будет ссылаться на коллекцию authors.
Для этого вернёмся в коллекцию Articles. Откройте Settings/Data Model/Collections/Articles.
Нажмите Create Field, выберите Many to One интерфейс.
Заполните графы: Key: author, Related Collection: выберите authors (или directus_users), Display Template: {{name}} — эта опция определяет, как элемент из связанной коллекции будет отображаться при выборе в выпадающем списке или в связке (в нашем случае в выпадающем списке будет отображаться поле “name”). Проще говоря, шаблон на основе полей коллекции, отображает понятный, читаемый текст вместо UUID.
Сохраните поле — Directus создаст колонку author с типом uuid, FK на authors.
Теперь в форме создания/редактирования статьи появится выпадающий список авторов, добавленных нами в коллекции Authors.
Таким образом, мы создали две коллекции и построили между ними M2O связь через структуру полей.
Создание и настройка ролей в Directus
Роли в Directus — это своеобразный механизм контроля доступа, который определяет, что могут видеть и делать разные пользователи в системе. Роли работают по трём принципам: разграничение по коллекциям (каждая роль может иметь разные права для разных коллекций, к примеру: может быть разрешено чтение статей, но запрещено редактирования пользователей), настройки полей (для разных ролей можно скрыть отдельные поля), фильтры данных (автоматическое ограничение видимости).
Для создания ролей перейдите в Settings/Roles & Permissions.
Нажмите + для создания новой роли:
Назовём её Authenticated — роль для зарегистрированных пользователей. Перед нами открывается следующее окно:
Теперь вы можете заполнить описание роли и сменить иконку роли (Description, Icon — по желанию).
Далее перейдите на вкладку Policies. Нажмите Create Policy (создать новую политику).
Укажите Name: например, Authenticated App Access, установите галочку App Access = включено, оставьте Admin Access выключенным, если не нужны полные права.
Откройте в этой же вкладке окно коллекций (Add Collection) и установите необходимые права для выбранных вами коллекций, например, для коллекции articles разрешите создание своих записей и чтение всех, для authors настройте права на чтение и создание.
Должно получиться так:
После этого нажмите на галочку в верхней панели — настройки роли применятся. Для проверки создайте пользователя и назначьте ему роль. Попробуйте войти в интерфейс Directus под этой учётной записью: если App Access включён — вход возможен, роль применяется. Если отключён — вход будет запрещён, даже при правильных логинах и паролях.
Подключение API Directus к python-проекту
Directus предоставляет несколько Python-клиентов:
PyDirectus — простой синхронный REST API‑обёртка: чтение/создание/обновление коллекций и файлов.
directus-python-client (или directus-py-client) — обёртка на requests, с поддержкой CRUD операций, авторизацией и фильтрами.
py-directus — асинхронный клиент на базе HTTPX и Pydantic, удобен для asyncio‑приложений.
В статье приведём примеры с directus-python-client.
Для установки SDK в терминале пропишите
pip install directus-python-client
После инициализации настроим аутентификацию и чтение данных. Для этого пропишите следующий код python:
from directus_api import DirectusApi
api = DirectusApi(
username="user@example.com",
password="password",
endpoint="https://your-directus.amvera.io"
)
articles = api.get_items(collection="articles", limit=5)
print(articles)
Замените все значения переменных на свои соответственно.
При запуске программы вам вернётся массив данных из вашей коллекции.
get_items — это метод SDK (например, из directus-python-client), который отправляет GET‑запрос к REST API Directus. Метод упрощает работу с API, абстрагируя авторизацию, формат запроса и разбора ответа.
Он используется для получения списка элементов из указанной коллекции, например articles, authors, и др.
Для создания статей вы можете дополнить свою программу следующим кодом:
data = {
"title": "Новая статья через Python",
"excerpt": "Краткая информация",
"content": "Подробный текст статьи"
}
created = directus.create_items("articles", [data])
Метод create_items используется для массового создания записей в заданной коллекции Directus. Он отправляет POST-запрос к REST API, в теле которого содержится список объектов данных, и получает в ответ статусы создаваемых сущностей.
Обновление и удаление статей
Для обновления статей используйте метод api.update_items.
api.update_items(collection="articles", data=[{"id": article_id, "title": "Обновленный заголовок"}])
Этот метод обновляет одну или несколько записей в указанной коллекции. Вы передаёте список объектов, каждый из которых обязательно содержит "id" — SDK отправляет PATCH-запрос к REST API.
Для удаления статей можно использовать метод api.delete_item
api.delete_item_by_id(collection="articles", id=article_id)
Важно отметить, что Directus поддерживает soft-delete: если в вашей коллекции есть поле status с флагом soft_delete, то при удалении запись только помечается как удалённая. Подлинное удаление возможно только при отсутствии soft-delete или при роли администратора.
Если у пользователя нет прав Delete для этой коллекции — возвращается ошибка авторизации.
Итоги
В статье мы подробно рассмотрели:
как развернуть Directus в Amvera Cloud — легко, в пару кликов в интерфейсе, без Docker и .yaml файлов.
как спроектировать коллекции Authors, Articles, определить типы полей и отношения между ними;
и как интегрировать Directus API через Python SDK (directus‑python‑client или pydirectus) — синхронизация контента, управление данными и автоматизация.
Наш проект — полностью настроен и готов к использованию на базе Directus. Мы настроили серверную инфраструктуру на платформе Amvera, создали структуру данных с коллекциями Authors, Articles, организовали гибкие связи между ними, настроили роль‑based access control с автоматическим присвоением автора, и реализовали интеграцию с внешним API на Python.