При интеграции 1С с внешними системами (веб-сайтами, мобильными приложениями, сторонними сервисами) разработчики часто сталкиваются с необходимостью передавать в HTTP-запросы несколько параметров. Например, идентификатор пользователя, ID документа, статус или период выборки. Начинающие разработчики часто используют стандартные строки запроса в стиле «классического веб-программирования», однако платформа 1С:Предприятие предоставляет гораздо более гибкие, безопасные и архитектурно верные механизмы для проектирования REST API.
В этой статье мы подробно разберем четыре основных способа передачи нескольких параметров в HTTP-сервисы 1С. Мы проанализируем преимущества каждого метода, разберем конкретные примеры кода как на стороне отправки (клиента), так и на стороне приема (самого HTTP-сервиса в 1С), а также выясним, когда и какой подход следует применять на практике.
Этот способ является наиболее предпочтительным с точки зрения современной архитектуры веб-сервисов (REST API). Вместо передачи параметров в конце строки после знака вопроса, мы зашиваем структуру параметров непосредственно в сам путь (URI) HTTP-сервиса.
Для реализации этого подхода в свойствах вашего HTTP-сервиса в конфигураторе 1С необходимо настроить шаблон URL. Например, зададим следующий шаблон пути:
/users/{idПользователя}/documents/{idДокумента}
В данном случае платформа 1С автоматически поймет, что фрагменты пути внутри фигурных скобок являются переменными (параметрами), которые необходимо извлечь из строки запроса.
Разберем по шагам, как прочитать такие параметры на стороне HTTP-сервиса 1С. Когда внешний клиент отправляет запрос на адрес вида https://myserver/BIS/hs/InDocSinh/users/555/documents/111, платформа автоматически разбирает путь и помещает параметры в специальную коллекцию Запрос.ПараметрыURL.
Рассмотрим пример кода в методе-обработчике HTTP-запроса (например, при методе GET):
Функция ПолучитьДанныеДокумента(Запрос)
// Получаем параметры, которые платформа автоматически извлекла из шаблона URL
ИдентификаторПользователя = Запрос.ПараметрыURL.Получить("idПользователя");
ИдентификаторДокумента = Запрос.ПараметрыURL.Получить("idДокумента");
// Проверим, заполнены ли ключевые параметры
Если ПустаяСтрока(ИдентификаторПользователя) Или ПустаяСтрока(ИдентификаторДокумента) Тогда
Ответ = Новый HTTPСервисОтвет(400); // Bad Request
Ответ.УстановитьТелоИзСтроки("Не указаны обязательные параметры запроса.");
Возврат Ответ;
КонецЕсли;
// Здесь выполняется бизнес-логика поиска и обработки данных
// ...
Ответ = Новый HTTPСервисОтвет(200); // OK
Ответ.УстановитьТелоИзСтроки("Данные успешно обработаны для пользователя: " + ИдентификаторПользователя);
Возврат Ответ;
КонецФункции
Преимущества использования шаблонов URL:
Этот метод часто называют классическим. Параметры передаются в самом конце URL в формате «ключ-значение», разделяясь символом амперсанда &. Именно этот вариант изначально использовал автор темы на форуме:
https://myserver/BIS/hs/InDocSinh?id_document=111&id_user=555
Несмотря на то, что этот подход кажется менее «современным», он абсолютно легитимен и активно применяется во всех веб-технологиях. В платформе 1С для работы с такими параметрами предназначено свойство Запрос.ПараметрыЗапроса.
Выясним, как правильно обработать такие параметры в коде 1С:
Функция ОбработатьПараметрыЗапроса(Запрос)
// Читаем параметры из коллекции ПараметрыЗапроса
ИдентификаторДокумента = Запрос.ПараметрыЗапроса.Получить("id_document");
ИдентификаторПользователя = Запрос.ПараметрыЗапроса.Получить("id_user");
// Параметры запроса (после знака ?) часто являются необязательными.
// Поэтому хорошей практикой является установка значений по умолчанию.
Если ИдентификаторПользователя = Неопределено Тогда
ИдентификаторПользователя = "ТекущийПользователь";
КонецЕсли;
// Логика обработки данных
// ...
Ответ = Новый HTTPСервисОтвет(200);
Ответ.УстановитьТелоИзСтроки("Документ " + ИдентификаторДокумента + " обработан.");
Возврат Ответ;
КонецФункции
Когда лучше использовать параметры запроса:
/documents?status=active&limit=50&sort=desc).Когда параметров становится действительно много (больше 3–5 штук) или они представляют собой сложные, развесистые структуры (массивы, таблицы, вложенные объекты), передавать их через строку адреса становится невозможно. Во-первых, существуют ограничения веб-серверов на длину строки URL (обычно около 2048 символов). Во-вторых, передача конфиденциальных данных (таких как пароли или персональные данные) в открытом виде в URL крайне небезопасна, так как они логируются веб-серверами.
Для методов изменения данных (таких как POST, PUT, PATCH) стандартом индустрии является передача параметров внутри тела запроса в формате JSON.
Рассмотрим детально, как это реализовать на практике с двух сторон.
Шаг 1. Отправка параметров из внешней системы (или другой базы 1С):
// Формируем структуру параметров
ПараметрыЗапроса = Новый Структура;
ПараметрыЗапроса.Вставить("id_document", "111");
ПараметрыЗапроса.Вставить("id_user", "555");
ПараметрыЗапроса.Вставить("status", "Проведен");
// Сериализуем структуру в строку JSON
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ПараметрыЗапроса);
СтрокаJSON = ЗаписьJSON.Закрыть();
// Создаем HTTP-запрос
Запрос = Новый HTTPЗапрос("/hs/InDocSinh");
Запрос.Заголовки.Вставить("Content-Type", "application/json");
Запрос.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8);
// Далее отправляем данный запрос через HTTPСоединение...
Шаг 2. Получение и десериализация параметров внутри HTTP-сервиса 1С:
Функция ОбработатьТелоЗапроса(Запрос)
// Получаем сырые данные тела запроса в виде строки
ТелоСтрокой = Запрос.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8);
Если ПустаяСтрока(ТелоСтрокой) Тогда
Ответ = Новый HTTPСервисОтвет(400);
Ответ.УстановитьТелоИзСтроки("Пустое тело запроса");
Возврат Ответ;
КонецЕсли;
// Десериализуем строку JSON обратно в структуру 1С
Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(ТелоСтрокой);
Попытка
Параметры = ПрочитатьJSON(Чтение);
Исключение
Ответ = Новый HTTPСервисОтвет(400);
Ответ.УстановитьТелоИзСтроки("Некорректный формат JSON: " + ОписаниеОшибки());
Возврат Ответ;
КонецПопытки;
// Теперь мы можем свободно обращаться к параметрам как к свойствам структуры
ИдентификаторДокумента = Параметры.id_document;
ИдентификаторПользователя = Параметры.id_user;
ТекущийСтатус = Параметры.status;
// Выполняем запись данных или проведение документа
// ...
Ответ = Новый HTTPСервисОтвет(200);
Ответ.УстановитьТелоИзСтроки("Пакет параметров успешно обработан.");
Возврат Ответ;
КонецФункции
Важное примечание: Если вызывающая система присылает данные в классическом формате HTML-форм (Content-Type: application/x-www-form-urlencoded), платформа 1С автоматически преобразует тело запроса и поместит все переданные ключи в стандартную коллекцию Запрос.ПараметрыЗапроса, избавляя вас от необходимости вручную парсить строку.
Иногда на форумах можно встретить советы передавать бизнес-параметры внутри HTTP-заголовков (Запрос.Заголовки). Однако профессиональные разработчики предостерегают от этого шага. Использование заголовков для передачи обычных учетных данных (например, ID номенклатуры или контрагента) считается грубым нарушением стандартов веб-разработки (антипаттерном).
Для чего действительно нужно использовать заголовки:
Authorization: Bearer [токен]).Content-Type: application/json).Подведем итоги нашего детального разбора. Выбор архитектуры передачи параметров в 1С должен опираться на характер этих данных: