Краткое руководство. Добавление бота в приложение чата

Мақала
03/25/2023

Узнайте, как создавать интерфейсы искусственного интеллекта для бесед в приложении чата с помощью канала обмена сообщениями Службы коммуникации 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 чат в качестве канала в Azure Служба Bot, сначала разверните бота. Чтобы развернуть бот, выполните следующие действия.

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

Создание ресурса Служба Bot Azure

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

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

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

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

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

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

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

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

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

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

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

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

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

В портал 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 . Вставьте идентификатор приложения Майкрософт и пароль приложения, скопированные ранее:
```
   {
     "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 Используйте класс из пакета 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 и выберите "Опубликовать".
После публикации решения запустите его и проверка, если Echobot отклошит сообщение пользователя в командной строке. Теперь, когда у вас есть решение, вы можете продолжать играть с различными действиями, необходимыми для бизнес-сценариев, для которых необходимо решить.

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

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

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

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

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

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

Поддерживаемые поля действий бота

В следующих разделах описаны поддерживаемые поля действий бота для потоков ботов и потоков "пользователь — бот".

Поток "бот — пользователь"

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

Процедуры

Message
Ввод с клавиатуры

Поля действий сообщения

Text
Attachments
AttachmentLayout
SuggestedActions
From.Name (Преобразовано в службы коммуникации SenderDisplayName.)
ChannelData (Преобразовано в службы коммуникации Chat Metadata. Если какие-либо ChannelData значения сопоставления являются объектами, они сериализуются в формате JSON и отправляются в виде строки.)

Поток "пользователь — бот"

Эти поля действий бота поддерживаются для потоков пользователей и ботов.

Действия и поля

Message
- 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.

Бөлісу құралы: