報表狀態

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

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

如果沒有 Report State,指定客廳中由多個供應商發出的燈具,「Ok Google,調亮我的客廳」指令就必須解決傳送至多個雲的 QUERY 意圖,而不只是根據之前回報的內容而查詢目前的亮度值。為提供最佳使用者體驗,Assistant 需要裝置目前的狀態,而不必往返裝置。

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

呼叫 Report State 時,請務必針對特定特徵提供完整狀態資料。Home Graph 會更新個別特徵的狀態,並在 Report State 呼叫時覆寫該特徵的所有資料。舉例來說,如果您要回報 StartStop 特徵的狀態,酬載必須包含 isRunningisPaused 的值。

立即開始

如要實作 Report State,請按照下列步驟操作:

啟用 Google HomeGraph API

  1. 前往 Google Cloud Console 的「HomeGraph API」頁面。

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

建立服務帳戶金鑰

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

注意:執行下列步驟時,請務必使用正確的 GCP 專案。這個專案與您的 smart home 專案 ID 相符。
  1. 前往 Google Cloud Console 的「建立服務帳戶金鑰」頁面。

    前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。
  2. 從「Service account」(服務帳戶) 清單中選取「New service account」(新增服務帳戶)
  3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
  4. 在「Service account ID」(服務帳戶 ID) 欄位中輸入 ID。
  5. 從「角色」清單中,依序選取「服務帳戶」 >「服務帳戶憑證建立者」

  6. 針對「Key type」(金鑰類型),選取「JSON」選項。

  7. 按一下「建立」,內含金鑰的 JSON 檔案會下載至電腦。

呼叫 API

從以下分頁標籤中選取所需選項:

HTTP

Home Graph 提供 HTTP 端點

  1. 使用下載的服務帳戶 JSON 檔案建立 JSON Web Token (JWT)。詳情請參閱「 使用服務帳戶驗證」。
  2. 使用 OAuth2lhttps://www.googleapis.com/auth/homegraph 範圍取得 OAuth 2.0 存取權杖:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. 使用 agentUserId 建立 JSON 要求。以下是報表狀態和通知的 JSON 要求範例:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. 將報表狀態和通知 JSON 與 HTTP POST 要求中的權杖結合至 Google Home Graph 端點。以下範例說明如何在指令列中使用 curl 來進行測試:
  7. 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 方法。它會傳回包含 ReportStateAndNotificationResponsePromise
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);
}
    

測試報告狀態

適合這項工作使用的工具

為做好準備,以利進行認證,請務必測試 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

然後按一下「清單」

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

錯誤回應

呼叫 Report State 時,您可能會收到下列任一錯誤回應。這些回應會採用 HTTP 狀態碼的形式。

  • 400 Bad Request:伺服器因語法無效而無法處理用戶端傳送的要求。常見原因包括 JSON 格式錯誤,或以 null 取代字串值。
  • 404 Not Found:找不到要求的資源,但日後可能會提供。通常這表示我們找不到要求的裝置。也可能表示使用者帳戶未與 Google 建立連結,或我們收到無效的 agentUserId。確認 agentUserIdSYNC 回應中提供的值相符,且您妥善處理 DISCONNECT 意圖。