Report State là một tính năng quan trọng cho phép Hành động Home chủ động báo cáo lại trạng thái mới nhất của thiết bị người dùng cho Google Home Graph thay vì chờ ý định QUERY
.
Report State báo cáo cho Google về trạng thái của các thiết bị của người dùng
với agentUserId
được chỉ định liên kết với chúng (được gửi trong yêu cầu
SYNC
ban đầu). Khi muốn thực hiện một hành động yêu cầu hiểu trạng thái hiện tại của thiết bị, Google Assistant chỉ cần tra cứu thông tin trạng thái trong Home Graph thay vì phát ý định QUERY
cho nhiều đám mây bên thứ ba trước khi đưa ra ý định EXECUTE
.
Khi không có Report State, với ánh sáng từ nhiều nhà cung cấp trong
phòng khách, lệnh Ok Google, làm sáng phòng khách sẽ yêu cầu
giải quyết nhiều ý định QUERY
được gửi đến nhiều đám mây, thay vì chỉ tìm kiếm các giá trị độ sáng hiện tại dựa trên những gì đã báo cáo trước đó. Để có trải nghiệm người dùng tốt nhất, Assistant cần có trạng thái hiện tại của thiết bị mà không yêu cầu thiết bị truyền một vòng tròn đến thiết bị.
Sau SYNC
ban đầu của một thiết bị, nền tảng sẽ gửi một ý định QUERY
để thu thập trạng thái của thiết bị để điền Home Graph.
Sau thời điểm đó, Home Graph chỉ lưu trữ trạng thái được gửi bằng Report State.
Khi gọi Report State, hãy nhớ cung cấp dữ liệu trạng thái hoàn chỉnh cho một đặc điểm nhất định. Home Graph cập nhật trạng thái trên cơ sở từng đặc điểm và ghi đè tất cả dữ liệu cho đặc điểm đó khi thực hiện lệnh gọi Report State. Ví dụ như nếu bạn đang báo cáo trạng thái cho đặc điểm StartStop, thì trọng tải cần có các giá trị cho cả isRunning
và isPaused
.
Bắt đầu
Để triển khai Report State, hãy làm theo các bước sau:
Bật API Google HomeGraph
-
Trong Google Cloud Platform Console, hãy truy cập trang HomeGraph API.
Truy cập vào 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 một khoá tài khoản dịch vụ
Hãy làm theo các hướng dẫn sau để tạo khoá tài khoản dịch vụ từ GCP Console:
-
Trong GCP Console, hãy chuyển đến trang Tạo khoá tài khoản dịch vụ.
Chuyển đến trang tạo khoá cho tài khoản dịch vụ - Trong danh sách Tài khoản dịch vụ, hãy chọn 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 tê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 của tài khoản dịch vụ.
Đối với Loại khoá, hãy chọn tuỳ chọn JSON.
- Nhấp vào Tạo. Tệp JSON chứa khoá của bạn được tải xuống máy tính.
Gọi API
Chọn một chế độ trong các thẻ bên dưới:
HTTP
Home Graph cung cấp một điểm cuối HTTP
- 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 phần 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 Trạng thái báo cáo và Thông báo: - Kết hợp Trạng thái báo cáo và JSON thông báo cùng với mã thông báo trong yêu cầu POST HTTP của bạn đến đ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 cách sử dụng
curl
, để kiểm thử:
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 cung cấp một điểm cuối gRPC
- Nhận định nghĩa dịch vụ vùng đệm giao thức cho API biểu đồ chính.
- Làm theo tài liệu dành cho nhà phát triển gRPC để tạo mã giả lập ứng dụng 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 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 xác thực 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', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
Java
HomeGraph API Client Library cho Java cung cấp các đường liên kết cho API Home Graph.
- Khởi động
HomeGraphApiService
bằng Thông tin xác thực 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 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); }
Trạng thái báo cáo kiểm tra
Để hành động của bạn sẵn sàng đạt giấy chứng nhận, bạn cần phải kiểm thử Report State.
Để làm điều này, bạn nên sử dụng Công cụ xem Home Graph. Đây là một ứng dụng web độc lập không yêu cầu tải xuống hoặc triển khai.
Trang tổng quan Report State vẫn có sẵn, nhưng không còn được dùng nữa và không còn được hỗ trợ.
Trang tổng quan về trạng thái báo cáo
Điều kiện tiên quyết
Trước khi có thể thử nghiệm hành động, bạn cần có Khoá tài khoản dịch vụ và agentUserId
của bạn. Nếu bạn đã có Khoá tài khoản dịch vụ và
agentUserId
, hãy xem phần Triển khai Trang tổng quan Report State.
Triển khai trang tổng quan về Trạng thái báo cáo
Sau khi bạn có Khoá tài khoản dịch vụ và Mã nhận dạng người dùng của nhân viên hỗ trợ cho dự án của mình,
hãy tải xuống và triển khai phiên bản mới nhất trên
Report State
Trang tổng quan.
Sau khi bạn tải phiên bản mới nhất xuống, hãy làm theo hướng dẫn từ
tệp README.MD
đi kèm.
Sau khi bạn đã triển khai trang tổng quan Report State, hãy truy cập vào trang tổng quan từ URL sau (thay thế your_project_id bằng mã dự án):
http://<your-project-id>.appspot.com
Trên trang tổng quan, hãy làm như sau:
- Chọn tệp khoá tài khoản của bạn
- Thêm agentUserId của bạn
Sau đó, hãy nhấp vào Danh sách.
Tất cả thiết bị của bạn đều có trong danh sách. Sau khi danh sách được điền, bạn có thể sử dụng nút Làm mới để cập nhật trạng thái của thiết bị. Nếu có thay đổi về trạng thái thiết bị, hàng sẽ được đánh dấu bằng màu xanh lục.
Phản hồi lỗi
Bạn có thể nhận được một trong các phản hồi lỗi sau khi gọi Report State. Các phản hồi này có dạng mã trạng thái HTTP.
400 Bad Request
– Máy chủ không thể xử lý yêu cầu do máy khách gửi do cú pháp không hợp lệ. Các nguyên nhân phổ biến bao gồm JSON không đúng định dạng hoặc sử dụngnull
thay vì "" cho giá trị chuỗi.404 Not Found
– Không tìm thấy tài nguyên được yêu cầu nhưng có thể sẽ có sau này. Thông thường, điều này có nghĩa là chúng tôi không thể tìm thấy thiết bị được yêu cầu. Điều này cũng có thể có nghĩa là tài khoản người dùng không được liên kết với Google hoặc chúng tôi nhận đượcagentUserId
không hợp lệ. Đảm bảo rằngagentUserId
khớp với giá trị đã cung cấp trong phản hồi SYNC và bạn đang xử lý đúng các ý định DISCONNECT.