Yêu cầu đồng bộ hoá sẽ kích hoạt yêu cầu SYNC
thực hiện đơn hàng của bạn cho bất kỳ người dùng Google nào có thiết bị liên kết với agentUserId
được chỉ định (mà bạn đã gửi trong yêu cầu SYNC ban đầu). Điều này cho phép bạn cập nhật thiết bị của người dùng mà không cần hủy liên kết và liên kết lại tài khoản của họ. Tất cả người dùng được liên kết với giá trị nhận dạng này
sẽ nhận được yêu cầu SYNC
.
Bạn phải kích hoạt một yêu cầu SYNC
:
- Nếu người dùng thêm một thiết bị mới.
- Nếu người dùng xóa một thiết bị hiện có.
- Nếu người dùng đổi tên thiết bị hiện có.
- Nếu bạn triển khai một loại thiết bị mới, đặc điểm quảng cáo hoặc thêm tính năng mới của thiết bị.
Bắt đầu
Để triển khai tính năng Yêu cầu đồng bộ hóa, hãy làm theo các bước sau:
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 API
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à một yêu cầu JSON mẫu cho Request Sync: - Hãy kết hợp JSON yêu cầu đồng bộ hóa JSON và mã thông báo trong yêu cầu HTTP POST của bạn với đ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": "user-123" }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:requestSync"
gRPC
API Home Graph cung cấp một điểm cuối gRPC
- Tải định nghĩa dịch vụ vùng đệm giao thức cho API đồ thị trên trang chủ.
- 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 RequestSync.
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 đăng nhập mặc định của ứng dụng. - Gọi phương thức
requestSync
bằng RequestSyncDevicesRequest. Phương thức này trả về mộtPromise
với RequestSyncDevicesResponse trống.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.requestSync({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', async: false } });
Java
Thư viện khách Home API dành cho Java cung cấp các đường 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
requestSync
bằngRequestSyncDevicesRequest
. Phương thức này trả về mộtReportStateAndNotificationResponse
trống.
// 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(); // Request sync. RequestSyncDevicesRequest request = new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false); homegraphService.devices().requestSync(request);
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 Request Sync. Những phản hồi này ở dạng mã trạng thái HTTP.
400 Bad Request
– Máy chủ không thể xử lý yêu cầu do ứng dụng gửi đ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.403 Forbidden
– Máy chủ không thể xử lý yêu cầu choagentUserId
đã cho do xảy ra lỗi khi làm mới mã thông báo. Hãy đảm bảo điểm cuối OAuth của bạn phản hồi chính xác để làm mới các yêu cầu mã thông báo và kiểm tra trạng thái liên kết tài khoản của người dùng.404 Not Found
– Không thể tìm thấy tài nguyên đã yêu cầu nhưng có thể có trong tương lai. Thông thường, điều này có nghĩa là tài khoản người dùng chưa liên kết với Google hoặc chúng tôi nhận được mộtagentUserId
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.429 Too Many Requests
– Đã vượt quá số lượng yêu cầu đồng bộ hoá tối đa choagentUserId
đã cho. Phương thức gọi chỉ có thể đưa ra một yêu cầu đồng bộ hoá đồng thời trừ khi cờasync
được đặt thành đúng.