问题排查

示例应用

如果您在使用 Home API 时遇到任何问题，可以收集日志以进行进一步调试。从移动设备收集日志需要使用 Xcode。 如果您需要 Google 旗下助理的帮助，请从 iOS 设备和集线器收集日志，然后在 Issue Tracker 中提交工单，并附上相关信息和日志。

收集 iOS 日志

对于涉及 Xcode 的所有步骤，您的移动设备都必须连接到本地机器。

应用日志和 SDK 日志会直接显示在 Xcode 控制台中，并可直接在其中收集。当移动设备连接到本地机器，并且您通过 Xcode 运行应用时，控制台会自动捕获并流式传输来自应用层和集成式 Home SDK 的标准输出 (stdout) 和标准错误 (stderr) 日志。这样，您就可以在开发和调试期间，以简单直接的方式监控实时初始化过程、API 互动和 SDK 事件。

从 Xcode 收集扩展程序日志

如果您在使用 Home API 时遇到任何问题，可以收集日志以进行进一步调试。

  1. 在 Xcode 中，前往顶部菜单栏中的 Debug，然后点击 Attach to Process by PID or Name。

    示例应用调试

  2. 在 PID or Process Name（PID 或进程名称）下，选择 MatterExtension，然后点击 Attach（附加）。

    示例应用附加扩展程序

  3. 如果您点击右上角，将会看到 Waiting to attach to MatterAddDeviceExtension on iPhone。

    示例应用等待状态

  4. 点击该标签页，然后选择 MatterAddExtension。

    添加 Matter 扩展程序的示例应用

  5. 控制台会记录扩展程序日志。

Sherlog：跨堆栈事件跟踪

Sherlog 是一项实时跟踪服务，可提供 Google 基础设施与合作伙伴云服务之间互动的端到端视图。

前提条件：跟踪需要使用 Google 协调的共享账号（例如，GReg 注册账号或演示账号）。

核心用途：调试功能缺陷和云到云 (C2C) 集成问题（例如账号关联失败或设备状态不正确），而无需更改生产代码。

功能：提供完整的 RPC 调用图、请求/响应载荷以及 SYNC、EXECUTE、QUERY 和账号关联 intent 的元数据。

Fuchsia Hub 设备日志

您可以使用此方法从以下 Fuchsia Hub 收集日志： * Google Nest Hub（第 2 代） * Google Nest Hub Max

如需为本地日志检索启用 hub，请执行以下操作：

  1. 向您的 Google 技术支持客户经理 (TAM) 发送电子邮件，告知其设备的序列号和型号。您可以在设备下方找到这些小字。
  2. 列入许可清单后，您必须按照以下步骤启用该功能：
    • 在 Hub 中：
      1. 从屏幕顶部向下滑动。
      2. 点按“设置”图标
      3. 查找 Fuchsia 版本：在 Nest Hub（第 2 代）上，依次前往设备信息 > 技术信息 > Fuchsia 版本
      4. 点按“Fuchsia 版本”7 次。此操作将启用开发者选项
      5. 返回到顶层菜单
      6. 点按“开发者选项”
      7. 点按“合作伙伴日志记录”
    • 该功能将启用 24 小时。之后，从第 5 步开始重新启用日志记录功能。
  3. 获取 Hub 的 IP 地址：
    • 通过带屏幕的集线器：
      1. 从屏幕顶部向下滑动。
      2. 点按“设置”图标
      3. 查找设备 IP 地址：在 Nest Hub（第 2 代）上，前往设备信息 > 技术信息 > IP 地址
    • 在手机上通过 Google Home 应用 (GHA) 执行以下操作：
    • 点按相应设备，打开设备详情页面
    • 点按“设置”图标 ，调出设置页面
    • 查找设备 IP 地址：依次前往设备信息 > 技术信息 > IP 地址
  4. 如需从 Hub 检索日志，您需要从同一 Wi-Fi 网络中的计算机向 Hub 发出 GET HTTP 请求。
    • 请记下端点的端口和路径： 
      curl -k -X GET https://ip-address:8443/setup/get_logs --output output-file
    • 连接只能保持打开一分钟，但从缓冲区检索的数据通常包含过去 20-30 分钟的事件。
      • 理想情况下，应在完成测试过程后立即使用此方法提取日志，以确保缓冲区包含与测试相关的内容（类似于 Android bug 报告）。

自动化操作

边缘检测

Google Home 生态系统中的自动化操作具有边缘检测功能，该逻辑可验证启动方式仅在实际状态发生变化时才会激活，而不是在状态更新仅重复设备的先前状态时激活。

例如，如果启动器是开灯，边缘检测会验证启动器是否仅在灯具设备从关闭状态变为开启状态时激活，而不是从开启状态变为开启状态（无变化）。

自动化操作未按预期运行

如果自动化操作在考虑边缘检测后仍未按预期运行，请执行以下操作：

  1. 检查每个设备，确保其在不依赖自动化操作的情况下也能正常运行。

  2. 查看自动化操作的自动化图，并将其与自动化 DSL 进行比较，以找出您可能存在的任何不正确的假设。

  3. 在执行自动化操作期间，在 Google Home 应用中观察设备状态。

  4. 检查并确保自动化操作引用的所有设备都位于您预期的结构中。删除自动化操作所依赖的设备可能会产生意外后果。请参阅删除设备对自动化操作的影响。

自动化操作在不该运行的时候运行

如果自动化操作在不该运行的时候运行，请检查启动方式条件。 您可能需要添加额外的逻辑，以确保状态变化仅被捕获一次，并且仅触发自动化操作一次。

自动化操作无法编译

确保您的应用包含所有必要的导入内容，包括与不同节点类型对应的每个类以及您引用的特征。

自动化操作创建未通过验证

如果自动化操作创建未通过验证，系统会显示警告或出错提示，提供有关问题的信息。如需了解详情，请参阅 ValidationIssueType 参考文档。

OAuth

如果您已有 OAuth 客户端

如果您已为已发布的应用创建了经过验证的 OAuth 客户端，则可以使用现有的 OAuth 客户端测试 Home API。

无需注册 Google Home Developer Console 即可测试和使用 Home API。 不过，即使您有来自其他集成的经过验证的 OAuth 客户端，您仍需要获得批准的 Developer Console 注册才能发布应用。

需要注意以下几点：

  • 使用现有 OAuth 客户端时，用户数量上限为 100。如需了解如何添加测试用户，请参阅生成 OAuth 客户端 ID。 除了 OAuth 验证之外，Home API 还规定，最多只能有 100 位用户向您的应用授予权限。 完成 Developer Console 注册后，此限制即会解除。

  • Developer Console 注册 应在您准备好通过 OAuth 限制设备类型授权时发送以供审批，以便为使用 Home API 更新应用做好准备。

对于仍处于 OAuth 验证待处理状态的 Google Cloud 应用，用户在验证完成之前无法完成 OAuth 流程。尝试授予权限将失败，并显示以下错误：

Access blocked: <Project Name> has not completed the Google verification process.