แนวทางปฏิบัติที่ดีที่สุด

ใช้รูปแบบเหล่านี้เพื่อให้การผสานรวมของพาร์ทเนอร์คาดการณ์ได้ ตรวจสอบได้ และปลอดภัยสำหรับสถานที่

ระบุสถานที่อย่างสม่ำเสมอ

เลือกวิธีการเชื่อมโยงที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณ และใช้อย่างสม่ำเสมอ:

• Direct Link - ใช้ facility_id ของ Performance Hub ที่ส่งคืนจากปลายทางสถานที่
• Linking Identifier - ใช้ตัวระบุตำแหน่งที่ตั้งของคุณเอง เช่น ID สาขา รหัสตำแหน่งที่ตั้ง หรือหมายเลขร้านค้า

อย่าส่งตัวระบุทั้งสองแบบในคำขอเดียวกัน Performance Hub จะประมวลผลคำขอโดยใช้วิธีการเชื่อมโยงที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณ

ดูคำแนะนำในการตั้งค่าได้ที่วิธีการเชื่อมโยงของพาร์ทเนอร์

เขียนข้อมูลแบบกลุ่มอย่างระมัดระวัง

Partner API รองรับเนื้อหาคำขอแบบ JSON และออกแบบมาสำหรับขั้นตอนการซิงค์แบบกลุ่มในส่วนที่มีการระบุไว้ในเอกสาร ให้จำกัดขนาดของแต่ละกลุ่มและออกแบบให้ลองใหม่ได้

แนวทางเริ่มต้น:

• ใช้ไม่เกิน 1000 รายการต่อคำขอแบบกลุ่ม เพื่อประสิทธิภาพสูงสุด
• รักษาขนาดเพย์โหลดให้ต่ำกว่า 10MB
• ไม่เกิน 5 คำขอต่อวินาทีต่อปลายทาง

ขีดจำกัดอัตราการเรียกใช้สามารถปรับได้ และผู้จัดการบัญชีพาร์ทเนอร์ของ Performance Hub สามารถกำหนดค่าเป็นรายกรณีได้ หากคุณคาดว่าจะมีการนำเข้าข้อมูลปริมาณมาก ทราฟฟิกช่วงเปิดตัว หรือการเติมข้อมูลรายงานย้อนหลัง ให้ตกลงปริมาณงานที่ต้องการก่อนถึงช่วงเวลาการเปลี่ยนแปลง

หากต้องการซิงค์ชุดข้อมูลขนาดใหญ่ ให้แบ่งออกเป็นส่วนย่อยที่กำหนดแน่นอน และบันทึก ID ของแต่ละส่วนไว้ฝั่งคุณ วิธีนี้ช่วยให้วิเคราะห์การลองใหม่ที่ล้มเหลวได้ง่ายขึ้น

ลองใหม่อย่างปลอดภัย

ใช้การเว้นระยะแบบเอ็กซ์โพเนนเชียล (exponential backoff) สำหรับความล้มเหลวชั่วคราว เช่น 429, 500, 502, 503 และ 504

หลีกเลี่ยงการลองใหม่แบบวนซ้ำถี่ ๆ จุดเริ่มต้นที่ดีคือ:

1. ลองใหม่หลังจาก 1 วินาที
2. ลองใหม่หลังจาก 2 วินาที
3. ลองใหม่หลังจาก 4 วินาที
4. หยุดและแจ้งเตือนหากการดำเนินการยังคงล้มเหลว

สำหรับความล้มเหลวในการตรวจสอบความถูกต้อง เช่น 400 หรือ 422 ให้แก้ไขคำขอก่อนลองใหม่

ใช้ Idempotency ในส่วนที่รองรับ

ปลายทางปลดล็อก Door/Gate Controller รองรับ idempotency_key แบบไม่บังคับ การใช้คีย์เดิมซ้ำสำหรับพาร์ทเนอร์ สถานที่ และประตูเดียวกันจะส่งคืนผลลัพธ์ที่มีอยู่เมื่อมี

ใช้คีย์ที่คงที่สำหรับการดำเนินการที่ทำอยู่ เช่น ID การเช็กอินหรือ ID เหตุการณ์การเข้าถึงจากระบบของคุณ

อย่าสันนิษฐานว่าปลายทางการเขียนทุกตัวรองรับ Idempotency เว้นแต่จะระบุไว้ในเอกสารของปลายทางนั้น

รักษาข้อมูลต้นทางให้สะอาด

ส่งค่าที่คงที่และเป็นมาตรฐานทุกครั้งที่ทำได้:

• ใช้ ID ของสมาชิก แผน สถานที่ และการเช็กอินที่สอดคล้องกันจากระบบต้นทางของคุณ
• ใช้การประทับเวลาแบบ ISO 8601 สำหรับวันที่และเวลา
• ส่งหมายเลขโทรศัพท์ในรูปแบบสากลหากมี
• ส่งสกุลเงินโดยใช้ฟิลด์ที่ระบุไว้ในเอกสารของแต่ละปลายทาง
• หลีกเลี่ยงการใส่ข้อมูลที่ควรอยู่ในฟิลด์แบบมีโครงสร้างลงในฟิลด์ข้อความอิสระมากเกินไป

ออกแบบสำหรับการซิงค์แบบส่วนเพิ่มและแบบเต็ม

การผสานรวมของพาร์ทเนอร์ส่วนใหญ่ต้องใช้ทั้งสองแบบ:

• การซิงค์แบบส่วนเพิ่ม สำหรับการเปลี่ยนแปลงในแต่ละวัน
• การซิงค์เพื่อกระทบยอดแบบเต็ม เพื่อแก้ไขเหตุการณ์ที่ตกหล่น การนำเข้าข้อมูลย้อนหลัง หรือข้อมูลที่คลาดเคลื่อน

การผสานรวมของคุณควรส่งสถานะปัจจุบันของสมาชิก แผนสมาชิก หรือสแนปช็อตรายงานซ้ำได้ โดยไม่ขึ้นอยู่กับว่าคำขอก่อนหน้าสำเร็จหรือไม่

เผยแพร่ Access Time Windows อย่างปลอดภัย

ให้ถือว่าค่า access_time_windows ของสมาชิกแต่ละรายเป็นสแนปช็อตที่สมบูรณ์และมีการกำหนดเวอร์ชันแยกกันอย่างอิสระ:

• ประสานสตรีม access_time_windows_revision ที่เพิ่มขึ้นทางเดียวเพียงสตรีมเดียวระหว่างเวิร์กเกอร์แบบส่วนเพิ่มและเวิร์กเกอร์กระทบยอด
• ลองส่งใหม่สำหรับการส่งที่ไม่แน่นอนหรือล้มเหลวชั่วคราว โดยใช้เวอร์ชันเดิมและเพย์โหลดที่ปรับให้เป็นมาตรฐานแบบเดิม
• เว้น access_time_windows ไว้เมื่อคุณไม่ได้อัปเดตค่านี้
• ส่ง [] ก็ต่อเมื่อการดึงข้อมูลจากแหล่งที่เชื่อถือได้สำเร็จและพิสูจน์แล้วว่าไม่มีช่วงเวลาเหลืออยู่เท่านั้น อย่าเปลี่ยนการหมดเวลาของต้นทาง ผลลัพธ์ที่ไม่ครบถ้วน หรือความล้มเหลวในการแยกวิเคราะห์ให้กลายเป็นการเพิกถอนสิทธิ์
• รักษา external_id และ scope_key ให้คงที่ และรับรองการจับคู่ขอบเขตทุกรายการก่อนใช้งานจริง
• ติดตามอายุของข้อมูลต้นทางเทียบกับนโยบายความเป็นปัจจุบันที่ตกลงไว้สำหรับการผสานรวมนั้น

ดูคู่มือผู้ส่งข้อมูล Access Time Windows ฉบับทางการ สำหรับสแนปช็อตแบบสมบูรณ์ เขตเวลา DST การยกเลิก และเวกเตอร์ทดสอบ

ถือว่าการควบคุมการเข้าถึงมีความสำคัญด้านความปลอดภัย

สำหรับการปลดล็อก Door/Gate Controller:

• ระบบของคุณต้องตัดสินว่าบุคคลนั้นได้รับอนุญาตให้เข้าหรือไม่ก่อนเรียก Performance Hub
• Performance Hub จะส่งคืน 200 ก็ต่อเมื่อตัวควบคุมในสถานที่ยืนยันว่ารีเลย์ปลดล็อกทางกายภาพแล้วเท่านั้น
• การยืนยันส่วนใหญ่เสร็จสิ้นภายใน 3-5 วินาที
• การหมดเวลาถือเป็นการปลดล็อกที่ล้มเหลวอย่างชัดเจน ไม่ใช่ความสำเร็จที่เกิดขึ้นเบื้องหลัง
• ลองใหม่ตามกฎด้านการเข้าถึงและความปลอดภัยของคุณเองเท่านั้น

บันทึก event_id และ command_id ที่ส่งคืนจากปลายทางปลดล็อกทุกครั้ง

ติดตามการผสานรวมของคุณ

ใช้บันทึกคำขอใน Partner Console ระหว่างการพัฒนาและการเปิดตัว ในการใช้งานจริง ให้เก็บบันทึกของคุณเองด้วย โดยมีข้อมูลต่อไปนี้:

• การประทับเวลาของคำขอ
• ปลายทาง
• ID ของเรคคอร์ดต้นทาง
• ตัวระบุสถานที่
• รหัสสถานะ HTTP
• เนื้อหาการตอบกลับหรือข้อความแสดงข้อผิดพลาดจาก Performance Hub

ฟิลด์เหล่านี้ช่วยให้การสนับสนุนและการกระทบยอดรวดเร็วขึ้นมากเมื่อลูกค้าสอบถามว่าเกิดอะไรขึ้น