Reka Bentuk Langganan Tolakan dan Webhook Aqara untuk Pengeluaran

Jawapan ringkas — Perkhidmatan tolakan mesej Aqara mempunyai dua laluan pengambilan: tolakan HTTP ke alamat yang anda konfigurasikan, dan MQ, yang dinyatakan dalam dokumen sebagai dibina di atas RocketMQ sumber terbuka. Laluan HTTP disahkan secara berkala, statistik kegagalan disimpan, dan peraturan penguatkuasaannya nyata: jika kadar kegagalan tolakan melebihi 5% dalam 5 minit, anda dimaklumkan melalui SMS atau e-mel, dan setengah jam selepas pemberitahuan itu tolakan digantung sehingga anda mengaktifkannya semula dalam konsol. Kedua-dua laluan menyimpan mesej untuk 12 jam terakhir. Setiap mesej membawa msgId dan cap masa milisaat: bina idempotensi dan penyelarasan berdasarkan itu, dan anggap susunan sebagai sesuatu yang anda kendalikan, bukan sesuatu yang diandaikan.

Inilah catatan yang menghalang integrasi anda daripada gagal secara senyap. Integrasi tolakan yang 99 peratus boleh dipercayai kelihatan sempurna dalam demo dan merosakkan data pelanggan pada bulan kedua.

Dua saluran, dan bila masing-masing berbaloi

Dokumentasi berterus terang tentang dua kaedah itu dan sebab kedua-duanya wujud: memenuhi keperluan masa nyata mesej dan ketekalan mesej.

HTTP ialah pilihan lalai bagi kebanyakan integrator. Pilih MQ apabila volum peristiwa setiap peranti anda menjadikan tetingkap kegagalan HTTP 12 jam sebagai jaring keselamatan yang terlalu nipis, atau apabila pengguna anda memang sudah pengguna baris gilir. Perhatikan ketidaksimetrian: bagi HTTP, dokumen menerangkan mekanisme pengesahan dan penjejakan kegagalan yang jelas; bagi MQ, ia menerangkan simpanan dan langganan, tetapi tiada peraturan penguatkuasaan yang setara. Jika anda memilih MQ demi kebolehpercayaan, jangan andaikan ia memulih sendiri dengan cara yang sama.

Apa yang didokumenkan platform, dan apa yang tidak

Fakta yang dinyatakan, daripada halaman tolakan mesej:

• Penghantaran ialah HTTP POST, application/json, ke alamat yang dikonfigurasikan di bawah Console → Project Management → Message push settings.
• Pengepala yang diperlukan: token (token akses sah bagi akaun yang diberi kebenaran), time, dan nonce (rawak, untuk keunikan). Pilihan: appkey dan sign, dipulangkan hanya jika anda mengaktifkan pengesahan tandatangan dengan appKey dan appSecret pada halaman itu.
• Tandatangan tolakan, apabila diaktifkan: susun appkey, nonce, token, time mengikut ASCII → cantumkan sebagai appkey=xxx&nonce=xxx&time=xxx&token=xxx → tambah appSecret → huruf kecil → MD5 32-bit.
• Alamat disahkan dari semasa ke semasa untuk memastikan kebolehpercayaan alamat perkhidmatan dan mekanisme respons penerimaan mesej.
• Ambang kegagalan: melebihi kadar kegagalan 5% dalam 5 minit, pihak ketiga dimaklumkan melalui SMS atau e-mel. Jika tidak diselesaikan, tolakan digantung setengah jam selepas pemberitahuan. Aktifkan semula dalam konsol.
• Mesej tolakan yang gagal disimpan untuk 12 jam terakhir, dengan API pertanyaan disediakan untuknya.

Tidak dinyatakan dalam dokumen bahasa Inggeris, dan wajar disahkan dengan Aqara sebelum bergantung padanya: sekurang-kurangnya sekali berbanding paling banyak sekali, jaminan susunan antara peranti, dasar cuba semula dan bilangan cuba semula bagi POST yang gagal, dan sama ada respons bukan 2xx dikira dalam statistik 5%. Reka bentuk seolah-olah setiap mesej boleh diduplikasi, dilewatkan, disusun semula dan hilang.

Idempotensi: andaikan pengulangan

Keadaan peranti dicetus mengikut aras. Penderia pintu melaporkan terbuka; ia tidak melaporkan satu tepi. Penghantaran semula keadaan yang sama bukan ralat, dan pengguna yang menganggap setiap mesej sebagai baharu akan mengira semuanya dua kali.

Platform memberi anda apa yang diperlukan. Setiap mesej membawa msgId, iaitu id pengenalan unik mesej; time, cap masa apabila mesej dijana, dalam milisaat; openId, pengecam pengguna yang diberi kebenaran; eventType; dan data, dengan data.time sendiri dalam milisaat. Simpan msgId dengan kekangan unik dan buang pendua semasa ketibaan, di tepi pengguna anda, dan letakkan sisipan serta penulisan keadaan dalam transaksi yang sama, kerana jadual nyahpendua yang ditulis di luarnya akan menipu anda.

Tiga kategori mesej tiba, dan ia memerlukan pengendalian berbeza:

1. Mesej pemberitahuan peristiwa: fakta kitaran hayat peranti: ikat dan nyahikat (gateway_bind, subdevice_bind, gateway_unbind, unbind_sub_gw), dalam talian dan luar talian (gateway_online, gateway_offline, subdevice_online, subdevice_offline), dev_name_change, dev_position_assign, serta peristiwa peraturan linkage_created, scene_created, event_created dan pasangan _deleted masing-masing. Dokumen menyatakan semua ini ditolak ke pelayan pihak ketiga, jadi anda tidak boleh menapisnya.
2. Mesej atribut peranti: perubahan keadaan dan pencetus operasi seperti keadaan suis, kuasa beban dan penggunaan kuasa, ditolak mengikut mod langganan yang dipilih pengguna.
3. Mesej kegagalan kawalan peranti: dipulangkan apabila kawalan gagal, dengan sumber pencetus, masa pencetus dan kod ralat. Isyarat satu-satunya yang boleh dipercayai bahawa kawalan yang anda hantar tidak berkesan.

Melanggan: sempitkan, atau lemas

Dokumen jelas bahawa volum data peranti sangat besar, dan anda boleh mengecilkan apa yang diterima. Dua antara muka langganan, kedua-duanya memerlukan tolakan mesej dikonfigurasikan dahulu:

• config.resource.subscribe: senarai sumber, setiap satu dengan subjectId, tatasusunan resourceIds dan rentetan attach pilihan.
• spec.config.trait.subscribe: tatasusunan trait, setiap satu dengan deviceId, tatasusunan codePaths dalam format yang didokumenkan endpointId.functionCode.traitCode, dan attach pilihan.

Medan attach berbaloi digunakan walaupun anda tidak memerlukannya. Ia dilalukan secara telus ke dalam badan pemberitahuan, menjadikannya tempat semula jadi untuk data korelasi anda sendiri: langganan mana, penyewa mana, peranti logik mana. Langgan mengikut penyewa, bukan secara global: premis 2,000 unit yang setiap penggunanya menerima setiap mesej atribut ialah masalah kos dan kependaman yang anda cipta sendiri.

Susunan: dua jam, tiada yang boleh dipercayai

Bandingkan time dengan data.time. Kedua-duanya cap masa milisaat dan ia bukan perkara yang sama: yang luar ialah bila mesej dijana, yang dalam ialah cap masa peristiwa tertentu. Jurang itulah tempat penghantaran tidak berturutan muncul: penderia gerakan tercetus, pencetus kedua tiba semasa yang pertama masih dalam perjalanan, dan clear mendarat sebelum set occupancy. Pengguna yang menggunakannya mengikut tertib ketibaan berakhir dengan bilik yang dipercayai berpenghuni sedangkan kosong. Tanpa jaminan susunan yang didokumenkan:

• Gunakan data.time dalam untuk penulis terakhir menang, bukan tertib ketibaan. Simpan keadaan semasa bersama cap masanya dan tolak kemas kini yang lebih lama daripada yang anda pegang.
• Terima susunan semula pada atribut sementara: kehadiran, gerakan, penghunian. Tetapkan sebagai boolean daripada cap masa terkini, jangan sekali-kali pembilang dan jangan sekali-kali togol.
• Jangan terbitkan keadaan perniagaan daripada ketiadaan mesej. Tiada apa dalam dokumen menjanjikan mesej tamat masa. Ketiadaan data bukan data.

Penyelarasan ialah jawapan sebenar

Jika anda tidak dapat jaminan, anda tidak memerlukannya: anda memerlukan gelung pembaikan. Jadualkan bacaan keadaan penuh berkala bagi peranti yang anda ambil berat dan tulis ganti pandangan setempat anda. Segala yang salah oleh aliran tolakan semasa anda tumbang, tidak berturutan atau dinyahpendua secara salah, bacaan penuh membetulkannya.

Saizkannya untuk menghadkan tetingkap kesalahan yang kelihatan sambil kekal mampu dibayar: imbasan penuh bagi setiap ruang setiap beberapa minit boleh dipertahankan untuk lapisan pengurusan bangunan, setiap jam sudah banyak untuk aplikasi pengguna. Tetingkap simpanan 12 jam bagi tolakan gagal ialah aset di sini: minta penyelarasan menyemak pertanyaan kegagalan itu dahulu, kerana memainkan semula apa yang tercicir lebih murah daripada membaca semula segalanya.

Apabila titik akhir anda tumbang

Laluan kegagalan yang didokumenkan tidak kabur dan ia bergigi: melebihi kadar kegagalan 5% dalam 5 minit, anda dimaklumkan melalui SMS atau e-mel; setengah jam selepas pemberitahuan itu, tolakan digantung sehingga anda mengaktifkannya semula dalam konsol. Penempatan dua puluh minit boleh meninggalkan integrasi anda tanpa langganan secara senyap, dengan satu-satunya amaran pada telefon yang tiada siapa pantau.

Pertahanan, mengikut nilai:

• Pulangkan 2xx dengan pantas. Akui dahulu, kemudian proses, pada baris gilir di belakang pengendali.
• Beri amaran pada saluran platform, bukan sekadar saluran anda sendiri. SMS/e-mel tiba sebelum penggantungan anda. Salurkan kepada sesiapa yang boleh bertindak dalam beberapa minit.
• Pantau kadar tercicir anda sendiri. Kadar ralat 5 minit yang menghampiri 5% meletakkan anda dalam tetingkap penguatkuasaan sama ada atau tidak ada yang perasan.
• Automasikan laluan pengaktifan semula atau tulis buku panduan sebelum anda memerlukannya. Tolakan yang digantung ialah togol konsol, dan pada pukul 2 pagi togol itulah keseluruhan insiden.
• Gagal dengan lantang dalam produk. UI yang menunjukkan "dikemas kini 4 jam lalu" mengalahkan amaran yang tiada siapa baca.

Senarai semak pra-pengeluaran

• [ ] Pengesahan tandatangan diaktifkan dan diuji, atau sengaja ditinggalkan
• [ ] Kekangan unik msgId dalam transaksi yang sama dengan perubahan keadaan
• [ ] Langganan diskopkan mengikut penyewa, bukan global; attach digunakan untuk korelasi
• [ ] Penulis terakhir menang berdasarkan data.time, bukan tertib ketibaan
• [ ] Mesej kegagalan kawalan disalurkan ke tempat yang akan dilihat manusia
• [ ] Penyelarasan keadaan penuh berkala dijadualkan dan dikosnkan
• [ ] Amaran kadar kegagalan pada margin selamat di bawah 5% dalam 5 minit
• [ ] Buku panduan untuk mengaktifkan semula tolakan yang digantung
• [ ] Jaminan penghantaran, susunan, dasar cuba semula dan had kadar disahkan dengan Aqara secara bertulis