Acara

Peristiwa bersifat asinkron dan dikelola oleh Google Cloud Pub/Sub, dalam satu topik per Project. Peristiwa memberikan update untuk semua perangkat dan struktur, dan penerimaan peristiwa terjamin selama token akses tidak dicabut oleh pengguna dan pesan peristiwa belum berakhir masa berlakunya.

Aktifkan acara

Peristiwa adalah fitur opsional SDM API. Lihat Mengaktifkan peristiwa untuk mempelajari cara mengaktifkannya untuk ProjectAnda.

Google Cloud Pub/Sub

Lihat dokumentasi Google Cloud Pub/Sub untuk mempelajari lebih lanjut cara kerja Pub/Sub. Khususnya:

Langganan acara

Saat peristiwa diaktifkan untuk Project, Anda akan diberi topik khusus untuk ID Project tersebut, dalam bentuk:

projects/sdm-prod/topics/enterprise-project-id

Untuk menerima peristiwa, buat langganan pull atau push ke topik tersebut, bergantung pada kasus penggunaan Anda. Beberapa langganan ke topik SDM didukung. Lihat Mengelola langganan untuk mengetahui informasi selengkapnya.

Memulai peristiwa

Untuk memulai peristiwa untuk pertama kalinya setelah langganan Pub/Sub dibuat, buat panggilan API devices.list sebagai pemicu satu kali. Peristiwa untuk semua struktur dan perangkat akan dipublikasikan setelah panggilan ini.

Sebagai contoh, lihat halaman Otorisasi di Panduan Memulai Cepat.

Urutan peristiwa

Pub/Sub tidak menjamin pengiriman peristiwa yang teratur, dan urutan penerimaan peristiwa mungkin tidak sesuai dengan urutan peristiwa yang sebenarnya terjadi. Gunakan kolom timestamp untuk membantu rekonsiliasi urutan peristiwa. Peristiwa juga dapat diterima satu per satu atau digabungkan menjadi satu pesan peristiwa.

Untuk informasi selengkapnya, lihat Mengurutkan pesan.

ID pengguna

Jika penerapan Anda didasarkan pada pengguna (bukan struktur atau perangkat), gunakan kolom userID dari payload peristiwa untuk mengaitkan 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 relasi

Peristiwa relasi mewakili pembaruan relasional untuk resource. Misalnya, saat perangkat ditambahkan ke struktur, atau saat perangkat dihapus dari struktur.

Ada tiga jenis peristiwa hubungan:

  • CREATED
  • DIHAPUS
  • DIPERBARUI

Payload untuk peristiwa hubungan adalah sebagai berikut:

Payload

{
  "eventId" : "d5c0f0bd-de65-44fd-ac60-686c302e56eb",
  "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 kini memiliki hubungan dengan object. Dalam contoh di atas, user telah memberikan akses ke perangkat tertentu ini ke developer, dan perangkat resmi userkini terkait dengan struktur resminya, yang memicu peristiwa.

subject hanya dapat berupa ruang 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: "64b87b46-1aec-42a4-8c01-997a407814df"
timestamp Waktu saat peristiwa terjadi. string
Contoh: "2019-01-01T00:00:01Z"
relationUpdate Objek yang menjelaskan informasi tentang pembaruan relasi. object
userId ID unik yang di-obfuscate yang mewakili pengguna. string
Contoh: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

Lihat Peristiwa untuk mengetahui informasi selengkapnya tentang berbagai jenis peristiwa dan cara kerjanya.

Contoh

Payload peristiwa berbeda untuk setiap jenis peristiwa hubungan:

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 hubungan tidak dikirim jika:

  • Ruang dihapus

Peristiwa resource

Peristiwa resource mewakili update khusus untuk resource. Hal ini dapat dilakukan sebagai respons terhadap perubahan nilai kolom sifat, seperti mengubah mode termostat. Tindakan ini juga dapat mewakili tindakan perangkat yang tidak mengubah kolom sifat seperti menekan tombol perangkat.

Peristiwa yang dihasilkan sebagai respons terhadap perubahan nilai kolom ciri berisi objek traits, mirip dengan panggilan GET perangkat:

Payload

{
  "eventId" : "a88bc884-d2b8-42d6-adba-b7be92c232a3",
  "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 setiap karakteristik untuk memahami format payload untuk setiap peristiwa resource perubahan kolom karakteristik.

Peristiwa yang dihasilkan sebagai respons terhadap tindakan perangkat yang tidak mengubah kolom karakteristik juga memiliki payload dengan objek resourceUpdate, tetapi dengan objek events, bukan objek traits:

Payload

{
  "eventId" : "4f80de08-1b77-42a4-b33e-40876a2a1865",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "MWJ253hZMPAsJZJWbrGM4ThsKM...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Jenis peristiwa resource ini ditentukan dalam karakteristik tertentu. Misalnya, Peristiwa gerakan ditentukan dalam sifat CameraMotion . Lihat dokumentasi setiap karakteristik untuk memahami format payload untuk jenis peristiwa resource ini.

Kolom

Kolom Deskripsi Jenis Data
eventId ID unik untuk peristiwa. string
Contoh: "4f80de08-1b77-42a4-b33e-40876a2a1865"
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", "UPDATED", "ENDED"
resourceGroup Objek yang menunjukkan resource yang mungkin memiliki update serupa dengan peristiwa ini. Resource peristiwa itu sendiri (dari objek resourceUpdate) akan selalu ada dalam objek ini. object

Lihat Peristiwa untuk mengetahui informasi selengkapnya tentang berbagai jenis peristiwa dan cara kerjanya.

Notifikasi yang dapat diperbarui

Notifikasi berdasarkan peristiwa resource dapat diterapkan di aplikasi, seperti untuk Android atau iOS. Untuk mengurangi jumlah notifikasi yang dikirim, fitur yang disebut notifikasi yang dapat diperbarui dapat diterapkan, dengan notifikasi yang ada diperbarui dengan informasi baru berdasarkan peristiwa berikutnya dalam thread peristiwa yang sama.

Peristiwa tertentu memiliki dukungan fitur untuk notifikasi yang dapat diperbarui dan diberi tag sebagai Dapat diperbarui  dalam dokumentasi. Peristiwa ini memiliki kolom tambahan yang disebut eventThreadId dalam payload-nya. Gunakan kolom ini untuk menautkan setiap peristiwa secara bersamaan dengan tujuan memperbarui notifikasi yang ada yang telah ditampilkan untuk 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 saling terkait, dan dapat ada 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 dan sesi peristiwa yang disediakan oleh SDM API.

Status thread

Peristiwa yang mendukung notifikasi yang dapat diperbarui juga memiliki kolom eventThreadState yang menunjukkan status thread peristiwa pada saat itu. Kolom ini memiliki nilai berikut:

  • STARTED — Peristiwa pertama dalam thread peristiwa.
  • DIPERBARUI — Peristiwa dalam rangkaian pesan peristiwa yang sedang berlangsung. Dalam satu thread, dapat ada nol atau beberapa peristiwa dengan status ini.
  • ENDED — Peristiwa terakhir dalam rangkaian peristiwa, yang mungkin merupakan duplikat dari peristiwa UPDATED terakhir, bergantung pada jenis rangkaian peristiwa.

Kolom ini dapat digunakan untuk melacak progres thread peristiwa dan saat peristiwa berakhir.

Pemfilteran peristiwa

Dalam beberapa kasus, peristiwa yang terdeteksi oleh perangkat dapat difilter agar 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 dapat dipublikasikan ke topik SDM untuk peristiwa Gerakan awal. Pesan lain untuk Motion setelah itu akan difilter dari publikasi hingga jangka waktu yang ditetapkan 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 logika sesi dan thread peristiwa.

Akun layanan

Akun layanan direkomendasikan untuk mengelola pesan peristiwa dan langganan SDM API. Akun layanan digunakan oleh aplikasi atau virtual machine, bukan orang, dan memiliki kunci akun unik sendiri.

Otorisasi akun layanan untuk Pub/Sub API menggunakan OAuth 2-legged (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 menyiapkannya, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server.

Otorisasi

Akun layanan harus diberi otorisasi untuk digunakan dengan Pub/Sub API:

  1. Aktifkan Cloud Pub/Sub API di Google Cloud.
  2. Buat akun layanan dan kunci akun layanan seperti yang dijelaskan dalam Membuat akun layanan. Sebaiknya berikan peran Pub/Sub Subscriber saja. Pastikan untuk mendownload kunci akun layanan ke komputer yang akan menggunakan Pub/Sub API.
  3. 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.
  4. Gunakan kredensial akun layanan atau token akses dengan Pub/Sub project.subscriptions API untuk mengambil dan mengonfirmasi pesan.

oauth2l

Google oauth2l adalah alat command line untuk OAuth yang ditulis dalam Go. Instal untuk Mac atau Linux menggunakan Go.

  1. Jika Anda tidak memiliki Go di sistem, download dan instal terlebih dahulu.
  2. Setelah Go diinstal, instal oauth2l dan tambahkan lokasinya ke variabel lingkungan PATH: 
    go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
  3. Gunakan oauth2l untuk mendapatkan token akses API, menggunakan cakupan OAuth yang sesuai: 
    oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
    Misalnya, jika kunci layanan Anda berada di ~/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 mengetahui 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 mengetahui 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 dapat ditampilkan sehubungan dengan panduan ini:

Pesan Error PPK Pemecahan masalah
Gambar kamera tidak lagi tersedia untuk didownload. DEADLINE_EXCEEDED Masa berlaku gambar acara berakhir 30 detik setelah acara dipublikasikan. Pastikan untuk mendownload gambar sebelum masa berlakunya habis.
ID peristiwa bukan milik kamera. FAILED_PRECONDITION Gunakan eventID yang benar yang ditampilkan oleh peristiwa kamera.

Lihat Referensi Kode Error API untuk mengetahui daftar lengkap kode error API.