Создать расширения для сообщений

Расширения сообщений позволяют пользователям взаимодействовать с веб-службой с помощью кнопок и форм в клиенте Microsoft Teams. Пользователи могут выполнять поиск или инициировать действия во внешней системе из области создания сообщения, поля команд или непосредственно из сообщения. Результаты этих взаимодействий можно вернуть клиенту Teams в виде карта в формате.

Важно!

Расширения сообщений доступны в средах Сообщества для государственных организаций (GCC), GCC-High и Министерства обороны (DOD).

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

На следующем рисунке показаны расположения, из которых можно вызывать расширения сообщений:

Примечание.

@mentioning Расширения сообщений в поле создания не поддерживаются.

Компьютер

Мобильные устройства

Сценарии, в которых используются расширения для сообщений

Сценарий	Пример
Для выполнения действия и возврата результата в беседу требуется внешняя система.	Можно зарезервировать ресурс и сообщить о зарезервированном периоде времени в канал.
Вам нужно найти что-то во внешней системе и поделиться результатами беседы.	Найдите рабочий элемент в Azure DevOps и поделитесь им с группой в виде адаптивной карточки.
Вы хотите выполнить сложную задачу, включающую несколько шагов или большой объем информации во внешней системе, и поделиться результатами беседы.	Создайте запись об ошибке в системе отслеживания на основе сообщения Teams, назначьте эту ошибку Бобу и отправьте карточку со сведениями об ошибке в цепочку беседы.

Сведения о работе расширений для сообщений

Расширение сообщений состоит из веб-службы, которую вы размещаете, и манифеста приложения, который указывает расположение в клиенте Teams, где вызывается веб-служба. Веб-служба использует схему обмена сообщениями Bot Framework и протокол безопасной связи, поэтому необходимо зарегистрировать веб-службу в качестве бота в Bot Framework.

Примечание.

Хотя веб-службу можно создать вручную, рекомендуется использовать пакет SDK Bot Framework для работы с протоколом.

В манифесте приложения (ранее называемом манифестом приложения Teams) определяется одно расширение сообщений с 10 разными командами. Каждая команда определяет тип, например действие или поиск, а также расположения в клиенте, из которого она вызывается. Расположения вызова включают область создания сообщения, панель команд и сообщение. При вызове веб-служба получает сообщение HTTPS с полезными данными JSON со всеми соответствующими сведениями. Ответ с полезными данными JSON, чтобы сообщить клиенту Teams о следующем взаимодействии, включаемом.

Типы команд расширения сообщений

Есть два типа команд расширения для сообщений: команда действия и команда поиска. Тип команды расширения для сообщений определяет элементы пользовательского интерфейса и потоки взаимодействия, доступные веб-службе. Некоторые взаимодействия, такие как проверка подлинности и конфигурация, доступны для обоих типов команд.

Команды действий

Команды действий используются для представления пользователям модального всплывающего окна для сбора или отображения информации. Когда пользователь отправляет форму, веб-служба отвечает, вставляя сообщение непосредственно в беседу или в область создания сообщения. Затем пользователь может отправить сообщение. Для более сложных рабочих процессов можно связать несколько форм.

Команды действий активируются из области создания сообщений, командного поля или сообщения. При вызове команды из сообщения исходные полезные данные JSON, отправленные боту, включают все сообщение, из которого она была вызвана. На следующем рисунке отображается диалоговое окно действия расширения сообщения (называется модулем задач в TeamsJS версии 1.x):

Команды поиска

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

Карточки активируются из области создания сообщения или командного поля, но не из сообщения. Они не могут быть активированы из сообщения. На следующем рисунке отображается диалоговое окно команды поиска расширения сообщения:

Примечание.

Дополнительные сведения о карточках см. в статье о том, что такое карточки.

Развертывание ссылки

Примечание.

Распаковка ссылок поддерживается только для расширений сообщений на основе бота.

При вставке URL-адреса в область создания сообщения вызывается веб-служба. Эта функция называется развертыванием ссылок. Вы можете подписаться на получение вызова при вставке URL-адресов, содержащих определенный домен, в область создания сообщения. Веб-служба может разворачивать URL-адрес в подробный карта, предоставляя больше сведений, чем стандартный предварительный просмотр веб-сайта карта. Вы можете добавить кнопки, чтобы пользователи могли немедленно выполнять действия, не выходя из клиента Teams. На следующих изображениях отображается функция распаковки ссылок при вставке ссылки в расширение сообщения:

Создать расширения для сообщений

Чтобы создать расширение для сообщений, если у вас его еще нет, существует два способа:

• Создание расширений сообщений с помощью API (на основе API). Вы можете легко создать расширение сообщений из существующего API. Для этого метода требуется документ OpenAPI Description (OAD).

• Создание расширений сообщений с помощью Bot Framework (на основе бота). Если вы хотите использовать беседу в режиме "один на один", вы можете создать новое расширение сообщений из бота.

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

Расширение сообщений на основе API

• Проще и быстрее создавать и обслуживать.
• Расширение сообщений использует API.
• Дополнительный код или ресурсы для логики бота не требуются.
• Идеально подходит для сценариев, когда расширение сообщений должно взаимодействовать только с веб-службой и не требует сложной логики или управления состоянием.
• Трафик приватизирован, так как он не зависит от инфраструктуры бота Azure.
• Поддерживает команды поиска.

Расширение сообщений на основе бота

• Более гибкий.
• Расширение сообщений использует Bot Framework.
• Может использовать все возможности бота.
• Идеально подходит для сценариев, когда расширение сообщений должно взаимодействовать с несколькими службами, управлять сложной логикой или взаимодействием с пользователем или поддерживать состояние между сеансами.
• Поддерживает команды действий, команды поиска и распаковку ссылок.

Выберите вариант, чтобы начать создание расширения для сообщений:

Пример кода

Название примера	Описание	.NET	Node.js	Python	Манифест
Расширение для сообщений с командами на основе действий	В этом примере показано, как определить команды действий, создать диалоговое окно и ответить на действие отправки диалога.	Просмотр	Просмотр	Просмотр	View
Расширение для сообщений с командами на основе поиска	В этом примере показано, как создать расширение сообщений на основе поиска. Он выполняет поиск пакетов Nuget и отображает результаты в расширении обмена сообщениями на основе поиска.	Просмотр	Просмотр	Просмотр	Просмотр
Предварительный просмотр действия расширения сообщений	В этом примере показано, как использовать предварительную версию действий в расширениях обмена сообщениями с помощью Bot Framework версии 4.	Просмотр	Просмотр	Н/Д	Просмотр
Действие расширения для сообщения для планирования задач	В этом примере показано, как запланировать задачу из команды действия расширения сообщений и получить напоминание карта в запланированные дату и время.	Просмотр	Просмотр	Н/Д	Просмотр