HTTP-сервисы
Contents
Введение. Теория http-сервисов
Одним из самых распространённых способов взаимодействия между приложениями в интернете является использование веб-сервисов. Суть в том, что одно приложение — назовём его поставщиком веб-сервиса — публикует свой сервис по уникальному веб-адресу (URL). Другие приложения, потребители, могут обращаться к этому адресу.
Существует несколько подходов к реализации веб-сервисов, отличающихся архитектурой и используемыми протоколами. В платформе «1С:Предприятие» поддерживаются два основных типа:
- HTTP-сервисы — это веб-сервисы, построенные по архитектуре REST (Representational State Transfer). Они работают поверх стандартного HTTP-протокола, используют простые URL-адреса и форматы данных, такие как JSON или XML. Благодаря своей простоте и гибкости REST стал самым популярным подходом для создания современных веб-сервисов.
- Web-сервисы — это сервисы, работающие по протоколу SOAP (Simple Object Access Protocol). Они используют строгую структуру сообщений на основе XML и описываются с помощью специального языка WSDL. SOAP-сервисы чаще применяются в корпоративных системах, где важны стандартизация, безопасность и надёжность.
В этой статье я подробно рассмотрю HTTP-сервисы (REST), так как они наиболее востребованы в современной разработке и активно используются при интеграции с внешними системами. Первая часть посвящена созданию собственных REST-сервисов — от архитектурных решений до реализации. Вторая часть демонстрирует, как эффективно взаимодействовать с уже существующими сервисами. Каждая часть самодостаточна и может быть использована независимо, а вместе они образуют полное руководство — от создания до потребления.
Разработка HTTP-сервисов
Подготовка базы
Чтобы наглядно показать, как работает HTTP-сервис в «1С:Предприятии», воспользуемся типичной структурой метаданных, которая встречается в большинстве учётных конфигураций, таких как «1С:Управление торговлей» или «1С:ERP».
Справочник «Номенклатура»
Основные реквизиты:
ВидНоменклатуры — ссылка на перечисление ВидыНоменклатуры (например, «Товар», «Услуга», «Материал»).
ЕдиницаИзмерения — ссылка на справочник Единицы измерения (штуки, килограммы, часы и т.д.).
Описание — произвольный текст, поясняющий особенности номенклатурной позиции.
Справочник «Контрагенты»
Основные реквизиты:
ИНН — строка, содержащая идентификационный номер налогоплательщика. Может быть пустой, если контрагент — физическое лицо без ИНН.
ЮрФизЛицо — ссылка на перечисление ЮрФизЛицо, которая указывает, является ли контрагент юридическим или физическим лицом.
ПолноеНаименование — официальное название организации или ФИО физического лица.
Документ «Реализация товаров»
Отражает факт отгрузки товаров или оказания услуг клиенту (рис.2).
Реквизиты документа:
Контрагент — ссылка на справочник Контрагенты (указывает, кому отгружено).
СостояниеОтгрузки — ссылка на перечисление СостоянияОтгрузки (например, «Не отгружено», «Частично отгружено», «Полностью отгружено»).
Табличная часть «Товары» содержит список отгруженных позиций:
Номенклатура — ссылка на справочник Номенклатура.
Количество — числовое значение (в выбранной единице измерения).
Цена — стоимость одной единицы.
Сумма — рассчитывается автоматически как Количество × Цена.
Создание HTTP сервиса. Пример 1
Придумаем задачу. Предположим, нужно получить список всей номенклатуры из одноименного справочника «Номенклатура».
В ветке Общие > HTTP-сервисы добавим HTTP-сервис с именем Номенклатура, который будет получать информацию из справочника Номенклатура. Свойство Корневой URL для сервиса установим как nomenclature.
Далее требуется создать у HTTP-сервиса подчиненный объект Шаблон URL, чтобы с помощью него можно было сопоставить URL, по которому произошло обращение к сервису, с одним из имеющихся HTTP-методов.
На вкладке Шаблоны URL добавим у нашего HTTP-сервиса шаблон URL с именем ПолучитьНоменклатуру и укажем шаблон URL get_nomenclature.
Затем для шаблона URL добавим метод GET, который будет вызван при сопоставлении этого шаблона с URL запроса к HTTP-сервису.
Далее, нажав на кнопку открытия в поле Обработчик, создадим обработчик этого метода. Имя обработчика автоматически формируется путем соединения имени шаблона URL и имени самого метода. Это имя можно изменить в дальнейшем по своему желанию, хотя делать это не рекомендуется.
В модуле нашего HTTP-сервиса будет создан шаблон функции-обработчика Get(), которая получает на вход параметр типа HTTPСервисЗапрос и должна вернуть объект типа HTTPСервисОтвет. Заполним эту функцию следующим образом.
Функция ПолучитьНоменклатуруGet(Запрос)
Ответ = Новый HTTPСервисОтвет(200);
СтрокаJSON = пр_ОбщегоНазначения.Номенклатура();
Ответ.УстановитьТелоИзСтроки(СтрокаJSON);
Ответ.Заголовки.Вставить("Content-Type","application/json");
Возврат Ответ;
КонецФункции
В переменной Ответ мы сразу же создаем объект типа HTTPСервисОтвет, который содержит ответ, формируемый HTTP-сервером на поступивший запрос. Ответ имеет стандартный код возврата HTTP (КодСостояния=200). Код состояния 200 сообщает об успешном выполнении запроса. Другие коды состояния, возвращаемых HTTP-сервером, будут использоваться во втором примере.
А также приложим листинг кода общего метода Номенклатура()
Функция Номенклатура() Экспорт
Запрос = Новый Запрос;
Запрос.Текст =
"ВЫБРАТЬ
| Номенклатура.Артикул КАК cod,
| Номенклатура.Наименование КАК name,
| ПРЕДСТАВЛЕНИЕ(Номенклатура.ВидНоменклатуры) КАК type,
| Номенклатура.Описание КАК description
|ИЗ
| Справочник.Номенклатура КАК Номенклатура";
Результат = Запрос.Выполнить();
Выборка = Результат.Выбрать();
Массив = Новый Массив;
Структура = Новый Структура("cod, name, type, description");
Пока Выборка.Следующий() Цикл
ЗаполнитьЗначенияСвойств(Структура, Выборка);
Массив.Добавить(Структура);
КонецЦикла;
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, Массив);
СтрокаJSON = ЗаписьJSON.Закрыть();
Возврат СтрокаJSON;
КонецФункции
Публикация HTTP-сервис на веб-сервере
Прежде чем проверить работу HTTP-сервис, его нужно опубликовать на веб-сервере. Для этого в диалоге публикации информационной базы на веб-сервере, на закладке HTTP сервисы, установим флажок Публиковать HTTP сервисы по умолчанию и отметим имеющиеся HTTP-сервисы, к которым мы хотим предоставить доступ из внешних систем.
Проверка работы HTTP сервиса
Запускаем браузер. Прописываем в строке браузера ip адрес компьютера, на котором работает веб-сервис (в нашем случае это наша локальная машина). После этого, если веб-сервер запущен, мы должны увидеть в браузере соответствующее сообщение.
Далее в строке браузера прописываем путь к нашему сервису по определенному правилу: Ip адрес / имя публикации / hs / корневой каталог / шаблон/.
В текущем примере строка будет иметь следующий вид: http://localhost/InfoBase/hs/nomenclature/get_nomenclature.
В результате в окне браузера мы увидим список всей номенклатуры из справочника Номенклатура.
Создание HTTP сервиса. Пример 2
Усложним задачу. Предположим, нужно получить информацию о документах реализации. Чтобы усложнить задачу, добавим при обращении к сервису некое уникальное свойство (например, ИНН), по которому будем идентифицировать контрагента.
В ветке Общие > HTTP-сервисы добавим новый HTTP-сервис с именем Реализация. Свойство Корневой URL для сервиса установим как realization.
Добавим у HTTP-сервиса объект Шаблон URL ПолучитьРеализации с шаблоном /get_realization/{Код}. В коде будем передавать ИНН Контрагента.
Затем для шаблона URL добавим метод GET, который будет вызван при сопоставлении этого шаблона с URL запроса к HTTP-сервису. Шаблон URL ПолучитьРеализацию описан с помощью шаблона /get_realization/{Код}. Этот шаблон содержит непараметризованный сегмент get_realization и параметризованный сегмент {Код}. Это означает, что любые символы, которые могут присутствовать в URL запроса к сервису после символов «/get_realization/», будут трактоваться как параметр URL Код, который можно получить из переданного в функцию параметра Запрос.
Далее, нажав на кнопку открытия в поле Обработчик, создадим обработчик этого метода.
Функция ПолучитьРеализацииGet(Запрос)
Ответ = Новый HTTPСервисОтвет(200);
Код = Запрос.ПараметрыURL.Получить("Код");
Если Код = Неопределено Тогда
Ответ = Новый HTTPСервисОтвет(400);
Ответ.УстановитьТелоИзСтроки("Не задан ИНН контрагента");
Ответ.Заголовки.Вставить("Content-Type","application/json");
Возврат Ответ;
КонецЕсли;
КонтрагентСсылка = Справочники.Контрагенты.НайтиПоРеквизиту("ИНН", Код);
Если КонтрагентСсылка = Справочники.Контрагенты.ПустаяСсылка() Тогда
Ответ = Новый HTTPСервисОтвет(404);
Ответ.УстановитьТелоИзСтроки("Контрагент не найден");
Ответ.Заголовки.Вставить("Content-Type","application/json;");
Возврат Ответ;
КонецЕсли;
СтрокаJSON = пр_ОбщегоНазначения.РеализацииТоваров(Код);
Ответ.УстановитьТелоИзСтроки(СтрокаJSON);
Ответ.Заголовки.Вставить("Content-Type","application/json;")
Возврат Ответ;
КонецФункции
Сначала в обработчике мы получаем значение параметра Код (Запрос.ПараметрыURL.Получить(«Код»)) и анализируем его. Если этот параметр URL не определен, то мы прекращаем работу функции и возвращаем ответ сервиса с кодом состояния 400, сообщающим об ошибке запроса.
Затем находим клиента по ИНН в справочнике Контрагента по значению параметра Код. Если контрагент не найден, то мы прекращаем работу функции и возвращаем ответ сервиса с кодом состояния 404, сообщающим об этом.
Код состояния HTTP — это трехзначное число, которое сервер возвращает клиенту в ответ на HTTP-запрос. Он указывает результат обработки запроса. В примере используются самые популярные, однако существует множество других кодов, описывающие различные сценарии взаимодействия.
Таким образом мы рассмотрели самые частые коды состояния
Если контрагент найден, мы получаем все документы реализации и сериализуем данные документов в JSON с помощью метода ЗаписатьJSON() объекта глобального контекста СериализаторXDTO. Результат записи сохраняем в строку JSON в переменную Результат. После этого с помощью метода УстановитьТелоИзСтроки() устанавливаем тело ответа HTTP-сервиса из строки Результат и возвращаем ответ сервиса в переменной Ответ.
А также приложим листинг кода общего метода РеализацииТоваров().
Функция РеализацииТоваров(Код) Экспорт
Запрос = Новый Запрос;
Запрос.Текст =
"ВЫБРАТЬ
| РеализацияТоваровТовары.Ссылка.Номер КАК number,
| РеализацияТоваровТовары.Ссылка.Дата КАК date,
| ПРЕДСТАВЛЕНИЕ(РеализацияТоваровТовары.Номенклатура) КАК product,
| РеализацияТоваровТовары.Количество КАК amount,
| РеализацияТоваровТовары.Цена КАК price,
| РеализацияТоваровТовары.Сумма КАК sum
|ИЗ
| Документ.РеализацияТоваров.Товары КАК РеализацияТоваровТовары
| ВНУТРЕННЕЕ СОЕДИНЕНИЕ Справочник.Контрагенты КАК Контрагенты
| ПО РеализацияТоваровТовары.Ссылка.Контрагент = Контрагенты.Ссылка
| И (Контрагенты.ИНН = &ИНН)";
Запрос.УстановитьПараметр("ИНН", Код);
Результат = Запрос.Выполнить();
Выборка = Результат.Выбрать();
Массив = Новый Массив;
Структура = Новый Структура("number, date, product, amount, price, sum");
Пока Выборка.Следующий() Цикл
ЗаполнитьЗначенияСвойств(Структура, Выборка);
Массив.Добавить(Структура);
КонецЦикла;
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, Массив);
СтрокаJSON = ЗаписьJSON.Закрыть();
Возврат СтрокаJSON;
КонецФункции
Проверка работы HTTP сервиса.
Снова запускаем браузер. Далее, в строке браузера прописываем путь к нашему сервису: http://localhost/InfoBase/hs/realization/get_realization/7728395580. В результате в окне браузера мы увидим данные по всем реализациям выбранного контрагента.
Либо такой результат в случае отсутствия контрагент в базе с указанным ИНН.
Обращение к HTTP-сервисам
Теперь рассмотрим как из системы «1С:Предприятие» можно обратиться к любому произвольному HTTP-сервису, опубликованному в Интернете. Для обращения к HTTP-сервисам и REST-интерфейсу (OData) используются такие объекты встроенного языка, как HTTPСоединение, HTTPЗапрос и HTTPОтвет:
- объект HTTPСоединение предназначен для взаимодействия с внешними системами по протоколу HTTP;
- объект HTTPЗапрос предназначен для описания HTTP-запросов, отправляемых через объект HTTPСоединение. Позволяет задать адрес запрашиваемого ресурса, заголовки и тело запроса;
- объект HTTPОтвет предоставляет доступ к содержимому ответа HTTP-сервера на запрос.
Обратимся к HTTP-сервисам, написанным ранее, но на этот раз из другой информационной базы. Например,получим список всей номенклатуры из справочника Номенклатура. Это можно сделать с помощью HTTP-сервиса Номенклатура с корневым URL nomenclature.
Создадим обработку с полем для ввода Адреса, в котором хранится URL для обращения к HTTP-сервису. Обработчик команды, получающей данные, заполним следующим образом:
&НаКлиенте
Процедура Получить(Команда)
Сообщение = Новый СообщениеПользователю;
Попытка
HTTPСоединение = Новый HTTPСоединение("localhost");
Исключение
Сообщение.Текст = "Не удалось соединиться с сервером";
Сообщение.Сообщить();
Сообщение.Текст = ОписаниеОшибки();
Сообщение.Сообщить();
Возврат;
КонецПопытки;
// аутентификация по логину и паролю
Basic = "Админ" + ":" + "123";
Basic = Base64Строка(ПолучитьДвоичныеДанныеИзСтроки(Basic));
Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", "Basic " + Basic);
HTTPЗапрос = Новый HTTPЗапрос(СокрЛП(Адрес), Заголовки);
Попытка
Результат = HTTPСоединение.ВызватьHTTPМетод("GET", HTTPЗапрос);
Сообщение.Текст = Результат.ПолучитьТелоКакСтроку();
Сообщение.Сообщить();
Исключение
Сообщение.Текст = ОписаниеОшибки();
Сообщение.Сообщить();
Возврат;
КонецПопытки;
КонецПроцедуры
В поле адрес указываем тот же URL, который мы вводили для этого в браузере, – InfoBase/hs/nomenclature/get_nomenclature – и вызываем команду Получить данные. В результате в окне сообщений мы увидим ответ сервера, содержащий список всей номенклатуры:
Теперь получим информацию о документах реализации по ИНН контрагента. Это можно сделать с помощью HTTP-сервиса Реализации с корневым URL realization.
В поле ввода обработки укажем тот же URL, который мы вводили для этого в браузере, – InfoBase/hs/realization/get_realization/7728395580 – и нажимаем кнопку Получить данные. В результате в окне сообщений мы увидим ответ сервера, содержащий информацию по реализованным товарам по выбранному контрагенту.
Итоги
В статье представлено руководство по работе с HTTP-сервисами в платформе «1С:Предприятие», охватывая как создание собственных REST-сервисов, так и обращение к внешним системам. Это поможет систематизировать или освежить знания по интеграции 1С-систем с внешними сервисами и построению современных REST-интерфейсов на базе платформы.
Используемые источники: Е. Ю. Хрусталёва Технологии интеграции «1С:Предприятия 8.3»
Comments
So empty here ... leave a comment!