Публикации — Администрирование¶
Публикация объектов позволяет использовать данные и логику «Первой Формы» вне системы — из внешних приложений. У каждого опубликованного объекта есть собственный URL, по которому к нему обращаются напрямую по HTTP. Публиковать можно объекты двух типов:
- Представления SQL View — динамические наборы данных, формируемые по SQL-запросу в момент обращения. Их выгружают, например, в Excel или во внешнюю систему (в том числе с преобразованием формата через XSLT).
- Пакеты действий (смарт-пакеты) — для приёма POST/GET-запросов от внешних систем и для расширения самой «Первой Формы»: вывод расчётных данных на карточку задачи, выполнение действий по кнопке из портального блока и т.п.
Публикации настраиваются в разделе администрирования «Публикации». Раздел адресован администраторам и интеграторам.
Список опубликованных объектов¶
В разделе отображается список всех опубликованных объектов.
По умолчанию показаны все публикации, отсортированные по ID по убыванию (новые — вверху); клик по заголовку колонки меняет порядок сортировки. Отбор по статусу позволяет показать только активные или только неактивные публикации — активной считается опубликованный и доступный извне объект.
Колонки списка:
| Колонка | Описание |
|---|---|
| ID | Уникальный номер объекта; присваивается системой автоматически и не редактируется. |
| Тип публикации | SQL View или Пакет действий. |
| Публикация | Клик по строке открывает окно редактирования публикации; в нём доступны URL для обращения к объекту. |
| Описание | Текстовое описание публикации. |
| Разрешён анонимный доступ | Строки с разрешённым анонимным доступом выделяются красным цветом. |
| Виден всем | Публикация доступна всем пользователям системы. |
| Группы доступа | Группы, которым разрешён доступ к публикации. |
Если при переходе в публикацию возникает ошибка доступа (401) и в URL присутствует параметр ?auth=true, пользователь перенаправляется на страницу авторизации для ввода логина и пароля. Адрес страницы логина задаётся ключом AuthTokenLoginUrl в appsettings.json.
Создание публикации¶
Чтобы создать публикацию, нажмите кнопку «Добавить публикацию» — откроется форма создания. Обязательные поля отмечены звёздочкой (*).
Конфигурация публикации¶
Клик по строке в списке открывает форму редактирования. В ней задаются название и активность объекта, тип и метод запроса, параметры запроса и сам публикуемый объект.
| Параметр | Описание |
|---|---|
| Описание | Описание объекта в свободной форме — желательно, чтобы оно отражало смысл объекта. |
| Алиас* | Уникальное название объекта (в свободной форме); входит в URL. |
| Тип публикации* | SQL View или Пакет действий (значение по умолчанию). |
| Тип запроса* | Для SQL View — GET и HEAD. Для пакетов действий — 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. Задаёт схему XSLT-преобразования результата (см. раздел «XSLT-схема» ниже). |
Параметры запроса¶
Чтобы добавить параметр, нажмите кнопку «Добавить параметр»; чтобы отредактировать существующий — нажмите на его строку в таблице.
| Поле | Описание |
|---|---|
| Тип параметра | Для методов GET, HEAD, PUT, DELETE — QueryString. Для POST — QueryString или RequestBody (последний может содержать любые входящие и исходящие параметры). В SQL View параметры не используются. |
| Ключ параметра | Имя параметра. |
| Валидация параметра | Тип значения: Строка, Число с плавающей точкой, Целое число, Дата. |
| Обязательность параметра | Если флажок включён, а обязательный параметр в запросе не передан, возвращается bad request. |
| Формат | Формат даты в виде строки, например dd.MM.yyyy. Задаётся только если в «Валидация параметра» выбрано «Дата». |
| Массив | Нет; Строка с разделителем — значение вида item1#item2#item3, где # — символ из поля «Разделитель массива»; Массив JSON — значение вида ["item1","item2","item3"]. |
| Разделитель массива | Символ-разделитель. Задаётся только если в «Массив» выбрано «Строка с разделителем». |
В смарт-скриптах (LUA) в публикациях типа POST параметры находятся в EVENTPARAMS, например: PARAMS = UTILS:json_decode(EVENTPARAMS["PublishedObjectParameters"]).
Особенности публикуемых смарт-пакетов¶
В опубликованном пакете действий последним должно быть смарт-действие «HTTP-ответ». Во все смарт-выражения такого пакета передаётся параметр @eventParam0 — строка в формате JSON со всеми параметрами запроса.
К значениям этих параметров обращаются через функцию JSON_VALUE, например: JSON_VALUE(@eventParam0, '$.queryString.paramName').
Если в публикации выполняется сложный высоконагруженный скрипт, который должен возвращать не только результат, но и признак успешности, используйте в пакете два смарт-действия: сначала «Выполнить SQL-скрипт» (раздел «Прочее») — в нём формируется выражение формата JSON, содержащее и тело, и код ответа; затем «HTTP-ответ» — оно обращается к результату предыдущего действия. Так скрипт не выполняется дважды.
XSLT-схема¶
Схема XSLT (только для SQL View) преобразует выгружаемые данные в нужный XML-формат под конкретную внешнюю систему. Если схема задана, при выгрузке XML данные проходят преобразование по шаблону.
Одно и то же представление SQL View можно опубликовать несколько раз и для каждой записи задать свой XSLT-шаблон — так одни и те же данные из «Первой Формы» выгружаются в разных форматах для разных внешних систем. По возможности само преобразование данных (очистку от HTML-тегов, смену денежного формата на числовой и т.п.) лучше выполнять на стороне SQL View, а не средствами XSLT.
Объект доступа¶
Конфигурация объекта доступа определяет права доступа к опубликованному объекту — на уровне групп или через смарт-выражение.
| Параметр | Описание |
|---|---|
| Описание | Название объекта в свободной форме. |
| Разрешить анонимный доступ | Если настройка активна, объект доступен без авторизации. Анонимно публикуют только данные, не содержащие коммерческой тайны; вызывать анонимно действия в бизнес-процессах недопустимо. При включении анонимного доступа проверьте, внесены ли нужные изменения в web.config (секция location для path="app/v1.2/api/publications"). |
| Виден всем | Если настройка активна, объект доступен всем пользователям системы. |
| Право просмотра | Доступ на уровне групп — выберите нужную группу из выпадающего списка. |
| Специальное право | Доступ ограничивается специальным правом, выданным на группу. |
| По смарт-выражению | Смарт-выражение должно возвращать массив ID пользователей. В редакторе смарт-выражения доступен контекст — JSON параметров опубликованного объекта. |
Если указаны и группы, и смарт-выражение, итоговый список доступа формируется как их пересечение (логическое И). По окончании настройки нажмите кнопку «Сохранить».
Использование SQL View в Excel¶
Данные опубликованного SQL View можно загрузить в Excel импортом из XML. Сначала скопируйте ссылку на XML-файл в опубликованном SQL View.
Затем в Excel на вкладке «Данные» выберите импорт из XML-источника (в Excel 2016 — «Из других источников» → «Из импорта данных XML»; в более ранних версиях — «Из Интернета») и укажите ссылку вида https://<сервер_1Формы>/app/v1.2/api/publications/data/<alias>?contentType=xml, где <alias> — алиас опубликованного SQL View. Выберите начальную ячейку для вставки и подтвердите импорт — данные из представления загрузятся в лист. Для работы с SQL View пользователь должен быть авторизован в браузере.
Basic Authentication в публикациях¶
Для API публикаций поддерживается Basic Authentication — аутентификация по логину и паролю без генерации токенов (учётные данные передаются в заголовке HTTP-запроса).
Механизм включается ключом AuthBasicAllowedPaths в appsettings.json — он задаёт разрешённые пути (регулярные выражения, разделённые ; или ,). По умолчанию Basic Authentication выключен, пока шаблоны путей не заданы. Примеры значений: ".*" — все пути, разрешённые атрибутом; "/app/v1\\.2/api/publications/action/get-sales" — один конкретный путь. Значимые символы регулярных выражений нужно экранировать.
Приоритет всегда у токенной аутентификации — обработчик Basic Authentication срабатывает, только если токен не смог верифицировать пользователя. Каждый такой запрос эквивалентен входу через стандартную форму: проверяются логин и пароль, учитывается ограничение на число неуспешных попыток по IP и логину, ведётся логирование.
Ограничения: при включённой двухфакторной аутентификации запрос с Basic Authentication завершится ошибкой 401; проверка капчи для этого метода отключена. Метод считается рискованным и разрешается только в исключительных случаях; предпочтительны учётные записи с паролем, хранящимся в базе данных, а не AD-пользователи.
Связанные документы¶
- Контроль доступа к публикациям
- Пошаговое создание публикации
- Техническая реализация: контроллеры, сервисы, маршруты — здесь же описано программное создание публикаций через Admin API
- Виджеты на порталах, привязанные к публикациям
- SmartScript и пакеты действий