検査ミドルウェアを使用してボットをデバッグする

この記事の対象: SDK v4

この記事では、検査ミドルウェアを使用してボットをデバッグする方法について説明します。 この機能を使用すると、Bot Framework Emulator で、ボットの現在の状態を確認でき、さらにボットの内外のトラフィックをデバッグできます。 トレース メッセージを使用してエミュレーターにデータを送信し、会話のある特定のターンでのボットの状態を調べることができます。

「ボット クイックスタートを作成する」で、Bot Framework v4 を用いてローカルに構築された EchoBot を使用し、ボットのメッセージの状態をデバッグおよび検査する方法を示します。 また、IDE を使用してボットをデバッグしたり、Bot Framework Emulator を使用してデバッグしたりすることもできますが、状態をデバッグするには、検査ミドルウェアをボットに追加する必要があります。 C#、JavaScript、Java、および Python の検査ボット サンプルを取得できます。

Note

Bot Framework JavaScript、C# および Python SDK は引き続きサポートされますが、Java SDK は、2023 年 11 月に終了する最終的な長期サポートとともに廃止される予定です。 このリポジトリ内の重要なセキュリティとバグの修正のみが行われます。

Java SDK を使用して構築された既存のボットは引き続き機能します。

新しいボットの構築については、Power Virtual Agents の使用を検討し、適切なチャットボット ソリューションの選択についてお読みください。

詳細については、「The future of bot building」をご覧ください。

前提条件

• ボットのミドルウェアと管理状態に関する知識。
• SDK 優先ボットをデバッグし、エミュレーターを使用してテストおよびデバッグする方法に関する知識
• Bot Framework Emulator のインストール
• ngrok をインストールする (他のチャンネルを使用するために、Azure に構成されているボットをデバッグする場合)
• C#、JavaScript、Java または Python の検索ボットサンプルのコピー。

エミュレーターを最新バージョンに更新する

ボット検査ミドルウェアを使用してボットをデバッグする前に、エミュレーターをバージョン 4.5 以降に更新します。 最新バージョンで更新プログラムを確認してください。

エミュレーターのバージョンを確認するには、メニューで [Help]、それから [About] の順に選択します。 お使いのエミュレーターの現在のバージョンが表示されます。

ボット コードを更新する

C#

[Startup.cs] ファイル内で検査状態と検索ミドルウェアを設定し、アダプターが使用します。

Startup.cs

});

services.AddSingleton<ConversationState>();

// Create the Bot Framework Authentication to be used with the Bot Adapter.

AdapterWithInspection.cs

{
    public class AdapterWithInspection : CloudAdapter
    {
        public AdapterWithInspection(BotFrameworkAuthentication auth, IConfiguration configuration, InspectionState inspectionState, UserState userState, ConversationState conversationState, ILogger<IBotFrameworkHttpAdapter> logger)
            : base(auth, logger)
        {
            // Inspection needs credentials because it will be sending the Activities and User and Conversation State to the emulator
            var credentials = new MicrosoftAppCredentials(configuration["MicrosoftAppId"], configuration["MicrosoftAppPassword"]);

            Use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

                // Send a trace activity, which will be displayed in the Bot Framework Emulator
                await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
            };
        }

EchoBot.cs ファイル内のボット クラスを更新します。

EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var conversationStateProp = _conversationState.CreateProperty<CustomState>("customState");
    var convProp = await conversationStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    var userStateProp = _userState.CreateProperty<CustomState>("customState");
    var userProp = await userStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text} conversation state: {convProp.Value} user state: {userProp.Value}"), cancellationToken);

    convProp.Value++;
    userProp.Value++;
}

JavaScript

ボットのコードを更新する前に、ターミナルで次のコマンドを実行して、パッケージを最新バージョンに更新する必要があります。

npm install --save botbuilder@latest

次に、JavaScript ボットのコードを次のように更新する必要があります。 詳細につ「ボットのコードを更新する」を参照するか、GitHub の「検査ミドルウェア」サンプルを参照してください。

index.js

検査状態を設定し、index.js ファイル内のアダプターに検査ミドルウェアを追加します。

// Import required bot services.
// See https://aka.ms/bot-services to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');

const { MicrosoftAppCredentials } = require('botframework-connector');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Create the Storage provider and the various types of BotState.
const memoryStorage = new MemoryStorage();
const inspectionState = new InspectionState(memoryStorage);
const userState = new UserState(memoryStorage);
const conversationState = new ConversationState(memoryStorage);

// Create and add the InspectionMiddleware to the adapter.
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword)));

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

bot.js

bot.js ファイル内のボット クラスを更新します。

this.onMessage(async (context, next) => {
    // get the state objects
    const testConversationState = await this.conversationStateAccessor.get(context, { count: 0 });
    const testUserState = await this.userStateAccessor.get(context, { count: 0 });

    // print the current state to the reply to show we are incrementing it
    await context.sendActivity(`You said '${ context.activity.text }' conversation-state: ${ testConversationState.count } user-state: ${ testUserState.count }`);

    // do the actual increment
    testConversationState.count++;
    testUserState.count++;

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

検査状態を設定し、Application.java ファイル内のアダプターに検査ミドルウェアを追加します。 検査状態は、BotDependencyConfiguration 基底クラスによって提供される既定の BotFrameworkHttpAdapter をオーバーライドするように @Primary に設定された BotFrameworkHttpAdapter を提供する新しい Spring @Bean を提供することによって設定されます。 以下のコード更新をご覧になるか、GitHubの「検査ミドルウェア」サンプルを参照してください。

Application.java

/**
 * Create an adapter with InspectionMiddleware.
 *
 * <p>
 * NOTE: This is marked as @Primary to override the default Bean.
 * </p>
 *
 * @param configuration     The configuration.
 *                          {@link BotDependencyConfiguration#getConfiguration()}
 * @param inspectionState   The InspectionState.
 *                          {@link BotDependencyConfiguration#getInspectionState(Storage)}
 * @param userState         The UserState.
 *                          {@link BotDependencyConfiguration#getUserState(Storage)}
 * @param conversationState The ConversationState.
 *                          {@link BotDependencyConfiguration#getConversationState(Storage)}
 * @return An AdapterWithInspection object.
 */
@Bean
@Primary
public BotFrameworkHttpAdapter getInspectionBotFrameworkHttpAdapter(
    Configuration configuration,
    InspectionState inspectionState,
    UserState userState,
    ConversationState conversationState
) {
    return new AdapterWithInspection(
        configuration,
        inspectionState,
        userState,
        conversationState
    );
}

AdapterWithInspection は com.microsoft.bot.integration パッケージの一部として実装されており、Java SDK のソース コードから確認できます。

EchoBot.java ファイル内のボット クラスを更新します。

EchoBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<CustomState> dataAccessor =
        conversationState.createProperty("customState");
    CompletableFuture<CustomState> convStateFuture =
        dataAccessor.get(turnContext, CustomState::new);

    // Get profile from UserState.
    StatePropertyAccessor<CustomState> profileAccessor =
        userState.createProperty("customState");
    CompletableFuture<CustomState> userStateFuture =
        profileAccessor.get(turnContext, CustomState::new);

    return convStateFuture.thenCombine(userStateFuture, (convProp, userProp) -> {
        convProp.setValue(convProp.getValue() + 1);
        userProp.setValue(userProp.getValue() + 1);

        return turnContext.sendActivity(
            MessageFactory.text(
                String.format(
                    "Echo: %s conversation state %d user state %d",
                    turnContext.getActivity().getText(), convProp.getValue(),
                    userProp.getValue()
                )
            )
        );
    }).thenApply(resourceResponse -> null);
}

Python

ボットのコードを更新する前に、ターミナルで次のコマンドを実行して、必要な PyPI パッケージをインストールします。

pip install aiohttp
pip install botbuilder-core>=4.7.0

アダプターにミドルウェアを追加して、app.py ファイルに検査状態を設定します。

app.py

from botbuilder.core import (
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication
from botbuilder.schema import Activity, ActivityTypes
from botframework.connector.auth import MicrosoftAppCredentials

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))

# Catch-all for errors.
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create InspectionMiddleware
INSPECTION_MIDDLEWARE = InspectionMiddleware(
    inspection_state=InspectionState(MEMORY),
    user_state=USER_STATE,
    conversation_state=CONVERSATION_STATE,
    credentials=MicrosoftAppCredentials(
        app_id=CONFIG.APP_ID, password=CONFIG.APP_PASSWORD
    ),
)
ADAPTER.use(INSPECTION_MIDDLEWARE)

# Create Bot
BOT = EchoBot(CONVERSATION_STATE, USER_STATE)

echo_bot.py ファイル内のボット クラスを更新します。

bots/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_data = await self.user_state_accessor.get(turn_context, CustomState)
    conversation_data = await self.conversation_state_accessor.get(
        turn_context, CustomState
    )

    await turn_context.send_activity(
        MessageFactory.text(
            f"Echo: {turn_context.activity.text}, "
            f"conversation state: {conversation_data.value}, "
            f"user state: {user_data.value}"
        )
    )

    user_data.value = user_data.value + 1
    conversation_data.value = conversation_data.value + 1

ボットをローカルでテストする

コードを更新した後、ボットをローカルで実行し、2 つのエミュレーター (1 つはメッセージを送受信するためのもので、もう 1 つはデバッグ モードでメッセージの状態を検査するためのもの) を使用してデバッグ機能をテストできます。 ボットをローカルでテストする:

1. ターミナルでボットのディレクトリに移動し、次のコマンドを実行してボットをローカルで実行します。

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

   mvn package
   java -jar .\target\bot-inspection-sample.jar 
   

   Python

   python app.py
   

2. エミュレーターを開きます。 [ボットを開く] を選択します。 [ボット URL]に [http://localhost:3978/api/messages] を入力し、MicrosoftAppId と MicrosoftAppPassword の値を入力します。 JavaScript ボットの場合、これらの値はボットの .env ファイルにあります。 C# ボットの場合、これらの値は appsettings.json ファイルにあります。 Java ボットの場合は、application.properties ファイルでこれらの値を見つけることができます。 [接続] を選択します。

3. 次に、別のエミュレーター ウィンドウを開きます。 この 2 つ目のエミュレーター ウィンドウは、デバッガーとして機能します。 前の手順で説明した指示に従います。 [デバッグ モードで開く] をオンにし、[接続] をクリックします。

4. この時点で、デバッグ エミュレーターに一意識別子 (/INSPECT attach <identifier>) を持つコマンドが表示されます。 デバッグ エミュレーターから識別子と共にコマンド全体をコピーし、最初のエミュレーターのチャット ボックスに貼り付けます。

   Note

   一意識別子は、ボットのコードに検査ミドルウェアを追加した後、デバッグ モードでエミュレーターを起動するたびに生成されます。

5. これで、最初のエミュレーターのチャット ボックスでメッセージを送信し、デバッグ エミュレーターでメッセージを検査できるようになりました。 メッセージの状態を確認するには、デバッグ エミュレーターで [ボットの状態] を選択し、右側の [JSON] ウィンドウで [値] を展開します。 デバッグ エミュレーターにボットの状態が表示されます。

   

Azure に構成されたボットの状態を検査する

Azure に構成され、チャネル (Teams など) に接続されているボットの状態を調べるには、ngrok をインストールして実行する必要があります。

ngrok を実行する

この時点で、エミュレーターが最新バージョンに更新され、ボットのコードに検査ミドルウェアが追加されました。 次の手順では、ngrok を実行し、ローカル ボットを構成します。 ngrok を実行する前に、ボットをローカルで実行する必要があります。

ボットをローカルで実行するには以下を行います。

1. ターミナルでボットのフォルダーに移動し、[最新のビルド] を使用するように npm 登録を設定します。

2. ボットをローカルで実行します。 ボットで 3978 のようなポート番号が公開されるのを確認できます。

3. 別のコマンド プロンプトを開き、ボットのプロジェクト フォルダーに移動します。 次のコマンドを実行します。

   ngrok http 3978
   

4. これで、ローカルに実行されているボットに ngrok が接続されました。 安全な (HTTPS) パブリック IP アドレスをコピーします。

   

ボット リソースの更新

ローカル ボットが ngrok に接続されたので、ngrok URL を使用するように Azure でボット リソースを構成できます。

1. Azure でボット リソースに移動します。 左側のメニューの [設定] で [構成] を選択します。

   1. メッセージング エンドポイントを、コピーした ngrok IP アドレスに設定します。 必要な場合、IP アドレスの後に /api/messages を追加します。 たとえば、https://e58549b6.ngrok.io/api/messages のようにします。

   2. [ストリーミング エンドポイントを有効にする] を選択 します。

      

   3. 適用を選択して、変更を保存します。

      ヒント

      [Apply] が有効になっていない場合は、[ストリーミング エンドポイントを有効にする] をオフにして [Apply] を選択してから、再び [ストリーミング エンドポイントを有効にする] をオンにして、再度 [Apply] を選択します。 [Enable Streaming Endpoint]\(ストリーミング エンドポイントを有効にする\) がオンになっており、エンドポイントの構成が保存されていることを確認する必要があります。

2. ボットの リソース グループにアクセスします。

   1. [デプロイ] を選択し、以前に正常にデプロイされたボット リソースを選択します。 左側のメニューから [テンプレート] を選択して、ボットに関連付けられている Web アプリの MicrosoftAppId と MicrosoftAppPassword を取得します。

      

   2. ボットの構成ファイル (C# の場合は appsettings.json 、JavaScript の場合は .env) を MicrosoftAppId と MicrosoftAppPassword で更新します。

3. エミュレーターを開始し、[ボットを開く] を選択し、[ボット URL] に [http://localhost:3978/api/messages] を入力します。 Microsoft アプリ ID と Microsoft App パスワードには、こちらがボットの構成ファイルに追加したのと同じ MicrosoftAppId と MicrosoftAppPassword を入力します。 次に、 [接続](Connect) を選択します。

4. これで、実行中のボットが Azure のボットリソースに接続されました。 Web チャットで Azure でボットをテストするには、ボット リソースに移動し、[Web チャットでテスト] を選択し、ボットにメッセージを送信します。

デバッグ モードを有効にします

1. エミュレーターで、[Debug] (デバッグ) を選択し、次に [Start Debugging] (デバッグを開始) を選択します。

2. [ボット URL] に ngrok の IP アドレスを入力します。/api/messages を忘れずに追加してください (たとえば、https://e58549b6.ngrok.io/api/messages）。

   1. Microsoft アプリ ID には、ボットのアプリ ID を入力します。
   2. Microsoft Appsのパスワードには、ボットのアプリ シークレットを入力します。
   3. また、[Open in debug mode]\(デバッグ モードで開く\) がオンになっていることも確認します。
   4. [接続] を選択します。

3. デバッグ モードを有効にすると、エミュレーターによって UUID が生成されます。 UUID は、エミュレーターでデバッグ モードを開始するたびに生成される一意の ID です。

4. UUID をコピーして [Web チャットでのテスト] チャット ボックス、またはお使いのチャネルのチャット ボックスに貼り付けます。 チャット ボックスに、「セッションに接続しました。すべてのトラフィックは検査のためにレプリケートされています」というメッセージが表示されます。

構成済みチャネルのチャット ボックスでメッセージを送信することにより、ボットのデバッグを開始できます。 ローカル エミュレーターは、デバッグのためのすべての詳細情報でメッセージを自動的に更新します。 ボットのメッセージの状態を検査するには、[ボットの状態]をクリックし、右側の JSON ウィンドウの値を展開します。

次のステップ

• 「トランスクリプト ファイルを使用してお使いのボットをデバッグする」方法を説明します。
• 「スキルまたはスキル コンシューマーをデバッグする」方法を説明します。