Руководство оператора#
О документе#
Настоящий документ содержит описание работы пользователя в UI компонента DS Lab (DSLB) продукта Platform V DataSpace (APT).
Расшифровку основных понятий см. в документе "Термины и определения".
Доступ к приложению#
Для работы с визуальным редактором модели (UI) пользователю необходимо осуществить аутентификацию и авторизацию во внешней по отношению к DS Lab IAM-системе.
Адрес подключения к web-интерфейсу визуального редактора модели можно получить у администраторов, занимающихся установкой компонента.
Для работы с визуальным редактором модели рекомендуется использовать Яндекс.Браузер или Google Chrome (см. раздел "Системное программное обеспечение" документа "Руководство по установке").
Проверка ограничений на вводимые оператором данные выполняется в компоненте DS Lab в момент выпуска сервиса.
Детальное описание разграничения прав пользователей в разрезе проектов, а также его настройки приведены в разделе "Администрирование системы разграничения прав в разрезе проектов" документа "Руководство по системному администрированию".
Использование приложения оператором#
Описанная в данном разделе функциональность компонента DS Lab доступна потребителю с ролью пользователь (обычно это разработчик/архитектор/аналитик).
Работа с проектом#
Компонент DS Lab (DSLB) позволяет создать концептуальную модель данных приложения. На основе заданной модели сервис создает базу данных, работа с которой осуществляется с помощью GraphQL-запросов.
В шапке web-интерфейса DS Lab (DSLB) сосредоточены инструменты управления проектом.
Шапка web-интерфейса#
На рисунке представлен внешний вид шапки веб-интерфейса DS Lab:
На верхней линии расположены:
Слева:
Список моделей — кнопка перехода к списку моделей тенанта.
Наименование текущей модели (на рисунке — "test1").
Глобальные настройки — кнопка вызова глобальных настроек модели.
По центру — функциональные кнопки для осуществления основных операций с моделью:
Импорт — кнопка для осуществления импорта модели.
Экспорт — кнопка для осуществления экспорта модели.
Проверить — кнопка для осуществления автоматической проверки модели.
Выпустить — кнопка для осуществления выпуска новой версии модели.
Справа:
Поиск — кнопка вызова строки поиска по элементам редактора модели.
Документация — кнопка вызова локальной документации по работе в UI компонента DS Lab.
Настройки тенанта — выпадающее меню с настройками тенанта.
На нижней линии расположены:
Слева — вкладки с инструментами работы в проекте:
Редактор — основной инструмент по созданию модели данных.
Статусная модель — инструмент по созданию статусной модели проекта.
Пользовательские запросы — инструмент по созданию пользовательских SQL-запросов.
Подписки — инструмент работы с подписками.
GraphQL-конструктор — конструктор запросов, с помощью которых можно работать с созданной базой данных.
Детали — содержит детальную информацию для работы с выпущенной моделью. Также на данной вкладке можно осуществить загрузку значений для справочников.
Разрешения — интерфейс для разграничения прав в разрезе GraphQL-запросов путем определения разрешений (см. документ "Система разграничения прав для GraphQL-запросов".
Справа — кнопки вызова инструментов управления моделью:
Управление моделью (доступно на вкладке Редактор) — вызов панели для задания основных параметров модели.
Управление статусной моделью (доступно на вкладке Статусная модель) — вызов панели для создания статусной модели проекта.
Слои (доступно на вкладке Редактор) — вызов панели для управления слоями проекта.
Внешние модели (доступно на вкладке Редактор) — вызов панели для добавления внешних моделей.
Глобальные настройки модели#
Для просмотра/корректировки глобальных настроек модели нажмите кнопку Глобальные настройки:
Будет предоставлена панель Глобальные настройки модели со следующими параметрами:
Имя в Meta — позволяет вручную задать код модели в SberWorks META. Заполнять поле не надо.
Префикс таблиц в БД — символы, которые добавляются в таблицы базы данных для их уникализации. Заполнять поле не надо.
Количество агрегатов в пакете — допустимое количество агрегатов в одной транзакции изменения. Заполнять поле не надо.
Суффикс для коллекционных свойств — символы, которые добавляются к наименованию свойства класса-владельца при установке связи типа Композиция.
Допускать lastChangeDate для Compare — признак, определяющий возможность осуществления проверки на соответствие фактических значений сущности ожидаемым с помощью системного поля lastChangeDate.
Допускать удаленные элементы модели — признак, определяющий режим обратной совместимости при удалении элементов.
Контроль внешних ссылок при удалении — признак, определяющий осуществление контроля целостности внешних ссылок при удалении сущности. Заполнять поле не надо.
Генерировать элементы для выборки свойств на основе сущности — признак, определяющий параметры для выборки свойств на основе сущности.
Тип расположения полей для вычислимых выражений - признак, определяющий параметр типа расположения полей для вычислимых выражений.
Для сохранения изменений, внесенных в глобальные настройки, нажмите кнопку Изменить.
Поиск элементов модели#
Поиск элементов можно вызвать по кнопке лупы в шапке web-интерфейса:
С помощью поиска можно найти любой элемент модели, независимо от выбора текущего элемента.
При нажатии кнопки отображается строка поиска.
Осуществляется поиск требуемого класса или свойства по его наименованию. Поиск не чувствителен к регистру.
Настройки тенанта#
В правом верхнем углу шапки web-интерфейса отображается имя владельца модели (тенанта). При нажатии на него выпадает меню с настройками.
Имеется возможность:
сменить тему интерфейса, нажав на пункт Тема;
сменить пользователя, нажав на пункт Сменить тенанта;
выйти из проекта по кнопке Выйти.
Панель операций#
В левом нижнем углу редактора модели имеется панель операций.
Базовый набор операций:
Уменьшить — уменьшить масштаб модели данных.
Увеличить — увеличить масштаб модели данных.
Масштабировать — изменить масштаб модели данных до пределов видимой области и отцентрировать.
Развернуть — раскрывает расширенный набор операций.
Расширенный набор операций:
Зафиксировать — фиксация всех элементов модели для удобства перемещения по ней.
Экспорт .png — экспорт модели данных в формат .png. При этом имеется возможность задать параметры экспорта:
Настройка отображения связей модели:
Показать скелетные связи — визуальное отключение всех связей, кроме агрегатных.
Скрыть все связи — визуальное отключение абсолютно всех связей.
Показать все связи — визуальное подсвечивание всех связей.
Создание модели данных#
Создание модели данных и работа с ней осуществляется на вкладке Редактор.
Управление моделью#
Основным элементом редактора является панель Управление моделью, которая вызывается по одноименной кнопке в шапке интерфейса, находясь на вкладке Редактор модели:
На данной панели задаются основные параметры модели:
Имя — уникальный идентификатор модели, который генерируется на основе названия проекта. Имя модели нельзя изменить.
Версия — версия открытой в редакторе модели. По умолчанию — 0.0.1.
Описание — произвольное текстовое описание модели.
Также на панели Параметры модели имеются следующие элементы для работы с моделью:
Скрыть удаленные элементы — признак отображения/скрытия удаленных элементов выпущенной модели в окне редактора. Подробнее см. в разделе "Удаление элементов модели".
Блок Добавить — содержит перечень элементов, которые можно добавить в модель:
Псевдонимы — кнопка для вызова панели управления псевдонимами.
Добавление агрегата#
В основе Platform V DataSpace лежит концепция предметно-ориентированного проектирования (англ. domain-driven design). Базовой сущностью модели данных является агрегат — набор строго связанных (неразделяемых) между собой сущностей, определяющих иерархию объектов с зафиксированным корнем (родительским элементом — владельцем всей иерархии).
Чтобы добавить агрегат в модель:
Откройте редактор проекта.
Откройте меню Управление моделью. Появится заголовок Модель.
В разделе Добавить нажмите кнопку Агрегат или в контекстном меню, вызвав его с помощью правой кнопки мыши в области редактора проекта.
Агрегат появится в редакторе, а вместо параметров модели откроется окно параметров корневого класса агрегата. Название агрегата совпадает с названием корневого класса.
Каждый агрегат состоит из одного класса (корня) или нескольких классов (корень и элементы). Элемент агрегата — это класс, входящий в агрегат, но не являющийся его корнем.
Далее необходимо указать параметры корневого класса.
Примечание
Рекомендуется добавлять только требуемые классы и свойства классов, чтобы в следующих релизах модели их не потребовалось удалять. То есть перед каждым релизом модели рекомендуется более внимательно проанализировать ее структуру на наличие возможно излишних сущностей. В выпущенной модели полного визуального удаления сущности не происходит.
Добавление классов в агрегат#
Чтобы добавить элемент в агрегат:
Откройте модель.
Выберите агрегат, в который необходимо добавить класс.
Нажмите кнопку Класс в панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется окно Добавить класс.
Задайте параметры связи добавляемого класса с родительским классом:
Имя класса — имя должно начинаться с прописной буквы и состоять из латинских символов. Имя класса не может быть пустым или совпадать с названиями примитивных типов.
Тип связи — название типа связи создаваемого класса с другим классом агрегата. Возможные значения:
Наследование — устанавливается при связывании классов для построения иерархии наследования классов. Стратегия наследования определяется в параметрах базового класса. При выборе данного типа связи необходимо определить следующие параметры:
Родительский класс — имя родительского класса, с которым устанавливается связь наследования. Выбирается из выпадающего списка имеющихся в модели классов.
Абстрактный класс — флаг, определяющий класс как абстрактный.
Композиция — устанавливается для построения связи между классами в дереве агрегатов. При выборе данного типа требуется определить следующие параметры связи:
Класс-владелец — имя класса, с которым устанавливается агрегатная связь. Выбирается из выпадающего списка имеющихся в модели классов.
Тип связи с классом-владельцем — возможные значения агрегатной связи:
Один к одному — устанавливается при связывании классов в одном агрегате в отношении один к одному.
Один ко многим — устанавливается при связывании классов в одном агрегате в отношении один ко многим.
Автоименование свойств классов — автоматическое определение наименований свойств, связывающих классы. Данный параметр отображается при выборе значения в поле Класс-владелец.
Имя свойства класса — имя свойства добавляемого класса, которое будет связано с классом-владельцем. Данный параметр отображается при выборе значения в поле Класс-владелец.
Имя свойства класса-владельца — имя свойства класса-владельца, с которым будет установлена связь. Данный параметр отображается при выборе значения в поле Класс-владелец. К значению данного поля автоматически добавляется суффикс, указанный в поле Суффикс для коллекционных свойств глобальных настроек модели.
Нажмите кнопку Добавить. Класс будет добавлен в агрегат, при этом для него будет установлена указанная связь с родительским классом. Откроется панель параметров класса, где необходимо задать остальные требуемые параметры класса.
Добавленный класс уже будет иметь одно свойство (объект propertyName), параметры которого требуется задать. Далее для класса можно добавить требуемые дополнительные свойства.
Задание параметров класса#
После добавления класса в агрегат необходимо указать его параметры.
Чтобы задать параметры, выделите требуемый класс и укажите его параметры в окне управления моделью. Задать параметры класса можно также в контекстном меню, вызвав его с помощью правой кнопки мыши на выделенном классе.
Выберем элемент агрегата "ClassName" с типом связи "Наследование":
Откроется окно параметров класса, имеющее следующий вид:
Задайте параметры:
Имя — имя должно начинаться с прописной буквы и состоять из латинских символов. Имя класса не может быть пустым или совпадать с названиями примитивных типов.
Описание — произвольное описание класса.
Родительский класс — список возможных родителей класса-наследника. При выборе родительского класса устанавливается связь. Подробнее про построение связей в модели см. в разделе "Создание связей в модели данных".
Стратегия наследования — список возможных стратегий наследования. Стратегию нельзя переопределить на наследуемых классах. Доступные значения:
Таблица на каждый класс (JOINED) — значение по умолчанию. С этой стратегией у каждого класса наследования есть собственная таблица в базе данных. Такой подход обеспечивает лучшую консистентность данных.
Общая таблица (SINGLE_TABLE) — при выборе этой стратегии все сущности иерархической структуры сопоставляются с одной таблицей базы данных. Такой подход обеспечивает повышенную производительность за счет риска снижения консистентности.
Способ заполнения ID — определяет стратегию заполнения ID класса. Доступные значения:
Авто (SNOWFLAKE) — значение по умолчанию. При таком способе ID задается через алгоритм snowflake. Передача пользовательского ID запрещена.
Смешанный (AUTO_ON_EMPTY) — при таком способе ID может передаваться пользователем. Если пользователь его не передал, то ID формируется алгоритмом snowflake.
Пользовательский (MANUAL) — при таком способе ID передается исключительно пользователем.
Блокируемый — указывает, что к объекту применима пессимистическая блокировка. Во время действия такой блокировки исключена модификация данных из сторонних сессий. По завершению предполагаемой модификации гарантируется непротиворечивая запись результатов.
Блок Имплементация — позволяет устанавливать связывание интерфейса с реализующим классом (данный тип связи не является агрегатным).
Блок Индексы — позволяет индексировать свойства класса.
Блок Добавить — содержит варианты добавления элементов в класс:
Функциональные кнопки управления отображением#
На панели управления каждого элемента с вложенностью (агрегаты, классы и enum) расположены функциональные кнопки управления визуальным отображением вложенных элементов:
Выровнять по вертикали — разместить свойства в строку.
В одну колонку — разместить свойства в колонку.
Свернуть свойства.
Для агрегата так же есть выравнивание — это первая дополнительная кнопка. Выравнивание происходит по иерархии. Enums и классы не обладающие агрегатной связью выстраиваются ниже классов с агрегатной связью. Свойства классов выравниваются по вертикали.
Добавление абстрактного класса#
Абстрактный класс — это базовый класс, который не предполагает создания экземпляров.
Чтобы добавить абстрактный класс:
Откройте модель данных.
Нажмите в блоке Добавить кнопку Абстрактный класс в окне управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется панель параметров абстрактного класса.
Задайте параметры абстрактного класса:
Имя класса — имя должно начинаться с прописной буквы и состоять из латинских символов. Имя класса не может быть пустым или совпадать с названиями примитивных типов.
Описание — произвольное описание класса.
Абстрактный класс будет добавлен в модель. При этом добавленный класс уже будет иметь одно свойство, параметры которого требуется задать.
Примечание
Имеется возможность добавить абстрактный класс в агрегат. Для этого необходимо выделить требуемый агрегат и нажать кнопку Добавить класс в панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Далее необходимо определить для класса тип связи Наследование и установить флаг Абстрактный класс (см. раздел "Добавление классов в агрегат").
Параметры свойства абстрактного класса аналогичны параметрам свойства элемента агрегата.
Далее для абстрактного класса можно добавить дополнительные свойства:
Родительский класс — список возможных родителей класса-наследника.
Блок Имплементация — позволяет устанавливать связывание интерфейса с реализующим классом (данный тип связи не является агрегатным).
Блок Добавить — содержит варианты добавления элементов в класс:
Удалить класс — позволяет удалить класс.
Добавление embeddable-класса#
Embeddable-класс (встраиваемый) определяет новый тип, который будет указан у свойства после его связывания с данным классом.
Чтобы добавить embeddable-класс:
Откройте необходимую модель.
Нажмите кнопку Добавить embeddable класс в окне управление моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется панель управления абстрактным классом. Сверху расположено имя класса и кнопки выравнивания вложенных элементов.
Задайте параметры абстрактного класса:
Имя класса — имя должно начинаться с прописной буквы и состоять из латинских символов. Имя класса не может быть пустым или совпадать с названиями примитивных типов.
Описание — произвольное описание класса.
Встраиваемый класс будет добавлен в модель. При этом добавленный класс уже будет иметь одно свойство, параметры которого требуется задать.
Далее для встраиваемого класса можно добавить требуемые дополнительные свойства:
Блок Добавить — содержит варианты добавления элементов в класс:
Удалить класс — позволяет удалить класс.
Добавление класса справочника#
Справочники — классы, в которые можно загрузить данные. Справочник создается в контейнере Справочники.
Примечание
В контейнере Справочники связи между классами не являются агрегатными, как для классов обычных агрегатов. Однако классы справочники могут быть связны между собой, иметь иерархию и каскадно удаляться (более подробное описание см. в разделе "Добавление свойства").
Чтобы добавить справочник:
Откройте необходимую модель.
В окне управления моделью в блоке Добавить нажмите Класс справочник. Данное действие можно осуществить из контекстного меню, вызвав его с помощью правой кнопки мыши в области редактора проекта. Откроется панель параметров данного класса.
Задайте параметры класса. Параметры справочника аналогичны параметрам обычного класса, за исключением не применимых к данному классу параметров Способ заполнения ID, Блокируемый и Внешняя ссылка.
В модель будет автоматически добавлен контейнер Справочники, в котором будет находиться добавленный класс. При этом добавленный класс уже будет иметь одно свойство, параметры которого требуется задать.
Далее для справочника можно добавить требуемые дополнительные свойства.
При необходимости в контейнер Справочники можно добавить дополнительные классы-справочники.
Чтобы добавить дополнительный справочник:
Выберите имеющийся контейнер Справочники.
Нажмите Класс в блоке Добавить панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши.
В окне Добавить класс задайте параметры связи добавляемого класса с родительским классом. Данные параметры аналогичны тем, что определяются при добавлении элемента агрегата.
Чтобы добавить дополнительный абстрактный класс:
Выберите имеющийся контейнер Справочники.
Нажмите кнопку Добавить абстрактный класс в блоке Добавить панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется панель параметров абстрактного класса.
Задайте параметры абстрактного класса.
Читайте подробнее, как загрузить данные для класса справочник.
Добавление интерфейса#
Интерфейс — это элемент модели, который не предполагает создания экземпляров. Он содержит описание свойств, которые могут быть использованы на классе, реализующем интерфейс.
Основная задача интерфейса — дать возможность осуществлять merge-запросы посредством JAVA SDK (см. раздел "Объединение запросов к разным агрегатам" документа "Руководство прикладного разработчика" компонента DataSpace Core (DSPC) продукта Platform V DataSpace (APT)).
Чтобы добавить интерфейс:
Откройте необходимую модель.
Нажмите кнопку Интерфейс в блоке Добавить панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется панель параметров данного интерфейса. Сверху расположено имя класса и кнопки выравнивания вложенных элементов.
Задайте имя или добавьте свойство.
Добавленный интерфейс уже будет иметь одно свойство (объект propertyName), параметры которого требуется задать.
После создания интерфейса необходимо установить связь с реализующим классом путем протягивания связи или выбрать интерфейс в блоке Имплементация в окне управления классом. При этом устанавливается связь с типом Имплементация.
Добавление события#
Событие (event) — это элемент модели, который будет обрабатываться при работе сервиса подписок.
Событие может выступать как в роли самостоятельного элемента, так и являться частью одного из существующих агрегатов в модели.
Отличия события от класса:
для события определена только операция создания;
событие служит только для подписки на него;
не наследуется и имеет плоскую структуру;
допустима ссылка на родительский класс для формирования агрегатной связи. Событие, у которого отсутствует родительская ссылка, является самостоятельным агрегатом;
обработанное всеми подписками событие автоматически удаляется по истечении времени;
не реплицируется в хранилище данных и не отражается в логической модели для хранилища данных.
Чтобы добавить самостоятельное событие:
Откройте необходимую модель.
Нажмите кнопку Событие в блоке Добавить панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется панель параметров данного события. Сверху расположено имя и кнопки выравнивания вложенных элементов.
Задайте имя или добавьте свойство. Добавленное событие уже будет иметь одно свойство (объект "propertyName"), параметры которого требуется задать.
Чтобы добавить событие частью агрегата:
Откройте необходимую модель.
Выберите желаемый агрегат и нажмите кнопку Событие в блоке Добавить панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши по агрегату. Откроется панель параметров данного события. Сверху расположено имя и кнопки выравнивания вложенных элементов.
Задайте имя или добавьте свойство. Добавленное событие уже будет иметь одно свойство (объект "propertyName"), параметры которого требуется задать.
Для удаления события:
Выделите требуемое событие и нажмите кнопку Управление моделью в шапке интерфейса. Откроется окно параметров события.
В окне параметров нажмите кнопку Удалить событие.
Задание параметров события#
После добавления события необходимо указать его параметры.
Чтобы задать параметры, выделите требуемое событие и нажмите кнопку Управление моделью в шапке интерфейса. Задать параметры можно также в контекстном меню, вызвав его с помощью правой кнопки мыши на выделенном событии.
Откроется окно параметров, имеющее следующий вид:
Под названием события расположены кнопки управления отображением.
Задайте параметры:
Имя — имя должно начинаться с прописной буквы и состоять из латинских символов. Имя события не может быть пустым или совпадать с названиями примитивных типов.
Описание — произвольное описание.
Событие слияния — параметр для событий слияния/разъединения, обязательно наличие ссылки на родительский класс.
Блок Индексы — позволяет индексировать свойства класса.
Блок Добавить — содержит варианты добавления элементов в класс: Свойство.
Добавление индексов#
Для классов, входящих в агрегат (корень и элементы), а также классов-справочников можно добавить индексы.
Имеется возможность добавить простые (состоящие из одного свойства) и составные (состоящие из нескольких свойств) индексы. Порядок свойств в индексе имеет значение: следует указывать свойства в порядке от высокоселективного к низкоселективному.
Для добавления индекса:
Выберите в модели требуемый класс.
В окне управления классом, либо через контекстное меню, в блоке Индексы нажмите на иконку с плюсом.
Откроется окно Добавить индекс.
В данном окне:
Установите флаг Уникальный (при необходимости) — указывает уникальность индекса.
В поле Добавить свойство выберите из выпадающего списка требуемое свойство или последовательность свойств. Предоставляемый список свойств зависит от указанной для класса стратегии наследования:
При стратегии наследования JOINED список свойств содержит набор свойств класса, для которого добавляется индекс.
При стратегии наследования SINGLE_TABLE список свойств содержит набор свойств класса, для которого добавляется индекс, а также свойства классов, находящихся выше в иерархии наследования.
Также имеются особенности отображения списка свойств для классов, имеющих связь с embeddable-классом и классов, имеющих внешнюю ссылку (reference) на другой класс:
При добавлении индекса для класса, имеющего ссылку на embeddable-класс, в списке свойств отображаются атрибуты данного embeddable-класса.
При добавлении индекса для класса, имеющего ссылку на другой класс, в списке свойств отображаются системные атрибуты entityid и rootEntityid:
если внешняя ссылка идет на корень агрегата, отображается атрибут .entityid;
если внешняя ссылка идет на элемент агрегата, отображаются атрибуты .entityid и .rootEntityid;
Примечание
Если в качестве индекса последовательно указать атрибуты .entityid и .rootEntityid, то такой индекс равносилен индексу на саму внешнюю ссылку (индекс на атрибут, являющийся именем внешней ссылки).
Нажмите кнопку ОК, индекс отобразится в таблице блока Индексы.
Пример добавления индексов#
Имеется следующая модель данных:
В представленной модели необходимо добавить индексы для класса PerformedService. Для этого в окне управления моделью в блоке Индексы необходимо нажать иконку +. Будет предоставлено окно Добавить индекс, где в поле Добавить свойство отображается следующий список свойств:
В данном списке:
для внешней ссылки deposit на элемент DepositAccount агрегата Deposit имеется два атрибута: deposit, deposit.entityid и deposit.rootEntityid.
При этом, если в качестве индекса последовательно указать атрибуты deposit.entityid и deposit.rootEntityid, то такой индекс равносилен индексу на саму внешнюю ссылку deposit.
Добавление свойств классов#
Каждый класс имеет одно или несколько свойств. Свойства могут быть обычными или внешними ссылками.
Обычные свойства класса отображаются на желтом фоне. Внешние ссылки отображаются на фиолетовом фоне.
Добавление свойства#
Чтобы добавить в класс свойство, выберите класс и нажмите кнопку Свойство в блоке Добавить в панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши.
Откроется панель управления свойством, которая содержит параметры:
Имя свойства — имя должно начинаться со строчной буквы и должно состоять из латинских символов. Имя не может быть пустым или совпадать с названиями примитивных типов. Максимальная длина имени — 40 символов.
Описание — произвольное описание свойства.
Тип — тип свойства можно выбрать из выпадающего списка.
Коллекционное — флаг, указывающий на коллекционность свойства.
Обязательное — флаг, указывающий на обязательность свойства.
Историцирование — флаг, определяющий запись истории при изменении значения атрибута.
Не учитывать в расчете хеш — флаг, определяющий исключение из расчета хеша идемпотентности.
Вычисляемое выражение — Имеются свойства, вычисляемые на основе выражения, в которых могут участвовать другие не вычисляемые свойства этого же класса. Прямое изменение данных свойств не допустимо. Свойства класса в выражении могут указываться как с привязкой к классу "C1.firstName", так и без "firstName". Регистр не учитывается. Изменение выражения обратно несовместимо (в последующих версиях модели изменять не допустимо).
Вычисляемые свойства могут быть проиндексированы и участвовать в построении составных индексов.
Также возможны параметры при определенных обстоятельствах:
Агрегирующая связь — флаг, указывающий на агрегирующую связь свойства. Параметр устанавливается автоматически и отображается для свойства, имеющего связь с коллекционным свойством.
Каскадное удаление — флаг для свойств справочников, указывающий, что взаимосвязанные справочники при удалении родительского удалятся вместе с ним.
Значение по умолчанию — поле, в котором надо указать значение свойства по умолчанию. Необязательное поле, которое появляется после выбора типа свойства.
Длина — необязательное поле, которое появляется после выбора типа свойства "String", "Unicode string", "BigDecimal", "LocalDateTime", "OffsetDateTime".
Маска — необязательное поле, которое появляется после выбора типа свойства "String", "Text". С помощью данного поля можно задать регулярное выражение, которому должно удовлетворять значение свойства.
Масштаб — необязательное поле, которое появляется после выбора типа свойства "BigDecimal".
Добавление внешней ссылки#
Внешние ссылки — это ссылки для связи со свойствами сторонних агрегатов.
Чтобы добавить в класс внешнюю ссылку, выберите его и нажмите кнопку Внешняя ссылка в блоке Добавить, панели управления классом или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется панель управления внешней ссылкой.
Данная панель содержит такие же параметры, как и у обычного свойства класса, за исключением дополнительных флагов, определяющих тип внешней ссылки:
Не определен. Значение по умолчанию.
Тип из внешней системы. При установке данного флага появляется поле Тип для указания класса из внешней системы.
Тип из текущей модели. При установке данного флага появляется поле Тип и флаг Контроль ссылки.
Тип — поле для указания класса из текущей модели, который выбирается из выпадающего списка.
Контроль ссылки — флаг, определяющий необходимость проверки целостности ссылки. Важно отметить, что контроль на удаление является дополнительной нагрузкой на модуль.
Обновить ссылку — флаг, определяющий исключение из расчета хеша идемпотентности.
Добавление перечисления#
Перечисление — это набор статических переменных, который создается на одном уровне с агрегатами.
Данный класс определяет новый тип, который будет указан у свойства после его связывания с таким классом.
Чтобы добавить перечисление:
Откройте необходимую модель.
Нажмите кнопку Enum в блоке Добавить, в окне управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется окно управления перечислением. Сверху расположена панель выравнивания вложенных элементов.
В окне управления укажите параметры:
Имя enum — название перечисления.
Описание enum — произвольное описание перечисления.
Нажмите кнопку Значение в блоке Добавить, чтобы добавить значение перечисления. Будет открыта панель управления значением, где необходимо указать следующие параметры:
Имя — поле не может быть пустым и должно состоять только из прописных латинских букв. Максимальная длина — 40 символов.
Описание — краткое описание значения.
Подробное описание значения — произвольное подробное описание значения.
Управление расширениями enum#
Для управления расширениями нажмите кнопку Расширения на панели управления перечислением или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется панель Управление расширениями ENUM.
На данной панели:
Для добавления расширения в поле Введите имя расширения задайте имя расширения и нажмите кнопку Добавить. Имя расширения не может быть пустым, должно состоять только из латинских символов, не превышать длину в 40 символов и быть уникальным в рамках экземпляра Enum. Расширение будет распространено для всех значений перечисления. После чего необходимо указать значения расширений в колонке таблицы Значение расширения.
Для удаления расширения в поле Выберите имя расширения выберите требуемое имя из выпадающего списка и нажмите кнопку Удалить.
Управление псевдонимами#
Имеется возможность добавлять пользовательские типы свойств (псевдонимы). Пользовательский тип свойства в дальнейшем можно указать для свойства при его добавлении.
Для управления псевдонимами нажмите кнопку Псевдонимы в окне Параметры модели или в контекстном меню, вызвав его с помощью правой кнопки мыши в области редактора проекта.
Для добавления псевдонима:
Нажмите кнопку Добавить.
В поле Введите имя псевдонима задайте имя псевдонима. Имя псевдонима не может быть пустым, должно состоять только из латинских символов и не превышать длину 254 символа.
В колонке таблицы Тип укажите тип псевдонима, выбрав его из выпадающего списка.
В зависимости от выбранного типа будут автоматически заполнены значения в колонке(-ах) Длина и/или Масштаб. Данные значения при необходимости можно изменить.
Для удаления псевдонима в колонке таблицы Удалить нажмите крестик для требуемого псевдонима.
Для сохранения информации и выхода из панели нажмите кнопку ОК.
Добавление внешних моделей#
Архитектура внешних моделей строится вокруг GraphQL Apollo Federation и является идеей построения единого шлюза для нескольких моделей. Каждая модель является самостоятельным сервисом и обладает собственной GraphQL-схемой.
Добавление внешней модели позволяет связать схемы и строить общие запросы. Для этого имеется возможность привязать к текущей модели данных требуемые внешние модели, разработка которых ведется параллельно, добавив их в окне редактора текущей модели данных (создав таким образом федерацию).
Внешняя модель отображается на фиолетовом фоне и располагается в контейнере с именем "Модель: <Имя_модели>".
При этом корректировку добавленных внешних моделей невозможно осуществить из окна редактора текущей модели.
Для управления внешними моделями нажмите в шапке интерфейса кнопку Внешние модели, находясь на вкладке Редактор:
Откроется окно Внешние модели:
Для добавления внешней модели выберите ее в выпадающем списке и нажмите кнопку Добавить. В окне Внешние модели появится блок с наименованием и ID добавленной модели. Кнопка глаза в данном блоке регулирует отображение внешней модели в окне редактора.
В шапке интерфейса на кнопке Внешние модели отобразится индикатор количества внешних моделей в текущем проекте.
Для удаления внешней модели щелкните иконку корзины в блоке с наименованием требуемой модели.
Связь с внешней моделью устанавливается с помощью внешней ссылки.
После выпуска модели с внешними сервисами откроются новые инструменты и скрытые свойства:
Флаг GraphQl Stitching — на вкладке GraphQL-конструктор. Установка данного флага меняет конечную точку запросов в конструкторе и дает возможность работы с данными (только на чтение) не только с текущей моделью, но и с добавленными в нее внешними сервисами.
Ссылка на endPoint stitching — на вкладке Детали. Данная конечная точка необходима для работы с совместными данными объединенных моделей.
Создание связей в модели данных#
DS Lab (DSLB) позволяет проектировать взаимоотношения между сущностями модели данных с помощью различных типов связей. Продукт позволяет создавать связи как внутри агрегата, так и между сущностями, расположенными за пределами одного агрегата.
Существуют следующие типы связей:
Наследование — устанавливается при связывании классов. Стратегия наследования определяется в параметрах базового (неабстрактного) класса. Данный тип связи задается при добавлении классов в агрегат путем установки типа связи Наследование.
One to one — устанавливается при связывании классов в одном агрегате в отношении один к одному. Данный тип связи является агрегатным и задается при добавлении классов в агрегат путем установки типа связи Композиция.
One to many — устанавливается при связывании классов в одном агрегате в отношении один ко многим. Данный тип связи является агрегатным и задается при добавлении классов в агрегат путем установки типа связи Композиция.
Many to one — устанавливается при связывании класса с перечислением (enum) или с классом другого агрегата. Данный тип связи не является агрегатным, задается путем протягивания связи.
Many to one (однонаправленная) — устанавливается при связывании классов в отношении многие к одному. Данный тип связи не является агрегатным, задается путем протягивания связи.
Имплементация — устанавливается при связывании интерфейса с реализующим классом. Данный тип связи не является агрегатным, задается путем протягивания связи.
Примечание
Связи типа many to many можно создавать только с помощью вспомогательных сущностей.
Для создания связи путем протягивания:
Наведите указатель на сущность: класс или свойство. На верхней рамке сущности появится серый квадрат.
Потяните стрелку от данного квадрата и соедините эту сущность с другой внутри агрегата или за его пределами. Тип созданной связи будут определен автоматически на основании связываемых сущностей.
На рисунке показан пример создания связи, протягиваемой от свойства "propertyName2" корневого класса агрегата к enum "Name1".
Чтобы посмотреть параметры связи:
Выделите требуемую связь:
В шапке интерфейса нажмите кнопку Управление моделью при выделенной связи. Откроется панель Связь с параметрами:
Тип связи — название типа связи. Возможные значения описаны выше.
Откуда — название сущности, от которой исходит связь.
Куда — название сущности, к которой приходит связь.
Агрегирующая связь — признак агрегирующей связи.
Внешняя ссылка — указывает на связь между сущностями, расположенными в разных агрегатах.
Для удаления связи нажмите кнопку Удалить связь на панели Связь или в контекстном меню, вызвав его с помощью правой кнопки мыши.
Для настройки отображения связей в модели обратитесь к панели операций, расположенной в левом нижнем углу рабочего окна. На панели операций имеются следующие функциональные возможности: Показать скелетные связи, Скрыть все связи, Показать все связи.
Разделение модели на слои#
DS Lab (DSLB) позволяет разделять модель на слои, не разделяя данные по разным хранилищам. Данную функциональность полезно использовать как для разработки нескольких независимых друг от друга модулей, имеющих общее хранилище — единую базу данных, так и при длительном ведении модели. Разделение на слои позволяет избежать громоздкости, упрощая взаимодействие с сущностями.
Физически слои представляют собой xml-файлы, добавляемые в структуру проекта.
Для вызова панели управления слоями нажмите в шапке интерфейса кнопку Слои, находясь на вкладке Редактор:
Откроется панель Слои, в заголовке которой расположены кнопки управления слоями:
Добавить слой — кнопка добавления нового xml-файла в структуру проекта.
Добавить директорию — кнопка добавления новой директории в структуру проекта.
Свернуть слои — кнопка для визуального сворачивания дерева слоев.
По умолчанию на панели отображается корневая директория с именем проекта (на представленном рисунке — "test1"), содержащая слой root.
Root — базовый слой, в котором будет вестись вся разработка при отсутствии других слоев. В данный слой невозможно добавлять директории и файлы. Также невозможно удалить данный слой или изменить его наименование.
Невозможно удалить или изменить наименование корневой директории с именем проекта. В данную директорию можно добавить одну директорию для ответвления вашего проекта.
Создание слоя проекта#
Для создания слоя выполните следующие действия:
Добавьте новую директорию.
Для этого на панели Слои выберите директорию, в которую требуется добавить новую директорию, и нажмите кнопку добавления с изображением папки. Появится окно создания новой директории:
Укажите наименование добавляемой директории.
Если хотите сразу добавить в новую директорию файл, укажите его наименование в поле Имя файла или оставьте наименование по умолчанию.
Чтобы не добавлять файл в новую директорию, необходимо снять флаг Добавить файл в новую директорию.
Нажмите Ок. В дерево проекта будет добавлен новый слой (на рисунке — "fileName1"):
При этом автоматически будет открыта рабочая область нового слоя. Его наименование отобразится в шапке интерфейса DS Lab рядом с заголовком модели:
Теперь вы можете вести разработку части проекта, определяемую слоем.
Работа со слоями проекта#
Внимание!
Разделение модели на слои необходимо выполнять строго по агрегатам. Нельзя создавать корень агрегата в одной частичной модели, а зависимый класс — в другой частичной модели.
Также нельзя оформлять внешние ссылки из одной частичной модели на классы другой модели, которые не являются корнем агрегата! Допустимо оформлять внешние ссылки только на классы, являющиеся корнями агрегата.
Выбор слоя определяет область редактирования. Если имеется необходимость опираться на соседние модули, компонент позволяет визуально включить эти модули в область редактирования. Выбор требуемых модулей осуществляется с помощью чекбоксов. Например:
Данный пример показывает возможность, работая с элементами слоя "fileName2", наблюдать элементы слоя "fileName" и проводить с ними связи.
Также можно объединять файлы и директории в одну директорию. Воспользуйтесь способом "drag and drop", чтобы переносить элементы, меняя структуру.
Созданные директории и слои можно переименовать, а также удалить. При наведении курсора мыши на наименование директории или слоя появляются кнопки для редактирования и удаления:
Экспортируя модель, состоящую из нескольких слоев, в zip-архиве будет сохранена структура панели Слои с ее вложенностью. Подробнее об экспорте см. описание в разделе "Экспорт и импорт проекта".
Создание статусной модели#
Продукт позволяет создать статусную модель проекта.
Для создания статусной модели перейдите на вкладку проекта Статусная модель.
В данной вкладке доступна кнопка вызова панели управления статусной моделью:
При нажатии на данную кнопку открывается панель Статусная модель:
Работа со статусами начинается с добавления требуемых наблюдателей. Для этого:
На панели управления статусной моделью нажмите кнопку + в блоке Наблюдатели. Откроется окно Добавить наблюдателя.
Укажите параметры наблюдателя:
Название — имя не может быть пустым, должно состоять только из латинских символов и не превышать длину 31 символ.
Описание — произвольное описание, не превышающее длину 254 символа.
Нажмите кнопку Добавить. Наблюдатель будет добавлен в блок Наблюдатели панели Параметры статусной модели:
В блоке расположены имя наблюдателя ProjectMain, напротив него активные кнопки редактирования и удаления. При нажатии на плюс слева от имени раскроется панель с описанием.
Далее можно перейти к процессу добавления статусов.
Добавление статусов#
Статусные модели строятся для классов модели данных. Определяются наблюдатели, для которых добавляются статусы и переходы между ними.
Для создания статусной модели для класса:
Перейдите на вкладку проекта Статусная модель.
Нажмите кнопку Контейнер статусов в блоке Добавить на панели управления моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши. Откроется окно Добавить класс.
В данном окне укажите:
Имя класса — выбирается из выпадающего списка, содержащего классы модели.
Наблюдатель — выбирается из выпадающего списка наблюдателей.
Нажмите кнопку Добавить. Отобразится выбранный класс, содержащий выбранного наблюдателя. Наблюдатель в свою очередь будет содержать статус (объект statusCode). Начальный статус наблюдателя отображается в модели на голубом фоне.
Определите параметры статуса. Для этого:
Выделите статус.
Укажите параметры в панели управления статусом statusCode или в контекстном меню, вызвав его с помощью правой кнопки мыши:
Код статуса — имя (код) статуса не может быть пустым, должно начинаться с буквенного символа и состоять только из латинских символов, цифр и символа "_". Имя не должно превышать длину 80 символов.
Описание статуса — произвольное описание.
Начальный — флаг устанавливается автоматически для начального статуса у текущего наблюдателя.
Для добавления дополнительного наблюдателя для класса:
Выберите требуемый класс.
Нажмите кнопку Наблюдатель в блоке Добавить на панели управления статусной моделью или в контекстном меню, вызвав его с помощью правой кнопки мыши.
На панели Добавить наблюдателя в поле Наблюдатель выберите требуемого из выпадающего списка.
Нажмите кнопку Добавить. Будет добавлен выбранный наблюдатель, содержащий статус (объект statusCode).
Выделите статус и укажите его параметры, как описано выше.
Имеется возможность включить запись истории изменений статусов требуемого класса. Для этого выберите требуемый класс и на панели управления классом установите для него флаг в блоке История изменений. Установить данный флаг можно также в контекстном меню, вызвав его с помощью правой кнопки мыши на выделенном классе.
Для добавления дополнительного статуса наблюдателю:
Выберите требуемого наблюдателя.
Нажмите кнопку Статус в блоке Добавить на панели управления наблюдателем или в контекстном меню, вызвав его с помощью правой кнопки мыши. Для наблюдателя будет добавлен дополнительный статус. Дополнительный статус отображается в модели на желтом фоне.
Выделите статус и укажите его параметры, как описано выше.
Создание переходов в статусной модели#
Создание переходов между статусами осуществляется путем протягивания. Для создания перехода:
Наведите указатель на статус. На верхней рамке появится серый квадрат.
Потяните стрелку от данного квадрата к другому статусу внутри класса.
Примечание
Создание перехода между статусами разных классов запрещено. Обязательно наличие перехода, исходящего из начального статуса, если статусная модель содержит более одного статуса.
На рисунке показан пример создания перехода между статусами:
Чтобы посмотреть параметры перехода, нажмите на него. Откроется панель Параметры связи, содержащая следующие параметры:
Откуда — название сущности, от которой исходит связь.
Куда — название сущности, к которой приходит связь.
Выпуск модели#
После завершения разработки концептуальной модели данных ее необходимо выпустить.
Для этого в шапке интерфейса нажмите кнопку Выпустить.
DS Lab (DSLB) запустит автоматические проверки. Если не будет найдено ошибок, запустится выпуск модели, в процессе которого будет создана соответствующая база данных. Время выпуска зависит от сложности модели.
Примечание
Запустить автоматическую проверку модели можно на любом этапе разработки.
После выпуска модели становятся доступны для работы следующие вкладки web-интерфейса: GraphQL-конструктор, Детали, Разрешения.
Для выпущенной модели на панели управления моделью появятся поля с указанием текущей и выпущенной версии модели.
Автоматическая проверка модели#
На любом этапе разработки вы можете нажать кнопку Проверить в шапке интерфейса.
После этого появится сообщение о найденных ошибках или успешный статус. Все найденные ошибки будут описаны в появившемся сообщении и их следует исправить до следующего выпуска модели.
Удаление элементов модели#
В выпущенной модели имеется возможность удалить и восстановить такие объекты модели, как агрегат, класс и свойство.
Если возникла необходимость удалить объект, это возможно сделать следующим образом:
Выделив требуемый объект и нажать кнопку Управление моделью в шапке интерфейса.
На панели управления параметрами объекта нажать кнопку Удалить <вид объекта>.
Удаление также можно осуществить из контекстного меню, вызвав его с помощью правой кнопки мыши на выделенном объекте. При этом объект не будет полностью удален из модели, а только визуально затемнен. В базе данных он будет помечен, как "deprecated".
Для того чтобы визуально скрыть в окне редактора удаленные элементы модели, необходимо установить флаг Скрыть удаленные элементы на панели параметров модели.
В дальнейшем удаленный объект можно восстановить, выделив его и нажав зеленую кнопку Восстановить <вид объекта> на панели параметров объекта, либо через контекстное меню.
Примечание
Удаление классов в выпущенной модели возможно осуществить в восходящем порядке, начиная с нижнего. Корневой класс удалить нельзя.
Экспорт и импорт проекта#
DS Lab (DSLB) позволяет экспортировать модель данных в формате xml.
Чтобы экспортировать модель данных, нажмите кнопку Экспорт в шапке интерфейса.
Для импорта модели данных, описанной в формате xml, нажмите кнопку Импорт в шапке интерфейса.
В процессе импорта сервис проверяет корректность описания и сообщает о возникших ошибках.
Пример модели#
В качестве примера можно импортировать модель данных для промоакции.
Примечание
Созданная на основе этой модели база данных используется в примерах выполнения GraphQL-запросов.
<model model-name="ds_mynewpromo_3e944f04_1fb0_430b_b15f_35" description="Модель данных для промоакции" version="0.0.2">
<enum name="GiftKind">
<value name="TSHIRT"/>
<value name="MUG"/>
<value name="CAP"/>
</enum>
<class name="Gift" label="Описание подарка" lockable="false" strategy="JOINED" is-abstract="false">
<property name="serialNumber" type="STRING" length="254" mandatory="true"/>
<property name="vendor" type="GiftVendor" label="Компания производитель подарка" parent="true"/>
<property name="kind" type="GiftKind" label="Тип подарка. Возможные типы заданы в перечислении: кепка (CAP), футболка (TSHIRT), кружка (MUG)."/>
<index unique="true">
<property name="serialNumber"/>
</index>
</class>
<class name="GiftVendor" label="Описание компании, которая предоставляет тот или иной подарок для промоакции" lockable="false" strategy="JOINED" is-abstract="false">
<property name="name" type="STRING" label="Название компании" length="254" mandatory="true"/>
<property name="gifts" type="Gift" label="Коллекция подарков, предоставляемых компанией" collection="SET" mappedBy="vendor"/>
</class>
<class name="VoucherSerie" label="Серия ваучеров, выпускаемых в рамках промоакции" strategy="JOINED" is-abstract="false">
<property name="code" type="STRING" length="254"/>
<property name="startedAt" type="LOCALDATE" label="Начало срока действия акции"/>
<property name="activeTo" type="LOCALDATE" label="Окончание срока действия акции"/>
<property name="vouchers" type="Voucher" label="Коллекция ваучеров в рамках серии" collection="SET" mappedBy="serie"/>
<index unique="false">
<property name="code"/>
<property name="startedAt"/>
</index>
</class>
<class name="Voucher" label="Описание ваучера" strategy="JOINED" is-abstract="false">
<property name="serie" type="VoucherSerie" label="Серия ваучера" parent="true"/>
<property name="code" type="STRING" label="промокод" length="254"/>
<property name="issuedAt" type="LOCALDATETIME" label="Дата выдачи подарка по ваучеру" length="3"/>
<reference name="gift" type="Gift" label="Подарок, на который может быть потрачен ваучер"/>
<index unique="true">
<property name="code"/>
</index>
</class>
<class name="GiftRequestCounter" label="Счетчик запроса подарков. Необходим для учета запросов закончившихся подарков" strategy="JOINED" is-abstract="false">
<property name="counter" type="INTEGER" label="Счетчик запросов подарков определенного типа"/>
<property name="lastRequest" type="LOCALDATETIME" label="Дата последнего запроса" length="3"/>
<property name="kind" type="GiftKind" label="Тип подарка. Возможные типы заданы в перечислении: кепка (CAP), футболка (TSHIRT), кружка (MUG)."/>
</class>
<status-classes class="Voucher">
<stakeholder code="VoucherMain" name="Основной статус ваучера"/>
</status-classes>
<statuses class="Voucher" historical="false">
<stakeholder-link code="VoucherMain">
<status code="OPEN" name="Открыт" initial="true">
<to status="ISSUED"/>
</status>
<status code="ISSUED" name="Использован" initial="false"/>
</stakeholder-link>
</statuses>
</model>
Порядок элементов при выгрузке#
Для удобства ручного редактирования и сравнения сторонними инструментами изменения модели при выгрузке модели задан следующий порядок для атрибутов и элементов:
Порядок следования элементов:
imports,
type-defs,
external-types,
enum (value (extension)),
interfaces (id, property, reference),
classes (id, property, reference, index (property), cci-index (property)),
query (param, id, property, implementations по dbms, причем без dbms — первая),
status-classes (stakeholder по code),
statuses (stakeholder-link по code (status по code, (to по status))),
layout.
Сортировка атрибутов:
У элемента model: model-name, table-prefix, component-code, description, version, versioned-entities.
У остальных элементов: class, code, name, status, extends, implements, is-abstract, is-dictionary, embeddable, type, length, scale, precision, parent, collection, mappedBy, default-value, mandatory, unique, external-link, mask, label, value, extension, lockable, strategy, class-access, historical, external-reference, final-class, id-prefixed, changeable, /integrity-check, status-reason, isDeprecated, description.
Выполнение пользовательских SQL-запросов#
Для создания пользовательского SQL-запроса перейдите на вкладку Пользовательские запросы проекта.
В данной вкладке отображается список существующих запросов.
Список содержит следующие колонки:
Имя — уникальный идентификатор. Имя запроса не может быть пустым, должно начинаться с заглавной буквы, не содержать кириллицы, не совпадать с названиями примитивных типов.
Метка — label xml-модели.
Описание — произвольное текстовое описание.
В списке поддерживается сортировка по имени, осуществляемая при нажатии на заголовок Имя в таблице.
Запрос можно отредактировать, нажав кнопку вызова окна корректировки.
При необходимости можно удалить строку параметров с помощью кнопки корзины, расположенной справа от строки. Перед полным удалением ожидается подтверждение.
Создание пользовательского запроса#
Если список пуст, создайте первый запрос, нажав кнопку Добавить запрос.
Открывшееся модальное окно является агрегатором запросов.
Основные параметры для создания запроса:
Имя — уникальный идентификатор. Имя запроса не может быть пустым, должно начинаться с заглавной буквы, не содержать кириллицы, не совпадать с названиями примитивных типов.
Метка — label xml-модели.
Описание — произвольное текстовое описание.
Добавить id — добавляет уникальный идентификатор запроса.
Блок Параметры. Задавать параметры необходимо в случае использования их в SQL-запросах. Если ни одного параметра не добавлено, нажмите кнопку Добавить, расположенную в правом нижнем углу блока. При этом в таблице появится новая строка с полями для заполнения:
Имя — уникальный идентификатор параметра. Не может быть пустым, должно начинаться со строчной буквы, состоять только из латинских символов и не превышать длину 40 символов.
Тип — тип можно выбрать из выпадающего списка.
Метка — label xml-модели.
Коллекционное — флаг, указывающий на коллекционность свойства.
Базовое значение — начальное значение, зависит от типа, поэтому нельзя ввести значение до выбора типа.
Описание — произвольное текстовое описание.
При необходимости можно удалить строку параметров с помощью кнопки корзины, расположенной справа от строки. Перед полным удалением ожидается подтверждение.
Блок Поле результата — параметры, которые ожидаются в результате поиска. Если ни одного параметра не добавлено, нажмите кнопку Добавить, расположенную в правом нижнем углу блока. При этом в таблице появится новая строка с полями для заполнения:
Имя — уникальный идентификатор параметра. Не может быть пустым, должно начинаться со строчной буквы, состоять только из латинских символов и не превышать длину 40 символов.
Тип — тип можно выбрать из выпадающего списка.
Метка — label xml-модели.
Описание — произвольное текстовое описание.
При необходимости можно удалить строку параметров с помощью кнопки корзины, расположенной справа от строки. Перед полным удалением ожидается подтверждение.
Блок Описание SQL-запроса — базовый интерфейс написания запросов. Если ни одного запроса не добавлено, нажмите кнопку Добавить, расположенную в правом нижнем углу блока. При этом в таблице появится новая строка с полями для заполнения:
dbms — группа параметров для выбора баз данных, к которым будет совершен запрос.
Значение — ячейка с редактором для написания sql-запроса.
При необходимости можно удалить блок параметров с помощью кнопки корзины, расположенной справа от блока. Перед полным удалением ожидается подтверждение.
После указания всех требуемых параметров для сохранения запроса нажмите кнопку Сохранить. Если запрос сохранять не требуется, нажмите кнопку Отмена для сброса заполненных параметров и закрытия окна.
Управление подписками#
Инструментарий подписок реализует универсальный (повторно используемый разными потребителями) механизм, позволяющий DataSpace участвовать в событийном обмене (выступать в роли провайдера событий).
Работу с подписками необходимо начинать с создания в модели данных события (event).
Управление подписками осуществляется на вкладке Подписки. На данной вкладке отображается таблица со списком имеющихся подписок. Если подписок нет, начните с их добавления.
Добавление подписки#
Перейдите на вкладку Подписки и нажмите Добавить подписку. Откроется окно с параметрами:
id — уникальный идентификатор подписки.
Внимание!
Значение "0" зарезервировано системой.
Имя — наименование подписки.
Описание — текстовое описание подписки.
Способ публикации — способ публикации (REST,KAFKA,GRAPHQLSUBS).
Тип событий — тип событий (entity name), на которые осуществляется подписка.
Асинхронная отправка — использование асинхронной отправки.
Приостановление при ошибке — приостановление отправки при первой ошибке (true/false).
Время окончания действия — время окончания действия подписки.
Callback — URL для публикации сообщения (для REST) или <наименование_кластера>:<наименование_топика> в случае Kafka.
Фильтр событий — строковое выражение для фильтрации записей события. С описанием формата строковых выражений можно ознакомиться в документе "Строковые выражения" компонента DataSpace Core (DSPC) продукта Platform V DataSpace (APT).
GraphQL-запрос — текст GraphQL-запроса для чтения дополнительных данных. С GraphQL-API можно ознакомиться в документе "Протокол GraphQL" компонента DataSpace Core (DSPC) продукта Platform V DataSpace (APT). Текст запроса может содержать placeholder формата ${<наименование_свойства_события>} (наименование свойства JPA-класса события entity,
nameкоторого прописан в полеeventTypeу конкретного subscription в subscriptions.xml). Перед выполнением GraphQL-запроса placeholders будут заменены на соответствующие значения свойств события.Спецификация JSON — спецификация трансформации JSON-данных в JSON-сообщение. Для трансформации по умолчанию используется библиотека JOLT, поэтому для описания преобразования в параметре template используется формат спецификации этой библиотеки. Исходные данные для трансформации по шаблону имеют общий вид:
{ "event": { <атрибуты события> }, "data": { <результат выполнения graphql-запроса. Если graphql-запрос в подписке не задан или не вернул данных - элемент пустой> } }Заголовки сообщения — спецификация дополнительных заголовков сообщения. Формат: <наименование_заголовка>=<значение>, где <значение> может содержать placeholders формата ${<наименование_свойства_события>}, которые будут заменены аналогично логике, описанной для поля
query.Количество повторений — количество повторных попыток публикации (актуально только для target == REST).
Тайм-аут — тайм-аут публикации, в миллисекундах (актуально только для target == REST).
Задержка — задержка между повторными попытками публикации, в миллисекундах (актуально только для target == REST).
Работа с данными с использованием протокола GraphQL#
Примечание
В данном разделе приведена краткая инструкция по работе с данными. Более подробную информацию можно посмотреть в документе "Протокол GraphQL" компонента DataSpace Core (DSPC) продукта Platform V DataSpace (APT).
После выпуска модели в Platform V DataSpace создается база данных, к которой можно обращаться с помощью GraphQl-запросов.
С описанием элементов схемы GraphQL можно ознакомиться в разделе "Элементы схемы" документа "Протокол GraphQL" компонента DataSpace Core (DSPC) продукта Platform V DataSpace (APT).
Все запросы отправляются с помощью HTTP-метода POST. Тело запроса зависит от операции, которая выполняется: запрос или изменение данных.
Запросы можно проектировать на вкладке GraphQL-конструктор:
Вкладка содержит:
флаг GraphQl Stitching, определяющий возможность формирования общих запросов к связанным моделям (при наличии связей с внешними моделями);
редактор запросов;
панель ответов Platform V DataSpace;
историю запросов, которая вызывается по кнопке HISTORY;
вкладку DOCS со справочником запросов и мутаций;
вкладку SCHEMA с JSON-схемой сущностей базы данных;
вкладку QUERY VARIABLES, в которой можно задавать переменные запросов;
вкладку HTTP HEADERS, в которой можно задавать заголовки запросов.
Примечание
При выходе из SmartMarket Studio редактор автоматически сохраняет созданные запросы.
В данном описании приведены примеры запросов к базе данных, созданной на основе модели, которая представлена в разделе "Экспорт и импорт проекта".
Запросы данных#
Запросы данных выполняются с помощью ключевого слова query.
Примечание
Список доступных запросов можно найти в разделе QUERIES справочника DOCS.
query {
#Запрос возвращает массив elems со списком компаний
searchGiftVendor {
#Список полей, которые будет содержать ответ
elems {
#Идентификатор компании
id
name
}
}
}
При работе с несколькими запросами на одной вкладке редактора, после ключевого слова query следует указать название каждого из них.
query searchGiftVendor {
#Запрос возвращает массив elems со списком компаний
searchGiftVendor {
#Список полей, которые будет содержать ответ
elems {
#Идентификатор компании
id
name
}
}
}
С подробным описанием элемента "Запрос" схемы GraphQL можно ознакомиться в разделе "Запрос" документа "Протокол GraphQL" компонента DataSpace Core (DSPC) продукта Platform V DataSpace (APT). Подробное описание видов запросов приведено в разделе "Виды запросов" данного документа.
Работа с историчными данными#
При работе с историчными данными (когда для атрибута указан признак historical="true") возможны три вида запросов:
Запрос состояния на момент времени:
query State {
getStateVoucherSerie(
id:"7067113783378706433"
date: "2022-02-21T15:00:00Z"
)
{code}
}
Запрос списка состояний:
query States {
getStatesVoucherSerie(
id:"7067113783378706433"
)
{
elems{
code
sysHistoryTime
}
}
}
Запрос списка изменений:
query History {
getVoucherSerieHistory(
id:"7067113783378706433"
)
{
elems{
code
sysHistoryTime
}
}
}
Примечание
Под состоянием понимается получение значений для всех запрошенных историцируемых атрибутов, а под изменением понимается получение значений только для изменившихся в рамках транзакции историцируемых атрибутов.
Фильтрация результатов#
Результаты запроса можно фильтровать.
Для этого опишите условия фильтрации в виде строки в параметре запроса cond.
query searchVouchers {
#Результат запроса будет содержать открытые ваучеры с кодом promo2
searchVoucher(cond: "it.code=='promo2' && it.statusForVoucherMain.code=='OPEN'") {
elems {
id
code
statusForVoucherMain{
code
name
}
gift{
entity{
type
vendor{
name
}
id
kind
}
}
serie {
id
startedAt
activeTo
}
}
}
}
Мутации данных#
В терминах GraphQL изменение данных называется мутацией.
Мутации данных выполняются в рамках пакета packet.
Примечание
Список доступных мутаций можно найти в разделе MUTATIONS справочника DOCS.
После вызова мутации следует указывать содержимое ответа.
mutation {
packet {
#Создание компании, предоставляющей подарки
createGiftVendor(input: {
name: "Sberdevices"
}){
#Ответ будет содержать идентификатор компании
id
}
}
}
При работе с несколькими мутациями на одной вкладке редактора, после ключевого слова mutation следует указать название каждой из них.
mutation createVendor {
packet {
createGiftVendor(input: {
name: "MyVendor"
}){
id
}
}
}
Создание нескольких сущностей#
Внутри одной мутации можно передавать пакеты для изменения нескольких сущностей. В этом случае каждый пакет должен иметь уникальное название.
mutation createVendor {
p1: packet {
createGiftVendor(input: {
name: "MyVendor"
}){
id
}
}
p2: packet {
createGiftVendor(input: {
name: "AnotherVendor"
}){
id
}
}
}
Предотвращение дублирования#
Чтобы избежать дублирования данных при повторных запросах, используйте ключ идемпотентности idempotencePacketId.
mutation createGift {
#Уникальность подарка опредляется по его серийному номеру
p1:packet(idempotencePacketId:"123456") {
createGift(input:{
kind: TSHIRT
vendor: 6966642249338191873
serialNumber: "123456"
}){id}
}
}
Если подарок с заданным серийным номером уже существует в базе, в результате повторного выполнения запроса сервис вернет идентификатор подарка.
Оптимистические блокировки#
Для использования оптимистической блокировки записей используйте параметр aggregateVersion.
mutation updateRequest {
packet(aggregateVersion:1){
updateGiftRequestCounter(input:{
id: 6967338499520528385
counter:1
lastRequest:"2021-05-09T20:20:00.000"
}) {
counter
lastRequest
}
}
}
Получение деталей для работы с моделью#
После выпуска модели на вкладке Детали имеется возможность получения детальной информации для работы с выпущенной моделью:
На вкладке отображается ряд точек доступа (endpoints):
packet и search используются при работе с сервисом через Java SDK;
dictionaries — загрузка справочных данных;
graphql — доступ для Backend-приложений (авторизация посредством application key/secret key на API gateway);
stitching — доступ к подключенным внешним моделям для Backend-приложений;
jwt graphql — доступ посредством JWT через систему разграничения прав. Описание системы разграничения прав в разрезе GraphQL-запросов см. в документе "Система разграничения прав для GraphQL-запросов").
Также на данной вкладке имеется ссылка на панель мониторинга базы (см. раздел "Мониторинг работы сервиса" в документе "Руководство системного администратора") — ссылка на dashboard.
Можно скачать артефакты SDK для взаимодействия с серверной частью DataSpace по кнопке Скачать.
Можно скачать Шаблонный проект по кнопке Скачать.
Загрузка значений для справочников#
На вкладке Детали нажмите кнопку Загрузить напротив заголовка Справочники.
Примечание
Для того чтобы обновить значения справочников, процедуру загрузки необходимо выполнить повторно.
Например, имеется следующий контейнер Справочники:
Для получения значений справочников необходимо загрузить следующий JSON-файл:
[
{
"type": "Department",
"objects": [
{
"id": "1",
"code": "161",
"name": "Ростов-на-Дону"
},
{
"id": "2",
"code": "123",
"name": "Москва"
},
{
"id": "3",
"code": "198",
"name": "SPB"
}
]
}
]
Часто встречающиеся проблемы и пути их устранения#
Возникающие проблемы может решать потребитель с ролью пользователь (обычно это разработчик).
Ошибка валидации модели#
После внесения изменений в модель она не проходит валидацию.
Возможная причина: внесение обратно несовместимых изменений.
Решение: устранить обратно несовместимые изменения в модели данных. Со списком несовместимых изменений можно ознакомиться в разделе "Несовместимые изменения" документа "Порядок внесения изменений в модель данных" компонента DataSpace Core (DSPC) продукта Platform V DataSpace (APT).
Проблема громоздкости модели#
Возможные пути решения:
На панели управления элементами со вложенностью есть функциональные кнопки, влияющие на отображение. Описание кнопок см. в разделе "Функциональные кнопки управления отображением".
Разделяйте свою модель на слои. Проект будет оставаться относительно одной базы, но иметь возможность отключить отображение части модулей. Подробную информацию о делении на слои см. в разделе "Разделение модели на слои".
Обратитесь к панели операций в левом нижнем углу редактора. В ней собраны функции позволяющие влиять на взаимодействие с моделью и ее визуальное отображение.
Параметры настройки#
Дополнительных параметров настройки не предусмотрено.
Параметры безопасности, касающиеся разграничения прав для GraphQL-запросов, описаны в документе "Система разграничения прав для GraphQL-запросов".
Правила эксплуатации#
При использовании системы разграничения прав GraphQL-запросов рекомендуется ознакомиться с документом Система разграничения прав для GraphQL-запросов.
При загрузке справочных данных используется формат JSON. Детальная структура файла описана в разделе "Работа с локальными справочниками" документа "Руководство по ведению модели" в документации компонента DSPC. Пример JSON-файла приведен в разделе "Загрузка значений для справочников".
При импорте модели используется формат xml. Детальная структура файла с правилами описания объектов модели приведены в документе "Руководство по ведению модели" компонента DSPC. Пример xml-файла модели представлен в разделе "Пример модели".