通过

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

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

  • 项目

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

此快速入门介绍如何：

先决条件

在 Azure 中创建和部署机器人

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

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

创建 Azure 机器人服务资源

首先，使用 Azure 门户创建 Azure 机器人服务资源。 通信服务聊天通道支持单租户机器人、托管标识机器人和多租户机器人。 在本快速入门中，我们将使用多租户机器人。

若要设置单租户或托管标识机器人，请查看机器人标识信息。

对于托管标识机器人，可能必须更新机器人服务标识。

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

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

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

若要为机器人创建 Web 应用，可以修改适用于你的方案的 Bot Builder 示例，或使用 Bot Builder SDK 创建 Web 应用。 最简单的示例之一是复述机器人。

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

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

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

  1. 在门户中，选择“创建资源”。 在搜索框中，输入“Web 应用”。 选择“Web 应用”磁贴。

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

  2. 在“创建 Web 应用”中，选择或输入应用的详细信息，包括要在其中部署该应用的区域。

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

  3. 选择“查看 + 创建”以验证部署并查看部署详细信息。 然后选择“创建”。

  4. 创建 Web 应用资源后，复制资源详细信息中显示的主机名 URL。 该 URL 是为 Web 应用创建的终结点的一部分。

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

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

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

  1. 在 Azure 门户中，转到你的 Azure 机器人资源。 在资源菜单中，选择“配置”。

  2. 在“配置”中，对于“消息传递终结点”，请粘贴在上一部分中复制的 Web 应用主机名 URL。 使用 /api/messages 附加 URL。

  3. 选择“保存”。

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

部署 Web 应用

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

  1. 使用 Git 克隆此 GitHub 存储库：

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

  2. 在 Visual Studio 中，打开复述机器人项目。

  3. 在 Visual Studio 项目中，打开 Appsettings.json 文件。 粘贴前面复制的 Microsoft 应用 ID 和应用密码：

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

    接下来，使用适用于 C# 机器人的 Visual Studio 部署该机器人。

    也可以使用命令提示符窗口部署 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 帐户后显示的结果中的 Web 应用。 若要完成配置文件，请选择“完成”，然后选择“发布”以开始部署。

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

获取通信服务资源

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

  1. 完成创建通信服务资源的步骤。

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

启用通信服务聊天通道

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

  1. 在 Azure 门户中，转到你的 Azure 机器人资源。 在资源菜单中，选择“通道”。 在可用通道列表中，选择“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. 验证资源详细信息后，机器人 ID 将显示在“机器人 Azure 通信服务 ID”列中。 可以使用机器人 ID 通过通信服务聊天 AddParticipant API 来表示聊天线程中的机器人。 将机器人添加为聊天参与者后，它将开始接收聊天相关的活动，并可以在聊天线程中给予回复。

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

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

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

新建 C# 应用程序

  1. 运行以下命令创建 C# 应用程序：

    dotnet new console -o ChatQuickstart

  2. 将目录更改为新的应用文件夹，并使用 dotnet build 命令编译应用程序：

    cd ChatQuickstart
dotnet build

安装包

安装适用于 .NET 的通信服务聊天 SDK：

dotnet add package Azure.Communication.Chat

创建聊天客户端

若要创建聊天客户端，需使用前面生成的通信服务终结点和用户访问令牌。 使用标识 SDK 中的 CommunicationIdentityClient 类来创建用户，并颁发要传递给聊天客户端的令牌。 可以按说明在门户中生成访问令牌。

复制以下代码并将其粘贴到 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);
        }
    }
}

对机器人启动聊天线程

使用 chatClient 上的 createChatThread 方法创建聊天线程。 将 ID 替换为机器人的通信服务 ID。

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 或 Azure 移动 SDK 来订阅传入消息通知：

// 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 是否在命令提示符处回显用户消息。 有了解决方案后，就可以继续执行需要解决的业务方案所需的各种活动了。

机器人的其他作用

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

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

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

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

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

后续步骤

尝试运行聊天机器人演示应用，通过 BotFramework WebChat UI 组件在聊天用户和机器人之间进行一对一的聊天。