Azure Bot Service チャネルでコパイロットを公開する

既存の Azure Bot Serviceチャネル にコパイロットを 接続 することができます。これは、Azure Bot Serviceチャネルのエンド ユーザーにコパイロットを 接続 する場合に役立ちます。

コパイロットを Azure Bot Service チャネルに追加するには、開発者の十分な専門知識が必要です。 この記事は、コードの開発と記述の経験がある IT 管理者または開発者向けに書かれています。

前提条件

• Azure Bot Service サブスクリプション。
• v4 SDK を使用する Azure Bot Service ボ ット。
• .NET Core SDK バージョン2.1。
• NuGet パッケージ Microsoft.Bot.Connector.DirectLine。
• Azure Bot Service チャネルに接続する Copilot Studio で作成されたコパイロット。
• モバイル アプリまたはカスタム アプリにコパイロットを公開します。

コード サンプル

このドキュメントで使用されているコード スニペットは中継ボットのサンプル コード からのものです。

参照

このドキュメントの手順では、次のドキュメントを参照しています。

• Azure Bot Serviceボット. のデプロイ手順については、 ボット をAzureにデプロイしてください。
• Azure Bot Serviceチャネル から 接続 へ、任意のAzureボット サービス対応チャネルへ。
• Azure Bot Serviceエミュレーターを使用したデバッグ Azure Bot Serviceボット. のデバッグ手順については、こちらを参照してください。

既存の Azure Bot Service ボットを作成または使用する

Copilot Studio コパイロットと Azure Bot Service チャネル間の会話を中継できる Azure Bot Service ボットが必要です。

既存のAzure Bot Serviceボット. がない場合は、 リレー ボット サンプル コード が適切な開始 ポイントする になります。 これは、コンパイルしてAzure Bot Serviceにデプロイできる Microsoft Bot Framework ボット サンプル コード から構築されています。 サンプル コードは開始点として使用することを意図しており、運用環境で直接使用することを意図していません。 ビジネスニーズに合わせてコードと最適化を追加する必要があります。

Azure Bot Service ボットが既にある場合は、Copilot Studio コネクタと会話セッションを管理するためのとコードを追加する必要があります。 次に、ボットを Azure Bot Service に展開し、Azure Portal でチャネルに接続できます。

Copilot Studio コパイロット パラメーターを取得する

Copilot Studioで構築した副操縦士に 接続 するには、副操縦士の名前とトークン エンドポイント を取得する必要があります。

1. Copilot Studio にコパイロットの名前をコピーします。

   

2. ナビゲーション メニューの 設定 で チャネル を選択します。

3. 接続するチャネルを選択します。 このシナリオでは、例として Slack を使用します。

   

4. トークン エンドポイント 値をコピーして保存するには、コピー を選択します。 Azure Bot Serviceチャネルに副操縦士を 接続 するには、エンドポイント が必要です。

   

Copilot Studio コパイロットを使用して会話セッションを管理する

Azure Bot Service チャネルと Copilot Studio コパイロットとの Direct Line 接続の間には、複数の会話が可能です。

Azure Bot Serviceボット は、Azure Bot Serviceチャネルからの会話を、 Direct Line 副操縦士との会話 Copilot Studio にマッピングして中継する必要があり、その逆も同様です。

サンプル コードの例

次の例では、中継ボットのサンプル コード からのサンプルを使用します。

1. 新しい外部 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;
    }
   

2. 複数のセッションを管理するには、外部の Azure Bot Service チャネル会話に対応する Copilot Studio コパイロット会話へのマッピングを維持する必要があります。 Copilot Studio コパイロット会話は、2 つのプロパティで識別および接続されます: ConversationtId および Token。

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

   会話のライフサイクルを管理するには、Direct Line トークンを更新するか、アイドル状態の会話をクリーンアップします。 トークンの更新について詳しくは、Direct Line トークンの更新 を参照してください。 トークンの更新をサポートする Copilot Studio コパイロット会話 Direct Line は次のように定義されます。

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

3. 新しい 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,
     }; 
   

4. 既存の会話を続行するには、受信した新しい外部 Azure Bot Service チャネル メッセージに対して、マッピング テーブルから既存の会話を取得し、外部会話アクティビティを Copilot Studio コパイロットに中継し、応答を取得します。

   次のサンプルは、ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken) method を上書きすることで会話を中継していることを示します

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

5. Copilot Studio コパイロットの応答を取得する方法については、Direct Line を使用してコパイロットと通信 を参照してください。 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 チャネル で表示されます。