Как реализовать веб-сервис в 1С для передачи данных в формате JSON?

← На главную

В современной разработке интеграция между 1С и внешними системами (сайтами, мобильными приложениями, сторонними сервисами) чаще всего строится на обмене данными в формате JSON. В рамках данной статьи мы разберем, как правильно реализовать веб-сервис в среде 1С:Предприятие, который принимает параметры (например, идентификаторы и даты) и возвращает результат выполнения запроса в компактном формате JSON. Мы проанализируем разницу между технологиями SOAP и HTTP, рассмотрим примеры кода и выясним, какой подход наиболее эффективен.

Выбор технологии: Web-сервисы (SOAP) или HTTP-сервисы?

Первым делом нам необходимо определиться с типом сервиса. В 1С существуют два основных механизма:

Web-сервисы (SOAP): Это классический протокол, который базируется на XML. Основная особенность в том, что SOAP всегда упаковывает данные в так называемый "конверт" (Envelope). Даже если вы попытаетесь вернуть строку JSON через такой сервис, клиент (например, Postman или браузер) получит XML-документ, внутри которого в одном из тегов будет лежать ваша JSON-строка. Это создает лишнюю нагрузку на парсинг и увеличивает объем трафика.
HTTP-сервисы: Это более современный и гибкий подход. Они позволяют работать напрямую с HTTP-протоколом. Мы можем сами управлять заголовками (Header) и телом ответа (Body). Именно HTTP-сервисы являются "золотым стандартом" для передачи чистого JSON, так как позволяют установить заголовок Content-Type: application/json.

Рассмотрим ситуацию, описанную пользователем в обсуждении: при попытке вызвать Web-сервис через Postman возвращается ошибка soap:Client. Это происходит потому, что Web-сервис ожидает строго определенную структуру XML, а попытка вернуть "просто текст" через стандартные механизмы SOAP часто приводит к конфликтам типов данных. Рекомендуем использовать именно HTTP-сервисы для любых задач, где требуется JSON.

Реализация HTTP-сервиса для сбора информации

Разберем по шагам процесс создания HTTP-сервиса, который принимает ID и Дату, выполняет запрос к базе данных и возвращает JSON. Для ускорения этого процесса можно взять за основу готовую заготовку интеграции через HTTP-сервис с примерами запросов и обмена данными.

Шаг 1. Настройка шаблона URL

В конфигураторе создадим новый объект HTTP-сервис. В нем настроим шаблон URL, например: /get_data/{ID}/{Date}. Это позволит нам получать параметры прямо из строки запроса.

Шаг 2. Получение параметров и выполнение запроса

В методе GET нашего сервиса напишем код для извлечения параметров и формирования выборки. Проанализируем пример кода:


Функция ДанныеGET(Запрос)
    // Получаем параметры из URL
    Идентификатор = Запрос.ПараметрыURL.Получить("ID");
    ДатаНачала = Запрос.ПараметрыURL.Получить("Date");
    
    // Подготавливаем запрос к БД
    ТекстЗапроса = 
    "ВЫБРАТЬ
    |   Номенклатура.Наименование КАК Имя,
    |   Номенклатура.Код КАК Артикул,
    |   Остатки.КоличествоОстаток КАК Остаток
    |ИЗ
    |   Справочник.Номенклатура КАК Номенклатура
    |ГДЕ
    |   Номенклатура.Ссылка = &Ссылка";
    
    ЗапросКБД = Новый Запрос(ТекстЗапроса);
    ЗапросКБД.УстановитьПараметр("Ссылка", Идентификатор);
    
    РезультатТаблица = ЗапросКБД.Выполнить().Выгрузить();
    
    // Переходим к сериализации
    Возврат СформироватьОтветJSON(РезультатТаблица);
КонецФункции

Сериализация данных в JSON

Теперь рассмотрим подробнее процесс преобразования таблицы значений или выборки запроса в строку JSON. Для этого в 1С предусмотрен мощный объект ЗаписьJSON. Выясним, как правильно его использовать, чтобы избежать ошибок типизации.


Функция СформироватьОтветJSON(ТаблицаДанных)
    Запись = Новый ЗаписьJSON;
    
    // Устанавливаем параметры записи (например, для форматирования дат)
    ПараметрыЗаписи = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Нет, " ", ЭкранированиеСимволовJSON.СимволыВнеASCII);
    Запись.УстановитьСтроку(ПараметрыЗаписи);
    
    // Сериализуем объект 1С (Таблицу значений) в JSON
    ЗаписатьJSON(Запись, ТаблицаДанных);
    
    СтрокаРезультат = Запись.Закрыть();
    
    // Формируем HTTP-ответ
    Ответ = Новый HTTPСервисОтвет(200);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
    Ответ.УстановитьТелоИзСтроки(СтрокаРезультат, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
    
    Возврат Ответ;
КонецФункции

Важный момент: Прямая запись таблицы значений функцией ЗаписатьJSON доступна не во всех версиях платформы для сложных структур. Если ваша версия платформы не поддерживает автоматическую сериализацию таблицы, сначала преобразуйте таблицу в Массив структур, где каждая Структура соответствует строке таблицы.

Обработка дат и специальных типов

Проанализируем ситуацию с датами, упомянутую в сообщении автора. В формате JSON нет специального типа для даты, она передается как строка. По умолчанию 1С использует стандарт ISO 8601. Если вам нужно изменить формат (например, передавать только дату без времени), используйте второй параметр функции ЗаписатьJSON — функцию преобразования или настройки параметров записи.

Если вы все же решили использовать Web-сервисы (SOAP), помните:

Тип возвращаемого значения в функции WS-сервиса должен быть string (строка).
В коде функции вы так же используете ЗаписьJSON, но возвращаете просто итоговую строку.
Потребитель вашего сервиса получит XML, внутри которого будет экранированная строка JSON. Это "двойная работа" для клиента, поэтому для мобильных приложений и веб-сайтов это решение считается плохим тоном.

Тестирование сервиса через Postman

Чтобы убедиться, что наш сервис работает корректно, выполним следующие действия:

Опубликуйте базу на веб-сервере (Apache или IIS).
В Postman выберите тип запроса GET.
Введите адрес вида http://server/base/hs/my_service/get_data/123/2023-10-25.
На вкладке Headers убедитесь, что сервер вернул Content-Type: application/json.

Если вы получаете ошибку "Обязательное возвращаемое значение не задано", проверьте, что в коде 1С во всех ветках алгоритма (включая обработку исключений) оператор Возврат передает объект HTTPСервисОтвет. В случае с Web-сервисом (SOAP) убедитесь, что в свойствах операции в конфигураторе указан "Тип возвращаемого значения".

Подводя итог, можно сказать: реализовать сбор информации и передачу её в JSON не только можно, но и достаточно просто, если использовать HTTP-сервисы и встроенные средства работы с JSON в 1С. Это обеспечит высокую скорость работы и легкость интеграции с любыми современными системами. В качестве альтернативы ручной веб-разработке можно использовать готовый конструктор API для настройки интеграции в формате JSON с автоматическим документированием.