對 Google Workspace 外掛程式進行偵錯

Google Workspace 外掛程式開發人員可能需要對程式碼偵錯，以便測試變更或排解複雜問題。Google Workspace 外掛程式偵錯作業可根據應用程式的架構、功能、應用程式的部署方式，以及偏好設定，以多種不同方式執行。

本頁面說明如何使用 ngrok 對 Google Workspace 外掛程式進行偵錯。ngrok 是一個整合式輸入平台，可用來測試本機開發環境。在本指南中，您將在本機環境中測試程式碼變更，並排解遠端環境中的問題。

注意： 如果您的 Google Workspace 外掛程式是以 Google Apps Script 建構而成，請改用下列程式碼：

• 測試部署項目
• 使用偵錯工具和中斷點

從本機開發環境偵錯

在本節中，您會與在本機環境中執行的 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。

公開 localhost 服務

您需要將本機環境連上網際網路，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"
           }
         ]
       }
     }
   }
   

   將 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 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. 在根目錄中建立 .vscode/launch.json 檔案，並建立名為 Debug Watch 的啟動作業，以觸發 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. 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. 如要變更應用程式行為，請將 Case 替換為 index.js 的 Case: 內嵌 51。當您儲存檔案時，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 的偵錯模式中，從通訊埠 9000 的 functions-framework 模組觸發應用程式：

      {
          "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. 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. 如要變更應用程式行為，請將 Case 替換為 main.py 檔案的 Case: 內嵌 56。儲存檔案時，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. 在 pom.xml 檔案中新增 Cloud Functions Framework 建構外掛程式 function-maven-plugin，將 Maven 專案設為在本機通訊埠 9000 上執行應用程式 CreateLinkPreview：

      ...
      <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. 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 檔案的 Case: 內嵌 78 取代 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 正積極偵錯。

相關主題

瞭解如何查詢錯誤記錄。