報表狀態

Report State 是相當重要的功能，可讓 Home動作會主動回報 使用者的裝置返回 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. 按一下「ENABLE」(啟用)。

建立服務帳戶金鑰

請按照下列操作說明，從 Google Cloud Console 產生服務帳戶金鑰：

1. 前往 Google Cloud Console 的「Create service account key」(建立服務帳戶金鑰) 頁面。

   前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。
2. 在「服務帳戶」清單中，選取 新增服務帳戶：
3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
4. 在「服務帳戶 ID」欄位中輸入 ID。

5. 在「角色」清單中，選取「服務帳戶」> 服務帳戶權杖建立者：

6. 在「Key type」(金鑰類型) 部分，選取「JSON」選項。

7. 點選「建立」。包含金鑰的 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);
}
    

測試報告狀態

為做好認證準備，請務必 Report State。

為此，建議使用 Home Graph 檢視器工具 這是一種獨立的網頁應用程式，不需要下載或部署。

您還是可以使用 Report State 資訊主頁，但 已淘汰且不再受到支援。

報表狀態資訊主頁

必要條件

您必須具備服務帳戶，才能測試動作 金鑰和您的 agentUserId。如果您已經有服務帳戶金鑰 agentUserId請參閱部署 Report State 資訊主頁。

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

取得專案的服務帳戶金鑰和代理程式使用者 ID 後， 下載及部署 Report State 資訊主頁。 下載最新版本後，請按照 已加入 README.MD 檔案。

部署「Report State」資訊主頁後，您就能存取 資訊主頁 (請將 your_project_id 替換成您的 專案 ID)：

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

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

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

然後按一下「清單」。

您的所有裝置都會列在其中。名單填入後，您就可以使用 「重新整理」按鈕更新裝置狀態。如果有裝置狀態改變 該列會以綠色醒目顯示。

錯誤回應

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

• 400 Bad Request - 伺服器無法處理 用戶端所傳送的要求，原因是語法無效。常見原因 包含格式錯誤的 JSON，或使用 null 而非「」字串值。
• 404 Not Found：無法擷取要求的資源 但未來可能會提供使用。通常這表示我們 找不到要求的裝置。這也可能表示使用者帳戶 未連結至 Google，或是我們收到無效的 agentUserId。確保 agentUserId 與您 SYNC 回應，則一切運作正常 處理 DISCONNECT 意圖。