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

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

أنت تمرر إلى FourA عنوان URL وقاعدة validate لما يجب أن تحتويه الصفحة الفعلية. يتولى FourA الباقي: يتدرج عبر سلم يراعي التكلفة، ويتوقف عند أول درجة تُرجع استجابة تقبلها قواعدك، ويتذكر ما نجح لكل مضيف حتى يكون الاستدعاء التالي على نفس الموقع منخفض التكلفة.

يشرح هذا الدليل ما يفعله وضع auto داخليا، ومتى تستخدمه، وكيف تقرأ استجابته. للاطلاع على مرجع المعلمات، راجع نقاط نهاية API.

الفكرة

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

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

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

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

توجد درجة واحدة خارج هذا الترتيب. عندما يصل مسار خروج إلى الموقع ولكن الموقع يرفض عنوان URL العميق المطلوب، يجلب auto صفحة الدخول للموقع من خلال مسار الخروج نفسه، ويحتفظ بملفات cookie التي تقدمها صفحة الدخول، ثم يطلب عنوان URL الخاص بك مجددا وهو يحملها. هذه هي درجة warmup. يتم تشغيلها فقط على عنوان URL أعمق من جذر الموقع، وفقط بعد فشل المحاولة المباشرة بالفعل، ولا يمكنها سوى إضافة نتيجة ناجحة، دون إلغاء أي نتيجة سابقة.

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

ما ترسله

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

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): تخطي درجات الخروج المباشر (direct-egress). قم بتعيين false فقط إذا كنت تعلم أن الموقع يتعامل بشكل أفضل مع IP نظيف مقارنة بالـ proxies التدويرية المجانية.
  • timeout_ms (الافتراضي 120000): الميزانية الإجمالية لكامل الاستدعاء. يقوم السلم بتوزيعها عبر الدرجات.
  • ignoreProxies: معرفات proxy لتجنبها في كل محاولة فرعية.
  • followRedirects (الافتراضي 5): الحد الأقصى لإعادة التوجيه (redirects) في الدرجات منخفضة التكلفة.

ما تحصل عليه في المقابل

{
  "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: استجابة الهدف. data عبارة عن نص في كل مستوى: صفحة JSON تعود كسلسلة نصية JSON حتى عندما يخدمها متصفح، لذا قم بتحليلها من جانبك. status هي حالة HTTP الخاصة بالهدف، وليست حالة النقل لطلبك إلى FourA. بالنسبة لمستويات single و proxy، فإن headers عبارة عن مصفوفة لكل قفزة (per-hop array). بالنسبة لمستويات browser، فإن headers عبارة عن كائن مسطح (flat object).
  • meta: أثر ما قام به السلم التدريجي، ويكون موجودا في كل استجابة بمجرد بدء السلم. يحدد meta.rung اسم الخطوة التي قدمت الاستجابة، ويحسب meta.attempts محاولات الطلبات الفرعية، ويوضح meta.solved ما إذا تم إكمال صفحة التحدي، ويمثل meta.credits إجمالي التكلفة للطلب (نفس الرقم في ترويسة X-FourA-Credits).
  • session: ثلاثية { proxy, cookies, userAgent } التي تجاوزت حماية الهدف. استخدمها لإعادة التشغيل مقابل نفس المضيف عبر /api/single/ أو /api/browser/.

يستجيب وضع Auto بـ HTTP 200 كلما تم تشغيل السلم، حتى عندما تفشل جميع المستويات. اقرأ status و error في متن الاستجابة لمعرفة ما حدث، وليس رمز حالة النقل. أي رمز غير 200 من /api/auto/ يعني أن الطلب لم يصل إلى السلم أبدا: 401 لمفتاح غير صالح، و 400 لمتن ليس بتنسيق JSON صالح أو لهدف على شبكة خاصة، و 502 أو 503 أو 504 عندما يتعذر على الخدمة استقبال الطلب أو عند نفاد الوقت. لا يستهلك Auto أي مساحة عند البوابة، لذا فإن الحدود المشتركة للمنصة لا ترفض الطلب نفسه: عندما يرفض أحدها طلبا أجراه السلم، تكون الاستجابة HTTP 200 مع وجود status: 429 أو 503 و retryAfter في متن الاستجابة. الحقل الذي يفشل في التحقق يرجع أيضا كـ HTTP 200، مع status: 400. والوصول إلى حد الخطة داخل السلم يعود أيضا كـ HTTP 200، مع وجود الرفض في متن الاستجابة (راجع عندما تصل حدود خطتك إلى السلم).

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

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

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"])

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

متى تستخدم Auto

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

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

توضيح معنى "النجاح" لـ Auto عبر Validate

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

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

{
  "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، يعتمد auto تلقائيا على قاعدة "HTTP 200 = نجاح" لكل صفحة لا يتعرف عليها كاختبار challenge، وبالتالي لن يكتشف صفحات التحقق غير المألوفة التي يعيدها الموقع مع الرمز 200.

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

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

  • probe: تم الحل عبر request مباشر منخفض التكلفة. المسار الأقل تكلفة.
  • proxy: تطلب الأمر تدوير proxy للعبور.
  • browser: تطلب الأمر معالجة كاملة عبر متصفح، وربما حل اختبار challenge.
  • cache: تمت إعادة استخدام session جاهزة من استدعاء auto سابق. المسار الأقل تكلفة في الاستدعاءات المتكررة.
  • warmup: قدم الموقع صفحته الرئيسية لكنه حظر عنوان URL العميق، لذا جلب auto الصفحة الرئيسية أولا، واحتفظ بملفات cookie المقدمة، ثم أعاد الطلب باستخدامها. الـ session المخزنة من هذا المستوى غير مرتبطة بمخرج واحد، لذا تعتمد الاستدعاءات اللاحقة على المستويات منخفضة التكلفة.
  • fail: لم ينتج أي مستوى استجابة تقبلها قواعدك.

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

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

الأخطاء والحالات الاستثنائية

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

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status هي استجابة الموقع في المحاولة الأخيرة التي رفضها auto، مثل 403. عندما لا تتلقى أي محاولة ردًا من الموقع على الإطلاق، فإنها تكون عادةً 502 أو 504، ويوضح error ما إذا كان لم يتم العثور على نقطة خروج تعمل أو إذا استُنفدت ميزانية timeout_ms. تعني status: 0 فقط أن اسم مضيف الهدف لم يتم حله، وهذه الاستجابة لا تحتوي على meta لأن السلم لم يبدأ أصلًا.

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

عندما تصطدم حدود خطتك بالسلم

تعد الاستدعاءات الفرعية في وضع Auto مجرد طلبات Single و Proxy و Browser عادية تحت مفتاحك، لذا تنطبق عليها حدود خطتك. يقرأ السلم رمز X-FourA-Limit عند الرفض ويتعامل مع النوعين بشكل مختلف.

المرحلة المغلقة تترك بقية السلم قابلة للاستخدام. يؤدي الرمز plan_limit_browser_daily (استنفاد طلبات Browser اليومية الخاصة بك) والرمز plan_limit_concurrency (يحتوي endpoint هذا بالفعل على عدد طلبات قيد التشغيل يطابق الحد الأقصى المسموح به في خطتك) إلى إغلاق مرحلة واحدة. يستمر Auto في تشغيل المراحل الأخرى، لذا ستستمر في تلقي الصفحة متى ما وفر مخرج متناوب أو جلسة نشطة المحتوى، ولا يتم لوم نقاط الخروج التي تمت تجربتها على رفض ناتج عن خطتك نفسها. لا يتم حظر أي شيء ولا يتم التخلص من أي جلسة.

الحساب غير المستوفي يوقف السلم تمامًا. لا يمكن للمراحل الأخرى معالجة الحالات plan_limit_credits، و plan_limit_bandwidth، و plan_limit_rate، و plan_limit_feature، و plan_limit_premium، لذا يعود auto فورًا بدلًا من استهلاك المزيد من رصيدك لإثبات ذلك. يرجع الرفض في body مع حالة الاستدعاء الفرعي ونفس حقل reason الذي تستخدمه endpoints المباشرة:

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

يصل جسم الرفض بالكامل من الطلب الفرعي، بالإضافة إلى status وmeta. اقرأ status من الجسم وليس من حالة النقل: لا يزال auto يستجيب برمز HTTP 200 هنا، لأن خطوات الترقية تم تنفيذها. يصل رفض plan_limit_feature أو plan_limit_premium بالطريقة نفسها مع status: 403. لا يستهلك الطلب الفرعي المرفوض أي رصيد، لذا يحسب meta.credits فقط الخطوات التي وصلت بالفعل إلى الهدف.

يمكن لطلب auto واحد أن يشغل عدة خانات أثناء تنفيذ خطواته المتتالية، وبالتالي فإن دفعة متوازية من طلبات auto تصل إلى الحد الأقصى للتزامن بعدد طلبات أقل مما تتوقع. يغطي تشغيل الطلبات بالتوازي كيفية تحديد حجم الدفعة.

ما لا يفعله Auto

  • لا يغير القيود القانونية. إذا رفض أحد المواقع كل نقطة خروج يمكن لـ FourA الوصول إليها، فإن auto يعيد هذا الرفض.
  • لا يخزن المحتوى مؤقتا (cache). كل طلب يصل إلى الهدف الفعلي. "الجلسة النشطة" (warm session) تعني الـ proxy وملفات تعريف الارتباط، وليست الـ response.
  • يظهر كصف واحد في سجل النشاط، تحت معرف الطلب الذي استلمته، مع مجموع أرصدة طلباته الفرعية. عند فتحه، ستجد طلبات Single / Proxy / Browser الفرعية التي أجراها auto نيابة عنك مدرجة كمحاولات، ولكل منها نتيجتها الخاصة. تُحسب هذه المحاولات ضمن حدود Single وProxy وBrowser الخاصة بك، ولا تُحسب أبدا ضمن عدد الطلبات الإجمالي أو معدل النجاح.

مواضيع ذات صلة

آخر تحديث: 30 سبتمبر 2026
← كيفية احتساب استهلاك خطتك