HTTP-сервис в расширении 1С: от пустого объекта до рабочего адреса

HTTP-сервис из расширения публикуется так же, как сервис основной конфигурации: в Конфигураторе через Администрирование → Публикация на веб-сервере. Разница одна, но на ней спотыкаются чаще всего: на вкладке HTTP-сервисов нужно включить флажок «Публиковать HTTP-сервисы расширений по умолчанию». Без него расширение подключено, сервис написан, а по адресу /hs/... веб-сервер отвечает 404.

Частое заблуждение — что для своего API придётся снимать конфигурацию с поддержки. Не придётся. Расширение добавляет HTTP-сервис, роль и общий модуль поверх типовой БП 3.0, ЗУП 3.1 или УТ 11, а обновления типовой ставятся как обычно. Порядок общий для платформы 8.3 и не зависит от прикладного решения.

Что проверить до создания сервиса

Сначала окружение. Если веб-сервер не готов, отлаживать код бессмысленно: любая ошибка будет выглядеть как «сервис не работает ».

Компоненты платформы и веб-сервер

• 🧩 В установке платформы должен стоять компонент «Модули расширения веб-сервера». Без него публикация завершится ошибкой, а в каталоге bin не будет wsisapi.dll (IIS) и wsap24.dll (Apache 2.4).
• 🌐 Веб-сервер установлен и запущен: IIS с компонентами ISAPI-расширений или Apache 2.4.
• 🔢 Разрядность модуля совпадает с разрядностью веб-сервера. 64-битный Apache не загрузит модуль из 32-битной платформы.
• 🔑 Конфигуратор для публикации запускают от имени администратора Windows. Иначе он не сможет записать httpd.conf или создать приложение в IIS.

Права и пользователь базы

• 👤 Заведите в базе отдельного пользователя для интеграции, например api_exchange, с аутентификацией 1С:Предприятия и паролем.
• 🛡️ Дайте ему только нужные роли. Роль с правами на объекты, которые читает или пишет сервис, удобно добавить в само расширение.
• 📁 Для IIS у пользователя пула приложений (обычно группа IIS_IUSRS) должно быть право чтения и выполнения на каталог bin платформы. Для файловой базы ещё и право изменения на каталог базы.

Совместимость расширения

Расширение должно быть применимо к базе: в Конфигураторе откройте Конфигурация → Расширения конфигурации и убедитесь, что у нужного расширения нет ошибок применения. Если основная конфигурация обновилась и расширение перестало применяться, HTTP-сервис из него тоже пропадёт.

Создание HTTP-сервиса в расширении

Откройте расширение в Конфигураторе: Конфигурация → Расширения конфигурации, выделите расширение, кнопка «Конфигурация». В дереве объектов найдите ветку Общие → HTTP-сервисы и добавьте новый объект.

Свойства сервиса

Корневой URL должен быть уникальным среди всех сервисов основной конфигурации и всех подключённых расширений. Если два сервиса претендуют на один адрес, работать будет только один, и не обязательно ваш.

Шаблон URL и методы

У сервиса создайте шаблон URL, например /items/{code}. Фигурные скобки задают параметр: в обработчике его значение придёт в Запрос.ПараметрыURL. Внутри шаблона добавьте метод и укажите HTTP-метод: GET, POST, PUT, DELETE.

У метода есть свойство «Обработчик». Нажмите на лупу рядом — Конфигуратор создаст функцию в модуле сервиса. Функция обязана вернуть объект HTTPСервисОтвет.

Обработчик: пример целиком

Ниже — рабочий обработчик GET, который по коду номенклатуры возвращает наименование в JSON. Он сам проверяет параметр и отдаёт 404, если элемент не найден.

Функция ItemsGET(Запрос)

	Код = Запрос.ПараметрыURL.Получить("code");
	Если Не ЗначениеЗаполнено(Код) Тогда
		Возврат ОтветJSON(400, Новый Структура("error", "Не указан код"));
	КонецЕсли;

	Ссылка = Справочники.Номенклатура.НайтиПоКоду(Код);
	Если Ссылка.Пустая() Тогда
		Возврат ОтветJSON(404, Новый Структура("error", "Не найдено"));
	КонецЕсли;

	Данные = Новый Структура;
	Данные.Вставить("code", Код);
	Данные.Вставить("name", Строка(Ссылка));
	Возврат ОтветJSON(200, Данные);

КонецФункции

Функция ОтветJSON(КодСостояния, Данные)

	Запись = Новый ЗаписьJSON;
	Запись.УстановитьСтроку();
	ЗаписатьJSON(Запись, Данные);

	Ответ = Новый HTTPСервисОтвет(КодСостояния);
	Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
	Ответ.УстановитьТелоИзСтроки(Запись.Закрыть(), КодировкаТекста.UTF8);
	Возврат Ответ;

КонецФункции

Параметры строки запроса (?limit=10) читаются из Запрос.ПараметрыЗапроса, тело POST — через Запрос.ПолучитьТелоКакСтроку().

Сохранение расширения в базе

Сохранить расширение в файл мало. Его нужно записать в базу: в окне конфигурации расширения выполните «Обновить конфигурацию базы данных» (F7). Новый сервис увидят только новые сеансы. Если включено повторное использование сеансов, старые сеансы пула ещё какое-то время работают со старой версией кода.

Публикация сервиса расширения на веб-сервере

Публикуют базу целиком, а не отдельный сервис. В одной публикации живут и веб-клиент, и OData, и все HTTP-сервисы — нужно лишь отметить, какие из них открыть.

Через Конфигуратор

1. Запустите Конфигуратор от имени администратора Windows.
2. Откройте Администрирование → Публикация на веб-сервере.
3. На основной вкладке задайте имя публикации латиницей, например trade, выберите веб-сервер и каталог.
4. Если нужен только API, снимите флажок публикации тонкого и веб-клиента и не включайте OData.
5. Перейдите на вкладку HTTP-сервисов.
6. Включите «Публиковать HTTP-сервисы расширений по умолчанию».
7. Флажок «Публиковать HTTP-сервисы по умолчанию» относится к основной конфигурации. Включайте его только если нужны и типовые сервисы.
8. Нажмите «Опубликовать». Для Apache после публикации перезапустите службу веб-сервера.

После этого сервис доступен по адресу:

http://<сервер>/<имя публикации>/hs/<корневой URL>/<шаблон>
http://srv01/trade/hs/exchange/items/00-00000123

Если сервиса расширения нет в списке

Окно публикации показывает сервисы основной конфигурации, и сервисы расширения там могут не отображаться. Это нормально. Публикацию решают два механизма: флажок публикации сервисов расширений по умолчанию или явная запись о сервисе в файле default.vrd в каталоге публикации.

<?xml version="1.0" encoding="UTF-8"?>
<point xmlns="http://v8.1c.ru/8.2/virtual-resource-system"
       xmlns:xs="http://www.w3.org/2001/XMLSchema"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       base="/trade"
       ib="Srvr=&quot;app01&quot;;Ref=&quot;trade&quot;;">
  <httpServices publishByDefault="false" publishExtensionsByDefault="false">
    <service name="Расш1_Обмен" rootUrl="exchange" enable="true"
             reuseSessions="autouse" sessionMaxAge="20"
             poolSize="10" poolTimeout="5"/>
  </httpServices>
</point>

Явная строка <service> удобнее флажка, когда расширений несколько, а наружу должен смотреть только один сервис. После правки default.vrd для Apache перезапустите службу, иначе изменения не подхватятся.

Через webinst без Конфигуратора

На сервере без графического интерфейса публикуют утилитой webinst из каталога bin платформы. Пример для Apache 2.4 и клиент-серверной базы:

cd "C:\Program Files\1cv8\8.3.25.1374\bin"
webinst -publish -apache24 -wsdir trade -dir "C:\Apache24\htdocs\trade" ^
  -connstr "Srvr=app01;Ref=trade;" ^
  -confpath "C:\Apache24\conf\httpd.conf" ^
  -descriptor "C:\deploy\trade.vrd"

Номер версии в пути замените на свой. Ключ -descriptor подставляет заранее подготовленный default.vrd. Это главный приём для повторяемых развёртываний: файл лежит рядом с исходниками расширения, и публикация на тестовом и рабочем сервере получается одинаковой. Для IIS вместо -apache24 и -confpath используется ключ -iis.

Почему сервис не отвечает: разбор по кодам

Начинайте с адреса /hs/<корневой URL>/ping из браузера. Код ответа сразу сужает круг причин.

Журнал регистрации как главный инструмент

Каждый вызов HTTP-сервиса открывает сеанс от имени пользователя, указанного при аутентификации. Поэтому ошибки обработчика видно в журнале регистрации: отберите события по пользователю интеграции и уровню «Ошибка». Там будет текст исключения и строка модуля.

Если в журнале пусто, запрос до базы не дошёл. Ищите причину на уровне веб-сервера: логи IIS в C:\inetpub\logs\LogFiles, у Apache — error.log в каталоге logs.

Обновление платформы ломает публикацию

Этот сценарий стоит держать в голове отдельно. В конфигурации веб-сервера прописан полный путь к модулю wsisapi.dll или wsap24.dll внутри каталога конкретной версии. После установки новой платформы и удаления старой путь становится битым, а все публикации перестают отвечать. Лечится повторной публикацией из Конфигуратора новой версии или командой webinst с тем же дескриптором.

Расширение в облаке и на чужом сервере

Если база живёт в облачном сервисе — 1С:Фреш, у хостинг-провайдера или в аренде, — веб-сервер вам не принадлежит. Конфигуратора с правами администратора Windows тоже нет. Значит, публиковать будет провайдер.

Что обычно меняется в облаке:

• 📮 Публикацию HTTP-сервиса заказывают через поддержку провайдера. Сообщите имя сервиса, корневой URL и нужен ли доступ к сервисам расширений.
• 🔍 Расширения в сервисах с разделением данных проходят проверку провайдером, прежде чем их разрешат подключать. Закладывайте на это время.
• 🔒 Расширение работает в безопасном режиме. Обращения к файлам на сервере, внешним компонентам и COM-объектам из обработчика будут падать с ошибкой — проектируйте сервис без них.
• 🧭 Адрес сервиса задаёт провайдер. В базах с разделением данных он может включать номер области, поэтому точный адрес берите у поддержки, а не собирайте сами.

Перед тем как отдавать расширение в облако, прогоните его на локальной копии в безопасном режиме. Свойство «Безопасный режим» есть в окне управления расширениями. Если сервис отработал там, в облаке сюрпризов будет меньше.

Как закрыть сервис от посторонних

HTTP-сервис — это дверь в базу. Опубликовали на внешний адрес — значит, в неё будут стучаться.

Минимальный набор мер

Чего не делать

• 🚫 Не прописывайте логин и пароль пользователя в строку ib файла default.vrd. Тогда любой, кто знает адрес, работает от имени этого пользователя без аутентификации.
• 🚫 Не выдавайте пользователю интеграции роль «Полные права». Создайте в расширении свою роль с правами только на нужные объекты.
• 🚫 Не публикуйте по Basic-аутентификации на HTTP без шифрования в интернет. Заголовок с паролем кодируется Base64, а не шифруется.

Частые вопросы