قواعد Validate تحدد الآن ما يُعد نجاحاً

تحدد قواعد validate الخاصة بطلبك الآن كيفية تصنيف كل نتيجة. إذا حددت أن كود 403 مقبول، فسيُحتسب كود 403 المُسلَّم كعملية ناجحة، وتتم فوترته كنجاح، ويظهر في موجز Activity جنباً إلى جنب مع استجابات 200.

قد يبدو هذا التغيير بسيطاً، لكنه يغير طريقة قياس دقة scraping على نطاق واسع.

آلية العمل

يحصل كل request إلى FourA على واحدة من سبع نتائج تحدد الفوترة والتحليلات. نتيجة success فقط هي الخاضعة للفوترة. وتتوزع باقي النتائج حسب الطرف المسؤول عن الفشل:

نتيجتا application_fail و application_error عندما يرفض الموقع الهدف الطلب أو يرجع جسم استجابة يحتوي على خطأ
نتيجة client_error عندما يكون الـ request المرسل مشوهاً أو غير صالح
نتائج service_fail و service_error و rate_limit عندما يعيق خطأ من جانبنا تنفيذ الطلب

قبل هذا التغيير، كان النجاح يعني شيئاً واحداً فقط: HTTP 200. وكانت استجابة 403 تُصنف دائماً كـ application_fail، حتى لو كنت تعلم أن كود 403 هو الاستجابة المطلوبة. (تُرجع بعض واجهات برمجة التطبيقات API للبيانات الرياضية كود 403 للأسواق المقيدة جغرافياً، وهذه هي الإشارة المحددة التي ينتظرها كودك.)

الآن، يحدد قسم validate النتيجة. ينفذ الـ request قواعدك أثناء المعالجة، وإذا كانت الاستجابة تطابقها، تصبح النتيجة success.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/feed",
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 403] },
      "data": { "fail": ["captcha", "Access Denied"] }
    }
  }'

يعامل هذا 200 و 403 كرموز حالة صالحة. إذا كان نص الاستجابة (body) يحتوي على علامة صفحة تحقق أو نص رفض الوصول، يفشل الطلب. أي شيء آخر يعتبر success.

قاعدتان يجب تذكرهما:

بدون validate، يبقى السلوك دون تغيير. الطلبات التي لا تحدد التحقق من الصحة تستمر في الفوترة بناءً على HTTP 200 فقط. الأمر اختياري لك.
validate يعمل في الاتجاهين. قواعد القبول تمرر الطلب؛ وقواعد الفشل ترفضه. وهما يتكاملان. لذا يمكنك قبول [200, 403] ومع ذلك ترفض الطلب عندما يحتوي الـ body على محتوى غير صحيح.

التأثير

هذا التغيير مهم للغاية للفرق التي تُرجع أهدافها استجابات غير 200 ولكنها تحتاج إليها بالفعل.

أمثلة من طلبات نراها يومياً:

واجهات برمجة تطبيقات (APIs) للبيانات الرياضية التي تُرجع 403 للأسواق المقيدة جغرافياً (بيانات لا تزال مفيدة، وتستحق التسجيل كنجاح)
نقاط نهاية البحث في التجارة الإلكترونية التي تُرجع 404 عندما يكون المنتج غير متوفر في المخزون (إشارة يقرؤها الكود الخاص بك، وليست فشلاً)
واجهات برمجة تطبيقات البث والمحتوى الجزئي التي تُرجع 206

قبل التغيير، كانت تلك الفرق تجري تدقيقاً خاصاً بها فوق سجلات Activity لدينا. لم يكن بإمكانهم الوثوق بعمود outcome لأن تعريفهم للنجاح لم يكن يطابق تعريفنا. وكانت الفوترة تتم بناءً على رقم لا يهمهم في الواقع.

الآن يعكس العمود الواقع. تُظهر علامة التبويب Activity في Dashboard ما حددته أنت كنجاح، وليس ما خمنّاه نحن. إجماليات الفوترة لديك تطابق ما كنت ستحسبه بنفسك (نتائج مبكرة: التغيير يُطبق على ما هو قادم فقط، لذا تحتفظ صفوف Activity القديمة بتصنيفها الأصلي).

الأثر العملي على مهام الكشط (scraping): خطوات مطابقة أقل بين مسار معالجة البيانات لديك وفاتورتنا. إذا كنت تقوم بالفعل بالتحقق من نص الاستجابة بعد استلامها، يمكنك نقل هذا الشرط إلى الطلب نفسه والتوقف عن صيانة مجموعة موازية من قواعد النجاح/الفشل خارج API الخاص بنا. تعريف واحد لما إذا كان الطلب قد استحق مكانه في مجموعة بياناتك، بدلاً من تعريفين متعارضين.

لكننا احتفظنا بشبكة الأمان. إذا لم تقم بتمرير كتلة validate، فلن يتغير شيء. يعود المصنف تلقائياً إلى "200 يعني النجاح" حتى تعمل الطلبات التي كانت تعمل بالأمس بنفس الطريقة اليوم.

للمستخدمين المتقدمين

يقبل validate ثلاث مجموعات قواعد تعمل بشكل مستقل: status، و headers، و data. تقبل كل منها قوائم accept و fail اختيارية.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/9876",
    "followRedirects": 5,
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 304] },
      "headers": { "accept": { "content-type": "application/json" } },
      "data": { "accept": ["\"price\":"], "fail": ["maintenance", "captcha"] }
    }
  }'

يتطلب هذا ما يلي:

أن تكون حالة الـ Status هي 200 أو 304
أن يُعلن الـ Response عن content type من نوع JSON
أن يحتوي الـ Body على حقل price
ألا يحتوي الـ Body على إشعار صيانة أو صفحة تحقق

إذا فشلت أي قاعدة، تكون النتيجة application_fail. وإذا نجحت كل القواعد، تكون النتيجة success. يعمل المصنف داخل الـ request نفسه، مما يجنبك الـ round trip التي تتطلبها خطوة تحقق منفصلة.

عند دمجه مع followRedirects: يتم تتبع ما يصل إلى 5 قفزات، ثم التحقق من صحة الـ response النهائي. يؤدي التبديل الخادع من URL سليم إلى صفحة تحقق إلى الفشل بشكل نظيف بدلا من تلويث مجموعة بياناتك.

ونصيحة من واقع تشغيل أدوات الـ scraping الخاصة بنا: صرح عن أنماط data.fail بحزم. يُعد الحصول على 200 OK مع صفحة تحقق بداخلها أكثر أنماط الفشل الصامت شيوعا في المواقع المحمية. تعامل مع الـ body كمرجع أساسي، وليس مع الـ status code.

للاطلاع على الـ schema الكاملة، يسرد مرجع الـ request كل حقل من حقول validate وكيفية تركيب كل منها.

ما التالي

نعمل حاليا على توفير عناصر قواعد أكثر ثراء: أدوات مطابقة بالـ regex لـ data، ومحددات JSON-path بنيوية، ومطابقة أكثر مرونة للـ headers. المبدأ يظل ثابتا. أنت تحدد كيف يبدو النجاح؛ والـ API يلتزم به بشكل شامل، بدءا من الـ request وحتى فاتورتك.

عندما يتعطل الـ scraper الخاص بك، يجب أن يظهر ذلك بوضوح. وعندما يعمل وفق قواعد كتبتها بنفسك، يمكنك الوثوق بتلك النتيجة تماما.