作为 Google Workspace 插件开发者,您可能需要调试代码以测试更改或排查复杂问题。您可以通过多种不同的方式调试 Google Workspace 插件,具体取决于应用的架构、应用的用途、应用的部署方式以及您的偏好设置。
本页面介绍如何使用 ngrok 调试 Google Workspace 插件。ngrok 是一个可用于测试本地开发环境的统一 Ingress 平台。在本指南中,您将在本地环境中测试代码更改,并排查远程环境中的问题。
从本地开发环境进行调试
在本部分中,您将与在本地环境中执行的 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
帐号。
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 请求重定向到您的本地环境。
- 在本地环境中的浏览器中,登录您的
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" } ] } } }
将
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
应用也会在本地主机上启动网页界面,您可以通过在浏览器中打开该网页界面来监控所有活动。图 5. 由
ngrok
应用托管的网页界面,未显示 HTTP 请求。使用测试人员帐号在新 Google 文档中预览支持请求网址,从而测试您的 Google Workspace 插件:
创建新的 Google 文档。
输入以下链接,然后按
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
点击该链接。
在本地环境的
Visual Studio Code
中,您可以看到执行已在设置的断点处暂停。Figure 6. 执行会在设置的断点处暂停。
如果您在 Google Workspace 插件超时之前从
Visual Studio Code
的调试程序继续执行,则 Google Workspace 插件会在缓存中显示 Google 文档中的链接预览。您可以在本地环境中查看由
ngrok
应用托管的网页界面中的 HTTP 请求和响应日志。图 7. 来自由
ngrok
应用托管的网页界面的 HTTP 请求。如需更改应用行为,请将
Case
替换为index.js
的Case:
内嵌51
。在您保存文件后,nodemon
会使用更新后的源代码自动重新加载应用,并且Visual Studio Code
会保持调试模式。图 8.该应用正在运行并监听已加载代码更改的端口
9000
上的 HTTP 请求。这一次,您可以选择在本地环境中
ngrok
应用托管的网页界面上记录的最后一个 HTTP 请求,然后点击Replay
,而不是点击链接并在新的 Google 文档中等待几秒钟。与上次一样,您的 Google Workspace 插件没有回复,因为目前正在积极调试。从
Visual Studio Code
的调试程序恢复执行时,您可以从本地环境中ngrok
应用托管的网页界面中看到该应用使用更新后的预览卡片生成响应。
Python
在本地环境中安装的
Visual Studio Code
IDE,执行以下操作:- 在新窗口中打开文件夹
add-ons-samples/python/3p-resources/create_link_preview
。 为 Python
env
创建一个新的虚拟环境并将其激活:virtualenv env
source env/bin/activate
在虚拟环境中使用
pip
安装所有项目依赖项:pip install -r requirements.txt
在根目录中创建文件
.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" ] }] }
在
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
应用也会在本地主机上启动网页界面,您可以通过在浏览器中打开该网页界面来监控所有活动。图 5. 由
ngrok
应用托管的网页界面,未显示 HTTP 请求。使用测试人员帐号在新 Google 文档中预览支持请求网址,从而测试您的 Google Workspace 插件:
创建新的 Google 文档。
输入以下链接,然后按
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
点击该链接。
在本地环境的
Visual Studio Code
中,您可以看到执行已在设置的断点处暂停。Figure 6. 执行会在设置的断点处暂停。
如果您在 Google Workspace 插件超时之前从
Visual Studio Code
的调试程序继续执行,则 Google Workspace 插件会在缓存中显示 Google 文档中的链接预览。您可以在本地环境中查看由
ngrok
应用托管的网页界面中的 HTTP 请求和响应日志。图 7. 来自由
ngrok
应用托管的网页界面的 HTTP 请求。如需更改应用行为,请将
Case
替换为main.py
文件的Case:
内嵌56
。在您保存文件后,Visual Studio Code
会使用更新后的源代码自动重新加载应用并保持调试模式。图 8.该应用正在运行并监听已加载代码更改的端口
9000
上的 HTTP 请求。这一次,您可以选择在本地环境中
ngrok
应用托管的网页界面上记录的最后一个 HTTP 请求,然后点击Replay
,而不是点击链接并在新的 Google 文档中等待几秒钟。与上次一样,您的 Google Workspace 插件没有回复,因为目前正在积极调试。从
Visual Studio Code
的调试程序恢复执行时,您可以从本地环境中ngrok
应用托管的网页界面中看到该应用使用更新后的预览卡片生成响应。
Java
在本地环境中安装的
Visual Studio Code
IDE,执行以下操作:- 在新窗口中打开文件夹
add-ons-samples/java/3p-resources
。 通过在
pom.xml
文件中添加 Cloud Functions 框架构建插件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> ...
现在,您可以在本地以调试模式启动它:
mvnDebug function:run Preparing to execute Maven in debug mode Listening for transport dt_socket at address: 8000
在根目录中创建文件
.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 }] }
在
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
应用也会在本地主机上启动网页界面,您可以通过在浏览器中打开该网页界面来监控所有活动。图 5. 由
ngrok
应用托管的网页界面,未显示 HTTP 请求。使用测试人员帐号在新 Google 文档中预览支持请求网址,从而测试您的 Google Workspace 插件:
创建新的 Google 文档。
输入以下链接,然后按
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
点击该链接。
在本地环境的
Visual Studio Code
中,您可以看到执行已在设置的断点处暂停。Figure 6. 执行会在设置的断点处暂停。
如果您在 Google Workspace 插件超时之前从
Visual Studio Code
的调试程序继续执行,则 Google Workspace 插件会在缓存中显示 Google 文档中的链接预览。您可以在本地环境中查看由
ngrok
应用托管的网页界面中的 HTTP 请求和响应日志。图 7. 来自由
ngrok
应用托管的网页界面的 HTTP 请求。如需更改应用行为,请将
Case
替换为CreateLinkPreview.java
文件的Case:
内嵌78
,重启mvnDebug
进程,然后重新启动Remote Debug Watch
以重新附加并重启调试。这一次,您可以选择在本地环境中
ngrok
应用托管的网页界面上记录的最后一个 HTTP 请求,然后点击Replay
,而不是点击链接并在新的 Google 文档中等待几秒钟。与上次一样,您的 Google Workspace 插件没有回复,因为目前正在积极调试。从
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,执行以下操作:
- 在新窗口中,打开应用的源代码。
在根目录中创建文件
.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 中主动调试该插件。
相关主题
了解如何查询错误日志。