QnA Maker ボットにテレメトリを追加する

[アーティクル]
07/20/2023

適用対象: SDK v4

注意

Azure AI QnA Maker は、2025 年 3 月 31 日に廃止される予定です。 2022 年 10 月 1 日から、新しい QnA Maker リソースやナレッジベースを作成することはできません。 Azure AI Language の一部として、新しいバージョンの質問と回答機能が利用できるようになりました。

Azure AI Language の機能であるカスタム質問応答は、QnA Maker サービスの更新バージョンです。 Bot Framework SDK での質問と回答のサポートの詳細については、「自然言語の理解」を参照してください。

テレメトリログを使用すると、ボットアプリケーションは Application Insights などのテレメトリサービスにイベントデータを送信できます。テレメトリは、どの機能が最も使用されているかを示すことによりボットの分析情報を提供し、不要な動作を検出し、可用性、パフォーマンス、および使用状況を可視化します。

TelemetryLoggerMiddleware Bot Framework SDK のクラスと QnAMaker クラスは、QnA Maker 対応ボットでテレメトリログを有効にします。 TelemetryLoggerMiddleware は、メッセージの受信、送信、更新、または削除のたびにテレメトリをログに記録するミドルウェアコンポーネントであり QnAMaker 、クラスはテレメトリ機能を拡張するカスタムログを提供します。

この記事では、次の内容について説明します。

ボットにテレメトリを実装するために必要なコード
標準のイベントプロパティを使用するすぐに使用できる QnA Maker ログとレポートを有効にするために必要なコード。
幅広いレポートのニーズに応えるために、SDK の既定のイベントプロパティを変更または拡張する方法。

前提条件

QnA Maker サンプルコード
Microsoft Azure のサブスクリプション。
Application Insights のキー
QnA Maker について理解していると役に立ちます。
QnA Maker アカウント。
既存の発行済み QnA Maker サポート情報。

注意

この記事は、テレメトリを組み込むために必要な手順をステップ実行することで、QnA Maker サンプルコードに基づいています。

QnA Maker ボットにテレメトリコードを追加する

まず、QnA Maker サンプルアプリから始めて、テレメトリを QnA Maker サービスを使用するボットに統合するために必要なコードを追加します。これにより、Application Insights で要求を追跡できるようになります。

Visual Studio で QnA Maker サンプルアプリを開きます。
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet パッケージを追加します。 NuGet の使用方法について詳しくは、「Visual Studio にパッケージをインストールして管理する」を参照してください。
次のステートメントを Startup.cs に含めます。
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
注意

QnA Maker サンプルコードを更新してフォローしている場合は、の Microsoft.Bot.Builder.Integration.AspNet.Core using ステートメントが QnA Maker サンプルに既に存在していることがわかります。

Startup.cs で、ConfigureServices() メソッドに次のコードを追加します。こうすることで、依存関係の挿入 (DI) によりテレメトリサービスをボットで使用できるようになります。

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    ...
    // Create the Bot Framework Adapter with error handling enabled.
    services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();

    // Add Application Insights services into service collection
    services.AddApplicationInsightsTelemetry();

    // Add the standard telemetry client
    services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();

    // Create the telemetry middleware to track conversation events
    services.AddSingleton<TelemetryLoggerMiddleware>();

    // Add the telemetry initializer middleware
    services.AddSingleton<IMiddleware, TelemetryInitializerMiddleware>();

    // Add telemetry initializer that will set the correlation context for all telemetry items
    services.AddSingleton<ITelemetryInitializer, OperationCorrelationTelemetryInitializer>();

    // Add telemetry initializer that sets the user ID and session ID (in addition to other bot-specific properties, such as activity ID)
    services.AddSingleton<ITelemetryInitializer, TelemetryBotIdInitializer>();
    ...
}

注意

QnA Maker サンプルコードを更新してフォローしている場合は、既に存在している services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); ことがわかります。

ConfigureServices() メソッドに追加されたミドルウェアコードを使用するようにアダプターに指示します。 AdapterWithErrorHandler.cs を開き、IMiddleware middleware をコンストラクターのパラメーターリストに追加します。ステートメントを Use(middleware); コンストラクターの最後の行として追加します。
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
appsettings.json ファイルで、Application Insights のインストルメンテーションキーを追加します。この appsettings.json ファイルには、Cosmos DB、Application Insights、QnA Maker の接続とメタデータなど、ボットが実行中に使用する外部サービスに関するメタデータが含まれています。 appsettings.json ファイルへの追加は、次の形式にする必要があります。
```
{
    "MicrosoftAppId": "",
    "MicrosoftAppPassword": "",
    "QnAKnowledgebaseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "QnAEndpointKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "QnAEndpointHostName": "https://xxxxxxxx.azurewebsites.net/qnamaker",
    "ApplicationInsights": {
        "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}
```
注意
- Application Insights のインストルメンテーションキーの取得の詳細については、「Application Insights キー」の記事をご覧ください。
- QnA Maker アカウントが既にあるはずです。 QnA Maker サポート情報 ID、エンドポイントキー、ホスト値の取得については、「GenerateAnswer API を使用した QnA Maker の回答の取得」の「GenerateAnswer エンドポイントを取得するための発行」セクションを参照してください。

この時点で、Application Insights を使用してテレメトリを有効にする準備作業が行われます。 Bot Framework Emulatorを使用してボットをローカルで実行し、Application Insights に移動して、応答時間、アプリの全体的な正常性、一般的な実行情報など、ログに記録されている内容を確認できます。

ヒント

個人情報の詳細については、「アクティビティイベントと個人情報のログ記録を有効または無効にする」を参照してください。

次に、QnA Maker サービスにテレメトリ機能を追加するために含める必要がある内容を確認します。

テレメトリを有効にして QnA Maker サービスから使用状況データをキャプチャする

QnA Maker サービスには利用できるテレメトリログが組み込まれているため、QnA Maker からのテレメトリデータの取得を開始するために行う必要はほとんどありません。まず、QnA Maker コードにテレメトリを組み込んで組み込みのテレメトリログを有効にする方法について説明します。次に、既存のイベントデータにプロパティを置き換えたり追加したりして、幅広いレポートのニーズを満たす方法について説明します。

既定の QnA Maker ログ記録を有効にする

IBotTelemetryClient 型の private の読み取り専用フィールドを QnABot.cs の QnABot クラスに作成します。

public class QnABot : ActivityHandler
    {
        private readonly IBotTelemetryClient _telemetryClient;
        ...
}

QnABot.cs の QnABot クラスのコンストラクターに IBotTelemetryClient パラメーターを追加し、前の手順で作成した private フィールドにその値を割り当てます。

public QnABot(IConfiguration configuration, ILogger<QnABot> logger, IHttpClientFactory httpClientFactory, IBotTelemetryClient telemetryClient)
{
    ...
    _telemetryClient = telemetryClient;
}

telemetryClient パラメーターは、QnABot.cs で新しい QnAMaker オブジェクトをインスタンス化するときに必要です。
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
ヒント

エントリで_configuration使用するプロパティ名が、AppSettings.json ファイルで使用したプロパティ名と一致し、それらのプロパティの値が、QnA Maker ポータルの [マイナレッジベース] ページの [コードの表示] ボタンを選択して取得されていることを確認します。

QnA Maker の既定のエントリからログに記録されたテレメトリデータを表示する

次の手順を実行して、Bot Framework Emulatorでボットを実行した後、Application Insights で QnA Maker ボットの使用状況の結果を表示できます。

Azure portalで、ボットの Application Insights リソースに移動します。
[監視] で [ログ] を選択します。

次の Kusto クエリを入力し、[ 実行] を選択します。

customEvents
| where name == 'QnaMessage'
| extend answer = tostring(customDimensions.answer)
| summarize count() by answer

ブラウザーでこのページを開いたままにします。新しいカスタムプロパティを追加した後に戻ります。

ヒント

Azure Monitor でログクエリを記述するために使用される Kusto クエリ言語を初めて使用するが、SQL クエリ言語に精通している場合は、 SQL to Azure Monitor ログクエリチートシートが役立つ場合があります。

既定のイベントプロパティを変更または拡張する

クラスで QnAMaker 定義されていないプロパティが必要な場合は、これを処理する 2 つの方法があります。両方とも、クラスから派生した独自のクラスを作成する QnAMaker 必要があります。最初の方法では、後出の「プロパティの追加」で説明しているように、既存の QnAMessage イベントにプロパティを追加します。 2 番目の方法では、「カスタムプロパティを持つ新しいイベントの追加」で説明しているように、プロパティの追加が可能な新しいイベントを作成します。

注意

QnAMessage イベントは Bot Framework SDK に含まれており、Application Insights のログに記録される、すぐに使用できるイベントプロパティをすべて提供します。

プロパティの追加

次に示すのは、QnAMaker クラスから派生する方法の例です。この例では、"MyImportantProperty" プロパティを QnAMessage イベントに追加しています。 QnAMessage イベントは、QnA の GetAnswers 呼び出しが実行されるたびにログに記録されます。

カスタムプロパティを追加する方法を学習した後、新しいカスタムイベントを作成し、それにプロパティを関連付ける方法を学習した後、Bot Framework Emulatorを使用してボットをローカルで実行し、Kusto クエリ言語を使用して Application Insights でログに記録されている内容を確認します。

QnAMaker クラスを継承する MyQnAMaker という名前の新しいクラスを Microsoft.BotBuilderSamples 名前空間に作成し、MyQnAMaker.cs という名前で保存します。クラスから QnAMaker 継承するには、using ステートメントを追加 Microsoft.Bot.Builder.AI.QnA する必要があります。コードは次のようになります。
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

にクラスコンストラクターを MyQnAMaker追加します。とのコンストラクターパラメーターには、さらに 2 つの using ステートメントがSystem.Net.HttpMicrosoft.Bot.Builder必要です。

using Microsoft.Bot.Builder.AI.QnA;
using System.Net.Http;
using Microsoft.Bot.Builder;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {
        public MyQnAMaker(
            QnAMakerEndpoint endpoint,
            QnAMakerOptions options = null,
            HttpClient httpClient = null,
            IBotTelemetryClient telemetryClient = null,
            bool logPersonalInformation = false)
            : base(endpoint, options, httpClient, telemetryClient, logPersonalInformation)
        {

        }
    }
}

コンストラクターの後に、新しいプロパティを QnAMessage イベントに追加し、ステートメント System.Collections.Generic、System.Threading、および System.Threading.Tasks をインクルードします。

using Microsoft.Bot.Builder.AI.QnA;
using System.Net.Http;
using Microsoft.Bot.Builder;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace Microsoft.BotBuilderSamples
{
        public class MyQnAMaker : QnAMaker
        {
        ...

        protected override async Task OnQnaResultsAsync(
                            QueryResult[] queryResults,
                            Microsoft.Bot.Builder.ITurnContext turnContext,
                            Dictionary<string, string> telemetryProperties = null,
                            Dictionary<string, double> telemetryMetrics = null,
                            CancellationToken cancellationToken = default(CancellationToken))
        {
            var eventData = await FillQnAEventAsync(
                                    queryResults,
                                    turnContext,
                                    telemetryProperties,
                                    telemetryMetrics,
                                    cancellationToken)
                                .ConfigureAwait(false);

            // Add new property
            eventData.Properties.Add("MyImportantProperty", "myImportantValue");

            // Log QnAMessage event
            TelemetryClient.TrackEvent(
                            QnATelemetryConstants.QnaMsgEvent,
                            eventData.Properties,
                            eventData.Metrics
                            );
        }

    }
}

オブジェクトを作成する代わりに、でオブジェクトQnABot.csを作成する代わりに、新しいクラスをQnAMaker使用するようにボットをMyQnAMaker変更します。

var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);

新しいプロパティ MyImportantProperty からログに記録されたテレメトリデータを表示する

エミュレーターでボットを実行した後、次の操作を行って Application Insights で結果を表示できます。

[Logs (Analytics)]\(ログ (分析)\) ビューがアクティブになっているブラウザーに戻ります。

次の Kusto クエリを入力して [実行] を選択します。これにより、新しいプロパティが実行された回数が表示されます。

customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
| summarize count() by MyImportantProperty

カウントの代わりに詳細を表示するには、最後の行を削除してクエリを再実行します。

customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)

カスタムプロパティを使用して新しいイベントを追加する

QnaMessage 以外のイベントにデータのログを記録する必要がある場合、独自のプロパティを持つ独自のカスタムイベントを作成することができます。これを行うには、次のようにクラスの末尾にコードを MyQnAMaker 追加します。

public class MyQnAMaker : QnAMaker
{
    ...

    // Create second event.
    var secondEventProperties = new Dictionary<string, string>();

    // Create new property for the second event.
    secondEventProperties.Add(
                        "MyImportantProperty2",
                        "myImportantValue2");

    // Log secondEventProperties event
    TelemetryClient.TrackEvent(
                    "MySecondEvent",
                    secondEventProperties);

}

Application Insights ダッシュボード

Azure で Application Insights リソースを作成するたびに、Azure によってリソースに関連付けられた新しいダッシュボードが作成されます。 [Application Insights] ブレードからダッシュボードを表示するには、[ アプリケーションダッシュボード] を選択します。

または、データを表示するには、Azure portalに移動し、ポータルメニューを展開して、[ダッシュボード] を選択します。次に、ドロップダウンメニューから目的のダッシュボードを選択します。

ダッシュボードには、ボットのパフォーマンスに関する既定の情報と、ダッシュボードにピン留めしたその他のクエリが表示されます。

次の方法で共有

QnA Maker ボットにテレメトリを追加する

前提条件

QnA Maker ボットにテレメトリコードを追加する

テレメトリを有効にして QnA Maker サービスから使用状況データをキャプチャする

既定の QnA Maker ログ記録を有効にする

QnA Maker の既定のエントリからログに記録されたテレメトリデータを表示する

既定のイベントプロパティを変更または拡張する

プロパティの追加

新しいプロパティ MyImportantProperty からログに記録されたテレメトリデータを表示する

カスタムプロパティを使用して新しいイベントを追加する

Application Insights ダッシュボード

追加情報

その他のリソース

次の方法で共有

QnA Maker ボットにテレメトリを追加する

前提条件

QnA Maker ボットにテレメトリ コードを追加する

テレメトリを有効にして QnA Maker サービスから使用状況データをキャプチャする

既定の QnA Maker ログ記録を有効にする

QnA Maker の既定のエントリからログに記録されたテレメトリ データを表示する

既定のイベント プロパティを変更または拡張する

プロパティの追加

新しいプロパティ MyImportantProperty からログに記録されたテレメトリ データを表示する

カスタム プロパティを使用して新しいイベントを追加する

Application Insights ダッシュボード

追加情報

その他のリソース

QnA Maker ボットにテレメトリコードを追加する

QnA Maker の既定のエントリからログに記録されたテレメトリデータを表示する

既定のイベントプロパティを変更または拡張する

新しいプロパティ MyImportantProperty からログに記録されたテレメトリデータを表示する

カスタムプロパティを使用して新しいイベントを追加する