OData в 1С
Автоматический REST-интерфейс
REST‑интерфейс в 1С — это способ предоставления прикладного функционала через HTTP‑запросы, выстроенный в соответствии с принципами REST: ресурсы адресуются по URL, действия над ними выражаются стандартными HTTP‑методами, а данные передаются в форматах JSON или XML. В платформе 1С такой интерфейс реализуется через HTTP‑сервисы, где разработчик явно описывает маршруты, обработчики и правила преобразования объектов информационной базы в представления, понятные внешним потребителям; REST‑интерфейс востребован для интеграции с веб‑приложениями, мобильными клиентами и сторонними системами, которым требуется простой и гибкий доступ к данным.
Объект конфигурации в 1С — это элемент метаданных, определяющий структуру, поведение и визуальное представление некоторой части прикладного решения: к ним относятся справочники, документы, регистры, отчёты, обработки, планы видов характеристик и другие сущности. Каждый объект конфигурации обладает набором свойств, форм, модулей и правил обработки, а его экземпляры в информационной базе хранят фактические данные; объекты конфигурации формируют каркас приложения, задают бизнес‑логику и определяют, как пользователи взаимодействуют с системой.
Внешняя система в контексте 1С — любая программная среда, не являющаяся частью текущей информационной базы или платформы 1С, с которой требуется организовать обмен данными или вызов функций. Это могут быть CRM, ERP, банковские шлюзы, маркетплейсы, корпоративные порталы или микросервисы; взаимодействие с внешней системой реализуется через веб‑сервисы, HTTP‑сервисы, файловый обмен, прямое подключение к базам данных либо через внешние компоненты, при этом особое внимание уделяется согласованию форматов, обеспечению безопасности и обработке ошибок.
Платформа 1С:Предприятие 8.3 может автоматически опубликовать REST-интерфейс OData к выбранным объектам конфигурации. Внешняя система читает и изменяет данные HTTP-запросами без написания отдельного HTTP-сервиса на каждый сценарий.
| OData | HTTP-сервис | |
|---|---|---|
| Настройка | Отметить объекты в публикации | Шаблоны URL + BSL |
| Контракт | Имена ресурсов по правилам платформы | Любой JSON/XML |
| Когда удобен | Витрины, BI, универсальный доступ | Узкий API "под интеграцию" |
Теория протокола OData — в статье энциклопедии про OData. Здесь — реализация на стороне 1С.
Публикация
Публикация информационной базы — это процедура предоставления доступа к ИБ 1С через внешние каналы: веб‑сервер, HTTP‑сервис или кластер серверов, чтобы к ней могли подключаться клиенты (тонкий, веб‑клиент) либо внешние системы. В процессе публикации настраиваются параметры доступа, аутентификации, маршрутизации запросов и управления сеансами, а также указывается, какие сервисы и ресурсы будут доступны снаружи; результатом публикации становится адрес (URL), по которому пользователи или интеграции обращаются к функционалу базы.
- Опубликовать информационную базу на веб-сервере.
- В мастере публикации включить стандартный интерфейс OData.
- Указать, какие объекты конфигурации доступны через интерфейс.
Корень сервиса:
https://host/base/odata/standard.odata/
Проверка в браузере: откройте этот URL. Если интерфейс жив, но ни один объект не опубликован, придёт минимальный XML/atom-ответ с пустым workspace. После добавления объектов в публикации список ресурсов расширится.
Стандартный интерфейс OData в 1С — это реализация протокола OData (Open Data Protocol) для унифицированного доступа к данным информационной базы: он позволяет читать, создавать, изменять и удалять объекты через HTTP‑запросы с использованием стандартных операций и параметров фильтрации, сортировки и выборки. В 1С OData‑интерфейс автоматически предоставляет доступ к основным прикладным объектам (справочникам, документам, регистрам) без необходимости вручную описывать каждый маршрут, а клиентские приложения могут использовать привычные REST‑паттерны и OData‑параметры для работы с данными.
XML/atom‑ответ — это формат представления данных, соответствующий спецификации Atom Publishing Protocol, где информация передаётся в виде XML‑документа с определённой структурой ленты (feed) и записей (entry). В 1С при работе с OData и некоторыми HTTP‑сервисами система может отдавать ответы в Atom‑формате, где каждый элемент описывает ресурс, его свойства, метаданные и связи; такой формат удобен для сценариев, где требуется совместимость с экосистемой Atom, поддержка пагинации и обновлений лент, хотя в современных интеграциях чаще используют JSON.
Workspace в ответе — это понятие из спецификации Atom, обозначающее логическое пространство (контейнер) внутри ленты, в котором группируются связанные ресурсы или коллекции. В контексте OData/Atom‑ответов 1С workspace может использоваться для структурирования данных по бизнес‑областям или правам доступа, позволяя клиенту различать наборы объектов с разными правилами обработки; на практике в типовых публикациях 1С это поле встречается редко и чаще проявляется при тонкой настройке метаданных сервиса.
Имена ресурсов
Идентификатор ресурса — это уникальная ссылка или ключ, однозначно определяющий конкретный объект в рамках сервиса: в OData это может быть составной ключ или GUID, в REST‑маршрутах — сегмент URL, в Atom‑ответах — элемент id. В 1С идентификатор ресурса позволяет адресовать отдельный экземпляр справочника, документа или регистра, выполнять над ним операции и связывать его с другими объектами; корректное формирование и интерпретация идентификатора критичны для согласованной работы клиентов и сервера.
Идентификатор ресурса: ПрефиксИмяОбъектаСуффикс.
| Объект конфигурации | Префикс в URL |
|---|---|
| Справочник | Catalog |
| Документ | Document |
| Регистр сведений | InformationRegister |
| Регистр накопления | AccumulationRegister |
| Константа | Constant |
| План обмена | ExchangePlan |
| План видов характеристик | ChartOfCharacteristicTypes |
ИмяОбъекта — как в конфигураторе (например, Номенклатура). Пример:
GET .../odata/standard.odata/Catalog_Номенклатура?$format=json
Суффиксы в контексте HTTP‑сервисов и OData 1С — это дополнительные части URL‑маршрута, уточняющие тип операции, версию API или формат ответа. Например, суффикс может указывать на получение табличной части, вызов команды, экспорт в определённый формат или обращение к альтернативному представлению ресурса; использование суффиксов помогает структурировать адресное пространство сервиса и избегать конфликтов имён, делая API более предсказуемым для потребителей.
Суффиксы:
_ИмяТабличнойЧасти— строки табличной части всех документов типа;_RecordSet/ поля набора записей регистра;- виртуальные таблицы регистра — функции вроде
SliceLast()(срез последних), с параметрами как в языке запросов.
Пример среза последних:
.../InformationRegister_ЦеныТоваров/SliceLast()
Параметры запроса
Параметры запроса — это данные, передаваемые вместе с HTTP‑запросом (в строке запроса, заголовках или теле), которые влияют на логику обработки и состав возвращаемых данных. В 1С параметры запроса используются для фильтрации, сортировки, пагинации, выбора полей и указания контекста выполнения; они позволяют клиентам гибко управлять поведением сервиса, не создавая отдельные маршруты под каждый сценарий, и обеспечивают баланс между универсальностью API и производительностью выборки.
| Параметр | Назначение |
|---|---|
$format=json | Ответ в JSON (иначе часто atom-xml) |
$metadata | Описание модели интерфейса |
$filter | Условие отбора |
$select | Список полей |
Заголовок Accept: application/json тоже запрашивает JSON у многих клиентов.
$filter — примеры
| Операция | Ключ | Пример |
|---|---|---|
| Равно | eq | $filter=Description eq 'Товар А' |
| Не равно | ne | $filter=Code ne '00001' |
| Больше | gt | $filter=Цена gt 1000 |
| И | and | $filter=Цена gt 10 and Цена lt 100 |
| ИЛИ | or | $filter=... |
| Начинается с | startswith | $filter=startswith(Description, 'ООО') eq true |
Строковые литералы в фильтре — в одинарных кавычках.
$select
Catalog_Сотрудники?$format=json&$select=Description,Code
Для табличной части: ИмяТабличнойЧасти/ИмяПоля.
Табличная часть в 1С — это подчинённая коллекция строк, хранящая повторяющиеся данные в составе объекта (чаще всего документа или справочника) и связанная с ним по ключу. Каждая строка табличной части содержит набор реквизитов, а сама часть обеспечивает хранение списков позиций, спецификаций, состава работ или любых иных повторяющихся элементов; табличные части активно используются в бизнес‑процессах, участвуют в проведении документов, влияют на формирование движений регистров и отображаются в формах как таблицы с возможностью редактирования и валидации.
HTTP-методы и API 1С
| Операция | HTTP | Метод HTTPСоединение |
|---|---|---|
| Чтение | GET | Получить() |
| Создание | POST | ОтправитьДляОбработки() |
| Частичное изменение | PATCH | Изменить() |
| Полная замена | PUT | Записать() |
| Удаление | DELETE | Удалить() |
Клиентский код — HTTP-запросы из 1С. Тело POST/PATCH обычно JSON с полями сущности.
Обращение к одному элементу
Ссылка на элемент — GUID в скобках:
Catalog_Должности(guid'88d54406-36a1-11e9-8bb2-642737df2048')?$format=json
GUID (Globally Unique Identifier) в 1С — это 128‑битный уникальный идентификатор, применяемый для однозначного обозначения объектов в информационной базе и при обмене данными между системами. В платформе GUID используется как внутренний ключ ссылок, при репликации и синхронизации баз, в интеграционных протоколах и при адресации ресурсов в OData/REST; его уникальность гарантирует отсутствие конфликтов даже при объединении данных из разных источников, а в XML‑ и JSON‑сериализации GUID обычно представляется в каноническом строковом формате.
GUID берут из поля Ref в ответе списка или из базы 1С.
Типичные ошибки
Сначала убедитесь, что открывается корень .../odata/standard.odata/.
| Симптом | Код odata.error | Причина |
|---|---|---|
| "Тип сущности не найден" | 8 | Ошибка в имени объекта (CatalogДолжности вместо Catalog_Должности) |
| "Экземпляр сущности не найден" | 9 | Неверный GUID или объект удалён |
| "Error parsing $filter" | 14 | Опечатка в $filter (например, startwith вместо startswith) |
| Пустой workspace | — | OData включён, объекты не отмечены в публикации |
Тело ошибки JSON:
{
"odata.error": {
"code": "8",
"message": { "lang": "ru", "value": "..." }
}
}
Разбирайте КодСостояния HTTP и поле code внутри ответа.
Безопасность и производительность
- Ограничивайте состав опубликованных объектов — не открывайте всю конфигурацию без необходимости.
- Назначьте отдельного пользователя интеграции с минимальными ролями.
- Тяжёлые выборки без
$filterи$selectнагружают СУБД — проектируйте запросы так же, как запросы 1С. - Переиспользование сеансов интернет-сервисов ускоряет частые вызовы (отдельная тема фазы 3).
Нужен жёсткий контракт для одного партнёра — чаще HTTP-сервис. Нужна витрина "все справочники для отчётности" — OData.