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

Статья
11/05/2024

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

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

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

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

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

Поделиться через