Руководство по расширению сообщений на основе действий - Teams

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

Основные возможности расширения сообщений на основе действий:

Предоставляет пользователю модальное всплывающее окно для сбора или отображения информации.
Активирует команды действий из области создания сообщения, командного поля или из сообщения.

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

Снимок экрана: выходные данные расширения сообщений после успешного выполнения пошагового руководства.

Предварительные условия

Осталось 17 мин

Убедитесь, что установлены следующие средства и настроена среда разработки:

	Установка	Для использования...
	Microsoft Teams	Microsoft Teams позволяет взаимодействовать со всеми пользователями, с которыми вы работаете, с помощью приложений для чата, собраний и звонков в одном месте.
	Visual Studio 2022	Вы можете установить корпоративную версию в Visual Studio 2022, а также рабочие нагрузки ASP.NET и веб-разработки. Используйте последнюю версию.
	Пакет SDK для .NET Core	Настраиваемые привязки для локальной отладки и Функции Azure развертываний приложений. Если вы не установили последнюю версию, установите переносимую версию.
	Туннель разработки	Функции приложений Teams (диалоговые боты, расширения сообщений и входящие веб-перехватчики) требуют входящих подключений. Туннель соединяет систему разработки с Teams. Туннель разработки — это мощный инструмент для безопасного открытия локального узла в Интернете и контроля доступа. Туннель разработки доступен в Visual Studio 2022 версии 17.7.0 или более поздней. или вы также можете использовать ngrok в качестве туннеля для подключения системы разработки к Teams. Он не требуется для приложений, которые содержат только вкладки. Этот пакет устанавливается в каталоге проекта (с помощью npm `devDependencies`).

Примечание.

После скачивания ngrok зарегистрируйтесь и установите authtoken.

Настройка локальной среды

Осталось 16 мин

Откройте Microsoft-Teams-Samples.
Выберите Код.
В раскрывающемся меню выберите Открыть с помощью GitHub Desktop.
Выберите Клонировать.

Регистрация приложения Microsoft Entra

Осталось 15 мин

Следующие действия помогут вам создать и зарегистрировать бот в портал Azure.

Создайте и зарегистрируйте приложение Azure.
Создайте секрет клиента, чтобы включить проверку подлинности бота с единым входом.
Добавьте канал Teams для развертывания бота.
Создайте туннель к конечным точкам веб-сервера с помощью туннеля разработки (рекомендуется) или ngrok.
Добавьте конечную точку обмена сообщениями в созданный туннель разработки.

Добавление регистрации приложения

Перейдите к портал Azure.
Выберите Регистрация приложений.
Выберите + Новая регистрация.
Введите имя приложения.
Выберите Учетные записи в любом каталоге организации (любой клиент Microsoft Entra ID — мультитенантный).
Нажмите Зарегистрировать.

Приложение зарегистрировано в Microsoft Entra ID. Откроется страница обзора приложения.

Примечание.

Сохраните идентификатор приложения из идентификатора приложения (клиента) и каталога (клиента) для дальнейшего использования.

Создание туннеля

dev tunnel
ngrok

Откройте Visual Studio.
Выберите Создать новый проект.
В поле поиска введите ASP.NET. В результатах поиска выберите ASP.NET Core Веб-приложение.
Нажмите кнопку Далее.
Введите имя проекта и нажмите кнопку Далее.
Нажмите Создать.

Откроется окно обзора.
В раскрывающемся списке отладки выберите Dev Tunnels (без активного туннеля)>Создать туннель....

Открывается всплывающее окно.
Обновите следующие сведения во всплывающем окне:
1. Учетная запись. Введите учетную запись Майкрософт или GitHub.
2. Имя: введите имя туннеля.
3. Тип туннеля: в раскрывающемся списке выберите Временный.
4. Доступ: в раскрывающемся списке выберите Общедоступный.
Нажмите OK.

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

Созданный туннель можно найти в раскрывающемся списке отладки следующим образом:
Нажмите клавишу F5 , чтобы запустить приложение в режиме отладки.
Если появится диалоговое окно Предупреждение системы безопасности , выберите Да.

Открывается всплывающее окно.
Нажмите Продолжить.

В новом окне браузера откроется домашняя страница туннеля разработки, и туннель разработки теперь активен.
Перейдите в Visual Studio и выберите Просмотреть выходные > данные.
В раскрывающемся меню консоли вывода выберите Dev Tunnels (Туннели разработки).

В консоли вывода отображается URL-адрес туннеля разработки.

Используйте ngrok или командную строку для создания туннеля к общедоступным конечным точкам HTTPS локального веб-сервера. Выполните следующую команду в ngrok:

ngrok http --host-header=localhost 3978

Совет

Если вы столкнулись с ERR_NGROK_4018, выполните действия, описанные в командной строке, чтобы зарегистрироваться и проверить подлинность ngrok. Затем выполните ngrok http --host-header=localhost 3978 команду .

В окне отображается URL-адрес HTTPS.

Снимок экрана: URL-адрес HTTPS ngrok.

Добавление веб-проверки подлинности

В левой области в разделе Управление выберите Проверка подлинности.
Выберите Добавить веб-сайт платформы>.
Введите URI перенаправления для приложения, добавив auth-end к полному доменному имени. Например, https://your-devtunnel-domain/auth-end или https://your-ngrok-domain/auth-end.
В разделе Неявное предоставление и гибридные потоки установите флажки Маркеры доступа и маркеры идентификаторов .
Нажмите Настроить.
В разделе Интернет выберите Добавить URI.
Введите https://token.botframework.com/.auth/web/redirect.
Выберите Сохранить.

Создание секрета клиента

В левой области в разделе Управление выберите Сертификаты & секреты.
В разделе Секреты клиента выберите + Новый секрет клиента.

Откроется окно Добавление секрета клиента .
Введите Описание.
Нажмите Добавить.
В разделе Значение выберите Копировать в буфер обмена , чтобы сохранить значение секрета клиента для дальнейшего использования.

Добавление разрешения API

В области слева в разделе Управление выберите Разрешения API.
Выберите + Добавить разрешение.
Выберите Microsoft Graph.
Выберите Делегированные разрешения.
Выберите следующие разрешения:
- Разрешения> OpenIdэлектронная почта, offline_access, openid, профиль.
- Пользователь>User.Read.
Выберите Добавить разрешения.
Примечание.
- Если приложению не предоставлено согласие ИТ-администратора, пользователи должны предоставить согласие при первом использовании приложения.
- Пользователи должны согласиться на разрешения API только в том случае, если приложение Microsoft Entra зарегистрировано в другом клиенте.

Добавление URI идентификатора приложения

В области слева в разделе Управление выберите Предоставить API.
Рядом с полем URI идентификатора приложения нажмите кнопку Добавить.
Обновите URI идентификатораapi://your-devtunnel-domain/botid-{AppID} приложения в формате или api://your-ngrok-domain/botid-{AppID} и нажмите кнопку Сохранить.

На следующем рисунке показано доменное имя:

Добавление область

В области слева в разделе Управление выберите Предоставить API.
Выберите + Добавить область.
Введите access_as_user в качестве имени области.
В разделе Кто может предоставить согласие? выберите Администраторы и пользователи.
Обновите значения остальных полей следующим образом:
- Введите Teams может получить доступ к профилю пользователякак Администратор отображаемое имя согласия.
- Введите Позволяет Teams вызывать веб-API приложения в качестве текущего пользователяв качестве Администратор описание согласия.
- Введите Teams для доступа к профилю пользователя и отправлять запросы от имени пользователя в качестве отображаемого имени согласия пользователя.
- Введите Включить Teams для вызова API этого приложения с теми же правами, что и у пользователя , в описании согласия пользователя.
Убедитесь, что параметру Состояние присвоено значение Включено.
Нажмите кнопку Добавить область.

На следующем рисунке показаны поля и значения:

Примечание.

Имя области должно совпадать с URI идентификатора приложения с /access_as_user добавлением в конце.

Добавление клиентского приложения

В области слева в разделе Управление выберите Предоставить API.

В разделе Авторизованные клиентские приложения определите приложения, которые вы хотите авторизовать для веб-приложения вашего приложения.
Выберите + Добавить клиентское приложение.
Добавьте мобильное или классическое приложение Teams и веб-приложение Teams.
1. Для мобильных или классических приложений Teams: введите идентификатор клиента как 1fec8e78-bce4-4aaf-ab1b-5451cc387264.
2. Для веб-сайта Teams: введите идентификатор клиента как 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.
Установите флажок Авторизованные области .
Нажмите кнопку Добавить приложение.

На следующем рисунке отображается идентификатор клиента:

Создание бота

Осталось 10 мин

Создание ресурса бота Azure

Примечание.

Если вы уже тестируете бот в Teams, выйдите из этого приложения и Teams. Чтобы увидеть это изменение, войдите еще раз.

Перейдите на домашнюю страницу.
Выберите + Создать ресурс.
В поле поиска введите Azure Bot.
Выберите ВВОД.
Выберите Azure Bot.
Нажмите Создать.
Введите имя бота в поле Дескриптор бота.
Выберите свою подписку в раскрывающемся списке.
Выберите свою группу ресурсов в раскрывающемся списке.

Если у вас нет существующей группы ресурсов, можно создать новую группу ресурсов. Чтобы создать новую группу ресурсов, выполните следующие действия.
1. Выберите Создать.
2. Введите имя ресурса и нажмите кнопку ОК.
3. Выберите расположение в раскрывающемся списке Расположение новой группы ресурсов .
В разделе Цены выберите Изменить план.
Выберите FO Free>Select.
В разделе Идентификатор приложения Майкрософт выберите Тип приложения в качестве мультитенантного.
В поле Тип создания выберите Использовать существующую регистрацию приложения.
Введите идентификатор приложения.

Примечание.

Нельзя создать несколько ботов с одним идентификатором приложения Майкрософт.
Выберите Проверить и создать.
После завершения проверки нажмите кнопку Создать.

Подготовка бота занимает несколько минут.
Выберите пункт Перейти к ресурсу.

Вы успешно создали бот Azure.

Добавление канала Teams

В левой области выберите Каналы.
В разделе Доступные каналы выберите Microsoft Teams.
Установите флажок, чтобы принять условия предоставления услуг.
Выберите Принять.
Нажмите Применить.

Добавление конечной точки обмена сообщениями

dev tunnel
ngrok

Используйте URL-адрес туннеля разработки в консоли вывода в качестве конечной точки обмена сообщениями.
В левой области в разделе Параметры выберите Конфигурация.
Обновите конечную точку обмена сообщениями в формате https://your-devtunnel-domain/api/messages.
Нажмите Применить.

Вы успешно настроили бот в службе Azure Bot.

Примечание.

Если ключ инструментирования Application Insights отображает ошибку, обновите идентификатор приложения.

Скопируйте URL-адрес HTTPS из ngrok.

Примечание.

URL-адрес HTTPS в ngrok — это полное доменное имя. — WebAppDomain это полное доменное имя, которое не включает https:// в него.
В левой области в разделе Параметры выберите Конфигурация.
Обновите конечную точку обмена сообщениями в формате https://your-ngrok-domain/api/messages.
Нажмите Применить.

Вы успешно настроили бот в службе Azure Bot.

Примечание.

Если ключ инструментирования Application Insights отображает ошибку с идентификатором приложения.

Настройка параметров приложения и файлов манифеста

Осталось 5 мин

Перейдите к файлу appsettings.json в клонированных репозиториях.
Откройте файл appsettings.json и обновите следующие сведения:
- Задайте значение "MicrosoftAppType"MultiTenant.
- Задайте "MicrosoftAppId" для бота идентификатор приложения Майкрософт.
- Задайте "MicrosoftAppPassword"значениесекрета клиента для бота.
- Оставьте "MicrosoftAppTenantId" пустым для мультитенантного бота.
- Задайте "BaseUrl" полное доменное имя.
Перейдите к файлу manifest.json в клонированного репозитория.
Откройте файл manifest.json и внесите следующие изменения:
- Замените на <<validDomains>> полное доменное имя.
- Замените все вхождения <<Microsoft-App-ID>> идентификатором приложения Microsoft бота.

Сборка и запуск службы

Осталось 4 мин

Для сборки и запуска службы используйте Visual Studio или командную строку.

Visual Studio
Командная строка

Откройте Visual Studio.
Перейдите в раздел Файл>Открыть>проект/решение.....
В папке csharp выберите файл TeamsMessagingExtensionsAction.csproj .
Нажмите клавишу F5 , чтобы запустить проект.
Выберите Да, если появится следующий диалог:

Появится веб-страница с сообщением Ваш бот готов!.

Перейдите к примеру>msgext-action>csharp в окне командной строки и введите следующую команду:

dotnet run

Снимок экрана: командная строка: dotnet run с командой dotnet run.

Добавление приложения расширения сообщений действия в Teams

Осталось 3 мин

В клонированных репозитория перейдите к примерам>msgext-action>csharp>TeamsAppManifest.
Создайте .zip со следующими файлами, которые находятся в папке Manifest :
- manifest.json
- icon-outline.png
- icon-color.png
В клиенте Teams щелкните значок Приложения .
Выберите Управление приложениями
Выберите Отправить приложение.
Найдите параметр Отправить пользовательское приложение. Если параметр отображается, включена отправка пользовательских приложений.

Примечание.

Если вы не найдете параметр для отправки пользовательского приложения, обратитесь к администратору Teams.
Выберите Открыть , чтобы отправить файл messaging.zip, созданный в папку TeamsAppManifest.
Нажмите Добавить.
Выберите Открыть, чтобы открыть приложение в личных область.

Кроме того, вы можете выполнить поиск и выбрать необходимые область либо выбрать канал, чат или собрание из списка, а затем перейти через диалоговое окно, чтобы выбрать Перейти.

Взаимодействие с приложением в Teams

Осталось 2 мин

Выберите Команду Создать карточку в списке команд для создания поля.
Введите свои данные во всплывающем окне модального окна.
Выберите Отправить.
Выберите Дополнительные параметры (...) в меню переполнения.
Выберите Дополнительные действия>Поделиться сообщением.
Если вы хотите включить изображение, установите флажок Включить изображение в карточке главного героя и нажмите кнопку Отправить.