Как подключиться к 1С через API: OData, HTTP-сервис и Жёлтый мост

Какие бывают способы

У 1С нет единого API. Механизмов несколько, и каждый чего-то требует: кто-то требует программиста, кто-то сисадмина и открытый порт, кто-то и того и другого.

OData: стандартный интерфейс платформы

С платформы 8.3.5 у любой конфигурации есть автоматический REST-интерфейс по протоколу OData 3.0. Его включают флажком при публикации базы на веб-сервере, адрес выглядит как /база/odata/standard.odata/. Через него доступны справочники, документы, регистры и их виртуальные таблицы: остатки, обороты, срез последних. Можно читать с отбором, создавать, менять, проводить документы. Права пользователя 1С и обработчики событий при этом работают.

Ограничения следуют из самого протокола:

• нет языка запросов 1С: ни произвольных соединений таблиц по своим условиям, ни группировок с итогами, ни временных таблиц и пакетов. Связанные объекты по ссылкам можно подтянуть через $expand, а своды и группировки считаете у себя;
• отчеты и обработки через OData недоступны;
• ссылки приходят идентификаторами: название контрагента или товара нужно подтянуть через $expand или дочитать отдельным вызовом;
• состав публикуемых объектов задается отдельно, обычно обработкой, и по умолчанию он пустой;
• база должна быть опубликована и доступна снаружи: белый IP, VPN или проброс порта, сертификат.

Про скорость. Когда мы подключали ИИ-ассистента к опубликованной базе через OData, один вызов занимал от 0,9 до 2 секунд, а простой вопрос о продажах потребовал нескольких последовательных вызовов, в сумме около 8-12 секунд. Часть этого времени давала наша первая версия подключения, она дочитывала ссылки по одной. Но сам подход OData к этому подталкивает: свод собирается из нескольких обращений, и каждое стоит сетевого круга. На больших выборках добавляются тайм-ауты и постраничное чтение, об этом отдельный разбор: OData и тайм-аут на больших выборках.

Для простого чтения объектов OData годится. Для вопросов вида «сравни маржу по группам за два квартала» нужен язык запросов, а его в OData нет.

HTTP-сервис в конфигурации

Программист добавляет в конфигурацию объект «HTTP-сервис», задает адреса и методы и пишет обработчик на встроенном языке. Базу публикуют на веб-сервере, сервис отвечает по адресу вида /база/hs/имя/.... Из штатных способов этот дает больше всего свободы: ответ может быть любым, и работает он быстро. Взамен нужны доработка конфигурации, публикация и защита входа. Сервис отдает только то, что в нем написано, новый вопрос означает новую доработку. Подробнее о сервисах и о том, когда они правда нужны, в отдельной практике про четыре способа.

Готовые расширения и модули с HTTP-API

Отдельный класс решений: расширение конфигурации, внутри которого уже есть HTTP-сервис, иногда с выполнением произвольных запросов или кода. Ставится быстрее, чем пишется свой сервис. Но условия те же: публикация базы, веб-сервер, правка файла публикации, входящий доступ. Расширения недоступны на базовых версиях программ и на старых конфигурациях, которые работают в режиме совместимости с прежними версиями платформы (так бывает, например, с конфигурациями на обычных формах), а на сопровождаемой базе каждое обновление нужно проверять. И отдельный риск: если расширение выполняет произвольный код, то при слабой авторизации открытый наружу адрес становится входом для чужих команд в базу. Это свойство всего класса, а не конкретного продукта, поэтому смотреть на авторизацию и права надо внимательно.

COM и внешнее соединение

Программа на той же машине или в той же сети подключается к базе как клиент. Возможностей много, язык запросов доступен полностью. Но это только Windows, нужен зарегистрированный компонент той же версии платформы и нужной разрядности, и после обновления платформы его приходится регистрировать заново. Снаружи сети так обычно не работают.

Обмен файлами

1С по расписанию выгружает файл (XML, CSV, Excel), внешняя система его забирает. Входящий доступ не нужен, и это плюс. Минусы: данные на момент выгрузки, состав файла заранее задан, а обратная запись означает вторую обработку на загрузку.

Сравнение способов

Когда что выбирать

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

OData подойдет, если база уже опубликована, нужно читать отдельные справочники и документы, а своды можно посчитать на своей стороне.

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

Обмен файлами хорош для ночных выгрузок в хранилище, где свежесть в пределах суток устраивает.

Жёлтый мост нужен, когда открывать базу наружу нельзя или некому, конфигурацию менять не хотят, а вопросы заранее не известны: ИИ-ассистент, аналитика, приложение в CRM, бот, разовая сверка. Его границы: база должна быть запущена и обработка работать; ответ приходит не мгновенно, обычно за секунды, а при очереди до 1-2 минут; запросы к одной базе выполняются по очереди. Для тысяч запросов в секунду это не подходит, там нужен свой HTTP-сервис.

Как это решает Жёлтый мост

Обмен идет в обратную сторону. В базе работает внешняя обработка, она сама по исходящему HTTPS забирает задания у шлюза onecdatalink.ru, выполняет их и возвращает результат. Входящих соединений в базу нет ни одного, поэтому не нужны белый IP, веб-сервер и публикация. Конфигурация не меняется, поддержка не снимается. Есть сборки под обычные формы и под старые платформы 8.3.5, а для 1С:Фреш и уже опубликованных баз мост сам читает данные по OData (как это устроено во Фреше).

Что это дает по сравнению с OData:

• Полный язык запросов 1С. Соединения, виртуальные таблицы остатков и оборотов, группировки, итоги, временные таблицы и пакеты. Свод считает сама база, а внешняя система получает готовый результат одним вызовом, без цепочки дочитываний.
• Большие объемы. До 10 000 строк за вызов и постраничное чтение дальше. Для больших регулярных выгрузок есть отдельная выгрузка файлами CSV с докачкой, ее подключают отдельно.
• Запись по правилам. Только на ключе «чтение и запись» и только по разрешению. По умолчанию прогон пробный, с откатом, а повтор с тем же номером операции (request_id) не создаст документ дважды.
• Защита данных. Читающий ключ отклоняет изменяющие конструкции. Маскировка включена по умолчанию: ФИО, ИНН и телефоны закрываются до того, как результат получит внешняя система или ИИ (как устроена маскировка). Каждое обращение пишется в журнал.

Данные при этом идут через сторонний шлюз. Он находится в России, а персональные значения внешняя система получает уже замаскированными. Если для вашей организации любой внешний посредник неприемлем, остается свой HTTP-сервис и своя публикация.

Как подключиться по шагам

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

Коротко

OData есть в платформе, но требует публикации, долго отвечает на сложных вопросах и не знает языка запросов 1С. HTTP-сервис быстрый и гибкий, но это доработка конфигурации, программист и открытый вход в базу. Готовые расширения экономят время на разработке, но оставляют публикацию и риски входящего доступа. Жёлтый мост дает внешним системам и ИИ полный язык запросов и запись по правилам, а база при этом сама ходит наружу и ничего не открывает.

Еще по теме: ИИ и 1С без сервера и открытых портов, ИИ в базу, не открывая ее наружу, как отдать данные из УПП 1.3, из УТ 10.3, из 1С:Фреш, сколько стоит подключить 1С к ИИ.