報表狀態

Report StateCloud-to-cloud

Report State 是一項重要功能，可讓 Google 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

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

    前往 HomeGraph API 頁面
  2. 選取與 smart home 專案 ID 相符的專案。
  3. 按一下「啟用」。

建立服務帳戶金鑰

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

注意：執行這些步驟時，請務必使用正確的 GCP 專案。這是與您的 smart home 專案 ID 相符的專案。

  1. 在 Google Cloud Console 中，前往「Service accounts」(服務帳戶) 頁面。

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

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

  2. 按一下「建立服務帳戶」。

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

  4. 在「Service account ID」欄位中輸入 ID。

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

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

  7. 在「Role」下拉式選單中，依序選取「Service Accounts」 >「Service Account OpenID Connect Identity Token Creator」。

  8. 按一下「繼續」。

  9. 按一下 [完成]。

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

  11. 依序選取「新增金鑰」 >「建立新的金鑰」。

  12. 在「金鑰類型」中，選取「JSON」選項。

  13. 按一下「建立」，系統就會將含有金鑰的 JSON 檔案下載至您的電腦。

如要瞭解建立服務帳戶金鑰的詳細操作說明和相關資訊，請參閱 Google Cloud 控制台說明網站的「建立及刪除服務帳戶金鑰」一文。

呼叫 API

請從下方分頁中選取所需選項：

HTTP

Home Graph 會提供 HTTP 端點

  1. 使用下載的服務帳戶 JSON 檔案建立 JSON Web Token (JWT)。詳情請參閱「 使用服務帳戶進行驗證」。
  2. 使用 oauth2l 取得具有 https://www.googleapis.com/auth/homegraph 範圍的 OAuth 2.0 存取權杖：
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. 使用 agentUserId 建立 JSON 要求。以下是報表狀態和通知的 JSON 要求範例：
    4. {
  "requestId": "123ABC",
  "agentUserId": "user-123",
  "payload": {
    "devices": {
      "states": {
        "light-123": {
          "on": true
        }
      }
    }
  }
}
  4. 將報告狀態和通知 JSON 和權杖結合，並在 HTTP POST 要求中傳送至 Google Home Graph 端點。以下範例說明如何在指令列中使用 curl 提出要求，做為測試：
    5. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

Home Graph 會提供 gRPC 端點

  1. 取得 Home Graph API 的通訊協定緩衝區服務定義。
  2. 按照 gRPC 開發人員說明文件的說明，為支援的語言產生用戶端虛設常式。
  3. 呼叫 ReportStateAndNotification 方法。

Node.js

Google API Node.js 用戶端提供 Home Graph API 的繫結。

  1. 使用應用程式預設憑證初始化 google.homegraph 服務。
  2. 請使用 ReportStateAndNotificationRequest 呼叫 reportStateAndNotification 方法。會傳回含有 ReportStateAndNotificationResponse 的 Promise。
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
          }
        }
      }
    }
  }
});

Java

適用於 Java 的 HomeGraph API 用戶端程式庫提供 Home Graph API 的繫結。

  1. 使用應用程式預設憑證初始化 HomeGraphApiService。
  2. 使用 ReportStateAndNotificationRequest 呼叫 reportStateAndNotification 方法。它會傳回 ReportStateAndNotificationResponse。
  // 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 資訊主頁仍可供使用，但已淘汰，且不再提供支援。

報表狀態資訊主頁

必要條件

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

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

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

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

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

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

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

然後按一下「清單」。

系統會列出你所有裝置。清單填入後，您可以使用「Refresh」按鈕更新裝置狀態。如果裝置狀態有變更，該列會以綠色醒目顯示。

錯誤回應

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

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