Thông báo cho phép Hành động smart home của bạn sử dụng Google Assistant để thông báo cho người dùng về các thay đổi hoặc sự kiện quan trọng liên quan đến thiết bị. Bạn có thể triển khai thông báo để người dùng biết kịp thời các sự kiện của thiết bị, chẳng hạn như khi ai đó đứng trước cửa, hoặc báo cáo về sự thay đổi trạng thái của thiết bị được yêu cầu, chẳng hạn như khi bu lông khoá cửa đã được gắn thành công hoặc bị kẹt.
Hành động smart home của bạn có thể gửi các loại thông báo sau cho người dùng:
Thông báo chủ động: Thông báo cho người dùng về một sự kiện trên thiết bị smart home mà không có yêu cầu nào trước đó của người dùng về thiết bị, chẳng hạn như chuông cửa.
Phản hồi tiếp theo: Xác nhận rằng một yêu cầu lệnh của thiết bị đã thành công hoặc không thành công, ví dụ như khi khoá cửa. Sử dụng các cảnh báo này cho các lệnh trên thiết bị cần có thời gian để hoàn thành. Các phản hồi tiếp theo chỉ được hỗ trợ khi yêu cầu lệnh của thiết bị được gửi từ loa thông minh và màn hình thông minh.
Assistant cung cấp các thông báo này cho người dùng dưới dạng thông báo trên loa thông minh và màn hình thông minh. Thông báo chủ động sẽ bị tắt theo mặc định. Người dùng có thể bật hoặc tắt mọi thông báo chủ động từ Google Home app (GHA).
Sự kiện kích hoạt thông báo
Khi sự kiện trên thiết bị xảy ra, quá trình thực hiện Hành động của bạn sẽ gửi yêu cầu thông báo cho Google. Các đặc điểm thiết bị mà Hành động smart home của bạn hỗ trợ xác định các loại sự kiện thông báo có sẵn và dữ liệu bạn có thể đưa vào các thông báo đó.
Những đặc điểm sau đây hỗ trợ thông báo chủ động:
Đặc điểm tính cách | Sự kiện |
---|---|
Đối tượng phát hiện | Các vật thể mà thiết bị phát hiện được, chẳng hạn như khi phát hiện thấy khuôn mặt được nhận dạng tại cửa. Ví dụ: "Alice và Bob đang ở cửa trước." |
RunCycle | Thiết bị hoàn thành một chu kỳ. Ví dụ: "Chu kỳ của máy giặt đã hoàn tất". |
Trạng thái cảm biến | Thiết bị phát hiện thấy trạng thái cảm biến được hỗ trợ. Ví dụ: "Đầu báo khói phát hiện thấy khói". |
Kiểm soát nhiệt độ | Thiết bị đã đạt đến điểm đặt nhiệt độ. Ví dụ: "Lò nướng đã được làm nóng trước đến 350 độ." |
ArmDisarm | Hệ thống chuyển sang trạng thái báo thức trước với bộ đếm ngược thời gian, được kích hoạt bởi một cửa mở. |
Dòng dữ liệu máy ảnh | Đường liên kết đến sự kiện phát trực tiếp của camera sau khi thiết bị phát hiện thấy một đối tượng hoặc chuyển động. |
Phát hiện chuyển động | "Phát hiện thấy chuyển động lúc 12 giờ trưa ngày 1 tháng 7 năm 2020." |
Những đặc điểm hỗ trợ các phản hồi tiếp theo:
Đặc điểm tính cách | Sự kiện |
---|---|
ArmDisarm | Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.ArmDisarm của thiết bị. Ví dụ:
"Hệ thống an ninh đã được bật."
|
Khóa mở khóa | Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.LockUnlock của thiết bị. Ví dụ: "Cửa trước đã khoá" hoặc "Cửa trước bị kẹt."
|
NetworkControl | Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.TestNetworkSpeed của thiết bị. Ví dụ: "Quá trình kiểm tra tốc độ mạng của bạn đã hoàn tất. Tốc độ tải xuống trên
bộ định tuyến văn phòng hiện là 80,2 Kb/giây và tốc độ tải lên là 9,3 Kb/giây."
|
OpenClose | Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.OpenClose của thiết bị. Ví dụ: "Cửa trước đã mở" hoặc "Không thể mở cửa trước."
|
Bắt đầu | Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.StartStop của thiết bị. Ví dụ: "Chân không đã khởi động".
|
Tất cả các loại thiết bị đều hỗ trợ thông báo về các đặc điểm thích hợp.
Xây dựng thông báo cho Hành động nhà thông minh
Thêm thông báo vào Hành động smart home của bạn trong các giai đoạn sau:
- Cho Google biết liệu thông báo đã được bật từ ứng dụng thiết bị smart home hay chưa. Nếu người dùng bật hoặc tắt thông báo trong ứng dụng, hãy gửi yêu cầu
SYNC
để thông báo cho Google về thay đổi đối với thiết bị. - Khi một sự kiện thiết bị hoặc sự thay đổi trạng thái có liên quan xảy ra sẽ kích hoạt thông báo, hãy gửi yêu cầu thông báo bằng cách gọi API Report State
reportStateAndNotification
. Nếu trạng thái thiết bị thay đổi, thì bạn có thể gửi cả trạng thái tải và thông báo trong Report State và lệnh gọi Thông báo.
Phần sau đây sẽ trình bày chi tiết hơn về các bước này.
Cho biết thông báo đã được bật trong ứng dụng của bạn hay chưa
Người dùng có thể chọn có muốn nhận thông báo chủ động hay không bằng cách bật tính năng này trong GHA. Trong ứng dụng dành cho thiết bị smart home, bạn cũng có thể tuỳ ý thêm khả năng cho phép người dùng bật/tắt thông báo một cách rõ ràng, ví dụ như trong phần cài đặt ứng dụng.
Thông báo cho Google biết tính năng thông báo đã được bật trên thiết bị của bạn bằng cách thực hiện lệnh gọi Request SYNC (Yêu cầu đồng bộ hóa) để cập nhật dữ liệu thiết bị. Bạn nên gửi một yêu cầu SYNC
như thế này bất cứ khi nào người dùng thay đổi chế độ cài đặt này trong ứng dụng.
Trong phản hồi SYNC
, hãy gửi một trong những thông tin cập nhật sau:
- Nếu người dùng bật thông báo rõ ràng trong ứng dụng trên thiết bị hoặc nếu bạn không cung cấp tuỳ chọn bật/tắt, hãy đặt thuộc tính
devices.notificationSupportedByAgent
thànhtrue
. - Nếu người dùng tắt thông báo một cách rõ ràng trong ứng dụng thiết bị, hãy đặt thuộc tính
devices.notificationSupportedByAgent
thànhfalse
.
Đoạn mã sau đây cho thấy ví dụ về cách đặt phản hồi SYNC:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Gửi yêu cầu thông báo tới Google
Để kích hoạt thông báo trên Assistant, phương thức thực hiện sẽ gửi trọng tải thông báo đến Google Home Graph qua Report State và lệnh gọi API Thông báo.
Bật API Google HomeGraph
-
Trong Google Cloud Console, hãy truy cập vào trang HomeGraph API.
Truy cập trang HomeGraph API - Chọn dự án phù hợp với mã dự án smart home của bạn.
- Nhấp vào BẬT.
Tạo khóa tài khoản dịch vụ
Hãy làm theo các hướng dẫn sau để tạo khóa tài khoản dịch vụ từ Google Cloud Console:
-
Trong Google Cloud Console, hãy chuyển đến trang Tạo khoá tài khoản dịch vụ.
Chuyển đến trang Tạo khoá tài khoản dịch vụ - Trong danh sách Service account (Tài khoản dịch vụ), hãy chọn New service account (Tài khoản dịch vụ mới).
- Trong trường Tên tài khoản dịch vụ, hãy nhập một tên miền.
- Trong trường Mã tài khoản dịch vụ, hãy nhập một mã.
Trong danh sách Vai trò, hãy chọn Tài khoản dịch vụ > Trình tạo mã thông báo tài khoản dịch vụ.
Đối với Loại khóa, hãy chọn tùy chọn JSON.
- Nhấp vào Tạo. Một tệp JSON chứa khoá tải xuống vào máy tính.
Gửi thông báo
Thực hiện lệnh gọi yêu cầu thông báo bằng cách sử dụng API devices.reportStateAndNotification
.
Yêu cầu JSON phải bao gồm eventId
. Đây là mã nhận dạng duy nhất do nền tảng của bạn tạo cho sự kiện kích hoạt thông báo. eventId
phải là
mã nhận dạng ngẫu nhiên khác nhau mỗi khi bạn gửi yêu cầu thông báo.
Trong đối tượng notifications
mà bạn truyền vào lệnh gọi API, hãy thêm giá trị priority
để xác định cách hiển thị thông báo. Đối tượng notifications
có thể bao gồm nhiều trường tuỳ thuộc vào đặc điểm thiết bị.
Thực hiện theo một trong các đường dẫn sau để đặt trọng tải và gọi API:
Gửi thông báo chủ động tải trọng
Để gọi API, hãy chọn một trong các thẻ sau:
HTTP
API Home Graph cung cấp một điểm cuối HTTP
- Sử dụng tệp JSON của tài khoản dịch vụ đã tải xuống để tạo Mã thông báo web JSON (JWT). Để biết thêm thông tin, hãy xem nội dung Xác thực bằng tài khoản dịch vụ.
- Lấy mã truy cập OAuth 2.0 với
phạm vi
https://www.googleapis.com/auth/homegraph
bằng oauth2l: - Tạo yêu cầu JSON bằng
agentUserId
. Dưới đây là yêu cầu JSON mẫu cho Report State và Thông báo: - Kết hợp Report State và JSON thông báo cùng với mã thông báo trong yêu cầu POST trong giao thức HTTP của bạn vào điểm cuối của Google Home Graph. Dưới đây là ví dụ về cách đưa ra yêu cầu trong dòng lệnh bằng
curl
để kiểm thử:
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
API Home Graph cung cấp một điểm cuối gRPC
- Xem định nghĩa về dịch vụ vùng đệm giao thức cho API Home Graph.
- Làm theo tài liệu dành cho nhà phát triển gRPC để tạo mã giả lập cho một trong các ngôn ngữ được hỗ trợ.
- Gọi phương thức ReportStateAndNotification.
Node.js
Ứng dụng Google API Node.js cung cấp các đường liên kết cho API Home Graph.
- Khởi chạy dịch vụ
google.homegraph
bằng cách sử dụng Thông tin đăng nhập mặc định của ứng dụng. - Gọi phương thức
reportStateAndNotification
bằng ReportStateAndNotificationRequest. Phương thức này trả về mộtPromise
với 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 Client Library for Java (Thư viện ứng dụng API HomeGraph cho Java) cung cấp các liên kết cho API Home Graph.
- Khởi chạy
HomeGraphApiService
bằng Thông tin đăng nhập mặc định của ứng dụng. - Gọi phương thức
reportStateAndNotification
bằngReportStateAndNotificationRequest
. Phương thức này trả về mộtReportStateAndNotificationResponse
.
// 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);
Gửi nội dung phản hồi tiếp theo
Trọng tải cho phản hồi tiếp theo chứa trạng thái của yêu cầu, mã lỗi cho sự cố lỗi (nếu có) và followUpToken
hợp lệ được cung cấp trong yêu cầu ý định EXECUTE
. Bạn phải sử dụng followUpToken
trong vòng 5 phút để vẫn còn hiệu lực và liên kết đúng cách phản hồi với yêu cầu ban đầu.
Đoạn mã sau đây cho thấy ví dụ về trọng tải yêu cầu EXECUTE
có trường followUpToken
.
{ "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 chỉ sử dụng followUpToken
để xuất thông báo trên thiết bị mà người dùng đang tương tác ban đầu và không truyền đến tất cả các thiết bị của người dùng.
Để gọi API, hãy chọn một trong các thẻ sau:
HTTP
API Home Graph cung cấp một điểm cuối HTTP
- Sử dụng tệp JSON của tài khoản dịch vụ đã tải xuống để tạo Mã thông báo web JSON (JWT). Để biết thêm thông tin, hãy xem nội dung Xác thực bằng tài khoản dịch vụ.
- Lấy mã truy cập OAuth 2.0 với
phạm vi
https://www.googleapis.com/auth/homegraph
bằng oauth2l: - Tạo yêu cầu JSON bằng
agentUserId
. Dưới đây là yêu cầu JSON mẫu cho Report State và Thông báo: - Kết hợp Report State và JSON thông báo cùng với mã thông báo trong yêu cầu POST trong giao thức HTTP của bạn vào điểm cuối của Google Home Graph. Dưới đây là ví dụ về cách đưa ra yêu cầu trong dòng lệnh bằng
curl
để kiểm thử:
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
API Home Graph cung cấp một điểm cuối gRPC
- Xem định nghĩa về dịch vụ vùng đệm giao thức cho API Home Graph.
- Làm theo tài liệu dành cho nhà phát triển gRPC để tạo mã giả lập cho một trong các ngôn ngữ được hỗ trợ.
- Gọi phương thức ReportStateAndNotification.
Node.js
Ứng dụng Google API Node.js cung cấp các đường liên kết cho API Home Graph.
- Khởi chạy dịch vụ
google.homegraph
bằng cách sử dụng Thông tin đăng nhập mặc định của ứng dụng. - Gọi phương thức
reportStateAndNotification
bằng ReportStateAndNotificationRequest. Phương thức này trả về mộtPromise
với 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 Client Library for Java (Thư viện ứng dụng API HomeGraph cho Java) cung cấp các liên kết cho API Home Graph.
- Khởi chạy
HomeGraphApiService
bằng Thông tin đăng nhập mặc định của ứng dụng - Gọi phương thức
reportStateAndNotification
bằngReportStateAndNotificationRequest
. Phương thức này trả về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
Thông báo hỗ trợ ghi nhật ký sự kiện như được nêu trong Truy cập nhật ký sự kiện bằng Ghi nhật ký trên đám mây. Các nhật ký này sẽ giúp bạn kiểm tra và duy trì chất lượng của thông báo trong Hành động.
Dưới đây là giản đồ của một mục notificationLog
:
Tài sản | Mô tả |
---|---|
requestId |
ID yêu cầu thông báo. |
structName |
Tên của cấu trúc thông báo, chẳng hạn như "ObjectDetection". |
status |
Cho biết trạng thái của thông báo. |
Trường status
bao gồm nhiều trạng thái có thể cho thấy lỗi trong tải trọng thông báo. Một vài trong số này có thể chỉ có trên các Hành động chưa ra mắt trong giai đoạn phát hành chính thức.
Ví dụ về trạng thái bao gồm:
Trạng thái | Mô tả |
---|---|
EVENT_ID_MISSING |
Cho biết rằng trường eventId bắt buộc bị thiếu.
|
PRIORITY_MISSING |
Cho biết trường priority bị thiếu.
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Cho biết rằng thuộc tính notificationSupportedByAgent của thiết bị thông báo được cung cấp trong SYNC là false.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Cho biết người dùng chưa bật thông báo trên thiết bị thông báo trong GHA. Trạng thái này chỉ áp dụng cho những Hành động chưa phát hành phiên bản chính thức. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Cho biết người dùng chưa chỉ định thiết bị thông báo cho Nhà/Cấu trúc. Trạng thái này chỉ áp dụng cho những Hành động chưa phát hành phiên bản chính thức. |
Ngoài các trạng thái chung này có thể áp dụng cho tất cả các thông báo, trường status
cũng có thể bao gồm các trạng thái cụ thể theo đặc điểm nếu có (ví dụ: OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).