В современной разработке на платформе 1С:Предприятие 8.3 интеграция с внешними веб-сервисами является одной из самых приоритетных задач. Чаще всего для обмена данными используется архитектурный стиль REST, а форматом передачи данных выступает JSON. В данной статье мы подробно разберем, как программно реализовать отправку запросов и получение ответов, проанализируем основные объекты платформы и рассмотрим практические примеры кода.
Для взаимодействия с внешними системами в 1С используется объект HTTPСоединение. Он позволяет установить сессию с сервером, указав адрес, порт и параметры безопасности. Прежде чем отправлять данные, нам необходимо инициализировать это соединение. Рассмотрим основные параметры, которые нам потребуются.
При создании соединения важно учитывать, используется ли защищенное соединение (HTTPS). Для этого применяется объект ЗащищенноеСоединениеOpenSSL. Давайте разберем по шагам процесс инициализации:
HTTPСоединение.
// Инициализация защищенного соединения
Защита = Новый ЗащищенноеСоединениеOpenSSL();
// Указываем хост сервера (без http/https)
Сервер = "api.externalservice.com";
// Создаем соединение
Соединение = Новый HTTPСоединение(Сервер, 443, , , , 30, Защита);
В данном примере мы установили таймаут 30 секунд. Это критически важно для предотвращения зависания сеанса пользователя при нестабильной работе внешнего ресурса. Проанализируем ситуацию: если сервер не ответит вовремя, система сгенерирует исключение, которое мы сможем обработать в блоке Попытка...Исключение.
После установки соединения нам необходимо подготовить сам запрос. Для этого используется объект HTTPЗапрос. В нем указывается ресурс (путь к API) и заголовки. Если мы передаем данные в формате JSON, обязательно нужно указать заголовок Content-Type.
Рассмотрим подробнее, как добавить заголовки авторизации и метаданные запроса:
Запрос = Новый HTTPЗапрос("/v1/data/sync");
Запрос.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
Запрос.Заголовки.Вставить("Authorization", "Bearer " + ТокенДоступа);
Выясним причину, почему кодировка utf-8 обязательна: большинство современных веб-сервисов работают именно с ней, и передача данных в стандартной для Windows кодировке (Windows-1251) приведет к ошибке парсинга на стороне сервера или "битым" символам в кириллице.
Чтобы отправить данные из 1С (например, структуру или массив), их нужно преобразовать в строку JSON. Для этого в платформе предусмотрен объект ЗаписьJSON. Мы можем записывать данные вручную или использовать метод ЗаписатьJSON, который автоматически преобразует объекты 1С в формат JSON.
Разберем пример создания тела запроса из структуры:
// Подготовим данные
ДанныеОбъекта = Новый Структура;
ДанныеОбъекта.Вставить("id", "12345");
ДанныеОбъекта.Вставить("name", "Наименование товара");
ДанныеОбъекта.Вставить("price", 1500.50);
// Сериализация в JSON
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ДанныеОбъекта);
СтрокаЗапросаJSON = ЗаписьJSON.Закрыть();
// Поместим строку в тело запроса
Запрос.УстановитьТелоИзСтроки(СтрокаЗапросаJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Обратите внимание на параметр ИспользованиеByteOrderMark.НеИспользовать. Для многих API наличие BOM-символа в начале строки является критической ошибкой, поэтому мы явно указываем его отсутствие.
Теперь, когда соединение установлено и запрос сформирован, мы выполняем отправку. В зависимости от задачи используются методы ВызватьHTTPМетод, ОтправитьДляОбработки (POST) или Получить (GET). Чаще всего для передачи данных используется POST.
Посмотрим на пример выполнения запроса и анализа полученного кода состояния:
Попытка
Ответ = Соединение.ОтправитьДляОбработки(Запрос);
КодСостояния = Ответ.КодСостояния;
Если КодСостояния = 200 Или КодСостояния = 201 Тогда
// Успешное выполнение
СтрокаОтвета = Ответ.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8);
ОбработатьРезультат(СтрокаОтвета);
Иначе
ВызватьИсключение "Ошибка сервера: " + КодСостояния;
КонецЕсли;
Исключение
Сообщить("Произошла ошибка при обмене: " + ОписаниеОшибки());
КонецПопытки;
Важно помнить, что код состояния 200 не всегда гарантирует отсутствие логических ошибок. Рекомендуется также анализировать тело ответа, которое может содержать специфические коды ошибок бизнес-логики внешнего сервиса.
Полученный от сервера текст в формате JSON необходимо превратить обратно в объекты 1С (Структуры и Массивы) для дальнейшей работы. Для этого используется объект ЧтениеJSON.
Проанализируем процесс парсинга:
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаОтвета);
Результат = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();
// Теперь мы можем обращаться к данным как к структуре
Если ТипЗнч(Результат) = Тип("Структура") И Результат.Свойство("status") Тогда
Если Результат.status = "success" Тогда
Сообщить("Данные успешно синхронизированы!");
КонецЕсли;
КонецЕсли;
Метод ПрочитатьJSON является универсальным инструментом. Он автоматически рекурсивно обходит все вложенные элементы JSON и создает соответствующие им коллекции 1С. Это значительно упрощает код по сравнению с ручным перебором токенов.
При реализации обмена данными через REST API следует придерживаться нескольких важных правил, которые помогут сделать интеграцию отказоустойчивой:
ФоновоеЗадание. Это позволит пользователю продолжать работу с интерфейсом 1С, пока идет обмен.Свойство(), так как структура ответа API может измениться без уведомления со стороны разработчиков сервиса.Рассмотрим пример использования фонового задания для отправки данных:
// Код на стороне клиента
ПараметрыЗадания = Новый Структура("ДанныеДляОтправки", МоиДанные);
ФоновыеЗадания.Выполнить("ИнтеграцияСервер.ОтправитьДанныеНаСервер", ПараметрыЗадания);
Таким образом, мы обеспечиваем высокую отзывчивость системы. Интеграция через REST API с использованием JSON в среде 1С — это мощный инструмент, который при правильной настройке объектов HTTPСоединение, HTTPЗапрос и средств работы с JSON позволяет связать 1С практически с любым современным веб-приложением или сервисом.