通知可讓 Cloud-to-cloud 整合使用 Google Assistant,向使用者傳達與裝置相關的重要事件或變更。您可以實作通知,讓使用者及時收到裝置事件通知,例如有人在門口時,或是回報要求的裝置狀態變更,例如門鎖栓已成功連結或卡住時。
您的 Cloud-to-cloud 整合功能可以向使用者傳送下列類型的通知:
主動通知:在使用者未向裝置提出任何要求 (例如門鈴響鈴) 的情況下,提醒使用者有關 smart home 裝置事件的資訊。
後續回應:確認裝置指令要求是否成功或失敗,例如鎖門時。請針對需要較長時間才能完成的裝置指令使用這些快訊。只有在智慧音箱和智慧螢幕傳送裝置指令要求時,系統才會支援後續回應。
Assistant 會將這些通知以廣播形式傳送給使用者,並透過智慧型喇叭和智慧型螢幕播放。主動式通知預設為關閉。使用者可以透過 Google Home app (GHA) 開啟或關閉所有主動通知。
觸發通知的事件
裝置事件發生時,執行要求會將通知要求傳送給 Google。Cloud-to-cloud 整合功能支援的裝置特徵會決定可用的通知事件類型,以及您可在這些通知中加入的資料。
下列特徵支援主動通知:
特徵 | 活動 |
---|---|
ObjectDetection | 裝置偵測到的物體,例如在門口偵測到已辨識的臉孔。例如:「Alice 和 Bob 在前門外。」 |
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 指出是否已在 smart home 裝置應用程式中啟用通知。如果使用者在您的應用程式中開啟或關閉通知,請傳送
SYNC
要求,通知 Google 裝置變更。 - 當相關裝置事件或狀態變更觸發通知時,請呼叫 Report State
reportStateAndNotification
API 傳送通知要求。如果裝置狀態有所變更,您可以在 Report State 和 Notification 呼叫中同時傳送狀態和通知酬載。
下列章節將詳細說明這些步驟。
指出應用程式是否已啟用通知
使用者可以在 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 中,前往「Create service account key」頁面。
前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。 - 從「Service account」(服務帳戶) 清單中選取「New service account」(新增服務帳戶)。
- 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
- 在「Service account ID」欄位中輸入 ID。
在「Role」清單中,依序選取「Service Accounts」 >「Service Account Token Creator」。
在「金鑰類型」中,選取「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 和通知的 JSON 要求範例: - 將 Report State 和 Notification JSON 與 Google Home Graph 端點的 HTTP POST 要求中的權杖合併。以下範例說明如何在指令列中使用
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
服務。 - 請使用
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', 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
適用於 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 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 和通知的 JSON 要求範例: - 將 Report State 和 Notification JSON 與 Google Home Graph 端點的 HTTP POST 要求中的權杖合併。以下範例說明如何在指令列中使用
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
服務。 - 使用 ReportStateAndNotificationRequest 呼叫
reportStateAndNotification
方法。會傳回含有 ReportStateAndNotificationResponse 的Promise
。
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
適用於 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(); // 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」一文所述,通知可支援記錄事件。這些記錄檔可用於測試及維持 Action 中的通知品質。
以下是 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
)。