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

  • Статья

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

Из этого краткого руководства вы узнаете, как выполнять следующие задачи:

Необходимые компоненты

  • Учетная запись 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:

  1. На портале выберите Создать ресурс. В поле поиска введите веб-приложение. Выберите плитку веб-приложения .

    Screenshot that shows creating a web app resource in the Azure portal.

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

    Screenshot that shows details to set to create a web app deployment.

  3. Выберите "Проверка и создание ", чтобы проверить развертывание и просмотреть сведения о развертывании. Затем выберите Создать.

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

    Screenshot that shows how to copy the web app endpoint URL.

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

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

  1. В портал Azure перейдите к ресурсу Azure Bot. В меню ресурсов выберите "Конфигурация".

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

  3. Выберите Сохранить.

Screenshot that shows how to create a bot messaging endpoint by using the web app hostname.

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

Последним шагом для создания бота является развертывание веб-приложения. В этом кратком руководстве используйте пример эхо-бота. Функция Echo Bot ограничена отображением входных данных пользователя. Вот как развернуть его в веб-приложении в Azure:

  1. Используйте Git для клонирования этого репозитория GitHub:

    git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

  2. В Visual Studio откройте проект Echo Bot.

  3. В проекте Visual Studio откройте файл Appsettings.json . Вставьте идентификатор приложения Майкрософт и пароль приложения, скопированные ранее:

       {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }

    Затем используйте Visual Studio для ботов C# для развертывания бота.

    Вы также можете использовать окно командной строки для развертывания бота Azure.

  4. В Visual Studio в Обозреватель решений щелкните правой кнопкой мыши проект EchoBot и выберите "Опубликовать".

    Screenshot that shows publishing your web app from Visual Studio.

  5. Выберите "Создать" , чтобы создать новый профиль публикации. Для целевого объекта выберите Azure:

    Screenshot that shows how to select Azure as target in a new publishing profile.

    Для конкретного целевого объекта выберите службу приложение Azure:

    Screenshot that shows how to select Azure App Service as the specific target.

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

    Screenshot that shows setting the deployment configuration with the web app name.

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

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

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

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

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

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

  1. В портал Azure перейдите к ресурсу Azure Bot. В меню ресурсов выберите каналы. В списке доступных каналов выберите Службы коммуникации Azure — Чат.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Выберите Подключение, чтобы просмотреть список ресурсов служб коммуникации, доступных в подписке.

    Screenshot that shows how to connect a Communication Service resource to the bot.

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

    Screenshot that shows how to save the selected Communication Service resource to create a new Communication Services user ID.

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

    Screenshot that shows the new Communication Services user ID assigned to the bot.

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

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

Создание нового приложения C#

  1. Выполните следующую команду, чтобы создать приложение C#:

    dotnet new console -o ChatQuickstart

  2. Измените каталог на новую папку приложения и выполните 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#

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

  1. В Visual Studio откройте проект чата.

  2. Щелкните правой кнопкой мыши проект ChatQuickstart и выберите "Опубликовать".

    Screenshot that shows deploying the chat application to Azure from Visual Studio.

  3. После публикации решения запустите его и проверка, если 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.