التوثيق › أدلة › الجلب الذكي (تلقائي)

الجلب الذكي (تلقائي)

تقوم بتمرير URL وقاعدة validate لـ FourA تحدد ما يجب أن تحتويه الصفحة الحقيقية. وتقوم FourA بالباقي: فهي تتدرج عبر مستويات تراعي التكلفة، وتتوقف عند أول مستوى يعيد response تقبله قواعدك، وتتذكر ما نجح لكل مضيف بحيث يكون الطلب التالي على نفس الموقع رخيصاً.

يشرح هذا الدليل ما تفعله auto خلف الكواليس، ومتى يجب استخدامها، وكيفية قراءة الـ response الخاص بها. للحصول على مرجع المعلمات، راجع API Endpoints.

الفكرة

تجعلك معظم إعدادات الكشط تختار المحرك مقدماً. Single هو الأسرع، و Proxy يضيف التدوير، و Browser يتعامل مع JavaScript. إذا خمنت بشكل خاطئ، فستضيع الأرصدة أو يتم حظرك.

تعكس auto ذلك. أنت تعلن عن النجاح (validate)، وليس الطريقة. تتسلق FourA المستويات حتى ينجح أحدها:

  1. اختبار رخيص (single، مباشرة من شبكة FourA الخاصة)
  2. proxy single مُدوّر
  3. Browser، مع JavaScript وحل إذا فرض الموقع تحديات
  4. Browser عبر proxy لأصعب الأهداف

تتوقف auto بمجرد أن يعيد أحد المستويات response تقبله قاعدة validate الخاصة بك.

يكون الافتراضي لـ forceProxy هو true، لذلك يتم تخطي المستوى 1 ولن يرى الهدف عنوان FourA الخاص أبداً. تنتهي معظم الطلبات بعد ذلك في المستوى 2، أو في جلسة دافئة مُعاد تشغيلها. قم بتعيين forceProxy: false عندما تعلم أن الهدف يعامل العنوان النظيف بشكل أفضل من العنوان المُدوّر، وحينها يعود المستوى 1.

ما ترسله

الحد الأدنى هو URL بالإضافة إلى سلسلة فرعية validate. بدون validate.data.accept، لا يمكن لـ auto التمييز بين الصفحة الحقيقية وصفحة التحدي البينية المعادة مع HTTP 200، وقد تعيد التحدي كنجاح.

curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'

إعدادات اختيارية (راجع مرجع الـ endpoint للحصول على التفاصيل الكاملة):

  • returnSession (الافتراضي true): إرجاع الـ { proxy, cookies, userAgent } الفائز حتى تتمكن من إعادة تشغيله.
  • forceProxy (الافتراضي true): تخطي درجات الخروج المباشر. قم بتعيين false فقط إذا كنت تعلم أن الموقع أكثر تقبلاً لعنوان IP نظيف مقارنة بالـ rotating proxies المجانية.
  • timeout_ms (الافتراضي 120000): الميزانية الإجمالية للاستدعاء بأكمله. السلم يوزعها عبر الدرجات.
  • ignoreProxies: معرفات الـ proxy التي يجب تجنبها في كل محاولة فرعية.
  • followRedirects (الافتراضي 5): الحد الأقصى لعمليات إعادة التوجيه على الدرجات الرخيصة.

ما يتم إرجاعه

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

ثلاثة أشياء يجب قراءتها:

  • status و data: بنفس الشكل الذي أرجعه المحرك الأساسي. status هو حالة HTTP للهدف، وليس حالة النقل لاستدعائك إلى FourA. بالنسبة لدرجات single و proxy، فإن headers عبارة عن مصفوفة لكل قفزة. بالنسبة لدرجات browser، فإن headers عبارة عن كائن مسطح.
  • meta: تتبع ما فعله ladder، وهو موجود في كل response. meta.rung يسمي الخطوة التي قدمت الـ response، و meta.attempts يحسب محاولات الاستدعاءات الفرعية، و meta.solved يشير إلى ما إذا كان قد تم تخطي تحدي الروبوت، و meta.credits هو إجمالي التكلفة للاستدعاء (نفس الرقم الموجود في الـ header X-FourA-Credits).
  • session: الثلاثية { proxy, cookies, userAgent } التي اخترقت الهدف. استخدمها لإعادة التشغيل ضد نفس المضيف عبر /api/single/ أو /api/browser/.

يجيب Auto بالحالة HTTP 200 كلما تم تشغيل ladder، حتى عند فشل كل درجة. اقرأ status و error في النص لمعرفة ما حدث، وليس كود حالة النقل. تعني الحالة غير 200 من /api/auto/ أن FourA رفض الاستدعاء قبل بدء ladder: 401 لمفتاح غير صالح، 400 لـ body غير صالح أو هدف خاص، 429 أو 503 لـ rate limits.

إعادة التشغيل باستخدام Session

بعد أن يرجع auto جلسة (session)، يمكنك الانتقال مباشرة إلى Single أو Browser للصفحات التابعة على نفس المضيف. لا يوجد تسلق جديد لـ ladder، ولا فحص جديد.

import requests

API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])

تكون الجلسة مستدامة بقدر ما يسمح به الهدف فقط. تربط بعض المواقع التصريح بملفات تعريف الارتباط (cookie) لساعات، بينما يقوم البعض الآخر بتدويرها كل بضع دقائق. إذا بدأ إعادة التشغيل في إرجاع التحديات مرة أخرى، قم باستدعاء /api/auto/ مرة أخرى للتحديث.

متى تستخدم Auto

استخدام auto استخدام single أو proxy أو browser يدويا
أنت تستهدف موقعا جديدا ولا تعرف ما يحتاجه أنت تعرف بالفعل المحرك الذي يعمل
تريد استدعاء واحدا يتعامل مع التراجع (fallback) لـ direct و proxy و browser نيابة عنك تريد تحكما كاملا في عمليات إعادة المحاولة والمهل الزمنية لكل استدعاء
لا تمانع في قضاء بضع ثوان في الفحص عند الاستدعاء الأول زمن انتقال الاستدعاء الأول أكثر أهمية من الاكتشاف
تريد جلسة مكتسبة يمكنك إعادة تشغيلها بتكلفة منخفضة أنت تقوم بتحسين حلقة ضيقة على هدف معروف بأنه جيد

لا يعد Auto دائما الخيار الأرخص. إذا كنت تعرف أن الهدف يعمل مع single + unblocker، فإن استدعاء Single مباشرة يكلف رصيدين (2 credits) مع زمن انتقال يمكن التنبؤ به. يكلف استخدام Auto على نفس الهدف ما ينفقه السلم الخاص به، والذي يمكن أن يكون أكثر إذا كان الموقع يتطلب التصعيد.

يخبر Validate ميزة Auto بما يعنيه "النجاح"

المعلمة الأكثر أهمية على الإطلاق هي validate. بدونها، لا يمكن لـ auto التمييز بين صفحة 200 حقيقية وشاشة تحدي 200 بينية متنكرة في شكل محتوى.

استخدم validate.data.accept مع سلسلة فرعية (substring) لا تحتوي عليها سوى الصفحة الحقيقية:

{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}

بالنسبة لـ JSON APIs، اقبل اسم الحقل الذي تتوقعه:

{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}

بالنسبة للمواقع التي تُرجع استجابات بخلاف 200 بشكل شرعي (الحظر الجغرافي الذي ترغب في تجاهله، أو 403 المتعمدة في الـ endpoints عند تسجيل الخروج)، اسمح بها عبر validate.status.accept:

{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}

بدون validate، يعود الوضع التلقائي إلى "HTTP 200 = نجاح" ولن يكتشف اعتراض تحدي Cloudflare الذي يعيده جدار حماية تطبيقات الويب (WAF) برمز 200.

قراءة meta.rung لفهم ما حدث

يعد meta.rung إشارة تصحيح الأخطاء الأكثر فائدة. القيم:

  • probe - تم الحل في request مباشر رخيص. المسار الأرخص.
  • proxy - تطلب تدوير الـ proxy للعبور.
  • browser - تطلب تصيير كامل للمتصفح، وربما مع حل التحدي.
  • cache - أعاد تشغيل جلسة نشطة من استدعاء تلقائي سابق. المسار الأرخص في الاستدعاءات المتكررة.
  • fail - لم ينتج أي مستوى response تقبله قواعدك.

يعني meta.solved: true أنه تم اكتشاف تحدي روبوت وتم تخطيه أثناء الاستدعاء. meta.attempts هو عدد محاولات الاستدعاء الفرعي قبل النجاح. للحصول على تفاصيل المورد وراء الحل، اقرأ حقل defense الذي تعيده مستويات single و proxy: راجع دفاعات مكافحة الروبوتات.

إذا استمر الموقع في الانتهاء عند browser عندما توقعت probe، ففكر فيما إذا كانت قاعدة validate الأكثر صرامة (أو الأقل صرامة) ستسمح بمرور مستوى أرخص. تذكر أن forceProxy يُعين افتراضيا على true، لذلك يتم تخطي فحص الخروج المباشر ما لم تقم بإيقاف تشغيله.

الأخطاء والحالات الطرفية

عندما يفشل الوضع التلقائي، يحمل الـ response status (وعادة ما تكون حالة آخر مستوى فشل) وسلسلة error نصية:

{
  "status": 0,
  "error": "all attempts failed",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status: 0 يعني عدم إنتاج أي مستوى لاستجابة على الإطلاق (كل محاولة انتهت مهلتها أو رُفضت). وجود status بقيمة غير صفرية بالإضافة إلى error يعني أن المحاولة الأخيرة تلقت استجابة، لكن auto رفضها (عبر validate أو غير ذلك).

تحقق من meta.attempts و meta.credits لمعرفة أين تم استهلاك الميزانية. إذا كان meta.attempts مرتفعا وكان meta.rung هو fail بعد مستوى browser، فقد يحتاج الهدف إلى timeout_ms أطول، أو قاعدة validate أكثر صرامة، أو ببساطة لا يمكن الوصول إليه عبر proxies الدورية في الوقت الحالي.

ما لا يفعله Auto

  • لا يتجاوز القيود القانونية. إذا كان الموقع محظورا جغرافيا ويرفض كل مخرج يمكن لـ FourA الوصول إليه، فسيعيد auto الحظر.
  • لا يقوم بتخزين المحتوى مؤقتا. كل استدعاء لا يزال يصل إلى الهدف. الجلسة الدافئة هي الـ proxy والـ cookies، وليس الاستجابة.
  • لا يكتب في Activity Log كصف منفصل عن الاستدعاءات الفرعية. الاستدعاءات الفرعية Single / Proxy / Browser التي أجراها auto نيابة عنك تظهر في النشاط؛ استدعاء /api/auto/ الخارجي يعمل كمنسق.

ذات صلة

آخر تحديث: 12 أغسطس 2026
← التعامل مع حماية مكافحة الروبوتات