أفضل الممارسات

استخدم هذه الأنماط لتبقى تكاملات الشركاء قابلة للتنبؤ والمراقبة وآمنة للمنشآت.

حدّد المنشآت بطريقة متسقة

اختر طريقة الربط المهيّأة لحساب الشريك الخاص بك واستخدمها باستمرار:

• Direct Link - استخدم facility_id الخاص بـ Performance Hub الذي تُرجعه نقطة نهاية المنشآت.
• Linking Identifier - استخدم معرّف الموقع الخاص بك، مثل معرّف الفرع أو رمز الموقع أو رقم المتجر.

لا ترسل المعرّفين كليهما في الطلب نفسه. يعالج Performance Hub الطلبات باستخدام طريقة الربط المهيّأة لحساب الشريك الخاص بك.

راجع طرق ربط الشركاء للحصول على إرشادات الإعداد.

نفّذ عمليات الكتابة المجمّعة بعناية

تقبل Partner API نصوص طلبات بتنسيق JSON، وهي مصممة لمسارات المزامنة القائمة على الدفعات حيثما ورد ذلك في الوثائق. اجعل الدفعات محدودة الحجم وقابلة لإعادة المحاولة.

الإرشادات الافتراضية:

• استخدم ما يصل إلى 1000 عنصر لكل طلب مجمّع لتحقيق أفضل أداء.
• اجعل حجم الحمولات أقل من 10MB.
• التزم بحد 5 طلبات في الثانية لكل نقطة نهاية.

حدود المعدل قابلة للتعديل، ويمكن لمدير حساب الشريك لدى Performance Hub تهيئتها لكل حالة على حدة. إذا كنت تتوقع عمليات استيراد كبيرة الحجم، أو حركة مرور عند الإطلاق، أو عمليات ملء رجعي للتقارير، فاتفق على الإنتاجية المطلوبة قبل فترة التغيير.

إذا كنت بحاجة إلى مزامنة مجموعة بيانات كبيرة، فقسّمها إلى أجزاء محددة وسجّل معرّف كل جزء لديك. فهذا يسهّل فهم ما حدث عند إخفاق إعادة المحاولة.

أعِد المحاولة بأمان

استخدم التراجع الأُسّي مع حالات الإخفاق العابرة مثل 429 و500 و502 و503 و504.

تجنّب حلقات إعادة المحاولة المتلاحقة. ونقطة البداية الجيدة هي:

1. أعِد المحاولة بعد ثانية واحدة.
2. أعِد المحاولة بعد ثانيتين.
3. أعِد المحاولة بعد 4 ثوانٍ.
4. توقّف وأطلق تنبيهًا إذا استمر إخفاق العملية.

في حالات إخفاق التحقق مثل 400 أو 422، أصلح الطلب قبل إعادة المحاولة.

استخدم خاصية عدم التكرار (idempotency) حيثما كانت مدعومة

تدعم نقطة نهاية فتح قفل وحدة التحكم في الباب/البوابة المعلمة الاختيارية idempotency_key. وتؤدي إعادة استخدام المفتاح نفسه للشريك والمنشأة والباب أنفسهم إلى إرجاع النتيجة الموجودة عند توفرها.

استخدم مفتاحًا ثابتًا للإجراء الذي يُنفَّذ، مثل معرّف تسجيل الدخول أو معرّف حدث الوصول من نظامك.

لا تفترض أن كل نقطة نهاية للكتابة تدعم عدم التكرار ما لم يكن ذلك موثّقًا لنقطة النهاية تلك.

حافظ على نظافة بيانات المصدر

أرسل قيمًا ثابتة وموحّدة كلما أمكن ذلك:

• استخدم معرّفات متسقة للأعضاء والخطط والمنشآت وتسجيلات الدخول من نظامك المصدر.
• استخدم طوابع زمنية بتنسيق ISO 8601 للتواريخ والأوقات.
• أرسل أرقام الهواتف بالتنسيق الدولي عند توفرها.
• أرسل العملات باستخدام الحقول الموثّقة لكل نقطة نهاية.
• تجنّب تحميل الحقول النصية الحرة ببيانات مكانها الحقول المنظَّمة.

صمّم لعمليات المزامنة التزايدية والكاملة

تحتاج معظم تكاملات الشركاء إلى كلتيهما:

• عمليات مزامنة تزايدية للتغييرات اليومية.
• عمليات مزامنة كاملة للتسوية لتصحيح الأحداث الفائتة أو عمليات الاستيراد التاريخية أو انحراف البيانات.

ينبغي أن يتمكن تكاملك من إعادة إرسال الحالة الحالية لعضو أو خطة عضوية أو لقطة تقرير دون الاعتماد على نجاح طلب سابق.

انشر Access Time Windows بأمان

تعامل مع قيمة access_time_windows لكل عضو على أنها لقطة كاملة ذات مراجعة مستقلة:

• نسّق تسلسلًا واحدًا متزايدًا باطّراد لقيمة access_time_windows_revision عبر عمليات المزامنة التزايدية وعمليات التسوية.
• أعِد محاولة أي تسليم غير مؤكد أو عابر بالمراجعة نفسها والحمولة الموحّدة نفسها.
• احذف access_time_windows عندما لا تحدّثها.
• لا ترسل [] إلا بعد أن يثبت جلب ناجح وموثوق من المصدر عدم بقاء أي نوافذ. ولا تحوّل أبدًا انتهاء مهلة في المصدر أو نتيجة جزئية أو إخفاقًا في التحليل إلى إلغاء.
• حافظ على ثبات external_id وscope_key، واعتمد كل تعيين للنطاقات قبل بيئة الإنتاج.
• راقب عمر بيانات المصدر وفقًا لسياسة الحداثة المتفق عليها لذلك التكامل.

راجع دليل منتجي Access Time Windows المرجعي للاطلاع على اللقطات الكاملة، والمناطق الزمنية، والتوقيت الصيفي، والإلغاء، ومتجهات الاختبار.

تعامل مع التحكم في الوصول بوصفه أمرًا بالغ الأهمية للسلامة

بالنسبة إلى عمليات فتح أقفال وحدات التحكم في الأبواب/البوابات:

• يجب أن يحدد نظامك ما إذا كان يُسمح للشخص بالدخول قبل استدعاء Performance Hub.
• لا يُرجع Performance Hub القيمة 200 إلا بعد أن تؤكد وحدة التحكم في الموقع أن المرحّل فتح القفل فعليًا.
• تكتمل معظم التأكيدات خلال 3-5 ثوانٍ.
• انتهاء المهلة يعني إخفاقًا صريحًا في فتح القفل، لا نجاحًا في الخلفية.
• لا تُعِد المحاولة إلا وفقًا لقواعد الوصول والسلامة الخاصة بك.

سجّل دائمًا قيمتي event_id وcommand_id اللتين تُرجعهما نقطة نهاية فتح القفل.

راقب تكاملك

استخدم سجلات الطلبات في Partner Console أثناء التطوير والإطلاق. وفي بيئة الإنتاج، احتفظ أيضًا بسجلاتك الخاصة متضمنةً ما يلي:

• الطابع الزمني للطلب.
• نقطة النهاية.
• معرّف السجل المصدر.
• معرّف المنشأة.
• رمز حالة HTTP.
• نص استجابة Performance Hub أو رسالة الخطأ.

تجعل هذه الحقول الدعم والتسوية أسرع بكثير عندما يسأل أحد العملاء عمّا حدث.