واجهة برمجة لفحص الملفات: SHA-256 وMIME الحقيقي وإشارة الفيروسات والبيانات الوصفية عبر REST

واجهة برمجة لفحص الملفات: SHA-256 وMIME الحقيقي وإشارة الفيروسات والبيانات الوصفية عبر REST

تحتاج التطبيقات التي تستقبل الملفات غالباً إلى نقطة تحقق تقنية قبل تمرير الملف إلى محلل أو سير عمل أو خط تخزين. فقد تستقبل منصة سوق مستندات البائعين، أو يقبل منتج SaaS مرفقات العملاء، أو تحتاج منصة مشاركة إلى تسجيل ما دخل إلى النظام. يمكن لكل فريق بناء حساب التجزئة واكتشاف MIME واستخراج البيانات الوصفية وطبقة فرز أولية للبرمجيات الخبيثة، لكن الحفاظ على هذه الفحوص متسقاً ليس دائماً أفضل استخدام لوقت التطوير. تجمع FileInspection هذه الخطوات في عقد REST غير متزامن وتعيد تقرير JSON واحداً.

طلب Multipart

يرسل العميل الموثّق طلباً من نوع multipart إلى POST /api/files/start-process. يجب استخدام actionName=FileInspection ووضع ملف واحد في الحقل file وإرسال parameters=[] وasync=true. يُقبل ملف واحد غير فارغ في كل استدعاء، بحد أقصى 50 ميغابايت، من دون تصفية للامتدادات. يتحقق الخادم من الطلب والحجم فعلياً؛ أما سمة accept في الواجهة أو اسم الملف أو MIME الذي يعلنه المتصفح فليست حدوداً أمنية.

تمثل الاستجابة الأولى إجراءً أُدخل إلى قائمة الانتظار، ولا تعني أن التقرير اكتمل. احفظ معرّف العملية وtrackingUrl، ثم استعلم عن /api/actions/get-action-infos/{id} ضمن السياق الموثّق. وهكذا لا يلزم إبقاء طلب الرفع مفتوحاً أثناء اكتشاف MIME أو فرز محرك مكافحة الفيروسات أو استخراج البيانات الوصفية أو فحص الوسائط.

محتوى تقرير JSON

نتيجة FileInspection الناجحة هي ملف JSON واحد يسجل الاسم الأصلي والحجم وتجزئة SHA-256 ونوع MIME الحقيقي المكتشف. تُستخرج قيمة MIME من المحتوى، ولا تُقبل القيمة القادمة من المتصفح باعتبارها دليلاً. يمنح ذلك التطبيق أساساً أفضل للتسجيل أو التوجيه أو تقرير ما إذا كان ينبغي تمرير الملف إلى محلل لاحق.

يمكن لـ ExifTool توفير بيانات EXIF مفلترة عندما يدعم التنسيق ذلك. ويمكن لـ FFprobe توفير الترميز والدقة والمدة ومعدل البت للصوت والفيديو. كما يمكن أن تحصل الصور وملفات PDF على معاينة OCR محدودة بـ500 حرف. تعتمد الحقول على التنسيق، وقد تكون غائبة أو فارغة أو غير متاحة؛ ولا ينبغي اعتبار غياب حقل ما دليلاً على فشل الرفع.

إشارات فرز وحدودها

يعرض قسم مكافحة الفيروسات حالة محرك مكافحة الفيروسات بقيمة clean أو infected أو error. هذه إشارة أولية للفرز، وليست ضماناً لمكافحة الفيروسات. تعني clean فقط أن هذا الفحص لم يسجل اكتشافاً، ولا يجوز تحويلها في واجهة أو سياسة آلية إلى «ملف آمن معتمد». يجب أن تبقى error متميزة عن clean حتى يتمكن النظام من اختيار مسار حذر.

يعرض قسم قواعد الكشف حالة clean أو matched أو not_run. مجموعة القواعد الأولية صغيرة عمداً وليست قاعدة كشف شاملة. قد تبرر matched إحالة الملف إلى المراجعة، بينما لا يثبت clean أو not_run غياب التهديد. يجب الحفاظ على هذا التمييز في الوثائق والسجلات ورسائل المنتج.

صمّم تكاملاً متيناً

احفظ معرّف الإجراء كمرجع دائم للمهمة غير المتزامنة. ميّز على الأقل بين التحقق المرفوض والمعالجة الجارية والفشل والنتيجة المكتملة. إذا انتهت مهلة طلب المتابعة، فاسترجع الإجراء الموجود أولاً قبل إنشاء طلب آخر. إعادة الفحص لمجرد أن استعلام الحالة لم يستجب قد تكرر العمل وتستهلك token إضافية.

عند النجاح، استخدم مرجع النتيجة الذي يوفره الخادم ومسار التنزيل الموثّق للحصول على JSON. لا تبنِ رابط نتيجة اعتماداً على رقم ID وحده، ولا تعتبر ID يرسله العميل دليلاً على الإذن. كما يجب على تطبيقك التحقق من الملكية عند ربط التقرير بسجل رفع. تساعد التجزئة في التتبع وإزالة التكرار، لكنها لا تمنح الوصول إلى الملف الأصلي.

السعر والنطاق العملي

يكلف الفحص الناجح 12 token. ولا تُفرض رسوم على أخطاء التحقق، ومنها الملف الفارغ أو الذي يتجاوز 50 ميغابايت. لذلك تناسب الخدمة نقطة تحقق تقنية محدودة قبل التحليل أو المراجعة البشرية، ولا تحل محل منصة تحليل برمجيات خبيثة كاملة أو سياسة محتوى خاصة بالتطبيق.

من خلال استدعاء REST غير متزامن يحصل التكامل على SHA-256 وMIME الحقيقي وإشارة محرك مكافحة الفيروسات أولية وحالة قواعد الكشف بسيطة وبيانات وصفية مفلترة وتفاصيل وسائط أو OCR حسب التنسيق. يتيح العقد غير المتزامن للنظام المستدعي متابعة عمله مع الاحتفاظ بمرجع واضح قابل للتدقيق.