1. 准备工作
作为物联网 (IoT) 开发者,您可以构建智能家居 Action,让用户能够通过 Google Home 应用中的触控功能以及 Google 助理的语音指令来控制其设备。
学习智能家居 Action 的调试工具是构建与 Google 助理的生产级质量集成的重要一步。为了方便进行监控和调试,我们提供了 Google Cloud Platform (GCP) 指标、Logging 和智能家居测试套件来帮助您识别和解决与 Action 有关的问题。
前提条件
- 阅读创建智能家居 Action 开发者指南
- 运行将智能家居设备关联到 Google 助理 Codelab
构建内容
在此 Codelab 中,您将部署一个存在 2 个缺陷的智能家居 Action,并将其关联到 Google 助理,然后通过智能家居、Google Cloud Platform (GCP) 指标和 Logging 的测试套件调试该 Action 的缺陷。
学习内容
- 如何使用 GCP 指标和 Logging 找出和解决生产问题
- 如何使用智能家居测试套件来识别功能和 API 问题
所需条件
- 网络浏览器,例如 Google Chrome
- 安装了 Google Home 应用的 iOS 或 Android 设备
- Node.js 10.16 或更高版本
- Google Cloud 结算帐号
2. 运行发生故障的应用
获取源代码
点击以下链接,将此 Codelab 的示例下载到您的开发机器上:
...或者,您也可以通过命令行克隆 GitHub 代码库:
$ git clone https://github.com/google-home/smarthome-debug.git
项目简介
洗衣机应用包含以下子目录:
public
:一个前端界面,可轻松控制和监控智能洗衣机的状态。functions
:一项完全实现的云服务,使用 Cloud Functions for Firebase 和 Firebase Realtime Database 来管理智能洗衣机。
关联到 Firebase
在开发机器上打开终端。进入 washer-faulty
目录,然后使用在将智能家居设备关联到 Google 助理 Codelab 中构建的 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
在浏览器中打开 Hosting 网址 (https://<project-id>.firebaseapp.com
),查看 Web 应用。在网页界面上,点击刷新 按钮,通过 Request Sync 使用发生故障的洗衣机应用的最新设备元数据更新 HomeGraph:
打开 Google Home 应用,验证您能否看到名为 Faulty Washer(故障洗衣机)的洗衣机设备。
3. 测试您的 Action
部署项目后,测试您的 Action 是否可控制洗衣机。
测试洗衣机
当您通过手机尝试以下任何语音指令时,请查看值的变化情况:
“Ok Google,启动洗衣机。”
“Ok Google,运行洗衣机。”
“Hey Google,让洗衣机暂停运行。”
“Ok Google,恢复洗衣机。”
“Ok Google,让洗衣机停止运行。”
当你暂停 / 恢复洗衣机时,你会注意到 Google 助理通过语音回复了出了点问题:
“抱歉,我无法连接<项目显示名称>。”
如需调试此问题,您首先需要详细了解错误,并缩小范围并确定根本原因。
Smarthome Analytics 信息中心
Smarthome Analytics 信息中心汇总了云执行方式的使用情况和运行状况指标图表,非常适合检查错误:
- 用量指标反映了智能家居 Action 的使用趋势,包括日活跃用户数和执行方式的总请求数。
- 健康指标可帮助您监控智能家居 Action 的异常情况,涵盖请求延迟时间、成功百分比和错误细分数据。
如需缩小错误原因的范围,请按照以下步骤访问项目信息中心。
- 在 Actions 控制台中,前往“项目”页面。
- 选择你的智能家居项目。
- 选择 Analytics 标签页,然后点击 Go to Google Cloud Platform。
- 系统随即会显示您的项目在 Google Cloud 上的信息中心列表。选择 Google Home Analytics - 云集成信息中心。
- 向下滚动到 Cloud Fulfillment 错误 - 状态细分图表,查看突出显示的时间范围内的错误代码。
PARTNER_RESPONSE_MISSING_DEVICE
错误代码会提示根本原因。接下来,根据错误代码检索事件日志以了解详情。
访问事件日志
如需详细了解此错误,请通过 Cloud Logging 访问智能家居 Action 的事件日志。
在 Google Cloud Platform 中打开导航菜单,然后在操作下选择 Logging > 日志浏览器,以访问项目的事件日志。或者,您也可以在搜索框中搜索日志浏览器。
在查询部分中,输入查询 PARTNER_RESPONSE_MISSING_DEVICE
,然后点击运行查询。与查询匹配的日志会显示在查询结果部分中。
错误日志显示了一个智能家居事件,其中包含错误详情,指示:
- 用户执行的操作是“恢复洗衣机”(
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 by Test Suite:
- 在网络浏览器中,打开智能家居测试套件。
- 使用右上角的按钮登录 Google。这样一来,测试套件就能将命令直接发送给 Google 助理。
- 在项目 ID 字段中,输入智能家居 Action 的项目 ID。然后点击下一步继续操作。
- 在 Test Settings 步骤中,您会看到 Test Suite 列出了洗衣机的设备类型和特征。
- 请停用 Test Request Sync 选项,因为示例洗衣机应用没有可添加 / 移除 / 重命名洗衣机的界面。在生产系统中,每当用户添加 / 移除 / 重命名设备时,您都必须触发请求同步。
- 点击下一步,开始运行测试。
测试套件运行完毕后,查看测试用例的结果。您会看到两个失败的测试用例,分别显示了以下错误消息:
若要调试智能家居 Action 失败,你需要先分析错误消息,进而确定错误的根本原因。
分析错误消息
为了帮助开发者确定根本原因,测试套件会显示每个失败测试用例的错误消息,以说明失败原因。
对于上述第一个失败的测试用例,
其错误消息表明,测试套件预计会在您的智能家居 Action 报告的状态中返回 "isPause": true
,但实际状态仅包含 "isPause": false
。
此外,第二个失败测试用例的错误消息表明,来自智能家居 Action 的 QUERY
响应中的状态包含 "isPause": true
,该状态与智能家居 Action 报告的状态不同:"isPause": false
:
然后,您应该根据这两条错误消息检查 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
重新运行智能家居测试套件,您会发现所有测试用例均已通过。
5. 恭喜
恭喜!你已成功学习了如何通过测试套件、GCP 指标和 Logging 来排查智能家居 Action 问题。
了解详情
在此 Codelab 的基础上,尝试做以下练习并浏览其他资源:
- 向您的设备添加更多支持的特征,并使用测试套件对这些特征进行测试。
- 创建信息中心、设置提醒并以编程方式访问指标数据,获取有关 Action 的实用用量指标。
- 探索智能家居的本地执行方式。
- 请查看我们的 GitHub 示例了解详情。
您还可以详细了解如何测试并提交 Action 以供审核,包括用于向用户发布 Action 的认证流程。