Acara

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

Mengaktifkan peristiwa

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

Google Cloud Pub/Sub

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

Pelajari dasar-dasar Pub/Sub dengan panduan Cara.
Pahami cara kerja Autentikasi.
Pilih Library Klien yang disediakan atau tulis library Anda sendiri dan gunakan REST/HTTP atau gRPC API.

Langganan peristiwa

Sebelum Januari 2025, jika peristiwa diaktifkan untuk Project, Anda akan diberikan topik khusus untuk Project ID tersebut, dalam bentuk:

projects/gcp-project-name/subscriptions/topic-id

Project yang dibuat setelah Januari 2025 harus menghosting sendiri topik Pub/Sub, dan Anda harus memberikan ID topik Anda sendiri. Lihat Membuat topik untuk mengetahui informasi selengkapnya.

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, lakukan panggilan API devices.list sebagai pemicu satu kali. Peristiwa untuk semua struktur dan perangkat akan dipublikasikan setelah panggilan ini.

Untuk contohnya, lihat halaman Otorisasi di Panduan Memulai Cepat Guide.

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 tiba satu per satu atau digabungkan ke dalam satu pesan peristiwa.

Untuk mengetahui informasi selengkapnya, lihat Mengurutkan pesan.

ID pengguna

Jika penerapan Anda didasarkan pada pengguna (bukan struktur atau perangkat), gunakan kolom userID dari payload peristiwa untuk mengorelasikan 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 di tambahkan 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" : "904c338e-7c6c-47e9-99be-7b658c422d0e",
  "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 the subject adalah resource yang kini memiliki relasi dengan object. Dalam contoh di atas, a user telah memberikan akses ke perangkat tertentu ini ke a developer, dan perangkat resmi user's sekarang terkait dengan struktur resmi mereka, yang memicu peristiwa.

subject hanya dapat berupa ruangan atau struktur. Jika a developer tidak memiliki izin untuk melihat user's struktur, subject akan selalu kosong.

Kolom

Kolom	Deskripsi	Jenis Data
`eventId`	ID unik peristiwa.	`string` Contoh: "47768f2e-b925-4911-84d1-772671b14fe3"
`timestamp`	Waktu 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 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:

Ruangan dihapus

Peristiwa resource

Peristiwa resource mewakili pembaruan khusus untuk resource. Peristiwa ini dapat berupa respons terhadap perubahan nilai kolom trait, seperti mengubah mode termostat. Peristiwa ini juga dapat mewakili tindakan perangkat yang tidak mengubah kolom trait, seperti menekan tombol perangkat.

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

Payload

{
  "eventId" : "a95d10a9-8319-4ed0-907b-71574bffad61",
  "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 trait individual untuk memahami format payload untuk peristiwa resource perubahan kolom trait event.

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" : "20aa9878-6dbd-4de4-9a6d-07e749e3f497",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "-NM0xCrbLkZ0E9VCRk0ndIUvN6...",
      }
    }
  }
  "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 trait tertentu. Misalnya, peristiwa Gerakan ditentukan dalam CameraMotion trait. Lihat dokumentasi setiap trait untuk memahami format payload untuk jenis peristiwa resource ini.

Kolom

Kolom	Deskripsi	Jenis Data
`eventId`	ID unik peristiwa.	`string` Contoh: "20aa9878-6dbd-4de4-9a6d-07e749e3f497"
`timestamp`	Waktu peristiwa terjadi.	`string` Contoh: "2019-01-01T00:00:01Z"
`resourceUpdate`	Objek yang menjelaskan informasi tentang perubahan resource.	`object`
`userId`	ID unik yang di-obfuscate yang mewakili pengguna.	`string` Contoh: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	ID unik untuk rangkaian peristiwa.	`string` Contoh: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
`eventThreadState`	Status rangkaian peristiwa.	`string` Nilai: "STARTED", "UPDATED", "ENDED"
`resourceGroup`	Objek yang menunjukkan resource yang mungkin memiliki perubahan 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 rangkaian peristiwa yang sama.

Pilih dukungan fitur peristiwa 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 peristiwa individual untuk tujuan memperbarui notifikasi yang ada yang telah ditampilkan untuk pengguna.

Rangkaian peristiwa tidak sama dengan sesi peristiwa. Rangkaian peristiwa mengidentifikasi status yang diperbarui untuk peristiwa sebelumnya dalam rangkaian yang sama. Sesi peristiwa mengidentifikasi peristiwa terpisah yang terkait satu sama lain, dan dapat ada beberapa rangkaian peristiwa untuk sesi peristiwa tertentu.

Untuk tujuan notifikasi, berbagai jenis peristiwa dikelompokkan ke dalam rangkaian yang berbeda.

Logika waktu dan pengelompokan rangkaian ini ditangani oleh Google dan dapat berubah kapan saja. A developer harus memperbarui notifikasi berdasarkan rangkaian dan sesi peristiwa yang disediakan oleh SDM API.

Status rangkaian

Peristiwa yang mendukung notifikasi yang dapat diperbarui juga memiliki kolom eventThreadState yang menunjukkan status rangkaian peristiwa pada waktu tersebut. Kolom ini memiliki nilai berikut:

STARTED — Peristiwa pertama dalam rangkaian peristiwa.
UPDATED — Peristiwa dalam rangkaian peristiwa yang sedang berlangsung. Dapat ada nol atau lebih peristiwa dengan status ini dalam satu rangkaian.
ENDED — Peristiwa terakhir dalam rangkaian peristiwa, yang mungkin merupakan duplikat dari peristiwa UPDATED terakhir, bergantung pada jenis rangkaian.

Kolom ini dapat digunakan untuk melacak progres rangkaian peristiwa dan kapan rangkaian tersebut berakhir.

Pemfilteran peristiwa

Dalam beberapa kasus, peristiwa yang terdeteksi oleh perangkat dapat 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 Gerakan setelah itu akan difilter agar tidak dipublikasikan 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 user's histori peristiwa. Namun, peristiwa tersebut 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 independen dari logika rangkaian dan sesi peristiwa.

Akun layanan

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

Otorisasi akun layanan untuk Pub/Sub API menggunakan OAuth Dua Kaki (2LO).

Dalam alur otorisasi 2LO:

Meminta token akses menggunakan kunci layanan. developer
developer Menggunakan token akses dengan panggilan ke API.

Untuk mempelajari lebih lanjut Google 2LO dan cara menyiapkan, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server.

Otorisasi

Akun layanan harus diotorisasi 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 berikan peran Pelanggan Pub/Sub saja. Pastikan untuk mendownload kunci akun layanan ke mesin yang akan menggunakan Pub/Sub API.
Berikan kredensial autentikasi Anda (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 mengambil dan mengonfirmasi pesan.

oauth2l

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

Jika Anda tidak memiliki Go di sistem Anda, download dan instal terlebih dahulu.
Setelah Go diinstal, instal oauth2l dan tambahkan lokasinya ke variabel lingkungan PATH Anda:
```
go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
```

Gunakan oauth2l untuk mendapatkan token akses untuk 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 oauth2l README 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 terkait dengan panduan ini:

Pesan Error	RPC	Pemecahan masalah
Gambar kamera tidak lagi tersedia untuk didownload.	`DEADLINE_EXCEEDED`	Gambar peristiwa akan habis masa berlakunya 30 detik setelah peristiwa 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 API Error Code Reference untuk mengetahui daftar lengkap kode error API.

Acara Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Mengaktifkan peristiwa

Google Cloud Pub/Sub

Langganan peristiwa

Memulai peristiwa

Urutan peristiwa

ID pengguna

Peristiwa relasi

Payload

Kolom

Contoh

DIBUAT

Struktur dibuat

Perangkat dibuat

Perangkat dibuat

DIPERBARUI

Perangkat dipindahkan

DIHAPUS

Struktur dihapus

Perangkat dihapus

Perangkat dihapus

Peristiwa resource

Payload

Payload

Kolom

Notifikasi yang dapat diperbarui

Status rangkaian

Pemfilteran peristiwa

Akun layanan

Otorisasi

oauth2l

Library Klien Google API

Error

Acara