Google Cloud 提供了各种工具，让您可以通过 Google Cloud Monitoring 来监控项目可靠性，以及通过 Google Cloud Logging 错误日志来调试问题。每当用户 intent 执行失败时，Google Home Analytics 流水线都会将该失败情况记入您的相应指标，并在项目日志中发布错误日志。
若要对错误进行问题排查，需要执行两个步骤：
- 通过智能家居指标监控项目的状态。
- 通过查看错误日志中的详细错误说明，对问题进行调查。
您可以选择通过与其他用户共享您的 Action 来测试它。请务必正确处理错误和异常。
监控错误
您可以通过 Google Cloud Monitoring dashboard来查看项目指标。以下是一些对于监控质量和调试尤为有用的关键图表：
- 监控项目可靠性时，首先应关注成功率图表。如果此图表中的指标下降，可能表示用户群中的部分用户或所有用户遇到了服务中断。我们建议您在每次项目发生更改或更新后密切监控此图表，看看是否有任何异常情况。
- 第 95 个百分位延迟图表是衡量 Cloud-to-cloud 集成给用户的体验好坏的重要指标。如果此图表中突然出现波动，可能表示您的系统跟不上请求的速度。建议您定期查看此图表，看看是否有任何意外行为。
- 在排查与集成相关的问题时，错误细分图表最为有用。针对成功百分比图表中突出显示的每个错误，错误细分图表中都会相应显示一个错误代码。您可以参阅下表，了解 Google Home platform标记的错误以及相应的排查方法。
常见平台错误代码
以下是项目日志中的一些常见错误代码，用于识别 Google Home platform发现的问题。如需了解问题排查信息，请参阅下表。如需查看完整的错误代码列表，请参阅错误和异常。
| 错误代码 | 说明 | 合作伙伴可采取的行动 |
|---|---|---|
ACTION_NOT_AVAILABLE |
该命令对设备的当前状态无效（例如，在设备处于关闭状态时发出“设置温度”命令）。
验证履单中的设备特征和当前状态逻辑。 |
是 |
AGENT_ISSUE |
合作伙伴的云代理出现一般性问题。
检查履单日志中是否存在未处理的异常或崩溃。 |
是 |
AGENT_UNAVAILABLE_ERROR |
Google 无法访问合作伙伴的履单网址。
确保您的服务器处于在线状态，防火墙未阻止 Google，并且网址正确无误。 |
是 |
APP_LAUNCH_FAILED |
未能启动目标设备上的第三方应用。
验证 appId 以及应用是否受目标硬件支持。 |
是 |
AUTH_EXPIRED |
OAuth 访问令牌已过期，无法刷新。
检查刷新令牌轮换，确保用户未撤消访问权限。 |
是 |
BACKEND_FAILURE_URL_TIMEOUT |
Google 在尝试访问您的服务时请求超时。
验证您的服务是否处于在线状态、是否接受连接以及是否未超出容量。此外，请验证目标设备是否已开机、已联网且已同步。 |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google 从您的服务收到 HTTP 5xx 错误代码。
在 Google Cloud Logging 中使用 requestId，以查看智能家居服务日志。
|
|
CHANNEL_SWITCH_FAILED |
设备无法切换到所请求的媒体渠道。
验证用户的频道名称/编号和订阅状态。 |
是 |
CHARGER_ISSUE |
设备报告其充电系统存在硬件问题。
合作伙伴应调查硬件级遥测和电池健康状况。 |
是 |
CHECK_PARTNER_APP |
此错误需要用户打开合作伙伴的应用才能解决。
对于需要复杂界面互动的错误（例如固件更新），请使用此代码。 |
是 |
COMMAND_FAILED |
执行命令期间发生了常规故障。
检查履单日志中的具体 requestId，找出根本原因。
|
是 |
COMMAND_INSERT_FAILED |
Google 无法将该设备的指令排入队列或进行处理。
调查数据库写入性能或内部命令排队逻辑。 |
是 |
DEVICE_NOT_FOUND |
请求中的设备 ID 在合作伙伴端不存在。
确保当用户添加或删除设备时，云会触发 requestSync。
|
是 |
ERROR_STATUS |
响应表明状态为不含代码的非特定“ERROR”。
始终包含特定的 errorCode 字符串，以改进用户 TTS 和信息中心数据。
|
是 |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google 从您的履单服务收到 HTTP 4xx 错误（而非 401）。
检查您的 Web 服务器日志中是否有 403、404 或 400 响应。 |
是 |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
履单网址被 robots.txt 或安全过滤条件屏蔽。
确保 Google 的抓取工具/服务可以访问您的履单端点。 |
是 |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google 从您的履单服务收到 HTTP 5xx 错误。
调查服务器崩溃、超时或 502/503 网关错误。 |
是 |
EXECUTION_BAILOUT_INVALID_RESPONSE |
JSON 响应格式不正确，处理已中止。
使用 JSON 验证器确保您的回答严格遵循意图架构。 |
是 |
EXECUTION_GAL_BAD_3P_RESPONSE |
由于令牌响应中的格式无效，账号关联失败。
验证 OAuth 服务器的响应格式是否符合 Google 的要求。 |
是 |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
用户的账号缺少执行此操作所需的权限。
检查在 OAuth 期间请求的范围，确保它们与所需的特征相符。 |
是 |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
合作伙伴云表示用户已解除账号关联。
确保您的 agentUserId 映射稳定且未被清除。
|
是 |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
集成在合作伙伴端处于只读状态。
检查用户账号是否已中止或处于“只读”维护模式。 |
是 |
EXECUTION_GAL_UNLINKED_BY_3P |
第三方服务主动解除了账号关联。
调查用户断开连接的原因（例如，安全重置）。 |
是 |
EXECUTION_INVALID_JSON |
Google 无法解析 JSON 响应载荷。
检查回答中是否存在语法错误、括号缺失或无效字符。 |
是 |
FAULTY_BATTERY |
设备硬件报告电池故障或电量耗尽。
指示用户使用 TTS 或应用更换实体电池。 |
是 |
FUNCTION_NOT_SUPPORTED |
设备不支持所请求的模式或功能。
确保您的 SYNC 响应准确反映了设备的功能。
|
是 |
HARD_ERROR |
一种非暂时性故障，如果不进行人工干预，则无法解决。
此值用于表示永久性硬件故障或无法恢复的账号状态。 |
是 |
INVALID_AUTH_TOKEN |
Google 从您的服务收到 HTTP 401 错误代码。
访问令牌未过期，但您的服务已使其失效。 在 Google Cloud Logging 中使用 requestId，以查看智能家居服务日志。
|
|
INVALID_JSON |
响应结构无效（例如，缺少必填字段）。
根据意图 JSON 架构验证您的回答。 |
是 |
LOCK_FAILURE |
智能门锁无法移动到所请求的状态。 调查锁硬件上的物理卡住、低电量或电机故障问题。 |
是 |
MALFORMED_JSON |
JSON 结构损坏（例如，字符串或对象未关闭）。
确保您的执行方式使用标准 JSON 库来序列化响应。 |
是 |
MISSING_STATE |
QUERY 响应未包含所请求的设备状态。
确保 SYNC 中定义的所有特征都包含在每个 QUERY 回答中。
|
是 |
NETWORK_PROFILE_NOT_RECOGNIZED |
设备无法识别所请求的网络配置文件。
验证配置文件名称字符串是否与 SYNC 响应中的受支持配置文件匹配。
|
是 |
NOT_IMPLEMENTED |
合作伙伴尚未实现所请求的 intent 或特征。
请仅在 SYNC 响应中添加您已完全实现的特征。
|
是 |
OAUTH_RECONNECT_CALL_TO_ACTION |
触发通知，提示用户重新关联账号。
当用户会话失效并需要手动重新进行 OAuth 身份验证时，请使用此值。 |
是 |
OPEN_AUTH_FAILURE |
用户的访问令牌已过期，Google 无法刷新该令牌；或者 Google 从您的服务收到 HTTP 401 错误代码。
如果您发现此代码的出现频率增加，请检查与智能家居 intent 或刷新令牌请求相关的错误的出现频率是否也有所增加。 |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
返回的 errorCode 字符串不在 Google 的支持列表中。
将内部错误映射到官方错误列表。 |
是 |
PARTNER_RESPONSE_INVALID_PAYLOAD |
响应中的 payload 字段不是有效的 JSON 对象。
验证履单响应的根结构。 |
是 |
PARTNER_RESPONSE_INVALID_STATUS |
响应 status 不是 SUCCESS、ERROR 或 OFFLINE。
确保响应中的每个设备结果都包含有效的状态字符串。 |
是 |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
响应未包含所有请求的命令/设备的结果。
请求的 commands 数组中的每个商品都必须有对应的响应条目。
|
是 |
PARTNER_RESPONSE_MISSING_DEVICE |
响应中省略了 Google 请求的特定设备。
确保您的回答包含请求载荷中提供的每个 ID。
|
是 |
PARTNER_RESPONSE_MISSING_PAYLOAD |
响应中缺少必填的 payload 字段。
确保您的顶级 JSON 对象包含 payload 键。
|
是 |
PARTNER_RESPONSE_NOT_OBJECT |
整个响应无法解析为 JSON 对象。
检查 HTTP 响应正文中是否存在尾随字符或非 JSON 内容。 |
是 |
PROTOCOL_ERROR |
底层通信协议中发生错误。
调查 HTTP 标头问题或 SSL/TLS 握手失败问题。 |
是 |
RELINK_REQUIRED |
用户必须重新关联账号，才能继续使用集成服务。
确保当刷新令牌永久无效时，服务器会返回此代码。 |
是 |
REQUEST_ID_NOT_FOUND |
Google 找不到相应请求的内部跟踪 ID。
通常是内部平台错误；请监控峰值并与支持团队联系。 |
是 |
RESOURCE_UNAVAILABLE |
所请求的资源（设备或特征）不可用。
检查设备是否处于“忙碌”状态或已被暂时停用。 |
是 |
RESPONSE_TIMEOUT |
履单服务未能在 9 秒内做出响应。
优化后端延迟时间；检查是否存在缓慢的数据库查询或区域网络延迟。 |
是 |
RESPONSE_UNAVAILABLE |
未收到合作伙伴履单网址的响应。
验证您的服务是否正在运行，以及端点是否未崩溃。 |
是 |
SCENE_CANNOT_BE_APPLIED |
无法激活所请求的场景（例如，缺少设备）。
检查合作伙伴云端用户场景的内部健康状况。 |
是 |
STREAM_UNPLAYABLE |
无法启动摄像头数据流或摄像头数据流已失败。
验证 WebRTC/HLS 信令，并确保流网址有效。 |
是 |
TIMEOUT |
处理 intent 时发生常规超时。
检查云端与设备中枢之间的内部服务超时日志。 |
是 |
TRANSIENT_ERROR |
暂时性错误是指会自动解决的错误。
这些错误最常表现为与设备或服务的连接断开。此外，如果无法打开与服务器的新连接，也会出现此问题。 |
|
UNABLE_TO_LOCATE_DEVICE |
无法使用定位器特征找到设备（例如，ping 失败）。
检查设备的本地连接（Wi-Fi/蓝牙）。 |
是 |
UNABLE_TO_RING_DEVICE |
已连接到设备，但无法触发其响铃/提醒功能。
验证硬件的提醒/扬声器状态和音量。 |
是 |
UNABLE_TO_SILENCE_DEVICE |
设备无法停止有效提醒/响铃。
调查云端与实体设备之间的通信故障。 |
是 |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
发生了意外错误；用户应检查合作伙伴应用。
用作没有特定 Google 支持的等效项的错误的全方位捕获。 |
是 |
UNKNOWN_ERROR |
一般性故障，未提供其他详细信息。
旨在用更具体的错误代码替换此代码，以改进问题排查。 |
是 |
UNLOCK_FAILURE |
智能门锁无法达到“已解锁”状态。 检查是否存在硬件卡顿、电池电量不足或 PIN 码输入无效的情况。 |
是 |
搜索日志
当您能够熟练地利用指标监控集成后，接下来就是利用 Cloud Logging 对特定错误进行问题排查。错误日志是一个类似 JSON 的条目，其字段包含各种有用信息，例如时间、错误代码，以及关于原始智能家居 intent 的详细信息。
Google Cloud 中有多个系统始终会向您的项目发送日志。您需要编写用于过滤日志的查询，以查找所需的日志。查询可以基于时间范围、资源、日志严重级别或自定义条目。
您可以使用查询按钮来构建自定义过滤条件。
如需指定时间范围，请点击时间范围选择按钮 ，然后从提供的选项中选择一个。这样系统就会过滤日志，并显示所选时间范围内生成的日志。
若要指定资源，请点击资源下拉菜单，然后选择 Google 助理 Action 项目。这样系统就会在您的查询中添加过滤条件，从而显示您的项目生成的日志。
使用严重级别按钮，按紧急、信息、调试和其他严重级别日志等级进行过滤。
您还可以使用Logs Explorer中的“查询”字段输入自定义条目。此字段使用的查询引擎既支持基本查询（例如字符串匹配），也支持更高级类型的查询，包括比较运算符 (<, >=, !=) 和布尔运算符 (AND, OR, NOT)。
例如，下面的自定义条目将返回由“LIGHT”类型设备产生的错误：
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
您可以访问查询库，查找更多有效查询日志的示例。
测试修正效果
在您发现错误并应用更新来修正错误后，我们建议您使用 Google Home Test Suite 全面测试修正效果。我们提供了介绍 Test Suite 使用方法的用户指南，该指南会逐步指导您有效地对更改进行测试。
学习资源
本文档说明了对智能家居 Action 中的错误进行问题排查的步骤。您也可以查看我们的 Codelab，详细了解调试：
- 调试智能家居 Codelab：关于调试智能家居云集成的快速入门指南。
- 调试 Local Home Codelab：调试智能家居本地集成的快速入门指南。