Перейти к основному содержимому

HTTP-сервисы 1С

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ
Разработчику Архитектору

Что такое HTTP-сервис​

HTTP-сервис — объект метаданных, с помощью которого прикладное решение 1С:Предприятие 8.3 публикует собственный REST-подобный интерфейс. Внешняя система обращается по URL и HTTP-методу; платформа сопоставляет запрос с шаблоном URL и вызывает обработчик на BSL.

Это альтернатива OData (OData в 1С), когда нужен узкий контракт "под задачу", а не универсальный доступ ко всем объектам конфигурации. Web-сервис (SOAP) — отдельный механизм для XML и WSDL — Web-сервисы 1С (SOAP).

КритерийHTTP-сервисOData
НастройкаШаблоны URL + код обработчикаПубликация объектов конфигурации
Гибкость контрактаВысокаяСтандартизированная модель ресурсов
Типичное применениеМаркетплейс, мобильное приложение, свой микросервисВитрина данных, отчётность, интеграция "как к таблицам"

Структура URL​

Общий вид адреса:

http://host/base/hs/<КорневойURL>/<относительныйURL>?параметры
ЧастьЗначение
http://host/baseURL публикации информационной базы (как у веб-клиента)
hsОбращение к HTTP-сервису (ws — к Web-сервису SOAP)
<КорневойURL>Свойство Корневой URL объекта HTTP-сервис (например, orders)
<относительныйURL>Совпадает с одним из шаблонов URL сервиса

Пример: сервис с корневым URL employees и шаблоном /code/{Код}:

https://server.example/erp/hs/employees/code/00001

При разделении данных разделители указывают только в URL базы; параметр Z в query для HTTP-сервисов не поддерживается.

Создание в конфигураторе​

  1. Общие → HTTP-сервисы — новый сервис, задать Корневой URL.
  2. Шаблоны URL — один или несколько шаблонов.

Символы в шаблоне:

  • обычные сегменты пути (/prices, /date);
  • {ИмяПараметра} — параметризованный сегмент (доступен в Запрос.ПараметрыURL);
  • * — "хвост" URL (например, отбор в /*);
  • / — разделитель сегментов.

Примеры шаблонов — /list, /item/{Код}, /documents/{id}/props/{PropertyName}/*.

  1. Для каждого шаблона — объекты Метод с выбором HTTP-метода — GET, POST, PUT, PATCH, DELETE или Любой.
  2. У метода — обработчик (функция в модуле HTTP-сервиса).

Если URL не сопоставился ни с одним шаблоном и методом, платформа вернёт 404 Not Found.

Обработчик запроса​

Сигнатура обработчика:

Функция СписокGET(Запрос) Экспорт
    
    Ответ = Новый HTTPСервисОтвет(200);
    // ...
    Возврат Ответ;
    
КонецФункции

Вход: HTTPСервисЗапрос — метод (HTTPМетод), ПараметрыURL, ПараметрыЗапроса (после ?), заголовки, тело (строка или двоичные данные).

Выход: HTTPСервисОтвет — код состояния, заголовки, тело (строка JSON/XML, двоичные данные или файл).

Пример — список с JSON​

Код ITЗагрузка примера кода…

Подробнее про формирование JSON — JSON в интеграции 1С.

Коды ответа в обработчике​

КодКогда
200Успех, тело с данными
204Успех без тела (например, DELETE)
400Неверные параметры запроса
404Объект не найден
500Исключение на сервере — лучше логировать и возвращать безопасное сообщение

Оборачивайте бизнес-логику в Попытка ... Исключение и не отдавайте клиенту внутренний стек — см. Обработка ошибок 1С.

Публикация​

HTTP-сервис работает только после публикации на веб-сервере (IIS, Apache и др.) через стандартный мастер публикации 1С. Включите флажок публикации HTTP-сервисов и укажите те сервисы, которые должны быть доступны снаружи.

Права: доступ проверяется по пользователю, под которым выполняется сеанс сервиса (Basic, Windows или настройки публикации). Валидируйте входные данные в коде обработчика.

Расширения конфигурации​

HTTP-сервисы можно добавлять в расширение без снятия конфигурации с поддержки. Флажок "Публиковать HTTP-сервисы расширений" по умолчанию публикует все сервисы расширения. Чтобы опубликовать только часть, отредактируйте файл default.vrd и удалите лишние записи.

HTTP-сервис и REST​

Действие определяется HTTP-методом — GET — чтение, POST — создание или команда, PUT/PATCH — изменение, DELETE — удаление. Соглашения REST соблюдаете вы в коде обработчика — платформа лишь маршрутизирует запрос.

Клиент для проверки

DELETE и POST из браузера напрямую не отправить — используйте Postman или curl или HTTP-запросы из 1С.

Связанные материалы​

Содержание