デバッグのガイドライン

  • [アーティクル]

適用対象: SDK v4

ボットは複雑なアプリであり、多くの部分が連携しています。 そのため、他の複雑なアプリの場合と同様、興味深いバグが発生したり、期待どおりにボットが動作しなかったりすることがあります。

ボットのデバッグは、場合によっては難しい作業になります。 すべての開発者は、そのタスクを実行するための独自の好みの方法を持っています。 以下のガイドラインは、ほとんどのボットに適用される提案です。

ボットが動作することを確認した後、次の手順はチャネルに接続することです。 これを行うには、ボットをステージング サーバーにデプロイし、ボットが接続するための独自の直接行クライアントを作成できます。 詳細については、「ボットをDirect Lineに接続する」を参照してください。

独自のクライアントを作成すると、チャネルの内部動作を定義し、ボットが特定のアクティビティ交換にどのように応答するかをテストできます。 そのクライアントに接続されたら、テストを実行してボットの状態を設定し、お使いの機能を確認します。 お使いのボットで音声などの機能が使用されている場合は、これらのチャネルを使用して、その機能を確認する手段を提供できます。

注意

Azure にボットをデプロイする場合、Web チャット チャネルは既定でプロビジョニングされます。

ここでAzure portalを使用してBot Framework EmulatorとWeb チャットの両方を使用すると、さまざまなチャネルと対話しながらボットがどのように動作するかについての詳細な分析情報を得ることができます。

お使いのボットのデバッグは、他のマルチスレッド アプリと同様に動作し、ブレークポイントを設定する機能が用意されています。また、イミディエイト ウィンドウなどの機能を使用することもできます。

ボットはイベント ドリブン方式のプログラミング パラダイムに従っています。このパラダイムに詳しくない場合、これを合理的に説明するのは困難です。 お使いのボットがステートレスかつマルチ スレッドであり、非同期/待機の呼び出しを処理するという考え方は、予期しないバグにつながることあります。 こうしたボットのデバッグは他のマルチスレッド アプリと同様に動作しますが、ここでは役に立つ提案、ツール、およびリソースをいくつか紹介します。

エミュレーターを使用したボット アクティビティについて

お使いのボットでは、通常の "メッセージ" アクティビティだけでなく、さまざまな種類のアクティビティが処理されます。 これらのアクティビティを理解すると、ボットのコードを効率的に書いたり、ボットが送受信しているアクティビティが期待どおりのものかを確認したりするうえで役立ちます。 エミュレーターを使用すると、これらのアクティビティの内容、アクティビティの発生時期、およびアクティビティに含まれる情報が表示されます。 詳細については、エミュレーターを使用したデバッグに関するページをご覧ください。

ユーザーとの対話のトランスクリプトの保存と取得

Azure BLOB のトランスクリプト ストレージは、ユーザーとボットの間の対話が含まれるトランスクリプトを格納して保存できる、特殊化されたリソースを提供します。

さらに、ユーザー入力の対話が格納された後は、Azure の "ストレージ エクスプローラー" を使用して、BLOB のトランスクリプト ストア内に格納されたトランスクリプトに含まれるデータを手動で確認できます。 次の例では、"mynewtestblobstorage" の設定から "ストレージ エクスプローラー" を開きます。保存されたユーザー入力を開くには、次を選択します: Blob Container > ChannelId TranscriptId >> ConversationId

BLOB トランスクリプト ストアに格納されているトランスクリプト エントリの例。

これにより、JSON 形式で格納された会話のユーザー入力が開きます。 ユーザー入力は、キー "text:" と共に保持されます。ボット トランスクリプト ファイルの作成と使用の詳細については、「トランスクリプト ファイルを 使用してボットをデバッグする」を参照してください。

ミドルウェアのしくみ

特に実行の継続やショートサーキットに関して言えば、初めて使うミドルウェアは直感的とは言えないでしょう。 ミドルウェアは、ボット ロジックに実行が渡されるタイミングをディクテーションする next() デリゲートへの呼び出しを使用して、ターンの立ち上がりまたは立ち下がりで実行できます。

複数のミドルウェアを使用していて、それがパイプラインの方向である場合、デリゲートは別のミドルウェアに実行を渡す可能性があります。 詳細については、ボットのミドルウェア パイプラインに関する記事をご覧ください。この考え方を、さらに明確に理解するうえで役立ちます。

デリゲートが next() 呼び出されない場合は、 ショート サーキット ルーティングと呼ばれます。 ミドルウェアが現在のアクティビティを満たしている場合、そして実行を渡す必要ないと判断した場合に、これが発生します。

ミドルウェアのショートサーキットのタイミングと理由を理解することは、パイプラインで最初に来るミドルウェアを示すのに役立ちます。 さらに、SDK や他の開発者によって提供される組み込みのミドルウェアでは、何を期待するか理解することが重要です。 組み込みのミドルウェアを使用する前に、まず独自のミドルウェアを作成して少し実験してみると役立つ場合もあります。

検査ミドルウェアを使用してボットをデバッグする方法の詳細については、「検査ミドルウェアを使用して ボットをデバッグする」を参照してください。

状態の理解

特に複雑なタスクの場合、状態を追跡することが、お使いのボットにとっては重要です。 一般的に、ベスト プラクティスは、アクティビティをできるだけ迅速に処理し、状態が永続化されるようにその処理を完了させることです。 アクティビティはほぼ同時にボットに送信でき、非同期アーキテクチャのために混乱を招くバグが発生する可能性があります。

重要なのは、自分が意図したとおりに状態が永続化されているかどうかを確認することです。 永続化の状態が存在する場所によっては、Cosmos DB および Azure Table Storage 用のストレージ エミュレーターが、運用環境のストレージを使用する前にその状態を確認するうえで役立つ場合があります。

重要

Cosmos DB ストレージ クラスは非推奨となりました。 最初に CosmosDbStorage で作成されたコンテナーにはパーティション キーが設定されておらず、_/partitionKey の既定のパーティション キーが指定されていました。

Cosmos DB ストレージで作成されたコンテナーは、Cosmos DB パーティション分割ストレージで使用できます。 詳細については、Azure Cosmos DB でのパーティション分割に関するページを参照してください。

また、従来の Cosmos DB ストレージとは異なり、Cosmos DB パーティション分割ストレージでは、Cosmos DB アカウント内にデータベースが自動的に作成されません。 新しいデータベースを手動で作成する必要がありますが、CosmosDbPartitionedStorage によってコンテナーが作成されるため、コンテナーの手動作成はスキップしてください。

アクティビティ ハンドラーを使用する方法

アクティビティ ハンドラーにより、別の複雑さが生じることがあります。具体的には、各アクティビティが独立したスレッドで実行されます (お使いの言語によっては Web worker で実行されます)。 ハンドラーの動作によっては、現在の状態が想定どおりではない問題が発生する可能性があります。

組み込みの状態はターンの最後に書き込まれますが、そのターンによって生成されたアクティビティはすべて、ターン パイプラインとは無関係に実行されています。 多くの場合、この影響を受けることはありませんが、アクティビティ ハンドラーによって状態が変更された場合は、その変更を含めるために状態を書き込む必要があります。 この場合、ターン パイプラインは、アクティビティ上で処理が完了するのを待つことができます。これにより、完了前に、そのターンについて適切な状態が確実に記録されます。

send activity メソッドとそのハンドラーにより、独自の問題が発生します。 on send activities ハンドラー内から send activity を単に呼び出すと、スレッドの無限フォークが発生します。 この問題を回避する方法はいくつかあります。たとえば、メッセージを送信情報に追加します。また、コンソールやファイルなどの別の場所に書き出してボットのクラッシュを回避します。

運用ボットのデバッグ

ボットが運用環境にある場合は、 ngrok を使用して任意のチャネルからボットをデバッグできます。 ボットを複数のチャネルにシームレスに接続することは、Bot Framework で使用できる重要な機能です。 詳細については、「 ngrok を使用して任意のチャネルからボットをデバッグ する」および 「スキルまたはスキル コンシューマーをデバッグする」を参照してください。

次のステップ

ボットの単体テストを実行する方法

その他のリソース