欢迎使用 Google Home 开发者中心,您可以在这里学习有关如何开发智能家居 Action 的新平台。注意:你将继续在 Actions 控制台中构建操作。

调试智能家居

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

1. 准备工作

作为一名物联网 (IoT) 开发者,你可以构建智能家居 Action,让用户能够通过 Google Home 应用中的触控功能和 Google 助理的语音指令来控制设备。

a4657871181b5ad2.gif

了解智能家居 Action 的调试工具是打造与 Google 助理的生产质量集成的重要步骤。为方便监控和调试,我们提供了 Google Cloud Platform (GCP) 指标和日志记录以及测试套件(智能家居),可帮助您发现和解决 Action 的问题。

前提条件

构建内容

在此 Codelab 中,您将部署一个存在 2 个缺陷的智能家居 Action 并将其关联到 Google 助理,然后通过测试套件对 Action 的缺陷进行调试,以获取智能家居和 Google Cloud Platform (GCP) 指标和日志记录。

学习内容

  • 如何使用 GCP 指标和日志记录找出并解决生产环境中的问题
  • 如何使用智能家居测试套件识别功能和 API 问题

所需条件

2. 运行故障应用

获取源代码

点击以下链接,将此 Codelab 的示例下载到您的开发机器上:

...或者,您也可以通过命令行克隆 GitHub 代码库:

$ git clone https://github.com/googlecodelabs/smarthome-debug.git

项目简介

洗衣机应用包含以下子目录:

关联到 Firebase

在开发机器上打开终端。转到 washer-faulty 目录,然后使用 Connect smart home devices to Google Assistant Codelab(将智能家居设备关联到 Google 助理)中的 Actions 项目设置 Firebase CLI:

$ cd washer-faulty
$ firebase use <project-id>

部署到 Firebase

转到 functions 文件夹,然后使用 npm. 安装所有必要的依赖项

$ cd functions
$ npm install

注意:如果您看到以下消息,可以忽略并继续。出现此警告是由于一些较旧的依赖项所致,您可以点击此处查看更多详细信息。

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

现在您已经安装了依赖项并配置了项目,接下来可以部署错误的洗衣机应用了。

$ firebase deploy

您应该会看到以下控制台输出:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<project-id>.firebaseapp.com

更新 HomeGraph

在你的浏览器 (https://<project-id>.firebaseapp.com) 中打开 Hosting 网址 以查看 Web 应用。在网页界面上,点击 Refresh ae8d3b25777a5e30.png 按钮,通过 Request Sync 使用故障洗衣机应用的最新设备元数据更新 HomeGraph:

6f2b1344179977cf.png

打开 Google Home 应用,验证您是否能看到名为 Faulty Washer 的洗衣机设备。

e357de6a7faff925.png

3. 测试您的 Action

部署项目后,测试 Action 是否控制洗衣机。

测试洗衣机

通过手机尝试以下任意语音指令时,检查其值是否发生变化:

“Ok Google,启动洗衣机。”

“Ok Google,运行洗衣机。”

“Ok Google,暂停我的洗衣机。”

“Ok Google,恢复我的洗衣机。”

“Ok Google,让洗衣机停止运行。”

当您暂停 / 恢复洗衣机时,您会注意到 Google 助理通过语音提示出了点问题:

“抱歉,我无法访问项目显示名称。”

如需调试此问题,您首先需要详细了解错误以缩小范围并找到根本原因。

智能家居 Google Analytics(分析)信息中心

建议您检查一下 Smarthome Analytics 信息中心,该信息中心汇总了有关您的云执行方式的使用情况和健康状况指标的图表:

  • 用量指标反映了智能家居 Action 的使用趋势,包括每日活跃用户数和履单请求总数。
  • 健康状况指标可帮助您监控智能家居 Action 的异常情况,包括请求延迟时间、成功百分比和错误细分。

要缩小错误的原因,请按照以下步骤访问项目信息中心。

  1. Actions 控制台中,转到“Projects”页面。
  2. 选择你的智能家居项目。
  3. 选择 Analytics 标签页,然后点击 Go to Google Cloud Platform

b1735bbe11a7aff8.png

  1. 此操作会将您转到 Google Cloud 上的项目信息中心列表。选择 Google Home Analytics - 云集成信息中心。

5edd3751323176dd.png

  1. 向下滚动到 Cloud Fulfillment 错误 - 状态细分图表,查看突出显示的时间范围的错误代码。

c468743c20a11c15.png

PARTNER_RESPONSE_MISSING_DEVICE 错误代码提供根本原因提示。接下来,根据错误代码检索事件日志以了解详情。

访问事件日志

如需更详细地了解此错误,请通过 Cloud Logging 访问智能家居 Action 的事件日志。

打开 Google Cloud Platform 中的导航菜单,然后在操作下选择日志记录 > 日志浏览器,以访问项目的事件日志。或者,您也可以在搜索框中搜索日志浏览器

查询部分,输入查询 PARTNER_RESPONSE_MISSING_DEVICE,然后点击运行查询。与查询匹配的日志会显示在查询结果部分中。

747cca0f1249a5a.png

错误日志是包含错误详情的智能家居事件,指示:

  • 用户执行的操作是“恢复洗衣机”(actionType:STARTSTOP_UNPAUSE”图标),与最近失败的语音指令相对应。
  • 关联的调试消息为“JSON response does not include device.

根据调试消息,您应该检查洗衣机应用为何未在 EXECUTE 响应中包含正确的设备。

确定错误的根本原因

functions/index.js 中,找到返回每个命令的状态和新设备状态的 EXECUTE 处理程序(位于 onExecute 数组中)。能否将设备 ID 插入到 EXECUTE 响应中取决于 updateDevice 函数的解析:

index.js

app.onExecute(async (body) => {
 ...

 for (const command of intent.payload.commands) {
   for (const device of command.devices) {
     for (const execution of command.execution) {
       executePromises.push(
           updateDevice(execution, device.id)
               .then((data) => {
                 result.ids.push(device.id);
                 Object.assign(result.states, data);
               })
               .catch((e) =>
                 functions.logger.error('EXECUTE',
                     device.id, e.message)));
     }
   }
 }

进一步检查 updateDevice 函数如何处理洗衣机上的暂停 / 恢复,您会发现与暂停 / 恢复命令匹配的字符串不正确:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpausePause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

修正错误

现在您已经确定了错误的根本原因,接下来可以更正暂停 / 恢复命令的字符串:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

测试修正效果

使用 Firebase CLI 部署更新后的代码:

firebase deploy --only functions

请重新尝试以下语音指令,现在您会发现当您暂停 / 恢复洗衣机时,Google 助理会正确地做出响应。

“Ok Google,让洗衣机暂停运行。”

=>

“没问题,正在暂停洗衣机。”

“Ok Google,恢复我的洗衣机。”

=>

“知道了,正在恢复洗衣机。”

您也可以通过提出问题来测试洗衣机的当前状态。

“Ok Google,我的洗衣机启动了吗?”

“Ok Google,我的洗衣机在运行吗?”

“Ok Google,我的洗衣机洗到哪一步了?”

4. 使用测试套件测试您的 Action

除了手动测试外,你还可以使用自动化的智能家居测试套件,根据与你的 Action 关联的设备类型和特征来验证用例。测试套件会运行一系列测试来检测 Action 中的问题,并会显示失败测试用例的信息性消息,在调试事件日志之前加快调试速度。

运行智能家居测试套件

如需测试测试套件的智能家居 Action,请按照以下说明操作:

  1. 在网络浏览器中,打开智能家居测试套件
  2. 使用右上角的按钮登录 Google。这样,测试套件就可以将命令直接发送到 Google 助理。
  3. Project ID 字段中,输入智能家居 Action 的项目 ID。然后点击下一步以继续操作。
  4. 测试设置步骤中,您会看到测试套件列出了洗衣机的设备类型和特征。

78ed6a1ebdb581bf.png

  1. 停用 Test Request Sync 选项,因为示例洗衣机应用没有任何用于添加/移除/重命名洗衣机的界面。在生产系统中,每当用户添加/移除/重命名设备时,您都必须触发请求同步
  2. 点击下一步以开始运行测试。

测试套件运行完毕后,查看测试用例的结果。您会看到两个失败的测试用例,并分别显示相应的错误消息:

5838d10631c98ed2.png

如需调试智能家居 Action 是否失败,你需要先分析错误消息,以确定错误的根本原因。

分析错误消息

为了帮助开发者找出根本原因,测试套件会显示每个失败的测试用例的错误消息,指明失败的原因。

对于上述第一个失败的测试用例,

99e4e5d06965a8a7.png

其错误消息表示测试套件在智能家居 Action 报告的状态下需要 "isPause": true,但实际状态仅包含 "isPause": false

此外,第二个失败的测试用例的错误消息会指明智能家居 Action 的 QUERY 响应中的状态包括 "isPause": true,这与 "isPause": false 中智能家居 Action 报告的状态不同:

fdb5124102e3a37.png

根据上述两种错误消息,你应该检查你的 Action 报告的状态 isPaused 是否正确。

确定错误的根本原因

打开 functions/index.js,其中包含 reportstate 函数,该函数通过报告状态将状态更改发布到 Home Graph。检查报告状态载荷,您会发现该载荷缺少 isPaused 状态,这正是测试套件在失败的测试用例中检查的状态。

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
              [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      ...
    });

修正错误

现在您已经确定了错误的根本原因,接下来可以通过将 isPaused 状态添加到报告状态载荷中来修改 functions/index.js

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
              [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

测试修正效果

使用 Firebase CLI 部署更新后的代码:

$ firebase deploy --only functions

重新运行智能家居测试套件,您会发现所有测试用例均已通过。

148837f85d377dd6.png

5. 恭喜

17d485868a6771bc.png

恭喜!你已成功了解如何通过测试套件对智能家居 Action 以及 GCP 指标和 Logging 进行问题排查。

了解详情

在此 Codelab 的基础上,尝试做以下练习并浏览其他资源:

您还可以详细了解如何测试和提交 Action 以供审核,包括用于向用户发布 Action 的认证流程。