Amalan Terbaik

Gunakan corak ini untuk memastikan integrasi rakan kongsi boleh dijangka, boleh diperhatikan dan selamat untuk kemudahan.

Kenal pasti kemudahan secara konsisten

Pilih kaedah pemautan yang dikonfigurasikan untuk akaun rakan kongsi anda dan gunakannya secara konsisten:

Direct Link - gunakan facility_id Performance Hub yang dikembalikan oleh titik akhir kemudahan.
Linking Identifier - gunakan pengecam lokasi anda sendiri, seperti ID cawangan, kod lokasi atau nombor kedai.

Jangan hantar kedua-dua pengecam dalam permintaan yang sama. Performance Hub menyelesaikan permintaan menggunakan kaedah pemautan yang dikonfigurasikan untuk akaun rakan kongsi anda.

Lihat Kaedah Pemautan Rakan Kongsi untuk panduan persediaan.

Tulis secara kelompok dengan berhati-hati

Partner API menerima badan permintaan JSON dan direka untuk aliran kerja penyegerakan berasaskan kelompok di mana didokumenkan. Pastikan kelompok terhad saiznya dan boleh dicuba semula.

Panduan lalai:

Gunakan sehingga 1000 item bagi setiap permintaan kelompok untuk prestasi optimum.
Pastikan muatan di bawah 10MB.
Kekal dalam had 5 permintaan sesaat bagi setiap titik akhir.

Had kadar boleh dilaraskan dan boleh dikonfigurasikan mengikut kes oleh pengurus akaun rakan kongsi Performance Hub anda. Jika anda menjangkakan import volum tinggi, trafik pelancaran atau pengisian semula laporan, persetujui daya pemprosesan yang diperlukan sebelum tetingkap perubahan.

Jika anda perlu menyegerakkan set data yang besar, bahagikannya kepada cebisan yang deterministik dan log setiap ID cebisan di pihak anda. Ini memudahkan anda memahami cubaan semula yang gagal.

Cuba semula dengan selamat

Gunakan penundaan eksponen untuk kegagalan sementara seperti 429, 500, 502, 503 dan 504.

Elakkan gelung cubaan semula yang rapat. Titik permulaan yang baik ialah:

Cuba semula selepas 1 saat.
Cuba semula selepas 2 saat.
Cuba semula selepas 4 saat.
Berhenti dan beri amaran jika operasi masih gagal.

Untuk kegagalan pengesahan seperti 400 atau 422, betulkan permintaan sebelum mencuba semula.

Gunakan idempotensi jika disokong

Titik akhir buka kunci Door/Gate Controller menyokong idempotency_key pilihan. Menggunakan semula kunci yang sama untuk rakan kongsi, kemudahan dan pintu yang sama mengembalikan hasil sedia ada apabila tersedia.

Gunakan kunci yang stabil untuk tindakan yang dilakukan, contohnya ID daftar masuk atau ID peristiwa akses daripada sistem anda.

Jangan anggap setiap titik akhir tulis menyokong idempotensi melainkan ia didokumenkan untuk titik akhir tersebut.

Pastikan data sumber bersih

Hantar nilai yang stabil dan dinormalkan di mana-mana yang boleh:

Gunakan ID ahli, pelan, kemudahan dan daftar masuk yang konsisten daripada sistem sumber anda.
Gunakan cap masa ISO 8601 untuk tarikh dan masa.
Hantar nombor telefon dalam format antarabangsa jika ada.
Hantar mata wang menggunakan medan yang didokumenkan untuk setiap titik akhir.
Elakkan membebankan medan teks bebas dengan data yang sepatutnya berada dalam medan berstruktur.

Reka untuk penyegerakan tokokan dan penuh

Kebanyakan integrasi rakan kongsi memerlukan kedua-duanya:

Penyegerakan tokokan untuk perubahan harian.
Penyegerakan penyesuaian penuh untuk membetulkan peristiwa yang terlepas, import sejarah atau hanyutan data.

Integrasi anda sepatutnya dapat menghantar semula keadaan semasa bagi ahli, pelan keahlian atau petikan laporan tanpa bergantung pada kejayaan permintaan sebelumnya.

Terbitkan Access Time Windows dengan selamat

Anggap nilai access_time_windows setiap ahli sebagai petikan lengkap yang disemak secara bebas:

Selaraskan satu aliran access_time_windows_revision yang meningkat secara monoton merentas pekerja tokokan dan penyesuaian.
Cuba semula penghantaran yang tidak pasti atau sementara dengan semakan dan muatan dinormalkan yang sama.
Tinggalkan access_time_windows apabila anda tidak mengemas kininya.
Hantar [] hanya selepas pengambilan sumber berautoriti yang berjaya membuktikan bahawa tiada tetingkap yang tinggal. Jangan sekali-kali jadikan tamat masa huluan, hasil separa atau kegagalan penghuraian sebagai pembatalan.
Pastikan external_id dan scope_key stabil, dan sahkan setiap pemetaan skop sebelum pengeluaran.
Pantau usia sumber berbanding dasar kesegaran yang dipersetujui untuk integrasi tersebut.

Lihat panduan pengeluar Access Time Windows yang berautoriti untuk petikan lengkap, zon waktu, DST, pembatalan dan vektor ujian.

Anggap kawalan akses sebagai kritikal keselamatan

Untuk buka kunci Door/Gate Controller:

Sistem anda mesti memutuskan sama ada orang itu dibenarkan masuk sebelum memanggil Performance Hub.
Performance Hub mengembalikan 200 hanya selepas pengawal di premis mengesahkan geganti telah dibuka kunci secara fizikal.
Kebanyakan pengesahan selesai dalam 3-5 saat.
Tamat masa ialah buka kunci yang gagal secara jelas, bukan kejayaan di latar belakang.
Cuba semula hanya mengikut peraturan akses dan keselamatan anda sendiri.

Sentiasa log event_id dan command_id yang dikembalikan oleh titik akhir buka kunci.

Pantau integrasi anda

Gunakan log permintaan Partner Console semasa pembangunan dan pelancaran. Dalam pengeluaran, selenggarakan juga log anda sendiri dengan:

Cap masa permintaan.
Titik akhir.
ID rekod sumber.
Pengecam kemudahan.
Kod status HTTP.
Badan respons atau mesej ralat Performance Hub.

Medan ini menjadikan sokongan dan penyesuaian jauh lebih pantas apabila pelanggan bertanya apa yang berlaku.