Các sự kiện không đồng bộ và được Google Cloud Pub/Sub quản lý, trong một chủ đề duy nhất cho mỗi Project. Sự kiện cung cấp thông tin cập nhật cho tất cả các thiết bị và cấu trúc, đồng thời việc nhận các sự kiện mới là miễn là mã truy cập không bị thu hồi bởi người dùng và thông báo sự kiện không đã hết hạn.
Bật sự kiện
Sự kiện là một tính năng không bắt buộc của API SDM. Xem Bật sự kiện để tìm hiểu cách bật các tính năng này cho Projectcủa bạn.
Google Cloud Pub/Sub
Hãy xem tài liệu về Google Cloud Pub/Sub để tìm hiểu tìm hiểu thêm về cách hoạt động của Pub/Sub. Cụ thể:
- Tìm hiểu kiến thức cơ bản về Pub/Sub thông qua Hướng dẫn thực hiện.
- Tìm hiểu cách hoạt động của mục Xác thực.
- Chọn Thư viện ứng dụng được cung cấp hoặc tự viết ra rồi sử dụng Các nền tảng API REST/HTTP hoặc gRPC.
Gói đăng ký sự kiện
Khi bật sự kiện cho Project, bạn sẽ được cung cấp một chủ đề dành riêng cho sự kiện đó Project Mã nhận dạng, có dạng:
projects/sdm-prod/topics/enterprise-project-id
Để nhận sự kiện, hãy tạo một chế độ kéo hoặc đẩy đăng ký vào chủ đề đó, tuỳ theo trường hợp sử dụng. Hỗ trợ nhiều gói thuê bao cho chủ đề SDM. Xem Quản lý gói thuê bao để tìm hiểu nhiều hơn của bạn.
Bắt đầu sự kiện
Để bắt đầu các sự kiện lần đầu tiên sau khi tạo gói thuê bao Pub/Sub, hãy thực hiện
devices.list
Lệnh gọi API dưới dạng điều kiện kích hoạt một lần. Các sự kiện cho tất cả cấu trúc và thiết bị sẽ xuất bản sau ngày này
cuộc gọi.
Để biết ví dụ, hãy xem Trang Uỷ quyền trong Quick Start (Bắt đầu nhanh) Hướng dẫn.
Thứ tự sự kiện
Pub/Sub không đảm bảo việc phân phối sự kiện theo thứ tự, đồng thời lệnh biên nhận của các sự kiện có thể không
tương ứng với thứ tự mà sự kiện thực sự xảy ra. Sử dụng timestamp
để hỗ trợ điều chỉnh thứ tự sự kiện. Các sự kiện cũng có thể đến riêng hoặc kết hợp
thành một thông báo sự kiện duy nhất.
Để biết thêm thông tin, hãy xem Sắp xếp thư theo thứ tự.
Mã nhận dạng người dùng
Nếu bạn triển khai dựa trên người dùng (thay vì cấu trúc hoặc thiết bị), hãy sử dụng
Trường userID
trong tải trọng sự kiện để liên kết các tài nguyên và sự kiện. Trường này là
một mã nhận dạng bị làm rối mã nguồn
đại diện cho một người dùng cụ thể.
userID
cũng có trong tiêu đề phản hồi HTTP của mỗi lệnh gọi API.
Sự kiện quan hệ
Sự kiện quan hệ biểu thị một bản cập nhật quan hệ cho một tài nguyên. Ví dụ: khi một thiết bị được thêm vào một cấu trúc hoặc khi một thiết bị bị xoá khỏi cấu trúc.
Có 3 loại sự kiện quan hệ:
- ĐÃ TẠO
- ĐÃ XÓA
- ĐÃ CẬP NHẬT
Tải trọng cho một sự kiện quan hệ như sau:
Dung lượng
{ "eventId" : "d93fe80c-dd14-4afb-80bd-b12dc7dca526", "timestamp" : "2019-01-01T00:00:01Z", "relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }, "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" }
Trong một sự kiện quan hệ, object
là tài nguyên đã kích hoạt sự kiện và
subject
là tài nguyên mà object
hiện có liên quan. Trong
ví dụ ở trên, a user đã cấp quyền truy cập vào thiết bị cụ thể này cho một
developervà thiết bị được cấp phép của userhiện liên quan đến thiết bị được cấp phép của họ
cấu trúc kích hoạt sự kiện.
subject
chỉ có thể là một căn phòng hoặc một nhà. Nếu a developer không có
quyền xem cấu trúc của user, nên subject
sẽ luôn là
trống.
Trường
Trường | Mô tả | Loại dữ liệu |
---|---|---|
eventId |
Giá trị nhận dạng duy nhất của sự kiện. | string Ví dụ: "96305092-d82e-4e52-9115-29bfd0594bf0" |
timestamp |
Thời gian khi sự kiện xảy ra. | string Ví dụ: "2019-01-01T00:00:01Z" |
relationUpdate |
Đối tượng cung cấp thông tin chi tiết về việc cập nhật mối quan hệ. | object |
userId |
Một giá trị nhận dạng duy nhất, bị làm rối mã nguồn đại diện cho người dùng. | string Ví dụ: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
Hãy xem Sự kiện để biết thêm thông tin về những loại các loại sự kiện khác nhau và cách chúng hoạt động.
Ví dụ
Đối với từng loại sự kiện quan hệ, các tải trọng sự kiện sẽ khác nhau:
ĐÃ TẠO
Đã tạo cấu trúc
"relationUpdate" : { "type" : "CREATED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
Đã tạo thiết bị
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
Đã tạo thiết bị
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
ĐÃ CẬP NHẬT
Đã di chuyển thiết bị
"relationUpdate" : { "type" : "UPDATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
ĐÃ XÓA
Đã xoá nhà
"relationUpdate" : { "type" : "DELETED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
Đã xoá thiết bị
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
Đã xoá thiết bị
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
Sự kiện quan hệ sẽ không được gửi khi:
- Đã xoá một phòng
Sự kiện tài nguyên
Sự kiện tài nguyên biểu thị một bản cập nhật dành riêng cho một tài nguyên. Nội dung đề xuất có thể là để phản hồi một thay đổi trong giá trị của trường trait, chẳng hạn như thay đổi chế độ của máy điều nhiệt. Tệp này cũng có thể biểu thị một hành động trên thiết bị không thay đổi trường đặc điểm, chẳng hạn như nhấn vào nút trên thiết bị.
Một sự kiện được tạo để phản hồi thay đổi về giá trị của trường trait chứa
Đối tượng traits
, tương tự như lệnh gọi GET trên thiết bị:
Dung lượng
{
"eventId" : "ba462282-5053-4e3c-bf38-612b802dfa53",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : {
"name" : "enterprises/project-id/devices/device-id",
"traits" : {
"sdm.devices.traits.ThermostatMode
" : {
"mode" : "COOL"
}
}
},
"userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"resourceGroup" : [
"enterprises/project-id/devices/device-id"
]
}
Sử dụng cá nhân tài liệu về trait để nắm được định dạng tải trọng cho mọi tài nguyên thay đổi trường trait sự kiện.
Một sự kiện được tạo để phản hồi một hành động trên thiết bị không thay đổi trường trait cũng có
tải trọng có đối tượng resourceUpdate
nhưng có đối tượng events
thay vì đối tượng traits
:
Dung lượng
{ "eventId" : "a556db20-2bab-4bd4-bb39-9c036a252a7e",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "MnCcivUK74q3Zq7CNUSsnYcAcM...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
Những loại sự kiện tài nguyên này được xác định theo các đặc điểm cụ thể. Ví dụ: Sự kiện chuyển động được xác định trong phần tử CameraMotion trait. Xem tài liệu về từng đặc điểm để tìm hiểu định dạng tải trọng cho các loại sự kiện tài nguyên này.
Trường
Trường | Mô tả | Loại dữ liệu |
---|---|---|
eventId |
Giá trị nhận dạng duy nhất của sự kiện. | string Ví dụ: "a556db20-2bab-4bd4-bb39-9c036a252a7e" |
timestamp |
Thời gian khi sự kiện xảy ra. | string Ví dụ: "2019-01-01T00:00:01Z" |
resourceUpdate |
Đối tượng nêu chi tiết thông tin về việc cập nhật tài nguyên. | object |
userId |
Một giá trị nhận dạng duy nhất, bị làm rối mã nguồn đại diện cho người dùng. | string Ví dụ: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
eventThreadId |
Giá trị nhận dạng duy nhất của chuỗi sự kiện. | string Ví dụ: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59" |
eventThreadState |
Trạng thái của chuỗi sự kiện. | string Giá trị: "BẮT ĐẦU", "ĐÃ CẬP NHẬT", "ĐÃ KẾT THÚC" |
resourceGroup |
Một đối tượng cho biết những tài nguyên có thể có nội dung cập nhật tương tự như sự kiện này. Tài nguyên của chính sự kiện đó (từ đối tượng resourceUpdate ) sẽ luôn hiện diện trong đối tượng này. |
object |
Hãy xem Sự kiện để biết thêm thông tin về những loại các loại sự kiện khác nhau và cách chúng hoạt động.
Thông báo có thể cập nhật
Bạn có thể triển khai thông báo dựa trên sự kiện tài nguyên trong một ứng dụng, chẳng hạn như cho Android hoặc iOS. Để giảm số lượng thông báo được gửi đi, một tính năng có tên là thông báo có thể cập nhật có thể được triển khai, trong đó thông báo hiện có được cập nhật thông tin mới dựa trên các sự kiện tiếp theo trong cùng một sự kiện chuỗi.Chọn hỗ trợ tính năng sự kiện cho thông báo có thể cập nhật và được gắn thẻ là
Có thể cập nhật eventThreadId
trong các tải trọng của chúng. Sử dụng bản thảo này
để liên kết các sự kiện riêng lẻ với nhau nhằm mục đích cập nhật một
hiển thị thông báo cho người dùng.
Một chuỗi sự kiện không giống với một phiên sự kiện. Chuỗi sự kiện xác định trạng thái đã cập nhật cho sự kiện trước đó trong cùng một chuỗi. Chiến lược phát hành đĩa đơn phiên sự kiện xác định các sự kiện riêng biệt có liên quan với nhau và có thể có nhiều chuỗi sự kiện cho một phiên sự kiện nhất định.
Để thông báo, các loại sự kiện khác nhau được nhóm thành những loại sự kiện khác nhau luồng.
Việc nhóm luồng và logic thời gian này do Google xử lý và tuân theo thay đổi bất kỳ lúc nào. developer nên cập nhật thông báo dựa trên các phiên và chuỗi sự kiện do API SDM cung cấp.
Trạng thái luồng
Các sự kiện hỗ trợ thông báo có thể cập nhật cũng có eventThreadState
cho biết trạng thái của chuỗi sự kiện tại thời điểm đó. Chiến dịch này
trường có các giá trị sau:
- BẮT ĐẦU — Sự kiện đầu tiên trong chuỗi sự kiện.
- ĐÃ CẬP NHẬT – Một sự kiện trong chuỗi sự kiện đang diễn ra. Có thể không có hoặc có nhiều sự kiện có trạng thái này trong một chuỗi.
- ĐÃ KẾT THÚC – Sự kiện cuối cùng trong một chuỗi sự kiện, có thể là bản sao của sự kiện ĐÃ CẬP NHẬT gần đây nhất, tùy thuộc vào loại chuỗi.
Bạn có thể sử dụng trường này để theo dõi tiến trình của một chuỗi sự kiện và thời điểm đã kết thúc.
Lọc sự kiện
Trong một số trường hợp, các sự kiện do thiết bị phát hiện có thể bị lọc ra khỏi quá trình xuất bản chủ đề SDM Pub/Sub. Hành vi này có tên là lọc sự kiện. Mục đích của tính năng lọc sự kiện là để tránh phát hành quá nhiều thông báo sự kiện tương tự nhau trong một khoảng thời gian ngắn.
Ví dụ: Một thông báo có thể được xuất bản lên một chủ đề trong SDM cho sự kiện Chuyển động ban đầu. Thông tin khác thông báo cho Chuyển động sau đó sẽ là bị lọc ra khỏi xuất bản cho đến khi một khoảng thời gian nhất định trôi qua. Sau khoảng thời gian đó thời gian trôi qua, thì thông báo sự kiện cho loại sự kiện đó có thể được xuất bản lại.
Trong ứng dụng Google Home (GHA), những sự kiện đã lọc sẽ vẫn hiển thị trong lịch sử sự kiện của user. Tuy nhiên, như vậy các sự kiện sẽ không tạo ra thông báo ứng dụng (ngay cả khi loại thông báo đó là bật).
Mỗi loại sự kiện có logic lọc sự kiện riêng được xác định bằng Google và có thể thay đổi bất cứ lúc nào. Logic lọc sự kiện này là độc lập với chuỗi sự kiện và logic phiên.
Tài khoản dịch vụ
Bạn nên sử dụng tài khoản dịch vụ để quản lý API SDM gói thuê bao và thông báo sự kiện. Tài khoản dịch vụ được ứng dụng hoặc máy ảo chứ không phải con người và có khoá tài khoản duy nhất của riêng mình.
Uỷ quyền tài khoản dịch vụ để API Pub/Sub sử dụng OAuth cấp quyền truy cập (2LO).
Trong quy trình uỷ quyền 2LO:
- developer yêu cầu mã truy cập bằng khoá dịch vụ.
- developer sử dụng mã truy cập với các lệnh gọi đến API.
Để tìm hiểu thêm về Google 2LO và cách thiết lập, hãy xem Sử dụng OAuth 2.0 cho máy chủ đến máy chủ Ứng dụng.
Ủy quyền
Tài khoản dịch vụ này phải được uỷ quyền để sử dụng với API Pub/Sub:
- Bật Cloud Pub/Sub API trong Google Cloud.
- Tạo một tài khoản dịch vụ và khoá tài khoản dịch vụ như mô tả trong Tạo tài khoản dịch vụ. Bạn chỉ nên chỉ định vai trò Người đăng ký Pub/Sub. Hãy nhớ tải khoá tài khoản dịch vụ xuống máy tính sẽ sử dụng API Pub/Sub.
- Cung cấp thông tin xác thực của bạn (khoá tài khoản dịch vụ) cho
bằng cách làm theo hướng dẫn ở trang trong
hoặc lấy mã truy cập theo cách thủ công bằng
oauth2l
, nếu bạn muốn kiểm tra nhanh quyền truy cập API. - Sử dụng thông tin xác thực tài khoản dịch vụ hoặc mã truy cập với
Pub/Sub
project.subscriptions
API để lấy và xác nhận thông báo.
OAuth2l
Google oauth2l
là một công cụ dòng lệnh dành cho OAuth được viết bằng ngôn ngữ Go. Cài đặt cho
Máy Mac hoặc Linux dùng Go.
- Nếu bạn chưa cài đặt Go trên hệ thống, hãy tải xuống và cài đặt ứng dụng này trước.
- Sau khi cài đặt Go, hãy cài đặt
oauth2l
và thêm vị trí của ứng dụng vàoPATH
biến môi trường:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- Sử dụng
oauth2l
để lấy mã truy cập cho API theo cách phù hợp (Các) phạm vi của OAuth:
Ví dụ: nếu khoá dịch vụ của bạn nằm ởoauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
~/myServiceKey-eb0a5f900ee3.json
:oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...
Hãy xem oauth2l
README để biết thêm thông tin về cách sử dụng
của bạn.
Thư viện ứng dụng API của Google
Có một số thư viện ứng dụng cho những API Google sử dụng OAuth 2,0. Hãy xem Thư viện ứng dụng API của Google để biết thêm thông tin về ngôn ngữ bạn chọn.
Khi sử dụng các thư viện này với Pub/Sub API, hãy dùng (các) chuỗi phạm vi sau:
https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
Lỗi
(Các) mã lỗi sau đây có thể được trả về theo hướng dẫn này:
Thông báo Lỗi | RPC | Khắc phục sự cố |
---|---|---|
Hình ảnh camera không còn có sẵn để tải xuống. | DEADLINE_EXCEEDED |
Hình ảnh sự kiện sẽ hết hạn sau 30 giây kể từ khi sự kiện được xuất bản. Đừng quên tải hình ảnh xuống trước khi hết hạn. |
Mã sự kiện không thuộc về camera. | FAILED_PRECONDITION |
Sử dụng đúng eventID do sự kiện máy ảnh trả về. |
Hãy xem Tài liệu tham khảo về mã lỗi API để biết danh sách đầy đủ các mã lỗi API.