使用文字記錄檔進行 Bot 偵錯Debug your bot using transcript files


成功進行 Bot 測試和偵錯的關鍵之一,就是能夠記錄並檢查在執行 Bot 時所發生的一些情況。One of the keys to successful testing and debugging a bot is your ability to record and examine the set of conditions that occur when running your bot. 本文討論 Bot 文字記錄檔的建立和使用方式,以提供一組詳細的使用者互動和 Bot 回應以供測試和偵錯。This article discusses the creation and use of a bot transcript file to provide a detailed set of user interactions and bot responses for testing and debugging.

Bot 文字記錄檔The bot transcript file

Bot 文字記錄檔是特製化的 JSON 檔案,可保留使用者與 Bot 之間的互動。A bot transcript file is a specialized JSON file that preserves the interactions between a user and your bot. 文字記錄檔不僅保留訊息內容,也會保留互動詳細資料,例如使用者識別碼、通道識別碼、通道類型、通道功能、互動時間等。這些資訊接著可用來協助尋找及解決 Bot 測試或偵錯時的問題。A transcript file preserves not only the contents of a message, but also interaction details such as the user id, channel id, channel type, channel capabilities, time of the interaction, etc. All of this information can then be used to help find and resolve issues when testing or debugging your bot.

建立/儲存 Bot 文字記錄檔Creating/Storing a bot transcript file

本文說明如何使用 Microsoft 的 Bot Framework 模擬器建立 Bot 文字記錄檔。This article shows how to create bot transcript files using Microsoft's Bot Framework Emulator. 文字記錄檔也可以透過程式設計方式建立;請參閱 Blob 文字記錄儲存體 ,以閱讀更多關於該方法的資訊。Transcript files may also be created programmatically; see Blob transcript storage to read more concerning that approach. 在這篇文章中,我們將使用多回合提示 Bot 的 Bot Framework 範例程式碼,該程式碼會要求使用者的運輸方式、名稱和年齡,但任何可使用 Microsoft 的 Bot Framework Emulator 存取的程式碼都可用來建立文字記錄檔。In this article we will use the Bot Framework sample code for Multi Turn Prompt Bot that requests a user's mode of transportation, name and age, but any code that can be accessed using Microsoft's Bot Framework Emulator may be used to create a transcript file.

若要開始此程序,請確保您想要測試的 Bot 程式碼是在您的開發環境內執行。To begin this process ensure that the bot code you want to test is running within your development environment. 啟動 bot framework 模擬器,選取 [ 開啟 bot ] 按鈕,然後輸入您的瀏覽器中顯示的 localhost: port 位址,後面接著 "/api/messages",如下圖所示。Start the bot framework Emulator, select the Open Bot button, then enter the address of localhost:port shown in your browser followed by "/api/messages" as shown in the image below. 現在,按一下 [連線 ] 按鈕,將模擬器連線至您的 bot。Now click the Connect button to connect the Emulator to your bot.


將模擬器連接到您的執行中程式碼之後,請將模擬的使用者互動傳送至 bot 以測試您的程式碼。After connecting the Emulator to your running code, test your code by sending simulated user interactions to the bot. 此範例中,我們已傳入使用者的運輸方式、名稱和年齡。For this example we have passed in the user's mode of transportation, name and age. 輸入您想要保留的所有使用者互動之後,請使用 bot framework 模擬器來建立並儲存包含此交談的文字記錄檔案。After you have entered all of the user interactions you want to preserve, use the bot framework Emulator to create and save a transcript file containing this conversation.

在 [即時聊天] 索引標籤 (如下所示) 中,選取 [儲存文字記錄] 按鈕。Within the Live Chat tab (shown below), select the Save transcript button.


選擇文字記錄檔的位置和名稱,然後選取 [儲存] 按鈕。Choose a location and name for your transcript file and then select the save button.

文字記錄另存為 ursula

您輸入要使用模擬器測試程式碼的所有使用者互動和 bot 回應現在已儲存至文字記錄檔案,您稍後可以重載該檔案,以協助您在使用者與 bot 之間進行互動。All of the user interactions and bot responses that you entered to test your code with the Emulator have now been saved into a transcript file that you can later reload to help debug interactions between your user and your bot.

擷取 Bot 文字記錄檔Retrieving a bot transcript file

若要使用 Bot Framework Emulator 取出 bot 文字記錄檔,請選取模擬器左上 角的檔案,然後 開啟 [文字 記錄 ... ],如下所示。To retrieve a bot transcript file using the Bot Framework Emulator, select the File then Open Transcript... in the upper left corner of the Emulator, as shown below. 接下來,選取您想要擷取的文字記錄檔。Next, select the transcript file that you want to retrieve. 您也可以從模擬器的 資源 區段中 的文字記錄清單控制項 存取 (文字記錄) (Transcripts may also be accessed from within the TRANSCRIPTS list control in the RESOURCES section of the Emulator)

在此範例中,我們會擷取名為 "ursula_user.transcript" 的文字記錄檔。In this example we are retrieving the transcript file named "ursula_user.transcript". 選取文字記錄檔會自動將整個保留的對話載入至標題為 [文字 記錄] 的新索引標籤。Selecting a transcript file will automatically load the entire preserved conversation into a new Tab titled Transcript.


使用文字記錄檔進行偵錯Debug using transcript file

載入文字記錄檔後,您現在即可對在使用者與 Bot 之間擷取的互動進行偵錯。With your transcript file loaded, you are now ready to debug interactions that you captured between a user and your bot. 若要這樣做,只要按一下 [記錄檔] 區段中 所記錄的任何事件或活動,就會顯示在模擬器的右下方區域中。To do this, simply click on any event or activity recorded in the LOG section shown in the lower right area of the Emulator. 在以下所示的範例中,我們選取了使用者傳送 "Hello" 訊息時的第一次反覆運算。In the example shown below, we selected the user's first interaction when they sent the message "Hello". 當我們這麼做時,會以 JSON 格式在模擬器的偵測 視窗中顯示有關此特定互動的文字記錄檔中的所有資訊。When we do this, all of the information in your transcript file concerning this specific interaction is displayed in the Emulator's INSPECTOR window in JSON format. 由下而上查看其中一些值,我們會看到:Looking at some of these values from the bottom upward, we see the:

  • 反覆運算類型為 message 。Interaction type was message.
  • 訊息的傳送時間。Time the message was sent.
  • 已傳送內含 "Yes" 的純文字。Plain text sent contained "Yes".
  • 訊息已傳送給 Bot。Message was sent to our bot.
  • 使用者識別碼和資訊。User id and information.
  • 通道識別碼、功能和資訊。Channel id, capabilities and information.


這麼詳細的資訊可讓您追蹤使用者輸入與 Bot 回應之間的逐步互動,而在 Bot 並未以您預期的方式回應或完全不回應使用者的情況下,這就很適合用於偵錯。This detailed level of information allows you to follow the step-by-step interactions between the user's input and your bot's response, which is useful for debugging situations where your bot either did not respond back in the manner that you anticipated or did not respond back to the user at all. 擁有這些值以及導致互動失敗的步驟記錄,可讓您逐步執行程式碼、尋找 Bot 未如預期般回應的位置,以及解決這些問題。Having both these values and a record of the steps leading up to the failed interaction allows you to step through your code, find the location where your bot does not respond as anticipated, and resolve those issues.

使用文字記錄檔搭配 Bot Framework 模擬器,只是可用來協助您進行 Bot 程式碼與使用者互動測試和偵錯的許多工具之一。Using transcript files together with the Bot Framework Emulator is just one of the many tools you can use to help you test and debug your bot's code and user interactions. 若要尋找更多 Bot 測試和偵錯的方法,請參閱下面所列的其他資源。To find more ways to test and debug your bot, see the additional resources listed below.

其他資訊Additional information

如需其他測試和偵錯資訊,請參閱:For additional testing and debugging information see: