Как передавать параметры и атрибуты в HTTPЗапрос при интеграции 1С с внешними REST API?

← На главную

При реализации интеграций 1С с современными веб-сервисами часто возникает вопрос: куда именно в объекте HTTPЗапрос помещать параметры сущностей, которые в документации к API описываются как Attributes или тело запроса? Разберем подробно механику отправки данных методами POST, PUT или PATCH, выясним типовые ошибки при установке тела запроса и рассмотрим готовые примеры кода на платформе 1С:Предприятие 8.3.

Проанализируем архитектуру REST-запросов. В отличие от GET-запросов, где параметры фильтрации передаются непосредственно в строке адреса (URL parameters или query string), операции создания и модификации данных передают параметры в виде полезной нагрузки — тела запроса (payload). В формате JSON эти поля и представляют собой те самые свойства и вложенные атрибуты, которые ожидает веб-сервер. В платформе 1С эти данные загружаются в запрос с помощью метода УстановитьТелоИзСтроки или через потоки данных.

Пошаговая отправка JSON через HTTPЗапрос

Разберем по шагам правильную последовательность действий при формировании и отправке HTTP-запроса с телом JSON:

Формирование структуры данных. Никогда не собирайте JSON простой конкатенацией строк. Используйте встроенные объекты Структура, Соответствие и Массив. Это исключит проблемы с экранированием спецсимволов и кавычек.
Сериализация в JSON. Преобразуем структуру в строку с помощью объектов ЗаписьJSON и функции глобального контекста ЗаписатьJSON.
Настройка заголовков запроса. Сервер должен знать тип передаваемых данных и параметры авторизации. Обязательно указываем заголовок Content-Type: application/json; charset=utf-8 и токен авторизации Authorization.
Заполнение тела запроса с отключением BOM. Это важнейший технический нюанс. При использовании УстановитьТелоИзСтроки платформа 1С по умолчанию может добавить в начало метку порядка байтов (Byte Order Mark, BOM). Большинство внешних веб-серверов не могут распарсить такой JSON и вернут ошибку 400 Bad Request. Поэтому в параметрах метода необходимо явно указать запрет использования BOM.
Выполнение запроса и чтение ответа. Отправляем запрос через защищенное соединение и десериализуем ответ с помощью ЧтениеJSON.

Посмотрим на практический пример реализации отправки запроса на добавление данных:


// 1. Формируем структуру с атрибутами
ДанныеДляОтправки = Новый Структура;
ДанныеДляОтправки.Вставить("email", "user@example.com");
ДанныеДляОтправки.Вставить("role_id", 1);

// Если API требует вложенный блок attributes:
Атрибуты = Новый Структура;
Атрибуты.Вставить("first_name", "Иван");
Атрибуты.Вставить("last_name", "Иванов");
ДанныеДляОтправки.Вставить("attributes", Атрибуты);

// 2. Сериализуем структуру в JSON-строку
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ДанныеДляОтправки);
СтрокаJSON = ЗаписьJSON.Закрыть();

// 3. Создаем HTTP-запрос и заполняем заголовки
АдресРесурса = "/api/latest/spaces/123/users";
Запрос = Новый HTTPЗапрос(АдресРесурса);
Запрос.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
Запрос.Заголовки.Вставить("Accept", "application/json");
Запрос.Заголовки.Вставить("Authorization", "Bearer " + ТокенДоступа);

// 4. Помещаем JSON в тело запроса БЕЗ использования BOM
Запрос.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);

// 5. Инициализируем защищенное HTTPS соединение и отправляем
Сервер = "developers.kaiten.ru";
Защита = Новый ЗащищенноеСоединениеOpenSSL;
Соединение = Новый HTTPСоединение(Сервер, 443, , , , 30, Защита);

Попытка
    Ответ = Соединение.ОтправитьДляОбработки(Запрос);
    
    КодСостояния = Ответ.КодСостояния;
    ТелоОтвета = Ответ.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8);
    
    Если КодСостояния = 200 Или КодСостояния = 201 Тогда
        ЧтениеJSON = Новый ЧтениеJSON;
        ЧтениеJSON.УстановитьСтроку(ТелоОтвета);
        РезультатСтруктура = ПрочитатьJSON(ЧтениеJSON);
        ЧтениеJSON.Закрыть();
    Иначе
        ВызватьИсключение "Ошибка сервиса. Код: " + КодСостояния + ", Ответ: " + ТелоОтвета;
    КонецЕсли;
Исключение
    ВызватьИсключение "Сбой при отправке запроса: " + ОписаниеОшибки();
КонецПопытки;

Особенности отправки запросов с методами PATCH и PUT

Рассмотрим подробнее сценарии, когда API требует обновления данных. Для этого часто применяются HTTP-методы PUT или PATCH.

Если для отправки метода PUT в объекте HTTPСоединение предусмотрен отдельный метод Записать, то для метода PATCH явного метода в платформе нет. Для этого используется универсальный метод ВызватьHTTPМетод:


// Отправка PATCH-запроса для частичного обновления атрибутов
Ответ = Соединение.ВызватьHTTPМетод("PATCH", Запрос);

Оптимизация работы с большими объемами данных

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

Создаем объект ПотокВПамяти.
Инициализируем ЗаписьJSON с передачей потока в метод ОткрытьПоток.
Вызываем ЗаписатьJSON для сериализации структуры.
Закрываем объект записи JSON и передаем поток в тело запроса через метод УстановитьТелоИзПотока или преобразуем в двоичные данные.

Использование готовых интеграционных библиотек

Если проект предполагает большое количество интеграций с внешними REST-сервисами, ручное конструирование объектов HTTPСоединение и HTTPЗапрос может оказаться трудоемким. В сообществе разработчиков 1С стандартом де-факто стали открытые интеграционные библиотеки, такие как библиотека Connector (или инструменты OpenIntegrations). Они инкапсулируют внутри себя рутинную работу с кодировками, заголовками, автоматической сериализацией параметров в JSON и обработкой статус-кодов ответов, позволяя разработчику писать лаконичный и надежный код в одну-две строки.