В современной разработке на платформе 1С:Предприятие 8.3 интеграция через HTTP-сервисы (REST API) стала стандартом де-факто. Это наиболее быстрый и надежный способ организовать обмен данными между 1С и веб-сайтами, мобильными приложениями или другими информационными системами. В рамках данной статьи мы подробно разберем, как спроектировать, реализовать и отладить собственный HTTP-сервис, используя штатные возможности платформы.
Прежде чем переходить к написанию кода, проанализируем ситуацию: нам необходимо предоставить внешней системе доступ к данным 1С (например, остаткам товаров) или возможность записывать данные в 1С (например, новые заказы с сайта). Использование HTTP-сервисов предпочтительнее устаревших технологий типа COM-соединения или тяжеловесных SOAP (Web-сервисов) из-за их легкости, высокой скорости работы и совместимости со всеми современными языками программирования.
Рассмотрим структуру стандартного HTTP-сервиса в 1С. Он состоит из трех основных уровней:
/get_balance/{Artikul}).Разберем по шагам процесс создания. В дереве конфигурации перейдем в ветку Общие — HTTP-сервисы. Создадим новый объект, назовем его ИнтеграцияСАйтом. Поле Корневой URL будет использоваться в адресе обращения. Например, если указать api_v1, то доступ к сервису будет осуществляться по адресу вида http://server/base/hs/api_v1/.
Проанализируем настройку шаблонов. Шаблон URL позволяет использовать переменные в пути запроса. Добавим шаблон ОстаткиТоваров с шаблоном пути /balance/{Артикул}. Фигурные скобки означают, что часть пути Артикул будет передана в 1С как параметр запроса.
Рассмотрим пример создания метода для получения остатка товара по его артикулу. В созданном шаблоне добавим метод ПолучитьОстаток с типом запроса GET. Платформа предложит создать функцию-обработчик в модуле сервиса.
Выясним причину, по которой важно правильно обрабатывать параметры. Нам нужно извлечь артикул из URL и найти соответствующий товар. Посмотрим на пример кода реализации:
Функция ОстаткиТоваровПолучитьОстаток(Запрос)
// Извлекаем параметр из шаблона URL
АртикулТовара = Запрос.ПараметрыURL.Получить("Артикул");
// Инициализируем структуру ответа
Результат = Новый Структура;
Результат.Вставить("Артикул", АртикулТовара);
Результат.Вставить("Остаток", 0);
Результат.Вставить("Статус", "Ошибка: Товар не найден");
// Выполняем поиск товара в базе
ЗапросКБД = Новый Запрос;
ЗапросКБД.Текст =
"ВЫБРАТЬ
| ТоварыНаСкладахОстатки.ВНаличииОстаток КАК Остаток
|ИЗ
| РегистрНакопления.ТоварыНаСкладах.Остатки(, Номенклатура.Артикул = &Артикул) КАК ТоварыНаСкладахОстатки";
ЗапросКБД.УстановитьПараметр("Артикул", АртикулТовара);
Выборка = ЗапросКБД.Выполнить().Выбрать();
Если Выборка.Следующий() Тогда
Результат.Остаток = Выборка.Остаток;
Результат.Статус = "Успех";
КонецЕсли;
// Формируем ответ в формате JSON
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, Результат);
СтрокаОтвета = ЗаписьJSON.Закрыть();
Ответ = Новый HTTPСервисОтвет(200);
Ответ.УстановитьТелоИзСтроки(СтрокаОтвета, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Ответ.Заголовки.Вставить("Content-Type", "application/json");
Возврат Ответ;
КонецФункции
В данном примере мы использовали объект HTTPСервисОтвет для возврата данных. Обратите внимание на установку кода состояния 200 (ОК) и заголовка Content-Type. Это критически важно для того, чтобы внешняя система правильно интерпретировала полученные данные как JSON.
Теперь разберем более сложную задачу: прием данных от внешней системы (например, создание нового заказа). Для этого добавим в шаблон новый метод с типом POST. В этом случае данные передаются не в URL, а в теле запроса.
Проанализируем ситуацию: внешняя система присылает нам JSON-объект с данными заказа. Нам необходимо прочитать тело запроса, преобразовать его в структуру 1С и создать документ. Рассмотрим подробнее код обработки входящего POST-запроса:
Функция ЗаказыСоздатьЗаказ(Запрос)
// Читаем тело запроса в строку
ТелоЗапроса = Запрос.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8);
// Парсим JSON во внутренние структуры 1С
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(ТелоЗапроса);
ДанныеЗаказа = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();
Попытка
// Создаем документ ЗаказКлиента
НовыйЗаказ = Документы.ЗаказКлиента.СоздатьДокумент();
НовыйЗаказ.Дата = ТекущаяДата();
// Предположим, что в JSON передается код контрагента
НовыйЗаказ.Контрагент = Справочники.Контрагенты.НайтиПоКоду(ДанныеЗаказа.КонтрагентКод);
// Заполнение табличной части
Для Каждого СтрокаТовара Из ДанныеЗаказа.Товары Цикл
НоваяСтрока = НовыйЗаказ.Товары.Добавить();
НоваяСтрока.Номенклатура = Справочники.Номенклатура.НайтиПоКоду(СтрокаТовара.Код);
НоваяСтрока.Количество = СтрокаТовара.Количество;
КонецЦикла;
НовыйЗаказ.Записать(РежимЗаписиДокумента.Проведение);
// Формируем успешный ответ
Ответ = Новый HTTPСервисОтвет(201); // 201 Created
Ответ.УстановитьТелоИзСтроки("Заказ успешно создан: " + НовыйЗаказ.Номер);
Исключение
// Обработка ошибок
Ответ = Новый HTTPСервисОтвет(500); // Internal Server Error
Ответ.УстановитьТелоИзСтроки("Ошибка при создании заказа: " + ОписаниеОшибки());
КонецПопытки;
Возврат Ответ;
КонецФункции
Многие разработчики сталкиваются с тем, что сервис не работает после создания. Выясним причину: HTTP-сервис должен быть опубликован на веб-сервере (IIS или Apache) и для него должны быть настроены права доступа.
Для публикации выполним следующие действия:
ИнтеграцияСАйтом.Важный момент: доступ к сервису по умолчанию ограничен. Чтобы внешняя система могла обращаться к 1С, необходимо либо создать специального пользователя с минимальными правами (роль с доступом к HTTP-сервису), либо настроить анонимный доступ в файле default.vrd. Рекомендуется использовать базовую авторизацию (Basic Auth), передавая логин и пароль пользователя 1С в заголовках HTTP-запроса.
Посмотрим на процесс отладки. Чтобы отладить код HTTP-сервиса, необходимо в настройках отладки 1С (Параметры — Отладка) установить режим Отладка через протокол HTTP и убедиться, что на сервере разрешена отладка. После этого можно ставить точки останова в модуле HTTP-сервиса, и они будут срабатывать при внешнем вызове.
Проанализируем производительность. При большом количестве запросов следует избегать тяжелых операций внутри методов сервиса. Если обработка данных занимает много времени, рекомендуется использовать механизм Фоновых заданий: сервис быстро принимает данные, ставит задачу в очередь и возвращает ответ 202 Accepted.
Рассмотрим использование объекта МенеджерHTTPСервисов для динамического анализа доступных интерфейсов, если ваша система предполагает сложную архитектуру с множеством точек входа.
Таким образом, мы разобрали полный цикл создания HTTP-сервиса в 1С: от проектирования шаблонов URL до обработки JSON и публикации. Соблюдение этих правил позволит вам создавать надежные и быстрые интерфейсы для интеграции любой сложности.