ساخت گیرنده Callback بیومتریک با Python، Node.js و PHP
گیرنده Callback بخش کوچکی از کد است که هر اسکن اثر انگشت، چهره یا کارت را به یک رکورد در سیستم خودتان تبدیل میکند. Cams Biometrics Gateway هر اسکن تأییدشده را بهصورت یک درخواست JSON به سرور شما ارسال میکند و سرور شما پاسخی میدهد تا تأیید کند که درخواست رسیده است. لازم نیست این گیرنده را از صفر بنویسید. Cams پرامپتهای AI Code Generator را برای Python، Node.js و PHP ارائه میدهد: یکی از آنها را در یک دستیار هوش مصنوعی مانند Claude یا ChatGPT قرار دهید تا یک فایل کامل و آماده اجرا شامل گیرنده Callback، کلاینت REST و یک رابط آزمایشی دریافت کنید. این آموزش توضیح میدهد که یک گیرنده چه کارهایی باید انجام دهد، چگونه برای زبان خود آن را تولید کنید، چگونه پیکربندی کنید و پیش از راهاندازی، چگونه آن را آزمایش کنید.
01 · شش وظیفه
وظایف یک گیرنده Callback
هر گیرنده Callback بیومتریک، صرفنظر از زبان برنامهنویسی، همین شش وظیفه را انجام میدهد. این موارد همچنین چیزهایی هستند که باید در هر کدی که تولید میکنید بررسی کنید.
| وظیفه | معنی آن | چرا اهمیت دارد |
|---|---|---|
| ۱. پذیرش درخواست | دریافت یک HTTP/HTTPS POST با بدنه JSON خام | Gateway هر رویداد را به این شکل ارسال میکند |
| ۲. تأیید توکن | بررسی AuthToken در برابر توکن Callback مورد انتظار شما | جلوی ارسال حضور و غیاب جعلی به URL شما توسط دیگران را میگیرد |
| ۳. مسیریابی بر اساس نوع رویداد | بررسی اینکه کدام کلید داخل RealTime وجود دارد و پردازش مناسب آن | هر Callback یک ثبت ورود یا خروج نیست؛ برخی گزارش عکس یا تغییر کاربر را ارسال میکنند |
| ۴. رد کردن موارد تکراری | استفاده از OperationID برای نادیده گرفتن رویدادهایی که قبلاً ذخیره کردهاید | ارسال تکراری هرگز به ثبت دوباره تبدیل نمیشود |
| ۵. ذخیره و ثبت گزارش | ذخیره فیلدهای موردنیاز و ثبت گزارش هر Callback | رکوردی میسازد که HRMS، حقوق و دستمزد یا داشبورد شما از آن استفاده میکند |
| ۶. پاسخ با done | بازگرداندن {“status”:”done”} با HTTP 200 | به Gateway اطلاع میدهد که رویداد با موفقیت رسیده است |
02 · دادههای خود را بشناسید
محمولهای که دریافت خواهید کرد
رایجترین Callback یک گزارش ورود یا خروج است که هر بار که فردی اسکن میکند ارسال میشود. این نمونه را با نام 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"
}
}
|
پس از پردازش هر Callback، گیرنده شما باید با HTTP 200 و دقیقاً این بدنه پاسخ دهد:
|
Callback API، پاسخی که گیرنده شما باید بازگرداند { "status": "done" } (HTTP 200)
|
انواع رویداد Callback
هر Callback داخل یک شیء RealTime میرسد. گیرنده شما با بررسی اینکه کدامیک از این کلیدها وجود دارد تصمیم میگیرد چه کاری انجام دهد:
| کلید داخل RealTime | آنچه گزارش میکند |
|---|---|
| PunchLog | یک اسکن حضور و غیاب: چه کسی، ورود یا خروج، چه زمانی و با چه روشی |
| UserUpdated | جزئیات یک کاربر روی دستگاه بهروزرسانی شده است |
دو جزئیاتی که توسعهدهندگان را غافلگیر میکند
| جزئیات | نکتهای که باید به آن توجه کنید |
|---|---|
| کلید پاسخ با حروف کوچک است | بازگرداندن status با حروف کوچک و مقدار done. فیلد Status با حرف بزرگ اول را از پاسخهای RESTful API کپی نکنید |
| قالب LogTime | LogTime به شکل 2020-09-17 07:48:22 GMT +0530 است. این زمان واقعی اسکن همراه با اختلاف زمانی دستگاه است. آن را با همان اختلاف زمانی تجزیه کنید و بهعنوان زمان حضور استفاده کنید |
03 · بگذارید هوش مصنوعی کد را بنویسد
گیرنده خود را با پرامپتهای AI Code Generator بسازید
Cams برای هر زبان سمت سرور پشتیبانیشده یک فایل پرامپت آماده منتشر میکند. هر پرامپت شامل خلاصهای از مشخصات Cams Web API 3.0 و دستورالعملهای روشن درباره آنچه باید ساخته شود است. آن را در یک دستیار هوش مصنوعی قرار میدهید و دستیار یک پیادهسازی کامل و تکفایلی برای پشته شما تولید میکند.
|
فایل پرامپت را دانلود کنید زبان خود را در بخش بعدی انتخاب کنید و فایل پرامپت .txt آن را دانلود کنید. |
|
|
آن را در یک دستیار هوش مصنوعی قرار دهید Claude، ChatGPT، Copilot یا هر ابزار کدنویسی هوش مصنوعی را باز کنید و کل محتوای پرامپت را قرار دهید. |
|
|
یک فایل کامل و آماده دریافت کنید هوش مصنوعی یک فایل تکفایلی تولید میکند. مقادیر پیکربندی خود را تنظیم کنید، آن را مستقر کنید و اجرا کنید. |
| هر فایل تولیدشده شامل | کارکرد آن |
|---|---|
| گیرنده Callback | بدنه خام POST را میخواند، AuthToken را تأیید میکند، بر اساس نوع رویداد مسیریابی میکند، هر Callback را ثبت میکند، گزارشهای حضور را ذخیره میکند، عکسهای حضور را ذخیره میکند و با done پاسخ میدهد |
| کلاینت REST | یک تابع درخواست عمومی بههمراه توابع wrapper برای هر ۲۷ عملیات RESTful، مانند AddUser، DeleteUser، ResendAllUser و UpdateAccessTime |
| رابط آزمایشی HTML | یک صفحه مرورگر با فیلدهای پیکربندی شما، منوی کشویی عملیات، ویرایشگر JSON با قالبهای درخواست از پیش پرشده، نمایشگر پاسخ و فهرستی از Callbackهای اخیر |
|
ابتدا مستندات میزبانیشده هر پرامپت به هوش مصنوعی میگوید که کل مستندات 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 | URL نقطه پایانی RESTful از حساب Cams API Monitor شما |
| stgid | شناسه Service Tag شما. |
| auth_token | AuthToken شما که در درخواستهای RESTful خروجی قرار میگیرد و در برابر AuthToken درخواستهای Callback ورودی بررسی میشود. |
|
توکنها را از کد مشترک دور نگه دارید برای یک آزمایش سریع، وارد کردن مقادیر در بلوک پیکربندی اشکالی ندارد. پیش از ورود به محیط واقعی، توکنها را به متغیرهای محیطی یا یک مدیر رازها (secrets manager) منتقل کنید تا هرگز در version control یا در یک فایل مشترک قرار نگیرند. |
پس از پیکربندی و استقرار در یک نشانی عمومی HTTPS، آن نشانی را بهعنوان Callback URL در Cams Gateway تنظیم کنید. از آن به بعد، هر اسکن تأییدشده بهصورت لحظهای به گیرنده شما میرسد.
06 · پیش از اتصال دستگاهها آزمایش کنید
آزمایش گیرنده خود
برای آزمایش گیرنده Callback به دستگاه بیومتریک نیاز ندارید. نمونه محموله را با cURL و یک توکن Callback مطابق خودتان برای گیرنده ارسال کنید و پاسخ را بررسی کنید.
|
ترمینال، ارسال یک Callback آزمایشی # 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 از پیش پرشده را تنظیم کنید و ارسال کنید. نمایشگر Callbackهای اخیر در همان صفحه تأیید میکند که Callbackهای آزمایشی شما دریافت شدهاند.
07 · چکلیست تولید
پیش از راهاندازی نهایی بررسی کنید
کدهای تولیدشده با هوش مصنوعی نقطه شروعی سریع و قابل اتکا هستند، اما مانند هر کد دیگری باید پیش از پردازش دادههای واقعی کارکنان بررسی شوند.
| مورد | زمان تکمیل |
|---|---|
| بازبینی کد | یک توسعهدهنده فایل تولیدشده را خوانده و میداند هر بخش چه کاری انجام میدهد |
| فقط HTTPS | گیرنده فقط از طریق HTTPS با گواهی معتبر قابل دسترسی است |
| محافظت از توکنها | AuthTokenها در متغیرهای محیطی یا یک مدیر رازها ذخیره میشوند |
| مدیریت موارد تکراری | OperationID ذخیره و بررسی میشود تا ارسالهای تکراری نادیده گرفته شوند |
| مناسب بودن ذخیرهسازی | ذخیرهساز فایل JSON برای راهاندازیهای کوچک مناسب است؛ استقرارهای بزرگتر ممکن است به یک پایگاه داده تولیدی منتقل شوند |
| محافظت از رابط آزمایشی | صفحه آزمایشی HTML روی سرورهای عمومی با رمز عبور محافظت شده یا غیرفعال است |
| مدیریت دقیق عکسها | عکسهای حضور ذخیرهشده روی دیسک کنترل دسترسی دارند و فقط تا زمانی که لازم است نگه داشته میشوند |
| وجود پایش | خطاها و حجم غیرعادی Callbackها ثبت میشوند و پایش خودتان برای آنها هشدار میدهد |
|
قوانین کسبوکار را جای دیگری نگه دارید وظیفه گیرنده پذیرش، تأیید، مسیریابی، ذخیره و تأیید دریافت است. تصمیمگیری درباره تأخیر کارکنان، محاسبه اضافهکار یا ارسال اطلاعیهها بر عهده سیستمهایی است که رویدادهای ذخیرهشده را میخوانند، مانند HRMS، ERP یا ابزارهای خودکارسازی شما. یک گیرنده متمرکز امنتر است و نگهداری آن آسانتر است. |
سوالات متداول
|
آیا باید خودم کدی بنویسم؟ معمولاً خیر. پرامپتهای AI Code Generator یک فایل کامل و آماده تولید میکنند. سه مقدار پیکربندی را تنظیم میکنید، آن را مستقر و آزمایش میکنید. یک توسعهدهنده باید پیش از راهاندازی نهایی کد را بازبینی کند. |
|
کدام دستیارهای هوش مصنوعی با پرامپتها کار میکنند؟ هر دستیار کدنویسی توانمند هوش مصنوعی، از جمله Claude، ChatGPT و Copilot. کل محتوای پرامپت را یکجا قرار دهید تا دستیار مشخصات کامل را در اختیار داشته باشد. |
|
URL نقطه پایانی RESTful و Service Tag ID را از کجا پیدا کنم؟ هر دو از حساب Cams API Monitor شما میآیند. درخواستهای RESTful به نقطه پایانی با ?stgid= و سپس Service Tag ID شما ارسال میشوند. |
|
چرا برای رویداد تکراری با done پاسخ دهم؟ زیرا رویداد با موفقیت رسیده است، حتی اگر قبلاً آن را ذخیره کرده باشید. پاسخ done به Gateway میگوید که نیازی به ارسال دوباره آن نیست. |
|
آیا میتوانم از زبانی استفاده کنم که در فهرست نیست؟ بله. گیرنده Callback فقط باید یک HTTPS POST را بپذیرد و JSON برگرداند. پرامپتها یک میانبر هستند و همان API با هر زبانی که بتواند این کار را انجام دهد کار میکند. |
نتیجهگیری: از پرامپت تا حضور لحظهای در کمتر از یک بعدازظهر
گیرنده Callback بیومتریک کوچک است، اما بخشی است که هر اسکن تأییدشده را به داده زنده برای HRMS، حقوق و دستمزد، داشبوردها و خودکارسازیهای شما تبدیل میکند. با پرامپتهای Cams AI Code Generator دیگر لازم نیست آن را از صفحه خالی بسازید. پرامپت Python، Node.js یا PHP را دانلود کنید، آن را در دستیار هوش مصنوعی خود قرار دهید، سه مقدار را تنظیم کنید و آزمایش کنید. سپس آن را بازبینی کنید، ایمن کنید و بگذارید دادههای حضور لحظهای جریان پیدا کنند.
Cams Biometrics Gateway رویدادهایی را ارسال میکند که گیرنده شما به آنها نیاز دارد. Callback API آن هر اسکن تأییدشده را بهصورت لحظهای و در یک قالب یکسان JSON از دستگاههای بیش از ۱۵ برند ارسال میکند و RESTful API آن ۲۷ عملیات دارد که کلاینت تولیدشده شما میتواند آنها را فراخوانی کند. تمام ارتباطات از طریق HTTP/HTTPS با اعتبارسنجی auth token و رمزگذاری اختیاری AES-256 انجام میشود. پلتفرم را در CamsBiometrics.com بررسی کنید و مستندات کامل Web API را، از جمله هر AI Code Generator Prompt، بخوانید: دریافت پرامپتها.