Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

测试和调试 HTTP Google Workspace 插件

作为 Google Workspace 插件开发者，您可能需要调试代码，以测试更改效果或排查复杂的问题。调试 Google Workspace 插件可以通过多种不同的方式完成，具体取决于您应用的架构、用途、部署方式以及您自己的偏好。

本页介绍了如何使用 ngrok 调试 HTTP Google Workspace 加载项。ngrok 是一个统一的入站平台，可用于测试本地开发环境。在本指南中，您将在本地环境中测试代码更改，并排查远程环境中的问题。

通过本地开发环境进行调试

在本部分中，您将与在本地环境中执行的 Google Workspace 插件互动。

前提条件

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 请求重定向到本地环境。

在本地环境的浏览器中，登录您的 ngrok 账号。
安装应用并在本地环境中设置 authtoken。
在您的 ngrok 账号中创建一个静态网域，在本指南的说明中，该网域称为 NGROK_STATIC_DOMAIN。

创建并安装插件部署

将 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 账号中的静态网域。

设置要使用的 Google Cloud 项目：
```
gcloud config set project PROJECT_ID
```
获取新的用户凭据，以用于应用默认凭据：
```
gcloud auth application-default login
```
将 PROJECT_ID 替换为应用的 Google Cloud 项目的项目 ID。

创建部署：

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

将 DEPLOYMENT_FILE_PATH 替换为部署文件的路径。

安装部署：
```
gcloud workspace-add-ons deployments install manageSupportCases
```
图 2. Google Workspace 加载项将其所有 HTTP 请求发送到静态网域。`ngrok` 公共服务充当 Google Workspace 插件与在本地执行的应用代码之间的桥梁。

测试 Google Workspace 插件

您可以在本地部署、测试、调试和自动重新加载 Google Workspace 加购项。

Node.js

在本地环境中安装的 Visual Studio Code IDE 中，执行以下操作：

在新窗口中，打开文件夹 add-ons-samples/node/3p-resources。

通过在 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"
    }
    ...
}

从根目录安装应用：
```
npm install
```

创建并配置名为 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"]
    }]
}

在 index.js 文件中添加一个会暂停 HTTP 请求处理的断点，然后使用之前添加的 Debug Watch 配置开始运行和调试。应用现已运行，并在端口 9000 上监听 HTTP 请求。

图 3. 应用正在运行，并在端口 9000 上监听 HTTP 请求。

在本地环境中启动 ngrok 应用：
```
ngrok http --domain=NGROK_STATIC_DOMAIN 9000
```
将 NGROK_STATIC_DOMAIN 替换为 ngrok 账号中的静态网域。所有请求现在都会重定向到本地环境和应用使用的端口。

图 4.运行 ngrok 服务器并进行重定向的终端。
ngrok 应用也会在本地主机上启动一个 Web 界面。您可以在浏览器中打开该文件，以监控所有活动。

图 5.由 ngrok 应用托管的 Web 界面，未显示任何 HTTP 请求。
通过在新的 Google 文档中使用测试账号预览支持请求网址，测试您的 Google Workspace 插件：
- 创建 Google 文档。
  
  创建 Google 文档
- 输入以下链接，然后按 enter：
```
https://example.com/support/case/?name=Name1&description=Description1&priority=P1
```
- 点击该链接。
在本地环境的 Visual Studio Code 中，您可以看到执行在设置的断点处暂停。

图 6.执行在设置的断点处暂停。
如果您在 Google Workspace 加载项超时之前从 Visual Studio Code 调试器恢复执行，Google Workspace 加载项会从缓存中显示 Google 文档中的链接预览。
您可以通过本地环境中由 ngrok 应用托管的 Web 界面查看 HTTP 请求和响应日志。

图 7.来自 ngrok 应用托管的 Web 界面
的 HTTP 请求。
如需更改应用行为，请将 index.js 的第 51 行中的 Case 替换为 Case:。保存文件后，nodemon 会自动重新加载应用，并使用更新后的源代码，而 Visual Studio Code 仍处于调试模式。

图 8.应用正在运行，并监听端口 9000 上的 HTTP 请求，且已加载代码变更。
这次，您无需点击链接并在新的 Google 文档中等待几秒钟，只需选择本地环境中由 ngrok 应用托管的 Web 界面上记录的最后一个 HTTP 请求，然后点击 Replay。与上次一样，您的 Google Workspace 加载项因正在进行主动调试而未回复。
当您从 Visual Studio Code 调试器恢复执行时，您会看到本地环境中的 ngrok 应用托管的 Web 界面显示，该应用会生成包含更新版预览卡片的响应。

Python

在本地环境中安装的 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 的启动，该启动在调试模式下从模块 functions-framework 触发端口 9000 上的应用，位于虚拟环境 env 中：
```
{
    "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 请求。
在本地环境中启动 ngrok 应用：
```
ngrok http --domain=NGROK_STATIC_DOMAIN 9000
```
将 NGROK_STATIC_DOMAIN 替换为 ngrok 账号中的静态网域。所有请求现在都会重定向到本地环境和应用使用的端口。

图 4.运行 ngrok 服务器并进行重定向的终端。
ngrok 应用也会在本地主机上启动一个 Web 界面。在浏览器中打开该页面，监控所有活动。

图 5.由 ngrok 应用托管的 Web 界面，未显示任何 HTTP 请求。
通过在新的 Google 文档中使用测试账号预览支持请求网址，测试您的 Google Workspace 插件：
- 创建 Google 文档。
  
  创建 Google 文档
- 输入以下链接，然后按 enter：
```
https://example.com/support/case/?name=Name1&description=Description1&priority=P1
```
- 点击该链接。
在本地环境的 Visual Studio Code 中，您可以看到执行在设置的断点处暂停。

图 6.执行在设置的断点处暂停。
如果您在 Google Workspace 加载项超时之前从 Visual Studio Code 调试器恢复执行，Google Workspace 加载项会从缓存中显示 Google 文档中的链接预览。
您可以通过本地环境中由 ngrok 应用托管的 Web 界面查看 HTTP 请求和响应日志。

图 7.来自 ngrok 应用托管的 Web 界面
的 HTTP 请求。
如需更改应用行为，请将 main.py 文件中第 56 行的 Case 替换为 Case:。保存文件时，Visual Studio Code 会自动重新加载应用，并使用更新后的源代码保持在调试模式下。

图 8.应用正在运行，并监听端口 9000 上的 HTTP 请求，且已加载代码变更。
这次，您无需点击链接并在新的 Google 文档中等待几秒钟，只需选择本地环境中由 ngrok 应用托管的 Web 界面上记录的最后一个 HTTP 请求，然后点击 Replay。与上次一样，您的 Google Workspace 加载项因正在进行主动调试而未回复。
当您从 Visual Studio Code 调试器恢复执行时，您会看到本地环境中的 ngrok 应用托管的 Web 界面显示，该应用会生成包含更新版预览卡片的响应。

Java

在本地环境中安装的 Visual Studio Code IDE 中，执行以下操作：
1. 在新窗口中，打开文件夹 add-ons-samples/java/3p-resources。
2. 通过将 Cloud Functions 框架 build 插件 function-maven-plugin 添加到 pom.xml 文件中，将 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 请求。
在本地环境中启动 ngrok 应用：
```
ngrok http --domain=NGROK_STATIC_DOMAIN 9000
```
将 NGROK_STATIC_DOMAIN 替换为 ngrok 账号中的静态网域。所有请求现在都会重定向到本地环境和应用使用的端口。

图 4.运行 ngrok 服务器并进行重定向的终端。
ngrok 应用也会在本地主机上启动一个 Web 界面。在浏览器中打开该页面，监控所有活动。

图 5.由 ngrok 应用托管的 Web 界面，未显示任何 HTTP 请求。
通过在新的 Google 文档中使用测试账号预览支持请求网址，测试您的 Google Workspace 插件：
- 创建 Google 文档。
  
  创建 Google 文档
- 输入以下链接，然后按 enter：
```
https://example.com/support/case/?name=Name1&description=Description1&priority=P1
```
- 点击该链接。
在本地环境的 Visual Studio Code 中，您可以看到执行在设置的断点处暂停。

图 6.执行在设置的断点处暂停。
如果您在 Google Workspace 加载项超时之前从 Visual Studio Code 调试器恢复执行，Google Workspace 加载项会从缓存中显示 Google 文档中的链接预览。
您可以通过本地环境中由 ngrok 应用托管的 Web 界面查看 HTTP 请求和响应日志。

图 7.来自 ngrok 应用托管的 Web 界面
的 HTTP 请求。
如需更改应用行为，请将 CreateLinkPreview.java 文件第 78 行中的 Case 替换为 Case:，重启 mvnDebug 进程，然后重新启动 Remote Debug Watch 以重新附加并重启调试。
这次，您无需点击链接并在新的 Google 文档中等待几秒钟，只需选择本地环境中由 ngrok 应用托管的 Web 界面上记录的最后一个 HTTP 请求，然后点击 Replay。与上次一样，您的 Google Workspace 加载项因正在进行主动调试而未回复。
当您从 Visual Studio Code 调试器恢复执行时，您会看到本地环境中的 ngrok 应用托管的 Web 界面显示，该应用会生成包含更新版预览卡片的响应。

从远程环境进行调试

在本部分中，您将与在远程环境中执行的 Google Workspace 插件互动。

前提条件

您的 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 中，执行以下操作：

在新窗口中，打开应用的源代码。

在根目录中创建文件 .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 替换为本地环境中的调试端口。

在应用的源代码中添加一个会暂停 HTTP 请求处理的断点，然后使用之前添加的 Debug Remote 配置开始运行和调试。

与已安装的 Google Workspace 加购项互动。您的 Google Workspace 加载项未回复，因为它正在 Visual Studio Code IDE 中进行主动调试。

测试和调试 HTTP Google Workspace 插件 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

通过本地开发环境进行调试

前提条件

Node.js

Python

Java

公开提供本地主机服务

创建并安装插件部署

测试 Google Workspace 插件

Node.js

Python

Java

从远程环境进行调试

前提条件

连接本地环境和远程环境

开始调试

Node.js

Python

Java

相关主题

测试和调试 HTTP Google Workspace 插件