Google Cloud 提供了各种工具，让您可以通过 Google Cloud Monitoring 来监控项目可靠性，以及通过 Google Cloud Logging 错误日志来调试问题。每当用户 intent 执行失败时，Google Home Analytics 流水线都会将该失败情况记入您的相应指标，并在项目日志中发布错误日志。
若要对错误进行问题排查，需要执行两个步骤：
- 通过智能家居指标监控项目的状态。
- 通过查看错误日志中的详细错误说明，对问题进行调查。
您还可以选择与其他用户共享您的 Action，以便对其进行测试。 确保 正确处理错误和异常 。
监控错误
您可以使用 Google Cloud Monitoring dashboards 来查看项目指标。以下是一些关键图表，对于监控质量和调试尤为有用：
- 监控项目可靠性时，首先应关注成功率 图表。如果此图表中的指标下降，可能表示用户群中的部分用户或所有用户遇到了服务中断。我们建议您在每次项目发生更改或更新后密切监控此图表，看看是否有任何异常情况。
- 第 95 个百分位延迟时间 图表是衡量 您的 Cloud-to-cloud 集成给用户的体验好坏的重要指标。如果此图表中突然出现波动，可能表示您的系统跟不上请求的速度。建议您定期查看此图表，看看是否有任何意外行为。
- 在排查与集成相关的问题时，错误细分 图表最为有用。针对成功百分比图表中突出显示的每个错误，错误细分图表中都会相应显示一个错误代码。您可以在下表中查看 Google Home platform 标记的错误以及如何排查这些错误。
常见平台错误代码
以下是项目日志中的一些常见错误代码，用于 识别 Google Home platform发现的问题。如需了解问题排查信息，请参阅下表。如需查看完整的错误代码列表， 请参阅 错误和异常。
| 错误代码 | 说明 | 合作伙伴可采取的行动 |
|---|---|---|
AGENT_ISSUE |
合作伙伴的云代理出现一般问题。
检查执行日志中是否存在未处理的异常或崩溃。 |
是 |
AGENT_UNAVAILABLE_ERROR |
Google 无法访问合作伙伴的执行网址。 确保您的服务器处于在线状态，防火墙未阻止 Google，并且 网址正确无误。 |
是 |
BACKEND_FAILURE_URL_TIMEOUT |
Google 在尝试访问您的服务时超时。
验证您的服务处于在线状态、接受连接且 未超出容量。此外，还要验证目标 设备是否已开机、处于在线状态且已同步。 |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google 从您的服务收到 HTTP 5xx 错误代码。
在 Google Cloud Logging 中使用 requestId，以查看
智能家居服务日志。调查服务器崩溃、超时、
或 502/503 网关错误。
|
|
COMMAND_FAILED |
执行命令期间发生一般性故障。
检查执行方式日志中是否存在特定的 requestId
以找出根本原因。 |
是 |
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 验证器确保您的响应严格遵循 intent 架构。 |
是 |
EXECUTION_GAL_BAD_3P_RESPONSE |
由于令牌响应中的格式无效，帐号关联失败。
验证 OAuth 服务器的响应格式是否符合 Google 的 要求。 |
是 |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
用户的账号缺少执行此操作所需的权限。
检查 OAuth 期间请求的作用域，并确保它们与所需的特征匹配。 |
是 |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
合作伙伴云表示用户已解除其账号的关联。
确保您的 agentUserId 映射稳定且未被清除。
|
是 |
EXECUTION_GAL_NOT_FOUND |
存储在 Google 中的用户访问令牌和刷新令牌无效或
无法刷新，导致无法进行身份验证和访问
合作伙伴服务。
确保令牌保持有效且同步，正确处理账号状态 更改，并在确认令牌已被撤消后要求用户重新关联账号。 |
是 |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
集成在合作伙伴端处于只读状态。
检查用户的账号是否已暂停或处于“只能观看” 维护模式。 |
是 |
EXECUTION_GAL_UNLINKED_BY_3P |
该账号已由第三方服务主动解除关联。
调查用户断开连接的原因（例如安全 重置）。确保合作伙伴的 OAuth 服务器能够正确响应 Google 的 refresh_token 请求，以便无缝颁发新的访问令牌。
|
是 |
EXECUTION_INVALID_JSON |
Google 无法解析 JSON 响应载荷。
检查响应中是否存在语法错误、缺少括号或无效字符。 |
是 |
INVALID_AUTH_TOKEN |
Google 从您的服务收到 HTTP 401 错误代码。
访问令牌未过期，但您的服务已使其失效。 在 Google Cloud Logging 中使用 requestId，以查看您的
智能家居服务日志。
|
|
INVALID_JSON |
响应结构无效（例如缺少必填
字段）。
根据 intent JSON 架构验证您的响应。 |
是 |
MALFORMED_JSON |
JSON 结构已损坏（例如未关闭的字符串或
对象）。
确保您的执行方式使用标准 JSON 库来序列化 响应。 |
是 |
NOT_IMPLEMENTED |
合作伙伴尚未实现所请求的 intent 或特征。
仅在您的 SYNC 响应中添加您已
完全实现的特征。
|
是 |
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 |
响应未包含所有请求的
命令/设备的结果。
根据 Google Home 开发者 文档验证响应结构。确保响应不会因内部服务器错误而被截断或 返回空正文。请求的 commands 数组中的每个项都必须有对应的响应条目。 |
是 |
PARTNER_RESPONSE_MISSING_DEVICE |
Google 请求的特定设备在响应中被省略。
确保响应包含 ID提供的每个
请求载荷。
|
是 |
PARTNER_RESPONSE_MISSING_PAYLOAD |
响应缺少必填的 payload 字段。
确保顶级 JSON 对象包含 payload 键。
|
是 |
PARTNER_RESPONSE_NOT_OBJECT |
整个响应无法解析为 JSON 对象。
检查 HTTP 响应正文中是否存在尾随字符或非 JSON 内容。确保 payload.commands[] 是包含 ID、状态和可选状态的正确 JSON 对象。 |
是 |
REQUEST_ID_NOT_FOUND |
Google 找不到请求的内部跟踪 ID。
通常是内部平台错误；监控峰值并与支持团队联系 支持团队。 |
是 |
RESOURCE_UNAVAILABLE |
所请求的资源（设备或特征）不可用。
检查设备是否处于“忙碌”状态或已被暂时停用。 |
是 |
RESPONSE_TIMEOUT |
执行服务未能 9 秒内响应。 优化后端延迟时间；检查是否存在数据库查询速度缓慢或区域 网络延迟的情况。 |
是 |
RESPONSE_UNAVAILABLE |
未从合作伙伴执行网址收到任何响应。 验证您的服务是否正在运行，并且端点未崩溃。 |
是 |
TIMEOUT |
处理 intent 时发生一般性超时。
检查日志中是否存在云和 设备 hub 之间的内部服务超时。 |
是 |
搜索日志
当您能够熟练地利用指标监控集成后，接下来就是利用 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 测试套件 全面测试修正效果Google Home Test Suite。我们提供了介绍 如何使用Test Suite的用户指南，该指南会逐步指导您有效地对 更改进行测试。
学习资源
本文档说明了对智能家居 Action 中的错误进行问题排查的步骤。您也可以查看我们的 Codelab，详细了解调试：
- 调试智能家居 Codelab：关于调试智能家居云集成的快速入门指南。
- 调试 Local Home Codelab：调试智能家居本地集成的快速入门指南。