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

Как начать работать

1. Настройте веб-хуки в репозиториях GitLab, которые будут отправлять запросы. Подробнее см. ниже.
2. Откройте настройки интеграции, укажите глобальные параметры работы сервиса и включите обработку запросов.
3. Создайте и настройте обработчики внешних запросов для нужных проектов/репозиториев, указав для каждого токен из веб-хука.

Настройка веб-хуков в GitLab

Для каждого репозитория, события из которого должен обрабатывать сервис-распределитель, необходимо настроить веб-хук (Settings → Webhooks). При настройке укажите следующие параметры:

• URL — адрес HTTP-сервиса 1С (endpoint), который принимает запросы. Например: http://<адрес_сервера>/transmitter/hs/gitlab/event/.
• Secret Token — секретный ключ, который будет использоваться для аутентификации запросов на стороне 1С. Это значение необходимо указать в качестве токена в справочнике «Обработчики внешних запросов» в 1С.
• Trigger — событие, которое будет вызывать веб-хук. Для работы сервиса необходимо выбрать Push events.

После настройки GitLab будет отправлять POST-запросы на указанный URL при каждом push-событии в репозитории.

Настройки интеграции с GitLab

Используется для задания глобальных параметров работы сервиса-распределителя (transmitter), обеспечивающего интеграцию с GitLab и информационными базами-получателями.

Настройки GitLab

Параметры для подключения к серверу GitLab и получения данных:

• Обрабатывать запрос GitLab — включает или отключает обработку входящих webhook-событий. Если флажок снят, сервис не реагирует на push-события в репозиториях.
• Имя файла со схемой маршрутов — имя JSON-файла (по умолчанию .ext-epf.json), расположенного в корне репозитория. Файл содержит правила маршрутизации.
• Токен — Personal Access Token пользователя GitLab. Используется для аутентификации при обращении к API GitLab для загрузки схемы маршрутов и файлов *.epf, *.erf.
  Как получить токен: в GitLab откройте User Settings → Access Tokens, создайте новый токен с правами (scopes) api.
• Таймаут соединения, сек — максимальное время ожидания ответа от GitLab. Если указано 0, таймаут не используется.

Информационные базы-получатели

Задаются параметры по умолчанию для подключения к HTTP-сервисам баз-получателей внешних обработок.

• Имя пользователя и Пароль — учётные данные для аутентификации на HTTP-сервисе базы-получателя. Пользователь должен иметь права на приём и сохранение файлов.
• Таймаут соединения, сек — максимальное время ожидания при отправке файла. Если указано 0, таймаут не используется.

Обработчики внешних запросов

Справочник «Обработчики внешних запросов» предназначен для регистрации репозиториев GitLab, от которых сервис будет принимать и обрабатывать webhook-события. Для каждого репозитория создаётся отдельный элемент справочника, в котором указывается секретный токен для аутентификации входящих запросов.

Реквизиты обработчика

• Наименование — произвольное имя для идентификации обработчика в системе. Рекомендуется указывать имя проекта или репозитория.
• URL — URL проекта в GitLab. Это ключевой реквизит, который используется для привязки обработчика к конкретному репозиторию. Система находит нужный обработчик, сопоставляя URL проекта из тела веб-хука со значением этого поля. Также используется для быстрой навигации к репозиторию из интерфейса 1С.
• Токен — секретный ключ (Secret Token), который указывается в настройках веб-хука на стороне GitLab. Этот ключ используется для проверки подлинности входящих запросов.

Важно: для загрузки файлов из репозитория (схемы маршрутов и самих обработок) система использует Personal Access Token, который задаётся глобально в общих настройках сервиса.

Основной функционал

Форма элемента справочника предоставляет доступ к инструментам для управления и анализа обработки событий, связанных с конкретным репозиторием.

• Элемент справочника: сам по себе обеспечивает приём, запись и последующую обработку событий GitLab (например, push-событий) в соответствии с указанными в нём параметрами (URL проекта, токен).
• История событий: команда «Загрузить историю» открывает журнал событий из журнала регистрации для анализа работы текущего обработчика и общих процессов.
• Повторная обработка: команда «Повторить обработку» позволяет вручную запустить повторную обработку выбранного события. Это полезно в случае, если первоначальная обработка завершилась с ошибкой.
• Фоновые задания: команда «Фоновые задания» открывает монитор фоновых задач, связанных с этим обработчиком. Здесь можно отслеживать статус доставки файлов получателям.
• Тело запроса: команда «Тело запроса» показывает полное тело обрабатываемого HTTP‑запроса в формате JSON, полученного от GitLab.
• Маршрутизация: команда «Маршрутизация» (в регистре «Внешние запросы») открывает редактор маршрутов отправки файлов. Подробнее о правилах см. Правила маршрутизации.
• Файлы: команда «Файлы» (в регистре «Внешние файлы») открывает просмотр метаинформации по загруженным из репозитория файлам.

Правила маршрутизации

Маршрутизация файлов определяется правилами, заданными в JSON-файле в корне репозитория (по умолчанию .ext-epf.json). Этот файл содержит две основные секции: ws для описания сервисов-получателей и epf для задания правил отправки файлов.

Секция ws (веб-сервисы)

Эта секция представляет собой массив объектов, где каждый объект описывает один сервис-получатель.

Атрибуты объекта сервиса:

• url (обязательный): Строка. Полный URL-адрес конечной точки (endpoint) HTTP-сервиса, который будет принимать файл.
• enabled (необязательный): Булево. Определяет, активен ли сервис. Сервис участвует в маршрутизации, только если значение этого поля установлено в true. Если поле отсутствует или его значение false, сервис игнорируется.
• name (необязательный): Строка. Уникальное имя (синоним) сервиса. Используется для обращения к сервису в других атрибутах, например, в правилах исключений (exclude).

"ws": [
    {
        "name": "ProductionDB1",
        "url": "http://endpoint1.example.com/api/hs/epf/uploadFile",
        "enabled": true
    },
    {
        "url": "http://endpoint2.example.com/api/hs/epf/uploadFile",
        "enabled": true
    },
    {
        "name": "TestDB_Archive",
        "url": "http://endpoint3.example.com/api/hs/epf/uploadFile",
        "enabled": false
    }
]

Секция epf (правила для файлов)

Эта секция является массивом объектов, где каждый объект задаёт правило для конкретного файла.

Атрибуты объекта правила:

• name (обязательный): Строка. Относительный путь к файлу (*.epf, *.erf) в репозитории, для которого применяется правило.
• exclude (необязательный): Массив строк. Список сервисов, которые нужно исключить из маршрута для данного файла. Исключение можно задавать как по имени сервиса (name), так и по URL-адресу конечной точки загрузки файлов в информационную базу-приемник (url).

"epf": [
    {
        "name": "src/ExternalReports/Report1.erf"
    },
    {
        "name": "src/ExternalDataProcessors/Processor2.epf",
        "exclude": [
            "ProductionDB1",
            "http://endpoint2.example.com/api/hs/epf/uploadFile"
        ]
    }
]

Логика построения маршрута

Push-событие (webhook) от GitLab может содержать несколько коммитов. Система обрабатывает их по особому алгоритму, чтобы гарантировать отправку только актуальных версий файлов и применение правильных правил маршрутизации.

1. Определение файлов для отправки

Из всего набора коммитов в push-событии система выбирает для отправки только последнюю версию каждого измененного файла (*.epf, *.erf). Например, если файл Report.erf был изменен в первом и третьем коммите, для отправки будет взята только версия из третьего коммита.

2. Построение маршрута для каждого файла

Для каждого отобранного файла маршрут строится индивидуально по следующему алгоритму:

1. Выбирается схема маршрутизации: система использует файл схемы (.ext-epf.json) из того же коммита, в котором находится последняя версия отправляемого файла. Это гарантирует, что правила маршрутизации соответствуют состоянию репозитория на момент изменения файла.
2. Выбираются активные сервисы: из секции ws выбранной схемы маршрутов отбираются все сервисы, у которых enabled установлено в true.
3. Применяются исключения: если для файла найдено правило с секцией exclude, из списка активных сервисов удаляются те, чьё имя (name) или адрес (url) присутствуют в списке exclude.
4. Формируется итоговый маршрут: файл будет отправлен на URL-адреса всех сервисов, оставшихся после применения исключений.

Если для файла не найдено соответствующего правила в секции epf или после применения исключений не осталось ни одного сервиса, файл не будет отправлен никуда.

Пример работы алгоритма

Рассмотрим сценарий, когда в GitLab происходит push-событие, содержащее два коммита.

Состояние репозитория

Коммит 1 (старый):

В этом коммите были изменены два отчёта и заданы первоначальные правила маршрутизации.

• Изменены файлы:
  • src/reports/Report1.erf
  • src/reports/Report2.erf
• Содержимое .ext-epf.json (Схема №1):

  {
    "ws": [
      { "name": "prod", "url": "http://prod.server/api/endpoint", "enabled": true },
      { "name": "test", "url": "http://test.server/api/endpoint", "enabled": true }
    ],
    "epf": [
      { "name": "src/reports/Report1.erf", "exclude": ["test"] },
      { "name": "src/reports/Report2.erf" }
    ]
  }
  

Коммит 2 (последний в push-событии):

В этом коммите повторно изменили первый отчёт и обновили правила маршрутизации, добавив новый сервис.

• Изменены файлы:
  • src/reports/Report1.erf (повторно)
  • .ext-epf.json
• Новое содержимое .ext-epf.json (Схема №2):

  {
    "ws": [
      { "name": "prod", "url": "http://prod.server/api/endpoint", "enabled": true },
      { "name": "test", "url": "http://test.server/api/endpoint", "enabled": true },
      { "name": "archive", "url": "http://archive.server/api/endpoint", "enabled": true }
    ],
    "epf": [
      { "name": "src/reports/Report1.erf" }
    ]
  }
  

Анализ и результат

1. Определение файлов для отправки:
   • src/reports/Report1.erf: будет отправлена версия из Коммита 2, так как это его последнее изменение.
   • src/reports/Report2.erf: будет отправлена версия из Коммита 1, так как в Коммите 2 он не менялся.
2. Построение маршрута для src/reports/Report1.erf:
   • Используется схема .ext-epf.json из Коммита 2 (Схема №2).
   • Активные сервисы из Схемы №2: prod, test, archive.
   • Правило для файла в Схеме №2: { "name": "src/reports/Report1.erf" }. Исключений нет.
   • Итог: файл будет отправлен на все три адреса: http://prod.server/api/endpoint, http://test.server/api/endpoint, http://archive.server/api/endpoint.
3. Построение маршрута для src/reports/Report2.erf:
   • Используется схема .ext-epf.json из Коммита 1 (Схема №1), так как файл последний раз менялся именно там.
   • Активные сервисы из Схемы №1: prod, test.
   • Правило для файла в Схеме №1: { "name": "src/reports/Report2.erf" }. Исключений нет.
   • Итог: файл будет отправлен на адреса http://prod.server/api/endpoint и http://test.server/api/endpoint.