報表狀態

Report State 是一項重要功能，可讓 Google Home 動作主動向 Google Home Graph 回報使用者裝置的最新狀態，而不是等待 QUERY 意圖。

Report State 會向 Google 回報使用者裝置的狀態，並附上與裝置相關聯的指定 agentUserId (在原始 SYNC 要求中傳送)。當 Google Assistant 想要執行需要瞭解裝置目前狀態的操作時，只要在 Home Graph 中查詢狀態資訊即可，不必在發出 EXECUTE 意圖前，先向各種第三方雲端發出 QUERY 意圖。

如果沒有 Report State，假設客廳有多個供應商提供的燈具，當使用者下達「Ok Google，調亮客廳」指令時，系統必須解析傳送至多個雲端的多個 QUERY 意圖，而不是直接根據先前回報的資訊查詢目前的亮度值。為提供最佳使用者體驗，Assistant 必須具備裝置的目前狀態，而不必往返裝置。

在裝置初始 SYNC 之後，平台會傳送 QUERY 意圖，收集裝置狀態以填入 Home Graph。之後，Home Graph 只會儲存透過 Report State 傳送的狀態。

呼叫 Report State 時，請務必提供特定特性的完整狀態資料。Home Graph 會根據各項特質更新狀態，並在發出 Report State 呼叫時覆寫該特質的所有資料。舉例來說，如果您要回報 StartStop 特性的狀態，酬載必須同時包含 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 的「Service accounts」(服務帳戶) 頁面。

   前往「Service Accounts」(服務帳戶) 頁面。

   您可能需要先選取專案，才能前往「服務帳戶」頁面。

2. 按一下「add Create service account」(建立服務帳戶)。

3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。

4. 在「Service account ID」(服務帳戶 ID) 欄位中輸入 ID。

5. 在「Service account description」(服務帳戶說明) 欄位中輸入說明。

6. 按一下 [建立並繼續]。

7. 在「Role」(角色) 下拉式選單中，依序選取「Service Accounts」(服務帳戶) >「Service Account OpenID Connect Identity Token Creator」(服務帳戶 OpenID Connect 身分識別權杖建立者)。

8. 按一下「繼續」。

9. 按一下「完成」。

10. 從服務帳戶清單中選取您剛建立的服務帳戶，然後從 more_vert「Actions」(動作) 選單中選取「Manage keys」(管理金鑰)。

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 檢視器工具，這是一款獨立的網頁應用程式，不需下載或部署。

Report State 資訊主頁仍可使用，但已淘汰，不再提供支援。

Report State 資訊主頁

必要條件

您必須先取得服務帳戶金鑰和 agentUserId，才能測試 Cloud-to-cloud 整合。如果您已有服務帳戶金鑰和 agentUserId，請參閱「部署 Report State 資訊主頁」。

部署 Report State 資訊主頁

取得專案的服務帳戶金鑰和代理使用者 ID 後，請從 Report State 資訊主頁下載並部署最新版本。下載最新版本後，請按照隨附 README.MD 檔案中的指示操作。

部署 Report State 資訊主頁後，請透過下列網址存取資訊主頁 (將 your_project_id 替換為您的專案 ID)：

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

在資訊主頁中執行下列操作：

• 選擇帳戶金鑰檔案
• 新增 agentUserId

然後按一下「清單」。

系統會列出你的所有裝置。清單填入後，您可以使用「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 Discrepancy Log 欄位定義

錯誤回應

呼叫 Report State 時，您可能會收到下列其中一項錯誤回應。這些回應會以 HTTP 狀態碼的形式呈現。

400 Bad Request

由於語法無效，伺服器無法處理用戶端傳送的要求。常見原因包括 JSON 格式錯誤，或使用 null 而非 "" 做為字串值。

找不到 404

找不到要求的資源，但日後可能可以使用。這通常表示我們找不到要求的裝置。也可能表示使用者帳戶未連結至 Google，或我們收到無效的 agentUserId。請確認 agentUserId 與 SYNC 回應中提供的值相符，且您已妥善處理 DISCONNECT 意圖。

當 ReportState 呼叫失敗並顯示 404 NOT_FOUND 錯誤時，表示雲端與 Home Graph 之間的同步處理不一致。如果裝置從 Home Graph 移除，或使用者取消連結帳戶，就可能發生這種情況。

如要處理 Report State 的 404 錯誤，請按照下列程序操作：

1. 檢查使用者帳戶狀態：針對傳回 404 錯誤的 agentUserId，呼叫 devices.sync。這有助於判斷錯誤是發生在整個使用者帳戶，還是特定裝置。
   • 如果 SYNC 傳回 404 錯誤，表示使用者帳戶已與 Google 解除連結。停止傳送 Report State 和 Request Sync，不再回報這位使用者的裝置狀態和要求同步。
   • 如果 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": {},
        }
      }
    }