Cloud-to-cloud整合功能可透過通知Google Assistant,向使用者傳達重要的裝置相關事件或變更。您可以實作通知,在發生即時裝置事件時提醒使用者,例如有人在門口,或是回報所要求的裝置狀態變更,例如門鎖閂鎖已成功鎖上或卡住。
Cloud-to-cloud 整合功能可傳送下列類型的通知給使用者:
主動通知:在使用者未要求裝置執行任何動作時,提醒使用者發生smart home裝置事件,例如門鈴響起。
後續回應:確認裝置指令要求成功或失敗,例如鎖門時。如果裝置指令需要一段時間才能完成,只有透過智慧音箱和智慧螢幕傳送裝置指令要求時,系統才會提供後續回覆。
Assistant 會在智慧音箱和智慧螢幕上向使用者發送這些通知。主動式通知預設為關閉。使用者可以透過Google Home app (GHA)開啟或關閉所有主動通知。
觸發通知的事件
裝置發生事件時,執行要求會將通知要求傳送給 Google。Cloud-to-cloud整合支援的裝置特徵會決定可用的通知事件類型,以及您可以在這些通知中加入的資料。
下列特徵支援主動通知:
特徵 | 事件 |
---|---|
ObjectDetection | 裝置偵測到的物體,例如在門口偵測到已辨識的臉孔。例如:「Alice and Bob are at the front door.」(愛麗絲和鮑伯在前門外)。 |
RunCycle | 裝置完成一個週期。例如:「洗衣機行程已完成。」 |
SensorState | 裝置偵測到支援的感應器狀態。例如: 「煙霧偵測器偵測到煙霧。」 |
下列特徵支援後續回覆:
特徵 | 事件 |
---|---|
LockUnlock | 執行 action.devices.commands.LockUnlock 裝置指令後,完成狀態和狀態變更。例如:「前門已上鎖」或「前門卡住了」。 |
NetworkControl | 執行 action.devices.commands.TestNetworkSpeed 裝置指令後,完成狀態和狀態變更。例如:「已完成網路速度測試。辦公室路由器的下載速度目前為 80.2 Kbps,上傳速度為 9.3 Kbps。"
|
OpenClose | 執行 action.devices.commands.OpenClose 裝置指令後,完成狀態和狀態變更。例如:「前門已開啟」或「前門無法開啟」。 |
所有裝置類型都支援適用特徵的通知。
為雲端對雲端整合功能建立通知
在下列階段,為 Cloud-to-cloud 整合服務新增通知:
- 向 Google 指出是否已透過裝置應用程式啟用通知。如果使用者在應用程式中開啟或關閉通知,請傳送
SYNC
要求,將裝置變更通知 Google。smart home - 發生相關裝置事件或狀態變更,觸發通知時,請呼叫 Report State
reportStateAndNotification
API 傳送通知要求。如果裝置狀態已變更,您可以在 Report State 和通知呼叫中,同時傳送狀態和通知酬載。
下列章節將詳細說明上述步驟。
指出應用程式是否已啟用通知
使用者可以在 GHA 中啟用這項功能,選擇是否要接收主動通知。在裝置的應用程式中,您也可以選擇讓使用者從裝置明確切換通知,例如從應用程式設定。smart home
請發出 Request SYNC 呼叫,向 Google 指出裝置已啟用通知,並更新裝置資料。每當使用者在應用程式中變更這項設定時,您都應傳送類似這樣的 SYNC
要求。
在 SYNC
回覆中,傳送下列其中一項更新:
- 如果使用者在裝置應用程式中明確開啟通知,或您未提供切換選項,請將
devices.notificationSupportedByAgent
屬性設為true
。 - 如果使用者在裝置應用程式中明確關閉通知,請將
devices.notificationSupportedByAgent
屬性設為false
。
以下程式碼片段顯示如何設定 SYNC 回應的範例:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
將通知要求傳送給 Google
如要在 Assistant 上觸發通知,履單程序會透過 Report State 和 Notification API 呼叫,將通知酬載傳送至 Google Home Graph。
啟用 Google HomeGraph API
-
在 Google Cloud Console 中,前往 HomeGraph API 頁面。
前往 HomeGraph API 頁面 - 選取與 smart home 專案 ID 相符的專案。
- 按一下「啟用」。
建立服務帳戶金鑰
請按照下列操作說明,從 Google Cloud Console 產生服務帳戶金鑰:
-
前往 Google Cloud Console 的「Service accounts」(服務帳戶) 頁面。
前往「Service Accounts」(服務帳戶) 頁面。系統可能會要求您選取專案,才會前往「服務帳戶」頁面。
按一下「建立服務帳戶」
。在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
在「Service account ID」(服務帳戶 ID) 欄位中輸入 ID。
在「服務帳戶說明」欄位中輸入說明。
按一下 [建立並繼續]。
在「Role」(角色) 下拉式選單中,選取「Service Accounts」(服務帳戶) >「Service Account OpenID Connect Identity Token Creator」(服務帳戶 OpenID Connect 身分識別權杖建立者)。
按一下「繼續」。
按一下 [完成]。
從服務帳戶清單中選取您剛建立的服務帳戶,然後從「動作」
選單中選取「管理金鑰」。依序選取「新增金鑰」 >「建立新的金鑰」。
在「金鑰類型」中,選取「JSON」選項。
按一下「建立」,系統就會將含有金鑰的 JSON 檔案下載至您的電腦。
傳送通知
使用 devices.reportStateAndNotification
API 呼叫通知要求。JSON 要求必須包含 eventId
,這是平台為觸發通知的事件產生的專屬 ID。eventId
應為隨機 ID,每次傳送通知要求時都不同。
在 API 呼叫中傳遞的 notifications
物件中,加入 priority
值,定義通知的顯示方式。視裝置特徵而定,您的 notifications
物件可能包含不同欄位。
請按照下列任一方式設定酬載並呼叫 API:
傳送主動式通知酬載
如要呼叫 API,請從下列任一分頁選取選項:
HTTP
Home Graph API 提供 HTTP 端點
- 使用下載的服務帳戶 JSON 檔案建立 JSON Web Token (JWT)。詳情請參閱「 使用服務帳戶進行驗證」。
- 使用 oauth2l 取得具有
https://www.googleapis.com/auth/homegraph
範圍的 OAuth 2.0 存取權杖: - 使用
agentUserId
建立 JSON 要求。 以下是 Report State 和 Notification 的 JSON 要求範例: - 在 HTTP POST 要求中,將 Report State、Notification JSON 和權杖一併傳送至 Google Home Graph 端點。以下範例說明如何使用
curl
在指令列中提出要求,做為測試:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "ObjectDetection": { "priority": 0, "detectionTimestamp": 1534875126750, "objects": { "named": [ "Alice" ], "unclassified": 2 } } } } } } }
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 API 提供 gRPC 端點
- 取得 Home Graph API 的通訊協定緩衝區服務定義。
- 請按照 gRPC 開發人員說明文件,為支援的語言 產生用戶端虛設常式。
- 呼叫 ReportStateAndNotification 方法。
Node.js
Google API Node.js 用戶端提供 Home Graph API 的繫結。
- 使用
應用程式預設憑證,初始化
google.homegraph
服務。 - 呼叫
reportStateAndNotification
方法,並提供 ReportStateAndNotificationRequest。系統會傳回Promise
,其中包含 ReportStateAndNotificationResponse。
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', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { ObjectDetection: { priority: 0, detectionTimestamp: 1534875126750, objects: { named: ['Alice'], unclassified: 2 } } } } } } } });
Java
HomeGraph API Java 用戶端程式庫提供 Home Graph API 的繫結。
- 使用應用程式預設憑證初始化
HomeGraphApiService
。 - 呼叫
reportStateAndNotification
方法,並傳遞ReportStateAndNotificationRequest
。 並傳回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 notification payload. Map<?, ?> notifications = Map.of( "ObjectDetection", Map.of( "priority", 0, "detectionTimestamp", 1534875126, "objects", Map.of("named", List.of("Alice"), "unclassifed", 2))); // Send notification. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications)))); homegraphService.devices().reportStateAndNotification(request);
傳送後續回覆酬載
後續回應的酬載包含要求狀態、事件失敗的錯誤代碼 (如適用),以及在 EXECUTE
意圖要求期間提供的有效 followUpToken
。followUpToken
必須在五分鐘內使用,才能維持有效性,並將回應與原始要求正確建立關聯。
以下程式碼片段範例顯示含有 followUpToken
欄位的 EXECUTE
要求酬載。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123", }], "execution": [{ "command": "action.devices.commands.TestNetworkSpeed", "params": { "testDownloadSpeed": true, "testUploadSpeed": false, "followUpToken": "PLACEHOLDER" } }] }] } }] };
Google 會使用 followUpToken
,只在使用者最初互動的裝置上輸出通知,不會向使用者的所有裝置廣播。
如要呼叫 API,請從下列任一分頁選取選項:
HTTP
Home Graph API 提供 HTTP 端點
- 使用下載的服務帳戶 JSON 檔案建立 JSON Web Token (JWT)。詳情請參閱「 使用服務帳戶進行驗證」。
- 使用 oauth2l 取得具有
https://www.googleapis.com/auth/homegraph
範圍的 OAuth 2.0 存取權杖: - 使用
agentUserId
建立 JSON 要求。 以下是 Report State 和 Notification 的 JSON 要求範例: - 在 HTTP POST 要求中,將 Report State、Notification JSON 和權杖一併傳送至 Google Home Graph 端點。以下範例說明如何使用
curl
在指令列中提出要求,做為測試:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "NetworkControl": { "priority": 0, "followUpResponse": { "status": "SUCCESS", "followUpToken": "PLACEHOLDER", "networkDownloadSpeedMbps": 23.3, "networkUploadSpeedMbps": 10.2 } } } } } } }
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 API 提供 gRPC 端點
- 取得 Home Graph API 的通訊協定緩衝區服務定義。
- 請按照 gRPC 開發人員說明文件,為支援的語言產生用戶端虛設常式。
- 呼叫 ReportStateAndNotification 方法。
Node.js
Google API Node.js 用戶端提供 Home Graph API 的繫結。
- 使用
應用程式預設憑證,初始化
google.homegraph
服務。 - 呼叫
reportStateAndNotification
方法,並傳遞 ReportStateAndNotificationRequest。 系統會傳回Promise
,其中包含 ReportStateAndNotificationResponse。
const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken; 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', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { NetworkControl: { priority: 0, followUpResponse: { status: 'SUCCESS', followUpToken, networkDownloadSpeedMbps: 23.3, networkUploadSpeedMbps: 10.2, } } } } } } } });
Java
HomeGraph API Java 用戶端程式庫提供 Home Graph API 的繫結。
- 使用
應用程式預設憑證初始化
HomeGraphApiService
- 呼叫
reportStateAndNotification
方法,並傳遞ReportStateAndNotificationRequest
。傳回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(); // Extract follow-up token. ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0]; String followUpToken = (String) executeInputs .getPayload() .getCommands()[0] .getExecution()[0] .getParams() .get("followUpToken"); // Build device follow-up response payload. Map<?, ?> followUpResponse = Map.of( "NetworkControl", Map.of( "priority", 0, "followUpResponse", Map.of( "status", "SUCCESS", "followUpToken", followUpToken, "networkDownloadSpeedMbps", 23.3, "networkUploadSpeedMbps", 10.2))); // Send follow-up response. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse)))); homegraphService.devices().reportStateAndNotification(request);
記錄
通知支援事件記錄,詳情請參閱「雲端對雲端服務的 Cloud Logging」。這些記錄有助於測試及維護動作中的通知品質。
以下是 notificationLog
項目結構定義:
屬性 | 說明 |
---|---|
requestId |
通知要求 ID。 |
structName |
通知結構體的名稱,例如「ObjectDetection」。 |
status |
指出通知的狀態。 |
status
欄位包含各種狀態,可能指出通知酬載中的錯誤。其中部分功能可能僅適用於尚未發布至正式版的動作。
例如:
狀態 | 說明 |
---|---|
EVENT_ID_MISSING |
表示缺少必填的「eventId 」欄位。
|
PRIORITY_MISSING |
表示缺少 priority 欄位。
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
表示通知裝置在 SYNC 中提供的 notificationSupportedByAgent 屬性為 false。 |
NOTIFICATION_ENABLED_BY_USER_FALSE |
表示使用者尚未在 GHA 中,對要傳送通知的裝置啟用通知功能。這項狀態僅適用於尚未發布至正式環境的整合。 |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
表示使用者尚未將通知裝置指派給住家/結構體。這項狀態僅適用於尚未發布至正式環境的整合。 |
除了適用於所有通知的一般狀態外,status
欄位也可能包含適用於特徵的狀態 (例如 OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
)。