Описание комплекта (SDK) для разработки плагина к сервису сообщений (MessageBroker)

Используйте комплект (SDK) для разработки .NET-приложения плагина, с помощью которого будут передаваться данные между сервисом и провайдером сообщений.

Для разработки плагина используйте пример из комплекта поставки. На основе примера:

[Настройте проект плагина](##Настройка проекта плагина).
[Разработайте посредник](##Разработка посредника) для передачи информации между провайдером и сервисом сообщений.
Разработайте:
- [настройки плагина](###Настройки плагина);
- модели для посредника;
- валидацию для базовых и дополнительных настроек посредника.
Создайте для плагина загрузчик TransportPluginBootstrapper и сервис-посредник TransportPlugin.

После завершения разработки [подключите плагин к сервису сообщений](##Подключение плагина к MessageBroker).

ВАЖНО. В примере используется название посредника ExampleTransport. При разработке замените его на свое название, например, название компании или провайдера сообщений. Замену нужно выполнить во всем проекте, в том числе в названии посредника, в настройках из файла appsettings.json, в docker-compose и т.д. Пример названия: ContosoTransport.

В качестве целевой платформы (TargetFramework) рекомендуется использовать .NET Standard 2.1. Если используется другая платформа, рекомендуется собирать Nuget-пакет с опцией self-contained.

Термины и определения

Сервис сообщений - набор из сервиса и планировщика заданий. Отвечает за планирование, маршрутизацию и отправку сообщений.
Провайдер - внешний сервис, который принимает от сервиса сообщений запросы на отправку сообщений и отправляет их на устройства пользователей.
Плагин - проект, реализующий адаптацию и отправку сообщений в провайдер. Представляет собой Nuget-пакет. готовый к установке в приложение сервиса сообщений.
Посредник - основная часть плагина, класс TransportProxy, в котором реализуется ключевой метод для отправки сообщения провайдеру.

Комплект поставки

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

ExampleTransportProxy - посредник;
Models - модели для посредника;
Configuration - настройки посредника;
ConfigurationValidator - механизм валидации настроек;
Plugin - плагин и загрузчик.

Настройка проекта плагина

Для корректной работы плагина убедитесь, что в файле проекта с расширением *.csproj заданы:

описание пакета;
копирование в пакет документации, символов отладки и dll-зависимостей;
внешние библиотеки. Укажите в нем зависимость от Nuget-пакета Core.MessageBroker.Transport.<Номер версии>.nupkg, который входит в комплект поставки сервиса сообщений: <PackageReference Include="Core.MessageBroker.Transport" Version="*" />
основные настройки:
- AssemblyName и RootNamespace - укажите название посредника;
- CopyLocalLockFileAssemblies, GenerateDocumentationFile, GeneratePackageOnBuild - укажите значение true.

Пример основных настроек:

<TargetFramework>netstandard2.1</TargetFramework>
<AssemblyName>ContosoTransport</AssemblyName>
<RootNamespace>ContosoTransport</RootNamespace>
<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
<TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);IncludeInPackage</TargetsForTfmSpecificContentInPackage>

Разработка посредника

При разработке посредника учитывайте модели для передачи параметров сообщения:

из сервиса сообщений в плагин;
из плагина в сервис сообщений.

Для передачи из сервиса сообщений в плагин используется модель [Message](###Message - сообщение), а для передачи ответа от плагина в сервис сообщений - модель [TransmitResult](###TransmitResult - результат отправки сообщения). Реализуйте преобразование данных между используемыми моделями.
Также ознакомьтесь с [кодами ошибок](###TransmitResult - результат отправки сообщения), которые поддерживаются для плагинов.

Message - сообщение

Модель используется для передачи сообщения из сервиса сообщений в плагин.

string Id - идентификатор сообщения;
string Title - заголовок сообщения;
string Content - содержимое сообщения;
MessagePriority Priority - приоритет сообщения:
- enum MessagePriority:
  - Low = -1 - низкий приоритет;
  - Normal = 0 - нормальный приоритет;
  - High = 1 - высокий приоритет.
MessageDeliveryMethod DeliveryMethod - метод доставки:
- enum MessageDeliveryMethod:
  - Push = 0 - push-метод. Сервис сообщений отправляет сообщения внешним адресатам, например провайдерам SMS;
  - Pull = 1 - pull-метод. Внешние адресаты самостоятельно забирают сообщения у сервиса.
string DeliveryProxy - канал доставки. Возможные значения: Sms, Smtp, Viber. Для отправки push-уведомлений должна быть реализована отправка по Sms. Подробнее см. в руководстве по установке платформы личного кабинета;
DateTimeOffset BestBefore - срок, в течение которого выполняются повторные попытки отправить сообщение, если при первоначальной отправке произошла ошибка. Например, это может случиться, если в работе планировщика заданий возник сбой. После истечения срока для сообщения устанавливается соответствующий признак, и оно не отправляется;
Dictionary<string, string> Properties - свойства сообщения в виде пары «ключ-значение». Используется в push-уведомлениях, также может использоваться для передачи специфических параметров сообщения;
MessageIdentity Identity - получатель сообщения:
- class MessageIdentity:
  - string CredentialType - тип реквизита удостоверения получателя. В стандартной реализации заполняется значениями ClaimTypes HTTP://SCHEMAS.XMLSOAP.ORG/WS/2005/05/IDENTITY/CLAIMS/MOBILEPHONE и HTTP://SCHEMAS.XMLSOAP.ORG/WS/2005/05/IDENTITY/CLAIMS/EMAILADDRESS из пространства System.Security.Claims. В собственной реализации можно использовать другие значения;
  - string CredentialValue - значение реквизита удостоверения получателя.
List<MessageAction> Actions - действия:
- class MessageAction:
  - string Name - наименование действия;
  - string Title - заголовок действия;
  - Dictionary<string, string> Parameters - параметры действия в виде пар «ключ-значение»:
    - ключом словаря является название параметра действия;
    - значением словаря является значение параметра действия.
List<MessageAttachment> Attachments - вложения:
- class MessageAttachment:
  - string Title - заголовок вложения;
  - string Url - ссылка на вложение.
List<string> Tags - тэги сообщения;

TransmitResult - результат отправки сообщения

Модель используется для передачи результата отправки сообщения из плагина в сервис сообщений.

bool IsSuccess - true, если сообщение было успешно отправлено;
Error Error - ошибка, возникшая во время отправки сообщения:
- class Error:
  - string Message - описание ошибки;
  - string Code - код ошибки. Для указания значения следует пользоваться перечислением enum ErrorCode. Значения перечислены ниже;
  - string StackTrace - стек-трейс системного исключения;
  - string[] UnregisteredTokens - список незарегистрированных токенов. Используется при отправке push-уведомлений.

Значения ErrorCode, при которых попыток отправить конкретное сообщение больше не будет:

IncorrectMessageDataError - некорректные данные в сообщении. Примеры сообщений об ошибке:
- "Сообщение не содержит информацию о номере телефона";
- "Не задан ни заголовок, ни содержимое сообщения";
- "Ошибка в реквизитах сообщения {pluginType} {responseBody}".
IncorrectPhoneNumberError - некорректный номер телефона, применяется при нормализации и валидации. Примеры сообщений об ошибке:
- "Номер телефона должен быть либо валидным международным номером, либо начинаться с '7', '8' и содержать 11 цифр".
InvalidCredentialTypeError - указан неверный типа реквизита получателя. Примеры сообщений об ошибке:
- "Тип реквизита получателя '{credentialType}' в сообщении {messageId} является некорректным для плагина {pluginType}".
MessageDeliveryError - ошибке доставки сообщения, без указания конкретики. Примеры сообщений об ошибке:
- "Не удалось отправить сообщение т.к. пришел неожиданный ответ {pluginType} {responseBody}";
- "Ошибка во время доставки сообщения {pluginType} {responseBody}".
MessageTransmitBlockedError - ошибка при блокировке номера со стороны провайдера. Примеры сообщений об ошибке:
- "Ошибка ожидания транспорта {pluginType} {responseText}. Транспорт будет временно заблокирован на {timeout} т.к. было слишком много ошибочных запросов";
- "Не удалось отправить сообщение {messageId}. Сообщение запрещено (по тексту или по имени отправителя)".
TransmitRetryExceededError - ошибка при слишком большом количестве попыток отправки. Не используется напрямую в плагинах. Работает в паре с настройкой MaxTransmitRetryCount. Примеры сообщений об ошибке:
- "Слишком много попыток отправить сообщение {messageId} посредством канала доставки '{deliveryProxyName}'".
TransportAuthorizeError - ошибках авторизации на стороне провайдера. Примеры сообщений об ошибке:
- "Ошибка авторизации транспорта {pluginType} {responseBody}".
SystemError - системная или неизвестная ошибка.

Значения ErrorCode, при которых попытка отправить конкретное сообщение выполняется промежуток времени, указанный в параметре плагина ProcessDelayMs в мс:

MessagePendingError - временная приостановка отправки корректного сообщения. Примеры сообщений об ошибке:
- "Ошибка ожидания транспорта {pluginType}. Сообщение {messageId} уже было отправлено ранее, повторная отправка возможно не ранее чем через {timeout}".
PriorityLimitError - достигнут лимит сообщений по приоритету. Примеры сообщений об ошибке:
- "Ошибка из-за достижения лимита сообщений {messagePriority} приоритета".
MessageTransmitError - неудачная попытка отправки сообщения. Примеры сообщений об ошибке:
- "Не удалось отправить сообщение {pluginType} {responseBody}".
TransportPendingError - ошибка ожидания ответа от провайдера. Действует сразу на все сообщения, отправляемые через указанный плагин. Примеры сообщений об ошибке:
- "Ошибка ожидания транспорта";
- "Ошибка из-за достижения лимита сообщений".

Значения ErrorCode для push-уведомлений:

PushDeliveryError - ошибка при отправке push-уведомления. Примеры сообщений об ошибке:
- "Ошибка при отправке Push уведомления. Ответ от сервера {statusCode}" - push-уведомление не отправлено. Сообщение будет отправлено через Sms;
- "Ошибка при отправке Push уведомления. Не удалось отправить Push уведомление" - push-уведомление не отправлено. Сообщение будет отправлено через Sms;
- "Ошибка при отправке Push уведомления. Обнаружены незарегистрированные токены" - переданные токены помечаются как удаленные. Само это сообщение в логах не означает, что push-уведомление не отправлено.

Любые системные исключения следует обернуть в результат TransmitResult с указанием стек-трейса Error.StackTrace и кода ошибки Code = SystemError, как это реализовано в примере плагина.

Настройки плагина

Настройки задаются в секции Transport, дочерней секции Proxies. Она может содержать любое разумное количество настроек, необходимых для реализации функциональности плагина. Для удобства разработки в класс ConfigurationBase выделены наиболее обобщенные параметры:

Host - имя хоста для подключения к провайдеру;
Port - номер порта для подключения к провайдеру;
Path - путь для подключения к провайдеру. Пример: /v1/messages;
UseSsl - признак необходимости использования SSL-сертификата. Чтобы сервис сообщений взаимодействовал с провайдером по защищенному каналу, необходимо указать true;
Username - имя пользователя для авторизации запросов к провайдеру;
Password - пароль пользователя для авторизации запросов к провайдеру;
MessagesPerSecond - количество сообщений в секунду, которые позволяет обрабатывать сервис. Используется при массовой отправке сообщений. Если указано значение 0, количество сообщений не ограничено;
MaxTransmitRetryCount - количество попыток отправить сообщение. Если указано значение null, то количество повторных попыток неограниченно.

Пример настройки для ОС на базе Linux:

      Transport__Proxies__ContosoTransportPlugin__Host: "notify.contoso.com"
      Transport__Proxies__ContosoTransportPlugin__Port: "443"
      Transport__Proxies__ContosoTransportPlugin__Path: "/v1/messages"
      Transport__Proxies__ContosoTransportPlugin__UseSsl: true
      Transport__Proxies__ContosoTransportPlugin__Username: "Admin"
      Transport__Proxies__ContosoTransportPlugin__Password: "11111"
      Transport__Proxies__ContosoTransportPlugin__MessagesPerSecond: 0
      Transport__Proxies__ContosoTransportPlugin__MaxTransmitRetryCount: 2

В примере ExampleTransport используются все указанные настройки, а также дополнительная настройка Sender - имя отправителя.

Подключение плагина к MessageBroker

Перед подключением плагина соберите проект в Nuget-пакет. Порядок подключения отличается в зависимости от используемой ОС. Если вы используете установщик DirectumLauncher, то обратитесь к соответствующей инструкции из комплекта поставки компонента установки DLC MessageBroker.

Windows

Скопируйте Nuget-пакет проекта в папку с плагинами сервиса сообщений. Папка указана в конфигурационном файле сервиса сообщений в параметре PluginsPath. Путь до конфигурационного файла: C:\inetpub\wwwroot\CoreMessageBroker\WebApiService\appsettings.json.
Укажите название плагина в конфигурационном файле сервиса сообщений в параметре <Канал доставки>DeliveryProxy. Возможные каналы доставки: Sms, Viber, Smtp, Push.
Задайте разработанные ранее настройки посредника.

Пример настройки для SmsDeliveryProxy:

  "Transport": {
    ...
    "SmsDeliveryProxy": "ExampleTransportPlugin",
    "ExampleTransportPlugin": {
      "Setting1": "",
      "Setting2": "",
      "Setting3": "",
      ...
    },
    ...
  }

Linux

Добавьте собранный Nuget-пакет с плагином в образ:
- cмонтируйте папку, в которой находится плагин;
- переопределите entrypoint для копирования плагинов из volume в основную директорию.
Укажите название плагина транспортного посредника в настройке Transport__<Канал доставки>DeliveryProxy. Возможные каналы доставки: Sms, Viber, Smtp, Push.

Пример настройки для SmsDeliveryProxy:

services:
  message-broker:
    image: registry.directum.ru/hrpro/directum.message.broker:*.*.*.*
    entrypoint: "sh -c 'cp /Plugins/*nupkg /app/Plugins && dotnet Core.MessageBroker.WebApiService.dll'"
    environment:
      ...
      Transport__SmsDeliveryProxy: "ExampleTransportPlugin"

      Transport__Proxies__ExampleTransportPlugin__Setting1: ""
      Transport__Proxies__ExampleTransportPlugin__Setting2: ""
      Transport__Proxies__ExampleTransportPlugin__Setting3: ""
      ...
    volumes:
      - ./Plugins:/Plugins
    ports:
      - "*:*"

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
src		src
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
StyleCop.ruleset		StyleCop.ruleset

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Описание комплекта (SDK) для разработки плагина к сервису сообщений (MessageBroker)

Термины и определения

Комплект поставки

Настройка проекта плагина

Разработка посредника

Message - сообщение

TransmitResult - результат отправки сообщения

Настройки плагина

Подключение плагина к MessageBroker

Windows

Linux

About

Uh oh!

Releases

Packages

Uh oh!

Languages

DirectumCompany/Core.MessageBroker.SDK

Folders and files

Latest commit

History

Repository files navigation

Описание комплекта (SDK) для разработки плагина к сервису сообщений (MessageBroker)

Термины и определения

Комплект поставки

Настройка проекта плагина

Разработка посредника

Message - сообщение

TransmitResult - результат отправки сообщения

Настройки плагина

Подключение плагина к MessageBroker

Windows

Linux

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages