Ранее мы уже писали о возможных способах интеграции 1С и КХД. Также мы подробно рассматривали возможность использования стандартного интерфейса OData, его преимущества и недостатки. В этой статье разберем интеграцию с использованием HTTP (REST) и Web-сервисов (SOAP).
Что нужно для начала интеграции?
HTTP и WS — это механизмы платформы 1С, предназначенные для взаимодействия с внешними системами. Используя их, можно создать мощный и настраиваемый канал обмена данными между 1С и КХД. Для этого нам нужны:
Платформа 1С:Предприятие 8.3 или выше — она поддерживает создание и использование HTTP и WS сервисов.
Веб-сервер Apache или IIS — программное обеспечение, которое обрабатывает HTTP-запросы и возвращает ответы пользователю. Он нужен, чтобы 1С могла принимать входящие запросы и отправлять данные.
Как опубликовать информационную базу на веб-сервере подробно описано в руководстве администратора на сайте информационно-технологического сопровождения 1C. Также можно использовать Инструкцию публикации IIS.
Информация о настройке web-сервисов и HTTP-сервисов доступна в руководстве администратора:
Выбор между HTTP (REST) и веб-сервисами (SOAP) зависит от сложности задачи и требований к обмену данными.
HTTP (REST) подходит для простого обмена информацией в формате JSON или XML, а также для асинхронных запросов, когда можно отправлять и получать данные без ожидания немедленного ответа. Например, 1С может отправлять в КХД информацию о новом контрагенте и продолжать свою работу, не дожидаясь подтверждения сохранения. Аналогичным образом можно асинхронно запрашивать информацию из КХД, например, список товаров, не блокируя работу 1С.
Web-сервисы(SOAP) предпочтительны в более сложных сценариях, где важны гарантии доставки сообщений, возможность проведения транзакций и работа со сложными структурами данных. SOAP характеризуется строгим форматом сообщений и поддерживает протоколы безопасности.
Допустим, в 1С добавили новую номенклатурную позицию (новый товар). 1С отправляет HTTP-запрос (REST) в КХД, передавая данные о новом товаре в формате JSON (например, {"name": "Новый товар", "code": "12345", "price": 100}).
1С не ждет подтверждения сохранения в КХД, а просто отправляет запрос и продолжает работу (асинхронный запрос). КХД может обработать этот запрос в фоновом режиме.
Или другой вариант. В 1С оформляется заказ на крупную сумму, при котором необходимо зарезервировать товары на складе, списать деньги со счета клиента и зафиксировать факт продажи в КХД.
В этом случае 1С отправляет в КХД SOAP-запрос, содержащий информацию о товарах, клиенте, сумме. SOAP-сервис на стороне КХД обрабатывает запрос как атомарную транзакцию (набор действий рассматривается как одно событие) — то есть либо все три операции выполняются успешно, либо отменяются все, если что-то пошло не так. Это значит, что данные о заказе будут корректно отражены как в 1С, так и в КХД, а также, что система КХД получит и подтвердит получение этого сообщения.
Сценарий интеграции по шагам
Рассмотрим алгоритм интеграции на примере передачи данных о контрагентах.
1. Планирование и проектирование
Аналитик определяет, какую информацию о новых контрагентах необходимо передавать из 1С в КХД.
Составляется таблица сопоставления полей, например:
1С.Код -> КХД.ID
1С.Наименование -> КХД.Name
1С.ИНН -> КХД.TaxID
1С.Адрес -> КХД.Address
Сопоставление (маппинг) полей – это установление соответствия между полями объектов 1С и полями в КХД. Без тщательного сопоставления данные могут быть неправильно интерпретированы.
Как это делается:
Анализ данных в 1С. Определите, какую информацию нужно передавать. Найдите нужные объекты в 1С и убедитесь, что в них есть необходимые поля. Например, в справочнике «Контрагенты» могут быть поля «Код», «НаименованиеПолное», «ИНН», а в табличной части «Контактная информация» — «ЮридическийАдрес».
Анализ данных в КХД. Изучите документацию КХД. Найдите объекты, в которых хранится информация о контрагентах. Проверьте, что в КХД есть все поля, которые будут заполняться данными из 1С. Например, в таблице «Partners» могут быть поля «ID», «Name», «TaxID», «Address».
Если нужных объектов в КХД нет, их необходимо создать. Для этого:
Сначала создайте новый объект в системе КХД, который будет хранить сведения о контрагентах, например таблицу «Partners».
Определите и добавьте необходимые поля в этот объект. Например, добавьте поля «ID», «Name», «TaxID», «Address» в таблицу «Partners». Это можно сделать через интерфейс настройки базы данных КХД или используя SQL-запросы для создания и изменения структуры таблиц.
Важно также проверить и сопоставить типы данных полей из 1С и КХД. Тип определяет, какое значение может хранить поле (текст, число, дата, логическое значение). Если они не совпадают, могут возникнуть ошибки при передаче информации. Например:
1С.Код (Строка) -> КХД.ID (Строка) — типы данных совпадают.
1С.ДатаСоздания (Дата) -> КХД.CreatedAt (DateTime) — типы данных разные, нужно преобразование.
То же самое касается и форматов.
1С.ДатаСоздания (Дата) -> КХД.CreatedAt (ISO 8601 DateTime):
Если в 1С дата «25.06.2024», то в КХД нужно передать ее в формате «2024-06-25T00:00:00Z».
2. Создание HTTP/WS-сервиса
HTTP-сервис в 1С
В конфигураторе 1С создается новый HTTP-сервис. Это делается в разделе «Общие» → «HTTP-сервисы». Нужно задать имя сервиса (например, DataExchange) и определить корневой URL, который будет использоваться как часть пути при обращении к сервису. Далее описываются шаблоны URL — ресурсы, для которых определяются методы GET, POST, PUT, DELETE.
Например:
Сервис DataExchange с корневым URL /de и шаблоном /partners будет содержать обработчик метода POST для создания новых контрагентов. Метод GET с шаблоном /partners/{partnerCode} будет возвращать данные о контрагенте по его коду. Здесь {partnerCode} — переменная, которая будет подставляться в зависимости от запроса и будет доступна в программном модуле HTTP сервиса в свойстве ПараметрыURL параметра Запрос в соответствующем обработчике.
В модуле HTTP сервиса необходимо написать обработчики для созданных методов. В зависимости от типа запроса (GET, POST и т.д.) и логики проектируемого решения, код 1С извлекает необходимую информацию из базы данных 1С.
Рекомендуется в модуле HTTP-сервиса реализовывать только логику, связанную с транспортом: получение параметров URL, тела запроса, их контроль и сериализацию ответов. Всю прикладную логику лучше выносить в общие модули. Это упростит тестирование и поддержку кода.
Для HTTP-сервиса нужно выбрать формат обмена данными (JSON или XML). JSON более распространен для REST API из-за своей легковесности и простоты обработки. Однако оборотной стороной легковесности можно считать не слишком широкий набор встроенных типов данных и необходимость самостоятельной проверки всей информации на корректность.
После разработки нужно опубликовать созданный сервис на веб-сервере.
URL будет иметь вид:
http://<server_address>/<base_name>/hs/de.
Где:
<server_address> - адрес веб-сервера с публикацией
<base_name> - имя базы, заданное при публикации
После создания HTTP-сервиса появляются такие возможности:
Создание нового контрагента:
POST http://<server_address>/<base_name>/hs/de/partners.Получение данных о контрагенте (например, с кодом 33458):
GET http://<server_address>/<base_name>/hs/de/partners/33458.
Подробная документация по разработке HTTP-сервиса доступна в Руководстве разработчика. Также множество статей на эту тему есть на Infostart’е, например вот эта.
Web-сервисы
Интеграция через WS (SOAP) похожа на HTTP (REST), но здесь используется XML вместо JSON, а REST API заменяется на более формальный протокол SOAP, частью которого является WSDL. WSDL — это XML-документ, который описывает контракт веб-сервиса, включая его методы, параметры ввода и вывода, а также типы данных.
Этот более сложный подход требует глубокого понимания протокола SOAP и работы с объектами XDTO, с помощью которого будут описаны все параметры вызовов и возвращаемые значения. Информация по разработке нового web-сервиса тянет на отдельную статью, поэтому тут рассматриваться не будет.
Из плюсов web-сервиса можно отметить:
автоматически генерируемый платформой 1С контракт WSDL, который можно передать разработчику со стороны КХД даже без реализации прикладной логики;
контроль типов параметров данных выполняется на уровне платформы 1С до выполнения прикладного кода
3. Ролевая модель.
В 1С предусмотрена гибкая система настройки прав доступа. Можно настроить доступ:
к методам сервисов;
к данным, которые будут предоставляться сервисами.
Пользователь, используемый для обмена информацией, должен иметь необходимые роли. Для этого нужно определить, требуется ли разделение доступа к методам сервисов и к данным. Затем создаются новые роли и настраиваются права.
Пользователю можно назначить используемые роли через подсистему Управление доступом, если конфигурация 1С разработана на базе БСП и эта подсистема внедрена. Либо можно назначить роли в режиме конфигуратора.
4. Тестирование
Перед запуском интеграции нужно протестировать сервис 1С.
Напишите модульные тесты для проверки прикладной логики.
Проверьте работу сервиса в комплексе, отправляя различные запросы (с валидными и не валидными данными). Для этого можно использовать такие инструменты, как Postman.
Используйте отладчик 1С для поиска и исправления ошибок.
Ведите логи работы сервиса для быстрого выявления и устранения проблем. Логировать нужно как на уровне транспорта (модуль http-сервиса), так и на прикладном уровне.
В Modus ETL интеграция между 1С и КХД осуществляется через HTTP-сервисы (подробнее на сайте: https://kb.modusbi.ru/web/docs_product/varianty-ispol-zovaniya-modus-etl). В рамках этой системы есть специальный компонент — Адаптер ETL, который устанавливается как расширение в конфигурацию 1С и включает в себя набор методов для извлечения необходимых данных.
Получение данных может осуществляться различными способами:
с помощью запроса на языке запросов 1С;
с помощью механизмов компоновки данных;
с помощью кода на языке 1С;
Аналитику нужно будет спланировать, какие конкретно данные нужно извлечь из 1С, в то время как разработчик ETL-процесса должен сформулировать запрос на языке запросов 1С для выполнения этой задачи.
Разработка интеграции на стороне КХД
Возможен сценарий, когда HTTP- или веб-сервис реализуется на стороне КХД, а 1С выступает в роли инициатора передачи данных. В этом случае создается API, который обрабатывает запросы от 1С.
Этот API может быть реализован на подходящем языке программирования (Python, Node.js, Java и т. д.). API должен иметь конечные точки, по аналогии с описанными для HTTP-сервиса на 1С. На стороне 1С нужно разработать процесс, который будет либо регулярно, либо по каким-то триггерам передавать данные в этот API.
API КХД должен:
Проверять информацию на соответствие структуре данных (как она должна выглядеть при обмене — тип, поля, ограничения на значения), чтобы предотвратить ошибки.
Сохранять данные в КХД.
Вести логи для отладки и мониторинга.
Возвращать клиенту информативные сообщения об ошибках.
Аналогично сервису 1С, API КХД необходимо тщательно протестировать:
проверить отдельные функции API и работу в комплексе;
проверить производительность API под нагрузкой и убедиться в защищенности от несанкционированного доступа.
В Modus ETL для взаимодействия с КХД реализован компонент Агент ETL https://kb.modusbi.ru/web/docs_product/agent-etl
Он с помощью API осуществляет запись данных источника в КХД.
Интеграционное тестирование
На этом этапе проверяется работа всей системы в целом.
Тестируйте все сценарии работы системы, включая создание, обновление и удаление информации.
Оцените производительность системы под нагрузкой.
Исправьте все обнаруженные ошибки.
После успешной проверки интеграция разворачивается на продакшн-серверах. Настройте мониторинг обмена данными и отслеживайте логи.
Риски на каждом из этапов и что нужно, чтобы их минимизировать
Чтобы избежать проблем при объединении 1С и КХД, нужна внимательность на каждом шаге настройки.
Подготовительный этап. На этом этапе часто возникают проблемы с пониманием требований, несовместимостью форматов данных и игнорированием нюансов, а также неправильным пониманием целей интеграции и частоты передачи информации. Чтобы минимизировать эти риски, важно тщательно обсуждать требования и цели интеграции, сопоставлять форматы данных, учитывать все детали и нюансы.
Этап настройки сервисов в 1С и КХД. Здесь возможны ошибки в логике запросов, некорректная работа сервиса, проблемы с производительностью, обработкой данных и безопасностью. Для минимизации этих рисков необходимо проверять код, использовать модульное тестирование, оптимизировать запросы, тестировать систему под нагрузкой и обеспечивать корректную обработку данных.
Этап тестирования. Могут возникнуть проблемы с обнаружением ошибок на поздней стадии, конфликты версий ПО и снижение производительности. Чтобы снизить эти риски, проводите тестирование регулярно, используйте тестовую среду и тщательно отлаживайте ошибки.
Промышленная среда. Здесь возможны неожиданные сбои. Например, внезапная перегрузка системы может привести к временной недоступности сервисов. Для минимизации этих рисков необходимо тщательно подготовиться к запуску, проводить мониторинг системы и быстро реагировать на инциденты.
Ответственность команды
На подготовительном этапе определяются цели интеграции, необходимые для обмена данные, форматы обмена и частота синхронизации. Аналитик и архитектор совместно разрабатывают техническое задание, учитывая особенности обеих систем (1С и КХД). Они определяют целесообразность использования HTTP- или WS-сервисов, учитывают возможные ограничения и оценивают сложность интеграции.
Разработчики 1С и КХД, руководствуясь техническим заданием, разрабатывают и настраивают HTTP- или WS-сервисы, пишут код на стороне 1С и тестируют отдельные компоненты сервисов.
Модульное и интеграционное тестирование выполняют QA-инженер (при его наличии), разработчики 1С и КХД, разработчик/руководитель проекта. В ходе тестирования проверяется корректность обмена данными, обработка ошибок и производительность, результаты тестирования документируются.
В промышленной эксплуатации системные администраторы настраивают серверы, проводят резервное копирование и мониторинг системы, а операционные менеджеры координируют запуск системы и обучают пользователей.
Заключение
Интеграция 1С и КХД — это сложный процесс, который требует хорошей подготовки, внимания к деталям и слаженной работы команды. Важно следить за каждым этапом, не спешить и проверять все шаги. Такой подход поможет избежать рисков и добиться успешной и стабильной интеграции.
Для упрощения подобной интеграции можно использовать уже готовые инструменты, например, Modus ETL. Благодаря этому решению задачи, связанные с проектированием HTTP-сервисов, взаимодействием между 1С и КХД, а также тестированием этого взаимодействия, передаются на команду вендора. Сотрудники на стороне заказчика, занимающиеся получением данных, должны пройти через:
планирование и проектирование
интеграционное тестирование
В результате риски, связанные с разработкой HTTP-сервисов, API, настройкой интеграции значительно снижаются. Таким образом, использование подобных инструментов не только ускоряет процесс разработки, но и минимизирует потенциальные риски для заказчика.
lazy_val
Это реальный опыт интеграции?
С какими именно КХД вы в интеграцию умеете?