Permulaan Platform Pembangun AqaraLink: Dari Kosong ke Panggilan Pertama

Jawapan ringkas — Laluan yang didokumenkan ada enam langkah: daftar akaun pembangun, cipta projek (menghasilkan appId dan kunci), pilih mod kebenaran, onboard peranti, panggil API, kemudian konfigurasikan tolakan mesej dan senarai putih IP. Pilihan kebenaran mempengaruhi segala yang selepasnya. Akaun Aqara mengikat peranti Aqara Home pengguna sebenar. Kebenaran projek untuk premis B-side yang di-onboard melalui Implementation Tool. Akaun maya mencipta akaun Aqara untuk pengguna akhir anda sendiri supaya aplikasi anda tidak meminta mereka mendaftar dua kali, dan akaun maya itu tidak boleh digunakan dalam Aqara Home, hanya melalui SDK.

Gambaran keseluruhan platform pembangun AqaraLink kami telah menerangkan apa itu platform dan modul yang ada. Catatan ini ialah minggu pertama membina di atasnya: tertib operasi, dan cabang yang perlu dipilih pada minggu pertama.

Enam langkah yang sebenarnya disenaraikan dokumentasi

Dokumen pembangun bahasa Inggeris di opendoc.aqara.com menetapkan proses integrasi awan dalam tertib tetap. Ikut secara literal, kerana dua langkah bergantung pada konfigurasi yang dicipta oleh langkah sebelumnya.

1. Daftar dan log masuk ke platform pembangun Aqara.
2. Cipta aplikasi dan kunci. Projek baharu → isi Project Name, Industry Type, Introduction → Simpan. Projek dipaparkan sebagai pending review; setelah diluluskan status bertukar kepada approved dan butiran projek boleh dilihat. appId ditetapkan kepada projek, dan apabila diluluskan kunci lalai dijana, kelihatan di bawah Project Details → Key Management, tempat anda boleh menambah lagi.
3. Pengurusan kebenaran. Tiga mod, dibincangkan di bawah.
4. Tambah peranti. Tiga laluan, dipilih "mengikut keperluan pembangun dan jenis kebenaran".
5. Pengurusan API. Tanya maklumat peranti, kawal peranti, konfigurasikan pautan.
6. Konfigurasi tolakan mesej, serta tetapan IP pilihan.

Dua fakta daripada senarai itu sering terlepas dan menyebabkan masalah kemudian. Pertama, projek tidak boleh digunakan sehingga diluluskan. Kedua, data pengguna dan peranti diasingkan antara projek, tetapi pengguna yang sama boleh diberi kebenaran kepada berbilang projek. Satu projek bagi setiap pelanggan oleh itu tidak mengasingkan penyewa dalam apa-apa erti yang bermakna; ia hanya menggandakan bilangan bukti kelayakan yang perlu anda putar.

Langkah 3 ialah keputusan sebenar: mod kebenaran yang mana

Inilah cabangnya. Murah untuk dibaca, mahal untuk ditukar selepas UX onboarding anda ditulis.

Baris "Kelihatan dalam Aqara Home" ialah keseluruhan tujuan mod akaun maya, dan kekangan yang ditebalkan ialah bahagian yang menjerat pasukan.

Akaun maya: apa itu dan apa yang bukan

Dokumentasi berterus terang tentang motivasinya. Pembangun yang sudah ada sistem akaun dan mahu membawa peranti Aqara ke dalam ekosistem IoT sendiri tanpa pengguna akhir menyedari dua set akaun, mengintegrasikan SDK peranti Aqara dalam aplikasi sendiri dan mengikat peranti kepada akaun maya yang ditentukan. Akaun maya ditakrifkan sebagai akaun Aqara maya yang dicipta melalui antara muka, yang mana pengguna boleh mengikat peranti melalui SDK terbuka atau implementation tool.

Bagi integrator yang membina untuk pelanggan:

• Anda memiliki identiti. accountId anda, iaitu rentetan yang anda cipta dan dijamin unik di bawah appId, ialah akarnya. Pelanggan anda tidak perlu mencipta akaun Aqara dan tidak perlu tahu ia wujud. Platform memulangkan openId, pengecam unik bagi pengguna maya, iaitu pemegang yang disimpan bahagian belakang anda dan digunakan dalam setiap panggilan berikutnya.
• Kesahan token anda yang tetapkan. config.auth.createAccount menerima boolean pilihan needAccessToken: false memulangkan openId sahaja, true turut memulangkan accessToken, refreshToken dan expiresIn. accessTokenValidity pilihan lalai kepada 7 hari dan menerima 1 hingga 24 jam atau 1 hingga 30 hari. Token segar semula sah sehingga tamat tempoh token akses tambah 30 hari.
• Akaun maya tidak boleh digunakan dalam aplikasi Aqara Home. Jika pengguna akhir anda turut menggunakan Aqara Home, mereka tidak akan melihat peranti yang anda ikat. Putuskan awal-awal sama ada itu boleh diterima, kerana ia tidak dapat dipulihkan oleh sokongan.

Turutan yang didokumenkan, dalam bentuk ringkas

Langkah 1: cipta akaun maya:

`` { "intent": "config.auth.createAccount", "data": { "accountId": "18900001234", "remark": "lumi-1" } } ``

Langkah 2: minta kod kebenaran dengan accountType 2 untuk akaun maya. Kod sah selama 10 minit. Langkah 3: tukarkannya dengan config.auth.getToken untuk mendapatkan accessToken, refreshToken, expiresIn dan openId.

Laluan akaun Aqara sebenar mengikut bentuk yang sama daripada akaun sebenar: config.auth.getAuthCode dengan accountType 0, kod sah 10 minit, kemudian config.auth.getToken, yang token aksesnya lalai kepada 7 hari. Kebenaran projek ialah pertukaran yang sama dengan accountType 1 dan kod daripada konsol IoT Solution Platform. config.auth.refreshToken mengendalikan pembaharuan, dan ketiga-tiganya memulangkan token dengan syarat yang sama: kesahan token segar semula ialah tamat tempoh token akses tambah 30 hari, had keras berapa lama token segar semula yang terlupa boleh wujud.

Semak nama parameter dan nilai jenis akaun semasa berbanding halaman pengurusan kebenaran yang terkini sebelum anda mengekodkannya secara tetap. Dokumen mempunyai versi berasingan daripada integrasi anda.

Setiap permintaan ditandatangani: bahagian yang tidak boleh dilangkau

Panggilan dihantar ke https://${domain}/v3.0/open/api, dengan domain ialah kawasan pelayan. Dokumen menyenaraikan kawasan yang dikerahkan termasuk tanah besar China, Amerika Syarikat, Korea Selatan, Rusia, Eropah dan Singapura, masing-masing dengan domain API dan zon waktu sendiri, dipilih pada projek. Pengepala yang diperlukan: Appid, Keyid (kunci aplikasi anda), Nonce (rentetan rawak, berbeza bagi setiap permintaan) dan Time. Accesstoken hadir apabila antara muka memerlukannya.

Peraturan tandatangan, disahkan daripada halaman peraturan tandatangan: susun parameter pengepala mengikut ASCII dan cantumkan sebagai Accesstoken=xxx&Appid=xxx&Keyid=xxx&Nonce=xxx&Time=xxx, tambah Appkey terus pada rentetan itu, jadikan hasilnya huruf kecil, kemudian MD5, 32-bit. Itulah pengepala Sign anda.

Satu pengecualian yang didokumenkan: sesetengah antara muka tidak memerlukan Accesstoken, dan dalam kes itu Accesstoken tidak mengambil bahagian dalam tandatangan. Tersilap dalam hal ini menghasilkan kod ralat 106 Invalid sign, dan 107 Illegal appKey menangkap kunci yang belum anda aktifkan.

Langkah 4: tiga laluan onboarding, bukan satu

SDK tanpa UI lebih sempit daripada yang dijangka orang: ia hanya digunakan untuk menambah peranti gateway, dengan sub-peranti kemudian ditambah melalui antara muka write.device.openConnect. SDK dengan UI memberikan halaman bergaya Aqara yang boleh digunakan terus atau digayakan semula. Bagi Zigbee, onboarding dipacu oleh hab: aplikasi anda memanggil API HTTP awan untuk meletakkan hab dalam mod pemasangan pasangan, dan hab menemui serta mengikat peranti di sekelilingnya. Satu nota jujur daripada dokumen: tiada pautan muat turun untuk App SDK diterbitkan di platform pembangun, dan halaman mengarahkan pembangun yang mempunyai keperluan supaya menghubungi pasukan perniagaan luar negara Lumi. Rancang perbualan itu sebelum anda merancang sprint.

Satu rumah atau seluruh premis: keputusan penentuan skop

Untuk rumah seorang pelanggan, anda memerlukan projek, senarai putih IP, dan Implementation Tool atau SDK untuk beberapa peranti. Untuk seluruh premis, anda menggunakan kebenaran projek pada Aqara IoT Solution Platform, dengan Implementation Tool mengendalikan penambahan secara kelompok dan kod kebenaran projek ditukar untuk token.

Soalan penentuan skop bukan "berapa banyak peranti", tetapi "identiti siapa yang memegang peranti apabila kontrak tamat". Di bawah akaun maya, peranti pelanggan anda berada dalam akaun yang anda cipta, dan apabila pelanggan itu pergi premis perlu dipindahkan, bukan dinyahtugaskan. Di bawah kebenaran projek, premis berada dalam projek anda dan peranti datang bersama reka bentuk ruang. Tulis siapa yang boleh mencetuskan penyegaran token, kerana orang itu pada hakikatnya mengawal peranti.

Senarai semak larian pertama

• [ ] Status projek tertera approved, bukan pending review
• [ ] appId direkodkan, kunci lalai kelihatan di bawah Key Management
• [ ] Kawasan pelayan dipilih; domain API dan zon waktu dicatat
• [ ] Senarai putih IP diisi: ia kosong secara lalai, jadi mana-mana IP boleh memanggil antara muka anda sehingga anda menyekatnya
• [ ] Mod kebenaran dipilih dan ditulis
• [ ] Penjanaan Nonce disahkan tidak berulang dalam klien HTTP anda
• [ ] Tandatangan tolakan mesej dikonfigurasikan, atau sengaja ditinggalkan
• [ ] Penyahpepijatan peranti dilaksanakan: peranti sebenar di bawah akaun yang diberi kebenaran, atau peranti maya yang anda tambah sendiri (gateway dahulu, kemudian sub-peranti)