问题排查

示例应用

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

收集 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 下，选择 MatterExtension ，然后点击 Attach 。

    示例应用附加扩展服务示例

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

    示例应用的等待状态

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

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

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

Sherlog：跨堆栈事件跟踪

Sherlog 是一种实时跟踪服务，可提供 Google 基础架构与合作伙伴云服务之间交互的端到端视图。

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

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

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

Fuchsia 中枢设备日志

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

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

  1. 向您的 Google 技术支持客户经理 (TAM) 发送电子邮件，告知其您设备的序列号和型号。您可以在设备底部找到这些信息（以小写字母显示）。
  2. 列入许可名单后，您必须按照以下步骤启用该功能：
    • 在中枢上：
      1. 从屏幕顶部向下滑动。
      2. 点按“设置”图标
      3. 找到 Fuchsia 版本：在 Nest Hub（第 2 代）上，依次前往设备信息 > 技术信息 > Fuchsia 版本
      4. 点按“Fuchsia 版本”7 次。这将启用开发者选项
      5. 返回到顶级菜单
      6. 点按“开发者选项”
      7. 点按“合作伙伴日志记录”
    • 该功能将启用 24 小时。之后，请从第 5 步开始重新启用日志记录功能。
  3. 获取中枢的 IP 地址：
    • 在中枢上（如果中枢有屏幕）：
      1. 从屏幕顶部向下滑动。
      2. 点按“设置”图标
      3. 找到设备 IP 地址：在 Nest Hub（第 2 代）上，依次前往设备信息 > 技术信息 > IP 地址
    • 在手机上的 Google Home 应用 (GHA) 中：
    • 点按相应设备以打开对应的设备详情页面
    • 点按“设置”图标 以 打开“设置”页面
    • 找到设备 IP 地址：依次前往设备信息 > 技术信息 > IP 地址
  4. 如需从中枢检索日志，您需要从同一 Wi-Fi 网络中的计算机向中枢发出 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 不需要注册。 不过，您仍然需要已获批准的 Developer Console注册才能发布应用，即使您有来自其他集成的 已验证 OAuth 客户端也是如此。

需要注意以下几点：

  • 使用现有 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.