Прямой API¶
Низкоуровневый синхронный интерфейс — отправка и чтение без участия очередей и фоновых заданий адаптера. Справочное описание методов.
Когда использовать
Прямой API — для случаев, когда нужен немедленный ответ о доставке или необходимо прочитать конкретное сообщение без очереди. Для регулярного обмена используйте очередь.
Готовый пример — в разделе «Примеры»
Законченный рецепт с контекстом (откуда брать ссылку на продюсер, как интегрировать в сервисный модуль) — Пример прямого API.
Методы¶
ПараметрыСообщения(Данные, Ключ)¶
Конструктор описания сообщения.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
Данные | Строка, ДвоичныеДанные, Структура, Массив Из Структура | да | Тело сообщения |
Ключ | Строка | да | Уникальный идентификатор сообщения |
Возврат. Структура с полями Данные, Ключ, Заголовки (Соответствие Из КлючИЗначение).
Отправить(Продюсер, ИмяТопика, Сообщение, Партиция = -1, Сессии = Неопределено)¶
Синхронная отправка сообщения в топик.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
Продюсер | СправочникСсылка.кфкПродюсеры | да | Ссылка на продюсер |
ИмяТопика | Строка | да | Имя топика |
Сообщение | Структура от ПараметрыСообщения() | да | Описание сообщения |
Партиция | Число | нет | Номер партиции; -1 (по умолчанию) — автоматический выбор |
Сессии | Соответствие | нет | При Неопределено подключение создаётся и закрывается на каждый вызов. При передаче Соответствие — переиспользуется для последующих вызовов (пакетный режим) |
Возврат. Структура {Успешно: Булево, ТекстОшибки: Строка} — общий результат операции.
Как работают Сессии
При первой передаче пустого Соответствие адаптер создаёт подключение и кладёт его в Сессии[Продюсер]. Последующие вызовы с тем же Сессии переиспользуют подключение — экономится время на установке соединения. По завершении пакета обязательно вызывайте ЗакрытьСессииПродюсера(Сессии).
Прочитать(Консьюмер, АвтоФиксацияСмещения, Сессии = Неопределено)¶
Синхронное чтение одного сообщения.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
Консьюмер | СправочникСсылка.кфкКонсьюмеры | да | Ссылка на консьюмер |
АвтоФиксацияСмещения | Булево | да | Истина — смещения фиксируются автоматически и периодически в фоновом режиме. Ложь — фиксация не производится (для ручного управления offset используются служебные средства) |
Сессии | Соответствие | нет | Аналогично Отправить |
Возврат. Структура {Успешно, ТекстОшибки, Сообщение}. Поле Сообщение может быть Неопределено, если в топике нет новых данных. Структура Сообщение содержит: Тело, Ключ, Заголовки, Топик, ВременнаяМетка, Раздел, Смещение.
ЗакрытьСессииПродюсера(Сессии) / ЗакрытьСессииКонсьюмера(Сессии)¶
Закрывают открытые сессии. Обязательны при пакетном режиме — в том числе в блоке исключения, иначе соединение зависнет и будет удерживать ресурсы на сервере 1С.
Гарантии и ограничения¶
- Прямой API не переживает перезапуски сервера 1С — нет очереди на диске.
- Нет автоматического повтора при сбое — вызывающий код сам решает, что делать при
Успешно = Ложь. - Нет параллельной обработки — её обеспечивает только очередь с диспетчерами.
- Сессии всегда закрываются вручную в пакетном режиме.
Когда стоит использовать¶
- Синхронная отправка команды во внешнюю систему с ожиданием ответа о доставке.
- Чтение одного сообщения (проверка работоспособности кластера, разовая диагностика).
- Периодические утилиты, которым не нужна инфраструктура очередей.
- Интеграционные тесты.
Когда не стоит¶
- Регулярный массовый обмен — используйте очередь.
- Сценарии, где важна устойчивость к сбоям.
- Когда нужна параллельная обработка.
Смотрите также¶
- Программный API — полный справочник
кфкИнтеграция. - Пример прямого API — готовый рецепт.