Добавление бота в приложение чата

2024-11-05

Узнайте, как создавать интерфейсы искусственного интеллекта для бесед в приложении чата с помощью канала обмена сообщениями Службы коммуникации Azure чата, доступного в Azure Служба Bot. В этом кратком руководстве вы создадите бот с помощью пакета SDK BotFramework. Затем интегрируйте бота в приложение чата, созданное с помощью пакета SDK для чата служб коммуникации.

В этой статье описывается, как выполнить следующее:

Создание и развертывание бота в Azure
Получите ресурс служб связи
Включение канала чата служб коммуникации для бота
Создание приложения чата и добавление бота в качестве участника
Дополнительные возможности бота

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

Учетная запись Azure и активная подписка. Создать аккаунт бесплатно.
Visual Studio 2019 или более поздней версии.
Последняя версия .NET Core. В этом кратком руководстве мы используем .NET Core 3.1. Обязательно установите версию, соответствующую экземпляру Visual Studio, 32-разрядной или 64-разрядной версии.
Пакет SDK для платформы Bot

Создание и развертывание бота в Azure

Чтобы использовать чат Azure Communication Services в качестве канала в Службе ботов Azure, для начала разверните бота. Чтобы развернуть бот, выполните следующие действия.

Создайте ресурс службы Azure Bot
Получение идентификатора и пароля приложения бота
Создание веб-приложения для хранения логики бота
Создание конечной точки обмена сообщениями для бота

Создайте ресурс службы Azure Bot

Сначала создайте ресурс службы Azure Bot на портале Azure. Канал чата службы коммуникации поддерживает одноарендные боты, боты с управляемыми удостоверениями и мультиарендные боты. В этом примере используется мультитенантный бот.

Чтобы настроить бот с одним клиентом или управляемым удостоверением, просмотрите сведения об удостоверениях Бота.

Для бота с управляемым удостоверением может потребоваться обновить удостоверение службы бота.

Получение идентификатора приложения бота и пароля приложения

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

Создание веб-приложения для хранения логики бота

Чтобы создать веб-приложение для бота, можно изменить примеры Bot Builder для вашего сценария или использовать пакет SDK Bot Builder для создания веб-приложения. Одним из самых простых примеров является Echo Bot.

Служба Bot Azure обычно ожидает, что контроллер веб-приложения Бот предоставил конечную точку в формате/api/messages. Конечная точка обрабатывает все сообщения, отправляемые боту.

Чтобы создать приложение бота, используйте Azure CLI для создания ресурса Службы приложений Azure или создания приложения на портале Azure.

Чтобы создать веб-приложение бота с помощью портал Azure:

На портале выберите Создать ресурс. В поле поиска введите веб-приложение. Выберите плитку веб-приложения .
В разделе "Создание веб-приложения" выберите или введите сведения для приложения, включая регион, в котором вы хотите развернуть приложение.
Выберите "Проверка и создание ", чтобы проверить развертывание и просмотреть сведения о развертывании. Затем выберите Создать.
При создании ресурса веб-приложения скопируйте URL-адрес имени узла, отображаемый в сведениях о ресурсе. URL-адрес является частью конечной точки, создаваемой для веб-приложения.

Создание конечной точки обмена сообщениями для бота

Затем в ресурсе бота создайте конечную точку обмена сообщениями веб-приложения:

В портал Azure перейдите к ресурсу Azure Bot. В меню ресурсов выберите "Конфигурация".
В разделе "Конфигурация" для конечной точки обмена сообщениями вставьте URL-адрес имени узла веб-приложения, скопированного в предыдущем разделе. Добавьте /api/messages к URL-адресу.
Выберите Сохранить.

Развертывание веб-приложения

Последним шагом для создания бота является развертывание веб-приложения. В этом кратком руководстве используйте пример бота Эхо. Функция 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 . Вставьте идентификатор приложения Майкрософт и пароль приложения, скопированные ранее:
```
   {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }
```
Затем используйте Visual Studio для ботов C# для развертывания бота.

Вы также можете использовать окно командной строки для развертывания бота Azure.
В Visual Studio в Обозреватель решений щелкните правой кнопкой мыши проект EchoBot и выберите "Опубликовать".
Выберите "Создать" , чтобы создать новый профиль публикации. Для целевого объекта выберите Azure:

Для конкретного целевого объекта выберите службу приложение Azure:
В конфигурации развертывания выберите веб-приложение в результатах, которые отображаются после входа в учетную запись Azure. Чтобы завершить профиль, нажмите кнопку "Готово", а затем нажмите кнопку "Опубликовать ", чтобы начать развертывание.

Получение ресурса служб коммуникации

Теперь, когда бот создан и развернут, создайте ресурс Служб коммуникации для настройки канала Служб коммуникации:

Выполните действия по созданию ресурса Служб коммуникации.
Создание пользователя Служб коммуникации и выдача маркера доступа пользователей. Убедитесь, что выбрана область чата. Скопируйте строку маркера и строку идентификатора пользователя.

Включение канала чата служб коммуникации

Если у вас есть ресурс служб коммуникации, можно настроить канал Служб коммуникации в ресурсе бота. В этом процессе для бота создается идентификатор пользователя.

В портал Azure перейдите к ресурсу Azure Bot. В меню ресурсов выберите каналы. В списке доступных каналов выберите Службы коммуникации Azure — Чат.
Выберите "Подключиться" , чтобы просмотреть список ресурсов служб коммуникации, доступных в подписке.
В области "Создать подключение" выберите ресурс чата служб коммуникации и нажмите кнопку "Применить".
При проверке сведений о ресурсе идентификатор бота отображается в столбце "Идентификатор бота Службы коммуникации Azure". Идентификатор бота можно использовать для представления бота в потоке чата с помощью API addParticipant служб коммуникации. После добавления бота в чат в качестве участника бот начинает получать действия, связанные с чатом, и он может ответить в потоке чата.

Создание приложения чата и добавление бота в качестве участника

Теперь, когда у вас есть идентификатор служб коммуникации бота, можно создать поток чата с ботом в качестве участника.

Создайте новое приложение на C#

Выполните следующую команду, чтобы создать приложение C#:
```
dotnet new console -o ChatQuickstart
```
Измените каталог на новую папку приложения и выполните dotnet build команду для компиляции приложения:
```
cd ChatQuickstart
dotnet build
```

Установите пакет

Установите пакет SDK чата служб коммуникации для .NET:

dotnet add package Azure.Communication.Chat

Создание клиента чата

Чтобы создать клиент чата, используйте конечную точку Служб коммуникации и маркер доступа пользователя, созданный ранее. Используйте класс CommunicationIdentityClient из Identity SDK для создания пользователя и выдачи токена для передачи клиенту чата. Маркеры доступа можно создать на портале, выполнив следующие инструкции.

Скопируйте следующий код и вставьте его в исходный файл Program.cs :

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Запуск потока чата с помощью бота

Используйте метод createChatThread на chatClient для создания потока чата. Замените идентификатор идентификатором служб коммуникации бота.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Получите клиент для чатовой ветки

Метод GetChatThreadClient возвращает клиент потока для уже существующего потока:

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Отправка сообщения в поток чата

Чтобы с помощью SendMessage отправить сообщение в поток:

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Получение сообщений из потока чата

Сообщения чата можно получить, опрашив GetMessages метод в клиенте потока чата с заданными интервалами:

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Проверьте список сообщений для ответа-эхо бота Hello World.

Вы можете использовать JavaScript или мобильные пакеты SDK Azure для подписки на входящие уведомления:

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

Очистка потока чата

Закончив пользоваться чатом, удалите переписку.

chatClient.DeleteChatThread(threadId);

Развертывание приложения чата C#

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

В Visual Studio откройте проект чата.
Щелкните правой кнопкой мыши проект ChatQuickstart и выберите "Опубликовать".
Когда вы опубликуете решение, запустите его и проверьте, отображает ли эхо-бот сообщение пользователя в командной строке. Теперь, когда у вас есть решение, вы можете продолжать играть с различными действиями, необходимыми для бизнес-сценариев, которые вам может потребоваться решить.

Дополнительные действия, которые можно выполнять с помощью бота

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

Обновление беседы
Обновление сообщения
Удаление сообщения
Индикатор набора текста
Действие события
Различные вложения, включая адаптивные карточки
Данные канала Бота

В следующих разделах показаны некоторые примеры для иллюстрации этих функций.

Отправка приветственного сообщения при добавлении нового пользователя в поток

Текущая логика 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 , чтобы убедиться, что конечная точка задана правильно.

Бот получает запрещенное исключение при ответе на сообщение

Убедитесь, что идентификатор приложения и пароль приложения Майкрософт бота сохранены правильно в файле конфигурации бота, который вы отправляете в веб-приложение.

Не удается добавить бота в качестве участника

Убедитесь, что идентификатор служб коммуникации бота используется правильно при отправке запроса на добавление бота в поток чата.

Следующие шаги

Попробуйте демонстрационное приложение чата для чата 1:1 между пользователем чата и ботом с помощью компонента пользовательского интерфейса BotFramework WebChat.

Дополнительные сведения о добавлении бота OpenAI см. в разделе "Интеграция бота OpenAI с чатом".