迁移到 Google Home 开发者中心已完成。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Google Home Vitals（云端）

借助这套信息中心和提醒，您可以主动维护与 Google Home 生态系统的高质量集成。Google 致力于支持合作伙伴为所有客户打造优质的生态系统

该信息中心包含三个部分，分别涵盖有助于提高整体集成质量的关键部分。

Google 到合作伙伴的指标 - 衡量从 Google 到您的云后端的调用是否正常。
系统运行状况 - 从合作伙伴到 Google 的指标 - 衡量从您的系统到 Google 的调用的运行状况。
设备健康状况 - 状态准确性 - 衡量存储在 Google 系统中（用于处理用户查询）的状态的准确性。

如果指标未达到目标值，系统会以红色突出显示，表明存在可能会影响用户体验的问题。以下信息详细介绍了每种目标，以及它们对用户的重要性。

如果点击以下按钮后未直接进入信息中心，您可以先选择概览页面，然后选择信息中心，再从我的信息中心列表中选择 Google Home Vitals 信息中心 (Cloud)，即可查看信息中心。

转到信息中心

Google 到合作伙伴指标

查询/执行成功率 >= 99.5% 指标用于衡量用户命令的正确执行频率，有助于避免 Google 助理做出“我无法访问该设备”之类的回答，或错误地确认未执行的命令。

“成功”的定义是什么？

如果 Google Home 平台收到有效响应，表明预期操作已完成或所请求的状态已检索到，则交易会被标记为成功。

包含非阻塞异常（例如，SUCCESS 状态伴随 lowBattery 异常）的响应会被计为成功交易。尽管有警告，但命令已到达设备，并且 intent 已得到满足。

“失败”的定义是什么？

在计算 QUERY 和 EXECUTE 成功率时，常见平台错误代码中标记为合作伙伴可采取行动的错误会被视为“失败”。此外，错误和异常页面上发现的错误也是“失败”，但以下情况除外：

失败异常
aboveMaximumLightEffectsDuration	armLevelNeeded	inOffMode
alreadyArmed	bagFull	lockedToRange
alreadyAtMax	belowMinimumLightEffectsDuration	lowBattery
alreadyAtMin	binFull	maxSpeedReached
alreadyClosed	cancelArmingRestricted	minSpeedReached
alreadyDisarmed	deadBattery	notSupported
alreadyDocked	degreesOutOfRange	离线
alreadyInState	deviceJammingDetected	percentOutOfRange
alreadyLocked	deviceNotMounted	rangeTooClose
alreadyOff	deviceNotReady	relinkRequired
alreadyOn	deviceOffline	remoteSetDisabled
alreadyOpen	deviceTurnedOff	safetyShutOff
alreadyPaused	discreteOnlyOpenClose	targetAlreadyReached
alreadyStarted	functionNotSupported	tooManyFailedAttempts
alreadyStopped	inAutoMode	valueOutOfRange
alreadyUnlocked	inEcoMode

查询/执行延迟时间（第 90 百分位）<= 1000 毫秒指标用于衡量所请求操作的等待时间，有助于确保用户不必等待太长时间，例如等待几秒钟让灯关闭。

延迟时间指标

延迟时间是衡量集成对最终用户响应速度的关键指标。该信息中心会跟踪第 90 百分位 (P90) 延迟时间，该指标代表“最慢”用户的体验（例如，P90 为 800 毫秒表示 90% 的请求在 800 毫秒或更短的时间内得到确认）。

Google 会针对状态检查和设备命令以不同的方式测量延迟时间，以确保技术准确性。

1. QUERY Latency（疑问）

此指标用于衡量 Google 请求设备的当前状态时的 Cloud-to-cloud 往返时间。

开始：Google 会向您的执行方式网址调度 action.devices.QUERY 请求。
测量窗口：云端接收、处理完整 HTTP 响应并将其传输回 Google 所用的时间。
结束：Google 收到并确认来自您服务的最终响应载荷。

2. 执行延迟时间（操作）

此指标用于衡量 Google 向设备发送控制请求时，设备确认命令所用的时间。

开始：Google 会向您的执行方式网址调度 action.devices.EXECUTE 请求。
测量窗口：云端接收命令并返回确认响应所用的时间。
结束：Google 收到 SUCCESS、PENDING 或 OFFLINE 状态响应。
技术范围：此指标用于衡量 Google 云与您的云之间的“响应确认”时间。它不会测量物理硬件（例如灯泡）完成物理状态变化所需的时间，因为这通常涉及云到云路径之外的本地网状网络延迟。

延迟时间缩短选项

地理位置路由的架构建议

如果无法实现任播 IP，我们建议采用以下经济实惠的替代方案，以确保用户由最近的区域数据中心提供服务。

全球负载均衡 (GLB)

请使用全球应用负载平衡器（大多数主要云提供商都提供此服务），而不是静态路由。
- 工作原理：您可以在网络边缘配置一个全局入口点 (网址)。负载平衡器会自动检测来自 Google 履单集群的请求的地理位置来源，并将流量路由到最近的区域性运行状况良好的后端。
- 优势：此功能可提供任播的性能，同时大幅降低配置复杂性和成本。
地理位置感知型 DNS (GeoDNS)
- 工作原理：配置 DNS 提供商，以根据 DNS 查询的地理位置将履单网址解析为不同的 IP 地址。
- 实现：确保您的 DNS 提供商针对 Google 的出站流量点进行了优化。当 Google 的区域性履单服务（例如，美国、欧盟或亚洲）解析您的网域时，它们将收到相应特定区域中数据中心的 IP 地址。

应用层优化策略

除了基础架构级路由之外，您还可以在应用层实现以下策略，以缩短请求处理延迟时间。

“Trampoline”代理方法

如果您必须维护主数据中心，请使用区域轻量级代理服务器 (Trampolines) 来处理初始握手。
1. Google 会访问您的全球网址。
2. 区域代理（例如，轻量级 Nginx 或 Lambda 函数）接收请求。
3. 代理通过内部高速骨干网将载荷转发到主数据库。
优势：这可以缩短“TCP 握手”时间，而对于远程请求，这通常是延迟的最大因素。
访问令牌区域提示

在账号关联 (OAuth) 过程中，您的系统可以识别用户的居住地区。

实现：将地区标识符编码到向 Google 签发的 access_token 中。当 Google 发送履单请求时，您的网关可以立即检查令牌并将请求路由到正确的区域集群，而无需进行数据库查找。

系统运行状况 - 合作伙伴到 Google 的指标

保持成功率 >= 99.5% 有助于确保 Google Home 中的设备状态正确无误、设备已添加和移除、自动化操作已触发，以及历史记录事件显示在 Google Home app (GHA) 的“活动”标签页中。

成功率是根据您的云推送状态更新时 Google 返回的 HTTP 响应代码计算得出的。为确保合作伙伴不会因 Google 方面出现的基础设施问题而受到处罚，该指标会从失败次数中排除 Google 内部错误。纳入计算范围的 API 调用可在 HomeGraph API 参考文档中找到。

“成功”的定义是什么？

2xx（成功）：Home Graph 已成功接收并处理状态更新。

“失败”的定义是什么？

4xx（合作伙伴错误）表示失败，并表明从您的云发送的请求存在问题。常见代码包括：

400 无效请求

原因：服务器无法处理请求，因为语法无效。常见原因包括 JSON 格式错误，或针对字符串值使用 null 而非 ""。

解决方案：确保请求正文是有效的 JSON（没有格式错误的结构或字符串字段的 null 值），并验证 agentUserId 是否与 SYNC 响应中的值一致。

404 未找到

原因：在 HomeGraph 中找不到 deviceId 或 agentUserId（尚未同步、已取消关联或 ID 不匹配）。

解决方案：

确保 agentUserId 与 SYNC 响应中提供的值一致。
使用 Home Graph SYNC API 确定 404 Not Found 错误是由 HomeGraph 中缺少设备还是缺少用户造成的。
请务必在设备或账号添加、移除、重命名或更新后触发 requestSync，以确保状态保持最新。
正确处理 DISCONNECT intent 以停止报告过时的设备。收到 DISCONNECT intent 后，云服务应停止使用请求同步和报告状态向 Google 发布更改。

429 资源已用尽

原因：您的集成已超出分配的配额。

解决方案：请参阅信息中心内“第 2a 步：调试配额问题”部分中有关配额管理的说明。您还可以参阅智能家居配额和限制了解详情。

设备健康状况 - 状态准确性

如果状态准确度达到或超过 99.5%，有助于确保用户在查看设备状态或使用“智能管家”等 AI 功能时看到正确的结果。如果状态准确性较低，自动化操作可能无法触发，历史记录条目可能无法及时显示在 GHA 的“活动”标签页中。如需了解详情，请参阅报告状态。

质量信息中心会使用两个不同的指标（总体准确度和最低类型/特征组合）每小时跟踪一次。

1. 准确率组件

该指标源自 Google 可以根据已知的 intent 结果验证所报告状态的“样本”。

2. 信息中心指标（每小时计算一次）

信息中心会根据 1 小时的时间间隔计算准确率。如果某个小时的总样本数 (S_Total) 不足 100 个，则该小时的准确率将设置为 N/A。

视图 1：总体准确率（全球平均值）

这表示您的集成在所有设备类型和特征组合中的总体准确性。它提供整个生态系统健康状况的加权平均值。

计算方式：所有设备的总状态准确率 / 所有设备的总状态总数。

视图 2：最低类型/特征组合

这有助于确定集成中最不可靠的特定类别。这样可以防止高音量的高质量设备隐藏低音量的低质量设备。例如，如果您有大量灯具的状态准确度高于 99.5%，但开关的状态准确度较低，则表明需要改进开关，而平均值可能会掩盖这一问题。

计算方式：所有特征 / 设备组合的状态准确率/状态总数的最小值。

3. 提高设备健康状况和状态的准确性

当存储在 Home Graph 中的状态与实时查询的结果不一致时，就会出现差异。

“缺少字段”错误

DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD 示例

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }

DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD 示例

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }

原因：出现 DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD 或 DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD 错误时，对于同一设备，您的 QUERY 响应和 Report State 请求中的载荷字段集不同。

解决方案：确保两个途径中的数据结构完全相同。如果某个特征包含在 SYNC 中，则其对应的字段必须同时存在于主动报告和被动查询中，并且必须保持一致。

“不准确”错误

DETAILED_ACCURACY_RESULT_INACCURATE 示例

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }

原因：对于 DETAILED_ACCURACY_RESULT_INACCURATE 错误，QUERY 响应中返回的值与最后一个报告状态值之间存在差异。

解决方案：确保在设备状态发生变化时始终触发报告状态，并确保报告状态和 QUERY 始终提供完全相同的最新值和所有必需字段，以保持数据一致性。

DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE 示例

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }

原因：出现 DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE 错误时，合作伙伴已成功执行命令，但未将更新后的设备状态报告给 Google。

解决方案：在执行命令后始终发送“报告状态”更新，以便 Home Graph 接收新的设备状态。

DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED 示例

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }

原因：对于 DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED 错误，尽管 QUERY 结果提供了当前状态，但尚未收到此设备的报告状态（状态为空，报告的时间戳位于纪元）。这表示状态更新未被触发、未能到达 HomeGraph，或者设备未能成功报告其连接或运行状态的转换。

解决方案：确保针对所有状态变化触发并成功发送报告状态。验证后端逻辑是否能正确处理状态更新、向 Google HomeGraph 确认交付成功，并确保设备始终同步其状态，以保持用户界面和自动化引擎的准确性。

提交测试结果

使用 Cloud Monitoring 监控指标

Google Home Vitals（云端） 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Google 到合作伙伴指标

“成功”的定义是什么？

“失败”的定义是什么？

延迟时间指标

延迟时间缩短选项

系统运行状况 - 合作伙伴到 Google 的指标

“成功”的定义是什么？

“失败”的定义是什么？

400 无效请求

404 未找到

429 资源已用尽

设备健康状况 - 状态准确性

1. 准确率组件

2. 信息中心指标（每小时计算一次）

3. 提高设备健康状况和状态的准确性

“缺少字段”错误

DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD 示例

DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD 示例

“不准确”错误

DETAILED_ACCURACY_RESULT_INACCURATE 示例

DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE 示例

DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED 示例

Google Home Vitals（云端）