Публикации

Публикация объектов позволяет использовать их вне "Первой Формы", внешними системами. При публикации создаются ссылки (Url), по которым можно обратиться к объектам напрямую. В настоящее время в "Первой Форме" можно публиковать SQL View и смарт-пакеты (пакеты действий).

SQL View динамически создают наборы данных в соответствии с определенным SQL-запросом в момент его выполнения. При этом обработка данных, хранящихся в системе "Первая Форма", выполняется непосредственно на SQL Server. Результаты вычислений могут быть сохранены в XML-файле. В дальнейшем эти данные могут использоваться следующими способами:

1. Данные могут быть загружены в Excel для дальнейшей обработки. Например, использование SQL View позволяет выгрузить в Excel большие и сложно структурированные объемы данных гораздо быстрее, чем с помощью встроенных механизмов экспорта данных из категорий "Первой Формы" в Excel;

2. Данные могут быть выгружены во внешние системы, в том числе с применением XSLT преобразований.

Пакеты действий могут использоваться при интеграции с внешними системами для выполнения POST и GET запросов к "Первой Форме", а также при расширении возможностей самой "Первой Формы" — например, для вывода дополнительной (расчетной) информации на карточку задачи, для изменения параметров задач по кнопке из портального блока и т.п.

ℹ️ При публикации пакетов действий используется смарт-действие "HTTP ответ". Обратите внимание на необходимость очистки тела ответа от лишних символов.

По умолчанию в списке отображаются все опубликованные объекты. С помощью отбора по статусу можно отобразить список только активных или только неактивных публикаций. Активной публикацией считается опубликованный и доступный для использования из внешних систем объект.

Параметр	Описание
ID	Уникальный номер опубликованного объекта, присваивается системой автоматически и не редактируется. Список отсортирован по ID по убыванию по умолчанию — новые публикации отображаются вверху. Кликните по заголовку колонки для изменения порядка сортировки
Тип публикации	Возможные варианты: -Sql-view -Пакет действий
Публикация	Клик по строке откроет окно редактирования конфигурации публикации.

В окне редактирования доступны ссылки (Url), по которым можно обратиться к объекту | Описание | Описание публикации (текстовое) | | --- | --- | | Разрешен анонимный доступ | Строки публикаций, для которых установлено разрешение анонимного доступа, автоматически выделяются красным цветом | | Виден всем | Публикация доступна для всех пользователей системы | | Группы доступа | Список групп, которым разрешен доступ к публикации |

В случае возникновения ошибки доступа (401 error) при переходе в публикацию, если в API  присутствует параметр URL ?auth=true, будет совершена переадресация на страницу авторизации в системе для ввода логина и пароля. В 257 версии страница логина указывается в ключе "AuthTokenLoginUrl" appsettings.json

Создание публикации

Для создания публикации нажмите на кнопку Добавить публикацию, после чего откроется форма создания. Обязательные поля отмечены символом *.

Редактирование публикации

Для перехода к форме редактирования публикации нажмите на ней в общем списке. Конфигурация публикации определяет название и активность объекта, а также параметры запросов (Post или Get).

Параметр	Описание
Описание	Описание объекта в свободной форме. Желательно, чтобы описание отображало смысл объекта
Алиас*	Уникальное название объекта (задается в свободной форме)
Тип публикации*	Возможные значения: -Sql-view -Пакет действий (По умолчанию)
Тип запроса*	Для SQL View доступен только метод GET, для пакетов действий — методы GET, HEAD, POST, PUT и DELETE. Метод HEAD работает аналогично GET, но сервер возвращает только заголовки ответа, такие как Content-Type или Content-Length, без самого тела
Тип содержимого	Настройка доступна только для запросов с типом Post. Возможные значения: -application/json -application/xml -application/x-www-form-urlencoded -multipart/form-data -plain text -text/xml
Параметры запроса	Передаваемые параметры необходимо задать в таблице. См. ниже
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"]
Разделитель массива	Символ разделителя в массиве (например, запятая).

ℹ️ В SQL View параметры не используются

Параметр задается только если в колонке "Массив" выбрано значение "Строка с разделителем" Обратите внимание: в смарт-скриптах (LUA) в публикациях типа POST параметр находится в EVENTPARAMS.

Пример:

PARAMS = UTILS:json_decode(EVENTPARAMS["PublishedObjectParameters");] --json входящих параметров

str = PARAMS["requestBody"\"data"]

Особенности публикуемых смарт-пакетов

ℹ️ В опубликованном пакете действий последним должно быть смарт-действие "HTTP ответ" (см. Список возможных смарт-действий)

В смарт-выражения, которые создаются в этом смарт-пакете, передается параметр \@eventParam0. Он содержит строку в формате JSON со всеми параметрами запроса.

Обращаться к значениям этих параметров можно через функцию JSON_VALUE:

JSON_VALUE(\@eventParam0, \'\$.queryString.paramName\')

Формирование тела ответа и кода ответа с помощью скрипта

Если в рамках публикации выполняется сложный высоконагруженный скрипт, который должен возвращать не только сам результат, но и признак успешности выполнения, используйте в публикуемом пакете два смарт-действия:

• сначала "Выполнить sql скрипт" (раздел "Прочее") — в нем можно сформировать выражение формата JSON, которое будет содержать и тело ответа, и код ответа

• затем "HTTP-ответ", в котором можно обратиться к результату предыдущего действия и получить подготовленные тело ответа и код ответа.

Таким образом, скрипт не придется выполнять дважды.

XSLT-схема

Схема XSLT используется для преобразования данных в определенный XML формат, соответствующий потребностям какой-либо внешней системы.

Например, представление SQL View может содержать данные для отображения на сайте компании в каталоге товаров. Те же данные могут использоваться и для внутренней аналитики в Excel, и для выгрузки в учетную систему. В этом случае удобно для SQL View создать один или несколько шаблонов для преобразования данных в соответствующие форматы.

Правила формирования схемы XSLT можно посмотреть здесь.

Если схема настроена, то при выгрузке XML производится трансформация по этому шаблону.

ℹ️ Одно и то же представление SQL View может быть добавлено в список опубликованных несколько раз, и для каждой такой записи может быть настроен свой шаблон XSLT. Благодаря этому одни и те же данные, полученные из "Первой Формы", могут выгружаться в разных форматах для использования в разных внешних системах.

Объект доступа

Конфигурация объекта доступа определяет права доступа к объекту. Доступ выдается на уровне групп или с помощью смарт-выражения.

Параметр	Описание
Описание	Название объекта (в свободной форме)
Разрешить анонимный доступ	Если настройка активна, опубликованный объект будет доступен без авторизации.
Виден всем	Если настройка активна, опубликованный объект будет доступен всем пользователям
Право просмотра	Доступ к объекту на уровне групп.

ℹ️ Анонимные публикации должны предоставлять только ту информацию, которая не содержит коммерческой тайны ℹ️ Недопустимо использовать анонимные публикации для вызова действий в бизнес-процессах ℹ️ Если вы разрешаете анонимный доступ к объекту публикации, проверьте, внесены ли необходимые изменения в файл web.config (в частности, должна быть секция location для path="app/v1.2/api/publications" )

Чтобы добавить группу, участники которой получат право просматривать отчет, в блоке Право просмотра выберите нужную группу из выпадающего списка.

ℹ️ Если указаны и группы, и смарт-выражение, то итоговый список доступа формируется как пересечение этих множеств (логическое И).

Параметр	Описание
Специальное право	Доступ к объекту ограничивается специальным правом, которое выдается на группу
По смарт-выражению	Смарт-выражение должно возвращать массив ID пользователей. При редактировании смарт-выражения доступен контекст — JSON параметров опубликованного объекта.

ℹ️ Если указаны и группы, и смарт-выражение, то итоговый список доступа формируется как пересечение этих множеств (логическое И).

По окончании настройки нажмите кнопку Сохранить.

Использование SQL View для работы в Excel

Для работы с динамической таблицей, формируемой в соответствии с представлением SQL View, используется приложение Excel. Чтобы загрузить данные, выполните импорт из файла XML.

Для Excel 2016

1. Скопируйте ссылку на XML-файл в опубликованном SQL View

2. В файле Excel на закладке "Данные" выберите пункт "Из других источников" -> "Из импорта данных XML".

3. В открывшемся окне в поле "Имя файла" укажите строку вида

https://\<сервер_1Формы>/app/v1.2/api/publications/data/sqlView1?contentType=xml

где sqlView1 — алиас опубликованного SQL View.

Затем нажмите кнопку Открыть.

4. Выберите начальную ячейку, в которую будут импортированы данные, и нажмите кнопку ОК.

После этого данные из представления SQLView будут загружены.

ℹ️ Для работы с SQL View пользователь должен быть авторизован в Internet Explorer

Для более ранних версий Excel

1. Скопируйте ссылку на XML-файл в опубликованном SQL View

2. В файле Excel на закладке "Данные" выберите пункт "Из Интернета"

3. В открывшемся окне в поле "Адрес" вставьте сохраненный адрес ссылки на опубликованный SQL и нажмите ввод.

Ссылка имеет вид:

https://\<сервер_1Формы>/app/v1.2/api/publications/data/sqlView1?contentType=xml

где sqlView1 — алиас опубликованного SQL View.

Откроется содержимое XML-файла. Щелкните на значок для таблиц, которые нужно импортировать. Соответствующие блоки XML-файла будут выделены цветом. Затем нажмите кнопку "Импорт".

4. В открывшемся окне подтвердите согласие на создание схемы на основе данных из XML-источника.

5. Выберите начальную ячейку, в которую будут импортированы данные, и нажмите кнопку "ОК".

После этого данные из представления SQLView будут загружены.

Basic Authentication в публикациях

В системе реализована поддержка Basic Authentication для API публикаций. Данный механизм позволяет выполнять аутентификацию с использованием логина и пароля без генерации токенов авторизации.

ℹ️ Basic Authentication — это метод аутентификации, при котором клиент передает логин и пароль в заголовке HTTP-запроса. Учетные данные уникальны для каждого контура и не используются токены, параметры запроса или дополнительные заголовки

Процесс аутентификации

1. Для работы Basic Authentication должны быть выполнены два условия: API /app/v1.2/api/publications/{publicationType}/{publicationAlias} должен быть помечен специальным атрибутом, и путь должен соответствовать шаблону, указанному в настройках.

2. Настройка разрешенных путей осуществляется с помощью ключа AuthBasicAllowedPaths в конфигурационном файле appsettings.json. Параметр поддерживает регулярные выражения, разделенные символами ";" или ",". По умолчанию Basic Authentication отключен даже для API с установленным атрибутом до тех пор, пока не будут заданы соответствующие шаблоны путей.

Примеры

• Разрешить Basic Authentication для всех путей (разрешенных атрибутом):

"AuthBasicAllowedPaths": ".*"

• Разрешить Basic Authentication для одного конкретного пути:

"AuthBasicAllowedPaths": "/app/v1\\.2/api/publications/action/get-sales"

ℹ️ Не забывайте экранировать значимые символы регулярных выражений

• Разрешить Basic Authentication для двух соответствующих шаблонам путей:

"AuthBasicAllowedPaths": ".*api/publications/action/first-.*;.*api/publications/action/second-.*"

3. Приоритет всегда отдается токенной аутентификации. Обработчик Basic Authentication активируется только в случае, если токенная аутентификация не смогла верифицировать пользователя.

4. При первом обращении к API с включенной Basic Authentication возвращается заголовок WWW-Authenticate: Basic realm="{some-realm}", после чего браузер предлагает ввести учетные данные.

5. Каждый запрос с использованием Basic Authentication эквивалентен входу через стандартную форму аутентификации: проверяются логин и пароль в провайдере аутентификации, учитываются ограничения на количество неуспешных попыток входа по IP и логину — задается в опции общих насроек приложения Максимальное число попыток логина до блокировки, выполняется логирование всех попыток входа и обновляется время последней активности пользователя.

Ограничения безопасности

Для Basic Authentication не работает двухфакторная аутентификация. Если у пользователя включена двухфакторная аутентификация, запрос с Basic Authentication завершится с ошибкой 401 Unauthorized.

Для Basic Authentication отключена проверка капчи. Опции максимального количества попыток входа до требования капчи в общих насройках приложения (Максимальное число попыток логина пользователя до капчи и Максимальное число попыток логина с IP до капчи) не применяются к данному методу аутентификации.

ℹ️ Basic Authentication считается рискованным с точки зрения безопасности и разрешается только в исключительных случаях после индивидуального рассмотрения каждого кейса. Не рекомендуется использовать данный метод в высоконагруженных сценариях

Предпочтительно применять учетные данные пользователей с паролями, хранящимися в базе данных, поскольку аутентификация AD-пользователей требует запросов к Active Directory с потенциальными рисками блокировки учетных записей и увеличения времени отклика.

Описание работы с публикациями в прежнем интерфейсе администрирования Полезные ссылки

XSLT преобразования

Общие SMART

Конфигурирование аутентификации по токенам

Примеры публикаций