Peristiwa bersifat asinkron dan dikelola oleh Google Cloud Pub/Sub, dalam satu topik per Project. Peristiwa memberikan update untuk semua perangkat dan struktur, serta penerimaan peristiwa dijamin selama token akses tidak dicabut oleh pengguna dan pesan peristiwa belum habis masa berlakunya.
Aktifkan acara
Peristiwa adalah fitur opsional di SDM API. Lihat Mengaktifkan peristiwa guna mempelajari cara mengaktifkannya untuk ProjectAnda.
Google Cloud Pub/Sub
Lihat dokumentasi Google Cloud Pub/Sub untuk mempelajari lebih lanjut cara kerja Pub/Sub. Pada khususnya:
- Pelajari dasar-dasar Pub/Sub dengan Panduan cara kerja.
- Memahami cara kerja Authentication.
- Pilih Library Klien yang disediakan atau tulis sendiri dan gunakan platform REST/HTTP atau gRPC API.
Langganan acara
Saat peristiwa diaktifkan untuk Project, Anda akan diberi topik khusus untuk Project ID tersebut, dalam bentuk:
projects/sdm-prod/topics/enterprise-project-id
Untuk menerima peristiwa, buat langganan pull atau push ke topik tersebut, tergantung kasus penggunaan Anda. Beberapa langganan ke topik SDM didukung. Lihat Mengelola langganan untuk informasi selengkapnya.
Memulai peristiwa
Untuk menginisiasi peristiwa untuk pertama kalinya setelah langganan Pub/Sub dibuat, lakukan panggilan API
devices.list
sebagai pemicu satu kali. Peristiwa untuk semua struktur dan perangkat akan dipublikasikan setelah panggilan ini.
Sebagai contoh, lihat halaman Memberi otorisasi di Panduan Memulai Cepat.
Urutan peristiwa
Pub/Sub tidak menjamin pengiriman peristiwa yang diurutkan, dan urutan penerimaan peristiwa mungkin tidak sesuai dengan urutan peristiwa yang sebenarnya terjadi. Gunakan kolom timestamp
untuk membantu rekonsiliasi urutan peristiwa. Peristiwa juga dapat masuk satu per satu atau digabungkan
menjadi satu pesan peristiwa.
Untuk mengetahui informasi selengkapnya, lihat Mengurutkan pesan.
ID pengguna
Jika implementasi Anda didasarkan pada pengguna (bukan struktur atau perangkat), gunakan kolom userID
dari payload peristiwa untuk menghubungkan resource dan peristiwa. Kolom ini adalah ID yang di-obfuscate yang mewakili pengguna tertentu.
userID
juga tersedia di header respons HTTP setiap panggilan API.
Peristiwa hubungan
Peristiwa hubungan mewakili update relasional untuk resource. Misalnya, saat perangkat ditambahkan ke suatu struktur, atau saat perangkat dihapus dari struktur.
Ada tiga jenis peristiwa relasi:
- DIBUAT
- DELETED (DIHAPUS)
- DIPERBARUI
Payload untuk peristiwa relasi adalah sebagai berikut:
Payload
{ "eventId" : "eed9763a-8735-45d9-81d9-e0621c130eb1", "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" }
Dalam peristiwa relasi, object
adalah resource yang memicu peristiwa, dan subject
adalah resource yang sekarang memiliki relasi dengan object
. Pada contoh di atas, user telah memberikan akses ke perangkat spesifik ini ke developer, dan perangkat yang diizinkan usersekarang terkait dengan struktur yang diizinkan, yang memicu peristiwa tersebut.
subject
hanya dapat berupa ruangan atau struktur. Jika a developer tidak memiliki
izin untuk melihat struktur user, subject
akan selalu
kosong.
Kolom
Kolom | Deskripsi | Jenis Data |
---|---|---|
eventId |
ID unik untuk peristiwa. | string Contoh: "1362476b-4ac4-4608-a8be-4c8cf4101426" |
timestamp |
Waktu saat peristiwa terjadi. | string Contoh: "2019-01-01T00:00:01Z" |
relationUpdate |
Objek yang memerinci informasi tentang pembaruan relasi. | object |
userId |
ID unik yang di-obfuscate yang mewakili pengguna. | string Contoh: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
Lihat Peristiwa untuk informasi selengkapnya tentang berbagai jenis peristiwa dan cara kerjanya.
Contoh
Payload peristiwa berbeda untuk setiap jenis peristiwa relasi:
DIBUAT
Struktur dibuat
"relationUpdate" : { "type" : "CREATED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
Perangkat dibuat
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
Perangkat dibuat
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
DIPERBARUI
Perangkat dipindahkan
"relationUpdate" : { "type" : "UPDATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
DELETED (DIHAPUS)
Struktur dihapus
"relationUpdate" : { "type" : "DELETED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
Perangkat dihapus
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
Perangkat dihapus
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
Peristiwa hubungan tidak dikirim saat:
- Ruang dihapus
Peristiwa resource
Peristiwa resource mewakili update khusus untuk resource. Hal ini dapat merespons perubahan nilai kolom trait, seperti perubahan mode termostat. Class ini juga dapat merepresentasikan tindakan perangkat yang tidak mengubah kolom trait, seperti menekan tombol perangkat.
Peristiwa yang dibuat sebagai respons terhadap perubahan nilai kolom trait berisi objek traits
, mirip dengan panggilan GET perangkat:
Payload
{
"eventId" : "5b98a768-6771-4d4d-836d-58cce3a62cca",
"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"
]
}
Gunakan dokumentasi masing-masing trait untuk memahami format payload untuk peristiwa resource perubahan kolom trait apa pun.
Peristiwa yang dihasilkan sebagai respons terhadap tindakan perangkat yang tidak mengubah kolom trait juga memiliki payload dengan objek resourceUpdate
, tetapi dengan objek events
, bukan objek traits
:
Payload
{ "eventId" : "3426d266-406b-48f3-9595-5192229a39a0",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "8XZ1cQ76Becovj551YfM9ZnuwB...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
Jenis peristiwa resource ini didefinisikan dalam karakteristik tertentu. Misalnya, peristiwa Gerakan ditentukan dalam karakteristik CameraMotion . Lihat dokumentasi setiap trait guna memahami format payload untuk jenis peristiwa resource ini.
Kolom
Kolom | Deskripsi | Jenis Data |
---|---|---|
eventId |
ID unik untuk peristiwa. | string Contoh: "3426d266-406b-48f3-9595-5192229a39a0" |
timestamp |
Waktu saat peristiwa terjadi. | string Contoh: "2019-01-01T00:00:01Z" |
resourceUpdate |
Objek yang menjelaskan informasi tentang update resource. | object |
userId |
ID unik yang di-obfuscate yang mewakili pengguna. | string Contoh: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
eventThreadId |
ID unik untuk thread peristiwa. | string Contoh: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59" |
eventThreadState |
Status thread peristiwa. | string Nilai: "STARTED", "UPDATE", "ENDED" |
resourceGroup |
Objek yang menunjukkan resource yang mungkin memiliki pembaruan serupa dengan peristiwa ini. Resource peristiwa itu sendiri (dari objek resourceUpdate ) akan selalu ada dalam objek ini. |
object |
Lihat Peristiwa untuk informasi selengkapnya tentang berbagai jenis peristiwa dan cara kerjanya.
Notifikasi yang dapat diperbarui
Notifikasi berdasarkan peristiwa resource dapat diimplementasikan dalam aplikasi, seperti untuk Android atau iOS. Untuk mengurangi jumlah notifikasi yang dikirim, fitur yang disebut notifikasi yang dapat diperbarui dapat diterapkan, dengan notifikasi yang sudah ada diperbarui dengan informasi baru berdasarkan peristiwa berikutnya dalam thread peristiwa yang sama.Pilih peristiwa yang mendukung notifikasi yang dapat diperbarui dan diberi tag sebagai
Dapat diperbarui eventThreadId
dalam payload-nya. Gunakan kolom ini untuk menautkan masing-masing peristiwa dengan tujuan memperbarui notifikasi yang ada dan yang telah ditampilkan kepada pengguna.
Thread peristiwa tidak sama dengan sesi peristiwa. Thread peristiwa mengidentifikasi status yang diperbarui untuk peristiwa sebelumnya di thread yang sama. Sesi peristiwa mengidentifikasi peristiwa terpisah yang terkait satu sama lain, dan mungkin terdapat beberapa thread peristiwa untuk sesi peristiwa tertentu.
Untuk tujuan notifikasi, berbagai jenis peristiwa dikelompokkan ke dalam thread yang berbeda.
Logika pengaturan waktu dan pengelompokan thread ini ditangani oleh Google dan dapat berubah kapan saja. developer harus memperbarui notifikasi berdasarkan thread peristiwa dan sesi yang disediakan oleh SDM API.
Status thread
Peristiwa yang mendukung notifikasi yang dapat diperbarui juga memiliki kolom eventThreadState
yang menunjukkan status thread peristiwa pada waktu tersebut. Kolom ini memiliki nilai berikut:
- STARTED — Peristiwa pertama dalam rangkaian peristiwa.
- DIPERBARUI — Peristiwa dalam rangkaian peristiwa yang sedang berlangsung. Mungkin ada nol atau beberapa peristiwa dengan status ini dalam satu thread.
- ENDED — Peristiwa terakhir dalam rangkaian peristiwa, yang mungkin merupakan duplikat dari peristiwa DIPERBARUI terakhir, bergantung pada jenis rangkaian pesannya.
Kolom ini dapat digunakan untuk melacak progres thread peristiwa dan kapan peristiwa tersebut telah berakhir.
Pemfilteran peristiwa
Dalam beberapa kasus, peristiwa yang terdeteksi oleh perangkat mungkin akan difilter agar tidak dipublikasikan ke topik SDM Pub/Sub. Perilaku ini disebut pemfilteran peristiwa. Tujuan pemfilteran peristiwa adalah untuk menghindari publikasi terlalu banyak pesan peristiwa serupa dalam waktu singkat.
Misalnya, pesan dapat dipublikasikan ke topik SDM untuk peristiwa Gerakan awal. Pesan lain untuk Motion setelahnya akan difilter agar tidak dipublikasikan hingga periode waktu tertentu berlalu. Setelah jangka waktu tersebut berlalu, pesan peristiwa untuk jenis peristiwa tersebut dapat dipublikasikan lagi.
Di Aplikasi Google Home (GHA), peristiwa yang difilter akan tetap ditampilkan di histori peristiwa user. Namun, peristiwa tersebut tidak menghasilkan notifikasi aplikasi (meskipun jenis notifikasi tersebut diaktifkan).
Setiap jenis peristiwa memiliki logika pemfilteran peristiwanya sendiri, yang ditentukan oleh Google dan dapat berubah kapan saja. Logika pemfilteran peristiwa ini tidak bergantung pada thread peristiwa dan logika sesi.
Akun layanan
Akun layanan direkomendasikan untuk mengelola pesan peristiwa dan langganan SDM API. Akun layanan digunakan oleh aplikasi atau mesin virtual, bukan orang, dan memiliki kunci akun uniknya sendiri.
Otorisasi akun layanan untuk Pub/Sub API menggunakan two-legged OAuth (2LO).
Dalam alur otorisasi 2LO:
- developer meminta token akses menggunakan kunci layanan.
- developer menggunakan token akses dengan panggilan ke API.
Untuk mempelajari Google 2LO lebih lanjut dan cara menyiapkan penyiapan, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server.
Otorisasi
Akun layanan harus diberi otorisasi untuk digunakan dengan Pub/Sub API:
- Aktifkan Cloud Pub/Sub API di Google Cloud.
- Buat akun layanan dan kunci akun layanan seperti yang dijelaskan dalam Membuat akun layanan. Sebaiknya hanya berikan peran Pub/Sub Subscriber. Pastikan Anda mendownload kunci akun layanan ke komputer yang akan menggunakan Pub/Sub API.
- Berikan kredensial autentikasi (kunci akun layanan) ke kode aplikasi Anda dengan mengikuti petunjuk di halaman pada langkah sebelumnya, atau dapatkan token akses secara manual menggunakan
oauth2l
, jika Anda ingin menguji akses API dengan cepat. - Gunakan kredensial akun layanan atau token akses dengan
Pub/Sub
project.subscriptions
API untuk menarik dan mengonfirmasi pesan.
Oauth2l
Google oauth2l
adalah alat command line untuk OAuth yang ditulis di Go. Instal untuk
Mac atau Linux menggunakan Go.
- Jika tidak memiliki Go di sistem Anda, download dan instal aplikasi tersebut terlebih dahulu.
- Setelah Go diinstal, instal
oauth2l
dan tambahkan lokasinya ke variabel lingkunganPATH
Anda:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- Gunakan
oauth2l
guna mendapatkan token akses untuk API, menggunakan cakupan OAuth yang sesuai:
Misalnya, jika kunci layanan Anda berada dioauth2l 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...
Lihat README oauth2l
untuk informasi penggunaan
selengkapnya.
Library Klien Google API
Ada beberapa library klien yang tersedia untuk Google API yang menggunakan OAuth 2.0. Lihat Library Klien Google API untuk informasi selengkapnya tentang bahasa pilihan Anda.
Saat menggunakan library ini dengan Pub/Sub API, gunakan string cakupan berikut:
https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
Error
Kode error berikut mungkin ditampilkan sehubungan dengan panduan ini:
Pesan Error | RPC | Pemecahan masalah |
---|---|---|
Gambar kamera tidak lagi tersedia untuk didownload. | DEADLINE_EXCEEDED |
Masa berlaku gambar acara akan berakhir 30 detik setelah acara dipublikasikan. Pastikan untuk mendownload image sebelum masa berlakunya habis. |
ID peristiwa bukan milik kamera. | FAILED_PRECONDITION |
Gunakan eventID yang benar yang ditampilkan oleh peristiwa terekam kamera. |
Baca Referensi Kode Error API untuk mengetahui daftar lengkap kode error API.