對 Google Chat 應用程式進行偵錯

身為 Google Chat 擴充應用程式開發人員，您可能需要對程式碼偵錯，以測試變更內容或排解各種複雜問題。Chat 應用程式的偵錯方法有許多種，端視應用程式的架構、用途、部署方式和您的偏好而定。

本頁面說明如何使用 ngrok 偵錯 HTTP Chat 應用程式。ngrok 是一個統一的進入平台，可用於測試本機開發環境。本指南的內容涵蓋在本機環境測試程式碼變更，以及在遠端環境排解問題。

注意： 如果您的 Chat 應用程式是使用 Google Apps Script 建構，請改用下列程式碼：

• 測試部署作業
• 使用偵錯工具和中斷點

從本機開發環境進行偵錯

在本節中，您將與在本機環境中執行的 Chat 應用程式互動。

圖 1. 在本機開發環境中進行偵錯。

研討會

Node.js

Python

Java

必要條件

Node.js

• 在您的本機環境中安裝最新版本的 node 和 npm。

• 在您的本機環境中安裝最新版本 nodemon，用於自動重新載入：

  npm install -g nodemon

• 已設定訊息傳送功能的 HTTP Chat 應用程式。您可以按照快速入門指南中的「必要條件」、「設定環境」和「將應用程式發布至 Google Chat」部分操作。唯一不同的是，您需要將「應用程式名稱」設為 Debug App，並將「HTTP 端點網址」設為任何內容，例如 http://example.com。

• 本機環境中設定的 IDE，可進行偵錯。本指南會使用 Visual Studio Code IDE 及其預設的偵錯功能，以利說明。

• Git 安裝 在本機環境中。

• ngrok 帳戶。

Python

• 在您的本機環境中安裝最新版本 python3。
• 本機環境中安裝的最新版本 pip 和 virtualenv，分別用於管理 Python 套件和虛擬環境。
• 已設定訊息傳送功能的 HTTP Chat 應用程式。您可以按照快速入門指南中的「必要條件」、「設定環境」和「將應用程式發布至 Google Chat」部分操作。唯一不同的是，您需要將「應用程式名稱」設為 Debug App，並將「HTTP 端點網址」設為任何內容，例如 http://example.com。
• 本機環境中設定的 IDE，可進行偵錯。本指南會使用 Visual Studio Code IDE 及其預設的偵錯功能，以利說明。
• Git 安裝 在本機環境中。
• ngrok 帳戶。
• 在您的本機環境中安裝並初始化最新版本 gcloud。

Java

• 在您的本機環境中安裝最新穩定版 Java SE 11's JDK。
• 本機環境中安裝的最新版本 Apache Maven，用於管理 Java 專案。
• 已設定訊息傳送功能的 HTTP Chat 應用程式。您可以按照快速入門指南中的「必要條件」、「設定環境」和「將應用程式發布至 Google Chat」部分操作。唯一不同的是，您需要將「應用程式名稱」設為 Debug App，並將「訊息」觸發條件「HTTP 端點網址」設為任何內容，例如 http://example.com。
• 本機環境中設定的 IDE，可進行偵錯。本指南會使用 Visual Studio Code IDE 及其預設的偵錯功能，以利說明。
• Git 安裝 在本機環境中。
• ngrok 帳戶。
• 在您的本機環境中安裝並初始化最新版本 gcloud。

公開提供本機主機服務

您必須將本機環境連上網際網路，Chat 應用程式才能存取。ngrok 應用程式會將對公開網址發出的 HTTP 要求，重新導向至本機環境。

1. 在本地環境的瀏覽器中，登入 ngrok 帳戶。
2. 在本機環境中安裝應用程式並設定 authtoken。
3. 在 ngrok 帳戶中建立靜態網域，本指南的操作說明會將其稱為 NGROK_STATIC_DOMAIN。

設定 Chat 應用程式

將 Chat 應用程式設定為將所有 HTTP 要求傳送至靜態網域。

1. 在 Google API 控制台中開啟 Google Chat API 頁面：

   前往 Google Chat API 頁面

2. 按一下 [設定] 標籤。

3. 依序前往「互動功能」 >「連線設定」 >「觸發條件」，然後將要測試的觸發條件 (例如「訊息」) 的 HTTP 端點網址設為：

   https://NGROK_STATIC_DOMAIN
   

   將 NGROK_STATIC_DOMAIN 替換為 ngrok 帳戶中的靜態網域。

4. 按一下 [儲存]。

圖 2. Chat 應用程式會將所有 HTTP 要求傳送至靜態網域。ngrok 公開服務可做為 Chat 應用程式與在本機執行的應用程式程式碼之間的橋樑。

測試 Chat 應用程式

您可以在本機部署、設定、測試、偵錯及自動重新載入 Chat 應用程式。

注意： 在 Python 和 Java 的範例中，Chat 應用程式會使用 Functions Framework 執行，在 Node.js 的範例中，則會使用 Express Framework 執行。

Node.js

1. 從 GitHub 將 googleworkspace/add-ons-samples 存放區複製到本機環境，其中包含要執行的應用程式程式碼：

   git clone https://github.com/googleworkspace/add-ons-samples.git

2. 在您本機環境中安裝的 Visual Studio Code IDE 中，執行下列操作：

   1. 在新視窗中開啟資料夾 add-ons-samples/node/chat/avatar-app。

   2. 在 package.json 檔案中新增兩個指令碼，設定應用程式以自動重新載入的方式進行偵錯：

      {
          ...
          "scripts": {
              ...
              "debug": "node --inspect index.js",
              "debug-watch": "nodemon --watch ./ --exec npm run debug"
          }
          ...
      }
      

   3. 從根目錄安裝應用程式：

      npm install

   4. 建立並設定名為 Debug Watch 的啟動程序，在根目錄中建立 .vscode/launch.json 檔案，藉此觸發 debug-watch 指令碼：

      {
          "version": "0.2.0",
          "configurations": [{
              "type": "node",
              "request": "launch",
              "name": "Debug Watch",
              "cwd": "${workspaceRoot}",
              "runtimeExecutable": "npm",
              "runtimeArgs": ["run-script", "debug-watch"]
          }]
      }
      

   5. 在 index.js 檔案中新增中斷點，暫停 HTTP 要求處理程序，然後使用先前新增的 Debug Watch 設定開始執行及偵錯。應用程式現已開始執行，並監聽通訊埠 9000 的 HTTP 要求。

      

      圖 3. 應用程式正在執行，並監聽通訊埠 9000 的 HTTP 要求。

3. 在本機環境中啟動 ngrok 應用程式：

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   將 NGROK_STATIC_DOMAIN 替換為 ngrok 帳戶中的靜態網域。所有要求現在都會重新導向至本機環境和應用程式使用的連接埠。

   

   圖 4. 終端機正在執行 ngrok 伺服器並重新導向。

4. ngrok 應用程式也會在 localhost 上啟動網頁介面，您可以在瀏覽器中開啟該介面，監控所有活動。

   

   圖 5. 由 ngrok 應用程式代管的網頁介面，顯示沒有 HTTP 要求。

5. 傳送即時訊息給 Chat 應用程式，測試應用程式：

   • 開啟 Google Chat。

     前往 Google Chat

   • 按一下「發起新即時通訊」圖示 。

   • 在對話方塊中輸入 Chat 應用程式名稱。

   • 在搜尋結果中找到 Chat 應用程式，然後依序點選「新增」>「Chat」。

   • 在即時訊息空間中輸入 Hello，然後按下 enter。您的 Chat 應用程式正在積極偵錯，因此不會回覆。

6. 在您本機環境的 Visual Studio Code 中，您會看到執行作業在設定的中斷點暫停。

   

   圖 6. 執行作業會在設定的中斷點暫停。

7. Visual Studio Code當您從偵錯工具恢復執行作業時，Google Chat 會在 Chat 應用程式回覆訊息前逾時。

8. 您可以透過本機環境中 ngrok 應用程式代管的網頁介面，查看 HTTP 要求和回應記錄。

   

   圖 7. 由 ngrok 應用程式代管的網頁介面發出的 HTTP 要求。

9. 如要變更應用程式行為，請更新 index.js 檔案中的回覆文字。儲存檔案時，nodemon 會自動重新載入應用程式，並使用更新後的原始碼，而 Visual Studio Code 則會維持偵錯模式。

   

   圖 8. 應用程式正在執行，並透過通訊埠 9000 監聽 HTTP 要求，且已載入程式碼變更。

10. 這次，您不必在聊天室中傳送第二則訊息 Hello，只要在本地環境中，選取 ngrok 應用程式代管的網頁介面上記錄的最後一個 HTTP 要求，然後按一下 Replay 即可。與上次相同，由於系統正在積極偵錯，因此 Chat 應用程式不會回覆。

11. 從 Visual Studio Code 的偵錯工具繼續執行時，您會發現本機環境中由 ngrok 應用程式代管的網頁介面，會顯示應用程式產生的回覆，其中包含更新版訊息。

Python

1. 取得新的使用者憑證，用於應用程式預設憑證：

   gcloud config set project PROJECT_ID
   gcloud auth application-default login

   將 PROJECT_ID 替換為應用程式的 雲端專案 專案 ID。

2. 從 GitHub 將 googleworkspace/add-ons-samples 存放區複製到本機環境，其中包含應用程式程式碼：

   git clone https://github.com/googleworkspace/add-ons-samples.git

3. 在您本機環境中安裝的 Visual Studio Code IDE 中，執行下列操作：

   1. 在新視窗中開啟資料夾 add-ons-samples/python/chat/avatar-app。

   2. 為 Python env 建立新的虛擬環境並啟用：

      virtualenv env
      source env/bin/activate

   3. 在虛擬環境中使用 pip 安裝所有專案依附元件：

      pip install -r requirements.txt

   4. 在根目錄中建立 .vscode/launch.json 檔案，並設定名為 Debug Watch 的啟動程序，在虛擬環境 env 中，從模組 functions-framework 觸發應用程式，在偵錯模式下於連接埠 9000 執行：

      {
          "version": "0.2.0",
          "configurations": [{
              "type": "python",
              "request": "launch",
              "name": "Debug Watch",
              "python": "${workspaceFolder}/env/bin/python3",
              "module": "functions_framework",
              "args": [
                  "--target", "avatar_app",
                  "--port", "9000",
                  "--debug"
              ]
          }]
      }
      

   5. 在 main.py 檔案中新增中斷點，暫停 HTTP 要求處理程序，然後使用先前新增的 Debug Watch 設定開始執行及偵錯。應用程式現已開始執行，並監聽通訊埠 9000 的 HTTP 要求。

      

      圖 3. 應用程式正在執行，並監聽通訊埠 9000 的 HTTP 要求。

4. 在本機環境中啟動 ngrok 應用程式：

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   將 NGROK_STATIC_DOMAIN 替換為 ngrok 帳戶中的靜態網域。所有要求現在都會重新導向至本機環境和應用程式使用的連接埠。

   

   圖 4. 終端機正在執行 ngrok 伺服器並重新導向。

5. ngrok 應用程式也會在 localhost 上啟動網頁介面，您可以在瀏覽器中開啟該介面，監控所有活動。

   

   圖 5. 由 ngrok 應用程式代管的網頁介面，顯示沒有 HTTP 要求。

6. 傳送即時訊息給 Chat 應用程式，測試應用程式：

   • 開啟 Google Chat。

     前往 Google Chat

   • 按一下「發起新即時通訊」圖示 。

   • 在對話方塊中輸入 Chat 應用程式名稱。

   • 在搜尋結果中找到 Chat 應用程式，然後依序點選「新增」>「Chat」。

   • 在即時訊息空間中輸入 Hey!，然後按下 enter。您的 Chat 應用程式正在積極偵錯，因此不會回覆。

7. 在您本機環境的 Visual Studio Code 中，您會看到執行作業在設定的中斷點暫停。

   

   圖 6. 執行作業會在設定的中斷點暫停。

8. 當您從偵錯工具繼續執行時，Visual Studio CodeGoogle Chat 會在 Chat 應用程式逾時前，在訊息中回覆您的名稱和虛擬人像圖片。

9. 您可以透過本機環境中 ngrok 應用程式代管的網頁介面，查看 HTTP 要求和回應記錄。

   

   圖 7. 由 ngrok 應用程式代管的網頁介面發出的 HTTP 要求。

10. 如要變更應用程式行為，請在 main.py 檔案中將 Hello 替換為 Hey。儲存檔案時，Visual Studio Code 會自動重新載入應用程式，並使用更新後的原始碼，同時維持偵錯模式。

    

    圖 8. 應用程式正在執行，並透過通訊埠 9000 監聽 HTTP 要求，且已載入程式碼變更。

11. 這次，您不必在聊天室中傳送第二則訊息 Hey!，只要在本地環境中，選取 ngrok 應用程式代管的網頁介面上記錄的最後一個 HTTP 要求，然後按一下 Replay 即可。與上次相同，由於系統正在積極偵錯，因此 Chat 應用程式不會回覆。

12. 從 Visual Studio Code 的偵錯工具繼續執行時，您會發現本機環境中由 ngrok 應用程式代管的網頁介面，會顯示應用程式產生的回覆，其中包含更新版訊息。

Java

1. 取得新的使用者憑證，用於應用程式預設憑證：

   gcloud config set project PROJECT_ID
   gcloud auth application-default login

   將 PROJECT_ID 替換為應用程式的 雲端專案 專案 ID。

2. 在您的本機環境中，從 GitHub 複製 googleworkspace/add-ons-samples 存放區，其中包含應用程式程式碼：

   git clone https://github.com/googleworkspace/add-ons-samples.git

3. 在您本機環境中安裝的 Visual Studio Code IDE 中，執行下列操作：

   1. 在新視窗中開啟資料夾 add-ons-samples/java/chat/avatar-app。

   2. 在 pom.xml 檔案中新增 Google Cloud Functions Framework 建構外掛程式 function-maven-plugin，設定 Maven 專案在本地的 9000 連接埠上執行應用程式 App：

      ...
      <plugin>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>function-maven-plugin</artifactId>
          <version>0.11.0</version>
          <configuration>
              <functionTarget>App</functionTarget>
              <port>9000</port>
          </configuration>
      </plugin>
      ...
      

   3. 現在您可以在本機以偵錯模式啟動應用程式：

      mvnDebug function:run
      Preparing to execute Maven in debug mode
      Listening for transport dt_socket at address: 8000

   4. 在根目錄中建立 .vscode/launch.json 檔案，並設定名為 Remote Debug Watch 的啟動程序，該程序會附加至先前以 8000 埠啟動的應用程式：

      {
          "version": "0.2.0",
          "configurations": [{
              "type": "java",
              "request": "attach",
              "name": "Remote Debug Watch",
              "projectName": "http-function",
              "hostName": "localhost",
              "port": 8000
          }]
      }
      

   5. 在 App.java 檔案中新增中斷點，暫停處理 HTTP 要求，然後開始附加及偵錯，使用先前新增的 Remote Debug Watch 設定。應用程式現已開始執行，並透過通訊埠 9000 監聽 HTTP 要求。

      

      圖 3. 應用程式正在執行，並監聽通訊埠 9000 的 HTTP 要求。

4. 在本機環境中啟動 ngrok 應用程式：

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   將 NGROK_STATIC_DOMAIN 替換為 ngrok 帳戶中的靜態網域。所有要求現在都會重新導向至本機環境和應用程式使用的連接埠。

   

   圖 4. 終端機正在執行 ngrok 伺服器並重新導向。

5. ngrok 應用程式也會在 localhost 上啟動網頁介面，您可以在瀏覽器中開啟該介面，監控所有活動。

   

   圖 5. 由 ngrok 應用程式代管的網頁介面，顯示沒有 HTTP 要求。

6. 傳送即時訊息給 Chat 應用程式，測試應用程式：

   • 開啟 Google Chat。

     前往 Google Chat

   • 按一下「發起新即時通訊」圖示 。

   • 在對話方塊中輸入 Chat 應用程式名稱。

   • 在搜尋結果中找到 Chat 應用程式，然後依序點選「新增」>「Chat」。

   • 在即時訊息空間中輸入 Hey!，然後按下 enter。您的 Chat 應用程式正在積極偵錯，因此不會回覆。

7. 在您本機環境的 Visual Studio Code 中，您會看到執行作業在設定的中斷點暫停。

   

   圖 6. 執行作業會在設定的中斷點暫停。

8. 當您從偵錯工具繼續執行時，Visual Studio CodeGoogle Chat 會在 Chat 應用程式逾時前，在訊息中回覆您的名稱和虛擬人像圖片。

9. 您可以透過本機環境中 ngrok 應用程式代管的網頁介面，查看 HTTP 要求和回應記錄。

   

   圖 7. 由 ngrok 應用程式代管的網頁介面發出的 HTTP 要求。

10. 如要變更應用程式行為，請將 Hello 替換為 Hey 內嵌 55 的 App.java 檔案，重新啟動 mvnDebug 程序，然後重新啟動 Remote Debug Watch，重新附加並重新啟動偵錯。

11. 這次，您不必在聊天室中傳送第二則訊息 Hey!，只要在本地環境中，選取 ngrok 應用程式代管的網頁介面上記錄的最後一個 HTTP 要求，然後按一下 Replay 即可。與上次相同，由於系統正在積極偵錯，因此 Chat 應用程式不會回覆。

12. 從 Visual Studio Code 的偵錯工具繼續執行時，您會發現本機環境中由 ngrok 應用程式代管的網頁介面，會顯示應用程式產生的回覆，其中包含更新版訊息。

從遠端環境偵錯

在本節中，您將與在遠端環境執行的 Chat 應用程式互動。

圖 9.從遠端環境偵錯。

必要條件

• 與 Chat 應用程式的即時訊息空間。您可以按照快速入門指南的「測試 Chat 應用程式」一節操作，搜尋並啟動 Chat 應用程式。
• 您的應用程式會在遠端環境中執行，並在指定連接埠上啟用偵錯工具，本指南的說明會將其稱為 REMOTE_DEBUG_PORT。
• 本機環境可以 ssh 遠端環境。
• 本機環境中設定的 IDE，可進行偵錯。在本指南中，我們會使用 Visual Studio Code IDE 及其預設的偵錯功能，以利說明。

連結本機和遠端環境

在要啟動偵錯用戶端連線的本機環境中，設定 SSH 通道：

ssh -L LOCAL_DEBUG_PORT:localhost:REMOTE_DEBUG_PORT REMOTE_USERNAME@REMOTE_ADDRESS

更改下列內容：

• LOCAL_DEBUG_PORT：本機環境中的偵錯通訊埠。
• REMOTE_USERNAME：遠端環境中的使用者名稱。
• REMOTE_ADDRESS：遠端環境的位址。
• REMOTE_DEBUG_PORT：遠端環境中的偵錯通訊埠。

本機環境中的偵錯通訊埠現已連結至遠端環境中的偵錯通訊埠。

開始偵錯

在本地環境中安裝 Visual Studio Code IDE，然後執行下列操作：

1. 在新視窗中開啟應用程式的原始碼。

2. 在根目錄中建立 .vscode/launch.json 檔案，並設定名為 Debug Remote 的啟動程序，該程序會附加至本機環境中的偵錯埠：

   Node.js

   {
       "version": "0.2.0",
       "configurations": [{
           "type": "node",
           "request": "attach",
           "name": "Debug Remote",
           "address": "127.0.0.1",
           "port": LOCAL_DEBUG_PORT
       }]
   }
   

   Python

   {
       "version": "0.2.0",
       "configurations": [{
           "type": "python",
           "request": "attach",
           "name": "Debug Remote",
           "connect": {
               "host": "127.0.0.1",
               "port": LOCAL_DEBUG_PORT
           }
       }]
   }
   

   Java

   {
       "version": "0.2.0",
       "configurations": [{
           "type": "java",
           "request": "attach",
           "name": "Debug Remote",
           "hostName": "127.0.0.1",
           "port": LOCAL_DEBUG_PORT
       }]
   }
   

   將 LOCAL_DEBUG_PORT 替換為本機環境中的偵錯埠。

3. 在應用程式的原始碼中新增中斷點，暫停 HTTP 要求處理作業，然後開始執行及偵錯，並使用先前新增的 Debug Remote 設定。

在與 Chat 應用程式互傳的即時訊息中，輸入要測試的內容，然後按下 enter。您的 Chat 應用程式不會回覆，因為系統正在 Visual Studio Code IDE 中偵錯。

相關主題

• 瞭解如何啟用及查詢錯誤記錄。
• 瞭解如何修正 Google Chat 應用程式錯誤，例如「應用程式沒有回應」、「Google Chat API 僅適用於 Google Workspace 使用者」或「使用者可從討論空間中排除」。
• 瞭解如何修正卡片錯誤，例如卡片訊息、對話方塊或連結預覽畫面未如預期顯示或運作。

非外掛程式的 Chat 應用程式：對 Google Chat 應用程式偵錯

下列說明文件適用於非 Google Workspace 外掛程式的 Chat 擴充應用程式。如要遷移非外掛程式的 Chat 擴充應用程式，請參閱「將 Chat 擴充應用程式轉換為 Google Workspace 外掛程式」。

如要從本機環境偵錯非外掛程式的 Chat 擴充應用程式，請按照下列步驟操作：

• 在「互動式功能」 >「連線設定」下方的 Chat API「設定」分頁中，選取「HTTP 端點 URL」，然後直接將「HTTP 端點 URL」欄位設為 https://<var>NGROK_STATIC_DOMAIN</var>。
• 使用 GitHub 存放區 (google-chat-samples/node/basic-app、google-chat-samples/python/avatar-app 或 google-chat-samples/java/avatar-app) 中，不屬於外掛程式的 Chat 應用程式範例程式碼。googleworkspace/google-chat-samples