Коннектор 1С

Коннектор 1С переносит в базу знаний компании организации, контрагентов, подразделения, номенклатуру и договоры из учётной базы 1С — через стандартный интерфейс OData, только на чтение. Статья для администраторов, которые подключают 1С к платформе. Обоснование — TAI-ADR-0056 (решение 7).

Как устроен

Коннектор — агент описанием onec-connector пакета company-knowledge, вид исполнителя observer (см. Агенты описанием). Его контейнер работает на узле fleet в сети, откуда видна база 1С, и раз в интервал делает проход:

sequenceDiagram
    participant A as onec-connector
    participant O as 1С (OData)
    participant CP as Control Plane
    participant M as Память
    A->>CP: GET /agents/me — ревизия: адрес, база, профиль, интервал
    loop каждый intervalSeconds
        A->>O: GET $metadata — сверка с профилем
        A->>O: GET <набор>?$select=Ref_Key,DataVersion,DeletionMark,…&$top=500&$skip=…
        A->>O: карточки только изменившихся записей
        A->>CP: POST /knowledge/snapshots — полный снимок на объект
        CP->>M: сверка: открыть, изменить, закрыть
        A->>CP: ревизия изменилась? — выход 75, узел поднимет новую
    end

1. $metadata. Профиль сверяется с базой. Объект, чьего набора сущностей или полей в базе нет, пропускается с предупреждением в журнале — его записи в базе знаний не закрываются.
2. Дельта по DataVersion. По каждому объекту постранично (по 500 строк) читаются Ref_Key, DataVersion, DeletionMark и поля фильтра. Карточка дочитывается только у записи с новой версией, остальные берутся из кэша состояния.
3. Полный снимок. Из кэша собирается полный снимок источника onec:<база> на каждый объект профиля (scope — набор сущностей, например Catalog_Номенклатура#items). Запись, пропавшая из 1С или помеченная на удаление, в снимок не попадает и закрывается сверкой. Без изменений в 1С snapshotId тот же, и память узнаёт повтор.
4. Состояние (кэш версий и карточек) — файл в томе реплики. Он сохраняется только после того, как ядро приняло снимки.

Сбой — ни одного снимка

Сбой любой страницы OData прерывает проход целиком: снимки не отправляются, состояние не меняется, записи не закрываются. Следующий проход начинает заново. Сбой отправки в ядро тоже оставляет прежнее состояние.

Запросы к 1С — только GET к <baseUrl>/odata/standard.odata/<набор> с $format=json, $select, $top/$skip и $metadata; таймаут запроса — 60 секунд.

Профили типовых конфигураций

Профиль — данные: какие наборы сущностей OData читать, в какой вид онтологии company@1 их класть, какое поле — ключ, какие поля — атрибуты, какой фильтр строк и какие связи строить по полям-ссылкам.

Профиль	Конфигурация	Объекты
bp30	1С:Бухгалтерия предприятия 3.0	Catalog_Организации, Catalog_Контрагенты, Catalog_ПодразделенияОрганизаций, Catalog_Номенклатура (группы и позиции), Catalog_ДоговорыКонтрагентов
ut11	1С:Управление торговлей 11	Catalog_Организации, Catalog_Контрагенты, Catalog_СтруктураПредприятия, Catalog_Номенклатура (группы и позиции), Catalog_ДоговорыКонтрагентов
erp2	1С:ERP Управление предприятием 2	как ut11
ka2	1С:Комплексная автоматизация 2	как ut11
zup3	1С:Зарплата и управление персоналом 3	Catalog_Организации, Catalog_ПодразделенияОрганизаций, Catalog_Должности

Что читает и чего не читает

Объект 1С	Вид	Ключ	Атрибуты	Связи
организации	legal_entity, own: true	ИНН	полное и краткое наименование, ИНН, КПП, ОГРН	—
контрагенты — только юридические лица, не группы	legal_entity, own: false	ИНН	полное и краткое наименование, ИНН, КПП	—
подразделения	org_unit	unit:onec:<база>:<Ref_Key>	наименование, код	unit_of — к родителю или организации
группы номенклатуры	offering_group	group:onec:<база>:<Ref_Key>	наименование	item_of — к родительской группе
номенклатура	offering	offering:onec:<база>:<Ref_Key>	полное наименование, артикул, тип (product, service, work — по признаку конфигурации)	item_of — к группе
договоры контрагентов	agreement	agreement:onec:<база>:<Ref_Key>	номер, предмет (наименование), дата, срок действия → validUntil	party_to — от контрагента к договору
должности (zup3)	role	role:<Ref_Key>	наименование	—

Запись без ключа (например, контрагент без ИНН) в снимок не попадает. Пустые ссылки и пустые даты 1С (0001-01-01) атрибутами не становятся.

Сотрудники и физические лица не читаются

Ни один профиль не читает справочники сотрудников и физических лиц; контрагент берётся, только если он юридическое лицо. Даже профиль зарплатной конфигурации читает только организации, подразделения и должности. Людей в базе знаний нет — роли связываются с платформой атрибутом platformRole (см. База знаний компании).

Коннектор ничего не пишет в 1С: у него нет ни одного запроса, кроме чтения.

Учётные данные

Служебный пользователь OData — секрет узла onec-credentials: файл в каталоге секретов узла, в контейнере — /run/secrets/onec-credentials. Формат — login:password или JSON {"user": "…", "password": "…"}.

• Секрет перечитывается каждый цикл: смена пароля не требует перезапуска.
• Значение уходит только заголовком Authorization (Basic). В журналы, исключения, снимки и артефакты оно не попадает, в окружение процесса — тоже.
• Нет файла или он не разбирается — цикл пропускается с предупреждением (без значения), агент продолжает работать.
• 1С ответила 401 или 403 — проход прерывается с сообщением «проверьте секрет».

Права пользователя OData

Выдайте служебному пользователю в 1С только чтение и только тех объектов, что перечислены в профиле: коннектору другого не нужно.

Описание агента

apiVersion: taimen.ai/v1
kind: Agent
key: onec-connector
spec:
  displayName: 1C connector
  identity:
    kind: agent
    permissions: [observations.write]
  work:
    workspace: ${KNOWLEDGE_WORKSPACE_ID}
  executor:
    kind: observer
    params:
      entrypoint: taimen_onec.agent:observe
      intervalSeconds: 3600
      config:
        baseUrl: http://1c.example.local/accounting
        base: accounting
        profile: bp30
  placement:
    requires: [onec-access]
    secrets: [onec-credentials]
    resources: {cpus: 0.5, memoryMb: 256}
  state: stopped

Параметр	Что значит
work.workspace	workspace базы знаний, куда идут снимки (переменная установки KNOWLEDGE_WORKSPACE_ID)
config.baseUrl	адрес публикации базы; запросы идут на <baseUrl>/odata/standard.odata/…
config.base	имя базы — часть источника onec:<base> и ключей записей
config.profile	bp30, ut11, erp2, ka2 или zup3
intervalSeconds	как часто делать проход; по умолчанию 3600
identity.permissions	observations.write — право на POST /knowledge/snapshots

Не меняйте base у работающего коннектора

Имя базы входит в источник и в ключи. Новое имя — новый источник: записи со старыми ключами останутся под старым источником и не закроются сами.

Процесс коннектора завершается кодом 2, если конфигурация неверна (нет baseUrl, base или profile, неизвестный профиль, у агента нет work.workspace, исполнитель не observer); 0 — агент остановлен; 75 — новая ревизия описания, узел поднимет контейнер на ней.

Установка и включение

1. Онтология. В дереве workspace базы знаний включён пакет company@1 (см. Регистрация и включение).

2. Образ коннектора на машине узла — собирается из корня поставки:

   docker build -t taimen/onec-connector:local -f integrations/onec/Dockerfile .
   

3. Узел fleet в сети, откуда видна 1С: метка onec-access, исполнитель observer с этим образом, секрет onec-credentials (см. Узлы и fleet):

   labels: [onec-access]
   executors:
     observer:
       image: taimen/onec-connector:local
       dataPath: /data
   secretsDir: /etc/fleet-node/secrets
   

   install -m 0600 /dev/null /etc/fleet-node/secrets/onec-credentials
   cat > /etc/fleet-node/secrets/onec-credentials   # login:password, затем Ctrl-D
   

4. Проверка профиля на базе — без записи в платформу:

   taimen-onec check --base-url http://1c.example.local/accounting --profile bp30 \
       --credentials-file ./onec-credentials
   

   {
     "Catalog_Организации": {"ok": true, "missing": []},
     "Catalog_Номенклатура#items": {"ok": false, "missing": ["Услуга"]}
   }
   

   Код выхода 0 — все объекты профиля есть в базе. Объект с ok: false коннектор будет пропускать.

5. Описание агента — адрес, имя базы и профиль в executor.params.config, state: running; применение пакета company-knowledge (см. Пакеты каталога). Контроллер fleet разместит агента на узле с меткой и секретом.

Типичные проблемы

Симптом	Причина	Что делать
агент не размещается	нет узла с меткой onec-access, секретом onec-credentials или исполнителем observer	проверить node.yaml и каталог секретов узла
в журнале «проход пропущен»	секрета нет, он пуст или не разбирается	записать login:password или JSON {user, password}
«1С отказала в доступе (401/403)»	неверный логин или пароль, нет прав на объекты	проверить пользователя OData в 1С
«1С недоступна»	узел не видит 1С, публикация OData не работает	проверить сеть узла и baseUrl
«объект … пропущен — в базе нет …»	конфигурация отличается от типовой профиля	taimen-onec check; выбрать другой профиль; данные объекта загрузить таблицей
процесс завершается с кодом 2	конфигурация агента неверна	проверить executor.params.config и work.workspace
контрагента нет в базе знаний	это физическое лицо или у него нет ИНН	так задумано: физические лица не читаются, запись без ключа пропускается
записи не закрываются после удаления в 1С	проход прерывается сбоем	устранить сбой; закрытие случится на первом успешном проходе

См. также

• База знаний компании
• Шаблоны загрузки
• Агенты описанием
• Узлы и fleet
• Контекст задачи и память