# Публикации — Администрирование

Публикация объектов позволяет использовать данные и логику «Первой Формы» вне системы — из внешних приложений. У каждого опубликованного объекта есть собственный URL, по которому к нему обращаются напрямую по HTTP. Публиковать можно объекты двух типов:

- **Представления SQL View** — динамические наборы данных, формируемые по SQL-запросу в момент обращения. Их выгружают, например, в Excel или во внешнюю систему (в том числе с преобразованием формата через XSLT).
- **Пакеты действий (смарт-пакеты)** — для приёма POST/GET-запросов от внешних систем и для расширения самой «Первой Формы»: вывод расчётных данных на карточку задачи, выполнение действий по кнопке из портального блока и т.п.

Публикации настраиваются в разделе администрирования «Публикации». Раздел адресован администраторам и интеграторам.

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

В разделе отображается список всех опубликованных объектов.

![Список опубликованных объектов](https://help.1forma.ru/help-images/publications/publications-1.png)

По умолчанию показаны все публикации, отсортированные по ID по убыванию (новые — вверху); клик по заголовку колонки меняет порядок сортировки. Отбор по статусу позволяет показать только активные или только неактивные публикации — активной считается опубликованный и доступный извне объект.

![Отбор по статусу](https://help.1forma.ru/help-images/publications/publications2.png)

Колонки списка:

| Колонка | Описание |
|---------|----------|
| ID | Уникальный номер объекта; присваивается системой автоматически и не редактируется. |
| Тип публикации | SQL View или Пакет действий. |
| Публикация | Клик по строке открывает окно редактирования публикации; в нём доступны URL для обращения к объекту. |
| Описание | Текстовое описание публикации. |
| Разрешён анонимный доступ | Строки с разрешённым анонимным доступом выделяются красным цветом. |
| Виден всем | Публикация доступна всем пользователям системы. |
| Группы доступа | Группы, которым разрешён доступ к публикации. |

Если при переходе в публикацию возникает ошибка доступа (`401`) и в URL присутствует параметр `?auth=true`, пользователь перенаправляется на страницу авторизации для ввода логина и пароля. Адрес страницы логина задаётся ключом `AuthTokenLoginUrl` в `appsettings.json`.

В сертифицируемой сборке анонимный доступ к публикациям закрыт на уровне ядра: запрос без действующей сессии отклоняется ответом 401 и не доходит до кода перенаправления, поэтому параметр `?auth=true` на страницу входа не уводит.

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

Чтобы создать публикацию, нажмите кнопку **«Добавить публикацию»** — откроется форма создания. Обязательные поля отмечены звёздочкой (`*`).

![Форма создания публикации](https://help.1forma.ru/help-images/publications/publications7.png)

## Конфигурация публикации

Клик по строке в списке открывает форму редактирования. В ней задаются название и активность объекта, тип и метод запроса, параметры запроса и сам публикуемый объект.

![Редактирование публикации](https://help.1forma.ru/help-images/publications/publications3.png)

| Параметр | Описание |
|----------|----------|
| Описание | Описание объекта в свободной форме — желательно, чтобы оно отражало смысл объекта. |
| Алиас\* | Уникальное название объекта (в свободной форме); входит в 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-схема» ниже). |

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

Чтобы добавить параметр, нажмите кнопку **«Добавить параметр»**; чтобы отредактировать существующий — нажмите на его строку в таблице.

![Форма редактирования параметра](https://help.1forma.ru/help-images/publications/publications6.png)

| Поле | Описание |
|------|----------|
| Тип параметра | Для методов `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 со всеми параметрами запроса.

![Параметры запроса в публикации](https://help.1forma.ru/help-images/publications/publications-.png)

К значениям этих параметров обращаются через функцию `JSON_VALUE`, например: `JSON_VALUE(@eventParam0, '$.queryString.paramName')`.

Если в публикации выполняется сложный высоконагруженный скрипт, который должен возвращать не только результат, но и признак успешности, используйте в пакете два смарт-действия: сначала «Выполнить SQL-скрипт» (раздел «Прочее») — в нём формируется выражение формата JSON, содержащее и тело, и код ответа; затем «HTTP-ответ» — оно обращается к результату предыдущего действия. Так скрипт не выполняется дважды.

## XSLT-схема

Схема XSLT (только для SQL View) преобразует выгружаемые данные в нужный XML-формат под конкретную внешнюю систему. Если схема задана, при выгрузке XML данные проходят преобразование по шаблону.

Одно и то же представление SQL View можно опубликовать несколько раз и для каждой записи задать свой XSLT-шаблон — так одни и те же данные из «Первой Формы» выгружаются в разных форматах для разных внешних систем. По возможности само преобразование данных (очистку от HTML-тегов, смену денежного формата на числовой и т.п.) лучше выполнять на стороне SQL View, а не средствами XSLT.

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

Конфигурация объекта доступа определяет права доступа к опубликованному объекту — на уровне групп или через смарт-выражение.

![Конфигурация объекта доступа](https://help.1forma.ru/help-images/publications/publications4.png)

| Параметр | Описание |
|----------|----------|
| Описание | Название объекта в свободной форме. |
| Разрешить анонимный доступ | Если настройка активна, объект доступен без авторизации. Анонимно публикуют только данные, не содержащие коммерческой тайны; вызывать анонимно действия в бизнес-процессах недопустимо. При включении анонимного доступа проверьте, внесены ли нужные изменения в `web.config` (секция `location` для `path="app/v1.2/api/publications"`). В сертифицируемой сборке признак анонимного доступа не действует: флажок в интерфейсе остаётся, но ядро отклоняет анонимный запрос кодом 401. |
| Виден всем | Если настройка активна, объект доступен всем пользователям системы. |
| Право просмотра | Доступ на уровне групп — выберите нужную группу из выпадающего списка. |
| Специальное право | Доступ ограничивается специальным правом, выданным на группу. |
| По смарт-выражению | Смарт-выражение должно возвращать массив ID пользователей. В редакторе смарт-выражения доступен контекст — JSON параметров опубликованного объекта. |

Если указаны и группы, и смарт-выражение, итоговый список доступа формируется как их пересечение (логическое И). По окончании настройки нажмите кнопку **«Сохранить»**.

## Использование SQL View в Excel

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

![Ссылка на опубликованное представление SQL View](https://help.1forma.ru/help-images/publications/publications8.png)

Затем в 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-пользователи.

## Связанные документы

- [Виджеты на порталах, привязанные к публикациям](https://help.1forma.ru/domains/portal/portal-api-cookbook.md)
- [SmartScript и пакеты действий](https://help.1forma.ru/domains/smart-actions/admin.md)
- [Локализация — Администрирование](https://help.1forma.ru/domains/localization/admin.md) — подписи страницы администрирования публикаций зависят от языка интерфейса