Руководство администратора

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

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

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

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

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

Список опубликованных объектов

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

Отбор по статусу

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

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

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

Форма создания публикации

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

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

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

Параметры запроса

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

Форма редактирования параметра

Обратите внимание: в смарт-скриптах (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-схема

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

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

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

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

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

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

Конфигурация объекта доступа

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

Использование 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 будут загружены.

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

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

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

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 до капчи) не применяются к данному методу аутентификации.

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

Полезные ссылки

Отчетность в Excel с помощью SQL View

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

Общие SMART

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

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