對 HTTP Google Workspace 外掛程式進行測試及偵錯

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

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

從本機開發環境偵錯

在本節中，您將與在本地環境中執行的 Google Workspace 外掛程式互動。

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

必要條件

Node.js

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

• 在本機環境中nodemon 安裝最新版本。這項資訊會用於自動儲值：

  npm install -g nodemon

• Google Cloud 專案。您可以按照必要條件和設定環境部分的操作說明，完成快速入門指南。

• 要在本機環境中偵錯的 Google Workspace 外掛程式程式碼。在本指南中，我們使用 GitHub 存放區 googleworkspace/add-ons-samples 中的程式碼範例 3p-resources 預覽連結功能，以利說明。

• 本機環境中設定的 IDE，可進行偵錯。在本指南中，我們使用 Visual Studio Code IDE 和預設的偵錯功能，僅供說明之用。

• ngrok 帳戶。

• 在您的本機環境中安裝並初始化最新版 gcloud。

Python

• 本機環境中已安裝最新版 python3。
• 在本地環境中安裝最新版本的 pip 和 virtualenv。分別用於管理 Python 套件和虛擬環境。
• Google Cloud 專案。您可以按照必要條件和設定環境部分的操作說明，完成快速入門指南。
• 要在本機環境中偵錯的 Google Workspace 外掛程式程式碼。在本指南中，我們使用 GitHub 存放區 googleworkspace/add-ons-samples 中的程式碼範例 3p-resources 預覽連結功能，以利說明。
• 本機環境中設定的 IDE，可進行偵錯。在本指南中，我們使用 Visual Studio Code IDE 和預設的偵錯功能，僅供說明之用。
• ngrok 帳戶。
• 在您的本機環境中安裝並初始化最新版 gcloud。

Java

• 本機環境中Java SE 11's JDK 安裝的最新穩定版。
• 在本機環境中安裝最新版 Apache Maven。用於管理 Java 專案。
• Google Cloud 專案。您可以按照必要條件和設定環境部分的操作說明，完成快速入門指南。
• 要在本機環境中偵錯的 Google Workspace 外掛程式程式碼。在本指南中，我們使用 GitHub 存放區 googleworkspace/add-ons-samples 中的程式碼範例 3p-resources 預覽連結功能，以利說明。
• 本機環境中設定的 IDE，可進行偵錯。在本指南中，我們使用 Visual Studio Code IDE 和預設的偵錯功能，僅供說明之用。
• ngrok 帳戶。
• 在您的本機環境中安裝並初始化最新版 gcloud。

公開提供本機主機服務

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

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

建立及安裝外掛程式部署項目

1. 設定 Google Workspace 外掛程式，將所有 HTTP 要求傳送至靜態網域。部署檔案應如下所示：

   {
     "oauthScopes": [
       "https://www.googleapis.com/auth/workspace.linkpreview",
       "https://www.googleapis.com/auth/workspace.linkcreate"
     ],
     "addOns": {
       "common": {
         "name": "Manage support cases",
         "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png",
         "layoutProperties": {
           "primaryColor": "#dd4b39"
         }
       },
       "docs": {
         "linkPreviewTriggers": [
           {
             "runFunction": "NGROK_STATIC_DOMAIN",
             "patterns": [
               {
                 "hostPattern": "example.com",
                 "pathPrefix": "support/cases"
               },
               {
                 "hostPattern": "*.example.com",
                 "pathPrefix": "cases"
               },
               {
                 "hostPattern": "cases.example.com"
               }
             ],
             "labelText": "Support case",
             "localizedLabelText": {
               "es": "Caso de soporte"
             },
             "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
           }
         ],
         "createActionTriggers": [
           {
             "id": "createCase",
             "labelText": "Create support case",
             "localizedLabelText": {
               "es": "Crear caso de soporte"
             },
             "runFunction": "$URL2",
             "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
           }
         ]
       },
       "httpOptions": {
         "granularOauthPermissionSupport": "OPT_IN"
       }
     }
   }
   

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

2. 設定要使用的 Google Cloud 專案：

   gcloud config set project PROJECT_ID

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

   gcloud auth application-default login

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

4. 建立部署作業：

   gcloud workspace-add-ons deployments create manageSupportCases \
       --deployment-file=DEPLOYMENT_FILE_PATH

   將 DEPLOYMENT_FILE_PATH 替換為部署檔案的路徑。

5. 安裝部署作業：

   gcloud workspace-add-ons deployments install manageSupportCases

   

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

測試 Google Workspace 外掛程式

您可以在本機部署、測試、偵錯及自動重新載入 Google Workspace 外掛程式。

注意： 在範例中，Google Workspace 外掛程式會使用 Cloud Run Functions Framework 執行。

Node.js

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

   1. 在新視窗中開啟資料夾 add-ons-samples/node/3p-resources。

   2. 在 package.json 檔案中新增一個依附元件和兩個指令碼，設定應用程式在本機執行並自動重新載入以進行偵錯：

      {
          ...
          "dependencies": {
            ...
            "@google-cloud/functions-framework": "^3.3.0"
          },
          "scripts": {
              ...
              "start": "npx functions-framework --target=createLinkPreview --port=9000",
              "debug-watch": "nodemon --watch ./ --exec npm start"
          }
          ...
      }
      

   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 要求。

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

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

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

   

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

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

   

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

4. 使用測試人員帳戶在新的 Google 文件中預覽案件網址，測試 Google Workspace 外掛程式：

   • 建立 Google 文件。

     建立 Google 文件

   • 輸入下列連結，然後按下 enter 鍵：

     https://example.com/support/case/?name=Name1&description=Description1&priority=P1
     

   • 並按一下連結。

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

   

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

6. 如果在 Google Workspace 外掛程式逾時前，從 Visual Studio Code 偵錯工具繼續執行作業，Google Workspace 外掛程式會從快取在 Google 文件中顯示連結預覽。

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

   

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

8. 如要變更應用程式行為，請在 index.js 的第 51 行將 Case 替換為 Case:。儲存檔案時，nodemon 會自動重新載入應用程式，並使用更新後的原始碼，Visual Studio Code 則會維持偵錯模式。

   

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

9. 這次，您不必點選連結並在新 Google 文件中等待幾秒，而是可以選取本機環境中由 ngrok 應用程式代管的網頁介面上記錄的最後一個 HTTP 要求，然後點選 Replay。與上次相同，由於 Google Workspace 外掛程式正在偵錯，因此不會回覆。

10. 從 Visual Studio Code 偵錯工具繼續執行時，您可以在本機環境中由 ngrok 應用程式代管的網頁介面中看到，應用程式會使用更新後的預覽資訊卡版本產生回應。

Python

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

   1. 在新視窗中開啟資料夾 add-ons-samples/python/3p-resources/create_link_preview。

   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", "create_link_preview",
                  "--port", "9000",
                  "--debug"
              ]
          }]
      }
      

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

      

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

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

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

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

   

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

3. 應用程式也會在 localhost 上啟動網頁介面。ngrok在瀏覽器中開啟活動記錄，即可監控所有活動。

   

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

4. 使用測試人員帳戶在新的 Google 文件中預覽案件網址，測試 Google Workspace 外掛程式：

   • 建立 Google 文件。

     建立 Google 文件

   • 輸入下列連結，然後按下 enter 鍵：

     https://example.com/support/case/?name=Name1&description=Description1&priority=P1
     

   • 並按一下連結。

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

   

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

6. 如果在 Google Workspace 外掛程式逾時前，從 Visual Studio Code 偵錯工具繼續執行作業，Google Workspace 外掛程式會從快取在 Google 文件中顯示連結預覽。

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

   

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

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

   

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

9. 這次，您不必點選連結並在新 Google 文件中等待幾秒，而是可以選取本機環境中由 ngrok 應用程式代管的網頁介面上記錄的最後一個 HTTP 要求，然後點選 Replay。與上次相同，由於 Google Workspace 外掛程式正在偵錯，因此不會回覆。

10. 從 Visual Studio Code 偵錯工具繼續執行時，您可以在本機環境中由 ngrok 應用程式代管的網頁介面中看到，應用程式會使用更新後的預覽資訊卡版本產生回應。

Java

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

   1. 在新視窗中開啟資料夾 add-ons-samples/java/3p-resources。

   2. 設定 Maven 專案，在本機上透過 9000 埠執行 CreateLinkPreview 應用程式，方法是在 pom.xml 檔案中新增 Cloud Functions Framework 建構外掛程式 function-maven-plugin：

      ...
      <plugin>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>function-maven-plugin</artifactId>
          <version>0.11.0</version>
          <configuration>
              <functionTarget>CreateLinkPreview</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. 在 CreateLinkPreview.java 檔案中新增中斷點，暫停 HTTP 要求處理程序，然後開始附加及偵錯，並使用先前新增的 Remote Debug Watch 設定。應用程式現已開始執行，並監聽通訊埠 9000 的 HTTP 要求。

      

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

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

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

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

   

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

3. 應用程式也會在 localhost 上啟動網頁介面。ngrok在瀏覽器中開啟活動記錄，即可監控所有活動。

   

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

4. 使用測試人員帳戶在新的 Google 文件中預覽案件網址，測試 Google Workspace 外掛程式：

   • 建立 Google 文件。

     建立 Google 文件

   • 輸入下列連結，然後按下 enter 鍵：

     https://example.com/support/case/?name=Name1&description=Description1&priority=P1
     

   • 並按一下連結。

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

   

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

6. 如果在 Google Workspace 外掛程式逾時前，從 Visual Studio Code 偵錯工具繼續執行作業，Google Workspace 外掛程式會從快取在 Google 文件中顯示連結預覽。

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

   

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

8. 如要變更應用程式行為，請在 CreateLinkPreview.java 檔案的第 78 行將 Case 替換為 Case:，重新啟動 mvnDebug 程序，然後重新啟動 Remote Debug Watch，重新附加並重新啟動偵錯。

9. 這次，您不必點選連結並在新 Google 文件中等待幾秒，而是可以選取本機環境中由 ngrok 應用程式代管的網頁介面上記錄的最後一個 HTTP 要求，然後點選 Replay。與上次相同，由於 Google Workspace 外掛程式正在偵錯，因此不會回覆。

10. 從 Visual Studio Code 偵錯工具繼續執行時，您可以在本機環境中由 ngrok 應用程式代管的網頁介面中看到，應用程式會使用更新後的預覽資訊卡版本產生回應。

從遠端環境偵錯

在本節中，您將與在遠端環境執行的 Google Workspace 外掛程式互動。

圖 9. 從遠端環境進行偵錯。

必要條件

• Google Workspace 外掛程式已部署及安裝。
• 您的應用程式正在遠端環境中執行，且偵錯工具已在指定通訊埠上啟用，並在本指南的指示中參照為 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 設定。

   與已安裝的 Google Workspace 外掛程式互動。Google Workspace 外掛程式正在 Visual Studio Code IDE 中偵錯，因此不會回覆。

相關主題

• 瞭解如何查詢錯誤記錄。