Для чего нужна virtual-сущность
Виртуальная сущность (virtual) читает данные существующих persistent-сущностей и собирает из них нужный вам ответ. Можно выбрать обычные поля, данные связанных записей и коллекции. Своя таблица, миграции для хранения и операции записи для такой сущности не создаются.
Например, сайт может одним запросом к проекции получить PageBlock, связанную Page и коллекцию BlockItem. Не понадобится отдельно запрашивать каждую сущность. При этом ограничения размера ответа и пагинация сохраняются: все записи без ограничения в один ответ не попадут.
Создать и выбрать поля
- Создайте сущность с Kind
virtual. - Выберите persistent Source entity, например PageBlock.
- Включите необходимые Read operations: List и/или Get by ID.
- Выберите скалярные поля источника.
- Для объявленных связей включите Include relation и выберите Target fields.
- Сохраните конфигурацию; для дальнейшего редактирования используйте Configure source and fields / Save fields.
Источником может быть persistent-сущность, но не другая проекция. Доступны поддерживаемые связи одного уровня; произвольного expand на любую глубину нет. Включайте поля, которые действительно нужны клиенту.
Output name и таблица Fields
Через Output name задайте имя поля в ответе API. Например, исходное bodyMarkdown можно вернуть как body, не переименовывая колонку БД. Допустимы lowerCamelCase и snake_case с маленькой буквы. Если оставить настройку пустой, сохранится исходное имя.
В Fields видны выбранные типы и возможности полей. У связанной сущности есть бейдж и действие Expand fields: оно раскрывает вложенные поля под строкой. Нажатие на саму строку открывает настройки. Так состав ответа можно проверить прямо в таблице.
List behavior на разных уровнях
Включите Searchable, Filterable и Sortable у выбранных скалярных полей, если тип поддерживает эти действия. Эти возможности задаются для самой проекции и не зависят от настроек persistent-источника.
| Где включено | Что меняет запрос |
|---|---|
| Поле PageBlock | Корневой список блоков |
| Скаляр выбранного belongsTo Page | Корневые блоки по значению связанной страницы |
| Поле коллекции items | Список элементов внутри каждого блока |
Если сортировать по полю belongsTo Page, изменится порядок корневых блоков. Отдельный список страниц при этом не создаётся. Сортировка по полю items работает внутри коллекции каждого блока и не меняет порядок самих блоков.
Лимиты и порядок коллекции
У hasMany задайте Default limit, Maximum limit, Order field и Direction. Оба лимита должны быть положительными целыми числами, Maximum — не меньше Default. Для Order field доступны подходящие выбранные скалярные поля целевой сущности; image/gallery использовать нельзя.
Например, выберите для items поле position, направление Ascending, Default limit 20 и Maximum limit 100. Сервер будет использовать этот порядок по умолчанию независимо от Sortable. Включать Sortable нужно, если хотите позволить клиенту менять порядок своим запросом.
Ответ коллекции содержит items, total, limit и offset. Сравнивайте total с числом полученных записей: если записей меньше, учитывайте следующие страницы. Параметры поиска, фильтров и сортировки дочерних записей относятся к конкретной коллекции и не заменяют параметры корневого списка.
Публикация и видимость
Откройте Access, разрешите нужные external List/Get и задайте отдельные серверные условия для PageBlock, Page и items. Например: блок видим, страница опубликована, элемент видим и его title не пуст. Правило дочерней коллекции ограничивает только её содержимое: пустая коллекция не исключает родителя из ответа.
Доступ исходных persistent-сущностей автоматически не переносится в virtual. Перед включением Anonymous проверьте собственные правила проекции и все выбранные поля.
Что увидит администратор
В системе администрирования проекцию можно только просматривать. Связанные данные доступны для чтения, коллекции имеют счётчик и страницы. Административное чтение media требует прав на исходную persistent-сущность. В external-ответе изображения представлены готовыми ссылками на варианты размеров; подробнее — Images.
Если сменить Source entity и подтвердить действие, редактор очистит выбранные поля в черновике. Выберите поля нового источника перед сохранением. Finish/Save fields сохраняет модель, а код обновляется после Generate.
Дополнительно: виртуальные сущности через CLI.