智能家居常见问题解答

常规

问： 应该在何种平台上以何种语言实现云到云执行方式基础架构？

答： 您可以在任何平台上以您选择的任何语言实现该基础架构，只要它支持现代 SSL (TLS) 和 OAuth 2.0 即可。建议您的部署要尽可能靠近您的其他 基础架构，以提高可靠性并缩短运行延迟（尽快向 实际用户设备返回响应）。

问：设备 ID 必须是唯一的吗？

答： 设备 ID 应该是唯一的。如果您没有在整个服务中使用唯一的 ID，那么必须确保设备 ID 至少在每用户级别上是唯一的。假设一名用户有多处住宅，并且两处住宅都与同一用户进行了集成。如果用户要求打开一处住宅中的灯，那么不应打开另一处住宅中具有相同 ID 的灯。

问： 设备名称必须是唯一的吗？

答： 名称不必是唯一的，但在用户设置完毕后，我们可能会在用户使用的过程中建议用户改进不太合适的命名，以获得更好的用户体验。

下面提供了快速命名指南：

  • 名称应是用户确实会用的表述。
  • 系统可识别字符串的子集，因此如果你设置了“acme 彩灯”这个名称，我们也可以对“acme 灯”作出响应。
  • 我们建议同时添加产品的描述性名称以及一个或多个用户定义的名称。
  • 用户不需要为灯指定房间名称，因为系统会自动为灯指定房间；每个房间里灯的名称应该是唯一的，但随时都可以用复数表述来控制所有灯（例如，办公桌灯台上的两个灯泡分别命名为“北侧的灯”和“东侧的灯”，但也可以统称为“灯”来一并控制）。

问： 设备状态多久更新一次？

答： 系统会在收到 QUERY 或 EXECUTE（ 用户发起的 Action）时检索暂存状态。如果用户询问“灯是开着的吗？”或者希望把灯调亮，系统需要执行查询以确定当前的状态。

问： 可以使用设备的当前状态直接更新 Home Graph 吗？

答： 可以，请使用 Report State API 调用。

账号关联和 OAuth

答： 需要。必须进行账号关联才能将用户的设备连接到 提供商的云服务。

问： 针对 OAuth 的访问令牌每 15.213 小时失效一次，可以吗？

答： 可以，但请针对比较短的失效时间（例如 10-20 分钟）进行测试。 我们的 OAuth 客户端应该会根据需要刷新令牌，而针对较短的失效时间进行测试可以验证这一点。

意图

问：系统何时执行 SYNC？

答： 系统会在 OAuth 完成后以及进行 请求同步调用后立即执行 SYNC。

问： 为什么 SYNC 不起作用？

答： 可能导致该请求失败的常见原因有很多。

  • 您发送的设备类型有误。

    • 例如，我们期待的是 action.devices.types.LIGHT，但是你发送了 action.devices.types.Light。

  • 您发送的设备类型不受支持。

    • 例如，你发送了 action.devices.types.FLASHLIGHT，但我们不支持这种 设备。

  • 您发送的字段无效/不受支持。

    • 例如，您有一个字段不在我们的规范中。

  • 您的 SYNC 响应存在其他某种格式问题。

    • 请检查括号！

  • 你遇到了账号关联问题。

    • 请确认你在 SYNC 请求的 Auth 标头中收到的访问令牌是否有效。

  • 对 SYNC 请求的响应用时过长。

    • 请确认你能否在 5 秒内响应 SYNC 请求。

问： 是否可以使用“待处理”响应？

答： 如果您的设备支持实时响应，我们强烈建议您提供成功/失败响应，而不是待处理响应。如果您认为自己需要使用“待处理”响应，请与我们联系。我们了解有些低功耗的 、不支持实时响应的设备可能需要使用待处理响应和异步 执行模式。

测试和提交

问： 可以设置开发云环境吗？

答： 可以，您可以测试未发布的云环境和配置。

问： 我的 Action 未显示在 Google Home 应用的“家居控制”部分中，这是为什么？

答： 请确认您是此项目的开发者。

报告状态

问： 实现报告状态有什么前提条件吗？

答： 项目需要使用 Smart Home API、支持 OAuth2，并需要 具备要报告状态的特征。

问： 我们需要多久报告一次设备上的状态？

答： Google 关注转换和终止状态。但如果在短时间内有大量状态变化（例如用户在一分钟内开关冰箱三次或滑动调光器），那么我们只需要报告的最终状态。

问： 在调用报告状态时，是否需要发送设备的完整状态？

答： 系统不支持部分状态更新，因此 Report State 调用应始终包含已更新的 特定特征的所有数据。如果两个特征会导致 不一致，请将它们一并报告。

问： Google 能否通过查询我的设备来获取状态（即轮询设备）？

答： 这是一种后备机制，我们不建议使用。如果我们需要经常轮询这些用户的设备，则无法保证额外负载是多少。这种需求来自新的视觉平台。除了未知负载的问题之外，用户体验也会大打折扣。我们 认为Report State对平台至关重要。

问： 目前哪些特征支持报告状态？

答： 支持已关联状态的所有公共特征。还应报告设备在线状态发生的任何变化 。

请注意，场景没有状态。不过，它们可能会导致设备状态发生变化。如果 Google Home Graph 中的任何设备有 变更状态，则需要报告此状态。

问： 报告状态是否要求发送时间戳？

答： 我们不要求发送时间戳；发送的最后一个状态将覆盖 之前的调用。

问： 如果我已经在 Query 和/或 Execute 中发送了状态，是否需要单独报告状态？

答： Home Graph 仅存储通过 Report State发送的状态。作为对 EXECUTE intent 和 QUERY intent 的响应而返回的状态仅用于针对用户的语音响应， 不会被存储。因此，即使设备的新状态已经作为对 EXECUTE intent 或 QUERY intent 的响应而返回了，也应调用Report State。

问： 如果在规定的期限内没有完全实现报告状态，会有什么后果？

答： 这会导致用户在 Google Home app (GHA)和视觉平台中的体验品质下降。这意味着，系统会发送许多 QUERY intents 来轮询状态，并且我们无法保证这会 与合作伙伴云中的额外负载相对应。

问： 如何测试报告状态实现情况？

答： 使用 Home Graph 查看器，这是一款自助测试工具，可向您显示 在 Home Graph 中存储的当前设备状态。

问： 我们可以将随机 requestId 用于报告状态吗？

答： 如果 Report State 由 EXECUTE 请求触发，我们建议合作伙伴使用从 EXECUTE 请求收到的相同 requestId，否则你只需使用随机 requestId。

问： 如果一名用户有多台设备，而其中一台设备的状态有变，我们是否需要报告所有设备的最新状态？

答：不需要。你只需报告该特定设备的状态。

最佳实践

问： 多久的延迟在可接受范围内？

答： 理想情况下，延迟应小于 1000 毫秒，2-5 秒的延迟也是可以接受的。如果延迟时间在 5 秒左右，请与我们联系。

问： 如何让声控音响设备在离线状态下也能正确地做出响应？

答: 在设备处于离线状态时返回离线状态。对于此错误，我们会以 TTS 形式返回“目前不可用 ”。如需了解详情，请参阅 错误和异常。