خلاصة سريعة: يوفّر SmartSlim Server من UGLYPEAR DATA واجهة RESTful API تضم أربع واجهات رئيسية: الرفع والضغط، الضغط الدفعي، الاستعلام عن الحالة، والإشعارات بالاستدعاء (Callback). تدعم طريقتَي مصادقة: API Key وBearer Token. يستغرق ضغط ملف PDF واحد بحجم 100 ميجابايت نحو 8 ثوانٍ، وضغط دفعة من 100 ملف نحو 12 ثانية. الحد الافتراضي للطلبات هو 60 طلبًا في الدقيقة، ويمكن رفعه إلى 300 في الإصدار المؤسسي. تعرض هذه المقالة جداول معمّلة لمعاملات الواجهات الأربع، وأمثلة استدعاء بـ Python/JavaScript/curl، وحلول معالجة الأخطاء. سنبدأ بنظرة عامة على الواجهة، ثم نشرح كل واجهة بالتفصيل.
إذا كنت تحتاج إلى تكامل محلي عبر SDK بدلاً من استدعاء HTTP، يُنصح أولاً بقراءة دليل تكامل SDK للضغط: استدعاء بعدة لغات Python/Java/C#.
أولًا: نظرة عامة على واجهات API
طُوّرت واجهة RESTful API لخادم SmartSlim Server باستخدام إطار FastAPI. جميع الواجهات تُعيد البيانات بصيغة JSON، وتدعم رفع الملفات عبر multipart/form-data. المسار الأساسي للواجهة هو /api/v1/، ويجب أن يحمل كل طلب معلومات المصادقة.
| الواجهة | الطريقة | المسار | الوظيفة | متزامن/غير متزامن |
|---|---|---|---|---|
| الرفع والضغط | POST | /api/v1/compress | رفع ملف واحد وضغطه | متزامن (أقل من 50 ميجابايت) / غير متزامن |
| الضغط الدفعي | POST | /api/v1/compress/batch | رفع عدة ملفات وضغطها دفعة واحدة | غير متزامن |
| الاستعلام عن الحالة | GET | /api/v1/status/{task_id} | الاستعلام عن حالة مهمة الضغط | متزامن |
| الإشعار بالاستدعاء | POST | عنوان URL للاستدعاء على العميل | إشعار فوري عند اكتمال الضغط | دفع غير متزامن |
طريقتا المصادقة: مصادقة API Key مناسبة لاستدعاءات الخادم، ومصادقة Bearer Token مناسبة لاستدعاءات الواجهة الأمامية. يقارن الجدول التالي بين خصائص الطريقتين.
| طريقة المصادقة | ترويسة الطلب | صلاحية المفتاح | سيناريو الاستخدام | الأمان |
|---|---|---|---|---|
| API Key | X-API-Key: your-key | دائمة (قابلة للإلغاء) | استدعاء من جانب الخادم | متوسط (يتطلب HTTPS) |
| Bearer Token | Authorization: Bearer token | 24 ساعة | استدعاء من الواجهة الأمامية | عالٍ (صلاحية قصيرة) |
ثانيًا: شرح مفصّل لمعاملات كل واجهة
1. واجهة الرفع والضغط
تستقبل واجهة الرفع والضغط ملفًا واحدًا وتُعيد نتيجة الضغط. الملفات التي يقل حجمها عن 50 ميجابايت تُعيد رابط التنزيل فورًا بشكل متزامن، أما الملفات الأكبر من 50 ميجابايت فتُعيد معرّف المهمة بشكل غير متزامن.
| المعامل | النوع | إلزامي | القيمة الافتراضية | الوصف |
|---|---|---|---|---|
| file | multipart/file | نعم | - | الملف المراد ضغطه |
| format | string | لا | كشف تلقائي | نوع الملف (pdf/image/ofd) |
| level | string | لا | medium | مستوى الضغط (low/medium/high/ultra) |
| quality | integer | لا | 75 | عامل الجودة (1-100) |
| callback_url | string | لا | - | عنوان URL للإشعار غير المتزامن |
2. واجهة الضغط الدفعي
تستقبل واجهة الضغط الدفعي عدة ملفات وتُعالجها بشكل غير متزامن، وتُعيد معرّف المهمة الدفعية. تدعم تحديد عدد العمليات المتزامنة، ويخضع الحد الأقصى للتزامن لقيود الترخيص.
| المعامل | النوع | إلزامي | القيمة الافتراضية | الوصف |
|---|---|---|---|---|
| files | multipart/file[] | نعم | - | قائمة الملفات المراد ضغطها (بحد أقصى 100 ملف) |
| level | string | لا | medium | مستوى الضغط |
| quality | integer | لا | 75 | عامل الجودة |
| workers | integer | لا | 4 | عدد العمليات المتزامنة (1-16) |
| callback_url | string | لا | - | عنوان URL للإشعار بالاكتمال |
3. واجهة الاستعلام عن الحالة
تستعلم واجهة الاستعلام عن الحالة عبر معرّف المهمة عن حالة ونتائج مهمة الضغط غير المتزامنة الحالية.
| حقل الإرجاع | النوع | الوصف |
|---|---|---|
| task_id | string | المعرّف الفريد للمهمة |
| status | string | الحالة (pending/processing/completed/failed) |
| progress | integer | نسبة التقدم (0-100) |
| download_url | string | رابط تنزيل نتيجة الضغط (بعد الاكتمال) |
| original_size | integer | حجم الملف الأصلي (بالبايت) |
| compressed_size | integer | حجم الملف بعد الضغط (بالبايت) |
| error | string | رسالة الخطأ (عند الفشل) |
ثالثًا: أمثلة استدعاء بثلاث لغات
فيما يلي أمثلة استدعاء بثلاث لغات: curl وPython وJavaScript. جميع الأمثلة تتناول رفع وضغط ملف PDF واحد.
| اللغة | الكود الأساسي | الوصف |
|---|---|---|
| curl | curl -X POST -H "X-API-Key: key" -F "file=@doc.pdf" -F "level=medium" http://localhost:8000/api/v1/compress | استدعاء من سطر الأوامر |
| Python | requests.post(url, headers={"X-API-Key":key}, files={"file":open("doc.pdf","rb")}, data={"level":"medium"}) | مكتبة requests |
| JavaScript | fetch(url, {method:"POST", headers:{"X-API-Key":key}, body:formData}) | واجهة Fetch API |
رابعًا: تحديد المعدل ومعالجة الأخطاء
تمتلك واجهة API آلية متكاملة لتحديد المعدل ومعالجة الأخطاء. إن فهم رموز حالة HTTP ورموز الأخطاء هو الأساس لكتابة كود استدعاء متين.
| رمز حالة HTTP | رمز الخطأ | المعنى | الإجراء المقترح |
|---|---|---|---|
| 200 | - | نجاح | تحليل بيانات الاستجابة |
| 400 | INVALID_PARAM | خطأ في المعاملات | التحقق من معاملات الطلب |
| 401 | UNAUTHORIZED | فشل المصادقة | التحقق من API Key/Token |
| 413 | FILE_TOO_LARGE | تجاوز حد حجم الملف | استخدام الرفع المجزأ |
| 429 | RATE_LIMITED | كثرة الطلبات | إعادة المحاولة مع تراجع أسي |
| 500 | INTERNAL_ERROR | خطأ في الخادم | إعادة المحاولة أو التواصل مع الدعم |
| 503 | SERVICE_UNAVAILABLE | الخدمة غير متاحة | الانتظار ثم إعادة المحاولة |
تفاصيل استراتيجية تحديد المعدل: 60 طلبًا في الدقيقة و10 طلبات متزامنة في الثانية افتراضيًا، و300 طلب في الدقيقة و30 طلبًا متزامنًا في الثانية في الإصدار المؤسسي. عند تجاوز الحد يتم إرجاع 429، وتتضمن ترويسة الاستجابة حقلَي X-RateLimit-Remaining (العدد المتبقي) وX-RateLimit-Reset (الطابع الزمني لإعادة الضبط). يُنصح بتنفيذ تراجع أسي على جانب العميل: عند استلام 429 انتظر ثانية ثم أعد المحاولة، وعند الفشل انتظر ثانيتين، ثم 4 ثوانٍ، وبحد أقصى 3 محاولات.
| نوع الملف | الحجم الأصلي | الحجم بعد الضغط | زمن الضغط | نسبة الضغط |
|---|---|---|---|---|
| PDF (مسح ضوئي) | 80 ميجابايت | 8.2 ميجابايت | 6.5 ثانية | 89.8% |
| PDF (إصدار إلكتروني) | 15 ميجابايت | 3.1 ميجابايت | 1.2 ثانية | 79.3% |
| صورة JPEG | 12 ميجابايت | 2.8 ميجابايت | 0.8 ثانية | 76.7% |
| صورة PNG | 25 ميجابايت | 6.5 ميجابايت | 1.5 ثانية | 74.0% |
| مستند OFD | 30 ميجابايت | 5.2 ميجابايت | 2.0 ثانية | 82.7% |
إذا كنت بحاجة إلى فهم مبادئ تصميم قائمة انتظار مهام الضغط الأساسية، يمكنك الرجوع إلى تصميم قائمة انتظار مهام الضغط. وإذا كنت تحتاج إلى نشر خدمة API عبر Docker، يمكنك الرجوع إلى نشر خدمة الضغط عبر Docker.
خامسًا: الأسئلة الشائعة FAQ
س1: كيف تتم مصادقة استدعاء واجهة برمجة الضغط؟
تدعم واجهة برمجة الضغط في خادم SmartSlim Server من UGLYPEAR DATA طريقتَي مصادقة: مصادقة API Key (إدخال المفتاح في ترويسة X-API-Key، مناسبة لاستدعاءات الخادم)، ومصادقة Bearer Token (إدخال JWT Token في ترويسة Authorization، مناسبة لاستدعاءات الواجهة الأمامية). يظل مفتاح API صالحًا بشكل دائم، ولكن يمكن إلغاؤه في أي وقت، بينما يبلغ عمر صلاحية الـ Token 24 ساعة ويحتاج إلى تجديد دوري. في بيئة الإنتاج يُنصح بطريقة API Key لبساطتها وموثوقيتها.
س2: ما صيغ الملفات التي تدعمها واجهة برمجة الضغط؟
تدعم واجهة برمجة الإصدار الخدمي PDF والصور (jpg/jpeg/tif) وصيغة OFD، بحد أقصى 1 جيجابايت للملف الواحد. تدعم واجهة برمجة الإصدار الشبكي 10 فئات رئيسية بأكثر من 40 صيغة (بما في ذلك الفيديو والصوت ومستندات Office وغيرها)، بحد أقصى 10 جيجابايت للملف الواحد. عند الاستدعاء يُحدَّد نوع الملف عبر معامل format، وفي حال عدم تمريره يُكشف تلقائيًا. انتبه إلى أن الإصدار الخدمي يدعم فقط PDF/الصور/OFD، أما جميع الصيغ فتتطلب الإصدار الشبكي.
س3: هل يوجد حد لتردد استدعاء واجهة برمجة الضغط؟
نعم، توجد استراتيجية تحديد معدّل لحماية استقرار الخدمة. الحد الافتراضي: 60 طلبًا في الدقيقة، و10 طلبات متزامنة في الثانية. عند التجاوز يُعاد رمز الحالة 429، وتتضمن ترويسة الاستجابة حقلَي X-RateLimit-Remaining وX-RateLimit-Reset. يمكن رفع الحد في الإصدار المؤسسي إلى 300 طلب في الدقيقة و30 متزامنًا في الثانية. يُنصح بتنفيذ آلية تراجع أسي على جانب العميل، وعند استلام 429 انتظر 1-2-4 ثوانٍ بشكل متزايد.
س4: كيف تتعامل واجهة برمجة الضغط مع الملفات الكبيرة؟
بالنسبة للملفات الكبيرة (التي تتجاوز 50 ميجابايت) يُنصح باستخدام واجهة الرفع المجزأ، حيث يُقسَّم الملف إلى أجزاء بحجم 5 ميجابايت، وبعد اكتمال رفع جميع الأجزاء يُخطر النظام بدمج الملف وضغطه. بعد اكتمال الضغط يمكن الحصول على النتيجة عبر الإشعار بالاستدعاء أو عبر الاستعلام الدوري عن الحالة. ضغط الملفات الكبيرة غير متزامن ولا يحجب استدعاءات API. يستغرق ضغط ملف PDF بحجم 100 ميجابايت نحو 8 ثوانٍ، وفيديو 1 جيجابايت نحو 90 ثانية، ويُولَّد رابط التنزيل تلقائيًا عند الاكتمال.
الخلاصة
توفّر واجهة RESTful API لخادم SmartSlim Server من UGLYPEAR DATA أربع واجهات رئيسية — الرفع والضغط، الضغط الدفعي، الاستعلام عن الحالة، والإشعار بالاستدعاء — لتغطية جميع السيناريوهات من ملف واحد إلى المعالجة الدفعية. طريقتا مصادقة للاختيار: API Key للخادم، وBearer Token للواجهة الأمامية. استراتيجية تحديد المعدل واضحة: 60 طلبًا في الدقيقة افتراضيًا و300 في الإصدار المؤسسي، مع رمز 429 يُرافقه إعادة المحاولة بتراجع أسي. ضغط PDF ممسوح ضوئيًا بحجم 80 ميجابايت إلى 8.2 ميجابايت في 6.5 ثانية فقط، بنسبة ضغط 89.8%.
احفظ ثلاث نقاط: أولًا، الملفات الأقل من 50 ميجابايت تُعيد النتيجة متزامنًا، أما الأكبر فتحتاج إلى الاستعلام بمعرّف المهمة؛ ثانيًا، عند رمز 429 نفّذ إعادة المحاولة بتراجع أسي، ولا تكرر المحاولة بعناد؛ ثالثًا، للملفات الكبيرة استخدم واجهة الرفع المجزأ بمقاطع 5 ميجابايت. اختيار الواجهة والمعاملات الصحيحة يجعل استدعاء واجهة برمجة الضغط في غاية البساطة. إذا كنت تفضّل تكامل SDK محليًا بدلاً من استدعاء HTTP، يمكنك الرجوع إلى دليل تكامل SDK للضغط.
مقالات ذات صلة
هل تحتاج إلى ضغط الملفات؟ جرّب SmartSlim من UGLYPEAR DATA
مبني على محرك ضغط Rust ذاتي التطوير، يدعم 10 فئات رئيسية بأكثر من 40 صيغة تشمل PDF والصور والفيديو وOffice وOFD، مع ضغط محلي لا تغادر فيه البيانات نطاقك.