При разработке информационных систем на платформе 1С:Предприятие часто возникает необходимость в интеграции с внешними системами или обмене данными между различными базами 1С — для этого подойдёт модуль обмена данными между базами через HTTP. Одним из наиболее универсальных и распространенных механизмов для решения этой задачи являются HTTP-сервисы. Они позволяют организовать взаимодействие по стандартному протоколу HTTP, что делает их совместимыми с подавляющим большинством современных платформ и приложений.
В этой статье мы подробно рассмотрим, как правильно реализовать HTTP-сервис в 1С 8.3 на управляемых формах. Мы разберем по шагам создание сервиса, его публикацию, обработку различных типов запросов (GET и POST) и формирование ответов, а также покажем, как к такому сервису можно обратиться из другой базы 1С или внешнего клиента. Присоединяйтесь, и давайте вместе создадим работающий HTTP-сервис!
HTTP-сервисы в 1С:Предприятии – это механизм, позволяющий конфигурировать обработчики HTTP-запросов непосредственно внутри конфигурации. Они являются мощным инструментом для организации взаимодействия между различными информационными системами. В отличие от веб-сервисов (SOAP), HTTP-сервисы обычно используются для реализации RESTful API (для этого удобно применять конструктор API для обмена в формате JSON), что предполагает более легковесный и гибкий подход к обмену данными, часто с использованием форматов JSON или XML.
Основные сценарии использования HTTP-сервисов:
Мы сосредоточимся на практических аспектах создания и использования HTTP-сервиса, чтобы вы смогли применить полученные знания в своих проектах.
Давайте начнем с создания самого HTTP-сервиса в конфигураторе. Мы пройдем все необходимые этапы, чтобы получить работающий прототип.
Первым шагом нам необходимо зарегистрировать новый HTTP-сервис в конфигурации 1С. Для этого мы выполним следующие действия:
MyService. Это имя будет использоваться в URL для идентификации нашего сервиса.api. Это позволит нам строить более структурированные URL. Для нашего простого примера оставим пустым.Важно: имя HTTP-сервиса должно быть уникальным в пределах конфигурации.
После создания самого сервиса нам нужно определить, по каким URL-адресам он будет доступен и какие HTTP-методы (GET, POST, PUT, DELETE) он будет поддерживать. Для этого:
MyService в дереве конфигурации./hello. Таким образом, полный URL для обращения к нашему сервису будет выглядеть примерно так: http://[сервер]/[имя_базы]/hs/MyService/hello. Мы также можем использовать переменные в шаблоне, например, /users/{id}, чтобы передавать параметры прямо в URL.Для нашего первого примера, который будет возвращать "Hello, World!", нам понадобится только метод GET:
ОбработкаGet. Эта функция будет располагаться в модуле HTTP-сервиса.Мы определили, что по URL /hello наш сервис будет обрабатывать GET-запросы через функцию ОбработкаGet.
Теперь нам нужно написать код для функции ОбработкаGet. Этот код будет выполняться каждый раз, когда наш HTTP-сервис получит GET-запрос по указанному URL. Для этого:
MyService в дереве конфигурации. Откроется модуль HTTP-сервиса.
// Обработчик GET-запроса для URL-шаблона "/hello"
// Параметр "Запрос" содержит объект ЗапросHTTPСервиса, который предоставляет информацию о входящем запросе.
Функция ОбработкаGet(Запрос)
// Создаем новый объект HTTPСервисОтвет с кодом состояния 200 (ОК).
// Код состояния 200 означает, что запрос был успешно обработан.
Ответ = Новый HTTPСервисОтвет(200);
// Устанавливаем тело ответа. В данном случае, это простая строка "Hello, World!".
// Мы указываем кодировку текста UTF8 и тип контента "text/plain".
// Тип контента важен, чтобы клиент понимал, какого формата данные он получает.
Ответ.УстановитьТелоИзСтроки("Hello, World!", КодировкаТекста.UTF8, "text/plain");
// Возвращаем объект ответа. Система 1С автоматически преобразует его в HTTP-ответ.
Возврат Ответ;
КонецФункции
В этом коде мы создаем объект HTTPСервисОтвет с кодом состояния 200 (что означает успешное выполнение) и устанавливаем в его тело строку "Hello, World!". Важно указать правильную кодировку (КодировкаТекста.UTF8) и тип содержимого ("text/plain"), чтобы клиент мог корректно интерпретировать ответ.
Чтобы наш HTTP-сервис стал доступен извне, необходимо опубликовать базу на веб-сервере (Apache или IIS). Если ваша база уже опубликована, возможно, достаточно будет просто обновить публикацию. Если нет, то выполним следующие действия:
После публикации наш сервис будет доступен по URL, формируемому следующим образом:
http://[имя_веб-сервера]/[имя_публикации_базы]/hs/[имя_HTTP_сервиса]/[URL_шаблон]
Например, если ваша база опубликована как "MyBase" на локальном веб-сервере (localhost), то URL для нашего примера будет:
http://localhost/MyBase/hs/MyService/hello
Откройте эту ссылку в браузере, и вы должны увидеть текст "Hello, World!". Это означает, что ваш первый HTTP-сервис успешно работает!
Простой "Hello, World!" - это хорошо, но на практике нам часто требуется передавать данные в сервис и получать более сложный ответ, например, в формате JSON. Рассмотрим эти возможности.
Для передачи параметров через GET-запрос мы используем стандартные URL-параметры (query parameters). Например: /hello?name=Иван&age=30.
Для получения этих параметров на стороне сервиса мы используем объект Запрос, который передается в обработчик.
// Обработчик GET-запроса, который теперь принимает параметры
Функция ОбработкаGet(Запрос)
// Получаем коллекцию параметров запроса
Параметры = Запрос.ПараметрыЗапросаHTTPСервиса;
// Пытаемся получить параметр "name"
Имя = Параметры.Получить("name");
Если Имя = Неопределено Тогда
Имя = "Гость"; // Значение по умолчанию, если параметр не передан
КонецЕсли;
// Пытаемся получить параметр "age" и преобразовать его в число
ВозрастСтрока = Параметры.Получить("age");
Возраст = Неопределено;
Если ВозрастСтрока <> Неопределено Тогда
Попытка
Возраст = Число(ВозрастСтрока);
Исключение
// Обработка ошибки, если возраст не удалось преобразовать в число
Сообщить("Некорректное значение возраста: " + ВозрастСтрока);
КонецПопытки;
КонецЕсли;
// Формируем ответ
ОтветТекст = "Привет, " + Имя + "!";
Если Возраст <> Неопределено Тогда
ОтветТекст = ОтветТекст + " Вам " + Возраст + " лет.";
КонецЕсли;
Ответ = Новый HTTPСервисОтвет(200);
Ответ.УстановитьТелоИзСтроки(ОтветТекст, КодировкаТекста.UTF8, "text/plain");
Возврат Ответ;
КонецФункции
Теперь, если мы обратимся по адресу http://localhost/MyBase/hs/MyService/hello?name=Алексей, мы получим "Привет, Алексей!". А по адресу http://localhost/MyBase/hs/MyService/hello?name=Ольга&age=25, мы увидим "Привет, Ольга! Вам 25 лет."
Для отправки более сложных данных, таких как объекты или большие объемы информации, обычно используются POST-запросы. Данные в POST-запросах передаются в теле запроса, часто в формате JSON или XML.
Для реализации POST-запроса нам необходимо:
/hello (или создать новый URL-шаблон для POST).
/hello (или нового) добавим новый метод, выбрав "POST".ОбработкаPost.ОбработкаPost в модуле HTTP-сервиса.
// Обработчик POST-запроса
Функция ОбработкаPost(Запрос)
Попытка
// Получаем тело запроса как строку. Обычно это JSON.
ТелоЗапроса = Запрос.ПолучитьТелоКакСтроку();
// Попытаемся разобрать JSON-строку в Структуру или Соответствие 1С.
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(ТелоЗапроса);
ДанныеJSON = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();
// Предполагаем, что получили Структуру с полями "Имя" и "Сообщение"
Если ТипЗнч(ДанныеJSON) = Тип("Структура") Тогда
Имя = ДанныеJSON.Имя;
Сообщение = ДанныеJSON.Сообщение;
ОтветТекст = "Получено от " + Имя + ": " + Сообщение;
Иначе
ОтветТекст = "Некорректный формат JSON или ожидается Структура.";
КонецЕсли;
// Формируем успешный ответ в формате JSON
Ответ = Новый HTTPСервисОтвет(200);
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
РезультатОтвета = Новый Структура;
РезультатОтвета.Вставить("Статус", "Успех");
РезультатОтвета.Вставить("Данные", ОтветТекст);
ЗаписатьJSON(ЗаписьJSON, РезультатОтвета);
Ответ.УстановитьТелоИзСтроки(ЗаписьJSON.Закрыть(), КодировкаТекста.UTF8, "application/json");
Исключение
// Если произошла ошибка (например, некорректный JSON), возвращаем 500 ошибку.
Ответ = Новый HTTPСервисОтвет(500);
Ответ.УстановитьТелоИзСтроки("Ошибка обработки запроса: " + ОписаниеОшибки(), КодировкаТекста.UTF8, "text/plain");
КонецПопытки;
Возврат Ответ;
КонецФункции
В этом примере мы:
Запрос.ПолучитьТелоКакСтроку().ЧтениеJSON и функцию ПрочитатьJSON.ЗаписьJSON и функцию ЗаписатьJSON. Обратите внимание на тип контента "application/json" для JSON-ответа.После изменения кода не забудьте обновить публикацию базы на веб-сервере.
Теперь, когда наш HTTP-сервис готов и опубликован, давайте разберем, как к нему можно обратиться из другой базы 1С или любого внешнего клиента.
Для отправки HTTP-запросов из клиентского кода 1С используются объекты HTTPСоединение и HTTPЗапрос. Мы рассмотрим примеры для GET и POST запросов.
Предположим, мы хотим получить "Hello, World!" или данные с параметрами.
// Функция для выполнения GET-запроса к нашему HTTP-сервису
Функция ВыполнитьGETЗапросКСервису()
// Параметры подключения к серверу, где опубликован HTTP-сервис
// Замените на актуальные данные вашего сервера и публикации
Сервер = "localhost"; // IP-адрес или доменное имя сервера 1С
Порт = 80; // Порт веб-сервера (обычно 80 для HTTP, 443 для HTTPS)
// Полный путь к нашему HTTP-сервису с URL-шаблоном и параметрами
// Для примера с параметрами: "/MyBase/hs/MyService/hello?name=Тест&age=42"
ПутьРесурса = "/MyBase/hs/MyService/hello";
// Создаем объект HTTPСоединение.
// Если используется HTTPS, то указываем четвертый параметр ИспользоватьЗащищенноеСоединение = Истина.
Соединение = Новый HTTPСоединение(Сервер, Порт);
// Создаем объект HTTPЗапрос.
// В конструктор передаем путь к ресурсу.
Запрос = Новый HTTPЗапрос(ПутьРесурса);
// В случае возникновения ошибок, мы их перехватим.
Попытка
// Выполняем GET-запрос. Метод Получить() предназначен для GET-запросов.
Ответ = Соединение.Получить(Запрос);
// Анализируем код состояния ответа. 200 - это успех.
Если Ответ.КодСостояния = 200 Тогда
Сообщить("Успешный ответ сервера:");
Сообщить(Ответ.ПолучитьТелоКакСтроку()); // Получаем тело ответа как строку
Иначе
Сообщить("Ошибка при выполнении GET-запроса. Код состояния: " + Ответ.КодСостояния);
Сообщить("Текст ошибки: " + Ответ.ПолучитьТелоКакСтроку()); // Выводим тело ошибки
КонецЕсли;
Исключение
// Если произошла ошибка на уровне соединения (например, сервер недоступен)
Сообщить("Ошибка соединения с HTTP-сервисом: " + ОписаниеОшибки());
КонецПопытки;
КонецФункции
Для отправки POST-запроса нам нужно передать данные в теле запроса.
// Функция для выполнения POST-запроса к нашему HTTP-сервису
Функция ВыполнитьPOSTЗапросКСервису()
// Параметры подключения к серверу
Сервер = "localhost";
Порт = 80;
ПутьРесурса = "/MyBase/hs/MyService/hello"; // Используем тот же URL-шаблон для примера
Соединение = Новый HTTPСоединение(Сервер, Порт);
Запрос = Новый HTTPЗапрос(ПутьРесурса);
// Подготавливаем данные для отправки в формате JSON
ДанныеДляОтправки = Новый Структура;
ДанныеДляОтправки.Вставить("Имя", "Клиент 1С");
ДанныеДляОтправки.Вставить("Сообщение", "Привет от клиентской базы!");
// Сериализуем структуру в JSON-строку
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ДанныеДляОтправки);
ТелоЗапросаJSON = ЗаписьJSON.Закрыть();
// Устанавливаем заголовок Content-Type, чтобы сервер знал, что мы отправляем JSON
Запрос.УстановитьЗаголовок("Content-Type", "application/json; charset=utf-8");
// Устанавливаем тело запроса
Запрос.УстановитьТелоИзСтроки(ТелоЗапросаJSON, КодировкаТекста.UTF8);
Попытка
// Выполняем POST-запрос. Метод Отправить() предназначен для POST-запросов.
Ответ = Соединение.Отправить(Запрос);
Если Ответ.КодСостояния = 200 Тогда
Сообщить("Успешный ответ сервера на POST-запрос:");
Сообщить(Ответ.ПолучитьТелоКакСтроку());
Иначе
Сообщить("Ошибка при выполнении POST-запроса. Код состояния: " + Ответ.КодСостояния);
Сообщить("Текст ошибки: " + Ответ.ПолучитьТелоКакСтроку());
КонецЕсли;
Исключение
Сообщить("Ошибка соединения с HTTP-сервисом: " + ОписаниеОшибки());
КонецПопытки;
КонецФункции
В POST-запросе мы:
ЗаписьJSON и ЗаписатьJSON.Content-Type: application/json, чтобы сервер знал, что в теле запроса находятся JSON-данные.Запрос.УстановитьТелоИзСтроки().Соединение.Отправить().Как мы уже выяснили, GET-запросы можно просто открыть в браузере. Для POST-запросов и более удобной работы с HTTP-сервисами удобно использовать специализированные клиентские программы, такие как Postman или Insomnia. Они позволяют легко конструировать запросы, устанавливать заголовки, формировать тело запроса и анализировать ответы.
Пример POST-запроса в Postman:
http://localhost/MyBase/hs/MyService/hello.Content-Type: application/json.
{
"Имя": "ВнешнийКлиент",
"Сообщение": "Тестовое сообщение из Postman"
}
При работе с HTTP-сервисами в 1С есть несколько важных моментов, которые помогут вам создавать надежные и эффективные решения.
Всегда старайтесь возвращать корректные HTTP-коды состояния в ответ на запросы. Это стандартный способ информирования клиента о результате выполнения запроса:
Мы видели примеры, где в блоке Попытка...Исключение мы возвращали 500-й код, что является хорошей практикой.
Обязательно указывайте кодировку (обычно UTF8) при работе с текстовыми данными в HTTP-сервисах (как при установке тела ответа на сервере, так и при отправке тела запроса на клиенте), а также при установке заголовка Content-Type.
Например, Ответ.УстановитьТелоИзСтроки(МояСтрока, КодировкаТекста.UTF8, "text/plain"); и Запрос.УстановитьЗаголовок("Content-Type", "application/json; charset=utf-8");.
Если HTTP-сервис предназначен для обмена конфиденциальными данными или выполнения важных операций, необходимо обеспечить его безопасность. В 1С есть встроенные механизмы для работы с HTTP-сервисами, которые могут использовать следующие методы аутентификации:
Authorization.При использовании HTTPСоединение в 1С можно указать имя пользователя и пароль: Соединение = Новый HTTPСоединение(Сервер, Порт, ИмяПользователя, Пароль);.
Мы можем использовать переменные в URL-шаблонах для более гибкой маршрутизации запросов. Например, шаблон /users/{id} позволит вам получить значение id из URL. В обработчике метода вы сможете получить значение этой переменной через свойство Запрос.ПараметрыURL.
// Пример обработчика для шаблона /users/{id}
Функция ОбработкаGetСПараметромURL(Запрос)
IDПользователя = Запрос.ПараметрыURL.Получить("id");
Ответ = Новый HTTPСервисОтвет(200);
Если IDПользователя <> Неопределено Тогда
Ответ.УстановитьТелоИзСтроки("Запрошен пользователь с ID: " + IDПользователя, КодировкаТекста.UTF8, "text/plain");
Иначе
Ответ.УстановитьТелоИзСтроки("ID пользователя не указан.", КодировкаТекста.UTF8, "text/plain");
КонецЕсли;
Возврат Ответ;
КонецФункции
Познакомимся с этими объектами подробнее, так как они являются центральными для обработки запросов:
HTTPСервисЗапрос: Этот объект передается в обработчик HTTP-сервиса и содержит всю информацию о входящем запросе:
Метод: HTTP-метод запроса (GET, POST и т.д.).ПараметрыЗапросаHTTPСервиса: Коллекция параметров URL (query parameters).ПараметрыURL: Коллекция значений переменных, определенных в URL-шаблоне.Заголовки: Коллекция всех заголовков запроса.ПолучитьТелоКакСтроку(), ПолучитьТелоКакДвоичныеДанные(): Методы для получения тела запроса.ИмяПользователя, ИдентификаторСеанса: Информация об аутентифицированном пользователе.HTTPСервисОтвет: Этот объект создается в обработчике и возвращается для формирования ответа:
КодСостояния: Числовой HTTP-код состояния (200, 404, 500 и т.д.).УстановитьТелоИзСтроки(), УстановитьТелоИзДвоичныхДанных(), УстановитьТелоИзПотока(): Методы для установки тела ответа.УстановитьЗаголовок(): Метод для добавления или изменения HTTP-заголовков ответа.Мы рассмотрели процесс создания, публикации и использования HTTP-сервисов в 1С:Предприятии 8.3. Теперь вы знаете, как принимать GET- и POST-запросы, обрабатывать параметры URL и тела запросов (в частности, JSON), а также формировать корректные HTTP-ответы. Мы также научились вызывать эти сервисы из клиентского кода 1С. HTTP-сервисы являются мощным инструментом для интеграции и обмена данными, и их освоение значительно расширит ваши возможности как разработчика 1С.
Не забывайте про тестирование, обработку ошибок и вопросы безопасности при разработке реальных решений. Практикуйтесь, экспериментируйте с различными типами запросов и форматами данных, и вы сможете создавать эффективные и надежные интеграционные решения на платформе 1С!