В современной разработке на платформе 1С:Предприятие 8.3 интеграция через HTTP-сервисы стала стандартом де-факто (поможет система управления интеграциями и потоками данных). Это позволяет системе взаимодействовать с мобильными приложениями, веб-сайтами и другими внешними сервисами через протокол HTTP, используя архитектурный стиль REST. В данной статье мы подробно разберем, как создать собственный HTTP-сервис, настроить шаблоны URL и реализовать обработку входящих запросов с возвратом данных в формате JSON.
Прежде чем переходить к практике, проанализируем, из каких компонентов состоит HTTP-сервис в 1С. Основным объектом метаданных является HTTPСервис. Внутри него определяются «Корневой URL» и «Шаблоны URL». Каждый шаблон может содержать один или несколько «Методов» (GET, POST, PUT, DELETE и др.), к которым привязываются обработчики в модуле сервиса.
Разберем структуру взаимодействия:
http://server/base/hs/RootURL/Template/.HTTPСервис.HTTPСервисОтвет.Рассмотрим процесс создания нового сервиса. В дереве метаданных перейдем в ветку Общие -> HTTP-сервисы и добавим новый объект. Назовем его, например, ОбменСМаркетплейсом — есть готовый модуль обмена с маркетплейсами по API. В поле «Корневой URL» укажем v1/exchange. Это важный момент: именно этот путь будет стоять после префикса /hs/ в адресе запроса.
Теперь создадим «Шаблон URL». Допустим, мы хотим получать информацию о товаре по его артикулу. Назовем шаблон ПолучитьТовар и укажем в поле «Шаблон» значение /item/{article}. Фигурные скобки означают, что часть пути является параметром, который мы сможем прочитать в коде.
Для созданного шаблона добавим метод GET. В свойстве «Имя метода» укажем GetItemInfo, а в поле «Обработчик» — название функции, которая будет создана в модуле сервиса. Проанализируем, как должна выглядеть сигнатура этой функции:
Функция GetItemInfo(Запрос)
// Здесь будет логика обработки
КонецФункции
Объект Запрос имеет тип HTTPСервисЗапрос. Он содержит всю информацию о входящем сообщении: заголовки, параметры URL, тело запроса.
Рассмотрим подробнее, как извлечь параметр артикула из URL и найти товар в базе данных, реализуя простой обмен данными между базами — для этого есть автоматическая выгрузка данных через REST API. Выясним причину, по которой использование параметров шаблона удобнее, чем передача через строку запроса: это делает API более «чистым» и соответствующим принципам REST.
Функция GetItemInfo(Запрос)
// Получаем артикул из параметров URL
АртикулТовара = Запрос.ПараметрыURL.Получить("article");
// Ищем товар в справочнике
ТоварСсылка = Справочники.Номенклатура.НайтиПоРеквизиту("Артикул", АртикулТовара);
Если ТоварСсылка.Пустая() Тогда
// Возвращаем ошибку 404, если товар не найден
Ответ = Новый HTTPСервисОтвет(404);
Ответ.УстановитьТелоИзСтроки("Товар с артикулом " + АртикулТовара + " не найден");
Возврат Ответ;
КонецЕсли;
// Формируем структуру для ответа
ДанныеТовара = Новый Структура;
ДанныеТовара.Вставить("Наименование", ТоварСсылка.Наименование);
ДанныеТовара.Вставить("Цена", ТоварСсылка.Цена);
ДанныеТовара.Вставить("Остаток", 10); // Для примера
// Преобразуем в JSON
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ДанныеТовара);
СтрокаJSON = ЗаписьJSON.Закрыть();
// Формируем успешный ответ
Ответ = Новый HTTPСервисОтвет(200);
Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
Ответ.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Возврат Ответ;
КонецФункции
Теперь разберем ситуацию, когда нам нужно не получить, а принять данные, например, создать новый заказ. Для этого создадим метод POST. Посмотрим на пример кода, который считывает тело запроса и десериализует его из формата JSON.
Функция CreateOrder(Запрос)
// Читаем тело запроса
СтрокаJSON = Запрос.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8);
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);
ДанныеЗаказа = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();
Попытка
// Начинаем транзакцию для создания документа
НачатьТранзакцию();
НовыйЗаказ = Документы.ЗаказПокупателя.СоздатьДокумент();
НовыйЗаказ.Дата = ТекущаяДата();
// Заполнение полей из структуры ДанныеЗаказа...
// НовыйЗаказ.Контрагент = ДанныеЗаказа.Customer;
НовыйЗаказ.Записать(РежимЗаписиДокумента.Запись);
ЗафиксироватьТранзакцию();
Ответ = Новый HTTPСервисОтвет(201); // Created
Ответ.УстановитьТелоИзСтроки("Заказ успешно создан: " + НовыйЗаказ.Номер);
Исключение
ОтменитьТранзакцию();
Ответ = Новый HTTPСервисОтвет(500); // Internal Server Error
Ответ.УстановитьТелоИзСтроки("Ошибка при создании заказа: " + ОписаниеОшибки());
КонецПопытки;
Возврат Ответ;
КонецФункции
Проанализируем несколько критически важных моментов, которые часто упускают разработчики при настройке интеграций:
Администрирование -> Публикация на веб-сервере. На вкладке «HTTP-сервисы» обязательно должна стоять галочка напротив вашего сервиса.Basic Authentication, передавая закодированные учетные данные в заголовке Authorization. Рекомендуется создать отдельного пользователя с минимальными правами (роль только на выполнение этого сервиса).ЖурналРегистрации или специальный регистр сведений, особенно на этапе отладки. Это поможет быстро выяснить причину, если внешняя система сообщает об ошибке.ЗаписатьJSON всегда обращайте внимание на настройки сериализации дат. Для отладки полезно использовать просмотрщик JSON-структуры через дерево значений. Стандарт ISO 8601 обычно является предпочтительным для внешних систем.Рассмотрим, как эффективно проверять работу созданного API. Использование встроенного отладчика 1С возможно, но требует предварительной настройки. Необходимо запустить сеанс в режиме отладки и в настройках отладки разрешить отладку HTTP-сервисов.
Для отправки тестовых запросов проанализируем специальные инструменты для тестирования http сервисов, такие как Postman или cURL. Они позволяют гибко настраивать заголовки, тело запроса и просматривать ответ сервера, включая HTTP-статусы (200 OK, 404 Not Found, 500 Error).
Посмотрим на пример формирования URL для обращения к опубликованному сервису:
http://myserver/mybase/hs/v1/exchange/item/A105
Где:
myserver — имя сервера или IP;mybase — имя публикации базы;hs — обязательный префикс для всех HTTP-сервисов 1С;v1/exchange — Корневой URL сервиса;item/A105 — путь по шаблону, где A105 — это значение артикула.Мы подробно разобрали процесс создания и программной начинки HTTP-сервисов. Использование объектов HTTPСервисЗапрос и HTTPСервисОтвет в сочетании с механизмами ЗаписьJSON и ЧтениеJSON делает 1С мощным инструментом для построения современных распределенных систем. Разберем и внедрим эти подходы в свои проекты, чтобы обеспечить быструю и надежную интеграцию.