Перейти к основному содержимому

Часто задаваемые вопросы

Обновлено: 23 октября 2025

Какие требования предъявляются к среде разработки?​

Любая IDE для разработки на Java 21.

Нужна ли локальная установка инстанса шлюза?​

Для разработки плагинов локальная установка шлюза не требуется.

В чём особенности плагинов разных типов?​

Коннектор​

Получает сообщения и отправляет их в ядро шлюза:

  • принимает исходящие сообщения в нативном формате от внешней системы, преобразует их и регистрирует в ядре шлюза;
  • получает статусы с помощью callback (обратный вызов) или polling (регулярный опрос сервера);
  • обрабатывает входящие сообщения.

Канал​

Получает сообщения от ядра и отправляет их во внешнюю систему — оператору мобильной связи, сервису push-уведомлений, сервису instant messages и т. д.:

  • преобразует исходящие сообщения в необходимый формат и отправляет во внешнюю систему;
  • получает статусы доставки от внешней системы и регистрирует их в ядре шлюза;
  • обрабатывает входящие сообщения.

Перехватчик​

Анализирует или меняет отправляемое сообщение:

  • прослушивает, модифицирует и/или блокирует исходящие сообщения после их регистрации, но до маршрутизации;
  • прослушивает статусы исходящих сообщений.

Задачи​

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

Можно ли комбинировать плагины разных типов? Как настраивается их взаимодействие?​

Один JAR-файл может содержать несколько плагинов любых типов. Настройка выполняется в веб-интерфейсе edna Prisma в разделе Компоненты. Инстансы плагинов можно создавать, включать или выключать так же, как это делается для системных модулей.

File IconКак создать компонент

С какими объектами шлюза может работать плагин? Как организуется доступ к ним?​

Ресурсы, общие для всех типов модулей​

  • getPluginInstanceName — получение информации об инстансе плагина;
  • logger — настройка журналирования;
  • getConnection и getSqlUtil — работа с БД в выделенной для плагина схеме;
  • getPersistenceMap и getInMemoryMap — хранилища пар «ключ-значение»;
  • getPrincipalSource и requirePrincipalSource — проверка авторизации по источнику;
  • launch — запуск фонового потока;
  • getRestSender — утилитные методы отправки REST-запросов;
  • @RestEndpoint — регистрация конечной точки в REST API.

Ресурсы, специфичные для коннектора​

  • produceOutMessage — регистрация исходящих сообщений в ядре;
  • getOutMessageHistory — запрос истории сообщений;
  • getDeliveryStatus, getNotReceivedDivStatuses и confirmDivStatusesAsReceived — получение статусов сообщений;
  • getNotReceivedIncomingMessages и confirmIncomingMessagesAsReceived — работа с входящими сообщениями.

Ресурсы, специфичные для канала​

  • produceStatus — регистрация статуса исходящего сообщения в ядре;
  • produceInMessageToConnect и produceInMessagesToConnect — регистрация входящих сообщений в ядре.

Доступ осуществляется через методы базового класса плагина либо его окружения (getEnv).

подсказка

Некоторые возможности работы с объектами продемонстрированы в примере Gradle-проекта, который предоставляет edna.

Должны ли быть у плагина неизменные методы или переменные?​

Неизменным должно быть имя плагина — значения переменных namespace и name. При изменении кода плагина нужно не забывать изменять его версию.

Каковы функции метода DeliveryMethod при определении метаданных канала?​

DeliveryMethod указывает на тип внешней системы и используется для маршрутизации, а также отчётности. Например, с его помощью можно запретить определённый тип канала.

Предположим, требуется отправка push-уведомлений. Что нужно изменить в коде примера канала?​

В ядре есть готовые push-каналы. Если требуется создать свой канал, то в переопределённом методе send компонента канала следует прописать логику преобразования исходящего сообщения в формат облака push-сервиса, отправки по протоколу push-сервиса, а также взаимодействия с облаком для получения статусов доставки и регистрации их в шлюзе.

Каковы функции метода receiveInMessage в примере канала? Параметр cloudUrl метода send является обязательным?​

  • receiveInMessage регистрирует конечную точку в REST API для взаимодействия с внешней системой. В примере показано, как можно получать от внешней системы входящие сообщения и регистрировать их в ядре.
  • cloudUrl — это пример, как можно работать с параметрами плагина. Разработчик плагина может применять необходимую ему логику.

Что изменилось в API версии 5?​

  • Удалён метод OutgoingMessage::getMetadata. Чтобы получить атрибуты исходящего сообщения, используйте метод OutgoingMessage::getAttribute{Type}(Stringname). Также можно получить список всех имен атрибутов методом OutgoingMessage::getAttributeNames.
  • Метод getAttribute(Class) заменен внутри класса OutgoingMessage новыми методами для каналов SMS, PUSH, IM, EMAIL, что позволяет разделять атрибуты сообщений разных типов.
  • Класс исходящего сообщения включает два новых поля, которые используются при взаимодействии с REST-коннектором:
    • metadata — метаданные сообщения, которые можно получить с помощью OutgoingMessage::getAttribute{Type}(String name);
    • options — параметры push-сообщения (OutgoingMessage::push()::getOpts()).
Пример JSON для отправки сообщения в REST-коннектор
{
"text": "Test message",
"type": "messageType",
"address" : "79621111111",
"subject" : "subject",
"priority" : "NORMAL",
"metadata" : [
{
"attributeName1": "attributeValue1",
"attributeName2": "attributeValue2"
}
],
"option": [
{
"pushOptKey1": "pushOptValue1",
"pushOptKey2": "pushOptValue2"
}
]
}

Как настроить плагин канала для отправки сообщений во внешнюю систему по REST с получением статусов через колбэки?​

  1. Начните с настройки HTTP-сервера:

    • Добавьте аннотацию классу плагина вашего канала io.edna.plugins.user.api.rest.RestServer и укажите порт, на котором плагин будет прослушивать запросы и перенаправлять методы-обработчики с аннотацией @io.edna.plugins.user.api.rest.RestEndpoint.
    • Адрес конечной точки имеет следующий вид: <адрес сервера>:<номер порта>/<путь из RestEndpoint::path>.
    • Например, если адрес сервера https://example.com, указан порт 1234 и в канале объявлен метод, аннотированный @RestEndpoint(path = "test"), то глобальный адрес конечной точки: https://example.com:1234/test.
  2. Настройте отправку сообщений во внешнюю систему:

    • Создайте метод send(OutgoingMessage message), который будет преобразовывать сообщение (message) в формат внешней системы и отправлять его.
    • Для оповещения ядра о результатах отправки используйте методы produceStatusSent и produceStatusError.
  3. Для получения статусов доставки из внешней системы через колбэки создайте метод с аннотацией @RestEndpoint, который будет передавать параметр с информацией о статусе в формате внешней системы.

  4. Для регистрации статуса в ядре в теле этого метода вызовите один из методов:

    • produceStatusDelivered(long messageId)

    • produceStatusUndelivered(long messageId)

    • produceStatusError(long messageId)

      к сведению

      Здесь messageId — идентификатор сообщения, который использовался в методе отправки и может быть получен с помощью OutgoingMessage::getId().

      Значение messageId не должно изменяться внешней системой, чтобы вместе с информацией о статусе передаваться в конечную точку механизма колбэка.

      подсказка

      Пример плагина канала можно посмотреть в шаблоне проекта — класс io.edna.connect.example.plugins.channels.SampleChannelUserPlugin.