Отправление сообщений сервису осуществляется по протоколу HTTP (поддерживается защищенное HTTPS соединение). Клиент для получения сообщений устанавливает постоянное TCP соединение с сервисом при помощи внешней компоненты 1С, выполненной по технологии Native API. Сообщения, передаваемые от сервиса клиенту, шифруются по алгоритму AES.
Несмотря на то, что основное предназначение сервиса - передача сообщений от сервера 1С клиентским сеансам, использование для отправления сообщений протокола HTTP позволяет отправлять сообщения в 1С из сторонних систем (например, сайт может уведомить менеджера о новом заказе, не дожидаясь загрузки этого заказа непосредственно в 1С).
Поддерживается работа в операционных системах семейства Windows и Linux.
Ознакомившись с описанием сервиса, может возникнуть логичный вопрос: «Зачем изобретать свой велосипед, если уже есть «1С:Сервер взаимодействия», который, к тому же имеет гораздо больше возможностей?». Действительно, если вам нужны полноценные обсуждения, видеозвонки и прочие «плюшки», то «1С:Сервер взаимодействия» подойдёт лучше всего. Но, если вам всего этого не требуется, но есть необходимость реализовать простое взаимодействие сервера 1С с клиентским сеансом (например, отправлять те же уведомления о новых заказах), то «1С:Сервер взаимодействия» в таком случае обладает для вас избыточным функционалом.
Так же стоит отметить, что «1С:Сервер взаимодействия» бесплатно, на момент написания статьи, предоставляется только сервисом «1С:Диалог». Вопрос «останется ли он бесплатным в будущем» остаётся открытым. Передаваемые сообщения пересылаются через Интернет, что делает необходимым иметь постоянный доступ к сети (впрочем, в наше время это совсем не проблема). Если вы не являетесь пользователем уровня КОРП, то за возможность развернуть «1С:Сервер взаимодействия» в локальной сети придётся заплатить 50 400 руб. Да и сама локальная установка и настройка сервера взаимодействия требует определённых навыков. На эту тему уже написано множество статей и снято не одно видео.
Представленный же сервис push-уведомлений для 1С (далее, PNS4OneS) абсолютно бесплатен, устанавливается парой нажатий кнопки «Далее» и прост в настройке. Справедливости ради, следует отметить, что установка под Linux чуть сложнее и требует использования командной строки, но это относительно Windows, сама же по себе установка под Linux так же довольно проста. Более того PNS4OneS является OpenSource-проектом, исходный код полностью открыт и доступен на github. Вы можете свободно изучать его, дорабатывать под свои нужды, если это потребуется и использовать в своих целях в соответствии с лицензией Apache 2.0.
Использование сервиса позволяет отказать от сценария, когда клиентский сеанс периодически вынужден сам опрашивать сервер 1С с использованием обработчика ожидания на предмет проверки наступления какого-либо события. В данном случае, при наступлении отслеживаемого события информацию о нём клиент получит практически мгновенно, при этом не будут тратиться ресурсы системы на постоянный опрос сервера.
Отдельно хочется обратить внимание, что сервис push-уведомлений разрабатывался как «pet-проект» больше для своего удовольствия и использовался в личных нуждах. После чего я решил поделиться им с сообществом, возможно, кому-то ещё, кроме меня, он покажется интересным.
Содержание.
Принцип работы сервиса push-уведомлений для 1С
Установка сервиса push-уведомлений для 1С
Настройка сервиса push-уведомлений
Администрирование сервиса push-уведомлений
Настройка 1С для использования сервиса push-уведомлений
Отправление уведомлений от сервера 1С клиентским сеансам
Обработка полученных сообщений
Отправление уведомлений клиентским сеансам 1С из сторонних систем
Демонстрационные обработки, входящие в состав расширения 1С
Условия использования сервиса push-уведомлений для 1С
Принцип работы сервиса push-уведомлений для 1С
Сервис, по своей сути, состоит их трёх компонент.
Первой компонентой является, собственно, сам сервис – приложение для x64 платформ Windows и Linux, которое принимает сообщения и пересылает их клиентам.
Для приёма сообщений используется HTTP-протокол, что позволяет передавать сообщения не только от 1С, но и из любой другой системы, поддерживающей данный протокол. Например, как уже упоминалось выше, это может быть web-приложение интернет-магазина или даже мобильное приложение, написанное на любом из доступных языков программирования. Хотя, изначальное предназначение сервиса – это передача оповещений от сервера 1С клиентским сеансам, ни что не мешает использовать его в описанных выше сценариях.
Для возможности передачи полученных сообщений клиентский сеанс 1С устанавливает постоянное TCP соединение с сервисом. Таким образом сообщение, отправленное сервером, практически сразу будет получено клиентским сеансом 1С. В локальной сети передача сообщений занимает доли секунды, что для пользователя выглядит, как мгновенная доставка.
Второй компонентой является расширение 1С, в котором реализованы методы по отправке сообщений от сервера и обработке полученных сообщений клиентом. «Из коробки» (без написания дополнительного кода) полученные сообщения просто отображаются в виде всплывающего уведомления с использованием процедуры 1С ПоказатьОповещениеПользователя. При необходимости, возможна реализация самостоятельной обработки полученных сообщений кодом 1С для реализации собственных сценариев.
И, наконец, третья компонента - внешняя компонента 1С, реализованная по технологии Native API. Данная компонента входит в состав расширения и используется для установки постоянного TCP соединения с сервисом.
В общем случае работа с сервисом выглядит следующим образом:
- Программист 1С реализует отправление требуемых сообщений сервису push-уведомлений. Например, если необходимо оповещать пользователей о новых назначенных ему задачах, то программисту потребуется добавить всего несколько строк кода для отправления сообщения в соответствующем месте (например, в обработчике события ПриЗаписи). Сообщение может быть отправлено как конкретному пользователю, так группе пользователей и даже сразу всем пользователям.
- При запуске пользователем сеанса 1С с помощью внешней компоненты устанавливается постоянное сетевое соединение с сервисом и выполняется ожидание входящих сообщений.
- Когда сервис push-уведомлений получает сообщение, он определяет получателя сообщения и, если с получателем установлено соединение, пересылает ему полученное сообщение. Следует отметить, что сообщения не сохраняются и передаются «онлайн». Т. е., если с пользователем, которому предназначено сообщение, в данный момент не установлено соединение, то сообщение будет проигнорировано.
- Сообщение принимается внешней компонентой 1С по протоколу TCP и передаётся в 1С через механизм внешних событий.
- В расширении 1С реализован обработчик ОбработкаВнешнегоСобытия. Если программист 1С не реализовал собственную обработку полученных сообщений, то для отображения уведомления вызывается стандартная процедура 1С ПоказатьОповещениеПользователя.
Установка сервиса push-уведомлений для 1С
Установка сервиса для операционной системы Windows
Поскольку сервис push-уведомления реализован на платформе .NET Core версии 6, то поддерживаются следующие операционные системы семейства Windows: пользовательские ОС начиная с Windows 8.1 и выше, серверные ОС начиная с Windows Server 2012 и выше.
Для более ранних ОС необходимо дополнительно установить распространяемый компонент Microsoft Visual C++ 2015–2019.
Установка выполняется из установочного пакета pns4ones-win-x64-1.0.0.exe и не требует каких-то специфических действий. Практически, весь процесс выполняется нажатием кнопки «Далее», поэтому детальное его описание не имеет смысла. Единственное, что следует отметить, рекомендуется устанавливать сервис как службу Windows (данная настройка аналогична настройке установщика платформы 1С и не должна вызывать трудностей).
Установка сервиса для операционной системы Linux
Платформа .NET Core версии 6 поддерживается практически во всех современных дистрибутивах ОС Linux. Подробную информацию о поддерживаемых дистрибутивах и их версий можно найти по адресу https://docs.microsoft.com/ru-ru/dotnet/core/install/linux.
Дистрибутив для Linux распространяется в виде архива и требует использования командной строки.
Архив с дистрибутивом необходимо распаковать в папку, в которой будет установлен сервис, выполнив следующую команду:
sudo tar xvzf pns4ones-1.0.0.tar.gz -C /opt/
Для завершения установки выполните команду:
sudo /opt/pns4ones/install.sh
При выполнении данной команды будут выполнены следующие действия:
- Создан пользователь pns4ones и каталог /etc/pns4ones, в котором будут храниться настройки сервиса. Доступ к данному каталогу будет установлен только для пользователей pns4ones и root, что предотвращает несанкционированный доступ к настройкам обычным пользователям.
- Создан и запущен linux сервис pns4ones.
Для управления сервисом используется утилита systemctl:
sudo systemctl start pns4ones – запуск сервиса push-уведомлений.
sudo systemctl stop pns4ones – остановка сервиса push-уведомлений.
sudo systemctl restart pns4ones – перезапуск сервиса push-уведомлений.
Настройка сервиса push-уведомлений
PNS4OneS использует три сетевых порта: порт для приёма сообщений от сервера 1С, порт для подключения клиентов 1С, порт веб-панели администрирования.
В целях безопасности веб-панель администрирования доступна только по сетевому интерфейсу localhost (127.0.0.1) на порту 36697: http://localhost:36697 Т. о. получить доступ к веб-панели администратора можно только с того компьютера, на котором установлен сам сервис. С любого другого компьютера локальной сети доступ к данной панели получить невозможно.
Параметры приёма и передачи сообщений могут настраиваться. Настройки указываются в INI файле pns4ones.ini.
В ОС семейства Windows настройки хранятся в %AppUserData%/Local/PNS4OneS. Так, например, если сервис установлен, как служба Windows и запускает от имени стандартного пользователя PNS4OneS, то полный путь к файлу настроек будет выглядеть следующим образом:
C:\Users\PNS4OneS\AppData\Local\PNS4OneS\pns4ones.ini
В ОС семейства Linux файл с настройками хранится по пути:
/etc/pns4ones/pns4ones.ini
Настройка приёма сообщений
По умолчанию, сообщения принимаются со всех сетевых интерфейсов на порту 36696. Т. е., если на сервере установлено несколько сетевых адаптеров, то сообщения будут приниматься с любого из них. Для изменения порта и/или ограничения прослушиваемых сетевых интерфейсов служит параметр listen (например, есть два сетевых адаптера: один в локальной сети, другой «смотрит» в Интернет, и необходимо запретить принимать сообщения из сети Интернет).
Примеры указания параметра:
listen=*:8092 – прослушивание всех сетевых интерфейсов на порту 8092.
listen=192.168.10.3:9062 – прослушивание только сетевого интерфейса 192.168.10.3 на порту 9062.
listen=localhost – прослушивание только сетевого интерфейса localhost на стандартном порту 36696. Такая настройка может использоваться для повышения безопасности, если сервис установлен на том же физическом сервере, где и сервер 1С и передача сообщений от сторонних систем не выполняется. Т. о. никто, кроме сервера 1С не сможет передавать сообщения, включая другие компьютеры локальной сети.
Настройка безопасного отправления сообщений
Сервис принимает уведомления по протоколу HTTP. Как известно, это простой текстовый протокол, в котором данные передаются в открытом виде.
Если отправление сообщений выполняется только сервером 1С и сервис push-уведомлений расположен в той же доверенной локальной сети (например, сеть предприятия, закрытая от сторонних пользователей), то дополнительных настроек по обеспечению передачи сообщений можно не выполнять.
Однако, если предполагается передача уведомлений из сторонних систем, расположенных в сети Интернет (например, из веб-приложения интернет-магазина) или к локальной сети нет доверии (например, к сети могут подключаться сторонние пользователи), то для повышения безопасности настоятельно рекомендуется настроить шифрование по протоколу HTTPS. Для этого необходимо выпустить соответствующий сертификат. Возможно использовать самоподписанный сертификат.
Примечание. Если передача сообщений из сторонних систем не используется, то максимально повысить безопасность отправления сообщений можно и без использования защищенного HTTPS соединения. Для этого необходимо установить сервис push-уведомлений на том же физическом сервере, на котором установлен сервер 1С и в настройках сервиса установить параметр listen=localhost (см. раздел «Настройка приёма сообщений» выше). В результате чего, несмотря на то, что сообщения будут передаваться от сервера 1С сервису push-уведомлений в открытом виде, перехватить их будет невозможно, т.к. передача происходит в рамках физического сервера без отправления данных в локальную сеть. Таким образом будет достигнута требуемая безопасность.
Сервис предусматривает два варианта работы по протоколу HTTPS.
1. Использование стороннего веб-сервера (IIS, Nginx, Apache) в качестве обратного прокси сервера (reverse proxy)
В таком варианте дополнительной настройки сервиса не требуется. Он продолжает работать в локальной сети по простому HTTP-протоколу. Настройка выполняется на веб-сервере: добавляется сертификат для шифрования трафика и выполняется настройка в качестве обратного прокси. Т. о. трафик из сети Интернет поступает по защищенному протоколу HTTPS на веб-сервер, а он уже перенаправляет запрос к сервису push-уведомлений внутри локальной сети.
С настройкой Nginx в среде Linux можно ознакомится по этой ссылке: https://docs.microsoft.com/ru-ru/aspnet/core/host-and-deploy/linux-nginx?view=aspnetcore-6.0.
С настройкой Apache в среде Linux можно ознакомится по этой ссылке: https://docs.microsoft.com/ru-ru/aspnet/core/host-and-deploy/linux-apache?view=aspnetcore-6.0.
2. Настройка использования защищенного протокола HTTPS самим сервисом push-уведомлений
Для такой настройки используются параметры ssl_mode, ssl_certificate, ssl_certificate_key и ssl_certificate_password.
ssl_mode – задаёт режим использования HTTPS протокола и может принимать следующие значения:
- None – защищенное HTTPS соединение не используется (значение по умолчанию).
- FromStorage – используется сертификат из стандартного хранилища сертификатов ОС.
- FromFileWithPrivateKey – используется сертификат, хранящийся в PEM-файле на диске. Приватный ключ располагается в отдельном PEM-файле.
- FromFileWithPassword – используется сертификат, хранящийся в PFX-файле на диске вместе с приватным ключом, защищенный паролем.
ssl_certificate - если параметр ssl_mode=FromStorage, то указывается имя сертификата в хранилище, иначе указывается путь к файлу, в котором хранится сертификат.
ssl_certificate_key - указывает путь к файлу приватного ключа сертификата. Обязателен, если параметр ssl_mode=FromFileWithPrivateKey, в противном случае игнорируется.
ssl_certificate_password - указывает пароль приватного ключа сертификата. Обязателен, если параметр ssl_mode=FromFileWithPassword, в противном случае игнорируется.
Настройка передачи уведомлений клиентам 1С
Сообщения, полученные сервисом push-уведомлений, передаются подключенным клиентам 1С по внутреннему протоколу через TCP соединение. Т. к. клиент может находиться удалённо вне локальной сети (например, сотрудник работает из дома или находится в командировке), то для повышения безопасности передаваемые сообщения шифруются по алгоритму AES.
По умолчанию клиенты подключаются по порту 36695 с любых сетевых интерфейсов. Для изменения этой настройки используется параметр service. Значение данного параметра устанавливается аналогично параметру listen, описанного в разделе «Настройка приёма сообщений».
Примеры указания параметра:
service=*:8093 – разрешение подключения клиентов с любых сетевых интерфейсов на порту 8093.
service=192.168.10.0 – разрешение подключения клиентов только в локальной сети 192.168.10.ХХХ на стандартном порту 36695.
Настройка уровня логирования
Для настройки уровня логирования используется параметр log_level. Данный параметр может принимать следующие значения:
- Information – в лог выводятся все сообщения, включая информационные.
- Warning – в лог выводятся только предупреждающие сообщения, а так же сообщения об ошибках (значение по умолчанию).
- Error – в лог выводятся только сообщения об ошибках.
- Critical – в лог выводятся только сообщения о критических ошибках.
- None – логирование сообщений не выполняется.
Пример файла настроек
Ниже приведен пример файла настроек.
listen=localhost
service=192.168.10.0:8270
ssl_mode=FromFileWithPrivateKey
ssl_certificate=/etc/pns4ones/cert/pns4ones.crt
ssl_certificate_key=/etc/pns4ones/cert/pns4ones.key
ssl_certificate_password=password
log_level=Error
Указание параметров сервиса через командную строку
Помимо INI файла, описанные выше параметры можно передавать через командную строку при запуске сервиса. Параметры, указанные в командной строке, имеют более высокий приоритет.
Перед именем параметра указывается прямая косая черта или дефис. Значение параметра указывается через пробел или знак «равно».
Примеры передачи параметров через командную строку.
C:\Program Files\PNS4OneS\PNS4OneS /ssl_mode FromStorage /ssl_certificate MyCompanyName
C:\Program Files\PNS4OneS\PNS4OneS -listen=localhost -log_level=Information
Описание параметров и их значений можно получить, вызвав исполняемый файл PNS4OneS с параметром -h.
Администрирование сервиса push-уведомлений
Для возможности пересылать сообщения через сервис используется понятие «Приложение сервиса». Необходимо подключить как минимум одно приложение. Каждое приложение содержит идентификатор и секретные ключи клиента и сервера.
Разделение на отдельные приложения позволяет повысить безопасность. Например, для интернет-магазина можно создать отдельное приложение, т. к. ключи будут использоваться сторонней системой. В случае компрометации ключей можно обновить ключи только для этого приложения не затрагивая передачу сообщений от сервера 1С. Или вообще удалить приложение, в результате чего сторонняя система не сможет передавать сообщения и это никак не затронет передачу других сообщений.
Использование веб-панели администратора
Администрировать сервис можно через веб-панель администратора, которая доступна по адресу http://localhost:36697
При первом входе необходимо указать логин и пароль для создания пользователя, которому будет доступно администрирование сервиса.
Для создания приложения используется кнопка «Создать приложение». После чего необходимо задать имя нового приложения.
Данные созданного приложения можно развернуть для получения значений секретных ключей сервера и клиента. Ключ сервера используется для отправления сообщений сервером 1С или сторонней системой. Ключ клиента используется клиентскими сеансами 1С для получения сообщений.
Рядом с ключами находятся кнопки, позволяющие скопировать значение в буфер обмена или обновить его в случае компрометации.
Администрирование сервиса через командную строку
Управлять приложениями сервиса можно также и через командную строку. Если сервис установлен на ОС без графического интерфейса, то это единственный способ администрирования, т. к. веб-интерфейс доступен только на сетевом интерфейсе localhost и недоступен по локальной сети для других компьютеров.
Для администрирования используется утилита PNS4OneSAdmin. Если запустить данную утилиту без параметров, то будет выведена справка об использовании утилиты.
В общем случае утилита используется следующим образом:
PNS4OneSAdmin <Команда> [<Параметры команды>]
Список доступных команд:
list – выводит список подключенных приложений, которые могут выполнять отправление уведомлений. Параметры отсутствуют.
create – создает новое приложение для отправления уведомлений. В качестве параметра указывается название создаваемого приложения.
upd_srv_key – обновляет ключ сервера для указанного приложения. В качестве параметра указывается идентификатор приложения, для которого необходимо обновить ключ сервера.
upd_cli_key – обновляет ключ клиента для указанного приложения. В качестве параметра указывается идентификатор приложения, для которого необходимо обновить ключ клиента.
remove – удаляет приложение, выполняющего отравление уведомлений. В качестве параметра указывается идентификатор приложения, которое необходимо удалить.
reset_token – сбрасывает ключ доступа к серверу для приложения. В качестве параметра указывается идентификатор приложения, для которого необходимо сбросить ключ доступа. После сброса ключа приложению необходимо повторно выполнить процесс авторизации.
Настройка 1С для использования сервиса push-уведомлений
Для возможности использования сервиса push-уведомлений в прикладное решение 1С необходимо подключить расширение сервиса. Сервис может работать с любой конфигурацией 1С. Однако, методы, связанные с хранением секретной информации (такие, так ключи сервиса и т. п.) и работы с пользователями ИБ используют библиотеку стандартных подсистем (БСП). Если в вашей конфигурации не используется БСП, то необходимо переопределить методы общего модуля pns4ones_СервисУведомленийПереопределяемый.
После подключения расширения сервиса, в режиме «Предприятие» появится новый раздел «Сервис уведомлений». В данном разделе возможно выполнить общие настройки подключения к сервису и определить текущее состояние подключения к сервису клиентского сеанса.
Для возможности настройки подключения к сервису, пользователю должна быть доступна типовая роль ПолныеПрава или отдельная роль расширения (pns4ones) Администрирование сервиса уведомлений, если необходимо предоставить возможность настройки пользователю, не обладающему полными правами. Обычным пользователям должна быть назначена роль (pns4ones) Использование сервиса уведомлений.
Настройка подключения к сервису push-уведомлений
Для настройки подключения к сервису необходимо перейти в раздел Сервис уведомлений > Настройка сервиса уведомлений.
Для включения использования сервиса необходимо установить флаг Использовать сервис уведомлений.
В поле ID приложения указывается идентификатор приложения сервиса (см. раздел «Администрирование сервиса push-уведомлений»).
В группе настроек Сервер отправления уведомлений указываются данные для отправления уведомлений сервером 1С.
Адрес сервера – IP-адрес или имя сервера, на котором находится сервис уведомлений. Если используется не стандартный порт 36696, то номер порта указывается через двоеточие. Например, «localhost:7777».
Ключ сервера – ключ сервера для приложения сервиса уведомлений (см. раздел «Администрирование сервиса push-уведомлений»).
Если для сервиса уведомлений настроено использование защищенного HTTPS соединения, то необходимо установить флаг Использовать защищенное соединение.
В группе настроек Сервер приема уведомлений указываются данные для подключения клиентских сеансов 1С к сервису уведомлений.
Адрес сервера – IP-адрес или имя сервера, на котором находится сервис уведомлений. По умолчанию значение равно адресу из раздела Сервер отправления уведомлений. Эти значения могут отличаться, если приём и передача сообщений сервисом уведомлений настроена на разных сетевых интерфейсах. Например, передача сообщений разрешена на всех сетевых интерфейсах, а подключаться для приёма уведомлений клиенты могут только из локальной сети. Если используется не стандартный порт 36695, то номер порта указывается через двоеточие. Например, «192.168.10.3:8888».
Ключ клиента – ключ клиента для приложения сервиса уведомлений (см. раздел «Администрирование сервиса push-уведомлений»).
Отправление уведомлений от сервера 1С клиентским сеансам
Структура передаваемого сообщения
Передаваемое сообщение представляет собой Структуру с полями, описанными ниже. Для создания пустого сообщения можно использовать процедуру ИнициализироватьСообщение общего модуля pns4ones_СервисУведомленийКлиентСервер.
| Поля | |
|---|---|
| Тема |
Строка Тема уведомления. Используется для фильтрации обработчиков уведомлений. |
| Оповещение |
Структура Описывает оповещение для отображения пользователю при помощи метода ПоказатьОповещениеПользователя. Если оповещение отсутствует, то содержит значение Неопределено. Для создания пустого оповещения можно использовать процедуру ИнициализироватьОповещение общего модуля pns4ones_СервисУведомленийКлиентСервер. Описание полей структуры см. ниже в разделе «Описание структуры Оповещение». |
| Данные |
Структура Произвольные данные вида «Ключ-Значение», переданные отправителем уведомления. Может использоваться в алгоритмах обработчиков уведомлений. Значения могут быть только строкового типа. |
| СтандартнаяОбработка |
Булево Если содержит значение Истина (устанавливается по умолчанию) и заполнено свойство «Оповещение», то будет показано стандартное оповещение пользователю с использованием метода ПоказатьОповещениеПользователя. Значение свойства может быть установлено в Ложь одним из обработчиков оповещения. В таком случае оповещение пользователь показано не будет. |
Описание структуры "Оповещение".
Поля структуры практически идентичные параметрам метода ПоказатьОповещениеПользователя.
| Поля | |
|---|---|
| Текст |
Строка Текст оповещения. |
| Пояснение |
Строка Пояснение оповещения. |
| Картинка |
Строка Имя картинки из библиотеки картинок, которая будет показана в оповещении. |
| Статус |
СтатусОповещенияПользователя Определяет важность оповещения пользователя. |
| ДействиеПриНажатии |
Строка Содержит навигационную ссылку, по которой будет выполнен переход при нажатии на оповещении. Если свойство не указано, то никаких действий при нажатии не выполняется. |
Отправление сообщения
Для отправления сообщения используются функции ОтправитьУведомлениеПользователю, ОтправитьУведомлениеГруппеПользователей, ОтправитьУведомлениеВсемПользователям общего модуля pns4ones_СервисУведомлений.
ОтправитьУведомлениеПользователю
ОтправитьУведомлениеПользователю(ИдентификаторПользователя, Сообщение)
Отправляет уведомление отдельному пользователю информационной базы.
| Параметры | |
|---|---|
| ИдентификаторПользователя |
Строка Идентификатор пользователя информационной базы, которому необходимо отправить уведомление. Для получения идентификатора можно использовать процедуру ПолучитьИдентификаторПользователя. |
| Сообщение |
Структура Отправляемое сообщение, см. раздел «Структура отправляемого сообщения». |
| Возвращаемое значение | |
|
Структура |
Структура, описывающая результат отправления уведомления со следующими полями:
|
ОтправитьУведомлениеГруппеПользователей
ОтправитьУведомлениеГруппеПользователей(ГруппаПользователей, Сообщение)
Отправляет уведомление группе пользователей информационной базы.
| Параметры | |
|---|---|
| ГруппаПользователей |
Строка Группа пользователей, которым необходимо отправить уведомление. Например, «Менеджеры по продажам». |
| Сообщение |
Структура Отправляемое сообщение, см. раздел «Структура отправляемого сообщения». |
| Возвращаемое значение | |
|
Структура |
Структура, описывающая результат отправки уведомления со следующими полями:
|
ОтправитьУведомлениеВсемПользователям
ОтправитьУведомлениеВсемПользователям(Сообщение)
Отправляет уведомление всем пользователям информационной базы.
| Параметры | |
|---|---|
| Сообщение |
Структура Отправляемое сообщение, см. раздел «Структура отправляемого сообщения». |
| Возвращаемое значение | |
|
Структура |
Структура, описывающая результат отправки уведомления со следующими полями:
|
Пример отправления сообщения.
Оповещение = pns4ones_СервисУведомленийКлиентСервер.ИнициализироватьОповещение();
Оповещение.Текст = НСтр("ru='Создана новая задача'");
Оповещение.Пояснение = Задача.Наименование;
Оповещение.Статус = СтатусОповещенияПользователя.Важное;
Оповещение.ДействиеПриНажатии = ПолучитьНавигационнуюСсылку(Задача);
Сообщение = pns4ones_СервисУведомленийКлиентСервер.ИнициализироватьСообщение();
Сообщение.Оповещение = Оповещение;
ИмяИсполнителя = Задача.Исполнитель.Наименование;
ИдентификаторПользователя = pns4ones_СервисУведомлений.ПолучитьИдентификаторПользователя(ИмяИсполнителя);
Результат = pns4ones_СервисУведомлений.ОтправитьУведомлениеПользователю(ИдентификаторПользователя, Сообщение);
Если Не Результат.Успешно Тогда
pns4ones_СервисУведомленийВызовСервера.ЗаписатьОшибкуВЖурналРегистрации(Результат.ТекстОшибки);
КонецЕсли;
Отправление сообщений на клиенте фоновым заданием
Отправлять уведомления может не только сервер 1С, но и клиенты друг другу. Передача сообщения в таком случае выполняется с использованием серверного вызова. Т. к., на отправление сообщения требуется некоторое время, чтобы установить соединение с сервисом по протоколу HTTP(S) и передать сообщение, то в работе клиента возможны задержки на время, пока сообщение не будет отправлено. Для предотвращения блокировки интерфейса клиента при отправлении сообщения есть возможность отправлять сообщение с использованием фонового задания.
Для этого предназначены процедуры НачатьОтправкуУведомленияПользователю, НачатьОтправкуУведомленияГруппеПользователей, НачатьОтправкуУведомленияВсемПользователям общего модуля pns4ones_СервисУведомленийКлиент.
Назначение этих процедур идентично описанным в разделе «Отправление сообщений» выше их аналогам из общего модуля pns4ones_СервисУведомлений.
Отличаются они только наличием дополнительных параметров.
| ОповещениеОЗавершении |
ОповещениеОЗавершении
|
| ВыводитьОкноОжидания |
Булево Если Истина, то будет открыто окно ожидания с визуальной индикацией длительной операции. Если используется собственный механизм индикации, то следует указать Ложь. |
| ТекстСообщения |
Строка Если параметр ВыводитьОкноОжидания = Истина, то в данный параметр может быть передан текст сообщения, который будет выведен в окне ожидания. Если параметр не указан, то будет выведено стандартное сообщение. |
Пример отправления сообщения фоновым заданием на клиенте
&НаКлиенте
Процедура ОтправитьОповещение()
Оповещение = pns4ones_СервисУведомленийКлиентСервер.ИнициализироватьОповещение();
Оповещение.Текст = НСтр("ru='Создана новая задача'");
Оповещение.Пояснение = Задача.Наименование;
Оповещение.Статус = СтатусОповещенияПользователя.Важное;
Оповещение.ДействиеПриНажатии = ПолучитьНавигационнуюСсылку(Задача);
Сообщение = pns4ones_СервисУведомленийКлиентСервер.ИнициализироватьСообщение();
Сообщение.Оповещение = Оповещение;
Оповещение = Новый ОписаниеОповещения("ОтправитьОповещениеЗавершение", ЭтотОбъект);
pns4ones_СервисУведомленийКлиент.НачатьОтправкуУведомленияПользователю(
Оповещение,
ИдентификаторПользователя,
Сообщение
);
КонецПроцедуры
&НаКлиенте
Процедура ОтправитьОповещениеЗавершение(Результат, ДопПараметры) Экспорт
Если Результат.Успешно Тогда
ТекстСообщения = НСтр("ru='Оповещение отправлено.'";
Иначе
ТекстСообщения = НСтр("ru='Произошла ошибка при отправлении оповещения'") + ": " + Результат.ТекстОшибки;
КонецЕсли;
ПоказатьПредупреждение(, ТекстСообщения);
КонецПроцедуры
Вспомогательные функции
В общем модуле pns4ones_СервисУведомлений находятся дополнительные функции для облегчения реализации отправления сообщений.
ПолучитьИдентификаторПользователя
ПолучитьИдентификаторПользователя(ИмяПользователя)
Возвращает идентификатор пользователя информационной базы, который используется для отправления уведомления.
| Параметры | |
|---|---|
| ИмяПользователя необязательный |
Строка Имя пользователя информационной базы, идентификатор которого необходимо получить. Если параметр не указан, то будет возвращен идентификатор текущего пользователя. |
| Возвращаемое значение | |
|
Строка |
Идентификатор пользователя информационной базы. |
ГруппаПользователяИБ
ГруппаПользователяИБ(ПользовательИБ)
Возвращает группу пользователя информационной базы для отправления уведомления.
| Параметры | |
|---|---|
| ПользовательИБ необязательный |
ПользовательИнформационнойБазы, Строка, УникальныйИдентификатор Пользователь ИБ, его имя или идентификатор. Если не указан, то будет возвращена группа текущего пользователя. |
| Возвращаемое значение | |
|
Строка |
Группа пользователя информационной базы. |
Обработка полученных сообщений
По умолчанию, полученное сообщение отображается в виде всплывающего уведомления с использованием метода ПоказатьОповещениеПользователя. Если требуется дополнительная обработка отдельных сообщений, то необходимо в клиентском модуле или модуле формы &НаКлиенте создать процедуру-обработчик и подключить её к обработке полученных сообщений с помощью процедуры ПодключитьОбработчикУведомлений общего модуля pns4ones_СервисУведомленийКлиент.
ПодключитьОбработчикУведомлений
ПодключитьОбработчикУведомлений(Обработчик, Тема)
Подключает обработчик, который будет вызван при появлении новых уведомлений.
| Параметры | |
|---|---|
| Обработчик |
ОписаниеОповещения
|
| Тема необязательный |
Строка Если указан, то обработчик будет вызван лишь для тех уведомлений, которые относятся к этой теме. |
Если стандартная обработка сообщения не требуется, то в обработчике необходимо установить Сообщение.СтандартнаяОбработка = Ложь.
ОтключитьОбработчикУведомлений
ОтключитьОбработчикУведомлений(Обработчик)
Отключает ранее подключенный обработчик новых уведомлений.
| Параметры | |
|---|---|
| Обработчик |
ОписаниеОповещения Описание процедуры, заданной при вызове ПодключитьОбработчикУведомлений. |
Пример обработчика уведомлений
&НаКлиенте
Перем ОбработчикОповещения;
&НаКлиенте
Процедура ПриОткрытии(Отказ)
ОбработчикОповещения = Новый ОписаниеОповещения("ОбработкаОповещенияОНовойЗадаче", ЭтотОбъект);
pns4ones_СервисУведомленийКлиент.ПодключитьОбработчикУведомлений(Оповещение, "НоваяЗадача");
КонецПроцедуры
&НаКлиенте
Процедура ПриЗакрытии(ЗавершениеРаботы)
pns4ones_СервисУведомленийКлиент.ОтключитьОбработчикУведомлений(ОбработчикОповещения);
КонецПроцедуры
&НаКлиенте
Процедура ОбработкаОповещенияОНовойЗадаче(Сообщение, ДопПараметры) Экспорт
Элементы.СписокЗадач.Обновить();
КонецПроцедуры
Отправление уведомлений клиентским сеансам 1С из сторонних систем
Как уже упоминалось ранее, отправление уведомления осуществляется по протоколу HTTP.
Авторизация в сервисе push-уведомлений
Для возможности отправить уведомление необходимо выполнить авторизацию в сервисе push-уведомлений для 1С. Для этого необходимо отправить GET запрос к ресурсу /auth с параметром server_key, значением которого является ключ сервера приложения из панели веб-администрирования.
Пример запроса.
http://mysite.com:36696/auth?server_key=jwEQmTEjQh9UvCO05JlVsKFh8X5K94Iuw2HbkyteVe3XUcOwjgrESEN8VdCnkcp4
В случае успешной авторизации ответ будет содержать объект JSON с данными ключа доступа.
| Представление JSON |
|---|
|
{ |
| Поля | |
|---|---|
| access_token |
string Ключ доступа к сервису. |
| expires_in |
number Дата, до которой действует ключ доступа в формате unix-time (содержит количество секунд с 01.01.1970 00:00:00). По истечению этой даты необходимо повторить процесс авторизации для получения нового ключа доступа. |
Отправление уведомлений
Для отправления уведомлений необходимо выполнить POST запрос к ресурсу /sendmessage.
Должен быть установлен заголовок Authorization, значением заголовка является строка формата «Bearer <КлючДоступа>». Подробнее о получении ключа доступа см. выше в разделе «Авторизация в сервисе push-уведомлений».
В теле запроса передаётся объект JSON, описывающий получателя(-ей) и отправляемое сообщение.
| Представление JSON |
|---|
|
{ |
В случае успешного отправления уведомления будет возвращён пустой ответ с кодом состояния 200. Если был передан неверный ключ доступа, то будет возвращён код состояния 401. Если срок действия указанного ключа доступа истёк, то будет возвращён код состояния 403. В таком случае необходимо выполнить повторную авторизацию для получения нового ключа доступа.
Объект JSON Recipient
Содержит данные о получателе(-ях) сообщения.
| Поля | |
|---|---|
| IbId |
string Идентификатор информационной базы. Получить идентификатор ИБ можно вызвав функцию ИдентификаторИнформационнойБазы общего модуля pns4ones_СервисУведомленийПереопределяемый. |
| Type |
string Тип получателя сообщения. Может принимать следующие значения:
|
| UserId |
string Указывается, если Type=user и содержит идентификатор пользователя, которому отправляется сообщение. |
| UserGroup |
string Указывается, если Type=group и содержит название группы пользователей, которым отправляется сообщение. Например, «Менеджеры по продажам». |
Объект JSON Message
Содержит данные отправляемого сообщения.
| Поля | |
|---|---|
| Topic optional |
string Название темы для отправляемого сообщения. |
| Notification optional |
object Notification Объект JSON, содержащий данные оповещения, отображаемого пользователю. Подробнее см. «Объект JSON Notification» ниже. |
| Data optional |
map (key: string, value: string) Произвольные дополнительные данные в виде ключ-значение. Значения должны быть строковым типом. Пример: {"ВидСобытия": "НоваяЗадача", "Номер": "00-013390"}. |
Объект JSON Notification
Содержит данные оповещения, отображаемого пользователю.
| Поля | |
|---|---|
| Title |
string Заголовок оповещения. |
| Body |
string Текст оповещения. |
| Icon optional |
string Название картинки из библиотеки картинок конфигурации 1С, которая будет выведена в оповещении. |
| Action optional |
string Навигационная ссылка, которая будет открыта при нажатии пользователем на оповещении. |
| Important |
boolean Если значение true, то оповещение будет отображено, как важное. |
Пример запроса
POST /sendmessage HTTP/1.1
Host: mysite.com
Authorization: Bearer ytO9ipwxUCUyp2SiI0hhWNKSyEpOcjmhJbVFKqFlFLMzA4z6OASv9nI5e36QioET
Content-Type: application/json
{
"Recipient": {
"Type": "all",
"IbId": "d2273d53-b633-4817-a006-4fa627a5dea9"
},
"Message": {
"Topic": "Hello",
"Notification": {
"Title": "Заголовок",
"Body": "Тело сообщения",
"Important": false
},
"Data": {
"param1": "value 1",
"param2": "value 2"
}
}
}
Демонстрационные обработки, входящие в состав расширения 1С
В состав расширения входят обработки, демонстрирующие работу с сервисом уведомлений и использование описанных выше процедур и функций.
Демонстрация оповещения пользователей о новых электронных письмах
В расширении заимствован общий модуль УправлениеЭлектроннойПочтой из БСП. При выполнении фонового задания на сервере по получению писем, пользователям, для которых получены письма отправляются соответствующие уведомления. Никакой дополнительной обработки не выполняется, в результате чего пользователь видит обычное всплывающее оповещение 1С. При нажатии на оповещение, если было получено одно письмо, то открывается форма этого письма. Если было получено несколько писем, то будет открыта форма списка документов ЭлектронноеПисьмоВходящее.
Демонстрация оповещения пользователя о новой задаче
В расширении заимствована задача ЗадачаИсполнителя. При сохранении новой задачи пользователем, создавшим её, пользователю-исполнителю отправляется соответствующе уведомление. Никакой дополнительной обработки не выполняется, в результате чего пользователь видит обычное всплывающее оповещение 1С. При нажатии на оповещение открывается форма созданной задачи.
Демонстрация выполнения длительной операции на сервере
Обработка запускает выполнение длительной операции фоновым заданием на сервере. По мере выполнения, задание на сервере передаёт клиенту изменение своего состояния через сервис push-уведомлений. По сути, является альтернативой типового обработчика ожидания из БСП. Только в данном случае получение информации о работе задания происходит не периодическим опросом на клиенте, а передаётся оповещение клиента самим заданием в режиме «онлайн».
Данная обработка предназначена в первую очередь для демонстрации передачи произвольных данных с сервера на клиент.
Простой чат
В качестве демонстрации реализации сложных сценариев создан простой чат, позволяющий пользователям обмениваться сообщениями в общей комнате. Поддерживаются приватные сообщения.
Чат состоит из двух частей (обработок): сервера и клиента. Сервер осуществляет подключение клиентов и передачу сообщений между ними. Отправление сообщений выполняется фоновым заданием без блокировки пользовательского интерфейса.
В данной демонстрации сервис уведомлений используется в качества транспорта сообщений, а вся бизнес-логика реализована кодом 1С.
Сетевая игра «Камень, Ножницы, Бумага»
Реализация известной игры «Камень, Ножницы, Бумага». Так же состоит из двух частей: сервера и клиента.
Поддерживается возможность создания нескольких серверов, что позволяется играть нескольким парам игроков одновременно.
Условия использования сервиса push-уведомлений для 1С
Исходные коды сервиса push-уведомлений, расширения 1С для работы с сервисом и внешней компоненты для обмена сообщениями сервиса с 1С распространяются под лицензией Apache 2.0. Вы можете свободно использовать, изменять и распространять его, в том числе и в коммерческих целях с обязательным указанием авторства. Подробнее см. текст лицензии http://www.apache.org/licenses/LICENSE-2.0
Исходный код и установочные пакеты доступны на github: https://github.com/ltfriend/PNS4OneS
Работа сервиса протестирована под следующими операционными системами:
- Windows 10;
- Windows 11;
- Windows Server 2012;
- CentOS 7;
- Ubuntu 21.10.
Работа внешней компоненты была протестирована со следующими платформами 1С:
- 1С:Предприятие 8.3.17.2308 для Windows;
- 1С:Предприятие (x86-64) 8.3.20.1674 для Windows;
- 1С:Предприятие (x86-64) 8.3.20.1549 для Linux.
