Report State是一項重要功能,可讓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
-
在 Google Cloud Console 中,前往「HomeGraph API」頁面。
前往 HomeGraph API 頁面 - 選取與「smart home」專案 ID 相符的專案。
- 按一下「啟用」。
建立服務帳戶金鑰
請按照下列操作說明,從 Google Cloud Console 產生服務帳戶金鑰:
-
在 Google Cloud Console 中,前往「建立服務帳戶金鑰」頁面。
前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。 - 從「服務帳戶」清單中,選取「新增服務帳戶」。
- 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
- 在「Service account ID」(服務帳戶 ID) 欄位中輸入 ID。
在「角色」清單中,依序選取「服務帳戶」 >「服務帳戶權杖建立者」。
針對「Key type」(金鑰類型),選取 [JSON] 選項。
- 按一下「Create」(建立)。含有金鑰的 JSON 檔案會下載到電腦上。
呼叫 API
請從下列分頁選取選項:
HTTP
Home Graph 提供 HTTP 端點
- 使用下載的服務帳戶 JSON 檔案,建立 JSON Web Token (JWT)。詳情請參閱「 使用服務帳戶進行驗證」。
- 使用 OAuth2l 取得含有
https://www.googleapis.com/auth/homegraph
範圍的 OAuth 2.0 存取權杖: - 使用
agentUserId
建立 JSON 要求。以下是報表狀態和通知的 JSON 要求範例: - 結合報表狀態與通知 JSON 以及 HTTP POST 要求中的權杖與 Google Home Graph 端點。以下範例說明如何在測試中使用
curl
透過指令列提出要求:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
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 端點
- 取得 Home Graph API 的通訊協定緩衝區服務定義。
- 按照 gRPC 開發人員說明文件產生其中一種支援的語言的用戶端虛設常式。
- 呼叫 ReportStateAndNotification 方法。
Node.js
Google API Node.js 用戶端提供 Home Graph API 的繫結,
- 使用應用程式預設憑證,初始化
google.homegraph
服務。 - 使用 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 的繫結項目。
- 使用應用程式預設憑證,初始化
HomeGraphApiService
。 - 使用
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
。確認agentUserId
與 SYNC 回應中提供的值相符,您也已正確處理 DISCONNECT 意圖。