调试 Google Chat 应用

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

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

注意 ：如果您的 Chat 应用是使用 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。

公开提供本地主机服务

您需要将本地环境连接到互联网，以便 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 应用还会在您的 localhost 上启动网页界面，您可以在浏览器中打开该界面来监控所有活动。

   

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

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

   • 打开 Google Chat。

     前往 Google Chat

   • 点击发起新对话 。

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

   • 在搜索结果中找到您的 Chat 应用，依次点击添加 > 聊天。

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

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

   

   图 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 应用还会在您的 localhost 上启动网页界面，您可以在浏览器中打开该界面来监控所有活动。

   

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

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

   • 打开 Google Chat。

     前往 Google Chat

   • 点击发起新对话 。

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

   • 在搜索结果中找到您的 Chat 应用，依次点击添加 > 聊天。

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

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

   

   图 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 Framework 构建插件 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 应用还会在您的 localhost 上启动网页界面，您可以在浏览器中打开该界面来监控所有活动。

   

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

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

   • 打开 Google Chat。

     前往 Google Chat

   • 点击发起新对话 。

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

   • 在搜索结果中找到您的 Chat 应用，依次点击添加 > 聊天。

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

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

   

   图 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 应用以启动一个聊天室。
• 在远程环境中运行的应用，且在给定端口上启用了调试程序，本指南的说明中将其引用为 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 用户使用”或“可以从聊天室中排除用户”。
• 了解如何修正卡片错误，例如卡片消息、对话框或链接预览未按预期呈现或运行。