بناء مستقبِل استدعاءات القياسات الحيوية بلغات Python وNode.js وPHP
مستقبِل الاستدعاءات هو الجزء البرمجي الصغير الذي يحوّل كل مسح لبصمة إصبع أو وجه أو بطاقة إلى سجل في نظامك الخاص. تُرسل Cams Biometrics Gateway كل مسح موثّق إلى خادمك كطلب JSON، ويرد خادمك بتأكيد وصول الطلب. لستَ مضطراً إلى كتابة هذا المستقبِل من الصفر. توفر Cams مطالبات AI Code Generator Prompts للغات Python وNode.js وPHP: الصق إحداها في مساعد ذكاء اصطناعي مثل Claude أو ChatGPT، وستحصل على ملف كامل وجاهز للعمل يتضمن مستقبِل الاستدعاءات وعميل REST وواجهة اختبار. يشرح هذا الدليل ما يجب أن يؤديه المستقبِل، وكيفية توليده للغة التي تستخدمها، وكيفية ضبطه، وكيفية اختباره قبل التشغيل الفعلي.
01 · المهام الست
ما الذي يجب أن يفعله مستقبِل الاستدعاءات
مهما كانت اللغة المستخدمة، يؤدي كل مستقبِل استدعاءات للقياسات الحيوية المهام الست نفسها. وهذه أيضاً النقاط التي يجب التحقق منها في أي شيفرة يتم توليدها.
| المهمة | ماذا تعني | لماذا تهم |
|---|---|---|
| 1. قبول الطلب | استقبال طلب HTTP/HTTPS من نوع POST مع نص JSON خام | بهذه الطريقة تُرسل Gateway كل حدث |
| 2. التحقق من الرمز | التحقق من AuthToken مقابل رمز الاستدعاء المتوقع لديك | يمنع أي جهة أخرى من إرسال حضور مزيّف إلى عنوان URL الخاص بك |
| 3. التوجيه حسب نوع الحدث | فحص المفتاح الموجود داخل RealTime ومعالجته وفقاً لذلك | ليس كل استدعاء تسجيل حضور؛ فبعضها يُبلغ عن صور أو تغييرات في بيانات المستخدمين |
| 4. تجاهل التكرارات | استخدام OperationID لتجاهل الأحداث التي سبق حفظها | لا تتحول عملية الإرسال المتكررة أبداً إلى سجل مكرر |
| 5. التخزين والتسجيل | حفظ الحقول التي تحتاجها وتسجيل كل استدعاء | يُنشئ السجل الذي سيستخدمه نظام الموارد البشرية، أو الرواتب، أو لوحة المعلومات |
| 6. الرد بالإتمام | إرجاع {“status”:”done”} مع HTTP 200 | يُبلغ Gateway بأن الحدث وصل بأمان |
02 · اعرف بياناتك
الحمولة التي ستستقبلها
أكثر الاستدعاءات شيوعاً هو سجل تسجيل الحضور، ويُرسل في كل مرة يتم فيها مسح. احفظ هذا النموذج باسم sample.json، لأنك ستستخدمه لاختبار المستقبِل لاحقاً.
|
Callback API، طلب PunchLog المرسل إلى المستقبِل {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
بعد معالجة أي استدعاء، يجب أن يرد المستقبِل بالرمز HTTP 200 ويكون نص الرد هذا تحديداً:
|
Callback API، الرد الذي يجب أن يعيده المستقبِل { "status": "done" } (HTTP 200)
|
أنواع أحداث الاستدعاء
يصل كل استدعاء داخل كائن RealTime. يقرر المستقبِل ما يفعله بفحص أي من هذه المفاتيح موجود:
| المفتاح داخل RealTime | ما الذي يُبلغ عنه |
|---|---|
| PunchLog | مسح حضور: من، وتسجيل الدخول أو الخروج، ومتى، وكيف |
| UserUpdated | تم تحديث بيانات مستخدم على الجهاز |
تفصيلتان توقعان المطورين في الخطأ
| التفصيلة | ما الذي يجب مراعاته |
|---|---|
| مفتاح الرد بأحرف صغيرة | أرجِع status بأحرف صغيرة مع القيمة done. لا تنسخ حقل Status بحرف أول كبير من استجابات RESTful API |
| صيغة LogTime | تبدو قيمة LogTime مثل 2020-09-17 07:48:22 GMT +0530. وهي وقت المسح الفعلي مع إزاحة الجهاز. قم بتحليلها مع الإزاحة واستخدمها كوقت للحضور |
03 · دع الذكاء الاصطناعي يكتب الشيفرة
أنشئ المستقبِل الخاص بك باستخدام مطالبات AI Code Generator Prompts
تنشر Cams ملف مطالبة جاهزاً لكل لغة خادم مدعومة. تحتوي كل مطالبة على ملخص لمواصفات Cams Web API 3.0 وتعليمات واضحة لما يجب بناؤه. تلصق المطالبة في مساعد ذكاء اصطناعي، فيولّد المساعد تنفيذاً كاملاً من ملف واحد لمجموعة التقنيات الخاصة بك.
|
حمّل ملف المطالبة اختر لغتك في القسم التالي وحمّل ملف المطالبة بصيغة .txt الخاص بها. |
|
|
الصقها في مساعد ذكاء اصطناعي افتح Claude أو ChatGPT أو Copilot أو أي أداة برمجة بالذكاء الاصطناعي، والصق محتوى المطالبة كاملاً. |
|
|
احصل على ملف كامل وجاهز للعمل يُنشئ الذكاء الاصطناعي ملفاً واحداً. اضبط قيم الإعداد، ثم انشره وشغّله. |
| يتضمن كل ملف مُولَّد | ماذا يفعل |
|---|---|
| مستقبِل الاستدعاءات | يقرأ نص POST الخام، ويتحقق من AuthToken، ويوجّه حسب نوع الحدث، ويسجل كل استدعاء، ويخزن سجلات التسجيل، ويحفظ صور الحضور، ويرد بـ done |
| عميل REST | دالة طلب عامة بالإضافة إلى دوال مغلِّفة لجميع عمليات RESTful البالغ عددها 27، مثل AddUser وDeleteUser وResendAllUser وUpdateAccessTime |
| واجهة اختبار HTML | صفحة متصفح تحتوي على حقول الإعداد الخاصة بك، وقائمة منسدلة للعمليات، ومحرر JSON معبّأ مسبقاً بقوالب الطلبات، وعارض للاستجابات، وقائمة بأحدث الاستدعاءات |
|
الوثائق المستضافة هي المرجع الأول تطلب كل مطالبة من الذكاء الاصطناعي قراءة وثائق Cams Web API الكاملة واعتبارها المصدر المعتمد للعمليات، ومخططات JSON، وأسماء الحقول، ورموز الاستجابة. وإذا تعارض أي شيء في ملخص المطالبة مع الوثائق المستضافة، فإن الوثائق هي التي تسود. |
04 · اختر لغتك
مطالبات للغات Python وNode.js وPHP
تم ضبط كل مطالبة لإنتاج شيفرة اصطلاحية بأقل قدر من الاعتماديات للغتها.
|
|
|
تتوفر المطالبات أيضاً للغة C# (.NET 8) مع Minimal API، ولغة Java مع HttpServer المدمج دون أي اعتماديات، ولغة Go مع net/http والمكتبة القياسية فقط، ولغة Ruby مع Sinatra وSQLite. يمكنك العثور عليها جميعاً في قسم AI Code Generator Prompts ضمن وثائق Cams Web API. احصل على المطالبات.
05 · ثلاث قيم يجب ضبطها
ضبط الملف المُولَّد
يحتوي الملف المُولَّد على كتلة إعداد في أعلاه. في نسخة PHP تبدو كما يلي، وتستخدم اللغات الأخرى القيم الثلاث نفسها:
|
كتلة الإعداد، نسخة PHP $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| الإعداد | ما الذي يجب إدخاله |
|---|---|
| base_url | عنوان RESTful endpoint URL من حساب Cams API Monitor الخاص بك |
| stgid | معرّف Service Tag ID الخاص بك. |
| auth_token | AuthToken الخاص بك، ويُرسل مع طلبات RESTful الصادرة، ويُتحقق منه مقابل AuthToken في طلبات الاستدعاء الواردة. |
|
أبقِ الرموز بعيداً عن الشيفرة المشتركة للاختبار السريع، لا بأس بكتابة القيم مباشرة في كتلة الإعداد. وقبل التشغيل الفعلي، انقل الرموز إلى متغيرات البيئة أو إلى مدير الأسرار، حتى لا تنتهي أبداً في نظام إدارة الإصدارات أو في ملف مشترك. |
بعد الضبط والنشر على عنوان HTTPS عام، اضبط هذا العنوان كـ Callback URL في Cams Gateway. ومن تلك اللحظة، يصل كل مسح موثّق إلى المستقبِل في الوقت الفعلي.
06 · اختبر قبل ربط الأجهزة
اختبار المستقبِل
لا تحتاج إلى جهاز قياسات حيوية لاختبار مستقبِل الاستدعاءات. أرسل إليه نموذج الحمولة بنفسك باستخدام cURL، مع رمز استدعاء مطابق، وتحقق من الاستجابة.
|
الطرفية، أرسل استدعاء اختبار # Save the sample payload as sample.json, then send it to your receiver:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Expected response (HTTP 200):
# {"status":"done"}
|
| الاختبار | ما الذي يجب إرساله | النتيجة المتوقعة |
|---|---|---|
| حدث صالح | sample.json، مع ضبط AuthToken على auth_token الخاص بك | HTTP 200 مع done، ويتم حفظ تسجيل الحضور |
| حدث مكرر | الطلب نفسه مرة ثانية | HTTP 200 مع done، ولا يتم حفظ سجل ثانٍ |
| رمز خاطئ | sample.json مع AuthToken مختلف | يتم الرفض، ولا يُحفظ أي شيء |
| حدث تسجيل دخول | sample.json مع تغيير Type إلى CheckIn | يُحفظ كتسجيل دخول |
| عملية RESTful | استخدم واجهة اختبار HTML المدمجة لإرسال عملية | استجابة تحتوي على Status وStatusCode |
تجعل واجهة اختبار HTML المُولَّدة جانب RESTful سهل التجربة: افتح الملف في المتصفح، واختر عملية من القائمة المنسدلة، وعدّل JSON المعبّأ مسبقاً، ثم أرسله. ويؤكد عارض الاستدعاءات الأخيرة في الصفحة نفسها أن استدعاءات الاختبار قد وصلت.
07 · قائمة مراجعة الإنتاج
راجع قبل التشغيل الفعلي
الشيفرة المُولَّدة بالذكاء الاصطناعي نقطة بداية سريعة وموثوقة، لكن مثل أي شيفرة، يجب مراجعتها قبل أن تتعامل مع بيانات موظفين حقيقية.
| البند | يُعتبر مكتملاً عندما |
|---|---|
| تمت مراجعة الشيفرة | قرأ المطور الملف المُولَّد وفهم ما يفعله كل قسم |
| HTTPS فقط | لا يمكن الوصول إلى المستقبِل إلا عبر HTTPS بشهادة صالحة |
| حماية الرموز | يتم تخزين AuthTokens في متغيرات البيئة أو في مدير الأسرار |
| معالجة التكرارات | يتم تخزين OperationID والتحقق منه بحيث يتم تجاهل عمليات الإرسال المتكررة |
| ملاءمة التخزين | مخزن ملفات JSON مناسب للإعدادات الصغيرة؛ وقد تنتقل النشرات الأكبر إلى قاعدة بيانات إنتاجية |
| حماية واجهة الاختبار | صفحة اختبار HTML محمية بكلمة مرور أو معطّلة على الخوادم العامة |
| التعامل بعناية مع الصور | صور الحضور المحفوظة على القرص مقيّدة بصلاحيات الوصول، وتُحتفظ بها فقط للمدة اللازمة |
| المراقبة قائمة | يتم تسجيل الأخطاء وأحجام الاستدعاءات غير المعتادة، ويتم التنبيه إليها عبر نظام المراقبة الخاص بك |
|
أبقِ قواعد العمل في مكان آخر مهمة المستقبِل هي القبول والتحقق والتوجيه والتخزين والإقرار. أما تحديد من تأخر، أو حساب الساعات الإضافية، أو إرسال الإشعارات، فيعود إلى الأنظمة التي تقرأ الأحداث المخزنة، مثل نظام الموارد البشرية أو ERP أو أدوات الأتمتة. فالمستقبِل المركّز أسهل في التأمين والصيانة. |
الأسئلة الشائعة
|
هل أحتاج إلى كتابة أي شيفرة بنفسي؟ عادةً لا. تُنتج مطالبات AI Code Generator Prompts ملفاً كاملاً وجاهزاً للعمل. تقوم بضبط ثلاث قيم إعداد، ثم تنشر الملف وتختبره. ويجب أن يراجع المطور الشيفرة قبل التشغيل الفعلي. |
|
أي مساعدات ذكاء اصطناعي تعمل مع المطالبات؟ أي مساعد برمجة بالذكاء الاصطناعي قادر، بما في ذلك Claude وChatGPT وCopilot. الصق محتوى المطالبة كاملاً دفعة واحدة كي يحصل المساعد على المواصفات كاملة. |
|
أين أجد عنوان RESTful endpoint URL ومعرّف Service Tag ID؟ كلاهما يأتي من حساب Cams API Monitor الخاص بك. تُرسل طلبات RESTful إلى عنوان endpoint URL مع ?stgid= متبوعاً بمعرّف Service Tag ID الخاص بك. |
|
لماذا أرد بـ done على حدث مكرر؟ لأن الحدث وصل بأمان بالفعل، حتى لو كنت قد حفظته سابقاً. فالرد بـ done يُبلغ Gateway بأنه لا حاجة لإرساله مرة أخرى. |
|
هل يمكنني استخدام لغة غير مذكورة هنا؟ نعم. يحتاج مستقبِل الاستدعاءات فقط إلى قبول طلب HTTPS من نوع POST وإرجاع JSON. المطالبات اختصار، والواجهة البرمجية نفسها تعمل مع أي لغة قادرة على ذلك. |
الخلاصة: من المطالبة إلى حضور فوري في فترة بعد الظهر
مستقبِل استدعاءات القياسات الحيوية صغير الحجم، لكنه الجزء الذي يحوّل كل مسح موثّق إلى بيانات حية لنظام الموارد البشرية والرواتب ولوحات المعلومات والأتمتة. مع Cams AI Code Generator Prompts، لم تعد بحاجة إلى بنائه من صفحة فارغة. نزّل المطالبة الخاصة بلغة Python أو Node.js أو PHP، والصقها في مساعد الذكاء الاصطناعي، واضبط ثلاث قيم، ثم اختبر. بعد ذلك راجعه وأمّنه، ودع بيانات الحضور في الوقت الفعلي تبدأ بالتدفق.
توفر Cams Biometrics Gateway الأحداث التي يحتاجها المستقبِل الخاص بك. تُرسل واجهة Callback API الخاصة بها كل مسح موثّق في الوقت الفعلي، بصيغة JSON موحدة واحدة، من أجهزة تنتمي لأكثر من 15 علامة تجارية، وتوفر واجهة RESTful API سبع وعشرين عملية يمكن لعميلك المُولَّد استدعاؤها. تتم جميع الاتصالات عبر HTTP/HTTPS مع التحقق من رمز المصادقة وتشفير AES-256 اختيارياً. استكشف المنصة على CamsBiometrics.com واقرأ الوثائق الكاملة لواجهة Web API، بما في ذلك كل مطالبة من AI Code Generator Prompts: احصل على المطالبات.