通知可讓 smart home 動作使用 Google Assistant 向使用者傳達重要的裝置相關事件或變化。您可以實作通知來提醒使用者及時接收裝置事件 (例如有人來訪時),或是回報要求的裝置狀態變更,例如門鎖門栓成功互動或卡住。
您的 smart home 動作可以傳送以下類型的通知給使用者:
主動通知:在使用者未事先對裝置提出任何要求 (例如門鈴響起) 的情況下,通知使用者 smart home 裝置事件。
後續回應:確認裝置指令要求已成功或失敗,例如鎖門時。因此,請針對需要一段時間才能完成的裝置指令使用這些快訊。只有透過智慧音箱和智慧螢幕傳送裝置指令要求時,系統才支援後續追蹤回應。
隨著智慧音箱和智慧螢幕的公告,Assistant 會向使用者提供這些通知。根據預設,主動通知會關閉。使用者可以開啟或關閉來自 Google Home app (GHA) 的所有主動通知。
觸發通知的事件
發生裝置事件時,您的動作執行要求會向 Google 傳送通知要求。smart home 動作支援的裝置特徵會決定可用的通知事件類型,以及可納入這些通知的資料。
以下特徵支援主動通知:
特徵 | 活動 |
---|---|
ObjectDetection | 裝置偵測到的物體,例如門口偵測到的臉孔。例如:「小艾和小明在前門外」。 |
RunCycle | 裝置完成循環。例如:「洗衣機週期已完成」。 |
SensorState | 裝置偵測到支援的感應器狀態。例如:「煙霧偵測器偵測到煙霧」。」 |
TemperatureControl | 裝置達到溫度設定點。例如:「烤箱已預熱至 350 度。」 |
ArmDisarm | 系統進入鬧鐘前狀態時,會啟動進入倒數計時,並由開門打開。 |
CameraStream | 在裝置偵測到物體或動作後,連結至攝影機的即時影像。 |
MotionDetection | 「在 2020 年 7 月 1 日中午 12 點偵測到動作。」 |
下列特徵支援後續回覆:
特徵 | 活動 |
---|---|
ArmDisarm | 執行 action.devices.commands.ArmDisarm 裝置指令後,完成狀態和狀態會改變。例如:「保全系統已啟動。」 |
LockUnlock | 執行 action.devices.commands.LockUnlock 裝置指令後,完成狀態和狀態會改變。例如:「前門已上鎖」或「前門卡住了」。 |
NetworkControl | 執行 action.devices.commands.TestNetworkSpeed 裝置指令後,完成狀態和狀態會改變。例如:"網路速度測試已完成。辦公室路由器目前的下載速度為 80.2 Kbps,上傳速度為 9.3 Kbps。"
|
OpenClose | 執行 action.devices.commands.OpenClose 裝置指令後,完成狀態和狀態會改變。例如:「前門已開啟」或「無法打開前門」。 |
StartStop | 執行 action.devices.commands.StartStop 裝置指令後,完成狀態和狀態會改變。例如:「已啟動吸塵器」。 |
所有裝置類型都支援適用特徵的通知。
建立智慧型住宅動作的通知
請在下列階段為「smart home」動作新增通知:
- 透過 smart home 裝置應用程式是否啟用通知功能,向 Google 說明。如果使用者在應用程式中開啟或關閉通知功能,請傳送
SYNC
要求來通知 Google 裝置變更。 - 發生相關裝置事件或狀態變更而觸發通知時,請呼叫 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 相符的專案。
- 按一下「ENABLE」(啟用)。
建立服務帳戶金鑰
請按照下列操作說明,從 Google Cloud Console 產生服務帳戶金鑰:
-
前往 Google Cloud Console 的「Create service account key」(建立服務帳戶金鑰) 頁面。
前往「Create Service Account Key」(建立服務帳戶金鑰) 頁面。 - 從「服務帳戶」清單中,選取「新增服務帳戶」。
- 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。
- 在「服務帳戶 ID」欄位中輸入 ID。
在「角色」清單中,選取「服務帳戶」 >「服務帳戶權杖建立者」。
在「Key type」(金鑰類型) 部分,選取「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 和通知 JSON 中的權杖與 HTTP POST 要求中的權杖結合至 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
服務。 - 使用 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 和通知 JSON 中的權杖與 HTTP POST 要求中的權杖結合至 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
服務。 - 使用 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);
Logging
通知支援事件記錄,詳情請參閱「透過 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
)。