Краткое руководство. Добавление бота в приложение чата
Узнайте, как создавать интерфейсы искусственного интеллекта для бесед в приложении чата с помощью канала обмена сообщениями Службы коммуникации Azure чата, доступного в Azure Служба Bot. В этом кратком руководстве вы создадите бот с помощью пакета SDK BotFramework. Затем вы интегрируете бота в приложение чата, созданное с помощью пакета SDK для чата служб коммуникации.
Из этого краткого руководства вы узнаете, как выполнять следующие задачи:
- Создание и развертывание бота в Azure
- Получение ресурса служб коммуникации
- Включение канала чата служб коммуникации для бота
- Создание приложения чата и добавление бота в качестве участника
- Дополнительные возможности бота
Необходимые компоненты
- Учетная запись Azure и активная подписка. Создать аккаунт бесплатно.
- Visual Studio 2019 или более поздней версии.
- Последняя версия .NET Core. (https://dotnet.microsoft.com/download/dotnet/).
- Пакет SDK для платформы Bot
Создание и развертывание бота в Azure
Чтобы использовать Службы коммуникации Azure чат в качестве канала в Azure Служба Bot, сначала разверните бота. Чтобы развернуть бот, выполните следующие действия.
- Создание ресурса Служба Bot Azure
- Получение идентификатора и пароля приложения бота
- Создание веб-приложения для хранения приложения бота
- Создание конечной точки обмена сообщениями для бота
Создание ресурса Служба Bot Azure
Сначала используйте портал Azure для создания ресурса azure Служба Bot. Канал чата служб коммуникации поддерживает боты с одним клиентом, боты управляемых удостоверений и мультитенантные боты.
- В целях этого краткого руководства мы будем использовать
multitenant
бота. - Чтобы настроить или
managed identity
ботsingle-tenant
, просмотрите сведения о удостоверении Бота. - Для бота
managed identity
может потребоваться обновить удостоверение службы бота.
Получение идентификатора приложения бота и пароля приложения
Затем получите идентификатор приложения Майкрософт и пароль, назначенные боту при его развертывании. Эти значения используются для последующих конфигураций.
Создание приложения бота и его публикация в веб-приложении
Чтобы создать бот, можно выполнить одно из следующих действий:
- Пересматривайте примеры Bot Builder для вашего сценария, создайте веб-приложение, а затем разверните пример бота в нем.
- Используйте пакет SDK Bot Builder для создания и публикации бота в веб-приложении.
В этом кратком руководстве мы будем использовать пример Echo Bot из примеров Bot Builder.
Создание веб-приложения для хранения приложения бота
Чтобы создать веб-приложение, используйте Azure CLI для создания ресурса службы приложение Azure или создания приложения в портал Azure.
Чтобы создать веб-приложение бота с помощью портал Azure:
На портале выберите Создать ресурс. В поле поиска введите веб-приложение. Выберите плитку веб-приложения .
В разделе "Создание веб-приложения" выберите или введите сведения для приложения, включая регион, в котором вы хотите развернуть приложение.
Выберите "Проверка и создание ", чтобы проверить развертывание и просмотреть сведения о развертывании. Затем выберите Создать.
При создании ресурса веб-приложения скопируйте URL-адрес имени узла, отображаемый в сведениях о ресурсе. URL-адрес является частью конечной точки, создаваемой для веб-приложения.
Создание конечной точки обмена сообщениями для бота
Azure Служба Bot обычно ожидает, что контроллер веб-приложений Бота предоставляет конечную точку в форме/api/messages
. Конечная точка обрабатывает все сообщения, отправляемые боту.
Затем в ресурсе бота создайте конечную точку обмена сообщениями веб-приложения:
В портал Azure перейдите к ресурсу Azure Bot. В меню ресурсов выберите "Конфигурация".
В разделе "Конфигурация" для конечной точки обмена сообщениями вставьте URL-адрес имени узла веб-приложения, скопированного в предыдущем разделе. Добавьте URL-адрес с
/api/messages
помощью .Выберите Сохранить.
Развертывание веб-приложения
Последним шагом для создания бота является развертывание веб-приложения. В этом кратком руководстве используйте пример эхо-бота. Функция Echo Bot ограничена отображением входных данных пользователя. Вот как развернуть его в веб-приложении в Azure:
Используйте Git для клонирования этого репозитория GitHub:
git clone https://github.com/Microsoft/BotBuilder-Samples.git cd BotBuilder-Samples
В Visual Studio откройте проект Echo Bot.
В проекте Visual Studio откройте файл Appsettings.json . Вставьте идентификатор приложения Майкрософт и пароль приложения, скопированные ранее:
{ "MicrosoftAppType": "", "MicrosoftAppId": "<App-registration-ID>", "MicrosoftAppPassword": "<App-password>", "MicrosoftAppTenantId": "" }
Затем используйте Visual Studio или VS Code для ботов C# для развертывания бота.
Вы также можете использовать окно командной строки для развертывания бота Azure.
В Visual Studio в Обозреватель решений щелкните правой кнопкой мыши проект EchoBot и выберите "Опубликовать".
Выберите "Создать" , чтобы создать новый профиль публикации. Для целевого объекта выберите Azure:
Для конкретного целевого объекта выберите службу приложение Azure:
В конфигурации развертывания выберите веб-приложение в результатах, которые отображаются после входа в учетную запись Azure. Чтобы завершить профиль, нажмите кнопку "Готово", а затем нажмите кнопку "Опубликовать ", чтобы начать развертывание.
Получение ресурса служб коммуникации
Теперь, когда бот создан и развернут, создайте ресурс Служб коммуникации для настройки канала Служб коммуникации:
Выполните действия по созданию ресурса Служб коммуникации.
Создание пользователя Служб коммуникации и выдача маркера доступа пользователей. Не забудьте задать область чата. Скопируйте строку маркера и строку идентификатора пользователя.
Включение канала чата служб коммуникации
Если у вас есть ресурс служб коммуникации, можно настроить канал Служб коммуникации в ресурсе бота. В этом процессе для бота создается идентификатор пользователя.
В портал Azure перейдите к ресурсу Azure Bot. В меню ресурсов выберите каналы. В списке доступных каналов выберите Службы коммуникации Azure — Чат.
Выберите "Подключиться" , чтобы просмотреть список ресурсов служб коммуникации, доступных в подписке.
В области "Создать подключение" выберите ресурс чата служб коммуникации и нажмите кнопку "Применить".
При проверке сведений о ресурсе идентификатор бота отображается в столбце "Идентификатор бота Службы коммуникации Azure". Идентификатор бота можно использовать для представления бота в потоке чата с помощью API addParticipant служб коммуникации. После добавления бота в чат в качестве участника бот начинает получать действия, связанные с чатом, и он может ответить в потоке чата.
Создание приложения чата и добавление бота в качестве участника
Теперь, когда у вас есть идентификатор служб коммуникации бота, можно создать поток чата с ботом в качестве участника.
Краткое руководство по добавлению чата в приложение
Выполните действия, описанные в кратком руководстве по добавлению чата в приложение , чтобы создать приложение чата.
- Замените <Resource_Endpoint> конечной точкой служб коммуникации на шаге "Получить ресурс службы коммуникации".
- Замените <Access_Token> маркером доступа пользователя на шаге "Получить ресурс службы коммуникации".
- Замените <Access_ID ботами ACS_ID> на шаге "Включить канал чата служб коммуникации".
Локальное запуск приложения чата C#
Чтобы запустить приложение чата локально, используйте dotnet run
команду:
dotnet run
Вы должны получить сообщение от бота в консоли, которая говорит "Hello World".
Пример результата:
1730405535010:Hello World
Дополнительные сведения, которые можно сделать с помощью бота
Бот может получать больше обычного текстового сообщения от пользователя в канале чата служб коммуникации. Некоторые действия, которые бот может получить от пользователя, включают:
- Обновление беседы
- Обновление сообщения
- Удаление сообщения
- Индикатор набора текста
- Действие события
- Различные вложения, включая адаптивные карточки
- Данные канала Бота
В следующих разделах показаны некоторые примеры для иллюстрации этих функций.
Отправка приветственного сообщения при добавлении нового пользователя в поток
Текущая логика Echo Bot принимает входные данные от пользователя и повторяет его обратно. Если вы хотите добавить дополнительную логику, например ответ на событие служб коммуникации, добавленного участником, скопируйте следующий код и вставьте его в исходный файл EchoBot.cs :
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;
namespace Microsoft.BotBuilderSamples.Bots
{
public class EchoBot : ActivityHandler
{
public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
{
if (turnContext.Activity.Type == ActivityTypes.Message)
{
var replyText = $"Echo: {turnContext.Activity.Text}";
await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
}
else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
{
if (turnContext.Activity.MembersAdded != null)
{
foreach (var member in turnContext.Activity.MembersAdded)
{
if (member.Id != turnContext.Activity.Recipient.Id)
{
await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
}
}
}
}
}
}
}
Отправка адаптивной карточки
Примечание.
Адаптивные карточки поддерживаются только в случаях использования Службы коммуникации Azure, когда все участники чата являются Службы коммуникации Azure пользователями, а не для вариантов использования взаимодействия Teams.
Вы можете отправить адаптивную карточку в поток чата, чтобы повысить вовлеченность и эффективность. Адаптивная карточка также помогает взаимодействовать с пользователями различными способами. Адаптивную карточку можно отправить из бота, добавив карточку в виде вложения действий бота.
Ниже приведен пример отправки адаптивной карточки:
var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
ContentType = "application/vnd.microsoft.card.adaptive",
Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);
await turnContext.SendActivityAsync(reply, cancellationToken);
Получение примеров полезных данных для адаптивных карточек в примерах и шаблонах.
Для пользователя чата канал чата служб коммуникации добавляет поле в метаданные сообщения, указывающие, что сообщение содержит вложение. В метаданных microsoft.azure.communication.chat.bot.contenttype
для свойства задано azurebotservice.adaptivecard
значение .
Ниже приведен пример сообщения чата, в который подключена адаптивная карточка:
{
"content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
"senderDisplayName": "BotDisplayName",
"metadata": {
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
},
"messageType": "Text"
}
Отправка сообщения от пользователя в бот
Вы можете отправить основное текстовое сообщение от пользователя боту так же, как отправить текстовое сообщение другому пользователю.
Однако при отправке сообщения с вложением от пользователя в бот добавьте этот флаг в метаданные чата коммуникации:
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
Чтобы отправить действие события от пользователя в бот, добавьте этот флаг в метаданные чата службы коммуникации:
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"
В следующих разделах показаны примеры форматов сообщений чата от пользователя к боту.
Простое текстовое сообщение
{
"content":"Simple text message",
"senderDisplayName":"Acs-Dev-Bot",
"metadata":{
"text":"random text",
"key1":"value1",
"key2":"{\r\n \"subkey1\": \"subValue1\"\r\n
"},
"messageType": "Text"
}
Сообщение с вложением
{
"content": "{
\"text\":\"sample text\",
\"attachments\": [{
\"contentType\":\"application/vnd.microsoft.card.adaptive\",
\"content\": { \"*adaptive card payload*\" }
}]
}",
"senderDisplayName": "Acs-Dev-Bot",
"metadata": {
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
"text": "random text",
"key1": "value1",
"key2": "{\r\n \"subkey1\": \"subValue1\"\r\n}"
},
"messageType": "Text"
}
Сообщение с действием события
Полезные данные события включают все поля JSON в содержимом сообщения, кроме Name
. Поле Name
содержит имя события.
В следующем примере имя endOfConversation
события с полезными данными "{field1":"value1", "field2": { "nestedField":"nestedValue" }}
отправляется боту:
{
"content":"{
\"name\":\"endOfConversation\",
\"field1\":\"value1\",
\"field2\": {
\"nestedField\":\"nestedValue\"
}
}",
"senderDisplayName":"Acs-Dev-Bot",
"metadata":{
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
"text":"random text",
"key1":"value1",
"key2":"{\r\n \"subkey1\": \"subValue1\"\r\n}"
},
"messageType": "Text"
}
Поле microsoft.azure.communication.chat.bot.contenttype
метаданных требуется только в сообщении, отправляемом пользователем боту.
Поддерживаемые поля действий бота
В следующих разделах описаны поддерживаемые поля действий бота для потоков ботов и потоков "пользователь — бот".
Поток "бот — пользователь"
Следующие поля действий бота поддерживаются для потоков бота между пользователями.
Процедуры
- Сообщение
- Ввод с клавиатуры
Поля действий сообщения
Text
Attachments
AttachmentLayout
SuggestedActions
-
From.Name
(Преобразовано в службы коммуникацииSenderDisplayName
.) -
ChannelData
(Преобразовано в службы коммуникацииChat Metadata
. Если какие-либоChannelData
значения сопоставления являются объектами, они сериализуются в формате JSON и отправляются в виде строки.)
Поток "пользователь — бот"
Эти поля действий бота поддерживаются для потоков пользователей и ботов.
Действия и поля
Сообщение
-
Id
(Идентификатор сообщения чата служб коммуникации) TimeStamp
Text
Attachments
-
Обновление беседы
MembersAdded
MembersRemoved
TopicName
Обновление сообщения
-
Id
(Обновленный идентификатор сообщения чата служб коммуникации) Text
Attachments
-
Удаление сообщения
-
Id
(Удаленный идентификатор сообщения чата служб коммуникации)
-
Мероприятие
Name
Value
Ввод с клавиатуры
Другие распространенные поля
-
Recipient.Id
иRecipient.Name
(идентификатор пользователя чата службы коммуникации и отображаемое имя) -
From.Id
иFrom.Name
(идентификатор пользователя чата службы коммуникации и отображаемое имя) -
Conversation.Id
(Идентификатор потока чата служб коммуникации) -
ChannelId
(Чат служб коммуникации, если пустой) -
ChannelData
(Метаданные сообщения чата служб коммуникации)
Шаблоны передачи бота
Иногда бот не понимает вопрос или не может ответить на вопрос. Клиент может попросить в чате подключиться к агенту человека. В этих сценариях поток чата должен быть передан от бота агенту человека. Вы можете разработать приложение для перехода беседы с бота на человека.
Обработка обмена данными между ботами
В некоторых случаях необходимо добавить двух ботов в один поток чата для предоставления различных служб. В этом сценарии может потребоваться убедиться, что бот не отправляет автоматические ответы на сообщения другого бота. При неправильной обработке автоматическое взаимодействие ботов может привести к бесконечному циклу сообщений.
Вы можете проверить удостоверение пользователя служб коммуникации отправителя сообщения в свойстве действия From.Id
. Проверьте, принадлежит ли он другому боту. Затем выполните необходимые действия, чтобы предотвратить поток обмена данными между ботами. Если этот тип сценария приводит к большим объемам звонков, канал чата служб коммуникации регулирует запросы, а бот не может отправлять и получать сообщения.
Дополнительные сведения об ограничениях регулирования.
Устранение неполадок
В следующих разделах описаны способы устранения распространенных сценариев.
Не удается добавить канал чата
На портале разработчика Microsoft Bot Framework перейдите в раздел Configuration>Bot Messaging, чтобы убедиться, что конечная точка настроена правильно.
Бот получает запрещенное исключение при ответе на сообщение
Убедитесь, что идентификатор приложения и пароль приложения Майкрософт бота сохранены правильно в файле конфигурации бота, который вы отправляете в веб-приложение.
Не удается добавить бота в качестве участника
Убедитесь, что идентификатор служб коммуникации бота используется правильно при отправке запроса на добавление бота в поток чата.
Следующие шаги
Полезные ссылки
- Ознакомьтесь с основными понятиями чата
- Узнайте о модели ценообразования для чата