你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：将机器人添加到聊天应用

项目
11/07/2024

了解如何使用 Azure 机器人服务中提供的 Azure 通信服务聊天消息通道在聊天应用程序中构建对话 AI 体验。在本快速入门中，你将使用 BotFramework SDK 创建一个机器人。然后，将此机器人集成到使用通信服务聊天 SDK 创建的聊天应用程序中。

此快速入门介绍如何：

在 Azure 中创建和部署机器人
获取通信服务资源
为机器人启用通信服务聊天通道
创建聊天应用并将机器人添加为参与者
探索机器人的更多功能

先决条件

Azure 帐户和有效的订阅。免费创建帐户。
Visual Studio 2019 或更高版本。
最新版本的 .NET Core。 (https://dotnet.microsoft.com/download/dotnet/)。
Bot Framework SDK

在 Azure 中创建和部署机器人

若要将 Azure 通信服务聊天用作 Azure 机器人服务中的通道，首先请部署一个机器人。若要部署机器人，请完成以下步骤：

创建 Azure 机器人服务资源
获取机器人的应用 ID 和密码
创建用于保存机器人应用的 Web 应用
为机器人创建消息传递终结点

创建 Azure 机器人服务资源

首先，使用 Azure 门户创建 Azure 机器人服务资源。通信服务聊天通道支持单租户机器人、托管标识机器人和多租户机器人。

在本快速入门中，我们将使用 multitenant 机器人。
若要设置 single-tenant 或 managed identity 机器人，请查看机器人标识信息。
对于 managed identity 机器人，你可能必须更新机器人服务标识。

获取机器人的应用 ID 和应用密码

接下来，获取部署机器人时分配给机器人的 Microsoft 应用 ID 和密码。稍后将使用这些值来完成配置。

创建机器人应用并将其发布到 Web 应用

若要创建机器人，可以执行下列操作之一：

针对你的场景修改 Bot Builder 示例，创建一个 Web 应用，然后将机器人示例部署到其中。
使用 Bot Builder SDK 创建机器人并将其发布到一个 Web 应用。

在本快速入门中，我们将使用 Bot Builder 示例中的 Echo Bot 示例。

创建用于保存机器人应用的 Web 应用

若要创建 Web 应用，请使用 Azure CLI 创建 Azure 应用服务资源，或者在 Azure 门户中创建应用。

若要使用 Azure 门户创建机器人 Web 应用，请执行以下操作：

在门户中，选择“创建资源”。在搜索框中，输入“Web 应用”。选择“Web 应用”磁贴。
在“创建 Web 应用”中，选择或输入应用的详细信息，包括要在其中部署该应用的区域。
选择“查看 + 创建”以验证部署并查看部署详细信息。然后选择“创建”。
创建 Web 应用资源后，复制资源详细信息中显示的主机名 URL。该 URL 是为 Web 应用创建的终结点的一部分。

为机器人创建消息传递终结点

Azure 机器人服务通常要求机器人应用程序 Web 应用控制器以 /api/messages 形式公开一个终结点。该终结点将处理发送到机器人的所有消息。

接下来，在机器人资源中创建 Web 应用消息传递终结点：

在 Azure 门户中，转到你的 Azure 机器人资源。在资源菜单中，选择“配置”。
在“配置”中，对于“消息传递终结点”，请粘贴在上一部分中复制的 Web 应用主机名 URL。使用 /api/messages 附加 URL。
选择“保存”。

部署 Web 应用

创建机器人的最后一步是部署 Web 应用。本快速入门使用 Echo Bot 示例。复述机器人功能仅限于复述用户输入。下面介绍如何将其部署到 Azure 中的 Web 应用：

使用 Git 克隆此 GitHub 存储库：

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

在 Visual Studio 中，打开复述机器人项目。
在 Visual Studio 项目中，打开 Appsettings.json 文件。粘贴前面复制的 Microsoft 应用 ID 和应用密码：
```
   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>",
       "MicrosoftAppTenantId": ""
   }
```
接下来，使用适用于 C# 机器人的 Visual Studio 或 VS Code 部署该机器人。

也可以使用命令提示符窗口部署 Azure 机器人。
在 Visual Studio 的解决方案资源管理器中，右键单击“EchoBot”项目，然后选择“发布”：
选择“新建”以创建新的发布配置文件。对于“目标”，请选择“Azure”：

对于特定目标，请选择“Azure 应用服务”：
在部署配置中，选择在登录到 Azure 帐户后显示的结果中的 Web 应用。若要完成配置文件，请选择“完成”，然后选择“发布”以开始部署。

获取通信服务资源

创建并部署机器人后，请创建一个用于设置通信服务通道的通信服务资源：

完成创建通信服务资源的步骤。
创建一个通信服务用户并颁发用户访问令牌。请务必将范围设置为“聊天”。复制令牌字符串和用户 ID 字符串。

启用通信服务聊天通道

获取通信服务资源后，可以在机器人资源中设置通信服务通道。在此过程中，将为机器人生成一个用户 ID。

在 Azure 门户中，转到你的 Azure 机器人资源。在资源菜单中，选择“通道”。在可用通道列表中，选择“Azure 通信服务 - 聊天”。
选择“连接”，查看订阅中可用的通信服务资源列表。
在“新建连接”窗格中选择通信服务聊天资源，然后选择“应用”。
验证资源详细信息后，机器人 ID 将显示在“机器人 Azure 通信服务 ID”列中。可以使用机器人 ID 通过通信服务聊天 AddParticipant API 来表示聊天线程中的机器人。将机器人添加为聊天参与者后，它将开始接收聊天相关的活动，并可以在聊天线程中给予回复。

创建聊天应用并将机器人添加为参与者

获取机器人的通信服务 ID 后，接下来可以创建一个聊天线程，机器人是其中的参与者。

遵循“向应用中添加聊天”快速入门

按照向应用中添加聊天快速入门中的步骤创建一个聊天应用。

将 <Resource_Endpoint> 替换为获取通信服务资源步骤中的通信服务终结点。
将 <Access_Token> 替换为获取通信服务资源步骤中的用户访问令牌。
将 <Access_ID> 替换为启用通信服务聊天频道步骤中的机器人 ACS_ID。

在本地运行 C# 应用程序

若要在本地运行聊天应用程序，请使用 dotnet run 命令：

dotnet run

你应该会在控制台中收到一条来自机器人的消息，该消息显示“Hello World”。

示例输出：

1730405535010:Hello World

机器人的其他作用

机器人不仅只能在通信服务聊天通道中接收来自用户的纯文本消息。机器人可以从用户那里接收的一些活动包括：

对话更新
消息更新
消息删除
键入指示符
事件活动
各种附件，包括自适应卡片
机器人通道数据

接下来的部分通过一些示例演示了这些功能。

将新用户添加到线程时发送欢迎消息

当前的复述机器人逻辑接受并复述用户的输入。如果你想要添加更多逻辑（例如响应“已添加参与者”通信服务事件），请复制以下代码并将其粘贴到 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 字段包含事件的名称。

在以下示例中，包含有效负载 "{field1":"value1", "field2": { "nestedField":"nestedValue" }} 的事件名称 endOfConversation 将发送到机器人：

{
    "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。

支持的机器人活动字段

以下部分介绍机器人到用户消息流和用户到机器人消息流支持的机器人活动字段。

机器人到用户消息流

机器人到用户消息流支持以下机器人活动字段。

活动

消息
Typing

消息活动字段

Text
Attachments
AttachmentLayout
SuggestedActions
From.Name（转换为通信服务 SenderDisplayName。）
ChannelData（转换为通信服务 Chat Metadata。如果任何 ChannelData 映射值为对象，则它们将序列化为 JSON 格式并作为字符串发送。）

用户到机器人消息流

用户到机器人消息流支持以下机器人活动字段。

活动和字段

消息
- Id（通信服务聊天消息 ID）
- TimeStamp
- Text
- Attachments
对话更新
- MembersAdded
- MembersRemoved
- TopicName
消息更新
- Id（已更新的通信服务聊天消息 ID）
- Text
- Attachments
消息删除
- Id（已删除的通信服务聊天消息 ID）
事件
- Name
- Value
Typing

其他常见字段

Recipient.Id 和 Recipient.Name（通信服务聊天用户 ID 和显示名称）
From.Id 和 From.Name（通信服务聊天用户 ID 和显示名称）
Conversation.Id（通信服务聊天线程 ID）
ChannelId（如果为空，则为通信服务聊天）
ChannelData（通信服务聊天消息元数据）

机器人交接模式

有时机器人无法理解或回答问题。客户可能会请求将机器人连接到人工座席。在这种情况下，必须将聊天线程从机器人交接到人工座席。可以将应用程序设计为将对话从机器人转接到人类用户。

处理机器人之间的通信

在某些用例中，可能需要将两个机器人添加到同一聊天线程来提供不同的服务。在这种情况下，可能需要确保一个机器人不会对另一个机器人的消息发送自动回复。如果处理不当，机器人之间的自动交互可能会导致消息无限循环。

可以在活动的 From.Id 属性中验证消息发送者的通信服务用户标识。检查它是否属于另一个机器人。然后，执行所需的操作来防止机器人之间的通信流。如果这种情况导致较高的通话量，通信服务聊天通道会限制请求，因而机器人将无法发送和接收消息。

详细了解限制。

疑难解答

以下部分介绍如何排查常见问题。

无法添加聊天通道

在 Microsoft Bot Framework 开发人员门户中，转到“配置”>“机器人消息传递”，验证是否已正确设置终结点。

机器人在回复消息时遇到已禁止异常

验证机器人的 Microsoft 应用 ID 和密码是否已正确保存在上传到 Web 应用的机器人配置文件中。

无法将机器人添加为参与者

验证在发送将机器人添加到聊天线程的请求时是否正确使用了机器人的通信服务 ID。

后续步骤

聊天入门

你可能还想要：

熟悉聊天的概念
了解如何对聊天进行定价

通过