Публикация объектов позволяет использовать их вне "Первой Формы", внешними системами. При публикации создаются ссылки (Url), по которым можно обратиться к объектам напрямую. В настоящее время в "Первой Форме" можно публиковать SQL View и смарт-пакеты (пакеты действий).
SQL View динамически создают наборы данных в соответствии с определенным SQL-запросом в момент его выполнения. При этом обработка данных, хранящихся в системе "Первая Форма", выполняется непосредственно на SQL Server. Результаты вычислений могут быть сохранены в XML-файле. В дальнейшем эти данные могут использоваться следующими способами:
1. Данные могут быть загружены в Excel для дальнейшей обработки. Например, использование SQL View позволяет выгрузить в Excel большие и сложно структурированные объемы данных гораздо быстрее, чем с помощью встроенных механизмов экспорта данных из категорий "Первой Формы" в Excel;
2. Данные могут быть выгружены во внешние системы, в том числе с применением XSLT преобразований.
Пакеты действий могут использоваться при интеграции с внешними системами для выполнения POST и GET запросов к "Первой Форме", а также при расширении возможностей самой "Первой Формы" — например, для вывода дополнительной (расчетной) информации на карточку задачи, для изменения параметров задач по кнопке из портального блока и т.п.
|
|---|
Список опубликованных объектов
По умолчанию в списке отображаются все опубликованные объекты. С помощью отбора по статусу можно отобразить список только активных или только неактивных публикаций. Активной публикацией считается опубликованный и доступный для использования из внешних систем объект.
Отбор по статусу
Параметр |
Описание |
|---|---|
ID |
Уникальный номер опубликованного объекта, присваивается системой автоматически и не редактируется |
Тип публикации |
Возможные варианты: •Sql-view •Пакет действий |
Публикация |
Клик по строке откроет окно редактирования конфигурации публикации. В окне редактирования доступны ссылки (Url), по которым можно обратиться к объекту |
Описание |
Описание публикации (текстовое) |
В случае возникновения ошибки доступа (401 error) при переходе в публикацию, если в API присутствует параметр URL ?auth=true, будет совершена переадресация на страницу авторизации в системе для ввода логина и пароля. В 257 версии страница логина указывается в ключе "AuthTokenLoginUrl" appsettings.json
Создание публикации
Для создания публикации нажмите на кнопку Добавить публикацию, после чего откроется форма создания. Обязательные поля отмечены символом *.
Форма создания публикации
Редактирование публикации
Для перехода к форме редактирования публикации нажмите на ней в общем списке. Конфигурация публикации определяет название и активность объекта, а также параметры запросов (Post или Get).
Редактирование публикации
Параметр |
Описание |
|---|---|
Описание |
Описание объекта в свободной форме. Желательно, чтобы описание отображало смысл объекта |
Алиас* |
Уникальное название объекта (задается в свободной форме) |
Тип публикации* |
Возможные значения: •Sql-view •Пакет действий (По умолчанию) |
Тип запроса* |
Для SQL View доступен только метод Get, для пакетов действий — методы Get, Post, Put и Delete |
Параметры запроса |
Передаваемые параметры необходимо задать в таблице. См. ниже |
URL |
Формируются автоматически на основании конфигураций публикации и объекта доступа. Для SQL View формируются два URL для форматов csv и xml |
Активность публикации |
При включенном флажке объект считается опубликованным и доступным для использования из внешних систем. При обращении к объекту с отключенной активностью публикации возвращается ошибка 403 |
Объект |
Имя сохраненного SQL View в базе данных или название общего смарт-пакета с включенным флажком "Для публикаций". Обратите внимание на особенности публикуемых смарт-пакетов |
XSLT схема |
(только для SQL View) Указывается, если для запроса SQL View нужно определить схему для XSLT-преобразований. См. ниже |
Для добавления параметра запроса нажмите кнопку Добавить параметр, для редактирования уже существующего параметра достаточно нажать на нужную строку в таблице.
Форма редактирования параметра
Столбец |
Значение |
|
|---|---|---|
Тип параметра |
Для методов Get, Put и Delete используется тип QueryString, а для метода Post — QueryString и RequestBody (параметр RequestBody может содержать любые входящие и исходящие параметры)
|
|
Ключ параметра |
Имя параметра |
|
Валидация параметра |
Возможные варианты: •Строка •Число с плавающей точкой •Целое число •Дата |
|
Обязательность параметра |
Если флажок включен, то параметр обязателен. Если в запрос не передан какой-то из обязательных параметров, то в качестве результата запроса возвращается bad request |
|
Формат |
Формат даты в виде строки вида dd.MM.yyyy. См. здесь Параметр задается только если в колонке "Валидация параметра" выбрано значение "Дата" |
|
Массив |
Возможные варианты: •Нет •Строка с разделителем. В этом случае в качестве параметра должна передаваться строка вида item1#item2#item3, где # — символ-разделитель (задается в параметре "Разделитель массива") •Массив JSON. В этом случае в качестве параметра должна передаваться строка вида ["item1", "item2", "item3"] |
|
Разделитель массива |
Символ разделителя в массиве (например, запятая). Параметр задается только если в колонке "Массив" выбрано значение "Строка с разделителем" |
Обратите внимание: в смарт-скриптах (LUA) в публикациях типа POST параметр находится в EVENTPARAMS.
Пример:
PARAMS = UTILS:json_decode(EVENTPARAMS["PublishedObjectParameters"]); --json входящих параметров
str = PARAMS["requestBody"]["data"]
Особенности публикуемых смарт-пакетов
|
|---|
В смарт-выражения, которые создаются в этом смарт-пакете, передается параметр @eventParam0. Он содержит строку в формате JSON со всеми параметрами запроса.
Параметры запроса в публикации
Обращаться к значениям этих параметров можно через функцию JSON_VALUE:
JSON_VALUE(@eventParam0, '$.queryString.paramName')
Формирование тела ответа и кода ответа с помощью скрипта
Если в рамках публикации выполняется сложный высоконагруженный скрипт, который должен возвращать не только сам результат, но и признак успешности выполнения, используйте в публикуемом пакете два смарт-действия:
•сначала "Выполнить sql скрипт" (раздел "Прочее") — в нем можно сформировать выражение формата JSON, которое будет содержать и тело ответа, и код ответа
•затем "HTTP-ответ", в котором можно обратиться к результату предыдущего действия и получить подготовленные тело ответа и код ответа.
Таким образом, скрипт не придется выполнять дважды.
Схема XSLT используется для преобразования данных в определенный XML формат, соответствующий потребностям какой-либо внешней системы.
Например, представление SQL View может содержать данные для отображения на сайте компании в каталоге товаров. Те же данные могут использоваться и для внутренней аналитики в Excel, и для выгрузки в учетную систему. В этом случае удобно для SQL View создать один или несколько шаблонов для преобразования данных в соответствующие форматы.
Правила формирования схемы XSLT можно посмотреть здесь.
Если схема настроена, то при выгрузке XML производится трансформация по этому шаблону.
|
|---|
Объект доступа
Конфигурация объекта доступа определяет права доступа к объекту. Доступ выдается на уровне групп или с помощью смарт-выражения.
Конфигурация объекта доступа
Параметр |
Описание |
|||
|---|---|---|---|---|
Описание |
Название объекта (в свободной форме) |
|||
Разрешить анонимный доступ |
Если настройка активна, опубликованный объект будет доступен без авторизации.
|
|||
Виден всем |
Если настройка активна, опубликованный объект будет доступен всем пользователям |
|||
Право просмотра |
Доступ к объекту на уровне групп. Чтобы добавить группу, участники которой получат право просматривать отчет, в блоке Право просмотра выберите нужную группу из выпадающего списка.
|
|||
Специальное право |
Доступ к объекту ограничивается специальным правом, которое выдается на группу |
|||
По смарт-выражению |
Смарт-выражение должно возвращать массив ID пользователей. При редактировании смарт-выражения доступен контекст — JSON параметров опубликованного объекта.
|
По окончании настройки нажмите кнопку Сохранить.
Использование SQL View для работы в Excel
Для работы с динамической таблицей, формируемой в соответствии с представлением SQL View, используется приложение Excel. Чтобы загрузить данные, выполните импорт из файла XML.
Для Excel 2016
1. Скопируйте ссылку на XML-файл в опубликованном SQL View
Ссылка на опубликованное представление SQL View
2. В файле Excel на закладке "Данные" выберите пункт "Из других источников" -> "Из импорта данных XML".
Выбор источника данных
3. В открывшемся окне в поле "Имя файла" укажите строку вида
https://<сервер_1Формы>/app/v1.2/api/publications/data/sqlView1?contentType=xml
где sqlView1 — алиас опубликованного SQL View.
Затем нажмите кнопку Открыть.
Импорт данных из SQL View
4. Выберите начальную ячейку, в которую будут импортированы данные, и нажмите кнопку ОК.
Выбор диапазона для вставки данных
После этого данные из представления SQLView будут загружены.
|
|---|
Для более ранних версий Excel
1. Скопируйте ссылку на XML-файл в опубликованном SQL View
Ссылка на опубликованное представление SQL View
2. В файле Excel на закладке "Данные" выберите пункт "Из Интернета"
Выбор источника данных
3. В открывшемся окне в поле "Адрес" вставьте сохраненный адрес ссылки на опубликованный SQL и нажмите ввод.
Ссылка имеет вид:
https://<сервер_1Формы>/app/v1.2/api/publications/data/sqlView1?contentType=xml
где sqlView1 — алиас опубликованного SQL View.
Откроется содержимое XML-файла. Щелкните на значок 
для таблиц, которые нужно импортировать. Соответствующие блоки XML-файла будут выделены цветом. Затем нажмите кнопку "Импорт".
Импорт данных из SQL View
4. В открывшемся окне подтвердите согласие на создание схемы на основе данных из XML-источника.
Подтверждение импорта
5. Выберите начальную ячейку, в которую будут импортированы данные, и нажмите кнопку "ОК".
Выбор диапазона для вставки данных
После этого данные из представления SQLView будут загружены.
Полезные ссылки
Отчетность в Excel с помощью SQL View
