Peristiwa asinkron dan dikelola oleh Google Cloud Pub/Sub, dalam satu topik sesuai Project. Peristiwa memberikan pembaruan untuk semua perangkat dan struktur serta tanda terima peristiwa dijamin selama token akses tidak dicabut oleh pengguna dan pesan peristiwa belum kedaluwarsa.
Aktifkan acara
Peristiwa adalah fitur opsional SDM API. Lihat Aktifkan peristiwa untuk mempelajari cara mengaktifkannya untuk Project.
Google Cloud Pub/Sub
Lihat dokumentasi Google Cloud Pub/Sub untuk mempelajari lebih lanjut tentang cara kerja Pub/Sub. Khususnya:
- Pelajari dasar-dasar Pub/Sub dengan Panduan cara kerja.
- Pahami cara kerja Authentication.
- Memilih 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 hal tersebut Project ID, dalam bentuk:
projects/sdm-prod/topics/enterprise-project-id
Untuk menerima peristiwa, buat objek pull atau push ke topik tersebut, bergantung pada kasus penggunaan. Beberapa langganan ke topik SDM didukung. Lihat Mengelola langganan untuk informasi lebih lanjut tidak akurat atau tidak sesuai.
Memulai peristiwa
Untuk memulai peristiwa untuk pertama kalinya setelah langganan Pub/Sub dibuat, buat
devices.list
Panggilan API sebagai pemicu satu kali. Acara untuk semua struktur dan perangkat akan dipublikasikan setelah ini
panggilan.
Misalnya, lihat Halaman Otorisasi di Mulai Cepat Panduan.
Urutan acara
Pub/Sub tidak menjamin pengiriman acara yang berurutan, dan urutan tanda terima peristiwa mungkin
sesuai dengan urutan
peristiwa sebenarnya terjadi. Menggunakan timestamp
untuk membantu rekonsiliasi urutan peristiwa. Acara juga dapat hadir secara terpisah atau gabungan
ke dalam satu pesan peristiwa.
Untuk 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. Bidang ini adalah
ID yang di-obfuscate yang mewakili pengguna tertentu.
userID
juga tersedia di header respons HTTP setiap panggilan API.
Peristiwa relasi
Peristiwa relasi mewakili update relasional untuk suatu resource. Misalnya, ketika perangkat ditambahkan ke struktur, atau saat perangkat dihapus dari struktur.
Ada tiga jenis peristiwa relasi:
- DIBUAT
- DIHAPUS
- DIPERBARUI
Payload untuk peristiwa relasi adalah sebagai berikut:
Payload
{ "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" }
Dalam peristiwa relasi, object
adalah resource yang memicu peristiwa dan
subject
adalah resource yang sekarang berhubungan dengan object
. Di kolom
di atas, user telah memberikan akses ke perangkat tertentu ini kepada
developer, dan perangkat yang diberi otorisasi userkini terkait dengan
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: "96305092-d82e-4e52-9115-29bfd0594bf0" |
timestamp |
Waktu terjadinya peristiwa. | 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-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" }
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 relasi tidak dikirim saat:
- Ruang dihapus
Peristiwa resource
Peristiwa resource mewakili update khusus untuk resource. Hal itu dapat berupa respons terhadap perubahan nilai isian karakteristik, seperti mengubah mode termostat. Ini juga dapat mewakili tindakan perangkat yang tidak mengubah kolom karakteristik seperti menekan tombol perangkat.
Peristiwa yang dihasilkan sebagai respons terhadap perubahan nilai kolom trait berisi
Objek traits
, mirip dengan panggilan GET perangkat:
Payload
{
"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"
]
}
Gunakan perorangan dokumentasi trait untuk memahami format payload untuk setiap resource perubahan kolom ciri peristiwa.
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" : "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" ] }
Jenis peristiwa resource ini didefinisikan dalam ciri tertentu. Misalnya, Peristiwa gerakan didefinisikan dalam CameraMotion trait. Lihat dokumentasi setiap trait untuk memahami format {i>payload<i} untuk jenis peristiwa sumber daya ini.
Kolom
Kolom | Deskripsi | Jenis Data |
---|---|---|
eventId |
ID unik untuk peristiwa. | string Contoh: "a556db20-2bab-4bd4-bb39-9c036a252a7e" |
timestamp |
Waktu terjadinya peristiwa. | string Contoh: "2019-01-01T00:00:01Z" |
resourceUpdate |
Objek yang memerinci informasi tentang update resource. | object |
userId |
ID unik yang di-obfuscate yang mewakili pengguna. | string Contoh: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
eventThreadId |
ID unik untuk rangkaian pesan peristiwa. | string Contoh: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59" |
eventThreadState |
Status thread peristiwa. | string Nilai: "STARTED", "DIPERBARUI", "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-jenis peristiwa dan cara kerjanya.
Notifikasi yang dapat diperbarui
Notifikasi berdasarkan peristiwa resource bisa diimplementasikan di aplikasi, seperti untuk Android atau iOS. Untuk mengurangi jumlah notifikasi yang dikirim, fitur yang disebut notifikasi yang dapat diupdate dapat diterapkan, jika notifikasi yang ada diperbarui dengan informasi baru berdasarkan peristiwa berikutnya di peristiwa yang sama .Pilih dukungan fitur acara untuk notifikasi yang dapat diperbarui dan diberi tag sebagai
Dapat diupdate eventThreadId
di payload-nya. Gunakan ini
kolom untuk menautkan peristiwa individual bersama-sama untuk memperbarui peristiwa yang ada
notifikasi yang telah dimunculkan kepada pengguna.
Rangkaian peristiwa tidak sama dengan sesi peristiwa. Rangkaian peristiwa mengidentifikasi status yang diperbarui untuk peristiwa sebelumnya di thread yang sama. Tujuan sesi peristiwa mengidentifikasi peristiwa terpisah yang terkait satu sama lain, dan bisa ada beberapa thread peristiwa untuk sesi peristiwa tertentu.
Untuk tujuan notifikasi, berbagai jenis peristiwa dikelompokkan ke dalam .
Pengelompokan thread dan logika pengaturan waktu ini ditangani oleh Google dan tunduk kepada berubah kapan saja. A developer harus memperbarui notifikasi berdasarkan sesi dan thread peristiwa yang disediakan oleh API SDM.
Status thread
Acara yang mendukung notifikasi yang dapat diperbarui juga memiliki eventThreadState
yang menunjukkan status thread peristiwa pada saat itu. Ini
memiliki nilai berikut:
- DIMULAI — Peristiwa pertama dalam rangkaian pesan peristiwa.
- DIPERBARUI — Peristiwa di rangkaian pesan peristiwa yang sedang berlangsung. Mungkin ada nol peristiwa atau lebih dengan status ini dalam satu thread.
- ENDED — Peristiwa terakhir dalam thread peristiwa, yang mungkin merupakan duplikat dari peristiwa yang terakhir DIPERBARUI, bergantung pada jenis thread.
Bidang ini bisa digunakan untuk melacak kemajuan utas peristiwa dan kapan berakhir.
Pemfilteran peristiwa
Dalam beberapa kasus, peristiwa yang terdeteksi oleh perangkat mungkin difilter sehingga tidak dipublikasikan ke topik Pub/Sub SDM. Perilaku ini disebut pemfilteran peristiwa. Tujuan pemfilteran peristiwa adalah untuk menghindari memublikasikan terlalu banyak pesan peristiwa serupa dalam waktu singkat.
Misalnya, pesan mungkin dipublikasikan ke topik SDM untuk peristiwa Gerakan awal. Yang lain pesan untuk Gerakan setelahnya akan menjadi disisihkan dari publikasi hingga jangka waktu tertentu berlalu. Setelah periode tersebut sepanjang waktu, pesan peristiwa untuk jenis peristiwa tersebut dapat dipublikasikan lagi.
Di Aplikasi Google Home (GHA), peristiwa yang yang difilter akan tetap ditampilkan dalam histori peristiwa user. Namun demikian, peristiwa tidak menghasilkan notifikasi aplikasi (meskipun jenis notifikasi tersebut diaktifkan).
Setiap jenis peristiwa memiliki logika pemfilteran peristiwa sendiri, yang ditentukan oleh Google dan dapat berubah kapan saja. Logika pemfilteran peristiwa ini terlepas dari thread peristiwa dan logika sesi.
Akun layanan
Akun layanan direkomendasikan untuk mengelola SDM API langganan dan pesan peristiwa. Akun layanan digunakan oleh aplikasi atau virtual machine, bukan orang, dan memiliki kunci akun uniknya sendiri.
Otorisasi akun layanan untuk penggunaan Pub/Sub API OAuth Berkaki Dua (2LO).
Dalam alur otorisasi 2LO:
- developer meminta token akses menggunakan kunci layanan.
- developer menggunakan token akses dengan panggilan ke API.
Untuk mempelajari lebih lanjut Google 2LO dan cara menyiapkannya, lihat Menggunakan OAuth 2.0 untuk Server ke Server Aplikasi.
Otorisasi
Akun layanan harus diizinkan untuk digunakan dengan API Pub/Sub:
- Mengaktifkan Cloud Pub/Sub API atau komponen lainnya di Google Cloud.
- Buat akun layanan dan kunci akun layanan seperti yang dijelaskan di Membuat akun layanan. Sebaiknya hanya berikan peran Pub/Sub Subscriber. Pastikan untuk download kunci akun layanan ke komputer yang akan menggunakan API Pub/Sub.
- Berikan kredensial autentikasi (kunci akun layanan) Anda ke
kode aplikasi dengan mengikuti petunjuk pada halaman di
langkah pertama, 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 menerima pesan.
Oauth2l
Google oauth2l
adalah alat command line untuk OAuth yang ditulis dalam Go. Instal untuk
Mac atau Linux yang menggunakan Go.
- Jika Anda tidak memiliki Go di sistem, download dan instal terlebih dahulu.
- Setelah Go diinstal, instal
oauth2l
dan tambahkan lokasinya kePATH
Anda variabel lingkungan (lingkungan):go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- Gunakan
oauth2l
untuk mendapatkan token akses untuk API, dengan menggunakan Cakupan OAuth:
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 oauth2l
README untuk penggunaan lebih lanjut
tidak akurat atau tidak sesuai.
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 | PPK | Pemecahan masalah |
---|---|---|
Gambar kamera tidak lagi tersedia untuk didownload. | DEADLINE_EXCEEDED |
Masa berlaku gambar peristiwa akan habis 30 detik setelah peristiwa dipublikasikan. Pastikan untuk mendownload gambar sebelum masa berlakunya habis. |
ID peristiwa bukan bagian dari kamera. | FAILED_PRECONDITION |
Gunakan eventID yang benar yang ditampilkan oleh peristiwa terekam kamera. |
Lihat Referensi Kode Error API untuk daftar lengkap kode error API.