Руководство пользователя

2.3.1 Подключение расширения

Расширение «Протон: ETL запросы к базе, редакция 1.0» предназначено для подключения к любой типовой конфигурации. Для подключения расширения требуется использование платформы «1С:Предприятия 8» не ниже 8.3.24.

Файл расширения имеет формат 1Cv8.cfe. Подключение файла расширения выполняется администратором системы в пользовательском режиме.

Для подключения расширения требуется запустить информационную базу-источник. В разделе НСИ и администрирование выбрать и открыть пункт меню Печатные формы, отчеты и обработки.

Далее необходимо выбрать группу Расширения (механизм Библиотеки стандартных подсистем).

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

Необходимо выбрать файл расширения и включить в список по команде Открыть.

После выбора файла расширения система выдаст предупреждение о необходимости перезагрузки, но перед этим требуется снять флаг Безопасный режим (необходимо учитывать, что для расширения безопасный режим не используется).

2.3.2 Обновление расширения

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

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

Пользователь с правами администратора в разделе НСИ и администрирование, как и при подключении расширения (см. скриншоты выше), выбирает пункт меню Печатные формы, отчеты и обработки, далее необходимо открыть пункт Расширения. В открывшемся диалоге необходимо активировать строку нужного расширения и по команде Обновить из файла (пройдя предупреждение безопасности по команде Продолжить) выбрать файл обновления расширения из диалога выбора.

2.3.3 Проверка возможности применения расширения при смене релиза конфигурации

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

Пользователь с правами администратора в разделе НСИ и администрирование, как и при подключении расширения (см. скриншоты выше), выбирает пункт меню Печатные формы, отчеты и обработки, далее необходимо открыть пункт Расширения. В открывшемся диалоге необходимо открыть меню Ещё и выполнить команду Проверить возможность применения всех расширений. В случае успешной проверки будет выведено информационное сообщение:

2.3.4 Отключение расширения

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

Отключение расширения производится из диалога общего списка расширений (в котором выполнялось подключение расширения).

Пользователь в разделе НСИ и администрирование, как и при подключении расширения (см. скриншоты выше), выбирает пункт меню Печатные формы, отчеты и обработки, далее необходимо открыть пункт Расширения. В открывшемся диалоге необходимо снять флаг в первой ячейке строки расширения.

При выполнении команды Отключить система выдаст предупреждение о необходимости перезагрузки. После перезагрузки расширения не будет в пользовательском интерфейсе.

2.3.5 Удаление расширения

Удаление расширения не влечёт за собой изменение данных расширяемой типовой конфигурации.

Удаление расширения производится из диалога общего списка расширений (в котором выполнялось подключение расширения).

Пользователь с правами администратора в разделе НСИ и администрирование, как и при подключении расширения (см. скриншоты выше), выбирает пункт меню Печатные формы, отчеты и обработки, далее необходимо открыть пункт Расширения. В открывшемся диалоге необходимо активировать строку расширения и выполнить команду Удалить (пройдя предупреждение безопасности по команде Продолжить).

При выполнении команды Удалить система выдаст предупреждение о необходимости перезагрузки. После перезагрузки расширения не будет в пользовательском интерфейсе, и все его данные будут безвозвратно удалены из информационной базы.

2.3.6 Настройка публикации на веб-сервере

После подключения расширения в базу-источник опубликуйте базу 1С:Предприятия на web-сервере. Обязательно проконтролируйте, что включена настройка публикации Публиковать HTTP сервисы расширений по умолчанию. Возможно, после публикации или изменения настроек публикации потребуется перезапуск web-сервера.

• Убедитесь, что в базе появились два HTTP-сервиса: etl (основной REST-интерфейс) и swagger (интерактивная документация API). Проверить доступность Swagger UI можно по адресу: http://<сервер>/<публикация>/hs/swagger/index.html
• Через браузер: выполните GET-запрос по адресу http://<сервер>/<имя_базы>/hs/etl/ping — при успешной установке сервис вернёт строку подтверждения
• Назначьте пользователю, под которым будет выполняться подключение, необходимые роли для доступа к данным

Важно: расширение необходимо установить в каждую базу 1С, которая будет использоваться как источник данных.

2.3.7 Настройка баз данных хранения (опционально)

Если планируется использовать внешние СУБД для хранения данных:

1. Перейдите в справочник «Базы данных хранения»
2. Создайте новые элементы для каждой целевой БД
3. Укажите параметры подключения (хост, порт, база данных, логин/пароль)
4. Выберите тип СУБД (ClickHouse или PostgreSQL)

2.3.8 Настройка коннекторов (при необходимости)

Для подключения к источникам данных:

1. Перейдите в справочник «Коннекторы»
2. Создайте коннекторы для каждого источника данных
3. Укажите параметры подключения и описание

2.3.9 Настройка интеграции с Superset (опционально)

Если используется визуализация через Apache Superset:

1. Перейдите в справочник «Серверы Superset»
2. Укажите URL и параметры подключения к серверу Superset

2.3.10 Настройка Telegram-ботов (опционально)

Для получения уведомлений через Telegram:

1. Перейдите в справочник «БотыTelegram»
2. Создайте элементы для каждого бота
3. Укажите токен бота, полученный от @BotFather
4. Настройте список пользователей, которые будут получать уведомления

2.5.1 Назначение и состав расширения

После установки расширение добавляет в базу-источник HTTP-сервис с корневым URL etl, через который конфигурация «Протон: ETL» получает данные в режиме реального времени. Расширение классифицировано как «Дополнение» — конфигурация базы-источника не снимается с поддержки.

Объекты конфигурации, добавляемые расширением:

2.5.2 Системные требования к базе-источнику

Расширение совместимо со следующими версиями платформы 1С:Предприятие:

• 1С:Предприятие 8.3.24 и выше (режим совместимости расширения: Не использовать)
• Рекомендуется использовать актуальные релизы платформы 8.3.24+

Расширение поддерживает работу в файловом и клиент-серверном режимах. База-источник должна быть доступна по сети с сервера, на котором запущена конфигурация «Протон: ETL» (требуется доступ по HTTP/HTTPS).

2.5.3 Настройка прав доступа в базе-источнике

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

Важно: права пользователя, назначенного для подключения, определяют, к каким данным конфигурация «Протон: ETL» получит доступ. Рекомендуется назначать пользователю те же права, что и у интерактивного пользователя соответствующей службы внутри организации.

3.2.1 Справочник «Базы данных хранения»

Назначение: хранение параметров подключения к внешним базам данных (ClickHouse, PostgreSQL).

Реквизиты элемента:

Действия пользователя:

1. Перейдите в раздел «Хранение данных» → «БДХранения»
2. Нажмите кнопку Создать
3. Заполните обязательные реквизиты:
   • Укажите наименование (например, «ClickHouse - Аналитика»)
   • Выберите тип СУБД
   • Введите адрес сервера БД (например, «127.0.0.1» или «clickhouse.company.local»)
   • Укажите название базы данных
   • Введите логин и пароль для подключения
4. Нажмите кнопку Записать и закрыть

Важно: перед сохранением рекомендуется проверить подключение к БД. Функция проверки может быть реализована в форме элемента справочника.

3.2.2 Справочник «ТаблицыБД»

Назначение: описание структуры таблиц в базах данных хранения.

Реквизиты элемента:

Действия пользователя:

1. Перейдите в справочник «ТаблицыБД»
2. Создайте новый элемент
3. Выберите БД хранения из справочника «БДХранения»
4. Укажите имя таблицы
5. Опишите структуру таблицы (поля, типы данных)

Альтернатива: для создания структуры таблицы на основе файла Excel используйте обработку «СозданиеСтруктурыТаблицыНаОсновеExcel» (см. раздел 3.3.5).

3.3.1 Справочник «Коннекторы к источникам данных»

Назначение: настройка подключений к различным источникам данных.

Реквизиты элемента:

Типы коннекторов. Конфигурация поддерживает следующие типы коннекторов:

• Файлы Excel — чтение данных из файлов Excel
• JSON по web ссылке — получение JSON-данных по HTTP/HTTPS
• Запрос URL — выполнение HTTP-запросов
• 1С - «Запросы к базе» — выполнение запросов к базам 1С через HTTP
• 1С - «Запросы к базе» (прямая запись ClickHouse) — выполнение запросов к базам 1С через HTTP с передачей результата напрямую в ClickHouse; это экономит трафик, потому что нет избыточных значений в формате JSON
• Шаг сценария — вторичные шаги сценария для обработки данных на промежуточном этапе: после получения данных из первоисточника и до помещения их в базу данных

Рекомендация по выбору СУБД: для больших объёмов данных рекомендуется использовать коннекторы, работающие напрямую с ClickHouse, так как эта СУБД является наиболее эффективной для операций чтения и записи аналитических данных.

3.3.2 Справочник «ИсточникиДанных1С»

Назначение: описание подключений к другим информационным базам 1С для извлечения данных.

Действия пользователя:

1. Создайте элемент справочника «ИсточникиДанных1С»
2. Укажите наименование информационной базы
3. Настройте параметры HTTP-подключения к базе 1С
4. Укажите логин и пароль пользователя 1С для доступа к данным
5. Сохраните настройки

3.3.3 Справочник «ЗапросыСУБД»

Назначение: хранение SQL-запросов для извлечения данных из внешних СУБД.

Действия пользователя:

1. Создайте элемент справочника «ЗапросыСУБД»
2. Укажите наименование запроса
3. Введите текст SQL-запроса
4. При необходимости добавьте параметры запроса
5. Протестируйте запрос перед использованием в обработке

3.3.4 Справочник «ОбработкаДанных»

Назначение: настройка многошаговых сценариев ETL-процессов.

Основные параметры:

Параметры для работы с Excel:

Параметры для работы с источниками 1С:

Табличные части:

• СценарийОбработки — последовательность шагов выполнения
  • ШагСценария (СправочникСсылка.ШагиОбработкиДанных) — ссылка на шаг обработки
• ЗависимыеОбработкиДанных — цепочка последовательного выполнения
  • ОбработкаДанных (СправочникСсылка.ОбработкаДанных) — зависимая обработка, которая будет запущена после текущей
• ЗапросыСУБД — выполнение нескольких SQL-запросов
  • ЗапросСУБД (СправочникСсылка.ЗапросыСУБД) — SQL-запрос к внешней БД

Назначение зависимых обработок. Механизм зависимостей обеспечивает получение данных в правильной последовательности. Например, для получения справочника подразделений организации необходимо, чтобы сначала выполнилась базовая обработка, и только после её завершения запускалась зависимая обработка — получение справочника организаций. Такая последовательность гарантирует целостность данных при сборе отчётности.

Типичные направления отчётности на основе запросов СУБД:

• По подразделениям — общее количество продаж в разрезе подразделений
• По номенклатуре — позиции с наибольшим объёмом продаж
• Ежедневный отчёт — количество продаж за текущий день

Запросы СУБД позволяют из одной общей таблицы сформировать несколько специализированных таблиц средствами СУБД. Для оптимизации производительности рекомендуется использовать конечные (материализованные) таблицы вместо View, если данные обновляются по расписанию, так как View пересчитывается при каждом обращении и замедляет работу при сложных расчётах.

Действия пользователя:

1. Откройте справочник «ОбработкаДанных»
2. Создайте новый элемент обработки
3. Укажите наименование (например, «Загрузка данных о продажах»)
4. Настройте основные параметры:
   • Выберите коннектор (для извлечения данных)
   • Укажите целевую таблицу БД хранения
   • Если требуется, установите флаг «ОчищатьКонечнуюТаблицуПередЗагрузкой»
   • Для автоматического выполнения установите флаг «ВыполнятьПоРасписанию»
5. Для работы с Excel-файлами:
   • Укажите количество строк заголовков
   • Укажите количество пропускаемых строк сверху
6. Для работы с источниками 1С:
   • Выберите источник данных 1С
   • Укажите период выборки (начало и конец)
   • Настройте периодичность запросов
7. Добавьте шаги обработки в табличную часть «СценарийОбработки»:
   • Шаг 1 (Extract): извлечение данных из источника
   • Шаг 2 (Transform): преобразование данных
   • Шаг 3 (Load): загрузка в БД хранения
8. При необходимости настройте зависимости:
   • В табличной части «ЗависимыеОбработкиДанных» укажите обработки, которые должны выполниться после текущей
9. Сохраните обработку
10. Выполните тестовый запуск с помощью кнопки Выполнить

Пример сценария обработки Excel:

Обработка: "Импорт прайс-листа из Excel"
├─ Коннектор: КоннекторExcel
├─ АдресИсточника: "\\server\files\price.xlsx"
├─ ExcelКоличествоСтрокЗаголовков: 2
├─ ExcelПропускатьСтрокиСверху: 5
├─ КонечнаяТаблицаБД: "Таблица_Прайс"
├─ ОчищатьКонечнуюТаблицуПередЗагрузкой: Да
└─ Сценарий:
   ├─ Шаг 1: Чтение Excel
   ├─ Шаг 2: Валидация данных
   └─ Шаг 3: Загрузка в ClickHouse

Пример сценария обработки данных 1С:

Обработка: "Ежедневная выгрузка остатков из 1С:УТ"
├─ ИсточникДанных1С: "1С:УТ Продакшн"
├─ НачалоПериода1С: Начало текущего дня
├─ КонецПериода1С: Конец текущего дня
├─ ПериодичностьДат1С: День
├─ КонечнаяТаблицаБД: "Таблица_Остатки"
├─ ВыполнятьПоРасписанию: Да
└─ Сценарий:
   ├─ Шаг 1: Получить данные из 1С через HTTP
   ├─ Шаг 2: Преобразовать формат данных
   ├─ Шаг 3: Проверить качество данных
   └─ Шаг 4: Загрузить в ClickHouse

Пример цепочки обработок:

Обработка 1: "Загрузка данных о продажах"
└─ ЗависимыеОбработкиДанных:
   └─ Обработка 2: "Расчет аналитических показателей"
      └─ ЗависимыеОбработкиДанных:
         └─ Обработка 3: "Формирование отчетов"

При выполнении обработки 1 автоматически запустится обработка 2, а после нее — обработка 3.

3.3.5 Обработка «Создание структуры таблицы на основе Excel»

Назначение: автоматическое создание структуры таблицы в БД хранения на основе структуры файла Excel.

Действия пользователя:

1. Создайте новый элемент справочника «Таблицы БД»
2. Нажмите Создать структуру → Заполнить структуру на основе Excel
3. Загрузите файл Excel с эталонной структурой
4. Укажите базу данных хранения из справочника «БДХранения»
5. Укажите имя создаваемой таблицы
6. Проверьте автоматически определенные типы данных для каждого поля
7. При необходимости скорректируйте типы данных
8. Нажмите кнопку Создать таблицу
9. Дождитесь подтверждения успешного создания

Результат: в выбранной БД хранения будет создана таблица с соответствующей структурой, а также добавлен элемент в справочник «ТаблицыБД».

3.3.6 Словари ClickHouse

Назначение: словари ClickHouse — специальный инструмент для хранения редко изменяемых справочных данных (условно-постоянной информации) с возможностью их быстрого использования в аналитических запросах без необходимости повторного обращения к источнику на каждом запросе.

Когда использовать словари. Словари ClickHouse применяются для данных, которые:

• Обновляются редко (например, подразделения организации, виды номенклатуры, контрагенты)
• Используются как справочная информация в большом количестве аналитических запросов
• Требуют высокой скорости доступа без промежуточных соединений таблиц (JOIN)

Пример использования. Справочник подразделений организации является типичным кандидатом для размещения в словарь ClickHouse. Данная информация практически не изменяется со временем, однако активно используется при формировании отчётности по различным направлениям. Размещение такого справочника в словарь позволяет обращаться к нему в запросах напрямую, без дополнительных соединений.

Настройка. Словари ClickHouse настраиваются на уровне СУБД. Для их создания используйте раздел «Запросы СУБД» в обработке данных (см. п. 3.3.4), указав соответствующий DDL-запрос для создания словаря в ClickHouse.

3.4.1 Справочник «Серверы Superset»

Назначение: хранение параметров подключения к серверам Superset.

Действия пользователя:

1. Создайте элемент справочника «Серверы Superset»
2. Укажите URL-адрес сервера Superset (например, «https://superset.company.local»)
3. Введите логин и пароль для доступа к API Superset
4. Сохраните настройки

3.4.2 Справочник «Superset Dashboards»

Назначение: управление дашбордами Superset из конфигурации 1С.

Действия пользователя:

1. Создайте элемент справочника «Superset Dashboards»
2. Укажите наименование дашборда
3. Выберите сервер Superset
4. Укажите ID дашборда в Superset (получается из веб-интерфейса Superset)
5. Сохраните элемент

3.4.3 Справочник «Superset Charts»

Назначение: управление графиками (charts) Superset.

Действия пользователя:

1. Создайте элемент справочника «Superset Charts»
2. Укажите наименование графика
3. Выберите дашборд, к которому относится график
4. Укажите ID графика в Superset
5. При необходимости настройте параметры для мобильного отображения (регистр сведений «НастройкиChartsДляМобильныхДиаграмм»)

3.4.4 Работа с Superset API

Назначение: Apache Superset предоставляет открытый REST API, который позволяет программно взаимодействовать с элементами системы визуализации: получать данные дашбордов, управлять графиками и переиспользовать аналитические данные в других системах.

Возможности Superset API:

• Получение массива данных, на основе которого сформирован дашборд
• Получение информации о структуре и составе дашборда
• Изменение параметров отображения графиков
• Трансляция подготовленных аналитических данных во внешние системы

Практическое применение. Superset API позволяет не только визуализировать данные, но и проводить их компиляцию на уровне платформы — создавать новые производные сущности и передавать их в другие корпоративные системы через API-интеграцию. Таким образом, Apache Superset выступает не только как инструмент визуализации, но и как промежуточный аналитический слой в архитектуре данных организации.

Настройка подключения к API. Параметры подключения к API Superset настраиваются в справочнике «SupersetСерверы» (см. п. 3.4.1). Для работы с API используются те же учётные данные, что и для веб-интерфейса Superset.

3.5.1 Справочник «БотыTelegram»

Назначение: настройка Telegram-ботов для отправки уведомлений.

Действия пользователя:

1. Создайте бота в Telegram через @BotFather и получите токен
2. Откройте справочник «БотыTelegram»
3. Создайте новый элемент
4. Укажите наименование бота
5. Введите токен, полученный от @BotFather
6. Сохраните элемент

3.5.2 Настройка получения уведомлений

Действия пользователя:

1. Запустите диалог с ботом в Telegram
2. Отправьте команду /start
3. Бот автоматически зарегистрирует ваш Chat ID
4. Данные о пользователе сохранятся в регистре сведений «ДанныеПользователейБотовTelegram»

Просмотр истории сообщений. Все отправленные сообщения регистрируются в регистре сведений «СообщенияTelegram», где можно просмотреть историю уведомлений.

3.6.1 Регламентное задание «ОбработкаДанныхПоРасписанию»

Назначение: автоматическое выполнение обработок данных согласно настроенному расписанию.

Настройка регламентного задания:

1. В разделе «Администрирование» → «Обслуживание» → «Регламентные и фоновые задания» найдите задание «ОбработкаДанныхПоРасписанию»
2. Откройте параметры задания
3. Установите флаг Использование для включения задания
4. Настройте расписание выполнения:
   • Ежедневно в определенное время
   • Еженедельно в определенные дни
   • Ежемесячно
   • Произвольное расписание
5. Сохраните настройки

Мониторинг выполнения. Результаты выполнения регламентного задания фиксируются в следующих регистрах:

• «ВыполненияОбработкиДанных» — общая информация о выполнении
• «ЛогВыполненияОбработкиДанных» — детальный лог операций
• «ОшибкиВыполненияОбработкиДанных» — информация об ошибках

3.7.1 Сценарий «Загрузка данных о закупках из 1С»

Описание: получение данных о закупках из рабочей базы 1С:Предприятие и отображение их в дашборде Apache Superset.

Этап 1. Сбор первичной информации

Источником данных является рабочая база 1С:Предприятие. Система поддерживает подключение к нескольким базам одновременно, что позволяет консолидировать данные из всех информационных баз организации.

Этап 2. Настройка обработки данных в ETL

1. Откройте справочник «ОбработкаДанных» и создайте новую обработку (например, «Загрузка поступления товаров»)
2. В блоке «Информация об исходном источнике данных»: выберите коннектор «1С — Запросы к базе (прямая запись ClickHouse)»; укажите источник данных 1С (одну или несколько рабочих баз)
3. В блоке «Настройки запроса к 1С» введите тело запроса на языке запросов 1С
4. В блоке «Информация о конечном месте хранения данных»: укажите целевую таблицу БД (например, «поступление_товаров»); при необходимости установите флаг «Очищать конечную таблицу перед загрузкой»
5. Установите расписание выполнения обработки (например, ежедневно в 01:00)

Этап 3. Визуализация в Apache Superset

После выполнения обработки данных наименование конечной таблицы БД автоматически становится доступным в Apache Superset.

1. В интерфейсе Superset обратитесь к таблице «поступление_товаров»
2. Создайте набор данных на основе SQL-запроса к этой таблице
3. Настройте необходимые поля, метрики и показатели
4. Сформируйте график или дашборд

Результат: данные из всех рабочих баз 1С собраны, обработаны и визуализированы в удобном интерфейсе — всего в 3 этапа.

3.7.2 Сценарий «Загрузка данных о продажах из файлов Excel»

Описание: получение данных о продажах из файлов Excel и отображение их в дашборде Apache Superset.

Типичный случай применения: в 1С сформирован сложный отчёт с нетривиальными запросами или компоновкой данных. Отчёт выгружается в файл Excel, после чего система ETL автоматически обрабатывает его и загружает данные в хранилище.

Этап 1. Подготовка источника данных

Сформируйте отчёт в 1С и выгрузите его в файл Excel. При необходимости можно использовать несколько файлов — система объединит их в единый набор данных.

Этап 2. Настройка обработки данных в ETL

1. Откройте справочник «ОбработкаДанных» и создайте новую обработку (например, «Воронка продаж из Excel»)
2. В блоке «Информация об исходном источнике данных»: выберите коннектор «КоннекторExcel»; укажите путь к файлу (или папке с файлами) Excel
3. Настройте параметры чтения файла: укажите количество строк заголовка («ExcelКоличествоСтрокЗаголовков»); укажите количество пропускаемых строк сверху («ExcelПропускатьСтрокиСверху»)
4. В блоке «Информация о конечном месте хранения данных»: укажите целевую таблицу БД (например, «воронка_продаж»); установите флаг «Очищать конечную таблицу перед загрузкой», если данные должны полностью заменяться при каждом обновлении
5. При необходимости создайте структуру таблицы автоматически с помощью обработки «СозданиеСтруктурыТаблицыНаОсновеExcel» (см. п. 3.3.5)

Этап 3. Визуализация в Apache Superset

1. В интерфейсе Superset обратитесь к таблице «воронка_продаж»
2. Создайте набор данных и настройте нужные поля и метрики
3. Сформируйте дашборд с необходимыми графиками

Результат: данные из файлов Excel обработаны и визуализированы в Apache Superset в единый удобный отчёт — всего в 3 этапа.

3.8.1 Обзор методов API

Все методы сервиса используют HTTP Basic Authentication. Учётные данные соответствуют пользователю базы-источника, которому назначена роль ETL_ОсновнаяРоль (см. п. 2.5.3).

3.8.2 Описание методов

`GET /etl/ping` — проверка доступности

Метод используется для технического мониторинга работоспособности сервиса. Не требует передачи тела запроса.

`GET /etl/metadata` — метаданные ETL

Возвращает список объектов ETL, доступных в базе-источнике: источников данных, запросов и отчётов. Используется конфигурацией «Протон: ETL» для автоматического заполнения справочника «ИсточникиДанных1С».

`POST /etl/query` — выполнение запроса

Основной метод интеграции. Выполняет запрос на языке запросов 1С к базе-источнику и возвращает результат в виде набора строк в формате JSON. Используется коннектором «1С — Запросы к базе» в обработках данных.

Структура тела запроса ETLQueryRequest:

Пример тела запроса:

{
  "Query": "ВЫБРАТЬ ПЕРВЫЕ 100 Товары.Наименование ИЗ Справочник.Номенклатура КАК Товары",
  "Params": []
}

`POST /etl/report/{ИмяОтчета}` — формирование отчёта

Формирует отчёт по его техническому имени и возвращает результат. Имя отчёта передаётся как параметр пути URL. Список доступных отчётов можно получить методом GET /etl/reports_metadata.

`GET /etl/reports_metadata` — список отчётов

Возвращает список отчётов, доступных для вызова через HTTP-сервис ETL, вместе с их параметрами и поддерживаемыми форматами выгрузки.

3.8.3 Просмотр документации API (Swagger UI)

Расширение содержит встроенную интерактивную документацию API в формате OpenAPI/Swagger. Документация позволяет просматривать описание всех методов и выполнять тестовые запросы непосредственно из браузера.

Порядок доступа к Swagger UI:

1. Откройте браузер
2. Перейдите по адресу: http://<сервер>/<публикация>/hs/swagger/index.html
3. При появлении запроса аутентификации введите учётные данные пользователя с ролью ETL_ОсновнаяРоль
4. В открывшемся интерфейсе будут доступны описания всех методов сервиса etl

Важно: Swagger UI предназначен для разработчиков и администраторов. Рядовым пользователям доступ к нему не требуется.

4.1.1 Роли основной конфигурации «Протон: ETL»

Дополнительно используются стандартные роли БСП для доступа к базовой функциональности.

4.1.2 Роль расширения конфигурации «Протон: ETL запросы к базе»

Расширение, устанавливаемое в базы 1С-источники, добавляет собственную роль. Эта роль назначается в базе-источнике — не в конфигурации «Протон: ETL».

Важно: роль ETL_ОсновнаяРоль назначается исключительно в базе-источнике. Порядок назначения описан в п. 2.5.3 настоящего руководства.

4.2.1 Регистр сведений «ВыполненияОбработкиДанных»

Назначение: хранение общей информации о запусках обработок данных.

Содержимое:

• Дата и время запуска
• Обработка данных
• Статус выполнения (успешно/ошибка)
• Время выполнения

Использование:

1. Откройте регистр сведений «ВыполненияОбработкиДанных»
2. Установите отбор по периоду и/или обработке
3. Просмотрите список выполнений
4. Для детализации откройте связанные записи в «ЛогВыполненияОбработкиДанных»

4.2.2 Регистр сведений «ЛогВыполненияОбработкиДанных»

Назначение: детальный лог выполнения каждого шага обработки.

Содержимое:

• Дата и время операции
• Шаг обработки
• Сообщение (описание выполненной операции)
• Дополнительные данные (параметры, результаты)

Использование:

1. Откройте регистр сведений «ЛогВыполненияОбработкиДанных»
2. Установите отбор по выполнению обработки
3. Просмотрите последовательность операций
4. Используйте для анализа и отладки процессов

4.2.3 Регистр сведений «ОшибкиВыполненияОбработкиДанных»

Назначение: регистрация ошибок, возникших при выполнении обработок.

Содержимое:

• Дата и время ошибки
• Обработка и шаг, на котором возникла ошибка
• Текст ошибки
• Стек вызовов (при наличии)

Использование:

1. Откройте регистр сведений «ОшибкиВыполненияОбработкиДанных»
2. Просмотрите список ошибок
3. Проанализируйте причины ошибок
4. Внесите необходимые исправления в обработки или настройки
5. После исправления повторите выполнение обработки

4.2.4 Регистр сведений «ЛогиВыполненияЗапросовClickHouse»

Назначение: специализированный лог для запросов к ClickHouse.

Использование: просмотр истории выполненных запросов к ClickHouse, анализ производительности запросов.

4.3.1 Очистка устаревших логов

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

Рекомендации:

• Логи выполнения обработок: хранить 3–6 месяцев
• Логи ошибок: хранить 12 месяцев
• Логи запросов к БД: хранить 1 месяц

4.3.2 Резервное копирование

Рекомендуется регулярное резервное копирование информационной базы:

• Ежедневное резервное копирование (автоматически)
• Сохранение копий перед внесением изменений в настройки обработок
• Хранение резервных копий на отдельном носителе

4.3.3 Мониторинг производительности

Для контроля производительности системы рекомендуется:

• Использовать технологический журнал 1С для анализа медленных операций
• Мониторить время выполнения обработок (регистр «ВыполненияОбработкиДанных»)
• Оптимизировать запросы к внешним БД при необходимости
• Контролировать объем данных в логах