將副手發佈至 Azure Bot Service 管道

文章
09/27/2024

可以將 Copilot 連線到現有的 Azure Bot Service 通道，如果要將 Copilot 連線 Azure Bot Service 通道上的最終使用者，這會很有説明。

將副手新增至 Azure Bot Service 管道需要大量的開發人員專業知識。本文是為具備開發和撰寫程式碼的 IT 系統管理員或開發人員所撰寫。

提示

您不需要依照此文件，將您的 Copilot Studio 副手新增至您的網站、Facebook 或 Microsoft Teams。如果您的目標是連接至自訂的 Web 或原生應用程式，則您的開發人員可以在將副手發佈至行動應用程式或自訂應用程式中學到更多內容。

重要

本節中的指示需要由您或您的開發人員進行軟體開發。它適用於有經驗的 IT 專業人員，例如 IT 系統管理員或開發人員，他們深刻了解開發人員工具、公用程式及 IDE。

先決條件

Azure Bot Service 訂閱。
使用 v4 SDK 的 Azure Bot Service 機器人。
.NET Core SDK 版本 2.1。
Nuget 套件 Microsoft.Bot.Connector.DirectLine。
在 Copilot Studio 中建立的用來連接至 Azure Bot Service 管道的副手。
將 Copilot 發佈到移動或自訂應用程式。

程式碼範例

本文所用的程式碼片段來自於中繼機器人範例程式碼。

建立或使用現有的 Azure Bot Service 機器人

您需要可在您的 Copilot Studio 副手和 Azure Bot Service 管道之間中繼交談的 Azure Bot Service 機器人。

中繼機器人圖解。

如果您沒有現有的 Azure Bot Service 機器人，則 relay 機器人示例代碼是一個很好的起點指向。它是根據範例代碼 Microsoft Bot Framework 構建的機器人可編譯並部署到 Azure Bot Service。範例程式碼是用做為起始點，而不是要直接用於生產中。您需要添加代碼和優化以滿足您的業務需求。

如果您已經有 Azure Bot Service 機器人，則需要新增 Copilot Studio 連接器和程式碼，才能管理交談工作階段。然後，您可以將機器人部署至 Azure Bot Service，並使用 Azure 入口網站連接至管道。

取得您的 Copilot Studio 副手參數

要連線您構建的 Copilot Studio Copilot，您需要檢索 Copilot 的名稱和令牌端點。

在 Copilot Studio 中複製您的副手名稱。
在導覽功能表的設定底下，選取管道。
選取您要連接的管道。此案例使用 Slack 做為範例。
若要複製並儲存權杖端點值，請選取複製。您需要端點將 Copilot 連線 Azure Bot Service 通道。

使用您的 Copilot Studio 副手管理交談工作階段

Azure Bot Service 管道與 Copilot Studio 副手的 Direct Line 連線之間可以存在多個交談。

您的 Azure Bot Service 機器人需要將對話從 Azure Bot Service 通道映射並中繼到 Direct Line 與 Copilot 的 Copilot Studio 對話，反之亦然。

範例程式碼

下列範例使用中繼機器人範例程式碼中的範例。

在每個新的外部 Azure Bot Service 管道交談開始時，開始 Copilot Studio 副手交談。請參閱取得 Direct Line 權杖，以及使用 Direct Line 來與副手通訊，取得開始與機器人進行新交談的指示。

using (var httpRequest = new HttpRequestMessage())
{   
    httpRequest.Method = HttpMethod.Get;
    UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
    httpRequest.RequestUri = uriBuilder.Uri;
    using (var response = await s_httpClient.SendAsync(httpRequest))
    {
        var responseString = await response.Content.ReadAsStringAsync();
        string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
    }
}

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

 // 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;
 }

若要管理多個工作階段，您需要維護外部 Azure Bot Service 管道交談至相應 Copilot Studio 副手交談的對應。您可以使用兩個屬性來識別和連接 Copilot Studio 副手交談：ConversationtId 與 Token。

Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();

若要管理交談生命週期，請重新整理 Direct Line 權杖或清除已閒置交談。如需深入了解權仗重新整理的資訊，請移至重新整理 Direct Line 權杖。 Copilot Studio 支援刷新 Direct Line 權杖的 Copilot 對話定義如下：

/// <summary>
/// Data model class for Copilot Studio copilot conversation
/// </summary>
public class PowerVirtualAgentsConversation
{
    public string ConversationtId { get; set; } // The Copilot Studio copilot conversation ID retrieved from step 1

    public string Token { get; set; } // The DirectLine token retrieved from step 1

    public string WaterMark { get; set; } // Identify turn in a conversation

    public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh

    public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to copilot
}

開始新的 Copilot Studio 副手交談時，請將索引鍵/值組 (external_Azure_Bot_Service_channel_conversationID、PowerVirtualAgentsConversation) 新增至對應資料表。

// After new Copilot Studio copilot conversation starts
ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
  {
    Token = token,
    ConversationtId = conversationId,
    WaterMark = null,
    LastConversationUpdateTime = DateTime.Now,
    LastTokenRefreshTime = DateTime.Now,
  };

若要在現有的交談中繼續進行，請在收到新的外部 Azure Bot Service 管道訊息之後，從對應表格中擷取現有的交談，將外部交談活動轉給您的 Copilot Studio 副手，並取得回覆。

下列範例透過覆寫 ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken) 方法來顯示中繼交談

// Invoked when a message activity is received from the user
// Send the user message to Copilot Studio copilot and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve copilot conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio copilot conversation
    ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
            currentConversation : /*await StartBotConversationAsync(externalCID)*/;

    // Create DirectLine client with the token associated to current conversation
    DirectLineClient client = new DirectLineClient(currentConversation.Token);

    // Send user message using directlineClient
    await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
    {
      Type = DirectLineActivityTypes.Message,
      From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
      Text = turnContext.Activity.Text,
      TextFormat = turnContext.Activity.TextFormat,
      Locale = turnContext.Activity.Locale,
    });

    // Update LastConversationUpdateTime for session management
    currentConversation.LastConversationUpdateTime = DateTime.Now;
}

請參閱使用 Direct Line 與副手通訊，瞭解如何取得 Copilot Studio 副手的回覆。收到 Copilot Studio 副手的回覆時，請參考從副手剖析交談承載，以了解如何將回應剖析為外部 Azure Bot Service 管道回覆。

您可以在中繼機器人範例程式碼 ResponseConverter.cs 中找到回覆剖析範例。

部署至 Azure Bot Service

在您將 Azure Bot Service 中繼機器人準備好之後，您需要將機器人部署到 Azure Bot Service。

設定 Azure Bot Service 管道

您可以通過登錄到 Azure 門戶並選擇部署到的 Azure Bot Service 資源組來設置要連線的通道。查看 Azure Bot Service 管道上每個管道的特定指示。

分享方式：