報表狀態

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

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

如果沒有 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。

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

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

5. 在「服務帳戶說明」欄位中輸入說明。

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

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

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);
}
    

測試報告狀態

如要讓 Cloud-to-cloud 整合項目通過認證，請務必測試 Report State。

為此，我們建議使用 Home Graph 檢視器工具，這項獨立的網路應用程式不需要下載或部署。

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

報表狀態資訊主頁

必要條件

如要測試 Cloud-to-cloud 整合，您需要服務帳戶金鑰和 agentUserId。如果您已有服務帳戶金鑰和 agentUserId，請參閱部署 Report State 資訊主頁。

部署「回報狀態」資訊主頁

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

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

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

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

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

然後按一下「清單」。

畫面會列出所有裝置。清單填入資料後，您可以使用「重新整理」按鈕更新裝置狀態。如果裝置狀態有變更，該列會以綠色醒目顯示。

回報州別差異

查詢式報表狀態準確度會評估裝置的最新報表狀態，與使用者查詢時的裝置狀態是否相符。這個值應為 99.5%。

錯誤回應

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

• 400 Bad Request：伺服器無法處理用戶端傳送的要求，因為語法無效。常見原因包括 JSON 格式錯誤，或是字串值使用 null 而非「""」。
• 404 Not Found - 找不到要求的資源，但日後可能提供。這通常表示我們找不到要求的裝置。這也可能表示使用者帳戶未連結至 Google，或是我們收到無效的 agentUserId。確認 agentUserId 與 SYNC 回應中提供的值相符，且您正確處理 DISCONNECT 意圖。

線上和離線狀態回報

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