调试 Google Chat 应用

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

本页面介绍如何使用 ngrok 调试 HTTP Chat 应用。ngrok 是一个统一 Ingress 平台，可用于测试本地开发环境。在本指南中，您将在本地环境中测试代码更改，并排查远程环境中的问题。

注意 ：如果您的聊天应用是使用 Google Apps 脚本构建的，请改用以下方法：

• 测试部署
• 使用调试程序和断点

从本地开发环境进行调试

在本部分中，您将与在本地环境中执行的 Chat 应用交互。

图 1. 在本地开发环境中进行调试。

研讨会

Node.js

Python

Java

前提条件

Node.js

• 您的本地环境中安装了最新版本的 node 和 npm。

• 在本地环境中安装的最新版本 nodemon，用于自动重新加载：

  npm install -g nodemon
  

• 针对消息配置的 HTTP Chat 应用。您可以按照快速入门指南中的前提条件、设置环境和将应用发布到 Google Chat 进行操作。唯一的区别在于，您需要将应用名称设置为 Debug App，将应用网址设置为任何值，例如 http://example.com。

• 您的本地环境中已设置可以调试的 IDE。在本指南中，我们使用 Visual Studio Code IDE 及其默认调试功能进行说明。

• Git（已在本地环境中安装）。

• ngrok 帐号。

Python

• 您的本地环境中安装了最新版本的 python3。
• 在本地环境中安装的最新版本 pip 和 virtualenv，它们分别用于管理 Python 软件包和虚拟环境。
• 针对消息配置的 HTTP Chat 应用。您可以按照快速入门指南中的前提条件、设置环境和将应用发布到 Google Chat 进行操作。唯一的区别在于，您需要将应用名称设置为 Debug App，将应用网址设置为任何值，例如 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://example.com。
• 您的本地环境中已设置可以调试的 IDE。在本指南中，我们使用 Visual Studio Code IDE 及其默认调试功能进行说明。
• Git（已在本地环境中安装）。
• ngrok 帐号。
• 在本地环境中安装并初始化最新版 gcloud。

公开 localhost 服务

您需要将本地环境连接到互联网，以便 Chat 应用可以访问该环境。ngrok 应用用于将向公共网址发出的 HTTP 请求重定向到您的本地环境。

1. 在本地环境中的浏览器中，登录您的 ngrok 帐号。
2. 在本地环境中安装应用并设置 authtoken。
3. 在您的 ngrok 帐号中创建一个静态网域，本指南的说明中引用了 NGROK_STATIC_DOMAIN。

配置 Chat 应用

配置 Chat 应用以将其所有 HTTP 请求发送到您的静态网域。

1. 在 Google Cloud 控制台中，打开 Google Chat API 页面：

   前往 Google Chat API 页面

2. 点击配置标签页。

3. 依次前往互动功能 > 连接设置，然后将 App Url 文本字段的值设置为：

   https://NGROK_STATIC_DOMAIN
   

   将 NGROK_STATIC_DOMAIN 替换为 ngrok 帐号中的静态网域。

4. 点击保存。

图 2. Chat 应用会将其所有 HTTP 请求发送到静态网域。ngrok 公共服务充当 Chat 应用与本地执行的应用代码之间的桥梁。

测试 Chat 应用

您可以在本地部署、配置、测试、调试和自动重新加载 Chat 应用。

注意 ：Chat 应用使用 Python 和 Java 示例中的 Cloud Functions 框架执行，以及使用 Node.js 示例中的 Express 框架执行。

Node.js

1. 将 googleworkspace/google-chat-samples 代码库从 GitHub 克隆到本地环境，其中包含要执行的应用代码：

   git clone https://github.com/googleworkspace/google-chat-samples.git
   

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

   1. 在新窗口中打开文件夹 google-chat-samples/node/basic-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 应用也会在本地主机上启动网页界面，您可以通过在浏览器中打开该网页界面来监控所有活动。

   

   图 5. 由 ngrok 应用托管的网页界面，未显示 HTTP 请求。

5. 向 Chat 应用发送私信来测试该应用：

   • 打开 Google Chat。

     前往 Google Chat

   • 点击发起新聊天图标 。

   • 在对话框中，输入您的 Chat 应用的名称。

   • 在搜索结果中，找到您的 Chat 应用，然后点击 Add（添加）> Chat。

   • 在私信聊天室中输入 Hello，然后按 enter。您的 Chat 应用没有回复，因为正在调试中。

6. 在本地环境的 Visual Studio Code 中，您可以看到执行已在设置的断点处暂停。

   

   Figure 6. 执行会在设置的断点处暂停。

7. 如果您在 Google Chat 超时之前从 Visual Studio Code 的调试程序恢复执行任务，Chat 应用会回复 Your message : Hello。

8. 您可以在本地环境中查看由 ngrok 应用托管的网页界面中的 HTTP 请求和响应日志。

   

   图 7. 来自由 ngrok 应用托管的网页界面的 HTTP 请求。

9. 如需更改应用行为，请将 Your message 替换为 index.json 的 Here was your message 内嵌 35。在您保存文件后，nodemon 会自动使用更新后的源代码重新加载应用，并且 Visual Studio Code 会保持调试模式。

   

   图 8.该应用正在运行并监听已加载代码更改的端口 9000 上的 HTTP 请求。

10. 这一次，您可以选择在本地环境中 ngrok 应用托管的网页界面上记录的最后一个 HTTP 请求，然后点击 Replay，而不是在聊天室中发送第二条消息 Hello。与上次一样，您的 Chat 应用没有回复，因为正在调试。

11. 从 Visual Studio Code 的调试程序恢复执行时，您可以从本地环境中 ngrok 应用托管的网页界面中看到，该应用使用更新后的消息 Here was your message : Hello 生成响应。

Python

1. 获取用于应用默认凭据的新用户凭据：

   gcloud config set project PROJECT_ID
   gcloud auth application-default login
   

   将 PROJECT_ID 替换为应用的 Cloud 项目的项目 ID。

2. 将 googleworkspace/google-chat-samples 代码库从 GitHub 克隆到本地环境，其中包含应用代码：

   git clone https://github.com/googleworkspace/google-chat-samples.git
   

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

   1. 在新窗口中打开文件夹 google-chat-samples/python/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 上的调试模式下，从端口 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", "hello_chat",
                  "--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 应用也会在本地主机上启动网页界面，您可以通过在浏览器中打开该网页界面来监控所有活动。

   

   图 5. 由 ngrok 应用托管的网页界面，未显示 HTTP 请求。

6. 向 Chat 应用发送私信来测试该应用：

   • 打开 Google Chat。

     前往 Google Chat

   • 点击发起新聊天图标 。

   • 在对话框中，输入您的 Chat 应用的名称。

   • 在搜索结果中，找到您的 Chat 应用，然后点击 Add（添加）> Chat。

   • 在私信聊天室中输入 Hey!，然后按 enter。您的 Chat 应用没有回复，因为正在调试中。

7. 在本地环境的 Visual Studio Code 中，您可以看到执行已在设置的断点处暂停。

   

   Figure 6. 执行会在设置的断点处暂停。

8. 在 Google Chat 超时之前，如果您在 Visual Studio Code 的调试程序中继续执行，Chat 应用会在消息中回复您的名字和头像图片。

9. 您可以在本地环境中查看由 ngrok 应用托管的网页界面中的 HTTP 请求和响应日志。

   

   图 7. 来自由 ngrok 应用托管的网页界面的 HTTP 请求。

10. 如需更改应用行为，请将 Hello 替换为 main.py 文件的 Hey 内嵌 51。在您保存文件后，Visual Studio Code 会使用更新后的源代码自动重新加载应用并保持调试模式。

    

    图 8.该应用正在运行并监听已加载代码更改的端口 9000 上的 HTTP 请求。

11. 这一次，您可以选择在本地环境中 ngrok 应用托管的网页界面上记录的最后一个 HTTP 请求，然后点击 Replay，而不是在聊天室中发送第二条消息 Hey!。与上次一样，Chat 应用没有回复，因为正在调试。

12. 从 Visual Studio Code 的调试程序恢复执行时，您可以从本地环境中 ngrok 应用托管的网页界面中看到，该应用使用更新后的消息版本生成响应。

Java

1. 获取用于应用默认凭据的新用户凭据：

   gcloud config set project PROJECT_ID
   gcloud auth application-default login
   

   将 PROJECT_ID 替换为应用的 Cloud 项目的项目 ID。

2. 在本地环境中从 GitHub 克隆 googleworkspace/google-chat-samples 代码库，其中包含应用代码：

   git clone https://github.com/googleworkspace/google-chat-samples.git
   

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

   1. 在新窗口中打开文件夹 google-chat-samples/java/avatar-app。

   2. 通过在 pom.xml 文件中添加 Cloud Functions 框架构建插件 function-maven-plugin，将 Maven 项目配置为在本地运行 9000 端口上的应用 HelloChat：

      ...
      <plugin>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>function-maven-plugin</artifactId>
          <version>0.11.0</version>
          <configuration>
              <functionTarget>HelloChat</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. 在 HelloChat.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 应用也会在本地主机上启动网页界面，您可以通过在浏览器中打开该网页界面来监控所有活动。

   

   图 5. 由 ngrok 应用托管的网页界面，未显示 HTTP 请求。

6. 向 Chat 应用发送私信来测试该应用：

   • 打开 Google Chat。

     前往 Google Chat

   • 点击发起新聊天图标 。

   • 在对话框中，输入您的 Chat 应用的名称。

   • 在搜索结果中，找到您的 Chat 应用，然后点击 Add（添加）> Chat。

   • 在私信聊天室中输入 Hey!，然后按 enter。您的 Chat 应用没有回复，因为正在调试中。

7. 在本地环境的 Visual Studio Code 中，您可以看到执行已在设置的断点处暂停。

   

   Figure 6. 执行会在设置的断点处暂停。

8. 在 Google Chat 超时之前，如果您在 Visual Studio Code 的调试程序中继续执行，Chat 应用会在消息中回复您的名字和头像图片。

9. 您可以在本地环境中查看由 ngrok 应用托管的网页界面中的 HTTP 请求和响应日志。

   

   图 7. 来自由 ngrok 应用托管的网页界面的 HTTP 请求。

10. 如需更改应用行为，请将 Hello 替换为 HelloChat.java 文件的 Hey 内嵌 55，重启 mvnDebug 进程，然后重新启动 Remote Debug Watch 以重新附加并重启调试。

11. 这一次，您可以选择在本地环境中 ngrok 应用托管的网页界面上记录的最后一个 HTTP 请求，然后点击 Replay，而不是在聊天室中发送第二条消息 Hey!。与上次一样，您的 Chat 应用没有回复，因为正在调试。

12. 从 Visual Studio Code 的调试程序恢复执行时，您可以从本地环境中 ngrok 应用托管的网页界面中看到，该应用使用更新后的消息版本生成响应。

从远程环境调试

在本部分中，您将与在远程环境中执行的 Chat 应用交互。

图 9. 从远程环境调试。

前提条件

• 包含 Chat 应用的私信空间。您可以按照快速入门指南中的测试 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 中主动调试。

相关主题

• 了解如何enable和查询错误日志。
• 了解如何修正 Google Chat 应用错误，例如“应用无响应”“Google Chat API 仅供 Google Workspace 用户使用”或“可以将用户排除在聊天室之外”。
• 了解如何修正卡片错误，例如卡片消息、对话框或链接预览无法呈现或按预期运行。