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

適用対象: SDK v4

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

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

前提条件

• Bot Framework Emulator をダウンロードしてインストールする
• ボットのミドルウェアの知識
• ボットの管理状態の知識
• ngrok をダウンロードしてインストールする (追加のチャネルを使用するために、Azure に構成されているボットをデバッグする場合)

Emulatorを最新バージョンに更新する

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

Emulatorのバージョンを確認するには、メニューの [ヘルプ] を選択し、[バージョン情報] を選択します。 現在のバージョンのEmulatorが表示されます。

ボットのコードを更新する

C#

検査状態を設定し、Startup.cs ファイル内のアダプターに検査ミドルウェアを追加します。 検査状態は、依存関係の挿入によって提供されます。 以下のコード更新プログラムを参照するか、GitHubの検査ミドルウェア のサンプルを参照してください。

Startup.cs

// The Inspection Middleware needs some scratch state to keep track of the (logical) listening connections.
services.AddSingleton<InspectionState>();

// Create the Bot Adapter with error handling enabled.
services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithInspection>();

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,
    ConfigurationServiceClientCredentialFactory,
    ConversationState,
    createBotFrameworkAuthenticationFromConfiguration,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState
} = require('botbuilder');

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

const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
    MicrosoftAppId: process.env.MicrosoftAppId,
    MicrosoftAppPassword: process.env.MicrosoftAppPassword,
    MicrosoftAppType: process.env.MicrosoftAppType,
    MicrosoftAppTenantId: process.env.MicrosoftAppTenantId
});

const botFrameworkAuthentication = createBotFrameworkAuthenticationFromConfiguration(null, credentialsFactory);

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

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 をオーバーライドするように設定された BotFrameworkHttpAdapter を提供する@Primary新しい 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 (
    BotFrameworkAdapter,
    BotFrameworkAdapterSettings,
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
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.
SETTINGS = BotFrameworkAdapterSettings(CONFIG.APP_ID, CONFIG.APP_PASSWORD)
ADAPTER = BotFrameworkAdapter(SETTINGS)

# Create MemoryStorage and state
MEMORY = MemoryStorage()
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)

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. Emulatorを開きます。 [ ボットを開く] を選択します。 ボットの URL とhttp://localhost:3978/api/messagesMicrosoftAppId と MicrosoftAppPassword の値を入力します。 JavaScript ボットの場合、これらの値はボットの .env ファイルにあります。 C# ボットの場合、これらの値は appsettings.json ファイルにあります。 Java ボットの場合は、 application.properties ファイルでこれらの値を見つけることができます。 [接続] を選択します。

3. 次に、別のEmulator ウィンドウを開きます。 この 2 番目のEmulator ウィンドウはデバッガーとして機能します。 前の手順で説明した指示に従います。 [デバッグ モードで開く] をオンにし、[Connect] を選択します。

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

   注意

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

5. これで、最初のEmulatorのチャット ボックスにメッセージを送信し、デバッグ Emulatorのメッセージを調べることができます。 メッセージの状態を検査するには、デバッグ Emulatorで [Bot State] を選択し、適切な JSON ウィンドウで値を展開します。 デバッグ Emulatorにボットの状態が表示されます。

   

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

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

ngrok を実行する

この時点で、Emulatorを最新バージョンに更新し、ボットのコードに検査ミドルウェアを追加しました。 次の手順では、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. [適用] を選択して変更を保存します。

      ヒント

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

2. ボットのリソース グループに移動します。

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

      

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

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

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

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

1. Emulatorで[デバッグ]、[デバッグの開始] の順に選択します。

2. ボット URL の ngrok IP アドレス (/api/messages の追加を忘れないでください) を入力します (例: https://e58549b6.ngrok.io/api/messages)。

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

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

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

構成済みチャネルのチャット ボックスでメッセージを送信することにより、ボットのデバッグを開始できます。 ローカル Emulatorは、デバッグのすべての詳細を含むメッセージを自動的に更新します。 ボットのメッセージの状態を調べるには、[ ボットの状態 ] を選択し、適切な JSON ウィンドウで 値 を展開します。

その他のリソース

• C#、JavaScript、または Python で検査ミドルウェア ボットのサンプルを試してください。
• 一般的な問題のトラブルシューティングに関する記事、およびそのセクションにあるその他のトラブルシューティングに関する記事をお読みください。
• 「エミュレーターを使用したデバッグ」の記事をお読みください。