报告状态

Report State 是一项重要功能，可让 Google Home Action 主动向 Google Home Graph 报告 用户设备的最新状态，而无需等待 QUERY intent。

Report State 会向 Google 报告与指定 agentUserId（在原始 SYNC 请求中发送）相关联的用户设备的状态 。当 Google Assistant 要执行一项需要了解设备当前状态的操作时，它可以直接在 Home Graph 中查询状态信息，而无需先向各种不同的第三方云发出 QUERY intent，然后再发出 EXECUTE intent。

如果不用 Report State，当客厅中有来自多个提供方的光线时，命令 Ok Google, brighten my living room 需要解析发送到多个云的多个 QUERY intent，而不是根据之前报告的内容直接查询当前的亮度值。为了提供最佳用户体验， Assistant需要获取设备的当前状态， 而无需数据往返设备。

在设备进行初始 SYNC 后，平台会发送一个 QUERY intent 用于收集设备的状态以填充 Home Graph。 此后，Home Graph 仅存储通过 Report State 发送的状态。

调用Report State时，请务必提供完整 状态数据，以获取给定特征。Home Graph 会按 特征更新状态，并在调用 Report State时覆盖相应特征的所有数据。例如，如果您要报告 状态，则载荷 需要同时包含 isRunning 和 isPaused 两者的值。

开始使用

如需实现 Report State，请按以下步骤操作：

• 启用 Google HomeGraph API
• 创建服务账号密钥
• 调用该 API

启用 Google HomeGraph API

1. 在 Google Cloud Console 中，前往 HomeGraph API 页面。

   转到 HomeGraph API 页面
2. 请选择与您的 smart home 项目 ID 相匹配的项目。
3. 点击启用 。

创建服务账号密钥

按照以下说明从 Google Cloud Console 生成服务账号密钥：

1. 在 Google Cloud Console 中，前往 服务账号 页面。

   前往“服务账号”页面。

   您可能需要选择相应项目，然后才能访问“服务账号”页面。

2. 点击 add创建服务账号 。

3. 在服务账号名称 字段中，输入一个名称。

4. 在服务账号 ID 字段中，输入一个 ID。

5. 在服务账号说明 字段中，输入说明。

6. 点击创建并继续 。

7. 从角色 下拉菜单中，依次选择服务账号 > Service Account OpenID Connect Identity Token Creator。

8. 点击继续 。

9. 点击完成 。

10. 在服务账号列表中，选择您刚刚创建的服务账号，然后从 more_vert 操作 菜单中选择管理密钥 。

11. 依次选择添加密钥 > 创建新密钥 。

12. 对于密钥类型，选择JSON选项。

13. 点击创建。包含密钥的 JSON 文件就会下载到计算机。

调用该 API

从下面的标签页中选择一个选项：

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});
    

  // Get Application Default credentials.
  GoogleCredentials credentials =
      GoogleCredentials.getApplicationDefault()
          .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

  // Create Home Graph service client.
  HomeGraphService homegraphService =
      new HomeGraphService.Builder(
              GoogleNetHttpTransport.newTrustedTransport(),
              GsonFactory.getDefaultInstance(),
              new HttpCredentialsAdapter(credentials))
          .setApplicationName("HomeGraphExample/1.0")
          .build();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request).execute();
}
    

测试报告状态

为了让您的 Cloud-to-cloud 集成为 认证做好准备，请务必测试 Report State。

为此，我们建议使用 Home Graph Viewer 工具， 这是一款无需下载或部署的独立 Web 应用。

Report State 信息中心仍可用，但已被 弃用，不再受支持。

报告状态信息中心

前提条件

您需要服务账号密钥和 agentUserId 才能测试您的 Cloud-to-cloud 集成。如果您已拥有您的 服务账号密钥和 agentUserId，请参阅部署 Report State信息中心。

部署报告状态信息中心

获取项目的服务账号密钥和代理用户 ID 后， 从 Report State 信息中心下载并部署最新版本。下载最新版本后，请按照随附的 README.MD 文件中的说明进行操作。

部署 Report State 信息中心后，可以通过以下网址访问 信息中心（将 your_project_id 替换为您的 项目 ID）：

http://<your-project-id>.appspot.com

在该信息中心内，执行以下操作：

• 选择你的账号密钥文件
• 添加你的 agentUserId

然后，点击 List。

系统会列出你的所有设备。系统填充列表后，你可以使用 Refresh 按钮更新设备状态。如果设备状态发生更改，则该行会以绿色突出显示。

报告状态差异

基于查询的报告状态准确率衡量的是，当用户查询设备时，设备的最新报告状态与设备状态的匹配程度。此值预计为 99.5%。如需详细了解项目的 报告状态准确率 的当前状态，请参阅 设备健康状况 - 状态准确率。您还可以通过 Logs Explorer查看报告状态差异日志的详细信息。

以下是报告状态差异日志的示例：

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

报告状态差异日志字段定义

错误响应

调用 Report State时，您可能会收到以下某个错误响应。这些响应以 HTTP 状态代码的形式出现。

400 无效请求

由于 语法无效，服务器无法处理客户端发送的请求。常见原因包括 JSON 格式错误，或针对字符串值使用 null 而非 ""。

404 未找到

未找到请求的资源，但未来可能提供这些资源。 通常情况下，这意味着我们无法找到请求的设备。这也可能意味着该用户账号未与 Google 关联，或我们收到的 agentUserId 无效。请确保 agentUserId 与您的 SYNC 响应中提供的值一致，并且您正确处理了 DISCONNECT intent。

如果 ReportState 调用因 404 NOT_FOUND 错误而失败，则表示您的云与 Home Graph 之间存在 同步不匹配。 如果设备从 Home Graph 中移除，或者 用户为其账号解除关联，则可能会发生这种情况。

如需处理来自报告状态的 404 错误，请使用以下过程：

1. 检查用户账号状态：针对返回 404 错误的 agentUserId 调用 devices.sync 。这有助于确定错误是针对整个用户账号还是特定设备。
   • 如果 SYNC 返回 404 错误，则表示用户账号不再与 Google 关联。停止为此用户的设备发送报告状态和请求同步。
   • 如果 SYNC 返回 200 OK，则表示用户账号仍处于关联状态，这意味着 404 错误是特定于设备的。
2. 协调设备列表：如果 SYNC 返回 200 OK，您需要 确定 Google 不再知道哪些设备。我们建议您将 Google 为用户提供的设备列表与您的设备数据库进行比较，并确定您的系统中 Google 列表中没有的设备。如果设备应同步到 Google，但尚未 与 Google 共享，请使用 SYNC 确保设备与 Google 同步。如果设备应与 Google 解除关联，请停止报告该特定设备的状态，并继续报告该 agentUserId 下的其他有效设备的状态。

在线和离线状态报告

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }