برنامج عدّ الأشخاص وواجهة برمجة التطبيقات: دليل التكامل للمطورين
2026-08-29 16:07يقوم برنامج عد الأشخاص بتحويل أحداث المستشعر الخام إلى مقاييس الإشغال وحركة الأقدام والبقاء، ويتم التكامل بين الاثنين من خلال واجهة HTTP JSON موثقة بدلاً من SDK خاص.يمكن للمطور سحب الإحصائيات باستخدام طلب POST موقع أو استلامها عبر webhook، ويكون محتوى البيانات هو نفسه في كلتا الحالتين.
يُغطي دليل واجهة برمجة تطبيقات عدّ الأشخاص أدناه نموذج البيانات، ونمطي التكامل، والمصادقة، وطلبًا عمليًا أوليًا. تتبع الأمثلة العملية الواجهة التي توفرها عدادات Pyroglaux ثلاثية الأبعاد المجسمة، وينطبق الشكل العام على معظم أجهزة العدّ الحديثة.
ما الذي يحصل عليه برنامج عد الأشخاص فعلياً؟
في نظام عد الأشخاص الحديث، يقوم المستشعر بإجراء العد على الجهاز ويصدر أحداثًا منظمة، لذلك لا يقوم برنامج عد الأشخاص بمعالجة الفيديو أبدًا.يتم تحليل إطارات العمق والتخلص منها على المستشعر نفسه.
يحمل حدث عبور واحد أربعة حقول: فهرس فريد للموضوع المتعقب، وطابع زمني بنظام يونكس يحدد وقت مغادرة الموضوع لمنطقة الكشف، ورمز نوع الحدث، ومدة البقاء بالمللي ثانية.
| مجال | يكتب | معنى |
|---|---|---|
| idIndex | عدد صحيح | فهرس فريد للموضوع الذي يتم تتبعه خلال الجلسة |
| الطابع الزمني | int64 | ثوانٍ يونكس في اللحظة التي غادر فيها الهدف المنطقة |
| نوع الحدث | عدد صحيح | 0 دخول، 1 خروج، 2 مرور، 3 إعادة دخول، -1 غير صالح |
| وقت البقاء | عدد صحيح | مدة البقاء داخل المنطقة، بالمللي ثانية |
المصدر: مواصفات واجهة HTTP لتدفق الركاب Pyroglaux، الإصدار 2.1.5.
تُعدّ أنواع الأحداث الأربعة هي الجزء الذي يخطئ فيه معظم من يقومون بحساب عمليات تكامل البرامج. فمعاملة كل حدث كدخول يؤدي إلى احتساب أي شخص يمرّ أمام الباب دون الدخول مرتين، ويتجاهل رمز إعادة الدخول الموجود تحديدًا لمنع احتساب المتسوق العائد كزائر جديد.
كيف تعمل عملية مصادقة واجهة برمجة تطبيقات عد الأشخاص؟
يتم توقيع الطلبات بدلاً من حمل رمز مميز في الرأس، باستخدام ملخص MD5 للمعلمات المصنفة المدمجة مع سر خدمة مشترك.يتم تحويل الملخص الناتج إلى أحرف كبيرة وإرساله في رأس Sign.
خطوات التوقيع ثابتة. يتم فرز كل معلمات الطلب بترتيب ASCII، وإضافة سر الخدمة المتفق عليه مع الجهاز، وأخذ ملخص MD5 السداسي العشري لتلك السلسلة، وتحويل الملخص إلى أحرف كبيرة، ووضع النتيجة في رأس التوقيع بجانب نوع محتوى JSON القياسي.
يتجنب طلب واجهة برمجة تطبيقات عدّ الأشخاص الموقّع تخزين رمز حامل طويل الأمد على جهاز موجود في أرضية المتجر. كما أن استخدام سر خدمة مُدار يُبطل كل طلب تم التقاطه مسبقًا بدون قائمة إبطال الرموز.
السحب أم الدفع: أي نمط تكاملي يناسب؟
يناسب نظام السحب الأساطيل الصغيرة والتطوير المبكر؛ بينما يناسب نظام الدفع لوحات المعلومات الحية والعقارات الأكبر حجماً.كلاهما يُرجع نفس نص JSON، لذا فإن المحلل المكتوب لأحد الأنماط يعمل دون تغيير مع النمط الآخر.
متى يجب على برنامج عدّ الأشخاص استطلاع الجهاز؟
ينبغي لبرامج عد الأشخاص إجراء استطلاع رأي أولاً، لأن عملية الاستطلاع سهلة التصحيح.يثبت أمر curl واحد الاتصال والمصادقة وشكل الحمولة قبل وجود أي كود برمجي للتطبيق.
تُعدّ تكلفة الاستطلاع هي توفير جهاز يمكن الوصول إليه. يجب أن يكون الخادم قادرًا على فتح اتصال داخلي مع كل مستشعر، ما يعني استخدام شبكة افتراضية خاصة (VPN)، أو عنوان ثابت، أو تعيين منفذ لكل جهاز. وبعد تجاوز عدد الأجهزة 50 جهازًا تقريبًا، يصبح هذا المخزون هو العبء الأكبر للصيانة.
متى يجب أن يقوم المستشعر بالضغط بدلاً من ذلك؟
يؤدي تكوين الدفع إلى تحويل المستشعر إلى عميل، لذا فإن الجهاز يحتاج فقط إلى الوصول إلى الشبكة الصادرة.لا توجد قاعدة جدار حماية واردة ولا حاجة إلى دفتر عناوين لكل جهاز.
يُزوَّد الجهاز بعنوان URL للوجهة عبر نقطة نهاية التكوين، وبعد ذلك تُرسَل أحداث العبور إلى ذلك العنوان فور حدوثها. ينخفض زمن الاستجابة من فترة الاستطلاع إلى ما يقارب الوقت الفعلي، وهو أمر مهم لحدود الإشغال وعرض قوائم الانتظار المباشرة.
كيف تقدم الطلب الأول؟
تغطي نقاط نهاية واجهة برمجة التطبيقات (API) الخاصة بعدادات الأشخاص الثلاثة جميع عمليات التكامل تقريبًا: الإحصاءات المباشرة، والإجماليات التاريخية، وقائمة الأحداث الخام.يستمع الجهاز على منفذ ثابت ويقبل طلبات POST RESTful مع نص JSON.
| غاية | نص الطلب | المرتجعات |
|---|---|---|
| فعاليات عبور الخام | startIndex, getQuantity | مصفوفة الأحداث بالإضافة إلى عدد الردود |
| الإجماليات التاريخية | بداية الطابع الزمني، نهاية الطابع الزمني | إجمالي الدخول، الخروج، المرور، العودة |
| نتيجة التتبع المباشر | لا أحد | المواضيع الحالية داخل المنطقة |
المصدر: مواصفات واجهة HTTP لتدفق الركاب من Pyroglaux، الإصدار 2.1.5. راجع وثائق الجهاز الحالية للحصول على المسارات الدقيقة، لأن أسماء نقاط النهاية تختلف عبر أجيال البرامج الثابتة.
ينبغي على برامج عدّ البيانات التي تُجري أول طلب أن تطلب مجموعة صغيرة من الأحداث بدلاً من يوم كامل. إرسال فهرس بداية يساوي صفرًا مع كمية 100 يُعيد 100 سجل كحد أقصى، ويُبلغ الرد عن عدد السجلات المتاحة فعليًا.
تحتوي كل استجابة من واجهة برمجة تطبيقات عدّاد الزوار على كائن نتيجة يتضمن علامة خطأ، ورمزًا رقميًا، ورسالة قابلة للقراءة. يمنع التحقق من علامة الخطأ قبل تحليل البيانات قراءة النتيجة الفارغة على أنها صفر زوار.
ما هي الحدود التي يجدر معرفتها قبل البناء؟
التخزين الموجود على الجهاز هو مخزن مؤقت، وليس قاعدة بيانات.يحتفظ جهاز العد عادةً بسجلات لمدة ثلاثة أيام تقريبًا، وهو ما يكفي للنجاة من انقطاع الشبكة في عطلة نهاية الأسبوع، ولكنه لا يكفي ليكون بمثابة نظام السجل.
تترتب على أي نظام لعدّ الأشخاص مبني على هذه الأجهزة ثلاث نتائج: أولاً، حفظ الأحداث في مخزن البيانات الخاص بك عند استرجاعها. ثانياً، تتبع آخر فهرس أو طابع زمني تم استيعابه بنجاح، بحيث يستأنف النظام عمله عند إعادة التشغيل بدلاً من إعادة تشغيله. ثالثاً، مطابقة الإجماليات اليومية مع نقطة النهاية التاريخية، لأن استعلام التجميع وقائمة الأحداث يتم حسابهما بشكل منفصل على الجهاز.
يُعدّ انحراف التوقيت أمرًا بالغ الأهمية في أي نظام لعدّ الأشخاص في مواقع متعددة. تُستمدّ الطوابع الزمنية من ساعة الجهاز، لذا فإنّ عدم تزامن المستشعر يُنتج أحداثًا تُصنّف بشكل خاطئ مقارنةً ببيانات نقاط البيع. لذا، يُنصح بضبط خادم الوقت أثناء التشغيل التجريبي وليس بعد أول تقرير غير متطابق.
كيف تصل البيانات إلى أداة ذكاء الأعمال؟
يجب أن يقوم نظام دمج بيانات حركة الأقدام بتخزين الأحداث بشكلها الخام وتجميعها عند القراءة.إن كتابة البيانات المجمعة مسبقًا على أساس الساعات في المستودع أمر مغرٍ ويجعل الأسئلة اللاحقة حول وقت البقاء أو إعادة الدخول غير قابلة للإجابة.
يُعدّ المخطط الأدنى العملي لدمج بيانات حركة الزوار هو صف واحد لكل حدث، يتضمن معرّف الجهاز، ومعرّف المنطقة، والطابع الزمني، ونوع الحدث، ومدة الإقامة. وتُستمد بيانات حركة الزوار بالساعة، والتحويل مقابل بيانات نقاط البيع، وتوزيع مدة الإقامة من هذا الجدول الواحد باستخدام لغة SQL العادية.
يُنتج برنامج عدّ الأشخاص الذي يربط معاملات نقاط البيع بمعرف الجهاز والساعة معدل التحويل مباشرةً. ينبغي على فرق البيع بالتجزئة التي تطبق هذا المقياس قراءةمسرد مقاييس البيع بالتجزئةبالنسبة للتعريفات التي ستحتاجها لوحة المعلومات.
هل يتعامل برنامج عد الأشخاص مع البيانات الشخصية؟
إن خط أنابيب العد القائم على العمق والذي ينقل الإحصاءات فقط لا يعالج البيانات الشخصية، لأنه لا توجد صورة ولا معرف يغادر المستشعر.تحتوي الحمولة الموضحة أعلاه على فهرس محدد النطاق لجلسة، وطابع زمني، ومدة زمنية.
هناك قراران تصميميان يُبقيان برامج عدّ الأشخاص في هذا الوضع. أولهما، إبقاء معالجة البيانات المتعمقة على الجهاز بدلاً من بثّ الإطارات إلى خادم للتحليل. وثانيهما، تجنّب ربط فهرس الجلسة بأي سجلّ عميل أو موظف، لأنّ هذا الربط هو ما سيُنشئ بيانات شخصية غير موجودة أصلاً.
تتوفر في بعض البرامج الثابتة ميزات إعادة تحديد الهوية التي تُمكّن برامج عدّ الأشخاص من إزالة البيانات المكررة لنفس الزائر على مدار اليوم، وتُغيّر هذه الميزات طريقة التحليل. لذا، يُرجى التعامل مع أي إمكانية لإزالة البيانات المكررة كمراجعة خصوصية منفصلة بدلاً من اعتبارها ترقية تلقائية.
الأسئلة الشائعة حول برامج عد الأشخاص وواجهات برمجة التطبيقات
هل يلزم وجود حزمة تطوير برمجية (SDK) لاستخدام واجهة برمجة تطبيقات عد الأشخاص؟
لا، يكفي إرسال طلب HTTP POST موقع مع نص JSON لواجهة برمجة تطبيقات عد الأشخاص.يمكن دمج أي لغة برمجة مزودة بعميل HTTP ودالة MD5. توفر حزم تطوير البرامج (SDKs) الخاصة بالموردين نفس الواجهة، وهي مريحة وليست ضرورية، كما أن تجنب استخدام حزمة تطوير البرامج يحافظ على قابلية التكامل بين أجيال الأجهزة المختلفة.
كم مرة يجب أن يقوم برنامج عد الأشخاص باستطلاع جهاز ما؟
كل دقيقة إلى خمس دقائق تغطي معظم احتياجات الإبلاغ.نادراً ما يُجدي الاستطلاع السريع نفعاً، لأن عدد المشاة يُسجّل لكل عملية عبور ويُجمع لاحقاً. أما شاشات عرض الإشغال المباشر فهي الاستثناء، وفي هذه الحالة يُفضّل استخدام نظام الدفع بدلاً من الاستطلاع السريع.
ماذا يحدث للعدادات أثناء انقطاع الشبكة؟
يقوم الجهاز بتخزين الأحداث مؤقتًا محليًا، ثم يقوم بمعالجة الأحداث المتراكمة بمجرد عودة الاتصال.عادةً ما تكون فترة الاحتفاظ بالبيانات ثلاثة أيام تقريبًا. يقوم نظام الاستيعاب الذي يتتبع آخر فهرس تمت معالجته باستعادة الفجوة تلقائيًا؛ أما نظام الاستيعاب الذي يطلب دائمًا أحدث السجلات فيفقد فترة الانقطاع نهائيًا.
هل يمكن لعدة أنظمة استدعاء واجهة برمجة تطبيقات عداد الأشخاص نفسها؟
نعم، واجهة السحب لا تعتمد على الحالة وتدعم القراء المتزامنين.يُحدد كل مُستدعي فهرس بداية أو نطاقًا زمنيًا، ما يسمح لخط أنابيب ذكاء الأعمال ولوحة المعلومات المباشرة بالاستعلام من الجهاز نفسه. عادةً ما تكون وجهات الإرسال محدودة بعدد قليل، لذا يُفضل استخدام مُرحِّل في بنيتك التحتية لإدارة التوزيع.
كيف يتم حساب زمن التوقف؟
تصل مدة البقاء لكل حدث على شكل وقت البقاء بالمللي ثانية، ويتم قياسها من لحظة الدخول إلى مغادرة منطقة الكشف.لا يُعدّ وقت بقاء الزائر في المنطقة هو نفسه وقت بقاء الزائر في المتجر. يتطلب قياس مدة بقاء الزائر في المتجر حدث دخول وحدث خروج مطابق، أو خاصية إعادة تعريف تربط بينهما.
ما الذي يجب أن يتحقق منه اختبار تكامل برنامج عد الأشخاص أولاً؟
امشِ عبر المدخل عددًا معروفًا من المرات وقارن العدد.عشر تمريرات مضبوطة في كل اتجاه تُؤكد صحة تعيين الاتجاه، وتعيين نوع الحدث، ومعالجة الطابع الزمني في عملية واحدة. أي تباين في هذه المرحلة هو مشكلة في الإعدادات، وليس مشكلة في الكود.
الخطوات التالية
ابدأ عملية دمج بيانات حركة الزوار بجهاز واحد، وبرنامج استطلاع، وعشر جولات استكشافية مُتحكَّم بها. بمجرد تطابق الأرقام، حدد ما إذا كان النشر يتطلب دفع البيانات، وصمم مخزن الأحداث قبل التوسع لأكثر من موقع واحد.
تنشر Pyroglaux مواصفات واجهة HTTP الكاملة مع كل جهاز، ولا تحصر التكامل باشتراك. تصفحنطاق مستشعر العد ثلاثي الأبعادأواطلب وثائق واجهة برمجة التطبيقات ووحدة نموذجية للمطور.