HTTP-сервисы 1С

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику Архитектору

---

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

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

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

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

---

Структура URL

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

http://host/base/hs/<КорневойURL>/<относительныйURL>?параметры

Часть	Значение
http://host/base	URL публикации информационной базы (как у веб-клиента)
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}/*.

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

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

---

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

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

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

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

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

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

Функция СписокGET(Запрос) Экспорт
    
    Ответ = Новый HTTPСервисОтвет(200);
    Выборка = Справочники.Номенклатура.Выбрать();
    
    Запись = Новый ЗаписьJSON;
    Запись.УстановитьСтроку();
    Запись.ЗаписатьНачалоМассива();
    
    Пока Выборка.Следующий() Цикл
        Запись.ЗаписатьНачалоОбъекта();
        Запись.ЗаписатьИмяСвойства("Код");
        Запись.ЗаписатьЗначение(Выборка.Код);
        Запись.ЗаписатьИмяСвойства("Наименование");
        Запись.ЗаписатьЗначение(Выборка.Наименование);
        Запись.ЗаписатьКонецОбъекта();
    КонецЦикла;
    
    Запись.ЗаписатьКонецМассива();
    Тело = Запись.Закрыть();
    
    Ответ.УстановитьТелоИзСтроки(Тело);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
    Возврат Ответ;
    
КонецФункции

Подробнее про формирование JSON — 128.md.

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

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

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

---

Публикация

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

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

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

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

---

HTTP-сервис и REST

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

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

DELETE и POST из браузера напрямую не отправить — используйте Postman или curl или 130.md.

---

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

• HTTP-запросы из 1С — вызов опубликованного сервиса
• OData в 1С — автоматический REST-интерфейс
• Интеграция — хаб
• HTTP как основа веб-интеграций

---

Проверка себя

• Из чего складывается URL .../hs/prices/date/20240101?
• Где в обработчике взять значение сегмента {Код}?
• Чем HTTP-сервис отличается от OData в вашем проекте?