Перейти к содержанию

Программный API

Модуль кфкИнтеграция — основная точка входа для прикладного разработчика (серверный/клиент-серверный контекст). Модуль кфкИнтеграцияКлиент содержит клиентские процедуры открытия форм.

Публичный API

Из прикладного кода вызывайте только кфкИнтеграция и кфкИнтеграцияКлиент. Все модули с суффиксом Служебный, СлужебныйВызовСервера являются внутренним API — их сигнатуры и поведение могут меняться без предупреждения.

Сводная таблица

Метод Категория Назначение
Отключить Регистрация Отменить регистрацию объекта при записи
ПоместитьВОчередьИсходящих Регистрация Поставить объект/массив в очередь исходящих
КлючОбъекта Регистрация Получить уникальный ключ объекта для сообщений
КлючЗаписиИсходящихСообщений Регистрация Получить ключи записей очереди исходящих по данным
ЭтоРегистрацияПриЗаписи События Проверка источника регистрации — подписка на событие
ЭтоРегистрацияПрограммно События Проверка источника регистрации — API
ЭтоРегистрацияПринудительно События Проверка источника регистрации — UI «Регистрация изменений»
Отправить Прямой API Синхронная отправка сообщения в топик
Прочитать Прямой API Синхронное чтение сообщения из топика
ЗакрытьСессииПродюсера Прямой API Закрыть открытые сессии продюсера
ЗакрытьСессииКонсьюмера Прямой API Закрыть открытые сессии консьюмера
ПараметрыСообщения Конструктор Сформировать описание сообщения
РезультатИнтеграции Конструктор Сформировать пустой результат операции
ИсторияВыгрузкиОбъекта Клиент Открыть форму очереди с отбором по объекту

Регистрация к обмену

Отключить(Источник)

Помечает объект флагом, предотвращающим его регистрацию в очередь при записи.

Параметр Тип Описание
Источник СправочникОбъект, ДокументОбъект, ПланВидовХарактеристикОбъект, ПланВидовРасчетаОбъект, ПланСчетовОбъект, БизнесПроцессОбъект, ЗадачаОбъект, ПланОбменаОбъект, РегистрСведенийНаборЗаписей, РегистрНакопленияНаборЗаписей, РегистрБухгалтерииНаборЗаписей, РегистрРасчетаНаборЗаписей Объект или набор записей регистра, подлежащий исключению

Возврат. Нет.

Только до записи

Вызывайте Отключить() до записи объекта — в обработчике ПередЗаписью или непосредственно перед Записать(). После записи вызов не имеет эффекта.

кфкИнтеграция.Отключить(Источник);

Полный пример — Подавление регистрации.

ПоместитьВОчередьИсходящих(Источник, ТипОбъект, Продюсеры)

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

Параметр Тип Обяз. По умолч. Описание
Источник ЛюбаяСсылка, объект, набор записей регистра, Структура, Соответствие, результат ПараметрыСообщения(), Массив Из перечисленных да — Что регистрировать
ТипОбъект Строка нет "" Ключ регистрации (см. ниже)
Продюсеры СправочникСсылка.кфкПродюсеры или коллекция нет Неопределено Конкретный продюсер/массив — если нужно обойти стандартную маршрутизацию

Возврат. Нет.

Поведение.

  • При передаче массива — работает пакетный режим: сообщения разбиваются на порции, регистрация завершается порционно.
  • При передаче результата ПараметрыСообщения() — сериализация не выполняется, тело сообщения берётся как есть.
  • Если функциональная опция кфкИспользоватьИнтеграцию выключена — метод возвращается без действия.

Параметр ТипОбъект — ключ регистрации. Адаптер ищет продюсер, у которого значение в «Объектах метаданных» точно совпадает с этой строкой. Может быть полным именем метаданных (Справочник.Номенклатура) или произвольным ключом (crm.order-placed). Подробно — Тип объект — ключ регистрации.

// Одиночная ссылка
кфкИнтеграция.ПоместитьВОчередьИсходящих(СсылкаНаДокумент);

// Массив (пакетный режим)
кфкИнтеграция.ПоместитьВОчередьИсходящих(МассивСсылок);

// Произвольное сообщение
Сообщение = кфкИнтеграция.ПараметрыСообщения("{""event"":""ping""}", "msg-1");
кфкИнтеграция.ПоместитьВОчередьИсходящих(Сообщение, "system.events");

Примеры — Принудительная регистрация, Произвольные события.

КлючОбъекта(Данные)

Возвращает уникальный ключ объекта, используемый адаптером для идентификации в исходящих сообщениях.

Параметр Тип Описание
Данные ЛюбаяСсылка, СправочникОбъект, ДокументОбъект, РегистрСведенийКлючЗаписи, РегистрНакопленияКлючЗаписи Данные для идентификации

Возврат. Строка (ключ) или Неопределено.

КлючЗаписиИсходящихСообщений(Данные)

Возвращает массив ключей записей в регистре исходящих, относящихся к данным.

Параметр Тип Описание
Данные ЛюбаяСсылка, СправочникОбъект, ДокументОбъект, РегистрСведенийКлючЗаписи Данные для поиска

Возврат. Массив Из Строка или Неопределено.

События регистрации

Используются в обработчике продюсера, чтобы различать источник попадания сообщения в очередь.

ЭтоРегистрацияПриЗаписи(Свойства)

Возвращает Истина, если сообщение было зарегистрировано подпиской на событие записи объекта.

Параметр Тип Описание
Свойства Структура Свойства сообщения, Свойства.СобытиеРегистрации — ПеречислениеСсылка.кфкСобытияРегистрации

Возврат. Булево. Бросает исключение, если СобытиеРегистрации не указано.

ЭтоРегистрацияПрограммно(Свойства)

Возвращает Истина, если сообщение было зарегистрировано через API ПоместитьВОчередьИсходящих.

ЭтоРегистрацияПринудительно(Свойства)

Возвращает Истина, если сообщение было зарегистрировано вручную через UI «Регистрация изменений» или эквивалентный механизм.

Если кфкИнтеграция.ЭтоРегистрацияПриЗаписи(Свойства) Тогда
    // зарегистрировано подпиской
ИначеЕсли кфкИнтеграция.ЭтоРегистрацияПрограммно(Свойства) Тогда
    // зарегистрировано API
ИначеЕсли кфкИнтеграция.ЭтоРегистрацияПринудительно(Свойства) Тогда
    // зарегистрировано вручную через UI
КонецЕсли;

Прямой API (синхронная отправка/чтение)

Подробный раздел — Прямой API. Здесь — краткие сигнатуры.

Отправить(Продюсер, ИмяТопика, Сообщение, Партиция, Сессии)

Синхронная отправка сообщения в Kafka. Без участия очереди и фоновых заданий.

Параметр Тип Обяз. По умолч. Описание
Продюсер СправочникСсылка.кфкПродюсеры да — Ссылка на продюсер
ИмяТопика Строка да — Имя топика
Сообщение Структура от ПараметрыСообщения() да — Описание сообщения
Партиция Число нет -1 Номер партиции; -1 — автоматический выбор
Сессии Неопределено или Соответствие нет Неопределено Неопределено — создание нового подключения на вызов. Соответствие — переиспользование подключения (пакетная отправка). После передачи Соответствие обязателен вызов ЗакрытьСессииПродюсера()

Возврат. Структура {Успешно: Булево, ТекстОшибки: Строка}.

Поведение в асинхронном режиме: 1. При исключении: Успешно = Ложь, ТекстОшибки = текст ошибки. 2. При отсутствии подтверждения: Успешно = Ложь, ТекстОшибки = причина. 3. При подтверждённой доставке: Успешно = Истина.

Прочитать(Консьюмер, АвтоФиксацияСмещения, Сессии)

Синхронное чтение одного сообщения и запись его в РегистрСведений.кфкВходящиеСообщения.

Параметр Тип Обяз. По умолч. Описание
Консьюмер СправочникСсылка.кфкКонсьюмеры да — Ссылка на консьюмер
АвтоФиксацияСмещения Булево да — Истина — смещения фиксируются автоматически и периодически в фоне
Сессии Неопределено или Соответствие нет Неопределено Аналогично Отправить

Возврат. Структура {Успешно, ТекстОшибки, Сообщение}. Сообщение может быть Неопределено, если в топике нет данных.

Поля Сообщение:

Поле Тип Описание
Тело Строка, ДвоичныеДанные Данные сообщения
Ключ Строка Ключ (key)
Заголовки Массив Из Структура Массив пар {Ключ, Значение}
Топик Строка Имя топика
ВременнаяМетка Число Время записи сообщения в топик/раздел
Раздел Число Номер партиции
Смещение Число Текущее смещение (offset)

ЗакрытьСессииПродюсера(Сессии)

Закрывает ранее созданные сессии продюсера.

Параметр Тип Описание
Сессии Соответствие Коллекция, переданная в Отправить()

ЗакрытьСессииКонсьюмера(Сессии)

Закрывает ранее созданные сессии консьюмера. Аналогично предыдущему.

Конструкторы

ПараметрыСообщения(Данные, Ключ)

Формирует описание сообщения для последующей передачи в Отправить() или ПоместитьВОчередьИсходящих().

Параметр Тип По умолч. Описание
Данные Строка, ДвоичныеДанные, Структура, Массив Из Структура "" Тело сообщения
Ключ Строка "" Уникальный идентификатор сообщения

Возврат. Структура:

Поле Тип Описание
Данные см. выше Тело сообщения
Ключ Строка Идентификатор
Заголовки Соответствие Из КлючИЗначение Пустое соответствие для добавления заголовков 
Сообщение = кфкИнтеграция.ПараметрыСообщения(СтрокаJSON, "Order-123");
Сообщение.Заголовки.Вставить("source", "crm");

РезультатИнтеграции()

Формирует пустой результат операции. Используется вспомогательным кодом; прикладному разработчику обычно не нужен напрямую.

Возврат. Структура {Успешно: Ложь, ТекстОшибки: ""}.

Клиентские методы (кфкИнтеграцияКлиент)

ИсторияВыгрузкиОбъекта(Данные, Форма, Окно, РежимОткрытияОкна)

Открывает форму очереди исходящих сообщений с отбором по объекту. Удобно встраивать в формы объектов кнопкой «История выгрузки».

Параметр Тип Обяз. По умолч. Описание
Данные ЛюбаяСсылка, СправочникОбъект, ДокументОбъект, РегистрСведенийКлючЗаписи да — Данные для поиска записей
Форма ФормаКлиентскогоПриложения нет Неопределено Форма-владелец
Окно ОкноКлиентскогоПриложения нет Неопределено Окно приложения, в котором открыть форму
РежимОткрытияОкна РежимОткрытияОкнаФормы нет БлокироватьОкноВладельца Режим открытия

Возврат. Нет. Если по Данные не найдены записи в очереди — форма не открывается.

&НаКлиенте
Процедура ИсторияВыгрузки(Команда)
    кфкИнтеграцияКлиент.ИсторияВыгрузкиОбъекта(Объект.Ссылка, ЭтаФорма);
КонецПроцедуры

Смотрите также