Глава 29. Система взаимодействия
страницаГлава 29. Система взаимодействия
29.1. Общая информация
Система взаимодействия ‑ это механизм, позволяющий взаимодействовать между собой системе «1С:Предприятие» (в одной или нескольких информационных базах), серверу взаимодействия и различным внешним системам. Одна информационная база (или область данных), однозначно идентифицируемая системой взаимодействия, называется приложением. Система взаимодействия призвана упростить автоматизацию бизнес-процессов предприятия и предоставляет пользователям приложения простой способ коммуникации в рамках выполнения должностных обязанностей. Пользоваться системой взаимодействия могут как пользователи приложения, так и внешние (по отношению к системе «1С:Предприятие») пользователи. При этом, если пользователь является пользователем приложения, то ему не требуется отдельно регистрироваться в системе взаимодействия. Авторизация пользователя в системе взаимодействия осуществляется системой «1С:Предприятие».
Взаимодействие может быть:
● Не интерактивным ‑ в обмене информацией принимают участие только подсистемы прикладного решения, не предполагающие интерактивного взаимодействия. Такое взаимодействие может происходить в том случае, если необходимо передавать какую-либо информацию между подсистемами прикладного решения во время выполнения какой-либо активности.
● Только интерактивным ‑ когда все участники взаимодействия являются живыми людьми. Например, два пользователя обсуждают возможность предоставления скидки контрагенту и ее (скидки) размер.
● Смешанным ‑ когда взаимодействие выполняется между живым человеком с одной стороны и подсистемой прикладного решения с другой. Простейшим примером такого взаимодействия является робот, отвечающий на определенные запросы.
При интерактивном взаимодействии пользователи приложения могут общаться друг с другом в режиме реального времени с помощью текстовых сообщений и видеозвонков. Под термином «видеозвонок» понимается любой возможный вариант общения двух (или более) пользователей, который включает в себя как только голосовой канал общения, так и полноценный видеозвонок (и голосовая информация и изображение). Видеозвонки могут быть только интерактивными (в них участвуют только живые люди). Во время видеозвонка имеется возможность демонстрации своего экрана. Экран может быть продемонстрирован только в том случае, если для данного пользователя окно видеозвонка занимает весь монитор. В противном случае вместо демонстрации экрана отображается специальный значок Показ экрана.
Взаимодействие пользователей осуществляется в рамках обсуждений. Обсуждение ‑ это набор сообщений, связанных одной темой. Темой обсуждения может быть все, что угодно: документ, погода, исполнение какого-либо действия и т. д. Обсуждение может быть двух видов:
1. Неконтекстное обсуждение ‑ обсуждение, которое не привязано к объекту информационной базы. В таком обсуждении могут принимать участие любые пользователи приложения, которые выбраны участниками обсуждения. Неконтекстных обсуждений может быть произвольное количество.
2. Контекстное обсуждение ‑ это обсуждение, которое привязано к какому-либо объекту приложения. В таком обсуждении могут принимать участие только те пользователи приложения, которые имеют доступ к обсуждаемому объекту. Каждый объект может иметь только одно обсуждение.
К сообщениям системы взаимодействия можно прикреплять различные файлы. Для этого необходимо настроить работу сервера взаимодействия с внешним хранилищем. Внешнее хранилище должно поддерживать протокол Amazon S3. Если сервер системы взаимодействия не подключен к хранилищу ‑ возможность прикрепления файлов будет недоступна. Если для передачи файлов используется сервис 1С:Диалог, то механизм передачи и хранения файлов имеет определенные ограничения, которые приведены на странице https://1cdialog.com/ru/pricing/.
Система взаимодействия может интегрироваться с различными внешними системами. В результате интеграции обеспечивается возможность доступа к обсуждениям во внешних системах из системы взаимодействия.
Доступ к сообщениям возможен с помощью Центра оповещений, элемента Обсуждения панели открытых, специальной панели сообщений в формах объектов системы (для контекстных сообщений) и с помощью программного интерфейса, предоставляемого свойством глобального контекста СистемаВзаимодействия.
Система взаимодействия реализована в клиент-серверной архитектуре и состоит из следующих частей:
● Клиентская часть системы взаимодействия является составной частью системы «1С:Предприятие».
● Серверная часть представляет собой специализированный сервер, представленный сервисом 1С:Диалог или экземпляром продукта 1С:Сервер взаимодействия. Содержимое обсуждений хранится на сервере системы взаимодействия. Информация о видеозвонках (включая факты совершения) никак не хранится в системе взаимодействия.
Обмен сообщениями между клиентской частью и сервером взаимодействия осуществляется по протоколу WebSocket. Этот протокол обеспечивает защищенную передачу данных, что позволяет безопасно передавать сообщения, с помощью которых общаются пользователи, как в локальной сети, так и через Интернет. Если доступ к серверу системы взаимодействия осуществляется через прокси-сервер, то настройки прокси-сервера получаются из системных настроек операционной системы (не поддерживается использование сценария автоматической настройки) или из конфигурационного файла inetcfg.xml (подробнее см. здесь). NTLM-аутентификация на прокси-сервере не поддерживается. Для видеозвонков используется соединение типа «точка-точка» (peer-to-peer), при этом установка соединения происходит через сервер системы взаимодействия.
Система «1С:Предприятие» обеспечивает пользовательский интерфейс для обмена сообщениями (любых поддерживаемых видов), а также предоставляет программный интерфейс, позволяющий выполнить некоторые операции, в число которых входят следующие:
● зарегистрировать или отменить регистрацию приложения в серверной части системы взаимодействия;
● объединять или отменять объединение приложений, а также получать информацию об объединенных приложениях;
● получать и устанавливать данные, позволяющие приложению взаимодействовать с сервером системы взаимодействия (данные регистрации);
● работать с пользователями системы взаимодействия;
● создавать и получать обсуждения и сообщения;
● реализовывать специализированные инструменты для работы с сообщениями.
Не поддерживается работа с несколькими копиями одной информационной базы. В том случае, если информационная база будет скопирована, то такая база сможет подключиться к сервису, однако при работе будут наблюдаться различные особенности, например:
● Обсуждения и оповещения будут доступны во всех копиях информационных базах.
● Будут наблюдаться проблемы при работе с контекстными обсуждениями для тех объектов, которые созданы после клонирования оригинальной информационной базы.
● Будут наблюдаться проблемы при работе с получателями сообщений в том случае, если пользователи в информационных базах создавались после клонирования.
В то же время, имеется возможность объединить несколько приложений в единое информационное пространство (с точки зрения системы взаимодействия). Для этого необходимо зарегистрировать каждое приложение в системе взаимодействия, а потом объединить необходимые приложения. Объединенные приложения обладают единым списком пользователей (из всех объединенных приложений). При объединении приложений можно указать, каким образом будут сопоставляться пользователи объединяемых приложений.
Видеозвонки поддерживаются:
● В тонком клиенте при работе под управлением:
● ОС macOS любой поддерживаемой версии.
● ОС Linux любой поддерживаемой версии.
● ОС Windows 7 и старше.
● Поддерживается использование видеозвонков в том случае, если клиентское приложение запущено на удаленном рабочем столе (RDP). Для этого необходимо обеспечить доступность в удаленном рабочем столе микрофона и камеры компьютера, на котором запускается подключение к удаленному рабочему столу.
● В веб-клиенте:
● При работе в веб-браузере:
● Google Chrome версии 64 и последующих.
● Microsoft Edge версии 64 и последующих.
● Mozilla Firefox версии 68 и последующих.
● Safari версии 13 и последующих.
● При использовании сервера системы взаимодействия версии 10 и последующих.
● При работе в веб-браузере видеозвонки поддерживаются только в том случае, если доступ к информационной базе выполняется по протоколу HTTPS.
● Трансляция экрана:
● Поддерживается при работе в веб-браузерах Google Chrome, Mozilla Firefox.
● Поддерживается только при использовании протокола HTTPS.
● При использовании веб-браузера Google Chrome доступна трансляция не только всего экрана, но и отдельной закладки.
● В веб-браузере Google Chrome требуется уставить расширение работы веб-браузера и предоставить расширению возможность выполнять снимок содержимого экрана.
При работе с сервисом 1С:Диалог, система «1С:Предприятие» должна иметь свободный доступ к следующим URL (и сетевым портам):
|
URL |
Порт |
Описание |
|
|
443 |
Точка подключения к сервису 1С:Диалог |
|
|
443 |
Хранилище файлов сервиса 1С:Диалог (доступ выполняется по протоколу HTTPS). |
|
|
80 |
Сервер проверки отзыва сертификатов. |
Если для работы используется развернутый экземпляр продукта 1С:Сервер взаимодействия, то используемые URL (и порты) определяются настройками этого сервера. За получением такой информации необходимо обращаться к администратору сервера системы взаимодействия. Документация по развертыванию и администрированию сервера взаимодействия представлена на Портале ИТС (https://its.1c.ru/db/csdoc).
29.2. Устройство системы взаимодействия
Работа системы взаимодействия построена на клиент-серверном обмене данными между системой «1С:Предприятие» и сервером системы взаимодействия. При этом и клиентское и серверное приложение системы «1С:Предприятие» выступают в роли клиентов сервера системы взаимодействия. Взаимодействие организуется вокруг приложения системы взаимодействия (информационная база или область данных).
Чтобы начать использование системы взаимодействия, приложение, пользователи которого будут участвовать в этом взаимодействии, необходимо зарегистрировать в сервисе системы. Во время регистрации приложения в сервисе системы взаимодействия создается (и сохраняется) следующая информация:
● Уникальный идентификатор приложения в сервисе. Этот идентификатор сохраняется как в самой информационной базе, так на сервере системы взаимодействия. Этот идентификатор нельзя получить и установить самостоятельно.
● Криптографические ключи, которые используются для обеспечения безопасной передачи сообщений между клиентской и серверной частями системы взаимодействия. Эти ключи хранятся как в приложении, так и на сервере системы взаимодействия. Каждая сторона взаимодействия хранит свой набор ключей.
● В сервисе также сохраняется имя регистрируемого приложения и адрес электронной почты, который используется при регистрации информационной базы. Адрес электронной почты, который используется при регистрации приложения в сервисе, будет олицетворять абонента сервиса. Один абонент сервиса может зарегистрировать несколько приложений. Этот абонент будет обладать административными правами в зарегистрированном приложении. Такой пользователь (или пользователи) также могут называться администратором абонента.
В дальнейшем адрес сервиса взаимодействия, имя приложения, электронная почта и код активации (совокупно) будут называться «параметры регистрации приложения в сервисе». В то же время параметры регистрации приложения в сервисе, идентификатор приложения в сервисе и криптографические ключи, используемые для обмена, будут совокупно называться «данными регистрации приложения».
Для того чтобы прекратить работу системы взаимодействия, необходимо выполнить отмену регистрации приложения в сервисе. В этом случае в приложении удаляются криптографические ключи, используемые для обеспечения обмена и, как следствие, обмен сообщениями становится невозможным. При повторной регистрации того же приложения будет создана новая пара ключей. В результате обмен сообщениями будет восстановлен и станет доступна вся история сообщений. Для корректного восстановления обмена сообщениями важно, чтобы у приложения остался неизменным уникальный идентификатор этого приложения в сервисе. Если это правило нарушено ‑ восстановить доступ к истории сообщений будет невозможно.
Для того чтобы приложение смогло зарегистрироваться в сервисе системы взаимодействия, в нем должны быть заданы пользователи. В противном случае приложение не сможет зарегистрироваться в сервисе и, как следствие, в нем будет невозможно использовать возможности системы взаимодействия. В процессе обмена информацией могут принимать участие только те пользователи приложения, которые зарегистрированы в сервисе взаимодействия. Для каждого пользователя приложения создается парный пользователь в системе взаимодействия. Создание такого пользователя выполняется при первой аутентификации пользователя приложения после регистрации этого приложения в сервере системы взаимодействия или с помощью методов встроенного языка. При последующих аутентификациях пользователя, в системе взаимодействия автоматически актуализируются имя и полное имя пользователя информационной базы. Сопоставление пользователей (приложения и сервиса взаимодействия) выполняется по уникальному идентификатору пользователя информационной базы системы «1С:Предприятие». Если требуется другой алгоритм синхронизации списка пользователей ‑ прикладной разработчик должен реализовать его самостоятельно.
29.3. Интерактивное взаимодействие
29.3.1. Параметры пользователей
После подключения приложения к сервису взаимодействия, появляется возможность указания дополнительных параметров для пользователя, который зарегистрирован в системе взаимодействия.
Поддерживается хранение полного имени пользователя, картинки (аватара), телефонного номера и адреса электронной почты.
29.3.2. Виды обсуждений
29.3.2.1. Неконтекстные обсуждения
Неконтекстные обсуждения не привязаны к каким-либо объектам приложения. Любой пользователь может создать произвольное количество таких обсуждений. Неконтекстные обсуждения могут быть двух видов: с любым количеством участников (вариант «группового обсуждения») и только с двумя участниками (вариант «один на один»). При создании обсуждения его участниками являются пользователь, создавший обсуждение, и те пользователи, которых он указал при создании обсуждения. В дальнейшем, в зависимости от имеющихся прав, участник обсуждения может:
● просматривать сообщения обсуждения;
● добавлять сообщения в обсуждение;
● следующие возможности доступны только для группового обсуждения (и недоступны для обсуждений «один на один»):
● изменять название (тему) обсуждения;
● добавлять новых участников обсуждения (любых пользователей информационной базы);
● покинуть обсуждение.
Если обсуждение покидает последний участник, то обсуждение становится недоступным. При этом на сервере взаимодействия содержимое обсуждений сохраняется. Неконтекстное обсуждение видимо только для участников обсуждения. Если сервер системы взаимодействия, который обслуживает информационную базу, позволяет выполнять видеозвонки, то групповой обсуждение можно вести как в текстовом формате, так и в формате видеоконференции. Эта часть обсуждения будет называться видеокомната. Для создания видеокомнаты не требуется выполнять дополнительных действий. Видеокомната доступна всем участникам обсуждения и в нее нужно просто «войти» (подключиться). Также имеется возможность подключения к групповым обсуждениям внешних пользователей.
Создание неконтекстного обсуждения выполняется из основной формы системы взаимодействия, которая становится доступной после регистрации приложения в сервисе взаимодействия. Участниками обсуждения могут быть любые пользователи системы взаимодействия. Для того, чтобы в обсуждении принял участие гостевой пользователь, необходимо, чтобы этот пользователь получил приглашение в обсуждение (подробнее см. здесь).
Основная форма системы взаимодействия всегда является второй (после начальной страницы) формой в панели открытых. Эту форму нельзя закрыть и перетащить в другое место панели. Если в прикладном решении отсутствует начальная страница, основная форма системы взаимодействия становится первой формой в панели открытых.
При создании нового обсуждения предлагается указать тему сообщения и участников. Инициатор обсуждения автоматически добавляется в список участников.
Для создания обсуждения «один на один» необходимо в строке поиска формы Обсуждения указать пользователя, с которым необходимо создать обсуждение. Для таких обсуждений не указывается тема и состав участников. Тема обсуждения «один на один» не может быть задана, а состав участников автоматически формируется системой.
В списке обсуждений показываются все неконтекстные обсуждения, по которым для пользователя есть уведомления. Если таких обсуждений меньше 50, то список дополняется неконтекстными обсуждениями, в которых пользователь является участником, и по которым для пользователя нет уведомлений. Эти обсуждения добавляются в список в порядке убывания даты последнего сообщения в обсуждении, пока размер списка не достигнет 50 элементов.
Поиск в списке обсуждений работает по темам обсуждений и именам пользователей. Поиск в списке сообщений работает только по сообщениям выбранного обсуждения. Не поддерживается возможность поиска обсуждения по тексту сообщений.
При появлении в обсуждении новых сообщений, участники обсуждения получают оповещения.
29.3.2.2. Контекстные обсуждения
Контекстные обсуждения (как уже было сказано ранее) привязаны к объектам приложения. Если приложение подключено к сервису взаимодействия, то для форм элементов ссылочных типов и форм записей регистров сведений, становится доступна команда формы Обсуждение. Для каждого объекта существует только одно контекстное обсуждение. В обсуждении могут принимать участие все пользователи приложения (или приложений), которые имеют право Чтение для обсуждаемого объекта.
Контекстное обсуждение выполняется в форме обсуждаемого объекта (в правой части). Такое обсуждение не имеет заголовка. Открытие и закрытие списка сообщений выполняется циклическим нажатием кнопки Обсуждение.
Несмотря на то, что в обсуждении по умолчанию могут принимать участие все пользователи приложения (с соответствующими правами), при создании сообщения в контекстном обсуждении имеется возможность выбрать адресатов сообщения. В данном случае адресаты выбираются для того, чтобы отобразить им оповещения о новом сообщении. Остальные пользователи получат оповещение только в том случае, если они подпишутся на получение оповещений о новых сообщениях в этом обсуждении.
Команда Обсуждение не выводится в формах, которые блокируют окно владельца или весь интерфейс. Эти формы обычно используются для отображения и редактирования данных, не имеющих самостоятельного прикладного значения, поэтому механизм обсуждений для них не предусмотрен.
Для форм, которые не блокируют окно владельца или интерфейс приложения, имеется возможность управлять доступностью команды Обсуждение в форме. Управление осуществляется с помощью свойства управляемой формы ОтображениеОбсуждений. Установка данного свойства в значение Не отображать приведет к тому, что команда Обсуждение не будет доступна в форме.
Следует, однако, учитывать, что контекстное обсуждение доступно только в той форме, навигационная ссылка которой указывает на данные, которые хранятся в информационной базе, или команду.
Смотри также:
● Права доступа (см. здесь).
29.3.3. Виды сообщений
29.3.3.1. Текстовые сообщения
Основным механизмом в системе взаимодействия считается обмен текстовыми сообщениями. Размер текстового сообщения ограничен значением 4 000 символов. Само текстовое сообщение может быть и просто текстом и форматированной строкой (объект типа ФорматированнаяСтрока). Указание форматированного сообщения доступно только при программном формировании сообщения. Когда форматированная строка присваивается свойству СообщениеСистемыВзаимодействия.Текст, то форматирование сохраняется, но картинки (если таковые есть в строке) удаляются. Форматирование сообщения будет сохранено в следующих случаях:
● во всплывающих уведомлениях,
● в центре оповещений,
● в формах обсуждений.
В остальных случаях текст сообщения отображается без форматирования. При отображении форматированного сообщения автоматическое распознавание гиперссылок не выполняется, а «смайлики» распознаются только для следующих комбинаций символов и эмотиконов (специальных символов Unicode):
|
Код |
Текстовый аналог |
Из встроенного языка |
|
U+1F610 |
:| |
|
|
U+1F600 |
:D |
|
|
U+1F642 |
:) |
|
|
U+1F641 |
:( |
|
|
U+1F62E |
:o |
|
|
U+1F61B |
:P |
|
|
U+1F609 |
;) |
|
29.3.3.2. Видеозвонки (видеоконференции)
Для использования видеоконференций должны быть выполнены следующие требования:
1. Сервер взаимодействия должен разрешать видеозвонки для абонента, который выполнял регистрацию приложения.
2. Клиентское приложение, которое применяется для работы в прикладном решении, позволяет использовать видеозвонки.
3. Компьютеры пользователей ‑ участников видеоконференции, должны быть оснащены микрофонами и динамиками. При наличии видеокамеры у участника видеоконференции обеспечивается показ изображения видеокамеры другим участникам видеоконференции.
Для того, чтобы определить возможность работы с видеозвонками (видеоконференциями) следует использовать метод ПоддерживаютсяВидеоконференции() менеджера системы взаимодействия. Если видеоконференции доступны, то можно определить, какое максимальное количество участников могут принимать участие в видеоконференции. Для этого следует использовать метод ПолучитьМаксимальноеКоличествоУчастниковВидеоконференции() менеджера системы взаимодействия.
Если видеозвонки (видеоконференции) поддерживаются, то можно использовать этот инструмент:
● Полностью интерактивно, с помощью соответствующих инструментов интерфейса клиентского приложения. В этом случае видеозвонок начинается интерактивно пользователем. Также для конкретного видеозвонка можно сформировать ссылку-приглашение для того, чтобы упростить подключение новых пользователей (в том числе гостевых). Для получения ссылки-приглашения надо нажать гиперссылку Копировать ссылку для приглашения участников в диалоге добавления участников видеоконференции.
● Из встроенного языка, с помощью метода менеджера системы взаимодействия НачатьВидеоконференцию(). В этом случае видеоконференция может быть начата в результате какого-то другого интерактивного действия. В рамках такого вызова состав участников видеоконференции может быть сформирован автоматически (по критериям, реализованным в прикладном решении) и пользователи могут не участвовать в начальном выборе состава участников.
29.3.4. Оповещения
Для информирования пользователей о новых сообщениях, система взаимодействия использует оповещения. Оповещение формируется для каждого нового сообщения в рамках каждого обсуждения. Оповещения направляются:
● при добавлении сообщения в контекстное обсуждение ‑ всем пользователям, которых автор сообщения указал в качестве адресатов, а также пользователям, включившим режим наблюдения для этого контекстного обсуждения (с учетом правил оповещения);
● при добавлении сообщения в неконтекстное обсуждение ‑ всем участникам обсуждения (с учетом правил оповещения);
● при пропущенном видеозвонке ‑ пользователю, пропустившему видеозвонок.
Обсуждение содержит сообщения, отправленные пользователями. При появлении нового сообщения возникает оповещение. Настройки системы позволяют управлять как доступностью сообщений, так и отображением оповещений. И получение сообщений, и получение оповещений управляются с помощью некоторых настроек: права пользователя, настройки получения оповещений и настройка отображения оповещений о новых сообщениях. Рассмотрим поведение системы в разрезе этих настроек.
Как известно, обсуждения бывают двух видов: контекстные и неконтекстные. Права пользователя для этих обсуждений формируются по-разному:
● Для контекстного обсуждения: пользователь должен иметь право Чтение на обсуждаемый объект.
● Для неконтекстного обсуждения: должен быть участником обсуждения.
Оповещения о новых сообщениях будут получены пользователем при следующих настройках обсуждений:
● Для контекстного обсуждения: в настройках обсуждения пользователь указал Оповещать обо всех сообщениях или является адресатом сообщения.
● Для неконтекстного обсуждения: в настройках обсуждения пользователь указал Оповещать о новых сообщениях.
Таким образом, если у пользователя есть права на обсуждение и он решил получать оповещения ‑ оповещения о новых сообщениях будут отображаться в Центре оповещений.
Режим получения оповещений управляется с помощью методов ПолучитьРежимНаблюдения() и УстановитьРежимНаблюдения(). Параметр, описывающий режим наблюдения, фактически означает следующее (в зависимости от вида обсуждения):
● Контекстное обсуждение:
● Истина ‑ соответствует режиму Оповещать обо всех новых сообщениях.
● Ложь ‑ соответствует режиму Оповещать только о новых сообщениях, адресованных мне.
● Неконтекстное обсуждение:
● Истина ‑ соответствует режиму Оповещать о новых сообщениях.
● Ложь ‑ соответствует режиму Не оповещать о новых сообщениях.
Как и установка режима получения оповещений, режим наблюдения может устанавливаться как для текущего, так и для произвольного пользователя. Во втором случае для выполнения операции требуется установка привилегированного режима.
Последняя настройка управляет отображением всплывающих оповещений о новых сообщениях:
● В настройках пользователя выбран режим Не беспокоить ‑ оповещения не будут отображаться для всех обсуждений.
● В настройках обсуждения выбран режим Не беспокоить ‑ оповещения не будут отображаться для того обсуждения, где указан режим Не беспокоить.
Для обсуждений имеется возможность управлять режимом Не беспокоить с помощью встроенного языка. Для этого следует использовать методы менеджера системы взаимодействия ПолучитьОтображениеОповещенийОбсуждения() и УстановитьОтображениеОповещенийОбсуждения(). Режим отображения оповещений может задаваться как для текущего пользователя, так и для любого пользователя системы взаимодействия. Для того, чтобы работать с режимом отображения оповещений для любого пользователя ‑ необходимо использование привилегированного режима.
Смотри также:
● Привилегированный режим (см. здесь).
● Права доступа (см. здесь).
29.3.5. Внешние пользователи
При эксплуатация информационных систем может возникать необходимость подключения внешних пользователей к общению с сотрудниками компании. Например, обсуждение заказа с контрагентом, условий трудового соглашения с кандидатом на работу и т. д. Такое взаимодействие можно организовать с помощью сторонних мессенджеров, а можно сделать с помощью системы взаимодействия.
Для реализации такой возможности система предоставляет возможность отправить внешнему пользователю специальную ссылку на внешний сайт. Перейдя по этой ссылке, внешний пользователь получит возможность общения с сотрудниками компании (включая видеозвонки) с помощью системы взаимодействия. Сайт, через который происходит общение, может быть предоставлен фирмой «1С» (сервис «dialog.online», https://dialog.online) или развернут в рамках собственного сервера системы взаимодействия.
Внешний пользователь имеет ряд ограничений, по сравнению с обычным пользователем системы взаимодействия:
● Внешний пользователь может общаться только в неконктекстных обсуждениях.
● Внешний пользователь может общаться только с теми пользователями, которые участвуют в обсуждениях, которые доступны этому внешнему пользователю (в которые его пригласили).
● Если внешний пользователь участвует в видеозвонке, где присутствуют пользователи, с которыми внешний пользователь не связан обсуждениями, то такие пользователи не видны для внешнего пользователя.
● Если внешний пользователь перестаёт участвовать в обсуждении, то он перестает «видеть» тех пользователей, которые были в покинутом обсуждении и больше не участвуют в обсуждениях с эти внешним пользователем.
● Внешний пользователь не может изменять состав пользователей обсуждения, кроме, как только покинуть обсуждение.
Внешний сайт могут пользовать и обычные пользователи «1С:Предприятия». Для них будет действовать только ограничение доступа к контекстным обсуждениям. Это может оказаться удобно при работе на мобильном устройстве, так как нет необходимости устанавливать мобильное приложение. Приглашение для обычных пользователей может быть отправлено только с помощью встроенного языка.
Если в системе взаимодействия доступен внешний доступ, то для того, чтобы начать общение с внешним пользователем, предоставляются следующие возможности:
● В меню списка обсуждений становится доступной команда Пригласить внешнего участника. В этом случае будет начато обсуждение «один на один».
● В меню группового обсуждения становится доступной команда Пригласить внешнего участника. В этом случае внешний пользователь станет участником обсуждения.
В обеих случаях будет создан внешний пользователь, созданному пользователю будет отправлено приглашение, и этот пользователь будет включен в соответствующее обсуждение.
Смотри также:
● Работа с пользователями (см. здесь).
● Программная работа с внешними пользователями (см. здесь).
29.3.6. Гостевые пользователи
Внешние пользователи ‑ это постоянные пользователи, которые идентифицируются с помощью электронной почты. Однако, часто возникает необходимость подключить к обсуждению или видеозвонку пользователя, который нужен только «здесь и сейчас», например это может быть собеседование при приеме на работу. В этом случае используется гостевой пользователь. Гостевой пользователь ‑ это внешний пользователь, который получил доступ к системе взаимодействия на конкретное обсуждение (видеокомната обсуждения и сами сообщения, если к ним предоставляется доступ) или на текущую видеоконференцию. Гостевой пользователь образуется в тот момент, когда некоторый человек подключается к видеозвонку (входит в видеокомнату) или обсуждению с помощью навигационной ссылки приглашения в обсуждение. Переход по такой ссылке выполняет переход в обсуждение (если разрешено) или подключение к видеокомнате обсуждения.
Гостевой пользователь имеет следующие ограничения:
● При первом переходе по ссылке приглашения в обсуждение будет создаваться новый гостевой пользователь.
● Имеет доступ к только одному обсуждению, для которого была сформирована ссылка-приглашение.
● Не имеет списка обсуждений.
● Не может создавать новые обсуждения.
● Такие пользователи не отображаются при выборе участников обсуждений. Из чего следует несколько следствий:
● Нельзя создавать новые обсуждения с участием гостевого пользователя.
● Гостевого пользователя нельзя добавить в участники обсуждения, отличного от того, куда он был приглашен.
● За пределами обсуждения, доступного гостевому пользователю, он недоступен для звонков и сообщений.
● Гостевой пользователь не может просматривать карточки пользователей системы взаимодействия.
● Гостевой пользователь не может стать полноценным внешним пользователем, если укажет электронную почту. В то же время, гостевой пользователь может изменять свое имя, номер телефона, адрес электронной почты и картинку.
Смотри также:
● Приглашение в обсуждение (см. здесь).
29.4. Не интерактивное взаимодействие
29.4.1. Общая информация
Большинство операций, выполняемых с использованием системы взаимодействия, можно выполнить интерактивно или с использованием методов встроенного языка. В данном разделе будут рассмотрены примеры реализации тех или иных возможностей работы с системой взаимодействия.
Внимание! Примеры, приведенные в данном разделе, не являются законченными, а служат лишь для иллюстрации работы описываемых механизмов.
Для доступа к программному интерфейсу системы взаимодействия предназначен менеджер системы взаимодействия, который представлен свойством глобального контекста СистемаВзаимодействия. Для вызова какого-либо метода следует указывать СистемаВзаимодействия.ИмяМетода(). Однако для упрощения текста, во время описания того или иного метода префикс СистемаВзаимодействия. будет опускаться. Примеры, естественно, будут содержать корректный синтаксис вызова.
29.4.2. Регистрация/отмена регистрации приложения
Для выполнения регистрации приложения на сервере системы взаимодействия служат методы НачатьРегистрациюИнформационнойБазы(), ВыполнитьРегистрациюИнформационнойБазыАсинх() и ВыполнитьРегистрациюИнформационнойБазы(). Первые два метода работают на стороне клиентского приложения и является асинхронными. Последний метод выполняется на стороне сервера и является синхронным.
Все методы получают на вход параметры регистрации (объекта ПараметрыРегистрацииИнформационнойБазыСистемыВзаимодействия), а возвращают результат регистрации (объект РезультатРегистрацииИнформационнойБазыСистемыВзаимодействия). Получение результат работы зависит от используемого метода:
● Для варианта с обратным вызовом: в метод НачатьРегистрациюИнформационнойБазы() требуется передать ссылку на обработчик оповещения (объект ОписаниеОповещения), в который будет передан результат регистрации.
● Для варианта с обещанием: результат регистрации будет результатом выполнения обещания, которое возвращает метод ВыполнитьРегистрациюИнформационнойБазыАсинх().
● Для серверного вызова: результат регистрации будет результатом работы метода.
В объекте РезультатРегистрацииИнформационнойБазыСистемыВзаимодействия статус регистрации отображается свойством РегистрацияВыполнена, а если регистрация не завершена, то свойство ТекстСообщения содержит информацию для пользователя.
Собственно регистрация выполняется за несколько шагов:
1. На первом шаге на сервер системы взаимодействия передаются параметры регистрируемого приложения. Для этого необходимо заполнить свойства АдресЭлектроннойПочты и АдресСервера объекта ПараметрыРегистрацииИнформационнойБазыСистемыВзаимодействия и вызвать метод НачатьРегистрациюИнформационнойБазы()/ВыполнитьРегистрациюИнформационнойБазыАсинх()/ВыполнитьРегистрациюИнформационнойБазы().
2. На следующем шаге сервер системы взаимодействия присылает на адрес электронной почты, который был указан на предыдущем шаге, письмо с кодом активации.
3. На последнем шаге необходимо повторить вызов метода НачатьРегистрациюИнформационнойБазы()/ВыполнитьРегистрациюИнформационнойБазыАсинх()/ВыполнитьРегистрациюИнформационнойБазы(), но кроме свойств АдресЭлектроннойПочты и АдресСервера, следует заполнить также свойство КодАктивации. В это свойство следует поместить значение, которое пришло в электронном письме от сервера системы взаимодействия.
В качестве адреса сервера системы взаимодействия может выступать адрес сервера 1cDialog.com (wss://1cdialog.com:443) или адрес самостоятельно развернутого сервера системы взаимодействия. Документация по развертыванию сервера системы взаимодействия находится по адресу https://its.1c.ru/db/csdoc.
4. Если никаких ошибок не происходило, то к этому моменту регистрация успешно завершена. Если при вызовах метода регистрации происходили какие-либо ошибки, то информация для пользователя будет передана в свойстве ТекстСообщения объекта РезультатРегистрацииИнформационнойБазыСистемыВзаимодействия. Способ получения объекта с результатом регистрации зависит от используемого метода регистрации. После окончания регистрации сформированы и сохранены все криптографические ключи, которые необходимы для работы с системой взаимодействия.
В завершение процесса регистрации система взаимодействия пришлет письмо, которое будет содержать ключ администрирования. Это значение является конфиденциальной информацией и позволяет выполнять некоторые операции, не являясь администратором абонента. Подробнее об этом параметре см. здесь.
Свойство ПараметрыРегистрацииИнформационнойБазыСистемыВзаимодействия.ИмяИнформационнойБазы служит для того, чтобы указать представление регистрируемого приложения.
Чтобы отказаться от регистрации приложения в сервисе, следует использовать методы НачатьОтменуРегистрацииИнформационнойБазы(), ОтменитьРегистрациюИнформационнойБазыАсинх() или ОтменитьРегистрациюИнформационнойБазы().
После успешного завершения работы метода пользователи текущего приложения не смогут пользоваться системой взаимодействия. В частности, будут удалены все необходимые криптографические ключи. Однако если выполнить повторную регистрацию приложения на тот же адрес электронной почты, то работа с системой взаимодействия будет восстановлена и будет восстановлен доступ ко всей переписке, которая была сформирована до отключения. Повторную регистрацию можно выполнить двумя способами:
1. Обычным способом, с явным указанием электронной почты. В этом случае надо понимать, что указание электронной почты отличной от той, что была указана во время предыдущей регистрации, приведет к тому, что будет утрачен доступ ко всем объектам системы взаимодействия, которые были сформированы до отключения. Фактически, это будет регистрация нового приложения.
2. Без указания электронной почты. В этом случае для регистрации будет использован адрес электронной почты, который использовался при первом подключении информационной базы. На этот адрес будет выслан код активации. Такой способ можно использовать, если утеряна информация о том, какой адрес электронной почты использовался для регистрации, но есть уверенность, что этот адрес в данный момент доступен. Тогда получение письма с кодом активации позволит, во-первых, восстановить подключение к системе взаимодействия и, во-вторых, узнать адрес электронной почты, на который выполнялась активация. Если текущая информационная база ранее не подключалась к системе взаимодействия, то повторное подключение без указания электронной почты не будет выполнено.
Для полного отключения приложение от сервиса взаимодействия (включая потерю доступа ко всей переписке, сформированной при работе в приложении), следует воспользоваться методом УстановитьДанныеРегистрацииИнформационнойБазы(), куда в качестве данных регистрации передать значение Неопределено. После выполнения такого действия регистрация приложения отменяется, и доступ к сообщениям теряется безвозвратно.
У метода УстановитьДанныеРегистрацииИнформационнойБазы() существует парный метод (ПолучитьДанныеРегистрацииИнформационнойБазы()), который позволяет получить всю информацию о подключении к серверу системы взаимодействия в виде единого объекта. Данный объект содержит всю информацию, которая указывалась при регистрации, а также все криптографические ключи, которые используются для работы с сервером системы взаимодействия. Если передать эти данные в качестве параметра метода УстановитьДанныеРегистрацииИнформационнойБазы(), то система взаимодействия будет считать приложение, в которой было выполнено это действие, полностью эквивалентной тому приложению, в котором были получены данные, использованные для установки. Поэтому основное предназначение пары методов Получить/УстановитьДанныеРегистрацииИнформационнойБазы() ‑ это миграция области данных между различными базами данных.
Последнее, о чем стоит упомянуть в контексте регистрации приложения в сервисе взаимодействия, это получение различной информации о самом сервере взаимодействия и его «отношениях» с текущей информационной базой. Для этого существуют следующие методы:
|
Метод |
Описание |
|
|
Возвращает адрес сервера системы взаимодействия, на котором зарегистрирована информационная база. |
|
|
Возвращает адрес электронной почты, на который была выполнена регистрация информационной базы. |
|
|
Возвращает версию сервера системы взаимодействия, на котором зарегистрирована информационная база. |
|
|
Проверяет, что приложение зарегистрировано в сервисе и эта регистрация не отключена. |
|
|
Проверяет, что приложение зарегистрировано в сервисе, регистрация не отключена и в приложении есть пользователи. |
|
|
Позволяет проверить, что текущий пользователь системы взаимодействия является администратором абонента. |
|
|
Позволяет изменить адрес электронной почты, который использовался при регистрации абонента. Для выполнения операции необходимо быть администратором абонента. |
29.4.3. Работа с пользователями
29.4.3.1. Общая информация
При работе с пользователями следует понимать, что в системе взаимодействия могут существовать различные виды пользователей. Кратко перечислим эти виды:
● Обычные пользователи. Это пользователи, которые образуются в результате подключения к системе взаимодействия пользователей информационной базы прикладного решения. Такого пользователя можно идентифицировать с помощью свойства ИдентификаторПользователяИнформационнойБазы.
Обычные пользователи обеспечивают работоспособность ботов системы взаимодействия (объект БотСистемыВзаимодействия). С ботом может быть связано два пользователя системы взаимодействия, один из которых необходим для того, чтобы бот мог участвовать в обсуждениях. Этого пользователя можно получить с помощью свойства БотСистемыВзаимодействия.Пользователь. Другой пользователь предназначен для указания прав бота на данные информационной базы (свойство БотСистемыВзаимодействия.ИмяПользователяИнформационнойБазыВыполненияОбработки). Более подробная информация о ботах системы взаимодействия см. здесь.
● Пользователи интеграции. Эти пользователи образуются в результате интеграции системы взаимодействия с различными мессенджерами и вызова вебхуков. Такой пользователь идентифицируется с помощью свойств ТипВнешнейСистемы и ИдентификаторПользователяВнешнейСистемы.
● Внешние пользователи. Эти пользователи появляются в том случае, когда к системе взаимодействия интерактивно подключается пользователь, который не является обычным пользователем и пользователем интеграции. Непосредственно создание такого пользователь системы взаимодействия выполняется перед тем, как сторонний пользователь получает приглашение для доступа к системе взаимодействия через специальный интернет-сайт. Внешний пользователь может быть идентифицирован по установленным свойствам Внешний и АндресЭлектроннойПочтыДляАутентификации.
● Гостевые пользователи. Эти пользователи являются подмножеством внешних пользователей. Такие пользователи создаются системой взаимодействия автоматически в том случае, если пользователь подключается с помощью ссылки-приглашения на конкретное обсуждение или видеозвонок. С помощью встроенного языка нельзя создать гостевого пользователя.
Смотри также:
● Взаимодействие «человек-машина» (см. здесь).
● Интеграция с внешними системами (см. здесь).
● Внешние пользователи (см. здесь).
29.4.3.2. Создание и обновление пользователей системы взаимодействия
После того, как выполнена регистрация приложения в сервисе взаимодействия, можно выполнить синхронизацию списка пользователей между пользователями приложения и пользователями системы взаимодействия. Для выполнения этой операции платформа предоставляет целый набор методов.
Текущий пользователь уже создан в системе взаимодействия ‑ это происходит автоматически, при первом интерактивном входе в систему «1С:Предприятие» после регистрации приложения в сервисе. Но может потребоваться перенести всех существующих пользователей приложения в сервис сразу после регистрации. Для этого следует воспользоваться методом СоздатьПользователя(). В качестве параметра метода выступает объект ПользовательИнформационнойБазы. Для получения списка пользователей информационной базы можно использовать метод ПользователиИнформационнойБазы.ПолучитьПользователей().
Пример:
УстановитьПривилегированныйРежим(Истина); ПользователиИБ = ПользователиИнформационнойБазы.ПолучитьПользователей(); Для каждого ПользовательИБ Из ПользователиИБ Цикл Попытка ИдентификаторПользователяСВ = СистемаВзаимодействия.ПолучитьИдентификаторПользователя(ПользовательИБ.УникальныйИдентификатор); Исключение ПользовательСВ = СистемаВзаимодействия.СоздатьПользователя(ПользовательИБ); // возможно дозаполнение свойств пользователя системы взаимодействия ПользовательСВ.Записать(); КонецПопытки; КонецЦикла; УстановитьПривилегированныйРежим(Ложь);
В данном примере выполняется попытка получения идентификатора пользователя системы взаимодействия для каждого пользователя приложения. Если пользователь приложения еще не создавался в системе взаимодействия ‑ будет сгенерировано исключение. В этом случае на основании пользователя приложения будет создан пользователь системы взаимодействия.
При работе с пользователями системы взаимодействия следует обратить внимание на свойство КлючСопоставления. Данное свойство может использовать для сопоставления пользователей при объединении приложений. При работе с пользователями системы взаимодействия следует обратить внимание еще на одно полезное свойство: ИдентификаторПользователяИнформационнойБазы. Данное свойство содержит уникальный идентификатор пользователя информационной базы, который можно использовать для поиска пользователя ПользователиИнформационнойБазы.НайтиПоУникальномуИдентификатору(). Когда свойство ИдентификаторПользователяИнформационнойБазы установлено в значение Неопределено, то это означает, что пользователь информационной базы, соответствующий пользователю системы взаимодействия, был удален из информационной базы. Повторно (после создания пользователя системы взаимодействия) сопоставить пользователя информационной базы и пользователя системы взаимодействия можно при наличии права АдминистрированиеДанных у пользователя, от имени которого выполняется новое сопоставление.
Если прикладное решение интегрируется с какой-либо внешней системой, то свойство ПользовательСистемыВзаимодействия.ТипВнешнейСистемы позволит определить, что пользователь создан модулем интеграции и является внешним по отношению к прикладному решению. Идентификатор внешнего пользователя в «своей» системе можно узнать с помощью свойства ПользовательСистемыВзаимодействия.ИдентификаторПользователяВнешнейСистемы. Для внешнего пользователя недоступна возможность видеозвонка и личного сообщения. Состав информации, связанной с пользователем, определяется внешней системой. Разные внешние системы могут предоставлять разный набор информации.
Когда пользователю информационной системы необходимо запретить использование системы взаимодействия, можно воспользоваться свойством ПользовательСистемыВзаимодействия.Заблокирован. Такая потребность может возникнуть, например, в том случае, когда пользователь уволился из компании, где использовалась система взаимодействия. Если пользователь системы взаимодействия заблокирован, то такой пользователь:
● Не может устанавливать соединение с сервером системы взаимодействия.
● Перестает получать уведомления.
● Не отображается в подборе пользователей системы взаимодействия.
● Такому пользователю нельзя сделать видеозвонок.
● Отображается с использованием специального значка.
● При отправке сообщения такому пользователю, добавлению его в список участников обсуждения или в видеоконференцию, возникает исключение.
Признак того, что пользователь является абонентом системы взаимодействия, служит свойство АдминистраторАбонента. При модификации пользователя это свойство недоступно на запись.
Смотри также:
● Совместное использование приложений (см. здесь).
● Интеграция с внешними системами (см. здесь).
● Права доступа (см. здесь).
● Работа с администраторами абонента (см. здесь).
29.4.3.3. Выбор пользователей системы взаимодействия
29.4.3.3.1. Общая информация
При указании пользователя в системе взаимодействия, платформа предоставляет возможность управлять этим процессом. Для этого предоставляется обработчик события АвтоПодборПользователейСистемыВзаимодействия. Этот обработчик события может располагаться в модуле формы клиентского приложения или в модуле приложения. Имеется возможность реализовать собственную форму выбора пользователей системы взаимодействия. Для этого существует обработчик события ОбработкаПолученияФормыВыбораПользователейСистемыВзаимодействия. Этот обработчик также может располагаться в модуле формы клиентского приложения или модуле приложения. Также, для указания формы выбора пользователей системы взаимодействия можно использовать свойство конфигурации ОсновнаяФормаВыбораПользователейСистемыВзаимодействия.
Система позволяет обработать выбор пользователя в следующих случаях:
● выбор получателя сообщения в обсуждении;
● выбор участника обсуждения в неконтекстном обсуждении;
● выбор участника видеоконференции.
Назначение выбора пользователей описывается системным перечислением НазначениеВыбораПользователейСистемыВзаимодействия. Значение данного перечисления передается в обработчики событий автоподбора пользователя и выбора формы в параметре НазначениеВыбора. С его помощью разработчик может понять, где выполняется то или иное действие.
Общая схема выбора пользователя выглядит следующим образом:
● При создании нового сообщения, пользователь начинает вводить имя своего корреспондента. При этом срабатывает событие автоподбора пользователя системы взаимодействия. Выбранные пользователи отображается в виде списка выбора у поля ввода имени пользователя.
● После того, как сформирован список выбора, платформа определяет, существует в данном прикладном решении специальная форма выбора пользователей системы взаимодействия. Если такая форма есть, то она отображается в виде гиперссылки Показать все в нижней части выпадающего списка пользователей. Определение формы выбора выполняется с помощью специального события, а также свойства конфигурации.
● Из списка выбора можно выбрать одного пользователя, а из формы выбора ‑ сразу несколько. Выбранные пользователи попадают в соответствующее поле ввода и выбор завершается. Можно начинать выбирать нового пользователя.
29.4.3.3.2. Определение списка пользователей
Более подробно рассмотрим последовательность событий, возникающих при вводе пользователей:
1. Выполняется вызов обработчика события АвтоПодборПользователейСистемыВзаимодействия формы клиентского приложения. Обработчик данного события может быть вызван только в том случае, если происходит выбор адресата в контекстном обсуждении.
На вход обработчик получает сформированный системой список пользователей. Данный список может быть модифицирован или полностью заменен.
Если при завершении обработчика параметр СтандартнаяОбработка установлен в значение Ложь, то платформа будет использовать тот список пользователей, который получен из данного обработчика. Если параметр СтандартнаяОбработка имеет значение Истина ‑ будет вызван обработчик автоподбора из модуля приложения (следующий шаг).
2. Выполняется вызов обработчика события АвтоПодборПользователейСистемыВзаимодействия модуля клиентского приложения.
На вход обработчик получает список пользователей, который сформирован системой или обработчиком события АвтоПодборПользователейСистемыВзаимодействия формы клиентского приложения. Данный список может быть модифицирован или полностью заменен.
Для формирования выпадающего списка пользователей система будет использовать в точности тот список пользователей, который получен из данного обработчика.
В обработку автоподробра пользователей передаются следующие параметры:
● Текст, введенный пользователем (параметр Текст).
● Список пользователей системы взаимодействия, которых по введенному тексту выбрала сама платформа (параметр ДанныеВыбора). Разработчик может переопределить данный список.
● Для чего выполняется подбор пользователей (параметр НазначениеВыбора).
● Описание формы клиентского приложения, в которой расположено контекстное обсуждение, для которого выполняется подбор получателей сообщения (параметр Форма).
● Идентификатор обсуждения, в которое добавляются пользователи (параметр Обсуждение).
Данные, которые находятся в параметре обработчика события ДанныеВыбора после выхода из обработчика, будут использованы в дальнейшей цепочке обработчиков или непосредственно системой взаимодействия.
В качестве значения параметра ДанныеВыбора выступает список значений. В качестве значения элемента этого списка может выступать:
● Значение типа ИдентификаторПользователяСистемыВзаимодействия. Если значение данного типа будет «пустым», то при формировании списка получателей сообщения контекстного обсуждения, такое значение будет интерпретироваться как Никого не оповещать. В остальных случаях такое значение будет игнорироваться. «Пустое» значение типа ИдентификаторПользователяСистемыВзаимодействия можно сформировать с помощью конструктора объекта ИдентификаторПользователяСистемыВзаимодействия без параметров.
● Значение типа УникальныйИдентификатор. Платформа будет «считать», что это идентификатор пользователя информационной базы. По данному идентификатору будет выполнен поиск пользователя системы взаимодействия.
● Массив значений типа ИдентификаторПользователяСистемыВзаимодействия или УникальныйИдентификатор. В этом случае в списке выбора формируется «группа» пользователей, для которой можно задать свое представление. В качестве примера можно отметить группировку пользователей по функциональному признаку: в группе Продавцы будут перечислены все пользователи, которые выполняют функцию продавцов. В этом случае выбор группы приведет к добавлению в список получателей сразу большого количества пользователей, без необходимости выбора каждого пользователя по одному.
Если для элемента списка значений задана картинка ‑ она будет выводиться в списке выбора. Если картинка не задана, то в случае массива будет выводиться картинка группы пользователей, а для конкретных пользователей будет выводиться картинка заданного пользователя.
Представление элемента списка значений задается или в соответствующем свойстве элемента списка значения или формируется системой автоматически:
● Для конкретного значения будет выводиться полное имя пользователя.
● Для группы ‑ полные имена пользователей, входящих в группу, разделенные запятой.
29.4.3.3.3. Определение формы выбора пользователей
После того, как сформирован выпадающий список пользователей, система определяет, существует в прикладном решении форма выбора пользователей системы взаимодействия. Это определение выполняется после каждого формирования списка пользователей. Для этого используется следующая последовательность действий:
1. Выполняется вызов обработчика события ОбработкаПолученияФормыВыбораПользователейСистемыВзаимодействия модуля формы клиентского приложения. Обработчик данного события может быть вызван только в том случае, если происходит выбор адресата в контекстном обсуждении.
Для указания имени формы выбора служит параметр обработчика ВыбраннаяФорма. Дальнейшее поведение, как обычно, зависит от значения параметра обработчика СтандартнаяОбработка:
● Параметр имеет значение Истина: вызывается обработчик выбора формы модуля приложения.
● Параметр имеет значение Ложь: платформа использует в качестве формы выбора пользователей системы взаимодействия ту форму, которая указана в параметре ВыбраннаяФорма.
2. Выполняется вызов обработчика ОбработкаПолученияФормыВыбораПользователейСистемыВзаимодействия модуля приложения.
Поведение обработчика подобно поведению аналогичного обработчика модуля формы. Однако имеется отличие, которое заключается в следующем: указание в данном обработчики значения Истина для параметра СтандартнаяОбработка приведет к тому, что система попытается использовать в качестве формы выбора пользователей форму, которая указана в свойстве конфигурации ОсновнаяФормаВыбораПользователейСистемыВзаимодействия. Если это свойство конфигурации не указано ‑ форма выбора пользователя системы взаимодействия не будет использована. Это означает, что в выпадающем списке пользователей не будет гиперссылки Показать все.
В процедуру обработки события выбора формы выбора пользователей системы взаимодействия передаются следующие параметры:
● Для чего выполняется подбор пользователей (параметр НазначениеВыбора).
● В какой форме расположено контекстное обсуждение, если происходит подбор получателей сообщения (параметр Форма).
● Идентификатор обсуждения, в которое добавляются пользователи (параметр Обсуждение).
● Параметры, которые будут использованы для открытия формы выбора пользователей системы взаимодействия (параметр Параметры). Платформа формирует в данной структуре следующие параметры:
● Параметр РежимВыбора установлен в значение Истина.
● Параметр МножественныйВыбор установлен в значение Истина.
● Параметр ЗакрыватьПриЗакрытииВладельца установлен в значение Истина.
● Форма, которая будет использоваться для выбора пользователей системы взаимодействия (параметр ВыбраннаяФорма). Если данный параметр при выходе из обработчика не равен пустой строке ‑ в списке подбора пользователей системы взаимодействия добавляется гиперссылка Показать все и при нажатии на эту гиперссылку открывается выбранная форма. Параметры открытия формы задаются значением параметра Параметры обработчика и могут быть модернизированы в обработчике определения формы выбора. Владельцем открываемой формы выбора будет указана форма, в которой отображается обсуждение.
Форма выбора, используемая для выбора пользователей системы взаимодействия, должна возвращать выбранных пользователей в качестве параметра метода Закрыть(). В качестве параметра метода Закрыть() может выступать:
● Значение типа ИдентификаторПользователяСистемыВзаимодействия.
● Значение типа УникальныйИдентификатор. Платформа будет «считать», что это идентификатор пользователя информационной базы. И по данному идентификатору будет выполнен поиск пользователя системы взаимодействия.
● Массив из значений вышеперечисленных типов.
29.4.3.4. Указание пользователя для авторизации
Как уже было сказано ранее, для работы с системой взаимодействия, клиентское приложение должно авторизоваться в системе взаимодействия. Однако, в системе «1С:Предприятие» есть ситуация, когда «клиентское приложение» работает от имени служебного пользователя системы (пользователь по умолчанию). Эта ситуация возникает в том случае, если запуск фонового задания, реализующего регламентное задание, выполняется планировщиком системы. Очевидно, что в таком случае код фонового задания не может подключиться к системе взаимодействия и не может выполнять необходимые действия (создавать сообщения, получать обсуждения и т. д.).
В этой ситуации можно использовать специальный метод УстановитьТекущегоПользователя() менеджера системы взаимодействия. При вызове данного метода, сеанс, в котором выполняется фоновое задание, подключается к системе взаимодействия от имени пользователя, переданного в качестве параметра метода.
Следует помнить, что данный метод может быть вызван только в том случае, когда сеанс, в котором вызывается этот метод, работает от имени пользователя по умолчанию.
29.4.3.5. Работа со списком администраторов абонента
Система взаимодействия предоставляет возможность изменять список администраторов абонента. Добавить пользователя в список администраторов можно с помощью метода ДобавитьВАдминистраторыАбонента(). Исключить пользователя из списка администраторов абонента можно с помощью метода ИсключитьИзАдминистраторовАбонента().
Оба этих метода могут быть выполнены от лица администратора текущего абонента ‑ в этом случае необходимо указать только идентификатор пользователя, с которым будет выполняться операция. Если операция выполняется пользователем, который не является администратором абонента, то кроме идентификатора пользователя необходимо указать еще один параметр, ключ администрирования.
Ключ администрирования ‑ это конфиденциальная информация, которая высылается пользователю (см. здесь), который регистрировал абонента на сервере системы взаимодействия, и позволяет использовать его как «пароль администратора». Ключ администрирования хранится только на сервере системы взаимодействия. Для каждого абонента существует свой ключ администрирования.
Администратор абонента может перевыпустить ключ администрирования с помощью метода ПолучитьНовыйКлючАдминистрирования(). Старый в этот момент перестает действовать.
Также имеется возможность получить временный код администрирования с помощью метода ОтправитьВременныйКод(). Эту операцию может выполнить любой пользователь системы. Временный код администрирования отправляется на адрес электронной почты, который использовался для регистрации абонента. Временный код администрирования выдается на 24 часа или до первого использования, в зависимости от того, что случится раньше. При выдаче временного кода администрирования постоянный ключ администрирования никак не изменяется и не модифицируется.
Таким образом, для того, чтобы иметь возможность выполнения административных функций с абонентом, необходимо иметь одну из следующих возможностей: войти в систему от имени действующего администратора абонента, знать ключ администрирования абонента или иметь доступ к электронной почте, на который выполнялась регистрация абонента. Из этого следует, что после того, как система «1С:Предприятие» и сервер системы взаимодействия обновятся до версии 8.3.24 или последующих версий ‑ настоятельно рекомендуется сформировать ключ администрирования абонента и обеспечить этому ключу надежное хранение.
29.4.4. Работа с обсуждениями
29.4.4.1. Базовые возможности
Для работы с обсуждением необходимо это обсуждение создать. Для этого предназначен метод СоздатьОбсуждение(). В результате работы метода создается объект, с помощью которого имеется возможность настраивать обсуждение и работать с ним. Созданное обсуждение еще не записано. Для записи следует явным образом вызвать метод Записать() созданного объекта. Рассмотрим некоторые свойства создаваемого обсуждения.
Свойство Идентификатор необходимо для однозначной идентификации обсуждения. В частности, для создания сообщения (методом СоздатьСообщение()) необходимо знать, в какое обсуждение это сообщение попадет. Идентификация обсуждения выполняется с помощью свойства Идентификатор.
Свойство Ключ позволяет использовать для идентификации обсуждения любой уникальный идентификатор, который, например, можно предусмотреть заранее. Так, если обсуждение используется для коммуникации между сервером и клиентом, то для идентификации требуемого обсуждения можно создать ключ обсуждения на этапе разработки прикладного решения, и потом везде использовать этот ключ для получения обсуждения. Ключ обсуждения нельзя изменить для уже записанного обсуждения.
Существенное отличие между свойствами Идентификатор и Ключ заключается в том, что Идентификатор становится известен в момент записи обсуждения, а Ключ можно определить заранее, до записи обсуждения.
Свойство ВнешнийИдентификатор используется в том случае, когда создается новое обсуждение с внешней системой. Запись объекта с установленным свойством ВнешнийИдентификатор возможно только в привилегированном режиме. Установка свойства имеет смысл только в интеграциях с WhatsApp и Webhook. Для интеграции с WhatsApp такая возможность позволит системе «1С:Предприятие» начать общение какой-либо шаблонной фразой, не дожидаясь действий со стороны абонента. В зависимости от внешней системы, свойство может принимать следующие значения:
● WhatsApp ‑ номер телефона внешнего участника (в международном формате, без префикса «+»). Подробнее см. здесь.
● Webhook ‑ идентификатор обсуждения, который был указан при создании обсуждения методом createConversation.
● Telegram, ВКонтакте и MAX ‑ идентификатор чата (с которым обменивается сообщениями обсуждение с указанным значением свойства ВнешнийИдентификатор) в этих системах.
Управление доступностью обсуждения для интерактивной работы с ним выполняется с помощью свойства Отображаемое. Если данное свойство установлено в значение Истина, то такое обсуждение будет доступно в основной форме обсуждений и пользователи смогут работать с этим обсуждением. Соответственно, если свойство установлено в значение Ложь, то такое обсуждение будет недоступно для интерактивной работы и доступ к такому обсуждению будет возможен только через программный интерфейс. Контекстное обсуждение следует всегда создавать так, чтобы свойство Отображаемое было установлено в значение Истина.
Свойство ТолькоПросмотр позволяет создать обсуждение, которое может изменяться только с помощью встроенного языка. Это свойство может быть установлено только для нового обсуждения и требует наличия права АдминистрированиеДанных (или привилегированного режима) у пользователя, от имени которого выполняется код на встроенном языке. В обсуждении, которе создано в режиме «только для чтения», невозможно интерактивно выполнять следующие действия: создание, изменение и удаление сообщений; изменение темы обсуждения; покидание обсуждения; изменение состава участников обсуждения.
Свойство КонтекстОбсуждения управляет тем, какой вид обсуждения будет создаваться: контекстное или неконтекстное. Данное свойство доступно для записи только для нового обсуждения. После записи сменить тип обсуждения уже невозможно. Также надо помнить, что у объекта может быть только одно контекстное обсуждение.
Когда создается неконтекстное обсуждение, свойство Групповое позволяет указать, какое количество участников будет у обсуждения. Если свойство Групповое установлено в значение Истина, то у обсуждения может быть произвольное количество участников. Если это свойство установлено в значение Ложь, то участников всегда два: автор обсуждения и один его собеседник.
С помощью свойства Участники задается перечень пользователей, которые будут иметь доступ к созданному неконтекстному(!) обсуждению. Список участников одного неконтекстного обсуждения ограничен 3 000 пользователей. Исключением является случай, когда в качестве списка участников будет задано значение СистемаВзаимодействия.СтандартныеПользователи.ВсеПользователиПриложения. Тогда к такому обсуждению будут иметь доступ все пользователи. Если состав участников не задан для неконтекстного обсуждения, то оно будет недоступно для всех пользователей системы. Доступ к контекстному обсуждению регулируется правом Чтение на объект контекста (свойство КонтекстОбсуждения). При создании контекстного обсуждения значение свойства Участники устанавливать не следует. При создании обсуждения «один на один»:
● не допускается использование значения СистемаВзаимодействия.СтандартныеПользователи.ВсеПользователиПриложения в списке участников;
● размер списка участников должен быть равен 2.
Как уже было сказано выше, для того, чтобы создать сообщение ‑ необходимо знать идентификатор обсуждения, в которое данное сообщение попадет. Метод СоздатьСообщение() формирует объект, который необходимо заполнить данными и записать. Для созданного сообщения свойства Дата и Автор заполняются автоматически. Для изменения этих свойств требуется переход в привилегированный режим. После записи новое сообщение будет «отправлено» участникам. Более подробно рассмотрим свойства сообщения.
Свойство Идентификатор является уникальным идентификатором созданного сообщения. Позволяет уникально идентифицировать каждое сообщение в системе.
Свойство Обсуждение прикрепляет сообщение к какому-либо существующему обсуждению. Невозможно создать сообщение, которое не связано с каким-либо обсуждением.
Свойство Данные позволяет прикрепить к сообщению произвольные данные. У этих данных имеется два ограничения: прикрепляемые данные должны поддерживать XDTO-сериализацию и объем данных в сериализованном виде не может превышать 100 Кбайт. Это свойство недоступно из пользовательского интерфейса. Данное свойство имеет смысл использовать в том случае, когда обсуждение используется как технологическое, для взаимодействия различных подсистем прикладного решения. Для передачи могут быть использованы следующие типы данных: Картинка; ДвоичныеДанные; Строка; значение системы «1С:Предприятие», поддерживающее XDTO-сериализацию. Если в свойство Данные помещается значение типа Строка, то в поле ФорматДанныхСтроки можно указать тип MIME для переданного значения.
С помощью свойства Получатели предоставляется возможность задавать, какие пользователи получат оповещение о сообщении для отображаемого контекстного сообщения. Это свойство не определяет доступность сообщения!
Если сообщение отправляется в отображаемое обсуждение, то с помощью свойства Действия можно задать перечень «команд», которые будут отображаться в форме сообщения. Выбор таких команд будет приводить к переходу по гиперссылке или к вызову соответствующего клиентского обработчика. С помощью этой возможности можно, например, реализовывать фиксированный список ответов робота в специальном обсуждении.
Следует помнить, что во всех случаях, когда требуется указание ссылки на обсуждение (при создании сообщения, при подключении какого-либо обработчика и т. д.), это обсуждение должно существовать к моменту указания ссылки. При этом не важно, каким образом будет выполняться идентификация обсуждения. Важно, что моменту выполнения требуемого действия, обсуждение, на которое требуется ссылка, уже существовало в базе данных системы взаимодействия.
29.4.4.2. Поиск обсуждений и сообщений
В процессе работы может возникать необходимость поиска (или получения) какого-либо конкретного обсуждения. Например, через обсуждение с известным ключом выполняется передача данных о длительном процессе, выполняемом на сервере. Получение конкретного обсуждения может выполняться несколькими способами:
1. По идентификатору обсуждения (метод ПолучитьОбсуждение()). В этом случае получается конкретное обсуждение.
2. По ключу обсуждения (другой вариант метода ПолучитьОбсуждение()). В этом случае также получается конкретное обсуждение.
3. С помощью отбора (метод ПолучитьОбсуждения()). В этом случае получается список обсуждений, которые соответствуют критериям отбора. Результат выполнения метода может включать и несколько обсуждений и их пустой список.
4. Получение контекстного обсуждения какого-либо объекта. Для этого используется метод НачатьПолучениеОбсуждения() формы клиентского приложения.
Также система предоставляет возможность получения списка сообщений по некоторым критериям. Для этого предназначен метод ПолучитьСообщения(). Результатом выполнения метода выступает массив сообщений, которые удовлетворяют указанным (в параметре отбора) критериям.
Смотри также:
● Поиск объектов системы взаимодействия (см. здесь).
29.4.4.3. Установка действий в сообщение
29.4.4.3.1. Общая информация
Система взаимодействия позволяет отображать наборы кнопок в сообщениях. Это касается как сообщений самой системы взаимодействия, так и сообщений, которые отправляются в различные системы, которые интегрированы с системой взаимодействия: ВКонтакте, Telegram, WhatsApp, MAX, чат на сайте.
Панель кнопок это несколько экранных кнопок, имеющих различный способ отображения и вызывающих выполнение различных действий при нажатии пользователем на эти кнопки. Панель кнопок может быть сформирована только из встроенного языка. Действия, связанные с кнопками панели, могут быть обработаны как на стороне клиентского приложения, так и на стороне сервера системы «1С:Предприятие» (в модуле бота системы взаимодействия). Отображение панели кнопок в системе взаимодействия может отличаться от отображения этой же панели кнопок в каком-либо мессенджере. Это связано с тем, что типы кнопок, правила видимости и отображения кнопок мессенджера могу отличаться от таковых в системе взаимодействия.
Предыдущий механизм установки действий в сообщениях признан устаревшим. Он не рекомендуется для использования . Документация по этому механизму находится в документации к «1С:Предприятие» версии 8.3.24 и предыдущих версиях (https://its.1c.ru/db/v8324doc/bookmark/dev/TI000001963). Для замены механизма установки действий панелью кнопок, следует для кнопок, в качестве действий устанавливаться значение ДействиеКнопкиПанелиКнопокСообщенияСистемыВзаимодействия.ОбработатьНаКлиенте.
29.4.4.3.2. Работа с панелью кнопок
Для работы с панелью кнопок предназначено свойство ПанельКнопок объекта СообщениеСистемыВзаимодействия. Это свойство дает доступ к объекту ПанельКнопокСообщенияСистемыВзаимодействия. Наполнение панели кнопок выполняется с помощью свойства РядыКнопок данного объекта, через которое доступна коллекция кнопок (типа РядыКнопокПанелиКнопокСообщенияСистемыВзаимодействия). Кнопки добавляются с помощью рядов, в которых расположены сами кнопки. Таким образом, образуется матрица, где по горизонтальной оси будут кнопки, а по вертикальной ‑ ряды кнопок. Количество кнопок в разных рядах может не совпадать.
Рассмотрим пример добавления для сообщения 4 кнопок (по 2 кнопки в 2 рядах):
Сообщение = СистемаВзаимодействия.СоздатьСообщение(СсылкаНаОбсуждение); Ряд1 = Сообщение.ПанельКнопок.РядыКнопок.Добавить(); Кнопка11 = Ряд1.Добавить(ДействиеКнопкиПанелиКнопокСообщенияСистемыВзаимодействия.ОтправитьСообщение, "Кнопка 1 1"); Кнопка11.ТекстСообщения = "Текст 1 1"; Кнопка12 = Ряд1.Добавить(ДействиеКнопкиПанелиКнопокСообщенияСистемыВзаимодействия.ОтправитьСообщение, "Кнопка 1 2"); Кнопка12.ТекстСообщения = "Текст 1 2"; Ряд2 = Сообщение.ПанельКнопок.РядыКнопок.Добавить(); Кнопка21 = Ряд2.Добавить(ДействиеКнопкиПанелиКнопокСообщенияСистемыВзаимодействия.ОтправитьСообщение, "Кнопка 2 1"); Кнопка21.ТекстСообщения = "Текст 2 1"; Кнопка22 = Ряд2.Добавить(ДействиеКнопкиПанелиКнопокСообщенияСистемыВзаимодействия.ОтправитьСообщение, "Кнопка 2 2"); Кнопка22.ТекстСообщения = "Текст 2 2"; Сообщение.Записать();
В этом примере в обсуждение (переменная СсылкаНаОбсуждение) будет добавлено сообщение с 4 кнопкам: Кнопка 1 1, Кнопка 1 2, Кнопка 2 1 и Кнопка 2 2. Каждая кнопка панели представлена своим объектом типа КнопкаПанелиКнопокСообщенияСистемыВзаимодействия. Нажатие любой из добавленных кнопок будет приводить к отправке сообщения, текст которого указывается в соответствующем свойстве каждой добавляемой кнопки. Очевидно, что для реального применения нужно как-то управлять тем, какое действие будет порождать кнопка при ее нажатии пользователем.
Для этого служит первый параметр метода РядКнопокПанелиКнопокСообщенияСистемыВзаимодействия.Добавить(). Само действие указывается с помощью значения системного перечисления ДействиеКнопкиПанелиКнопокСообщенияСистемыВзаимодействия:
|
Значение |
Описание |
|
|
Нажатие на кнопку создаёт сообщение с запросом текущего местоположением пользователя. Действие не доступно в тонком, толстом, веб-клиенте, но доступно в мобильном клиенте и для использования в интеграциях с мессенджерами. |
|
|
Нажатие на кнопку создаёт сообщение с запросом контактной информацией (телефоном) пользователя. Действие не доступно в тонком, толстом, веб-клиенте, но доступно в мобильном клиенте и для использования в интеграциях с мессенджерами. |
|
|
Нажатие на кнопку приводит
к вызову обработчика события Доступно только для кнопок, создаваемых ботом. |
|
|
Нажатие на кнопку приводит
к вызову обработчика события Действие не доступно для использования в интеграциях с мессенджерами. |
|
|
Нажатие на кнопку создаёт сообщение с текстом кнопки. |
|
|
Нажатие на кнопку создаёт сообщение
с текстом кнопки. В свойство Действие не доступно для использования в интеграциях с мессенджерами. |
|
|
Нажатие на кнопку осуществляет
переход по навигационной ссылке, указанной в свойстве |
В предыдущей таблице видно, что действия доступны не во всех клиентских приложениях. Поэтому для того, чтобы обеспечить универсальную работу клиентского приложения, при добавлении кнопок следует использовать метод ИнтеграцияСистемыВзаимодействия.ПоддерживаетсяДействиеКнопкиПанелиКнопокСообщения(). Чтобы получить интеграцию текущего обсуждения, следует использовать свойство обсуждения Интеграция (для получения идентификатора интеграции системы взаимодействия) и метод СистемаВзаимодействия.ПолучитьИнтеграцию() для получения того объекта, через который можно проверять возможность использования того или иного действия для кнопки.
С помощью свойства ВидКнопок объекта ПанельКнопокСообщенияСистемыВзаимодействия можно указать, каким образом будет отображаться панель кнопок: в виде кнопок или в виде гиперссылок. Указание выполняется с помощью значения системного перечисления ВидКнопкиПанелиКнопокСообщенияСистемыВзаимодействия.
Теперь подробнее рассмотрим свойства объекта КнопкаПанелиКнопокСообщенияСистемыВзаимодействия:
|
Свойство |
Описание |
|
|
Свойство позволяет прикрепить
к кнопке произвольные данные. Если для кнопки установлено действие Это свойство недоступно из пользовательского интерфейса. Данное свойство имеет смысл использовать в том случае, когда данные могут быть полезны боту, например, для взаимодействия различных подсистем прикладного решения. |
|
|
Содержит описание действия, которое будет выполнено при нажатии пользователем данной кнопки. Действия кнопки описаны выше. |
|
|
Свойство позволяет управлять доступностью
кнопки. Если свойство установлено в значение |
|
|
Вспомогательное свойство, которое можно использовать, чтобы быстро идентифицировать кнопку. |
|
|
Содержит картинку, которая отображается на кнопке. Для отображения картинка масштабируется до размера 16х16 пикселей. Не используется в интеграциях с мессенджерами. |
|
|
Содержит URL, который будет использован
для перехода. Используется в тому случае, если для кнопки установлено
действие |
|
|
Содержит текст, который отображается кнопкой. Имеется возможность в качестве значения свойства указывать форматированную строку. Однако, форматированная строка будет отображаться только в том случае, если кнопки отображаются в виде гиперссылок. Для обычных кнопок (и в сообщениях интеграции) форматирование удаляется и на кнопку располагается обычный текст. |
|
|
Содержит текст сообщения, которое будет
отправлено при нажатии на кнопку, если для кнопки установлено действие Если свойство не заполнено, то текст
сообщение будет содержать значение из свойства |
29.4.4.3.3. Обработка действий кнопок
Если у кнопки панели кнопок выбрано действие ОбработатьБотом или ОбработатьНаКлиенте, то разработчику следует определить один из обработчиков для того, чтобы реализовать желаемое поведение.
Для действия ОбработатьБотом следует использовать обработчик события ОбработкаНажатияКнопкиПанелиКнопокСообщенияСистемыВзаимодействия модуля бота системы взаимодействия. Этот обработчик должен находиться в модуле того бота, который обслуживает соответствующее обсуждение. Бот обрабатывает нажатие кнопок только в тех сообщениях, который создал сам этот бот. В обработчик передается информация, позволяющая точно идентифицировать контекст нажатия кнопки:
● Сообщение системы взаимодействия, в котором была нажата кнопка.
● Объект, описывающий нажатую кнопку.
● Какой пользователь нажал кнопку.
● Различная дополнительная информация, которая могла быть указана при создании бота системы взаимодействия.
Для действия ОбработатьНаКлиенте следует использовать обработчик события ПриНажатииКнопкиПанелиКнопокСообщенияСистемыВзаимодействия модуля приложения. В этот обработчик передается сообщение, в котором была нажата кнопка, и сама нажатая кнопка. Еще раз отметим, что кнопка с установленным действием ОбработатьНаКлиенте, является полным аналогом устаревшего действия системы взаимодействия.
Стоит отметить, что сообщение, в котором присутствуют кнопки, можно редактировать. Такая возможность может быть востребована в следующей ситуации: бот вначале формирует сообщение пользователю с необходимостью нажать ту или иную кнопку, а затем публикует текст, описывающий сделанный выбор. Например, бот запрашивает подтверждение заказа (или записи на какую-либо услугу), а после действия пользователя ‑ выводит текст с информацией о подтверждении. При этом будет разумно удалить кнопки с действиями. В этом случае бот может очистить коллекцию Сообщение.ПанельКнопок сообщения, в котором выполнено действие, установить нужный текст оповещения и записать сообщение. В пользовательском интерфейсе кнопки будут удалены и в сообщении будет только результат выполненного действия.
29.4.4.3.4. Отображение кнопок в сообщении
Отображение кнопок в сообщении зависит от того, каким образом отображаются кнопки:
● Свойство ВидКнопок установлено в значение ВидКнопкиПанелиКнопокСообщенияСистемыВзаимодействия.ОбычнаяКнопка: система пытается изменить размер кнопок таким образом, чтобы в результате кнопки отображались ровным прямоугольником, где высота ‑ это количество рядов, а ширина ‑ не больше ширины отображения сообщения.
● Свойство ВидКнопок установлено в значение ВидКнопкиПанелиКнопокСообщенияСистемыВзаимодействия.Гиперссылка: система пытается сделать так, чтобы все гиперссылки одного ряда уместились по ширине отображения сообщения. Других попыток выравнивания не предпринимается.
29.4.4.3.5. Ограничения работы с кнопками
Общие ограничения
Система взаимодействия накладывает следующие ограничения на панель кнопок:
● Максимальное количество кнопок в панели кнопок ‑ 100.
● Максимальное количество рядов ‑ 10.
● Максимальное количество кнопок в ряду ‑ 10.
Telegram
Мессенджер Telegram накладывает следующие ограничения на работу с кнопками в сообщениях:
● Не рекомендуется одновременно использовать в одной панели кнопки, одни из которых отображаются как inline (прикрепленные к сообщению), а другие как reply (прикрепленные к полю ввода сообщения). Рекомендуется, чтобы кнопки в Telegram отображались либо как inline, либо как reply.
● Не рекомендуется менять в сообщении состав кнопок так, что меняется расположение кнопок в Telegram. При наличии разных кнопок в панели, Telegram игнорирует кнопки reply.
ВКонтакте
Система ВКонтакте накладывает следующие ограничения на работу с кнопками в сообщениях:
● Максимальное количество кнопок в панели ‑ 10, остальные кнопки игнорируются и не отображаются.
● Кнопки, для которых свойство Доступность установлено в значение Ложь, игнорируются и не отображаются.
● Текст, отображаемый кнопкой, не должен превышать 40 символов. Кнопки с большей длиной текста игнорируются и не отображаются.
● В одном ряду кнопок может быть только одна кнопка с установленным действием НавигационнаяСсылка.
● Среди всех кнопок может быть только одна кнопка с установленным действием ЗапроситьМестоположение. Остальные кнопки с таким действием игнорируются и не отображаются.
● Если среди кнопок присутствует кнопка с действием ЗапроситьМестоположение, то она гарантированно будет отображена.
● Кнопка с установленным действием ЗапроситьМестоположение занимает весь ряд кнопок.
Мессенджер WhatsApp накладывает следующие ограничения на работу с кнопками в сообщениях:
● Кнопки отображаются только в мобильном клиенте WhatsApp.
● На кнопку в сообщении можно нажать только один раз. Повторное нажатие не поддерживается.
MAX
Мессенджер MAX накладывает следующие ограничения на работу с кнопками в сообщениях:
● Максимальное количество кнопок в одном ряду ‑ 7.
● Если в одном ряду есть кнопки, выполняющие одно из следущих действий: переход по URL, запрос местоположения или запрос номера телефона, то в одном ряду допускается не более 3 кнопок.
● Под сообщением бота допускается не более 210 кнопок, сгруппированных в 30 рядов.
29.4.4.4. Вложения
Система взаимодействия позволяет присоединять вложения к сообщениям системы взаимодействия. Эта возможность доступна только в том случае, если сервер системы взаимодействия соответствующим образом настроен. Для того, чтобы определить возможность работы с вложениями, следует использовать метод ПоддерживаетсяРаботаСВложениями().
Собственно работа с вложениями осуществляется с помощью свойства Вложения объекта СообщениеСистемыВзаимодействия. При работе с вложениями сервер системы взаимодействия контролирует три параметра:
● размер одного загружаемого файла;
● размер всех загружаемых файлов, за сутки;
● размер всех получаемых файлов, за сутки.
Данные параметры настраиваются на стороне сервера взаимодействия. При нарушении какого-либо из этих параметров формируется исключение.
Чтобы добавить новый объект вложения, следует использовать метод Вложения.Добавить(). При этом предполагается, что объект, помещаемый во вложение, не обязательно является файлом на диске. Можно, например, поступить следующим образом для отправки печатной формы документа в формате PDF:
● Создать поток в памяти (объект ПотокВПамяти).
● Сохранить табличный документ в созданный поток в формате PDF (метод Записать() объекта ТабличныйДокумент).
● Добавить вложение из созданного потока.
При создании вложения имеет смысл придерживаться следующих рекомендаций:
● Если вложение предполагается использовать в интерактивных сообщениях, то рекомендуется в качестве значения свойства ВложениеСистемыВзаимодействия.Наименование указывать имя файла с расширением, соответствующим фактическому типу содержимого. При этом свойство ВложениеСистемыВзимодействия.ТипСодержимого должно содержать реальный MIME-тип вложения.
● Если не предполагается использовать вложение для интерактивных операций, то значения свойств Наименование и ТипСодержимого объекта ВложениеСистемыВзимодействия формально могут быть любыми, но рекомендуется в качестве значения свойства ТипСодержимого указывать реальный MIME-тип, максимально корректно описывающий тип передаваемых данных.
Если свойство ВложениеСистемыВзимодействия.ТипСодержимого не задано, то платформа пытается определить тип вложения самостоятельно:
● При интерактивном прикреплении файла в сообщение:
● В тонком и толстом клиентах тип определяется по расширению файла.
● В веб-клиенте ‑ на основании информации, предоставляемой веб-браузером.
● При вставке картинки из буфера обмена устанавливается тип image/png.
● Если объект ВложениеСистемыВзимодействия формируется из встроенного языка и его свойство ТипСодержимого не указывается, то считается, что свойство объекта Наименование содержит имя прикрепляемого файла и выполняется попытка определить тип на основании расширения этого файла.
При отображении сообщения с вложениями в интерфейсе клиентского приложения, платформа отображает известные вложения специальными картинками:
● Для файлов стандартных платформенных типов (текстовый документ, табличный документ, графическая схема, географическая схема, HTML-документ, внешний отчет, внешняя обработка) отображается стандартная платформенная картинка соответствующего типа файла.
● Для файлов Microsoft Office, Open Office, Libre Office, PDF-файлов и архивов отображается картинка соответствующего типа файла.
● Для вложения с типом содержимого audio/* отображается картинка «аудио».
● Для вложения с типом содержимого video/* отображается картинка «видео».
● Для вложения с типом содержимого text/* отображается картинка «текст».
● Для вложения с типом содержимого image/* отображается картинка «картинка».
● Для остальных типов содержимого отображается картинка «неизвестный тип файла».
Система взаимодействия позволяет в одном сообщении отправлять несколько вложений, в т.ч. без текста сообщения. В мессенджере MAX каждое вложение будет передано своим сообщением, другими словами, если необходимо передать N вложений, то в MAX-е будет создано N связных сообщений. Удаление сообщения в системе взаимодействия будут удалены все связанные сообщения в мессенджере MAX. Текст редактируется либо у первого сообщения (если ранее были переданы только вложения, без текста), либо у того фактического сообщения, которое содержит редактируемый текст. Также следует помнить, что порядок следования связных сообщений в общем случае не определен.
29.4.4.5. Действия для вложений
Если в системе взаимодействия настроена работа с вложениями, то в прикладном решении может потребоваться реализовать специальные действия для вложений. Для этой цели предназначен метод ПодключитьОбработчикФормированияКоманд().
Данный обработчик срабатывает каждый раз, когда в интерфейсе клиентского приложения требуется получить команду по умолчанию (при нажатии левой кнопки мыши) или контекстное меню (при нажатии правой кнопки мыши). При нажатии правой кнопки мыши обработчик формирования команд будет вызван при нахождении курсора мыши над ссылкой, вложением, действием или самим сообщением. При нажатии левой кнопки мыши список команд будет затребован только для ссылки, вложения или действия. Так как обработчик формирования команд вызывается в интерактивном режиме и достаточно часто, в нем не рекомендуется размещать какие-либо длительные и интерактивные операции (например, задавать вопросы или открывать формы).
Обработчик формирования команд получает на вход следующие параметры:
● Параметры ‑ содержит информацию о том, где в сообщении нажата кнопка мыши. Свойство Параметры.Источник позволит понять, где нажата кнопка мыши. Свойства Обсуждение и Сообщение задают «контекст» действия.
● Параметр Команды содержит массив объектов типа ОписаниеКомандыСистемыВзаимодействия. При вызове обработчика этот параметр содержит команды, которые платформа по умолчанию размещает в контекстном меню для данного источника. Разработчик может сформировать это меню полностью самостоятельно, удалив команды, созданные по умолчанию. Стоит отметить, что конструкция встроенного языка Команды.Добавить(Новый ОписаниеКомандыСистемыВзаимодействия(Неопределено)); добавит в контекстное меню разделитель. Предоставляется возможность добавить стандартные команды системы взаимодействия. В этом случае необходимо добавление команды выглядит следующим образом Команды.Добавить(Новый ОписаниеКомандыСистемыВзаимодействия(СтандартнаяКомандаСистемыВзаимодействия.КопироватьСообщение));.
● Параметр КомандаПоУмолчанию содержит описание команды, которая будет вызвана, если в сообщении нажали левую кнопку мыши. Если данный параметр равен значению Неопределено, то контекстное меню будет открыто в любом случае: и при нажатии на правую и на левую кнопки мыши.
● Параметр ДополнительныеПараметры содержит данные, которые может потребоваться передать в обработчик формирования команд из того контекста, в котором подключается этот обработчик.
При необходимости, обработчик формирования команд может быть отключен с помощью метода ОтключитьОбработчикФормированияКоманд().
29.4.4.6. Внешние пользователи
Описание внешних пользователей см. здесь. Кроме интерактивных возможностей, система также предоставляет программисту работать с внешними пользователями с помощью встроенного языка.
Чтобы определить, что в данной системе поддерживается работа внешних пользователей, служит метод менеджера системы взаимодействия ПоддерживаетсяВнешнийДоступ().
Для того, чтобы внешний пользователь мог участвовать в обсуждении, его надо вначале создать в системе взаимодействия и затем отправить этому пользователю приглашение (в виде специальной ссылки). Создание внешнего пользователя выполняется обычным образом, но принципиально важно указать следующие свойства:
● Свойство Внешний ‑ оно указывает, что данный пользователь системы взаимодействия олицетворяет внешнего (по отношению к системе) пользователя.
● Свойство АдресЭлектроннойПочтыДляАутентификации ‑ в этом свойстве содержится адрес электронной почты, который однозначно идентифицирует внешнего пользователя.
После того, как пользователь создан , ему необходимо отправить навигационную ссылку с помощью метода ОтправитьНавигационнуюСсылкуВнешнегоДоступа(). В качестве инструмента доставки будет использоваться электронная почта, а адресом доставки служит адрес, указанный при создании внешнего пользователя в свойстве АдресЭлектроннойПочтыДляАутентификации. В зависимости от того, какой сайт используется для работы внешнего пользователя, будет выбираться почтовый сервер, через который выполняется доставка электронного письма со ссылкой на обсуждение. Если для работы используется сервис «dialog.online», то электронное письмо будет приходить с адреса info@dialog.online.
Если требуется отправить приглашение существующему пользователю системы взаимодействия (например, при необходимости пригласить обычного пользователя), то, очевидно, повторно его создавать не надо. Необходимо найти нужного пользователя системы взаимодействия и передать его в качестве значения параметра Пользователь метода ОтправитьНавигационнуюСсылкуВнешнегоДоступа().
Если навигационную ссылку необходимо передать каким-то другим способом (SMS, сторонний мессенджер и т. д.), то в этом случае можно получить внешнюю навигационную ссылку на обсуждение с помощью метода ПолучитьНавигационнуюСсылкуВнешнегоДоступа() менеджера системы взаимодействия. Полученную ссылку можно отправить получателю любым удобным способом. Следует помнить, что получение навигационной ссылки внешнего доступа требует наличия права доступа АдминистрированиеДанных.
Когда пользователь использует команду Пригласить внешнего участника, то в этом случае вызывается обработчик ОбработкаПриглашенияВнешнегоПользователяСистемыВзаимодействия(). Основной способ применения данного обработчика ‑ формирование собственного диалога приглашения внешнего пользователя. Если при выходе из обработчика параметр СтандартнаяОбработка будет равен значению Истина ‑ будет открыт стандартный диалог приглашения внешнего участника.
Смотри также:
● Права доступа (см. здесь).
29.4.4.7. Гостевые пользователи
Описание гостевых пользователей см. здесь. Гостевой пользователь получается приглашение в конкретное обсуждение и не может получить доступа к другим объектам системы взаимодействия. Доступ может быть получен интерактивно, например, с помощью флажка Создать ссылку-приглашение для других участников в диалоге создания нового обсуждения. Там же можно установить флажок Только видеозвонки и тогда гостевые пользователи, которые воспользуются такой ссылкой, смогут участвовать только в видеоконференции и не смогут писать сообщения. Еще одним способом интерактивного создания приглашения может быть команда Еще ‑ Пригласить участников по ссылке или почте в существующем неконтекстном обсуждении. В любом случае ссылка, которая будет создана, может быть использована неограниченным количеством людей (в том числе несколько раз один и тем же физическим пользователем). И это будет важным отличие от приглашения внешнего пользователя: каждого внешнего пользователя необходимо приглашать отдельно, т. к. у него собственная электронная почта.
Ссылкой-приглашением может воспользоваться любой пользователь из любого клиентского приложения. Но при этом следует помнить о некоторых различиях:
● Ссылка, открытая в веб-браузере, приводит к созданию гостевого пользователя во всех случаях, кроме одного. Гостевой пользователь не будет создан, если в текущем веб-браузере ранее аутентифицировался внешний пользователь по приглашению из той же информационной базы, что и используемая ссылка-приглашение. В этом случае при переходе по ссылке-приглашению в обсуждение попадет соответствующий внешний пользователь.
Идентификационная информация, по которой система определяет, нужно создавать нового пользователя или нет, хранится в данных веб-браузера. Из этого следует два следствия: 1) открытие одной и той же ссылки в нескольких разных(!) веб-браузерах, приведет к созданию нескольких гостевых пользователей и 2) очистка данных веб-браузера приведет к такому же эффекту.
● Ссылка, открытая в том же приложении, в котором сформирована ссылка-приглашение, приведет к тому, что к обсуждению подключиться полноправный пользователь системы взаимодействия (без ограничений внешнего или гостевого пользователя).
● Ссылка, открытая в приложении, отличном от приложения, в котором сформирована ссылка-приглашение (или в информационной базе, вовсе не подключенной к системе взаимодействия) приведет к открытию ссылки в веб-браузере и, как следствие, созданию нового гостевого пользователя.
Кроме интерактивных возможностей, создать ссылку приглашения в обсуждение можно из встроенного языка. Для этого следует использовать метод ПолучитьНавигационнуюСсылкуПриглашенияВОбсуждение() менеджера системы взаимодействия. Для формирования ссылки необходимо знать, для какого обсуждения формируется приглашение (параметр Обсуждение типа ИдентификаторОбсужденияСистемыВзаимодействия) и будет приглашенный пользователь иметь возможность писать сообщения в обсуждение или только участвовать в видеокомнате (параметр ТолькоВидеоконференция типа Булево). Если для системы взаимодействия включен внешний доступ, то метод вернет ссылку для внешнего доступа, в противном случае это будет внутренняя ссылка (пригодная для использования из клиентского приложения). Отзыв навигационной ссылки-приглашения выполняется только интерактивно.
29.4.5. Поиск объектов системы взаимодействия
Система взаимодействия предлагает инструменты для получения списка объектов, отвечающих некоторым критериям:
● Поиск пользователей ‑ ПолучитьПользователей().
● Поиск обсуждений ‑ ПолучитьОбсуждения().
● Поиск сообщений ‑ ПолучитьСообщения().
Каждый из методов получает на вход параметр, который описывает параметры объектов, которые необходимо получить. Каждый метод получает отбор в объекте соответствующего типа, но есть несколько параметров, которые являются общими для всех отборов рассматриваемых методов:
● Свойство Количество ‑ определяет, какое максимальное количество объектов будет получено в одной порции данных. Значение по умолчанию для данного свойства ‑ 200 объектов. Максимальное значение данного свойства ‑ 250 объектов.
● Свойство НаправлениеСортировки определяет то, каким образом выполняется сортировка выборки.
● Свойства После и ДатаНачала описывают начальную границу выборки в соответствующем отборе.
Рассмотрим подробнее, как это работает. Разработчик указывает параметры отбора в соответствующем объекте и вызывает метод поиска. Важным моментом является то, что перед первым вызовом поиска необходимо установить свойство отбора НаправлениеСортировки и не менять это значение, если требуется получить все объекты, которые соответствуют отбору.
После получения первой части выборки, необходимо указать системе, с какого объекта продолжать получение объектов:
● Для поиска сообщений и пользователей необходимо использовать свойство После. В это свойство необходимо поместить последнего объекта из предыдущей выборки.
● Для поиска обсуждений необходимо установить свойство ДатаНачала равным последнему сообщению предыдущей выборки.
Затем необходимо получить следующую порцию объектов с помощью соответствующего метода поиска и продолжать цикл до тех пор, пока не будут получены все объекты, которые следует обработать.
Следует помнить, что методы поиска не гарантируют непрерывности получаемых данных. Если после обработки какой-либо порции результатов в исходных данных будут выполнены изменения (в уже обработанном фрагменте исходных данных) ‑ то измененные данные могу быть не получены и последовательность будет нарушена.
29.4.6. Взаимодействие «человек-машина» или боты в системе взаимодействия
29.4.6.1. Общая информация
Прикладное решение может включать возможности автоматического ответа в некоторые обсуждения или может требовать реакции на данные, которые поступают с сервера «1С:Предприятия». Также к прикладному решению могут быть подключены различные системы мгновенного обмена сообщениями, откуда также могут поступать сообщения. Для того чтобы реализовать это, нужно иметь возможность реагировать на изменения, которые происходят в обсуждениях. Тогда прикладное решение может оперативно обрабатывать новые сообщения в обсуждениях и адекватно на них реагировать.
Такое поведение можно условно разделить на два класса задач:
1. Реализация автоматической реакции клиентского приложения на не интерактивные сообщения.
2. Реализация автоматической реакции прикладного решения на интерактивные сообщения пользователя. Причем пользователем может быть не только пользователь информационной базы, но и внешний (по отношению к прикладному решению) пользователь.
В первом случае необходимо обеспечить некоторый обработчик сообщений непосредственно в самом клиентском приложении, который будет обеспечивать обработку сообщений и выполнение команд, которые в этих сообщениях поступают. Очевидно, что для выполнения таких команд требуется, чтобы было запущено клиентское приложение. Для выполнения этого сценария вполне достаточно возможности подключения обработчика новых сообщений.
Во втором случае ситуация более сложная. Достаточно типичным сценарием является следующая последовательность действий:
● В некоторой системе обмена мгновенными сообщениями (мессенджере) пользователь находит некоторого абонента, которого представляет прикладное решение, и пишет ему сообщение. В роли абонента выступает некоторый специфический инструмент конкретного мессенджера (бот, сообщество и т. д.).
● В прикладном решении сообщение попадает в систему взаимодействия, в обсуждение, связанное с этой системой обмена мгновенными сообщениями.
● Предполагается, что реакция на сообщение пользователя реализуется в самом прикладном решении некоторым алгоритмом, который реализован в специализированном объекте конфигурации. Прикладное решение анализирует сообщение и определяет, какой пользователь системы должен взаимодействовать с пользователем внешней системы.
● Затем сообщение направляется выбранному пользователю, и дальнейшее общение может выполняться уже без участия автоматических алгоритмов.
Очевидно, что в этом случае первичный канал «пользователь ‑ прикладное решение» должен работать вне зависимости от того, запущено какое-то клиентское приложение или нет. Для того чтобы реализовать данный сценарий, необходимо реализовать интеграцию с внешней системой (подробнее см. здесь), а также специальный объект системы «1С:Предприятие» под названием «бот системы взаимодействия». Также надо понимать, что внешняя система не является обязательным «ингредиентом» такой схемы. Подобный бот может существовать и в рамках обычной информационной базы, выполняя, при этом, некоторые сервисные функции.
Дальше, в данной главе, речь пойдет о реализации каждого из описанных сценариев взаимодействия пользователя и прикладного решения.
29.4.6.2. Автоматическая реакция клиентского приложения
29.4.6.2.1. Особенности реализации
Реакция на сообщения реализуется путем подписки клиентского приложения на появление новых сообщений в каком-либо обсуждении. В данный класс задач могут попадать следующие задачи:
● Оповещения клиентского приложения о выполнении некоторых служебных действий (например, перезапуск клиентского приложения).
● Отображение состояния выполнения длительных задач, выполняемых на сервере.
● Другие подобные задачи.
Подключение обработчика новых сообщений выполняется с помощью метода НачатьПодключениеОбработчикаНовыхСообщений(). Для выполнения этой операции необходимо знать, каким образом идентифицировать обсуждение, на которое подписывается клиентское приложение. Вопрос однозначной идентификации обсуждения (и сообщения, на которое требуется реагировать) очень сильно зависит от специфики реализуемого алгоритма. Перед тем, как выбрать конкретную схему реализации, рекомендуется ответить на несколько очень простых вопросов, которые позволят более четко понять, каким образом будет выполняться взаимодействие. Рассмотрим эти вопросы подробнее:
1. Что мы хотим сделать?
Ответ на этот вопрос позволит определить, каким образом будет передаваться указание на выполняемое действие. Действие можно передать с помощью следующих свойств объекта СообщениеСистемыВзаимодействия: Данные, Текст или с помощью свойства ОбсуждениеСистемыВзаимодействия.Ключ.
2. Кто будет выполнять требуемое действие?
Ответ на этот вопрос определяет адресацию выполняемого действия. Адресация может быть реализована следующими способами:
● свойства Получатели или Данные объекта СообщениеСистемыВзаимодействия;
● свойства Участники или Ключ объекта ОбсуждениеСистемыВзаимодействия.
3. Будут-ли параметры у выполняемого действия и как они будут указываться?
Выполняемые действия могут быть простыми и однозначными. Простейший пример ‑ необходимость выполнить перезапуск клиентского приложения в момент получения команды на это. В то же время, другие действия могут требовать различные параметры. Например, требуется выполнить перезапуск клиентского приложения в некоторое время или по какому-то условию. В этом случае параметры действия можно передавать с помощью свойств Данные и Текст объекта СообщениеСистемыВзаимодействия.
Рассмотрим несколько подробнее ответы на указанные вопросы.
На способ выдачи команд может существенно влиять выполняемая задача: реализуется обработка сообщений в интерактивном или не интерактивном обсуждении. Так, если рассматривается реакция на интерактивные команды, то логично предположить, что команды будут вводиться пользователем с помощью текстовых сообщений (свойство СообщениеСистемыВзаимодействия.Текст), а для не интерактивного взаимодействия лучше подходят свойства СообщениеСистемыВзаимодействия.Данные или ОбсуждениеСистемыВзаимодействия.Ключ. При этом работа через свойство сообщения Данные хорошо решает задачу передачи данных, т. к. обеспечивает структурированность передаваемой информации и позволяет формально описать контракт, по которому взаимодействуют отправитель и получатель сообщений.
Очевидно, что программная обработка сообщений подразумевает подписку на появление новых сообщений. Т. к. система не позволяет подписаться на новые сообщения всех обсуждений, то необходимо определить, какое обсуждение следует обрабатывать. В этом смысле ответ на вопрос об адресации является даже более приоритетным, чем выбор способа передачи команды. Таким образом, определив нужное обсуждение, становится понятно, как будет определяться состав обрабатываемых сообщений: автоматически (если используется адресация через свойства обсуждения) или с помощью некоторой схемы фильтрации (если используется адресация через свойства каждого, конкретного, сообщения).
С точки зрения данных, передаваемых в сообщении, видно, что самым универсальным способом ответить на все заданные вопросы является использование свойства Данные каждого сообщения. При использовании не интерактивных действий, выглядит вполне разумным следующее построение схемы взаимодействия:
● В системе формируется служебное обсуждение (с заранее известным ключом обсуждения). Что упрощает подключение и использование обработчика команд.
● В свойстве сообщения Данные указываются все данные, необходимые для выполнения действия: команда, участники команды, параметры команды и т. д.
Очевидно, что такой подход не подойдет для интерактивных команд. В этом случае придется решать проблему с передаваемыми данными с помощью разбора текста сообщения.
29.4.6.2.2. Примеры реализации
Общая информация
Рассмотрим несколько примеров реализации обработки сообщений на встроенном языке. Следует помнить, что приводятся примеры, демонстрирующие те или иных особенности механизма, а не законченные инструменты решения какой-либо задачи.
Пример 1
Общая схема подписки на какое-либо обсуждение выглядит достаточно просто. Для этого следует знать только значение, которое однозначно идентифицирует обсуждение. В этой роли выступает идентификатор обсуждения или его (обсуждения) ключ. Таким образом, подписка на обработку новых сообщений существующего обсуждения выглядит следующим образом:
Процедура ПодписатьсяНаСлужебноеОбсуждение(КлючСлужебногоОбсуждения) Экспорт ОбработкаПодключения = Новый ОписаниеОповещения("ЗавершениеПодключения", СообщенияКлиент, , "ОшибкаПодключения", СообщенияКлиент); ОбработкаСообщенийСервера = Новый ОписаниеОповещения("ОбработкаСообщенийСервера", СообщенияКлиент); СистемаВзаимодействия.НачатьПодключениеОбработчикаНовыхСообщений(ЗавершениеПодключения, КлючСлужебногоОбсуждения, ОбработкаСообщенийСервера); КонецПроцедуры Процедура ОбработкаСообщенийСервера(Сообщение, ДополнительныеПараметры) Экспорт // в данном обработчике будет выполняться обработка новых сообщений КонецПроцедуры Процедура ЗавершениеПодключения(ДополнительныеПараметры) Экспорт // в данном обработчике будет выполняться обработка завершения подключения обработчика КонецПроцедуры Процедура ОшибкаПодключения(ИнфоОбОшибке, СтандартнаяОбработка, ДополнительныеПараметры) Экспорт // в данном обработчике будет выполняться обработка ошибок подключения обработчика КонецПроцедуры
В данном примере нет разницы (с точки зрения синтаксиса метода) каким образом выполняется идентификация обсуждения. Хотя формальный параметр и называется КлючСлужебногоОбсуждения, его фактическим значением может быть как ключ обсуждения, так и идентификатор обсуждения.
Пример 2
Данный пример демонстрирует создание обсуждения, предназначенного для выполнения единственного действия, а также реализация этого действия и отправку команды на выполнение действия.
Будет создано обсуждение, которое предназначено только для посылки команды на перезапуск клиентского приложения для определенного пользователя (или пользователей).
Команда будет выполнена в том случае, если нужный пользователь указан в сообщении. В качестве идентификатора обсуждения будет выступать ключ.
Создание такого обсуждения будет выполняться на сервере следующим образом:
Обсуждение = СистемаВзаимодействия.СоздатьОбсуждение(); Обсуждение.Отображаемое = Ложь; Обсуждение.Ключ = "ПерезапускКлиентов"; Обсуждение.Участники.Добавить(СистемаВзаимодействия.СтандартныеПользователи.ВсеПользователиПриложения); Обсуждение.Записать();
Отправка сообщения в такое обсуждение может выглядеть следующим образом:
Обсуждение = СистемаВзаимодействия.ПолучитьОбсуждение("ПерезапускКлиентов"); АдресатыКоманды = Новый Массив; АдресатыКоманды.Добавить(<ИдентификаторПользователя1>); АдресатыКоманды.Добавить(<ИдентификаторПользователяN>); Сообщение = СистемаВзаимодействия.СоздатьСообщение(Обсуждение.Идентификатор); Сообщение.Данные = АдресатыКоманды; Сообщение.Записать();
Сообщение всегда должно содержать или текст или данные, даже если эти компоненты не анализируются системой.
В обработчике новых сообщений может быть следующий код на встроенном языке:
ТекущийПользователь = СистемаВзаимодействия.ИдентификаторТекущегоПользователя(); Если Сообщение.Данные.Содержит(ТекущийПользователь) Тогда ЗавершитьРаботуСистемы(Ложь, Истина); КонецЕсли;
Примечание. Плохо в этом примере то, что он перезапускает приложение «не глядя» на то, что делает пользователь. В реальной системе так делать не следует.
Пример 3
Еще одним вариантом реализации обработки сообщений будет рассмотрена реализация одного обсуждения, которое предназначено для всего служебного трафика внутри системы. Обсуждение идентифицируется ключом, а «подробности» заказываемого действия находятся в свойстве сообщения Данные:
● свойство Команда содержит команду, которая должна быть выполнена;
● свойство Адресат ‑ содержит пользователя, который выполняет команду.
Отправка команды будет следующим образом:
Обсуждение = СистемаВзаимодействия.ПолучитьОбсуждение("КомандныйКанал"); Параметры = Новый Структура; Параметры.Вставить("Команда", "Перезапуск"); Параметры.Вставить("Адресат", ИдентификаторПолучателя); Сообщение = СистемаВзаимодействия.СоздатьСообщение(Обсуждение.Идентификатор); Сообщение.Данные = Параметры; Сообщение.Записать();
Обработка сообщения будет выглядеть аналогично предыдущему примеру:
ТекущийПользователь = СистемаВзаимодействия.ИдентификаторТекущегоПользователя(); Если Сообщение.Данные.Адресат = ТекущийПользователь Тогда Если Сообщение.Данные.Команда = "Перезапуск" Тогда ЗавершитьРаботуСистемы(Ложь, Истина); КонецЕсли; КонецЕсли;
29.4.6.2.3. Реализация робота
Примечание. Для реализации робота рекомендуется рассматривать реализацию объекта БотСистемыВзаимодействия. Подробнее про данный объект см. здесь.
Если требуется реализовать некоторого робота, который будет реагировать на сообщения («бота»), которые интерактивно формирует пользователь, то логика работы будет несколько другой. В этом случае необходимо подписываться не на получение нового сообщения, а на факт отправки сообщения. Для этого существует метод ПодключитьОбработчикПослеОтправкиСообщения(). Подключенный обработчик будет срабатывать каждый раз после того, как пользователь отправит интерактивное сообщение. Срабатывать обработчик будет на том клиентском компьютере, на котором пользователь ввел сообщение. Параметрами подключенного обработчика события будут введенное сообщение и обсуждение, в рамках которого оправлено сообщение.
Дальнейшая реакция опять зависит от логики прикладного решения. В обработчике можно проанализировать текст сообщения и что-то ответить в том случае, если в этом тексте обнаружены ключевые слова. В обработчике можно проанализировать участников обсуждения и ответить только в том случае, если пользователь, который олицетворяет робота, входит в состав участников и т. д.
// === Код на стороне клиентского приложения Процедура СоздатьРобота() Экспорт Обработчик = Новый ОписаниеОповещения("ОбработкаОтправкиСообщения", СообщенияКлиент); СистемаВзаимодействия.ПодключитьОбработчикПослеОтправкиСообщения(Обработчик); КонецПроцедуры Процедура ОбработкаОтправкиСообщения(Сообщение, Обсуждение, ДополнительныеПараметры) Экспорт Если СтрНачинаетсяС(Сообщение.Текст, "?") Тогда // здесь вызывается реализация робота (бота) СоздатьСообщениеРобота(Обсуждение.Идентификатор, "Я робот!"); КонецЕсли; КонецПроцедуры // === Код на стороне серверного приложения Процедура СоздатьСообщениеРобота(ИдентификаторОбсуждения, ТекстСообщения) Экспорт Обсуждение = СистемаВзаимодействия.ПолучитьОбсуждение(ИдентификаторОбсуждения); Сообщение = СистемаВзаимодействия.СоздатьСообщение(Обсуждение.Идентификатор); Сообщение.Текст = ТекстСообщения; Сообщение.Записать(); КонецПроцедуры
Вышеуказанный пример подключает обработчик отправки сообщения, в котором выполняется анализ сообщения, введенного пользователем. Если сообщение начинается с символа «?», то считается, что такое сообщение адресовано роботу. В этом случае робот ответит в обсуждение сообщением Я робот!.
29.4.6.3. Бот системы взаимодействия
29.4.6.3.1. Общая информация
Для автоматизации общения пользователя и прикладного решения предназначен объект конфигурации БотСистемыВзаимодействия. Каждый бот создается для выполнения одной или нескольких определенных функций. Для реализации своих функций у бота имеется модуль объекта, в котором существует обработчик события ОбработкаСообщенияСистемыВзаимодействия. В этом обработчике находится реализация поведения бота.
Для того чтобы бот мог выполнять свои функции, с ботом связаны несколько пользователей:
● Пользователь системы взаимодействия. Данный пользователь является олицетворением бота в системе взаимодействия. Именно с этим аватаром общается другой пользователь системы взаимодействия, когда требуется взаимодействие с ботом. Этот пользователь всегда должен быть задан для бота. Если его не указать, то бот не сможет участвовать в обсуждениях системы взаимодействия (теряется смысл бота).
● Пользователь информационной базы прикладного решения. Данный пользователь определяет, к каким данным будет иметь доступ то или иной бот. Если с ботом не связан никакой пользователь информационной базы, то такой бот будет обладать правами, которые указаны в свойстве конфигурации Основные роли. Этот пользователь не является обязательным для указания.
Рассмотрим подробнее, как связаны различные пользователи при использовании бота. Когда система «1С:Предприятие» создает предопределенного бота, то для такого бота автоматически создается пользователь системы взаимодействия. При этом пользователь системы взаимодействия, связанный с предопределенным ботом, не связан ни с каким пользователем информационной базы. Аналогичное поведение можно реализовать и для обычного бота (создание пользователя системы взаимодействия без парного пользователя информационной базы). Связывать пользователя системы взаимодействия, олицетворяющего бота, с пользователем информационной базы имеет смысл в том случае, если необходимо выполнять какие-то интерактивные(!) действия в обсуждениях от имени бота.
Пользователь информационной базы, от имени которого работает бот, определяет только права доступа бота. Остальные параметры пользователя для бота безразличны. Этот пользователь может быть полностью самостоятельным, а может быть парным пользователем к пользователю системы взаимодействия. Выбор остается за разработчиком, т. к. именно разработчик понимает все аспекты задачи, которые он пытается решить с помощью бота.
С точки зрения системы взаимодействия, пользователь системы взаимодействия, связанный с ботом, ничем принципиально не отличается от других пользователей системы взаимодействия. Это значит, что бота можно включать в различные обсуждения, устанавливать для него режим наблюдения и т. д. Но сам бот, как участник обсуждения, имеет несколько особенностей и ограничений:
● Правила получения ботом сообщений:
● Бот не может получить сообщения, написанные им самим.
● Бот не может получить сообщения, написанные другими ботами.
● Бот может получить сообщения в следующих случаях:
● Обсуждение «один на один»: человек общается с ботом.
● Групповое неконтекстное обсуждение или контекстное обсуждение: будет получать сообщения, адресованные непосредственно боту, а все остальные сообщения ‑ в соответствии с настройками режима наблюдения бота.
● Бот не может принимать участия в видеозвонке.
Таким образом, общая схема использования бота выглядит следующим образом:
● Создается бот и описывается его логика работы в соответствующем обработчике.
● Для бота указывается пользователь информационной базы, если боту нужны права доступа к данным, которые отличаются от прав доступа по умолчанию.
● Для бота указывается пользователь системы взаимодействия. Такой пользователь может быть создан автоматически (для предопределенного бота) или выбран из уже существующих пользователей системы взаимодействия. После этого бот доступен для использования в информационной базе.
29.4.6.3.2. Устройство бота
Как уже было сказано, бот ‑ это объект БотСистемыВзаимодействия, а логика бота реализуется в обработчикеОбработкаСообщенияСистемыВзаимодействия() модуля объекта бота.
Бот (как объект конфигурации) характеризуется следующими параметрами:
● Предопределенный ‑ признак, указывающий, что бот является предопределенным ботом (по аналогии с предопределенным регламентным заданием). Предопределенный бот ничем не отличается от обычного бота, за исключением того, что его нельзя явно создать или удалить. Если в метаданных бота установлен признак Предопределенный, то при обновлении конфигурации в информационной базе автоматически будут созданы бот и пользователь системы взаимодействия. Если признак предопределенности снят, то информация о боте удаляется, пользователь системы взаимодействия перестает быть ботом. Начальные значения параметров предопределенного бота устанавливаются с помощью свойств объекта метаданных. В дальнейшем, при работе приложения, их можно менять через объект БотСистемыВзаимодействия. Изменение свойств метаданных (Имя, Синоним и Картинка) для предопределенного бота будут применены к пользователю системы взаимодействия при вызове метода ВыполнитьОбработкуБотов() менеджера системы взаимодействия.
● Картинка ‑ данное свойство содержит картинку, которая будет установлена пользователю системы взаимодействия, ассоциированному с данным ботом.
Бот (как объект встроенного языка) обладает следующими свойствами:
● Предопределенный ‑ это свойство является отражением свойства объекта конфигурации в объектную модель.
● Метаданные ‑ ссылается на объект конфигурации, описывающий бота. Изменение данного свойства приводит к изменению логики работы существующего бота. Не поддерживается изменение данного свойства для предопределенных ботов.
● Пользователь ‑ содержит ссылку на пользователя системы взаимодействия, который олицетворяет данного бота. Пользователя можно менять во время работы системы, изменение допустимо как из встроенного языка, так и с помощью соответствующей стандартной функции.
● ИмяПользователяИнформационнойБазыВыполненияОбработки ‑ данное свойство содержит ссылку на пользователя информационной базы. Указанный в данном свойстве пользователь определяет, какие права доступа к объектам базы данных будут предоставлены боту.
● ДополнительныеПараметры ‑ через это свойство можно передавать боту какие-то дополнительные данные, которые не могут быть переданы через информационную базу. Эти параметры можно применять тогда, когда один объект БотСистемыВзаимодействия используется для разных ботов. Например, есть объект БотСистемыВзаимодействия, который в одном случае (бот с именем Отрицание) на любой запрос человека отвечает Никак нет!, а в другом (бот с именем Подтверждение) случае на любой вопрос человека отвечает Так точно!. В этом случае текст ответа бота можно передавать в обработчик сообщения (в модуль объекта бота) с помощью дополнительных параметров. Для того чтобы создать несколько ботов, которые «обслуживаются» одним объектом метаданных, следует создать несколько объектов БотСистемыВзаимодействия (или получить эти объекты для уже созданных ботов), и для каждого объекта указать одинаковое значение для свойства объекта Метаданные.
Боты создаются следующими способами:
● В результате вызова метода ВыполнитьОбработкуБотов() менеджера системы взаимодействия. Таким способом создаются предопределенные боты.
● С помощью метода БотСистемыВзаимодействия.Записать(). Собственно объект БотСистемыВзаимодействия можно получить с помощью методов СоздатьБота(),ПолучитьБота() илиПолучитьБотов() менеджера системы взаимодействия.
Кроме возможности обработать сообщение системы взаимодействия, с помощью модуля бота можно обрабатывать следующие события:
● Добавление бота в существующее обсуждение системы взаимодействия. Для этого служит обработчик события ПриДобавленииВОбсуждениеСистемыВзаимодействия.
● Удаление бота из обсуждения системы взаимодействия. Для этого служит обработчик события ПриУдаленииИзОбсужденияСистемыВзаимодействия.
● Если создается новое обсуждение с участием бота, то будет вызван обработчик события ПриСозданииОбсужденияСистемыВзаимодействия.
29.4.6.3.3. Примеры реализации
Эхо-бот
В качестве примера реализации рассмотрим бота, который выступает в роли эхо: повторяет то, что пришло ему в качестве сообщения. Для реализации бота следует создать объект конфигурации:
Рис. 549. Свойства эхо-бота
В модуле объекта для созданного бота необходимо поместить следующий текст:
Процедура ОбработкаСообщенияСистемыВзаимодействия(Сообщение, ДополнительныеПараметры) Ответ = СистемаВзаимодействия.СоздатьСообщение(Сообщение.Обсуждение); Ответ.Текст = "echo" + Символы.ПС + ">" + СтрСоединить(СтрРазделить(Сообщение.Текст, Символы.ПС), Символы.ПС + ">"); Ответ.Записать(); КонецПроцедуры
При запуске клиентского приложения, в системе взаимодействия будет автоматически создан бот и соответствующий ему пользователь системы взаимодействия. Это произойдет потому, что мы создали предопределенного бота.
Если теперь отправить боту Эхо Бот любое сообщение, он ответит текстом, который начинается с текста echo, а на следующих строках (в режиме цитирования) будет выведен текст, который отправлен боту.
Эхо-бот и мессенджер
Как говорилось ранее, бот системы «1С:Предприятие» может участвовать в обсуждениях, которые инициированы из систем обмена мгновенными сообщениями (мессенджеров). Для того чтобы объект типа БотСистемыВзаимодействия смог обрабатывать сообщения из мессенджера, надо выполнить два действия:
1. Создать собственно бота.
2. Создать интеграцию системы «1С:Предприятие» и мессенджера. Описание такой интеграции см. стр. здесь.
3. Указать в настройках интеграции пользователя системы взаимодействия, который олицетворяет бота, в качестве участника обсуждения по умолчанию.
Вся остальная схема работы ничем не отличается от общей схемы работы с мессенджером (подробнее см. здесь). Единственной особенностью такой работы будет то, что в качестве одного из, или единственного пользователя, который получает сообщение из мессенджера, будет пользователь системы взаимодействия, олицетворяющий бота системы «1С:Предприятие».
Так, если добавить пользователя системы взаимодействия ранее созданного «Эхо-бота» в существующую интеграцию с какой-либо системой обмена мгновенными сообщениями, то на каждое сообщение внешнего пользователя всегда будет формироваться ответ в виде заданного вопроса. Наверное, не стоит так делать для интеграции, которая обслуживает какие-то реальные потребности внешних пользователей.
29.4.6.3.4. Схема обработки сообщений от системы взаимодействия
Общая информация
В общем случае, процесс получения (и обработки) сообщения из системы взаимодействия выглядит следующим образом:
● При выполнении метода менеджера системы взаимодействия ВыполнитьОбработкуБотов() платформа создает сетевое соединение с системой взаимодействия. Данное соединение удерживается в течение 2 минут. В момент каждого вызова метода ВыполнитьОбработкуБотов() таймаут начинает отсчитываться от момента вызова метода. Если вызов метод не выполнялся в течение 2 минут ‑ сетевое соединение закрывается, и взаимодействие с системой взаимодействия прерывается. Данное поведение не зависит от того, в каком варианте работы информационной базы (файловом или клиент-серверном) выполняется работа с системой взаимодействия. В связи с этим, рекомендуется вызывать метод ВыполнитьОбработку() с помощью регламентного задания, которое должно срабатывать 1 раз в минуту.
● За обработку сообщений, поступающих от системы взаимодействия, отвечают несколько фоновых заданий. Специфика их работы зависит от используемого варианта информационной базы (файловый или клиент-серверный). Эта специфика будет рассмотрена подробнее в следующих разделах. В общем описании работы специфика файлового варианта не будет отдельно рассматриваться.
● Как только система взаимодействия оповещает платформу о появлении нового сообщения, начинают свою работу три фоновых задания:
● Фоновое задание получения сообщений выполняется как реакция на уведомление от системы взаимодействия. Фоновое задание получает сообщение, помещает его в очередь сообщений информационной базы, уведомляет систему взаимодействия о получении сообщения и завершает свою работу.
● На следующем этапе запускается фоновое задание обработки очереди сообщений. Данное фоновое задание анализирует очередь сообщений и запускает фоновые задания обработки полученных сообщений. При запуске фоновым заданиям передается идентификатор обрабатываемого сообщения, а также указывается, от имени какого пользователя, и в какой области данных должно работать фоновое задание. После обработки всей очереди фоновое задание завершается.
● Последним этапом является выполнение фонового задания обработки полученного сообщения. Это фоновое задание выполняет обработку конкретного сообщения, при этом фоновое задание выполняется от имени конкретного пользователя и в конкретной области данных. Именно из этого фонового задания происходит вызов обработчика модуля объекта бота, который выполняет обработку сообщения системы взаимодействия.
Наличие трех фоновых заданий призвано решить несколько задач:
● Обеспечить подобные схемы работы в файловом и клиент-серверном вариантах работы.
● Реализовать минимальные задержки в получении сообщений от системы взаимодействия.
● Обеспечить исполнение фонового задания обработки конкретного сообщения в конкретной области данных и от имени определенного пользователя, и сделать это с минимальными накладными расходами.
● Снизить накладные расходы при получении сообщений от системы взаимодействия.
Файловый вариант
Каждое фоновое задание обработки сообщений всегда обрабатывает одно сообщение и завершает работу. Если сообщения для обработки нет, то ожидание сообщений не выполняется. Следует помнить, что в файловом варианте фоновые задания всегда выполняются последовательно и это выполнение обеспечивается одним экземпляром клиентского приложения. Обработка выполняется следующим образом:
● В момент получения нового сообщения (через установленное сетевое соединение), платформа запускает фоновое задание получения сообщений. Данное фоновое задание запускается с максимальным приоритетом. Другими словами, вне зависимости от того, сколько фоновых заданий ожидают своего выполнения в момент поступления сообщения от системы взаимодействия, фоновое задание получения сообщений будет всегда запущено после завершения выполнения текущего фонового задания (если таковое есть).
● Фоновое задание получения сообщений выполняет получение одного сообщения. Сообщение записывается в очередь сообщений базы данных. Запускается (а фактически ‑ планируется запуск) фоновое задание обработки получения сообщений. Фоновое задание получения сообщений завершается.
● Фоновое задание обработки очереди сообщений получает из очереди одно сообщение. Определяются параметры обработки этого сообщения: имя пользователя и пароль, от имени которых будет обрабатываться сообщение, параметры области данных, в рамках которой будет выполняться обработка сообщения. Затем планируется запуск фонового задания обработки полученных сообщений, которому передается полученное сообщение. Фоновое задание запускается с ранее определенными параметрами. Затем фоновое задание обработки очереди сообщений анализирует, есть в локальной очереди необработанные сообщения или нет. Если сообщения есть ‑ фоновое задание обработки очереди сообщения планирует свой повторный запуск. После завершения всех вышеописанных действий фоновое задание обработки очереди завершает свою работу.
● Фоновое задание обработки полученных сообщений вызывает обработчик сообщений бота. Если сообщение получено успешно, то сообщение в очереди помечается как обработанное. Если код на встроенном языке завершился аварийно, то попытка обработки сообщения будет предпринята повторно. После выполнения этих действий фоновое задание завершает свою работу.
Клиент-серверный вариант
При работе клиент-серверного варианта всегда запускаются все три фоновых задания работы с сообщениями. Однако фоновое задание обработки полученных сообщений после завершения своей работы не завершается, а «засыпает» на время 20 секунд. Если в течение 20 секунд потребуется обработать новое сообщение от системы взаимодействия, то обработка будет выполнена достаточно быстро, т. к. кластеру серверов не потребуется тратить время на создание нового сеанса фонового задания. Если следующее сообщение поступило более чем через 20 секунд после поступления предыдущего сообщения, то фоновое задание будет запущено заново. Обработка выполняется следующим образом:
● В момент получения нового сообщения (через установленное сетевое соединение), платформа передает управление фоновому заданию получения сообщений. Это фоновое задание получает все сообщения от системы взаимодействия, записывает их в очередь сообщений базы данных и уведомляет фоновое задание обработки полученных сообщений.
● Фоновое задание обработки очереди сообщений получает управление после получения очередного сообщения. Для каждого из полученных сообщений определяются параметры запуска фонового задания обработки полученных сообщений. Затем фоновому заданию обработки полученных сообщений передается для обработки идентификатор сообщения, которое требуется загрузить.
● Фоновое задание обработки полученных сообщений вызывает обработчик получения сообщения системы взаимодействия, который размещен в модуле объекта бота. Если сообщение получено успешно, то сообщение в очереди помечается как обработанное. Если код на встроенном языке завершился аварийно, то попытка обработки сообщения будет предпринята повторно. После выполнения этих действий фоновое задание «завершает» свою работу (с учетом особенностей, описанных в начале раздела).
Таким образом, ключевое отличие между файловым и клиент-серверным вариантом заключается (фактически) в устройстве механизма работы с фоновыми заданиями. В файловом варианте в каждый момент времени работает только одно фоновое задание и фоновые задания выполняются последовательно. В клиент-серверном варианте фоновые задания могут работать параллельно.
29.4.7. Совместное использование
Система взаимодействия позволяет объединить несколько приложений, зарегистрированных в системе взаимодействия, в единое пространство. В случае объединения приложений, в качестве пользователей системы взаимодействия выступают пользователи всех объединенных приложений. При объединении приложений, также, становится доступной возможность обмена сообщениями между приложениями. Объединять приложения может только владелец абонента всех объединяемых приложений. Совместное использование поддерживается:
● сервисом 1cDialog.com,
● продуктом 1С:Сервер взаимодействия.
Для объединения приложений можно использовать стандартную функцию системы «1С:Предприятие» (при использовании сервиса 1cDialog.com) или реализовать нужный код на встроенном языке (при использовании экземпляра продукта 1С:Сервер взаимодействия).
В качестве примера необходимости такого объединения можно привести работу территориально-распределенного предприятия, например сети магазинов и центральный офис сети. Каждый магазин и центральный офис имеют собственную информационную базу. В центральном офисе можно развернуть экземпляр продукта 1С:Сервер взаимодействия или воспользоваться сервисом 1cDialog.com. Базы данных регистрируются в выбранном сервисе (каждый магазин и база центрального офиса). Затем происходит объединение получившихся приложений. В результате получается единое информационное пространство, позволяющее обмениваться сообщениями пользователям всех баз данных в реальном масштабе времени.
Для объединения приложений необходимо использовать объект СовместноеИспользованиеПриложенийСистемыВзаимодействия. Перечень объединяемых приложений задается с помощью свойства этого объекта Приложения. Данное свойство можно заполнить на основании результата использования функции ПолучитьПриложенияАбонента(). Данный метод следует вызывать при работе от имени пользователя, являющегося владельцем абонента.
Кроме списка объединяемых приложений, объект СовместноеИспользованиеПриложенийСистемыВзаимодействия позволяет указать, каким образом будут сопоставляться пользователи системы взаимодействия объединяемых приложений:
● По имени (значение Имя) ‑ в этом случае одинаковыми будут считаться пользователи системы взаимодействия, у которых одинаковое свойство Имя.
● По полному имени (значение ПолноеИмя) ‑ в этом случае одинаковыми будут считаться пользователи системы взаимодействия, у которых одинаковое свойство ПолноеИмя.
● По ключу сопоставления (значение КлючСопоставления) ‑ в этом случае одинаковыми будут считаться пользователи системы взаимодействия, у которых одинаковое свойство КлючСопоставления. Таким образом, можно выполнить выборочное сопоставление пользователей приложений. Для тех пользователей, которых необходимо сопоставить между разными приложениями, следует указать свойство КлючСопоставления. В этом случае пользователи с одинаковыми ключами будут прозрачны для объединенных приложений, а остальные пользователи будут доступны только в рамках «своих» приложений системы взаимодействия.
Выбор способа сопоставления пользователей осуществляется с помощью свойства СопоставлениеПользователей.
Наконец свойство СопоставлениеКонтекстовОбсуждений объекта СовместноеИспользованиеПриложенийСистемыВзаимодействия позволяет указать, что объекты, которые в разных приложениях обладают одинаковыми идентификаторами ‑ будут считаться одинаковыми в рамках информационного пространства объединенных приложений. Так, если в рамках распределенной информационной системы установлено сопоставление контекстов обсуждений, то открывается возможность обсуждать один документ из разных приложений (информационных баз).
При объединении нескольких приложений, эти приложения начинают работать по схеме «все со всеми». Т. е. каждое из объединенных приложений получает возможность взаимодействовать с любым другим приложением из списка объединенных. В то же время, система взаимодействия не поддерживает использование такой схемы: Приложение1 объединяется с Приложение2, а Приложение2 объединяется с Приложение3 и при этом Приложение3 не может взаимодействовать с Приложение1.
Для отмены сопоставления приложений служит метод ОтменитьСовместноеИспользованиеПриложенийАбонента(). Отмена совместного использования выполняется аналогично установке сопоставления: формируется список приложений, которые больше нет необходимости использовать совместно (но не меньше двух), и вызывается метод ОтменитьСовместноеИспользованиеПриложенийАбонента().
С помощью метода СовместноеИспользованиеПриложенийВзаимодействия() можно получить список совместно используемых приложений и параметров совместного использования. При этом следует учитывать тот факт, что совместно используемые приложения возвращаются парами.
29.5. Интеграция с различными системами
29.5.1. Общая информация
Система взаимодействия поддерживает интеграцию с различными внешними (по отношению к серверу взаимодействия и «1С:Предприятием») системами. Это могут быть системы мгновенного обмена сообщениями; системы, которые могут только выполнить вызов какого-либо HTTP-сервиса; веб-сайты, на которые можно установить «клиентскую часть» обсуждения системы взаимодействия.
Система мгновенного обмена сообщениями ‑ это клиент-серверное программное обеспечение, предназначенное для обмена различными сообщениями между пользователями этих систем. На компьютере (или ином устройстве пользователя) пользователя установлено клиентское приложение. Это приложение чаще всего называют мессенджерами (в данном разделе мы будем использовать этот термин) или по имени всей системы. В качестве клиентского приложения может выступать и веб-приложение. Как правило, все взаимодействие выполняется через централизованный сервер (или сервера) системы мгновенного обмена сообщениями. Клиентские приложения подключаются к «своему» серверу. На момент написания данного раздела, можно перечислить следующие, наиболее популярные системы: ВКонтакте, Telegram, WhatsApp, MAX и т. д.
Система взаимодействия предоставляет возможность наладить взаимодействие прикладного решения, написанного на базе «1С:Предприятия», с одним из поддерживаемых мессенджеров. При этом взаимодействие мессенджера и прикладного решения можно охарактеризовать как интерактивное и двустороннее. Это означает, что основная схема взаимодействия подразумевает диалог, в котором участвуют люди и в этом взаимодействии активное участие принимают обе стороны. Под активным участием понимается возможность создавать сообщения в обсуждении.
Кроме такого взаимодействия, существуют и другие схемы взаимодействия. Например, есть некоторая исполнительная система, в которой происходят некоторые события. Прикладное решение должно получать информацию о том, что событие произошло, и выполнять какие-то действия. Для реализации такой схемы взаимодействия можно поступить по-разному:
● Можно вызывать методы программного интерфейса исполнительной системы.
● Можно реализовать в прикладном решении Интернет-сервисы, которые будет вызывать исполнительная система.
● Можно предложить исполнительной системе воспользоваться механизмом вебхуков (webhook, веб-перехватчик). Этот механизм представляет из себя специальный URL на сервере системы взаимодействия, на который должен быть отправлен POST-запрос с телом запроса, которое оформлено особым образом. Получив такой запрос, сервер системы взаимодействия начнет вызывать связанные механизмы системы «1С:Предприятие». Данный способ позволяет реализовать машинное и одностороннее взаимодействие исполнительной системы и прикладного решения. Система «1С:Предприятие» может только принимать сообщения от внешнего источника.
В тех случаях, когда система «1С:Предприятие» обслуживает какой-либо интернет-магазин, то может возникать потребность реализовать следующий сценарий использования: на сайте есть чат, пользователь может написать в этот чат, а отвечать ему будет сотрудник компании, которая продает товары на сайте. При этом желательно, что для того, чтобы ответить пользователю сайта, пользователю системы «1С:Предприятие» не приходилось переходить в другую систему. В некотором смысле, данный вариант взаимодействия похож на интеграцию с мессенджером, но с другим «клиентским приложением».
Описанию различных вариантов процессов интеграции будет посвящен данный раздел.
29.5.2. Работа с внешними системами
29.5.2.1. Схема работы с внешней системой
Для интеграции внешней системы и прикладного решения необходимо выполнить следующие действия:
● Во внешней системе выполнить действия, необходимые для обеспечения взаимодействия со сторонним программным обеспечением. Это может быть создание бота, сообщества, доработка программного обеспечения и т. д.
● В прикладном решении создать новую интеграцию ‑ связь системы взаимодействия и внешней системой. Это можно сделать как интерактивно (с помощью стандартной функции), так и из встроенного языка.
В дальнейшем будем называть объект внешней системы, который олицетворяет интеграцию (бот, сообщество и т. д.) внешней системы и системы взаимодействия ‑ пользователем интеграции. Другими словами, человек будет писать «пользователю интеграции» для того, чтобы написать сообщение, которое поступит в систему взаимодействия и, потом, в прикладное решение.
Собственно взаимодействие в такой интегрированной системе будет выглядеть следующим образом:
● Пользователь внешней системы находит нужного пользователя интеграции, который связан с прикладным решением. Поиск может быть выполнен любым способом, который поддерживается внешней системой (по имени, по QR-коду и т. д.).
● Затем пользователь пишет найденному пользователю интеграции сообщение.
● Внешняя система передает сообщение системе взаимодействия.
● При получении входящего сообщения сервер системы взаимодействия:
● Для каждого нового пользователя внешней системы создает нового пользователя системы взаимодействия. Пользователю выставляется отметка о том, что это «внешний» пользователь. Информация о пользователе заполняется на основании данных, полученных от внешней системы.
● Создает внеконтекстное групповое отображаемое обсуждение (если таковое не было создано ранее) для этого пользователя. Данное обсуждение получает специальную отметку о том, что это обсуждение с «внешним» миром. Заголовок обсуждения имеет имя внешнего пользователя или группового чата мессенджера. В заголовке обсуждения отображается, из какой внешней системы начато обсуждение. Вид заголовка зависит от того, каким образом выполняется общение с пользователем интеграции внешней системы: ему пишут напрямую или добавляют в какую-то группу. Это зависит от используемой внешней системы.
● Для созданного обсуждения создается список пользователей. В этот список входят: пользователь, начавший обсуждение и все пользователи, которые указаны при создании интеграции. Внешний пользователь отображается с соответствующей пометкой.
● В созданное обсуждение добавляется полученное сообщение. Автором сообщения становится внешний пользователь. Оповещения в системе взаимодействия формируются по стандартным правилам. Для внешнего пользователя оповещения не создаются.
● Сообщение, отправленное из системы взаимодействия во внешнюю систему, будут написаны от имени пользователя интеграции (как он представляется во внешней системе). В качестве получателя будет выступать внешний пользователь системы взаимодействия (тот, кто начал обсуждение).
Таким образом, сообщения от внешних пользователей в системе взаимодействия будут персонифицированными (с точностью до того, как пользователь представлен во внешней системе). Сообщения, которые передаются из прикладного решения во внешнюю систему, будут «анонимными», т. е. автором сообщений будет пользователь интеграции, а не фактический автор сообщения. Поэтому идентифицировать фактического пользователя прикладного решения, от имени которого написано то или иное сообщение, во внешней системе будет невозможно.
При работе с внешними системами следует учитывать, что:
● Каждая внешняя система может иметь отдельный список ограничений.
● В общем случае интеграция с внешними системами поддерживает работу с файлами, однако каждая внешняя система обладает своими особенностями. Подробности можно посмотреть в документации к серверу взаимодействия.
29.5.2.2. Технические особенности интеграции
29.5.2.2.1. Получение списка доступных внешних систем
Список внешних систем, интеграция с которыми поддерживается системой «1С:Предприятие», зависит от сервера взаимодействия. Список внешних систем, поддерживаемых сервером взаимодействия, может быть изменен в рамках одной полной версии системы «1С:Предприятие». Также не следует опираться на то, что список поддерживаемых внешних систем является постоянным и зависит от версии системы «1С:Предприятие».
Для того чтобы получить список доступных внешних систем, предназначена функция менеджера системы взаимодействия ПолучитьТипыВнешнихСистем(). Каждая внешняя система будет представлена своим текстовым именем. Тип внешней системы, полученный из этого списка, далее будет использоваться в различных методах при создании интеграции.
29.5.2.2.2. Информация о внешней системе
После того, как выбрана внешняя система, с которой будет выполняться интеграция, необходимо получить информацию об этой системе. Для этого служит функция менеджера системы взаимодействия ПолучитьОписаниеВнешнейСистемы(). Результатом вызова будет объект типа ОписаниеВнешнейСистемыСистемыВзаимодействия. Объект содержит имя внешней системы (свойство Тип) и список параметров, которые необходимы для подключения к внешней системе (свойство ОписаниеПараметров).
Каждый параметр представлен объектом ОписаниеПараметраВнешнейСистемыСистемыВзаимодействия. Каждый параметр характеризуется именем (свойство Имя) и признаком того, что данный параметр необходимо указывать в обязательном порядке (свойство Обязательный). Типом любого параметра внешней системы будет Строка. Состав параметров зависит от соответствующего модуля интеграции системы взаимодействия.
29.5.2.2.3. Параметры интеграции
Общая информация
В данном разделе содержится краткое описание параметров различных типов интеграций системы взаимодействия.
Telegram
|
Параметр |
Описание |
|
|
Токен, который необходим для использования
программный интерфейс Telegram. Возвращается ботом Токен должен быть уникален среди всех информационных баз, зарегистрированных в используемом сервере взаимодействия. Другими словами, один бот Telegram не может быть подключен к разным информационным базам одного сервера взаимодействия. |
ВКонтакте
|
Параметр |
Описание |
|
|
Идентификатор группы ВКонтакте, который формируется при создании группы ВКонтакте. |
|
|
Ключ доступа, который необходим для того, чтобы система взаимодействия могла пользоваться программный интерфейс ВКонтакте. |
|
Параметр |
Описание |
|
|
Заголовок чата в WhatsApp. |
|
|
Токен доступа, полученный от провайдера. Необходим для того, что система взаимодействия могла использовать программный интерфейс WhatsApp. |
Чат на сайте
|
Параметр |
Описание |
|
|
Допустимые значения: Значение по умолчанию: Значение Значение Значение Если на сервере системы
взаимодействия видеозвонки недоступны или чат подключен по протоколу HTTP,
то значением данного параметра считается |
|
|
Допустимые значения: Значение по умолчанию: Цветовая схема окна с чатом. По умолчанию используется такая же тема, что и в веб-браузере. |
|
|
Допустимые значения: Значение по умолчанию: Параметр включает или выключает камеру клиентского устройства при начале видеозвонка. |
|
|
Допустимые значения: Значение по умолчанию: Задает возможность отображения картинок пользователей в чате. |
|
|
Обязательный параметр. Язык локализации чата (включая служебные сообщения). Задается 2-х или 4-х буквенным кодом ISO. Подробно список можно посмотреть в стандартной обработке управления системой взаимодействия. |
|
|
Допустимые значения: Значение по умолчанию: Указывает положение кнопки чата в мобильной версии: слева-снизу или слева-сверху. |
|
|
Допустимые значения: Значение по умолчанию: Указывает ориентацию чата. |
|
|
Допустимые значения: 0, 50, 100. Значение по умолчанию: 100. Указывает вертикальное положение чата. |
|
|
Ключ подписи, который используется для сопоставления пользователя чата и системы взаимодействия. Описание работы параметра см. здесь. |
|
|
Значение по умолчанию: Позволяет указать фоновый цвет заголовка чата. |
|
|
Значение по умолчанию: пустая строка. Задается текст, который будет отображаться в заголовке чата. |
|
|
Значение по умолчанию: Позволяет указать цвет символов заголовка чата. |
В таблице подчеркиванием выделено имя параметра, значение которого должно быть указано в обязательном порядке.
MAX
|
Параметр |
Описание |
|
|
Токен, который необходим для использования
программного интерфейса MAX. Возвращается ботом Токен должен быть уникален среди всех информационных баз, зарегистрированных в используемом сервере взаимодействия. Другими словами, один бот MAX не может быть подключен к разным информационным базам одного сервера взаимодействия. |
29.5.2.2.4. Создание интеграции и ее свойства
Зная тип внешней системы и параметры этой системы, можно создать интеграцию. Для этого следует использовать метод СистемаВзаимодействия.СоздатьИнтеграцию(). Затем необходимо заполнить все параметры создаваемой интеграции и сохранить этот объект. Интеграция описывается объектом типа ИнтеграцияСистемыВзаимодействия. При создании интеграции необходимо указать следующие свойства:
● ТипВнешнейСистемы ‑ строка, которая содержит имя внешней системы (мессенджера), с которым создается интеграция. Значение свойства должно в точности совпадать с одним из значений, которое получено в результате вызова функции ПолучитьТипыВнешнихСистем().
● Ключ ‑ значение, позволяющее однозначно идентифицировать создаваемую интеграцию в рамках информационной базы.
● Использование ‑ признак того, что создаваемая интеграция будет использоваться системой взаимодействия.
● ПараметрыВнешнейСистемы ‑ содержит соответствие, в котором каждая пара КлючИЗначение содержит информацию по одному параметру внешней системы. Обязательные параметры должны быть указаны в любом случае, а необходимость заполнять остальные параметры зависит от используемой внешней системы.
● Представление ‑ строка, которая описывает создаваемую интеграцию и является человекочитаемым текстом. Данный текст не является представлением пользователя интеграции в мессенджере.
● Участники ‑ список пользователей системы взаимодействия, которые будут получать оповещения о новых сообщениях в создаваемом обсуждении. Участниками обсуждения могут быть как реальные пользователи системы (конкретные физические лица), так и боты, реализованные в прикладном решении. Причем бот может быть единственным участником обсуждения по умолчанию. Других пользователей бот может подключать после анализа начального сообщения пользователя внешней системы. Про создание ботов в системе «1С:Предприятие» ‑ см. здесь, а про подключение бота к интеграции с внешней системой ‑ см. здесь.
● Идентификатор ‑ значение типа ИдентификаторСистемыВзаимодействия, который создается в момент записи новой интеграции в информационную базу. Идентификатор создается сервером системы взаимодействия.
Собственно интеграция создается при первом сохранении объекта ИнтеграцияСистемыВзаимодействия с помощью метода Записать(). После записи интеграции, некоторые свойства этого объекта заполняются значениями, описывающими возможности созданной интеграции.
Свойство ДоступноРедактированиеСообщения определяет возможность редактирования сообщений, которые помещаются в обсуждения, связанные с данной интеграцией. Значение свойства определяется типом интеграции и не может быть изменено разработчиком. Если данное свойство установлено в значение Ложь, то попытка изменения уже существующего сообщения будет невозможна (при вызове метода Записать() будет формироваться исключение).
Свойство ДоступныВидеоконференции определяет возможность совершения видеозвонков для пользователей данной интеграции. Значение свойства определяется типом интеграции и не может быть изменено разработчиком. Если данное свойство установлено в значение Истина ‑ пользователь интеграции может совершать видеозвонки. Если в качестве внешней системы выступает чат на сайте (тип внешней системы WebChat), то данное свойство будет установлено в значение Истина только в том случае, если параметр интеграции allowVideoconferences установлен в значение true.
Свойство НавигационнаяСсылкаТочкиПодключения содержит URL, который должен быть предоставлен внешней системе в случае необходимости:
● При использовании webhook значением данного свойства является адрес, к которому внешняя система будет выполнять POST-запрос.
● При использовании чата, значение данного свойства должно быть указано в тексте клиентской части сайта для того, чтобы сайт смог загрузить реализацию чата.
29.5.2.3. Шаблоны сообщений WhatsApp
Взаимодействие с WhatsApp может быть организовано только в рамках бизнес-аккаунта. Создание бизнес-аккаунтов доступно с помощью авторизованных провайдеров данной услуги. Для систем на базе «1С:Предприятие» реализована поддержка провайдера «Девино Телеком» (https://www.devinotele.com/ru/).
Интеграция в рамках бизнес-аккаунта накладывает некоторые ограничения:
● Произвольный ответ на вопрос пользователя допускается в интервал времени, не превышающий 24 часа с момента последнего сообщения пользователя в чате. Этот интервал будем называть «период произвольного ответа» (возможно сокращение ППО).
● После закрытия этого окна отправить сообщение можно только с помощью шаблонных сообщений.
● Создание шаблонных сообщений возможно только через веб-интерфейс, который предоставляется провайдером. Шаблонные сообщения должны пройти одобрение в WhatsApp.
● Сообщение, отправленное в чат мессенджера, нельзя редактировать.
● Зная номер телефона пользователя, система «1С:Предприятие» может первой начать взаимодействие. В качестве сообщения может выступать только шаблонная фраза. Пример такого действия будет приведен далее в этом разделе.
Кроме этих особенностей, система «1С:Предприятие» накладывает собственные ограничения на взаимодействие:
● Не поддерживаются команды в сообщениях.
Несмотря на то, что шаблоны сообщений создаются на стороне провайдера, «1С:Предприятие» предоставляет программный интерфейс, который упрощает использование этих шаблонов.
Во-первых, менеджер системы взаимодействия позволяет получить время окончания ППО. Для этого предназначен метод ПолучитьВремяОкончанияДоступностиОтвета()/ПолучитьВремяОкончанияДоступностиОтветаАсинх(). Данный метод вернет время окончания ППО в часовом поясе текущего компьютера. Если метод используется для других типов интеграции, то будет возвращаться значение Неопределено.
Во-вторых, система позволяет получить шаблоны, которые будут использоваться для формирования ответов. Для этого необходимо использовать метод ПолучитьШаблоныСообщения()/ПолучитьШаблоныСообщенияАсинх() менеджера системы взаимодействия. При первом вызове этого метода, сервер системы взаимодействия обращается к провайдеру, получает одобренные шаблоны и сохраняет их в своей базе данных. Затем эти шаблоны передаются в систему «1С:Предприятие». Сервер системы взаимодействия регулярно выполняет актуализацию списка одобренных шаблонов. Таким образом, хранение шаблонов в системе «1С:Предприятие» не выполняется (и не требуется).
Шаблоны сообщений возвращаются в виде массива объектов типа ШаблонСообщенияСистемыВзаимодействия. Рассмотрим подробнее данный объект. Этот объект обладает определенных набором свойств (все свойства доступны только для чтения):
|
Свойство |
Описание |
|
|
Значение типа |
|
|
Имя шаблона, как оно задано на стороне провайдера. |
|
|
Код языка, на котором задан шаблон. Код языка задается на стороне провайдера. Могут быть шаблоны одного сообщения на разных языках. Код задается строкой. |
|
|
Строка, которая является собственно
шаблоном сообщения. В рамках этого шаблона допускаются параметры, которые
называются подстановками и в теле шаблона определяются двойными
фигурными скобками, в которых указывается цифровой номер подстановки.
Номера должны начинаться с 1 и не должны иметь пропусков
в нумерации. Строка может иметь вид: |
|
|
Строка, которая может содержать представление шаблона в виде, понятном пользователю системы «1С:Предприятие». |
|
|
Фиксированный массив, в котором
каждый элемент массива содержит текстовое описание каждого параметра. Эти
представления могут использоваться для диалога формирования собственно
сообщения. Для примера шаблона (из описания свойства ●
●
●
Соответствие номера параметра и элемента массива выполняется по индексу, который вычисляется как «номер параметра ‑ 1». |
Имеется возможность запомнить идентификатор конкретного шаблона и, при необходимости, получить этот шаблон с помощью метода ПолучитьШаблонСообщения()/ПолучитьШаблонСообщенияАсинх(), указав требуемый идентификатор шаблона.
При формировании шаблонного сообщения системы взаимодействия, которое будет отправлено в интеграцию с мессенджером WhatsApp, необходимо выполнить следующие действия:
1. Получить нужный шаблон сообщения.
2. Создать сообщение системы взаимодействия для требуемой интеграции.
3. В сообщении указать свойство ШаблонСообщения. Для этого следует использовать идентификатор шаблона сообщения. Если указано данное свойство, то при записи сообщения будут игнорироваться следующие свойства сообщения: Текст, Вложения, Данные и Действия.
4. Указать свойство сообщения ЗначенияПодстановокШаблонаСообщения. В этом свойстве находится массив значений, которые будут заменять собой параметры в шаблоне. Заменой занимается непосредственно сервер мессенджера WhatsApp. Для сохраненного сообщения это свойство будет содержать параметры, которые были указаны в момент создания сообщения.
При вызове метода сообщения Записать() выполняется отправка сообщения на сервера системы WhatsApp, где и выполняется подстановка значений и публикация сообщения в чате мессенджера.
Для указания представлений (как шаблона, так и подстановок) следует использовать метод менеджера системы взаимодействия УстановитьПредставлениеШаблонаСообщения()/УстановитьПредставлениеШаблонаСообщенияАсинх(). Методу следует указать идентификатор шаблона, а также представление собственно шаблона (формальный параметр ПредставлениеШаблона) и подстановок (формальный параметр ПредставленияПодстановок). Представления подстановок указываются в виде массива. Представления запоминаются сервером системы взаимодействия и при следующем получении шаблона сообщения, все ранее указанные представления будут сохранены.
Если для формирования шаблонного сообщения необходимы интерактивные действия пользователя, то система «1С:Предприятие» предоставляет возможность использовать для этого системный диалог или реализовать таковой c помощью средств конфигурирования.
Формирование диалога начинается с создания обработчика события ОбработкаВыбораШаблонаСообщенияСистемыВзаимодействия модуля приложения. Обработчик этого события получает управление в том случае, когда пользователь выбирает команду Отправить шаблонное сообщение. В формальном параметре Обсуждение обработчик получает идентификатор обсуждения системы взаимодействия, в котором будет создано шаблонное сообщение. Параметр СтандартнаяОбработка отвечает за необходимость отображения стандартного диалога отправки шаблонного сообщения. Если в рамках создаваемого диалога необходимо получить текст сообщения (с выполненными подстановками) для предварительного просмотра, то это можно сделать с помощью метода ПолучитьТекстСПодстановками() объекта ШаблонСообщенияСистемыВзаимодействия.
Для того, чтобы первым начать обсуждение, зная номер телефона пользователя, можно использовать следующий код:
// Создаем обсуждение с внешним идентификатором, // поэтому требуется привилегированный режим УстановитьПривилегированныйРежим(Истина); Обсуждение = СистемаВзаимодействия.СоздатьОбсуждение(); Обсуждение.Интеграция = ИдентификаторИнтеграции; Обсуждение.ВнешнийИдентификатор = ТелефонПользователя; Обсуждение.Записать(); Сообщение = СистемаВзаимодействия.СоздатьСообщение(Обсуждение.Идентификатор); Сообщение.ШаблонСообщения = ИдентификаторШаблонаСообщения; Сообщение.ЗначенияПодстановокШаблонаСообщения.Добавить(ЗначениеПодстановки); Сообщение.Записать();
В данном примере используются следующие переменные:
● ИдентификаторИнтеграции ‑ значение типа ИдентификаторИнтеграцииСистемыВзаимодействия. Значение может быть получено из свойства Идентификатор объекта ИнтеграцияСистемыВзаимодействия, описывающая интеграцию с WhatsApp.
● ТелефонПользователя ‑ значение типа Строка. Значение содержит номер пользователя в международном формате, без лидирующего символа «+», например 78881234567.
● ИдентификаторШаблонаСообщения ‑ тип ИдентификаторШаблонаСообщенияСистемыВзаимодействия. Идентификатор шаблона сообщения, которое будет отображаться пользователю WhatsApp.
● ЗначениеПодстановки ‑ тип произвольный. Значение, которое используется для формирования результирующего сообщения.
29.5.3. Действия во внешних системах для создания интеграции
29.5.3.1. Общая информация
В данном разделе будут описаны действия, которые необходимо выполнить во внешней системе для того, чтобы система взаимодействия смогла взаимодействовать с этой внешней системой.
29.5.3.2. Telegram
Внимание! Описание работы с внешней системой приводится по состоянию на момент написания документации.
Для того чтобы система взаимодействия могла интегрироваться с Telegram, необходимо в мессенджере создать бота, который будет представлять систему взаимодействия. Для этого в мессенджере необходимо выполнить следующие действия:
1. Найдите в Telegram бота BotFather (или перейдите по ссылке https://telegram.me/botfather).
2. Прочитав текст приветствия, начните общение с ботом нажатием кнопки Запустить в чате (в мессенджере Telegram).
3. Введите команду создания нового бота /newbot или выберите соответствующую гиперссылку в списке команд.
4. Введите имя бота в ответ на запрос бота. Введенный текст будет являться представлением создаваемого бота в Telegram.
5. В ответ на запрос бота введите идентификатор бота. Это имя должно:
● заканчиваться на суффикс bot;
● быть уникальным в рамках Telegram.
6. Telegram создаст бота и сообщит токен, который потребуется для того, чтобы внешнее (по отношению к Telegram) приложение смогло использовать HTTP API мессенджера Telegram. Сохраните это значение, оно потребуется для создания интеграции в системе взаимодействия. Рекомендуется относиться к данному ключу как к конфиденциальной информации.
После создания бота в Telegram, необходимо создать интеграцию в информационной базе. Для этого следует открыть стандартную обработку Управление системой взаимодействия и в ней:
1. Выбрать гиперссылку Интеграции.
2. Добавить новую интеграцию.
3. Указать представление бота Telegram в системе взаимодействия (поле Наименование).
4. В поле Тип внешней системы выбрать Telegram.
5. Разрешите использование интеграции (установить флажок Использование).
6. В параметрах необходимо указать токен, который предоставил бот BotFather при создании нашего бота, в качестве значения параметра token.
7. Затем необходимо указать пользователей, которые по умолчанию будут участниками группового обсуждения в системе взаимодействия (таблица Участники обсуждения по умолчанию). Если не указать пользователей, то сообщения из Telegram никто не увидит.
8. Нажатие кнопки ОК создает интеграцию и подключает систему взаимодействия к мессенджеру Telegram.
29.5.3.3. ВКонтакте
Внимание! Описание работы с веб-интерфейсом приводится по состоянию на момент написания документации.
Для того чтобы система взаимодействия могла интегрироваться с ВКонтакте, пользователь, выполняющий действия в веб-интерфейсе ВКонтакте, должен обладать правами администратора сообщества. Для создания интеграции, необходимо получить идентификатор группы ВКонтакте и специальный токен. Для этого в веб-интерфейсе ВКонтакте необходимо выполнить следующие действия:
1. На сайте ВКонтакте (https://vk.com) перейти на страницу управления выбранным сообществом (или создайте новое сообщество).
2. Перейти на страницу Управление ‑ Настройки ‑ Работа с API ‑ Ключи доступа.
3. На этой странице нажать кнопку Создать ключ. При создании ключа обязательно укажите флаги:
● Разрешить приложению доступ к управлению сообществом.
● Разрешить приложению доступ к сообщениям сообщества.
● Разрешить приложению доступ к документам.
4. Нажать кнопку Создать для фактического создания ключа доступа. Созданный ключ доступа необходимо сохранить, оно потребуется для создания интеграции в системе взаимодействия. Рекомендуется относиться к данному ключу как к конфиденциальной информации.
5. Перейти на страницу Управление ‑ Настройки ‑ Работа с API ‑ Callback API. На этой странице необходимо получить идентификатор созданной группы. Для этого надо найти на странице текст вида {"type": "confirmation", "group_id": 123456789 }. В этом тексте число 123456789 ‑ это и есть идентификатор группы, который нужно запомнить.
6. Перейти на страницу Управление ‑ Настройки ‑ Сообщения. На этой странице нужно установить параметр Сообщения сообщества в значение Включено и нажать кнопку Сохранить.
После выполнения необходимых действий в ВКонтакте, необходимо создать интеграцию в информационной базе. Для этого следует открыть стандартную обработку Управление системой взаимодействия и в ней:
1. Выбрать гиперссылку Интеграции.
2. Добавить новую интеграцию.
3. Указать представление сообщества ВКонтакте в системе взаимодействия (поле Наименование).
4. В поле Тип внешней системы выбрать VK.
5. Разрешите использование интеграции (установить флажок Использование).
6. В таблице Параметры указать параметры интеграции:
● В параметр groupID указать идентификатор группы ВКонтакте.
● В параметр token указать ключ доступа группы ВКонтакте.
7. Затем необходимо указать пользователей, которые по умолчанию будут участниками группового обсуждения в системе взаимодействия (таблица Участники обсуждения по умолчанию). Если не указать пользователей, то сообщения из группы ВКонтакте никто не увидит.
8. Нажатие кнопки ОК создает интеграцию и подключает систему взаимодействия к системе ВКонтакте.
29.5.3.4. WhatsApp
ВНИМАНИЕ! Описание работы с веб-интерфейсом приводится по состоянию на момент написания документации.
Для того чтобы система взаимодействия могла интегрироваться с WhatsApp, необходимо заключить договор с провайдером WhatsApp Business API ‑ компанией «Девино Телеком». Описание действий, необходимых для заключения договора и получения необходимых данных, приведено по ссылке: https://v8.1c.ru/static/instruktsiya-po-podklyucheniyu-k-whatsapp-business-api/.
После выполнения необходимых действий в личном кабинете «Девино Телеком», необходимо создать интеграцию в информационной базе. Для этого следует открыть стандартную обработку Управление системой взаимодействия и в ней:
1. Выбрать гиперссылку Интеграции.
2. Добавить новую интеграцию.
3. Указать представление канала WhatsApp в системе взаимодействия (поле Наименование).
4. В поле Тип внешней системы выбрать WHATSAPP_DEVINO.
5. Разрешите использование интеграции (установить флажок Использование).
6. В таблице Параметры указать параметры интеграции:
● В параметр channel указать имя канала, через который будет выполняться коммуникация.
● В параметр token указать токен (ключ доступа), полученный от компании «Девино Телеком».
7. Затем необходимо указать пользователей, которые по умолчанию будут участниками группового обсуждения в системе взаимодействия (таблица Участники обсуждения по умолчанию). Если не указать пользователей, то сообщения из WhatsApp никто не увидит.
8. Нажатие кнопки ОК создает интеграцию и подключает систему взаимодействия к мессенджеру WhatsApp.
9. После настройки интеграции, необходимо значение поля Навигационная ссылка точки подключения (поле расположено ниже списка интеграций) передать вашему менеджеру «Девино Телеком».
29.5.3.5. MAX
Внимание! Описание работы с внешней системой приводится по состоянию на момент написания документации.
Для того чтобы система взаимодействия могла интегрироваться с MAX, необходимо подключиться к платформе "MAX для партнеров" на сайте https://business.max.ru/:
● Создание организации описывается на странице: https://dev.max.ru/docs/maxbusiness/connection.
● Создание бота описывается здесь: https://dev.max.ru/docs/chatbots/bots-create.
● После модерации необходимо получить токен бота, который будет использоваться при создании интергации в прикладном решении.
После создания бота в MAX, необходимо создать интеграцию в информационной базе. Для этого следует открыть стандартную обработку Управление системой взаимодействия и в ней:
1. Выбрать гиперссылку Интеграции.
2. Добавить новую интеграцию.
3. Указать представление бота MAX в системе взаимодействия (поле Наименование).
4. В поле Тип внешней системы выбрать MAX.
5. Разрешите использование интеграции (установить флажок Использование).
6. В параметрах необходимо указать токен, который получен в личном кабинете при создании нашего бота, в качестве значения параметра token.
7. Затем необходимо указать пользователей, которые по умолчанию будут участниками группового обсуждения в системе взаимодействия (таблица Участники обсуждения по умолчанию). Если не указать пользователей, то сообщения из MAX никто не увидит.
8. Нажатие кнопки ОК создает интеграцию и подключает систему взаимодействия к мессенджеру MAX.
29.5.4. Использование webhook
29.5.4.1. Схема использования webhook
Как было сказано ранее, при использовании вебхуков, интеграция работает только в одну сторону: сообщения передаются со стороны внешней системы в систему взаимодействия и, затем, в прикладное решение.
Пользователь, который будет олицетворять систему, которая отправляет сообщения в прикладное решение, будет называться пользователем интеграции. Для того, чтобы внешняя система могла пользоваться вебхуком, ей необходимо сообщить адрес точки подключения, который можно получить с помощью метода ИнтеграцияСистемыВзаимодействия.НавигационнаяСсылкаТочкиПодключения(). Этот адрес следует использовать при настройки системы, которая будет отправлять сообщения.
После того, как сообщение от внешней системы попадает в точку подключения, выполняются следующие действия:
● Тело сообщения разбирается.
● Создается пользователь интеграции, если он еще не создан.
В качестве имени пользователя интеграции выступает:
● Имя пользователя, переданное в сообщении createUser.
● Имя экземпляра интеграции, если в сообщении внешней системы не указан пользователь (автор сообщения).
● Создается обсуждение системы взаимодействия, если оно еще не создано.
● В качестве участников обсуждения выступают:
● Пользователь интеграции.
● Пользователи, заданные при настройке интеграции как участники по умолчанию.
● Если необходимо, чтобы сообщения попадали в заранее созданное обсуждение с выбранным составом участников, то следует:
● Предварительно создать обсуждение с помощью встроенного языка.
● Передать идентификатор созданного обсуждения внешней системе, чтобы эта система использовала этот идентификатор в своих сообщениях. Строковое представление идентификатора обсуждения можно получить с помощью функции Строка(), параметром которой выступает объект типа ОбсуждениеСистемыВзаимодействия.Идентификатор.
● В обсуждение добавляется сообщение, автором которого является пользователь интеграции и содержимое определено сообщением внешней системы.
29.5.4.2. Поддерживаемые команды
29.5.4.2.1. Общая информация
В качестве команды выступает POST-запроса внешней системы. Этот запрос должен удовлетворять следующим требованиям:
● Тело запроса формируется в кодировке UTF-8 без BOM.
● Тело запроса представляет собой JSON-документ.
● Тело запроса, в общем, имеет следующий вид:
{ "command" : { "param1": value1, … "paramN": valueN } }
Если в команде допускается текст в формате HTML, то в этом случае поддерживаются следующие возможности оформления:
● Поддерживаемые элементы: a, b, big, font, i, li, ol, s, small, span, strike, strong, u, ul.
● Атрибут элемента style: background-color, color, font-family, font-size, font-style, font-weight, text-decoration.
Результат выполнения команды отражается кодом возврата:
● 200 OK ‑ команда выполнена успешно.
● 404 No active integration ‑ интеграция не найдена или не активна.
● 409 Conflict ‑ при вызове команды create… для уже существующего объекта.
● 500 <Текст ошибки> ‑ при обработке команды произошла ошибка.
Далее в разделе будет описаны форматы команд.
29.5.4.2.2. createConversation
Описание:
Создает новое обсуждение.
Синтаксис:
{ "createConversation": { "extConversationId": "1", "title": "Заголовок обсуждения", "extUserId": "1", "members": [ "1" ] } }
Параметры:
● extConversationId ‑ внешний идентификатор создаваемого обсуждения.
● title ‑ заголовок создаваемого обсуждения (в виде строки).
● extUserId ‑ внешний идентификатор пользователя, от имени которого создается обсуждение.
Если не задан, то будет создан пользователь системы взаимодействия с именем, совпадающим с именем интеграции, и он будет добавлен в обсуждение. В этом случае во всех запросах, относящихся к этому обсуждению, не должны быть указаны параметры extUserId, members, addMembers, removeMembers.
Необязательный параметр.
● members ‑ массив внешних идентификаторов пользователей, которые являются участниками обсуждения со стороны внешней системы.
Необязательный параметр.
29.5.4.2.3. createMessage
Описание:
Создает новое сообщение в обсуждении.
Синтаксис:
{ "createMessage": { "extId": "1", "text": "Тест сообщения", "textFormat": "text/plain", "extUserId": "1", "extConversationId": "1", "data": "", "dataType": "" } }
Параметры:
● data ‑ произвольные данные, прикрепляемые к сообщению.
Необязательный параметр.
● dataType ‑ тип MIME, описывающий данные, указанные в параметре data.
Необязательный параметр.
● extConversationId ‑ внешний идентификатор обсуждения, в котором создается сообщение.
● extId ‑ внешний идентификатор создаваемого сообщения.
● extUserId ‑ внешний идентификатор пользователя-автора сообщения.
Если не задан, то будет создан пользователь системы взаимодействия с именем, совпадающим с именем интеграции, и он будет добавлен в обсуждение. В этом случае во всех запросах, относящихся к этому обсуждению, не должны быть указаны параметры extUserId, members, addMembers, removeMembers.
Необязательный параметр.
● text ‑ текст сообщения.
● textFormat ‑ формат текста сообщения. Возможные значения: text/plain, text/html. Значение по умолчанию ‑ text/plain.
Необязательный параметр.
При создании сообщения с помощью данного метода, разработчик может запрограммировать передачу следующих файлов:
● Картинки. Собственно картинка передается значением свойства data в формате Base64. В свойстве dataType необходимо указать корректный тип MIME для переданной картинки.
● Любые двоичные данные. Данные передаются значением свойства data в формате Base64. В свойстве dataType необходимо указать значение application/octet-stream.
● Значение системы «1С:Предприятие», поддерживающее XDTO-сериализацию. Данные передаются значением свойства data в формате JSON. В свойстве dataType необходимо указать значение application/json+xdto.
● Любая строка. Данные находятся в свойстве data. В свойстве dataType необходимо указать корректное значение типа MIME.
При формировании объекта СообщениеСистемыВзаимодействия на основании команды createMessage, свойства Данные и ФорматДанныхСтроки заполняются следующим образом:
● Если параметр dataType содержит тип MIME image/*:
● В свойство Данные помещается значение типа Картинка, сформированная на основании значения параметра data.
● В свойство ФорматДанныхСтроки помещается Неопределено.
● Если параметр dataType содержит тип MIME application/octet-stream:
● В свойство Данные помещается значение типа ДвоичныеДанные, сформированная на основании значения поля data.
● В свойство ФорматДанныхСтроки помещается Неопределено.
● Если формат данных сообщения application/json+xdto:
● В свойство Данные помещается значение, которое является результатом XDTO-десериализации строки из параметра data.
● В свойство ФорматДанныхСтроки помещается Неопределено.
● В остальных случаях:
● В свойство Данные помещается значение параметра data.
● В свойство ФорматДанныхСтроки помещается значение параметра dataType.
29.5.4.2.4. createUser
Описание:
Создает пользователя интеграции в системе взаимодействия.
Синтаксис:
{ "createUser" : { "extUserId": , "name": , "fullName": , "picture": } }
Параметры:
● extUserId ‑ внешний идентификатор внешнего пользователя.
● name ‑ короткое имя внешнего пользователя (в виде строки).
● fullName ‑ полное имя внешнего пользователя (в виде строки). Может быть пустой строкой.
● picture ‑ картинка пользователя в виде строки в формате Base64. Необязательный параметр.
29.5.4.2.5. updateConversation
Описание:
Изменяет параметры обсуждения. Позволяет изменить заголовок обсуждения, а также добавить или удалить пользователей обсуждения.
Синтаксис:
{ "updateConversation": { "extConversationId": "1", "title": "Новый заголовок обсуждения", "extUserId": "5", "addMembers": [ "5" ], "removeMembers": [ "1" ] } }
Параметры:
● extConversationId ‑ внешний идентификатор изменяемого обсуждения.
● title ‑ заголовок обсуждения.
Необязательный параметр.
● extUserId ‑ внешний идентификатор пользователя, от имени которого изменяется обсуждение.
Если не задан, то будет создан пользователь системы взаимодействия с именем, совпадающим с именем интеграции, и он будет добавлен в обсуждение. В этом случае во всех запросах, относящихся к этому обсуждению, не должны быть указаны параметры extUserId, members, addMembers, removeMembers.
Необязательный пользователь.
● addMembers ‑ массив внешних идентификаторов пользователей, которые будут добавлены к участникам обсуждения.
Необязательный параметр.
● removeMembers ‑ массив внешних идентификаторов пользователей, которые будут удалены из участников обсуждения.
Необязательный параметр.
29.5.4.2.6. updateMessage
Описание:
Изменяет существующее сообщение.
Синтаксис:
{ "updateMessage": { "extId": "1", "text": "Тест сообщения", "textFormat": "text/plain", "extUserId": "1", "extConversationId": "1" } }
Параметры:
● extId ‑ внешний идентификатор изменяемого сообщения.
● text ‑ текст сообщения.
● textFormat ‑ формат текста сообщения. Возможные значения: text/plain, text/html.
Необязательный параметр. Значение по умолчанию ‑ text/plain.
● extUserId ‑ внешний идентификатор пользователя-автора сообщения.
Если не задан, то будет создан пользователь системы взаимодействия с именем, совпадающим с именем интеграции, и он будет добавлен в обсуждение. В этом случае во всех запросах, относящихся к этому обсуждению, не должны быть указаны параметры extUserId, members, addMembers, removeMembers.
Необязательный параметр.
● extConversationId ‑ внешний идентификатор обсуждения, в котором изменяется сообщение.
29.5.4.2.7. updateUser
Описание:
Обновляет параметры пользователя интеграции в системе взаимодействия.
Синтаксис:
{ "updateUser" : { "extUserId": , "name": , "fullName": , "picture": } }
Параметры:
● extUserId ‑ внешний идентификатор внешнего пользователя.
● name ‑ новое короткое имя внешнего пользователя (в виде строки). Необязательный параметр.
● fullName ‑ новое полное имя внешнего пользователя (в виде строки). Необязательный параметр.
● picture ‑ новая картинка пользователя в виде строки в формате Base64. Необязательный параметр.
29.5.5. Чат на сайте
29.5.5.1. Общая информация
Данный способ интеграции предназначен для решения следующей задачи: необходимо обеспечить возможность для пользователя некоторого сайта общаться с компанией, которая использует этот сайт для выполнения своей деятельности. На сайте может быть интернет-магазин, витрина с примерами продукции и т. д.
Для того, чтобы реализовать такую интеграцию, необходимо выполнить следующие действия:
1. Доработать реализацию сайта (как клиентскую, так и серверную части) так, чтобы на этом сайте пользователь смог начать разговор в чате. При необходимости, код сайта может использовать программный интерфейс чата для выполнения некоторых действий.
2. Создать нужный тип интеграции в системе «1С:Предприятие».
3. Реализовать на встроенном языке системы «1С:Предприятие» требуемое взаимодействие с чатом, если необходимо. Если чат используется только в режиме мессенджера (т. е. только для интерактивного обмена текстовыми сообщениями) ‑ никаких дополнительных действий выполнять не требуется.
29.5.5.2. Интерфейс чата
Для того, чтобы подключить чат к веб-сайту, необходимо в код веб-сайта вставить следующий фрагмент кода:
URL точки подключения можно получить или при создании интеграции (в стандартной обработке управления системой взаимодействия) или с помощью метода НавигационнаяСсылкаТочкиПодключения() объекта типа ИнтеграцияСистемыВзаимодействия.
После загрузки интерфейса чата, в глобальном контексте сайта становится доступен объект CollaborationSystemWebChat1CE (типа CollaborationSystemWebChat1CEClass). Через этот объект возможно взаимодействие с чатом.
Объект CollaborationSystemWebChat1CE предоставляет следующие методы:
open()
Описание:
Разворачивает окно чата.
Возвращаемое значение:
void.
close()
Описание:
Сворачивает окно чата.
Возвращаемое значение:
void.
setContactInfo(<contactInfo>)
Описание:
Устанавливает контактные данные пользователя.
Параметры:
contactInfo обязательный
Тип: Object.
Объект, содержащий значения полей контактных данных пользователя. Объект содержит следующие свойства:
● name ‑ тип String ‑ содержит имя пользователя.
● fullName ‑ тип String ‑ содержит полное имя пользователя.
● email ‑ тип String ‑ содержит адрес электронной почты пользователя.
● phone ‑ тип String ‑ содержит номер телефона пользователя.
Возвращаемое значение:
void.
getContactInfo()
Описание:
Возвращает поданные пользователем в форме представления контактные данные.
Возвращаемое значение:
Promise<Object>. Результатом выполнения обещания является значение типа Object, которое содержит следующие свойства:
● name ‑ тип String ‑ содержит имя пользователя.
● fullName ‑ тип String ‑ содержит полное имя пользователя.
● email ‑ тип String ‑ содержит адрес электронной почты пользователя.
● phone ‑ тип String ‑ содержит номер телефона пользователя.
setMatchingKeyToken(<matchingKeyToken>)
Описание:
Устанавливает токен с ключом сопоставления пользователя системы взаимодействия и пользователя на сайте.
Параметры:
matchingKeyToken обязательный
Тип: String.
Токен, содержащий ключ сопоставления пользователя системы взаимодействия и пользователя на сайте. Токен может быть подписан (JWS) с использованием созданного в параметрах интеграции ключа подписи signKey или не подписан (JWT). Данный ключ сопоставления будет доступен через свойство ИдентификаторПользователяВнешнейСистемы типа ПользовательСистемыВзаимодействия.
Возвращаемое значение:
void.
logout()
Описание:
Осуществляет завершение сеанса для текущего в чате пользователя.
Возвращаемое значение:
Promise<void>. Результатом выполнения обещания является значение типа void.
isVideoconferenceEnabled()
Описание:
Возвращает информацию о доступности видеозвонков.
Возвращаемое значение:
Promise<Boolean>. Результатом выполнения обещания является значение типа Boolean:
● true ‑ видеозвонки доступны.
● false ‑ видеозвонки не доступны.
startVideoconference()
Описание:
Начинает видеозвонок пользователя сайта пользователю системы «1С:Предприятие».
Возвращаемое значение:
Promise<Boolean>. Результатом выполнения обещания является значение типа Boolean:
● true ‑ видеозвонок начался.
● false ‑ видеозвонок был отменен.
sendMessage(<message>)
Описание:
Отправляет текст сообщения.
Параметры:
Message обязательный
Тип: Object.
Сообщение, которое необходимо отправить в чат. Объект имеет следующие свойства:
● text ‑ тип String -текст сообщения.
● textFormat- тип String ‑ тип сообщения: text/plain или text/html.
Возвращаемое значение:
void.
addListener(<eventType>, <eventListener>)
Описание:
Добавляет обработчик события <event>.
Параметры:
eventType обязательный
Тип: String. Имя события чата (описано далее).
eventListener обязательный
Тип: Function. Содержит ссылку на метод обработчика события.
Возвращаемое значение:
void.
removeListener(<eventType>, <eventListener>)
Описание:
Удаляет обработчик события <event>.
Параметры:
eventType обязательный
Тип: String. Имя события чата (описано далее).
eventListener обязательный
Тип: Function. Содержит ссылку на метод обработчика события.
Возвращаемое значение:
void.
Объект CollaborationSystemWebChat1CE предоставляет возможность обрабатывать следующие события чата:
|
Событие |
Описание |
|
|
Вызывается при закрытии (сворачивании) чата. |
|
|
Вызывается после полной инициализации чата (когда чат полностью готов к работе). |
|
|
Вызывается при открытии (разворачивании) чата. |
|
|
Вызывается при окончании видеозвонка. |
|
|
Вызывается при начале видеозвонка. |
Отдельно остановимся на процессе сопоставления пользователей сайта и системы взаимодействия. Как уже было отмечено ранее, работа системы взаимодействия всегда выполняется от лица какого-либо пользователя. Из этого следует, что любой пользователь, который подключается к системе взаимодействия, должен иметь свое цифровое олицетворение в системе взаимодействия. Однако, пользователь сайта, на котором развернут чат, и пользователь системы взаимодействия (в общем случае) ничего не знают друг о друге.
При выполнении интеграции можно будет использовать один из следующих механизмов интеграции:
● Не выполнять явного соответствия. В этом случае пользователь сайта какое-то время будет «узнаваться» чатом (через механизм хранения данных веб-браузером), но при входе с другого компьютера или через продолжительный промежуток времени будет создан новый пользователь системы взаимодействия. Для такого использования ничего делать не требуется.
● Сопоставлять пользователей. В этом случае необходима доработка не только клиентской части сайта, но и его серверной части. В кратком изложении схема сопоставления выглядит следующим образом: программное обеспечение сайта сообщает серверу взаимодействия уникальный идентификатор пользователя, который сейчас работает на сайте. Сервер взаимодействия по этому идентификатору находит «своего» пользователя и передает сайту сообщения обсуждения с этим пользователем. Теперь рассмотрим эту схему более подробно.
Сайт, на котором развернут чат, должен сообщить системе взаимодействия некоторую информацию, по которой можно однозначно определить, какой пользователь сайта входит в чат. Для этого сайт должен сформировать токен в формате JWT или JWS (JSON Web Signature).
Т. к. JWS ‑ это (фактически) подписанный токен JWT. Таким образом, вначале необходимо сформировать сам токен, полезная нагрузка которого должна содержать следующие претензии:
● sub ‑ в этой претензии должен располагаться уникальный идентификатор пользователя сайта (строковое представление). Это значение в дальнейшем будет в системе «1С:Предприятие» с помощью свойства ПользовательСистемыВзаимодействия.ИдентификаторПользователяВнешнейСистемы.
● iat ‑ в этой претензии размещается время создания JWT по времени сервера сайта, в который интегрируется чат.
JWT должен формироваться на стороне серверной части сайта. Теперь этот токен необходимо передать в чат системы взаимодействия, который передаст эту информацию далее, на сервер взаимодействия. Для такой передачи следует использовать метод чата setMatchingKeyToken(). Сервер взаимодействия извлекает из токена полезную нагрузку и сопоставляет пользователя сайта с пользователем системы взаимодействия. Затем сервер взаимодействия «отдает» сайту содержимое обсуждения для указанного пользователя. Если в процессе работы сайта пользователь сайта меняется (например, текущий пользователь вышел из личного кабинета, а другой пользователь авторизовался), то сайт должен повторить процедуру формирования токена для нового пользователя и повторно выполнить установку ключа сопоставления. После этого содержимое чата обновится.
Описанная выше схема работает в том случае, когда в настройках интеграции не указан параметр signKey.
У рассмотренного метода есть неприятная особенность, связанная с безопасностью интеграции (и данных пользователей). Если предположить, что клиентская часть сайта является ненадежным элементом, то злоумышленник может указать произвольный идентификатор пользователя сайта в претензии JWT и получить доступ к чужим данным.
Чтобы избежать этого, в настройках интеграции следует указать параметр signKey. В этом случае сервер взаимодействия будет ожидать в параметрах метода setMatchingKeyToken() не JWT, а JWS-токен. Также необходимо доработать серверную часть сайта таким образом, чтобы после формирования необходимого JWT, сервер сайта подписывал этот токен (формировал JWS) с помощью ключа, указанного в параметре интеграции signKey. Этот ключ необходимо вручную указать в серверном коде сайта. Формирование JWS должно выполняться с помощью библиотек работы с токенами языка программирования, который используется для разработки серверной части сайта.
В результате указанных доработок клиентская часть не сможет изменить полезную нагрузку JWT без нарушения подписи. Вся остальная схема остается той же: JWS передается в чат с помощью метода setMatchingKeyToken(), чат передает токен на сервер взаимодействия. Только теперь, прежде чем начать поиск пользователя по информации из полезной нагрузки токена, сервер взаимодействия проверит подпись токена. И дальнейшая работа будет возможна только в том случае, если переданный токен не был изменен.
Смотри также:
● JSON Web Signature, веб-подпись JSON: https://datatracker.ietf.org/doc/html/rfc7515.
29.6. Выгрузка и перенос данных
29.6.1. Общая информация
Механика сохранения и восстановления данных служит для переноса информации между различными серверами взаимодействия. В частности, с помощью этого механизма можно переносить информацию из сервиса 1С:Диалог в свой сервер взаимодействия и обратно. Данный механизм не ставит своей целью дать возможность регулярного резервного копирования данных пользователей с целью сохранения данных на случай сбоев. Для резервного копирования базы данных сервера и внешнего хранилища файлов рекомендуется использовать стандартные средства СУБД PostgreSQL и используемого хранилища.
Для выполнения задач миграции служит программный интерфейс системы «1С:Предприятие», который позволяет выполнять операции выгрузки и восстановления данных, а также некоторые сервисные функции.
Выгрузка данных может выполнять в файл, расположенный в файловой системе или в хранилище, которое доступно по протоколу Amazon S3 (далее ‑ хранилище).
Сервер системы взаимодействия по умолчанию позволяет одновременно хранить не более 5 файлов выгрузки данных. Количество хранимых файлов выгрузки настраивается непосредственно в сервере взаимодействия и недоступно для изменения со стороны системы «1С:Предприятие».
29.6.2. Выгрузка данных
Для выполнения операции выгрузки данных следует использовать методы НачатьСозданиеВыгрузкиДанных()/НачатьСозданиеВыгрузкиДанныхАсинх(). В качестве параметра выступает описание создаваемой копии данных. В результате выполнения метода начинается создание файла выгрузки, а в качестве возвращаемого значения выступает идентификатор выгрузки данных (тип ИдентификаторВыгрузкиДанныхСистемыВзаимодействия).
Выгрузка данных может занимать существенное время. Чтобы упростить процесс ожидания, имеется возможность получить описание выгрузки по ее идентификатору (с помощью пары методов ПолучитьВыгрузкуДанных()/ПолучитьВыгрузкуДанныхАсинх()). Результатом работы методов будет объект ВыгрузкаДанныхСистемыВзаимодействия. Свойство этого объекта Статус позволяет мониторить текущее состояние выгрузки данных. Создание выгрузки завершится в том случае, когда свойство ВыгрузкаДанныхСистемыВзаимодействия.Статус станет равно значению СтатусВыгрузкиДанныхСистемыВзаимодействия.Готово.
Кроме получения статуса выполнения выгрузки данных, объект ВыгрузкаДанныхСистемыВзаимодействия дает доступ к следующим данным:
● Идентификатор ‑ идентификатор выгрузки данных.
● ДатаСоздания ‑ дата и время создания (или регистрации) выгрузки данных.
● Описание ‑ произвольное описание выгрузки данных.
● Статус ‑ статус выгрузки данных.
● СтатусВосстановления ‑ статус восстановления данных из данной выгрузки данных, если восстановление не выполнялось или еще не завершено ‑ значение Неопределено.
● ДоступнаВыгрузка ‑ указывает, что файл с выгрузки данных можно загрузить в виде файла.
После окончания создания выгрузки данных может потребоваться получить эту копию в виде файла. Для этого следует выполнить следующие действия:
1. Проверить, что выгрузку данных можно получить в виде файла с помощью свойства ВыгрузкаДанныхСистемыВзаимодействия.ДоступнаВыгрузка.
2. Получить временную ссылку на файл с выгрузкой данных с помощью метода ПолучитьАдресВыгрузкиДанных()/ПолучитьАдресВыгрузкиДанныхАсинх(). Если выгрузка данных создана в хранилище, то ссылка имеет ограниченное время жизни, которое настраивается в самом хранилище. Если выгрузка данных сразу создавалась в виде файла, то метод вернет путь на файловой системе сервера системы взаимодействия.
3. Сохранить файл, доступный по указанной ссылке.
29.6.3. Восстановление данных
Основным сценарием восстановления данных является восстановление из той выгрузки, которая доступна «здесь и сейчас». Другими словами, это выгрузка данных, которая уже находится в списке выгрузок и находится на этом же сервере системы взаимодействия. Для того, чтобы восстановить из такой выгрузки, необходимо получить идентификатор этой копии и воспользоваться одним из методов НачатьВосстановлениеИзВыгрузкиДанных()/НачатьВосстановлениеИзВыгрузкиДанныхАсинх() (подробнее про это написано далее в этом разделе).
Другим возможным сценарием восстановления является случай, когда файл выгрузки данных расположен «отдельно» от сервера системы взаимодействия. Например, сервер был установлен на новый компьютер, но выгрузка со «старого» сервера имеется в доступном файле. В этом случае для того, чтобы восстановить данные на сервере взаимодействия, необходимо выполнить следующие действия:
1. Предоставить серверу взаимодействия файл с выгрузкой данных, которую требуется восстановить. Это можно сделать двумя способами:
1. Загрузить файл выгрузки данных с помощью клиентского приложения. Регистрация файла выгрузки будет выполнена автоматически.
2. Разместить данные на компьютере, на котором развернут сервер системы взаимодействия (для ускорения процесса восстановления) или в хранилище, доступное для сервера системы взаимодействие.
Выполнить регистрацию файла выгрузки данных.
2. Выполнить восстановление данных из зарегистрированной копии.
Для загрузки файла с помощью клиентского приложения следует использовать методы ЗагрузитьВыгрузкуДанных()/ЗагрузитьВыгрузкуДанныхАсинх(). Метод ЗагрузитьВыгрузкуДанныхАсинх() предполагает использование с указанием пути к файлу и без интерактивных действий (диалог выбора файла). Интерактивный выбор файла осуществляется при использовании метода ЗагрузитьВыгрузкуДанныхАсинх(). Параметры диалога задаются с помощью параметра типа ПараметрыДиалогаПомещенияФайлов. Результатом загрузки файла будет идентификатор выгрузки данных.
Если загрузить файл выгрузки данных с помощью клиентского приложения не представляется возможным, то можно обеспечить доступность файла выгрузки для сервера взаимодействия с помощью файловой системы или хранилища S3. После этого необходимо выполнить регистрацию файла выгрузки в сервере взаимодействия с целью получения идентификатора выгрузки данных и для того, чтобы указать серверу, где расположен файл с резервной копией. Для выполнения регистрации используются методы ВыполнитьРегистрациюВыгрузкиДанных()/ВыполнитьРегистрациюВыгрузкиДанныхАсинх().
После получения идентификатора можно выполнить собственно восстановление данных из данных выгрузки. Для этого следует использовать методы НачатьВосстановлениеИзВыгрузкиДанных()/НачатьВосстановлениеИзВыгрузкиДанныхАсинх(). Статус восстановления можно периодически проверять с помощью свойства ВыгрузкаДанныхСистемыВзаимодействия.СтатусВосстановления.
Если потребовалось восстановить данные из выгрузки, которая создавалась на этом же сервере системы взаимодействия, то, очевидно, можно пропустить шаги по загрузке файла и его регистрации. Нужно будет выбрать нужную выгрузку, получить ее идентификатор и выполнить восстановление.
29.6.4. Перенос данных
Перенос данных между двумя различными серверами системы взаимодействия выглядит следующим образом:
1. В сервере взаимодействия, который выступает источником данных, выполняется выгрузка данных.
2. Созданная выгрузка выгружается в файл.
3. Файл выгрузки переносится на сервер взаимодействия, который является приемником данных.
4. Выполняется восстановление данных из полученного файла.
29.6.5. Прочие возможности
Для управления выгрузками данных, кроме методов, непосредственно связанных с выгрузкой и восстановлением данных, могут потребоваться различные вспомогательные функции. Рассмотрим их в этом разделе.
При выборе выгрузки для восстановления, важно понимать, какие выгрузки данных сейчас доступны для использования. Для того, чтобы получить список выгрузок, зарегистрированных для данного абонента сервера взаимодействия, предназначены методы ПолучитьВыгрузкиДанных()/ПолучитьВыгрузкиДанныхАсинх(). В результате выполнения методов будет получен массив, который содержит объекты типа ВыгрузкаДанныхСистемыВзаимодействия.
Для выгрузки данных можно установить описание. Это произвольная текстовая строка, которая в дальнейшем позволит понять, в какой момент (или по какому поводу) выполнена данная выгрузка данных. Установка описания может выполняться как с помощью соответствующего параметра в методах создания и выгрузки, так и с помощью специальных методов УстановитьОписаниеВыгрузкиДанных()/УстановитьОписаниеВыгрузкиДанныхАсинх().
Если выгрузка данных стала не нужна, то ее можно удалить из списка резервных копий с помощью методов УдалитьВыгрузкуДанных()/УдалитьВыгрузкуДанныхАсинх(). При удалении выгрузки данных файл физически с диска (или из хранилища) не удаляется.
29.7. Администрирование
Описание администрирования системы взаимодействия приводится в справке стандартной функции Управление системой взаимодействия.
Документация по развертыванию и администрированию сервера взаимодействия представлена на Портале ИТС (https://its.1c.ru/db/csdoc).
29.8. Безопасность в системе взаимодействия
При работе с системой взаимодействия необходимо понимать, что база данных системы взаимодействия содержит не менее конфиденциальную информацию, чем и информационная база системы «1С:Предприятие», к которой подключена система взаимодействия. Как следствие, относиться к этой базе данных (и доступу к ней) следует исходя из тех же подходов, что и к информационной базе системы «1С:Предприятие».
В то же время, особенности системы взаимодействия накладывают дополнительные требования к организации доступа. К таким дополнительным требованиям относятся:
● Настоятельно не рекомендуется подключать совместное использование вашей информационной базы и любой другой информационной базы, которая вам не знакома или вы не уверены в ее надежности.
● Настоятельно не рекомендуется передавать не использованный код регистрации информационной базы в системе взаимодействия сторонним лицам. Такая ситуация может возникнуть в том случае, если злоумышленник начал регистрацию совместного использования информационных баз и просит администратора абонента сообщить код подтверждения. В системе взаимодействия «код регистрации» выполняет функцию, аналогичную одноразовому коду, который применяется для подтверждения банковских операций, например, во время покупки в Интернет-магазине.
● Если к системе взаимодействия вашей информационной базы подключаются сторонние информационные базы, то не рекомендуется выполнять сопоставление пользователей по имени (это будет выполняться автоматически). Рекомендуется в этом случае выполнять сопоставление по ключу сопоставления пользователя. При этом каждого пользователя будет необходимо сопоставлять вручную. С помощью встроенного языка имеется возможность упростить выполнение такого сопоставления.
Пренебрежение этими рекомендациями может привести к тому, что данные системы взаимодействия станут доступны злоумышленникам. Рассмотрим пример, показывающий возможность получения такого доступа.
Исходные данные: имеется информационная база (далее используется сокращение «ОИБ»), которая подключена к системе взаимодействия. У этой информационной базы имеется администратор (далее будет использоваться сокращение «АОБ»). АОБ регистрировал информационную базу в системе взаимодействия, следовательно, является администратором абонента этой базы. Имеется некоторая информационная база (далее используется сокращение «ИБЗ»), которой владеет злоумышленник (далее будет использоваться сокращение «АБЗ»).
Действия злоумышленника: АБЗ обращается к АОБ и просит его организовать совместное использование приложений (ИБЗ и ОИБ). По какой-то причине (личное знакомство, не подумал о последствия и т. д.) АОБ регистрирует совместное использование приложений. АБЗ создает в информационной базе ИБЗ пользователя, имя которого совпадает с именем доверенного пользователя в ОИБ.
Результат: Войдя в информационную базу ИБЗ от имени доверенного пользователя, АБЗ получает полный доступ ко всей переписке доверенного пользователя, которая проводилась в системе взаимодействия в ОИБ.
Рекомендации:
1. Если необходимо включить совместное использование двух информационных баз, то рекомендуется использовать один из следующих способов:
1. АОБ имеет полный административный доступ к подключаемой информационной базе.
2. Выполнять соответствие пользователей информационных баз с помощью ключей сопоставления. Сопоставление по именам использовать не рекомендуется.
2. Если есть подозрение, что копия информационной базы стала доступна злоумышленникам, то рекомендуется выполнить перерегистрацию информационной базы в системе взаимодействия. Для этого следует использовать методы ОтменитьРегистрациюИнформационнойБазы() и ВыполнитьРегистрациюИнформационнойБазы(). Методы можно использовать любым способом (синхронные, асинхронные).
3. Если необходимо прекратить совместное использование системы взаимодействия, то следует использовать метод ОтменитьСовместноеИспользованиеПриложенийАбонента(). В метод передается список приложений, совместное использование которых с вашим приложением нужно запретить. Получить список совместного использования можно с помощью метода ПолучитьСовместноеИспользованиеПриложенийАбонента().