HTTP-сервис: запросы, метаданные и запись объектов из внешней системы

Задача

Внешней программе часто нужно не «красивое API под одну конфигурацию», а три вещи:

1. понять, какие объекты есть в конкретной базе;

2. выполнить запрос и получить таблицу;

3. точечно записать реквизит или табличную часть уже существующего объекта.

Последнее время все чаще появляются ИИ-агенты или способы работы Cursor и 1С, но при этом нет быстрого способа подключить любого агента напрямую к 1С, чтобы он мог вносить изменения в базу или читать ее не в файловом варианте. При разработке КонфигРедактора, осталось достаточно много интересных функций и модулей по работе напрямую с 1С.

COM-соединение неудобно с Linux и с сервисами. Штатный OData не всегда покрывает произвольный запрос и запись табличных частей «как есть». Писать отдельный HTTP-сервис под каждый документ накладно, если задача — отладка, выгрузка, сверка или тонкий коннектор к своей утилите.

Ниже — универсальный модуль шаблонного HTTP-сервиса. Это не продукт «под ключ» и не замена правам доступа. Это исходник, который администратор сам вставляет в свою конфигурацию или расширение и сам решает, кому его открывать.

К статье приложен файл модуля. Имя обработчика в шаблоне URL — execute1.

Что умеет модуль

Точка входа принимает тело POST в JSON и ветвится по полю action.

Ответ всегда application/json; charset=utf-8. Ошибки — объект {"error": "..."} и код 400 или 500.

Модуль не создаёт новые объекты «с нуля»: write_object работает с уже существующей ссылкой. Создание элементов — отдельная доработка, её в файле нет.
 

Как подключить(краткая инструкция)

1. В конфигураторе или расширении создайте HTTP-сервис, например Connector.

2. Корневой URL — короткий и без «секрета в пути». Секрет должен быть в аутентификации веб-сервера / HTTP-сервиса, а не в адресе.

3. Добавьте шаблон URL, например execute.

4. Метод — POST. Обработчик — экспортная функция execute1 из приложенного модуля (скопируйте текст в модуль HTTP-сервиса).

5. Опубликуйте базу на веб-сервере. Проверьте, что HTTP-сервисы включены в публикации.

6. Назначьте роль: только нужным пользователям разрешите использование этого HTTP-сервиса. Не оставляйте выполнение от пользователя с полными правами «потому что так проще отладить».

Адрес будет вида:

https://сервер/база/hs/Connector/execute

Точное написание зависит от имени сервиса и шаблона в вашей публикации.

Проверка «сервис жив» без полезной нагрузки должна давать 400 и текст про пустое тело — это нормально. Пустой POST специально отвергается.

Контракт: общий вид запроса

Минимальный запрос на выборку:

{
  "query": "ВЫБРАТЬ ПЕРВЫЕ 10 Наименование ИЗ Справочник.Номенклатура",
  "params": {}
}

Поле params — объект. Ключ — имя параметра запроса без амперсанда. Значения приводятся к типам платформы: число, булево, дата, UUID (строка 8-4-4-4-12), обычная строка.

Пример с параметром:

{
  "query": "ВЫБРАТЬ Ссылка, Наименование ИЗ Справочник.Контрагенты ГДЕ ИНН = &ИНН",
  "params": {
    "ИНН": "7700000000"
  }
}

Успешный ответ:

{
  "columns": ["Ссылка", "Наименование"],
  "rows": [
    ["3f2c1a10-....-....-....-............", "ООО Пример"]
  ]
}

Почему таблица, а не массив объектов: так проще разбирать ответ в Python, PowerShell и Excel-подобных конвейерах; имена колонок не нужно угадывать по первой строке. Ссылки в ячейках сериализуются в GUID (через УникальныйИдентификатор()), даты — в yyyy-MM-ddTHH:mm:ss. Пустые значения и хранилища значений в JSON не выводятся.

Если JSON тела разобрать нельзя — 400. Если падает выполнение запроса — 500 и подробное представление ошибки платформы. На боевой базе подробный стек лучше обрезать: сейчас модуль отдаёт ПодробноеПредставлениеОшибки, это удобно при отладке и опасно в открытом контуре.

Действие metadata

{
  "action": "metadata"
}

Внешняя программа получает карту имён. Это нужно, когда база нетиповая или сильно доработана и клиент не хочет хардкодить Справочник.Номенклатура.

Дополнительно модуль собирает только те типы, в строковом представлении которых есть «Ссылка» / Reference. Примитивы (строка, число, дата, булево) в эти словари не попадают. Если клиенту нужна полная схема реквизитов — расширьте СобратьТипыРеквизитов: уберите фильтр по подстроке «Ссылка».

Имена пользователей в метаданных читаются в попытке: на части платформ коллекция недоступна, тогда вернётся пустой массив.

Действие write_object

Нужны prefix, obj_name, guid. Реквизиты — массив, табличные части — объект «имя ТЧ → массив строк».

{
  "action": "write_object",
  "prefix": "Справочник",
  "obj_name": "Номенклатура",
  "guid": "3f2c1a10-1111-2222-3333-444444444444",
  "requisites": [
    {
      "attr": "Комментарий",
      "value": "заполнено из внешней системы"
    }
  ],
  "tabular": {}
}

Префикс понимается по-русски: справочник, документ, плансчетов, планвидовхарактеристик. Английские имена менеджеров в текущей версии не разбираются.

Ссылочный реквизит можно передать объектом:

{
  "type": "reference",
  "guid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "meta": "Справочник.ЕдиницыИзмерения"
}

Либо строкой UUID, если в поле meta_type у элемента requisites уже указан тип ссылки.

Поведение табличных частей жёсткое: ТЧ очищается и заполняется заново. Частичное изменение одной строки без остальных в модуле не предусмотрено. Перед вызовом клиент должен прислать полный снимок ТЧ.

Стандартные поля вроде «Ссылка» / reference пропускаются, чтобы не пытаться присвоить неизменяемый реквизит.

После заполнения вызывается обычный Объект.Записать(). Обработчики записи, подписки и контроль остатков работают. Это не «запись в обход логики» (кроме ветки константы, см. ниже).

Действие write_constant

{
  "action": "write_constant",
  "const_name": "ЗаголовокСистемы",
  "value": "Тестовая база"
}

Для ссылочной константы добавьте value_meta_type, например Справочник.Организации, и передайте GUID.

В приложенном модуле запись константы идёт через получение менеджера и попытку выставить ОбменДанными.Загрузка. На части релизов удобнее заменить блок на прямой вызов:

Константы[ИмяКонстанты].Установить(ЗначениеУстановить);

либо на СоздатьМенеджерЗначения(), присвоение .Значение и Записать(). Если решите оставить обход обмена — делайте это осознанно: подписки на запись константы могут не сработать.

Проверьте эту ветку на своей платформе до выкладки в рабочий контур. Остальные действия от неё не зависят.

Как вызывается снаружи

PowerShell:

$body = @{
  query  = "ВЫБРАТЬ ПЕРВЫЕ 5 Наименование ИЗ Справочник.Номенклатура"
  params = @{}
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://server/db/hs/Connector/execute" `
  -Method Post `
  -ContentType "application/json; charset=utf-8" `
  -Headers @{ Authorization = "Basic ...." } `
  -Body $body

Python:

import requests

r = requests.post(
    "https://server/db/hs/Connector/execute",
    json={
        "query": "ВЫБРАТЬ ПЕРВЫЕ 5 Наименование ИЗ Справочник.Номенклатура",
        "params": {},
    },
    auth=("user", "password"),
    timeout=60,
)
r.raise_for_status()
print(r.json())

Авторизацию берите ту, которую настроили в публикации: basic, cookie infobase user, OS. Модуль сам логин не проверяет — он выполняется уже от имени пользователя HTTP-сервиса.

Устройство сериализации

В модуле три слоя преобразования.

1. Параметр запроса (ПолучитьЗначениеПараметра). Строка-UUID становится УникальныйИдентификатор. Строка, похожая на дату, пробуется через XMLЗначение и Дата(). Остальное остаётся строкой, числом или булевом. Этого достаточно для &ДатаНачала и &Ссылка в типичных запросах, если ссылку передавать UUID и в тексте запроса сравнивать с Ссылка.

2. Ячейка ответа (ЗначениеВJSON). Ссылку пытаемся отдать как GUID. Если у значения нет УникальныйИдентификатор(), уходит Строка(). Хранилище значения отбрасывается: тащить двоичные данные в каждую строку выборки нельзя.

3. Запись из JSON (ПреобразоватьЗначениеИзJSON). Булевы слова true/Да/1, даты, числа с запятой, объект {type, guid, meta}. Ошибка преобразования глотается в нескольких местах: лучше недозаписать поле, чем уронить весь объект. Для критичных реквизитов после вызова перечитайте объект запросом.

Разбор JSON тела сделан с запасом: ПрочитатьЗначениеJSON, затем ПрочитатьJSON, затем ЧтениеJSON.Прочитать(). На новых платформах сработает первый путь.

Безопасность — это не приложение к статье, это условие использования

Модуль выполняет произвольный текст запроса и умеет писать объекты. Это штатный HTTP-сервис вашей базы, а не «дыра с улицы». Если опубликовать его в интернет без аутентификации и с полными правами, последствия те же, что у открытого консоли запросов.

Минимальный набор, без которого файл лучше не включать:

• HTTP-сервис только для служебного пользователя с отдельной ролью.

• Роль не содержит интерактивного удаления, администрирования и лишних прав на запись. Для сценария «только читаем» уберите из модуля ветки write_* совсем.

• Веб-сервер: HTTPS, basic/OS, ограничение по IP или VPN. Не публикуйте сервис на том же endpoint, что пользовательский тонкий клиент, без отдельной публикации.

• На рабочей базе замените произвольный query на белый список: разрешённые имена сохранённых запросов или заранее заданные шаблоны. Текущий файл — для контура разработки и контролируемой интеграции.

• Не логируйте тело запроса целиком: там могут быть персональные данные.

• ПодробноеПредставлениеОшибки на периметре уберите: клиенту достаточно короткого кода.

• Журнал регистрации: фиксируйте пользователя, action, имя объекта, GUID. Текст запроса — по необходимости, в закрытом журнале.

Пункт про белый список повторяю отдельно: приложенный исходник намеренно широкий. Узкий контур — ваша доработка, не «забытая опция».

Файл не обходит лицензирование платформы, не является средством скрытого доступа и не предназначен для работы без ведома администратора информационной базы.

Ограничения текущей версии

• Нет GET, нет пагинации, нет асинхронных длительных запросов. Тяжёлый запрос без ПЕРВЫЕ и без отбора повесит HTTP-поток.

• Нет записи регистров сведений/накопления отдельным action.

• Нет создания объектов и копирования.

• write_object не ставит режим загрузки обмена: сработают проверки проведения и подписки.

• Пользовательские поля составного типа: клиент должен прислать meta, иначе GUID не во что превратить.

• Имена метаданных в metadata — только Имя, без синонимов и комментариев.

• Код рассчитан на управляемое приложение и платформу 8.3 с JSON. На конкретной конфигурации проверьте запись константы и разбор дат.

Если нужно проведение документа — после записи вызывайте Записать(РежимЗаписиДокумента.Проведение) отдельной доработкой. Сейчас модуль этого не делает: проведённый документ при изменении табличной части может потребовать перепроведения, и это уже бизнес-решение, не транспорт.

Отличия от OData/COM/Обмен/Шина/SQL

OData — стандартная витрина объектов. Этот файл — универсальный коннектор разработчика. На периметре без белого списка запросов он опаснее OData: OData не даст выполнить ВЫБРАТЬ по всей базе произвольным текстом.

SOAP web-сервис — жёсткий контракт операций: ПолучитьОстатки(Склад, Дата). Удобно, когда набор методов известен заранее. Тяжелее JSON, хуже для «произвольного запроса».

COM-коннектор — полный объектный модель 1С снаружи. Мощно, но Windows, DCOM, сессии, не HTTP. С Linux-сервиса и из облака обычно не вариант.

Обмен через планы обмена / EnterpriseData / КД — пакетная синхронизация справочников и документов между базами. Не интерактивный «выполни запрос и запиши одну строку».

Шина / ESB / «1С:Шина» — очереди, гарантия доставки, идемпотентность. Это транспорт предприятия, не консоль.

Прямой SQL к СУБД — обходит логику 1С, права, регистраторы. Для прикладной записи объектов не подходит.

Обработка в базе / регламентное задание — нет внешнего HTTP. Файл на диске, ручной запуск.

Итог

Шаблон закрывает типовой зазор между «внешний скрипт» и «консоль запросов внутри базы»: карта метаданных, выборка таблицей, точечная запись. Ставьте его как служебный сервис с узкой ролью. Произвольный запрос на периметре без белого списка — это уже не интеграция, а открытая консоль.