将助手发布到移动或自定义应用

项目
08/12/2024

可以将助手添加到自定义应用，以便应用的用户直接从应用内部与助手交互。

在大多数情况下，自定义应用是基于 Web 的移动设备应用或充当业务需要的其他服务的适配器的移动设备应用。

移动应用的连接过程不同，具体取决于应用是基于 Web 的应用还是本机应用。

将助手连接到基于 Web 的应用相对简单，因为涉及将代码段复制到应用中。但是，基于 Web 的应用和本机或自定义应用仍然都需要相当丰富的开发人员专业知识，才能将助手完全集成到应用中。本文中对这两种过程均有描述。

先决条件

.NET Core SDK 版本 2.1。
Nuget 包 Microsoft.Bot.Connector.DirectLine。
在 Copilot Studio 中创建以连接到应用的助手。

将助手连接到基于 Web 的应用

在 Copilot Studio 内的导航菜单中的设置下面，选择渠道。
选择移动应用磁贴打开配置窗口。
复制基于 Web 的应用部分下的代码，然后将其提供给应用开发人员以添加到基于 Web 的应用中。

将助手连接到本机应用或自定义应用

小费

虽然本部分介绍的是如何连接到移动应用，也可以将相同流程应用于自定义应用或本机应用，如 IoT（物联网）应用。

如果您的目标是连接到 Azure 机器人服务渠道，开发人员除了遵守此处的说明，还可以在将助手发布到 Azure 机器人服务渠道中了解更多信息。

重要提示

本部分中的说明要求您或您的开发人员进行软件开发。其面向经验丰富的 IT 专业人士，如深谙开发人员工具、实用程序和 IDE 的 IT 管理员或开发人员。

代码示例

本文中使用的代码段来自：

连接器示例代码

引用

本文档中的说明引用了以下源材料：

检索 Copilot Studio 助手参数

若要连接到创建的助手，需要检索助手的名称和令牌终结点进行识别。

在 Copilot Studio 中复制助手的名称。
在导航菜单中的设置下面，选择渠道。
选择移动应用。
在令牌终结点旁边，选择复制。获取 Direct Line 令牌步骤中需要此终结点。

获取 Direct Line 令牌

若要开始与助手对话，需要 Direct Line 令牌。可以通过向 Copilot Studio 屏幕中指示的端点发出 GET 请求来获取此令牌。然后，必须将该令牌用作对 directline API 的后续调用的标头。

示例:

GET <BOT TOKEN ENDPOINT>

如果请求成功，将返回 Direct Line 令牌、过期时间和所请求助手的 conversationId。示例:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

示例代码示例

以下示例使用连接器示例代码的示例获取 Copilot Studio 助手的 Direct Line 令牌。

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

响应对象将与我们之前看到的 GET 请求相同

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

使用 Direct Line 与助手通信

检索 Direct Line 令牌之后，就可以使用 Direct Line 与 Copilot Studio 助手对话。按照 Bot Framework Direct Line API 中的说明启动对话并收发消息。

以下示例使用连接器示例代码中的示例启动对话和与 Copilot Studio 助手收发消息。

使用 Direct Line 令牌初始化 DirectLineClient 示例并启动对话：

   // Use the retrieved token to create a DirectLineClient instance
   using (var directLineClient = new DirectLineClient(token))
   {
       var conversation = await directLineClient.Conversations.StartConversationAsync();
       string conversationtId = conversation.ConversationId;
   }

启动后，可以使用 token 和 conversationtId 的组合识别和连接每个对话。向现有对话发送用户消息：

   // Use the retrieved token to create a DirectLineClient instance
   // Use the conversationId from above step
   // endConversationMessage is your predefined message indicating that user wants to quit the chat
   while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
   {
       using (var directLineClient = new DirectLineClient(token))
       {
           // Send user message using directlineClient
           // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
           await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
           {
               Type = ActivityTypes.Message,
               From = new ChannelAccount { Id = "userId", Name = "userName" },
               Text = inputMessage,
               TextFormat = "plain",
               Locale = "en-Us",
           });
       }
   }

使用相同 token 和 conversationId 检索助手的回复。检索到的 Direct Line 响应活动中同时包含用户的消息和助手的消息。可以按助手的名称筛选响应活动以仅获取助手的响应消息。

   // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0

       // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
       ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);

       // update watermark from response
       watermark = response?.Watermark;

       // response contains set of Activity from both user and bot
       // To display bot response only, filter Activity.From.Name equals to your bot name
       List<Activity> botResponses = response?.Activities?.Where(x =>
                 x.Type == ActivityTypes.Message &&
                   string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();

       // Display botResponses
   }

刷新 Direct Line 令牌

如果应用程序与助手的对话很长，可能需要添加代码以刷新 Direct Line 令牌。令牌会到期，但是可以在到期前刷新；有关详细信息，请参阅 Direct Line 身份验证。

以下示例使用连接器示例代码中的示例刷新现有 Copilot Studio 对话的令牌。

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

分析助手中的对话有效负载

开始与助手对话之后，对话 JSON 有效负载使用标准 Microsoft Bot Framework Direct Line 活动。可以在 Bot Framework Direct Line API 中了解详细信息。

处理转接活动

如果应用程序需要转接给人工代理提供程序，需要处理转接活动。如果点击“转接到代理”节点，将发送转接活动。可以详细了解转接活动的有效负载。

触发欢迎消息

如果要让助手在用户启动对话时自动发送问候系统主题，您可以发送 Type=event 和 Name=startConversation 的活动。

通过