Какую проблему решаем
Часто возникает ситуация, когда несколько разных клиентов должны работать с одним и тем же внешним API. В роли клиентов могут выступать различные базы 1С, сайты или другие системы. При этом каждый клиент использует свой набор методов API и ожидает ответ в собственном формате, отличающемся от форматов других клиентов.
Самый простой и очевидный подход — настроить интеграцию с внешним API непосредственно на стороне каждого клиента. Однако на практике при таком подходе можно столкнуться со следующими проблемами:
- Сложность поддержки при изменениях API. Внешние сервисы со временем меняются: может измениться URL, набор endpoint’ов, порты, форматы ответов и другие параметры. В этом случае интеграцию приходится обновлять в каждом клиенте отдельно.
- Подключение новых клиентов через копирование. При появлении нового клиента интеграцию, как правило, настраивают заново — часто путём копирования уже существующего решения от другого клиента.
- Адаптация ответов API на стороне клиента. Внешний сервис может возвращать большой объём данных, значительная часть которых конкретному клиенту не нужна. В результате каждый клиент вынужден самостоятельно разбирать ответ API, извлекать нужные данные и приводить их к удобной для себя структуре.
Библиотека «Точка маршрутизации» позволяет аккуратно и централизованно решить все перечисленные выше проблемы.
- Вся интеграция с внешним API сосредоточена в одном месте. Логика взаимодействия с внешним сервисом размещается на стороне точки маршрутизации. Благодаря этому при изменениях в API (смена URL, endpoint’ов, форматов ответов и т.д.) достаточно внести правки только в одном месте, без необходимости дорабатывать каждого клиента.
- Простое подключение новых клиентов. Для подключения нового клиента достаточно настроить обращение к нужному ресурсу точки маршрутизации. Поскольку вся интеграционная логика уже реализована на её стороне, клиенту не требуется выполнять сложную настройку или разбираться в деталях работы внешнего API.
- Подготовка ответа в формате, удобном для клиента. Точка маршрутизации позволяет заранее обработать ответ внешнего сервиса: привести его к нужному формату и исключить лишние данные. В результате клиент получает только ту информацию, которая ему действительно нужна, и сразу в удобном для работы виде.
Пример использования
Задача
Предположим, нам нужна интеграция с вымышленным сервисом http://api.docscan.org/, предоставляющий REST API для анализа PDF-документов через LLM. Методы API:
POST /auth— получение токена (API-ключ обязателен в заголовке).POST /loadfile— загрузка PDF-файла для анализа, возвращает idFile.GET /result/{idFile}— получение JSON-результата анализа документа.GET /deleteFile/{idFile}— удаление загруженного файла.
Все методы, кроме auth, требуют Bearer-токен, полученный через auth.
С помощью этого API требуется реализовать две раздельные операции:
- Получение информации о документе: Сумма, Вид документа, Номер штрихкода.
- Получение Информации о контрагенте: ИНН, КПП, Наименование
Шаг 1. Модуль API
Создадим внешнюю обработку, в модуле которой реализуем программный интерфейс по вызову методов REST-API http://api.docscan.org/. Созданная внешняя обработка - это модуль API.
Шаг 2. Прикладная операция получения информации документа
Создадим внешнюю обработку модуля прикладной операции получения информации документа. Модуль обработки содержит обработчик POST-запроса, который принимает PDF, отправляет его на http://api.docscan.org и возвращает JSON с суммой документа, видом документа и штрихкодом. При этом взаимодействие с API сервиса выполняется через модуль API, созданном на шаге 1.
Шаг 3. Прикладная операция: информация о контрагенте
Вторая операция извлекает из PDF данные контрагента: ИНН, КПП и Наименование. Для этого также создаем внешнюю обработку модуля прикладной операции и реализуем обработчик POST-запроса:
Шаг 4. Добавление информации о сервисе.
Загружаем созданные модули API и прикладных операций, созданных на шагах 1 - 3, в справочник внешних обработок (например, в справочник Дополнительные отчеты и обработки).
Теперь можно создать описание сервиса - для этого переходим в справочник (тм) Внешние сервисы библиотеки и создаем новый элемент. Для примера заполним так:
Здесь:
- Идентификатор сервиса — уникальный идентификатор, по которому определяется, к какому API нужно отправить запрос. Указывается в параметре
serviceIdURL входящего запроса. - Модуль API — внешняя обработка, созданная на шаге 1, которая содержит все вызовы методов API внешнего сервиса.
- Прикладные операции — перечень операций, доступных для вызова:
- Идентификатор операции — строковый идентификатор, по которому определяется выполняемая операция. Указывается в параметре
operationIdURL запроса клиента. - Модуль операции — внешняя обработка прикладной операции (созданная на шагах 2–3), в которой реализуется:
- обработка входящего запроса от клиента;
- взаимодействие с API через модуль API;
- подготовка и формирование итогового ответа для клиента.
- Идентификатор операции — строковый идентификатор, по которому определяется выполняемая операция. Указывается в параметре
Что получилось
В результате стали доступны два ресурса:
POST docscan/info-doc- анализирует содержимое переданного pdf и возвращает результат в формате
{ "СуммаДокумента": 15200.50, "ВидДокумента": "Счет-фактура", "Штрихкод": "4601234567890" }POST docscan/customer-info- возвращает данные контрагента из переданного pdf в формате
{ "ИНН": "7701234567", "КПП": "770101001", "Наименование": "ООО Выдуманный Контрагент" }
Пример полного пути к ресурсу:
http://<ip-адрес>/<имя публикации>/hs/api-gateway/docscan/info-doc
Альтернативный вариант использования
Библиотеку «Точка маршрутизации» удобно использовать как простой способ развернуть точку подключения вашей информационной системы 1С для работы с другими клиентами — будь то сайты, другие базы 1С или сторонние системы.
Когда это может пригодиться:
- Отправка данных на сайт по запросу. Достаточно создать прикладную операцию с обработкой GET-запроса, описать алгоритм формирования данных, и клиент получит ответ в нужном формате.
- Обработка входящих web-hook’ов. Можно быстро подключить и описать логику обработки входящих уведомлений от других систем. При этом нет необходимости создавать отдельный HTTP-сервис — вся логика находится во внешних обработках и её легко менять в любой момент.
- Интеграция с frontend. Простое решение для добавления HTTP-endpoint’ов, через которые frontend сможет получать или отправлять данные.
- Альтернатива oData. Библиотека позволяет предоставить REST-интерфейс для обмена данными с другими системами, без необходимости заморачиваться с oData.
При таком варианте использования в модуле API нужно делать реализацию получения и обработки данных в текущей информационной системе 1С.
Резюме
Плюсы использования библиотеки:
- Быстрое создание endpoint’ов. После внедрения библиотеки в информационную базу 1С достаточно один раз опубликовать HTTP-сервис api-gateway, и новые точки подключения будут готовы к работе без обновления конфигурации.
- Гибкость и простота изменений. Логика обработки входящих запросов полностью находится во внешних обработках, поэтому её можно менять и расширять в любой момент, без вмешательства в конфигурацию.
Минусы:
- Использование внешних обработок сказывается на производительности
- Это не полноценный API-gateway - в библиотеке нет полноценного логирования и трассировки запросов, балансирование нагрузкой.
- Не известно как поведет себя в высоконагруженных системах - пока не предоставилось возможности сильно нагрузить http-сервис api-gateway из библиотеки. Буду признателен если поделитесь своим опытом :)
В приложенном архиве вы найдете:
- Файл поставки библиотеки route_point_1.0.1.1.cf
- Выгрузку демо-базы demo_route_point.dt
- Документацию в каталоге docs
- Архив с расширением для юнит-тестов unit-tests.zip (перед использованием прочитайте раздел по юнит-тестам в документации)
- Шаблоны модулей API и прикладной операции
Найденные ошибки оформляйте в issue на github - буду исправлять :)
Рекомендуемая версия платформы: 8.3.25.1394
Репозиторий проекта: https://github.com/MadRave/route-point
Документация по внедрению здесь
Вступайте в нашу телеграмм-группу Инфостарт
