エミュレーターを使用したテストとデバッグ
この記事の対象: SDK v4
Bot Framework Emulator は、ボット開発者がローカルでもリモートでも、ボットをテストし、デバッグできるデスクトップ アプリケーションです。 Emulator を使用すると、ボットとチャットしたり、ボットが送受信するメッセージを検査したりできます。 Emulator では、Web チャット UI に表示されるようにメッセージが表示され、ボットとメッセージを交換すると、JSON の要求と応答がログに記録されます。 ボットをクラウドにデプロイする前に、Emulator を使用してローカルで実行し、テストします。 まだ Azure AI Bot Service で作成していない場合や、チャンネルで実行するように構成していない場合でも、Emulator を使用してボットをテストできます。
Note
Bot Framework JavaScript、C# および Python SDK は引き続きサポートされますが、Java SDK は、2023 年 11 月に終了する最終的な長期サポートとともに廃止される予定です。 このリポジトリ内の重要なセキュリティとバグの修正のみが行われます。
Java SDK を使用して構築された既存のボットは引き続き機能します。
新しいボットの構築については、Power Virtual Agents の使用を検討し、適切なチャットボット ソリューションの選択についてお読みください。
詳細については、「The future of bot building」をご覧ください。
前提条件
- Bot Framework Emulator をインストールします。
ボットをローカルで実行する
ボットを Bot Framework Emulator に接続する前に、ボットをローカルで実行する必要があります。 ボットを実行するには、Visual Studio または Visual Studio Code を使用するか、コマンド ラインを使用できます。 コマンド ラインを使用してボットを実行するには、次の操作を行います。
コマンド プロンプトにアクセスし、ボットのプロジェクト ディレクトリに移動します。
次のコマンドを実行して、ボットを起動します。
dotnet run[アプリケーション開始。シャットダウンには CTRL+C を押してください] の前の行のポート番号をコピーします。
この時点では、ボットはローカルで実行されています。
localhost で実行されているボットに接続する
プロキシ設定の構成
企業プロキシの背後で開発する場合、エミュレーターは構成された環境変数 HTTP_PROXY および HTTPS_PROXY を使用し、HTTP 要求と HTTPs 要求のプロキシ URL ルートをそれぞれ指定します。
localhost で実行中のボットに接続している場合、エミュレーターは最初にプロキシ経由でルーティングしてから localhost への接続を試みます。 通常、プロキシは、バイパスする必要があることを指定しない限り、接続をブロックします localhost。
エミュレーターの localhost への接続を許可し、HTTP_PROXY および HTTPS_PROXY 設定をバイパスするには、ローカル コンピューターで次の環境変数を定義する必要があります。
NO_PROXY=localhost
認証用にエミュレーターを構成する
ボットが認証を必要とし、ログイン ダイアログを表示するには、エミュレーターを次に示すように構成する必要があります。
サインイン確認コードの使用
- エミュレーターを起動します。
- エミュレーターで、左側のウィンドウで [設定] (歯車アイコン) を選択します。
- [ローカル アドレスに対して ngrok をバイパスする] を有効にします。
- [OAuthCard のサインイン確認コードを使用する] を有効にします。
- [保存] を選択します。
ボットによって表示されるログイン ボタンを選択すると、確認コードが生成されます。 ボット入力チャット ボックスにコードを入力して、認証を実行します。 その後、許可されている操作を実行できます。
または、以下で説明されている手順を実行することもできます。
認証トークンを使用する
- エミュレーターを起動します。
- エミュレーターで、左側のウィンドウで [設定] (歯車アイコン) を選択します。
- ngrok へのローカル パスを入力します。 ngrok の詳細については、「ngrok」を参照してください。
- [エミュレーターの起動時に ngrok の実行] を有効にします。
- [バージョン 1.0 認証トークンの使用] を有効にします。
- [保存] を選択します。
ボットによって表示されるログイン ボタンを選択すると、資格情報を入力するように求められます。 認証トークンが生成されます。 その後、許可されている操作を実行できます。
ローカルで実行されているボットに接続するには、[ボットを開く] を選択します。 先ほどコピーしたポート番号を次の URL に追加し、その更新した URL を [Bot URL]\(ボットの URL\) バーに貼り付けます。
http://localhost:<port number>/api/messages
お使いのボットが Microsoft アカウント (MSA) の資格情報で実行されている場合は、その資格情報も入力します。
ボットの資格情報を使用
ボットを開いたときに、ボットが資格情報を使用して実行されている場合は、Microsoft アプリ ID および Microsoft アプリ パスワードを設定します。 Azure Bot Service でボットを作成した場合、資格情報はそのボットの App Service ([設定 -> 構成] セクションの下) で使用できます。 値がわからない場合は、ローカルで実行されているボットの構成ファイルからそれを削除してから、ボットをエミュレーターで実行できます。 ボットがこれらの設定で実行されていない場合は、その設定でエミュレーターを実行する必要もありません。
AD ID プロバイダー アプリケーションを作成する場合は次の点に注意してください。
- サポートされるアカウントの種類がシングル テナントに設定されている場合に、Microsoft アカウントではなく個人用サブスクリプションを使用すると、エミュレーターにエラー「ボットの Microsoft App ID または MMicrosoft Apps パスワードが間違っています。」と表示されます。
- この場合、サポートされているアカウントの種類を [任意の組織ディレクトリ内のアカウント] (任意の Microsoft Entra ID ディレクトリ - マルチテナント) と個人用の Microsoft アカウント (Xbox など) に設定する必要があります。
詳細については、「Microsoft Entra ID ID プロバイダー アプリケーションを作成する」および「Azure portal を使用して新しいアプリケーションを登録する」を参照してください。
インスペクターを利用してメッセージ アクティビティの詳細を表示する
ボットにメッセージを送信すると、ボットが応答を返すはずです。 会話ウィンドウ内でメッセージ吹き出しを選択し、ウィンドウの右側にある "インスペクター" 機能を使用して、未加工の JSON アクティビティを検査できます。 メッセージ吹き出しは選択すると黄色になり、アクティビティ JSON オブジェクトがチャット ウィンドウの左に表示されます。 この JSON 情報には、チャネル ID、アクティビティの種類、会話 ID、テキスト メッセージ、エンドポイント URL など、重要なメタデータが含まれます。 ユーザーから送信されたアクティビティだけでなくボットの応答アクティビティを検査できます。
ヒント
検査ミドルウェアをボットに追加することで、チャネルに接続されているボットの状態の変化をデバッグできます。
サービスの検査
Note
Azure AI QnA Maker は 2025 年 3 月 31 日に廃止されます。 2022 年 10 月 1 日以降、新しい QnA Maker リソースまたはナレッジ ベースを作成できなくなります。 Azure AI Language の一部として、質問応答機能の新しいバージョンが提供されました。
Azure AI Language の機能であるカスタム質問応答は、QnA Maker サービスの更新バージョンです。 Bot Framework SDK での質問と回答のサポートの詳細については、「自然言語の理解」を参照してください。
Note
Language Understanding (LUIS) は、2025 年 10 月 1 日に廃止されます。 2023 年 4 月 1 日以降は、新しい LUIS リソースを作成することはできません。 より新しいバージョンの言語理解が、現在、Azure AI Language の一部として提供されています。
Azure AI Language の機能である会話言語理解 (CLU) は、LUIS の更新バージョンです。 Bot Framework SDK での言語理解のサポートの詳細については、「自然言語の理解」を参照してください。
エミュレーターを用いると、LUIS と QnA Maker から JSON 応答を検査することもできます。 ボットと言語サービスが接続されているとき、右下の LOG ウィンドウにある [trace] を選択できます。 この新しいツールには、エミュレーターから直接、言語サービスを更新するための機能もあります。
LUIS サービスに接続しているとき、トレース リンクに Luis Trace が指定されます。 これが選択されると、意図、エンティティ、指定スコアなど、LUIS サービスからの raw 応答が表示されます。 ユーザーの発話の意図を再割り当てできます。
接続された QnA Maker サービスでは、ログに QnA トレースが表示されます。 これが選択されると、そのアクティビティに関連付けられている質問と回答の組みと信頼度スコアをプレビューできます。 ここから、ある回答に対する質問に別の言い回しを追加できます。
Azure へのサインイン
エミュレータを使って、ご自身の Azure アカウントにログインできます。 これは、ご自身のボットが依存するサービスを追加および管理するときに役に立ちます。 サインインするには:
[ファイル] を選択し、[Azure でサインイン] を選択します。
[ようこそ] 画面で、[Azure アカウントでサインイン] を選択します。 Emulator アプリケーションを再起動しても、その Emulator でのサインイン状態が継続されるようにするように設定することもできます。
データ収集の無効化
Emulator による使用状況データの収集を許可する必要がなくなった場合は、次の手順に従って、データ収集を簡単に無効にできます。
エミュレーターで、左側のウィンドウで [設定] (歯車アイコン) を選択します。
[データ コレクション] セクションの [使用状況データの収集を許可してエミュレーターを改善する] の選択を解除します。
[保存] を選択します。
気が変わった場合は、後でデータ収集を再び可能にすることができます。
その他のリソース
Bot Framework Emulator はオープン ソースです。 開発に貢献したり、バグや提案を送信したりできます。
トラブルシューティングについては、一般的な問題のトラブルシューティングに関する記事、およびそのセクションに示されているトラブルシューティングに関するその他の記事をご覧ください。
次のステップ
検査ミドルウェアを使用して、チャネルに接続されているボットをデバッグします。