Playground

تتيح لك أداة Playground (الشريط الجانبي > Playground) تنفيذ طلبات API مباشرة باستخدام مفتاحك الفعلي دون كتابة أي كود. إنها أسرع طريقة لتجربة موقع هدف جديد، أو تصحيح أخطاء استجابة معقدة، أو مقارنة أوضاع Auto و Single و Proxy و Browser جنبًا إلى جنب.

افتحها عبر الرابط foura.ai/dashboard#playground.

ما تقدمه الأداة

نموذج واحد. أربعة محركات. ترافيك فعلي.

Auto: جلب ذكي. تقوم بتمرير URL بالإضافة إلى قاعدة validate وتختار FourA المسار الأقل تكلفة الذي يعمل بنجاح.
Single: جلب HTTP مباشر بخصائص شبكة واقعية تحاكي المتصفح
Proxy: جلب عبر proxy مدار بتدوير تلقائي، مع إمكانية تحديد بلدان مستهدفة بعينها
Browser: يفتح الرابط URL داخل مثيل متصفح Chrome للمواقع التي تعتمد على تصيير JS

تُنفذ الطلبات باستخدام مفتاح API الذي تختاره في أعلى الصفحة. يُحسب الاستخدام من حصة هذا المفتاح تمامًا مثل أي استدعاء في بيئة الإنتاج، لذا تجنب استهلاك خطتك أثناء الاختبار.

اختيار المفتاح

تعرض القائمة المنسدلة لمفاتيح API كل مفتاح نشط يمكنك استخدامه: مفاتيحك الخاصة تحت My Keys، ثم مجموعة لكل مؤسسة تنتمي إليها. يمكن لأي عضو استخدام مفتاح المؤسسة، ويُحسب أي طلب يُجرى بواسطته من خطة مالك المؤسسة. اختر المفتاح الذي تريد احتساب تكلفة الطلب عليه. إذا لم تكن تمتلك أي مفاتيح نشطة بعد، فستظهر مطالبة مضمنة توجهك إلى صفحة API Keys لإنشاء مفتاح.

اختيار الوضع

يتيح لك صف Mode العلوي التبديل بين Auto والمحركات اليدوية. عند تحديد Auto، يتحول النموذج إلى واجهة Auto المبسطة (رابط URL مع validate وبعض الإعدادات البسيطة). يُعرض كلا الصفين دائمًا: Mode: Auto، وProduct: Single، Proxy، Browser. يؤدي اختيار أحدهما إلى إلغاء تحديد الآخر. يؤدي تبديل المنتجات إلى تغيير الحقول المرئية والمحرك الذي يتلقى الطلب. يتم الاحتفاظ بالاختيار الحالي عند إعادة تحميل الصفحة.

Mode	متى يُستخدم
Auto	موقع هدف جديد أو موقع ذو حماية مختلطة. يختار Auto المسار الأقل تكلفة ويتذكر ما يعمل بنجاح.
Single	جلب HTTP سريع. الخيار الأول الأنسب للمضيفين المعروفين.
Proxy	نفس عملية الجلب مع تدوير تلقائي للـ proxy. قم بتعيين `exitCountries` عندما تحتاج إلى بلد محدد يظهر للهدف.
Browser	يُحمّل الصفحة داخل مثيل متصفح Chrome. يُستخدم عندما لا تظهر البيانات إلا بعد تشغيل JavaScript.

بناء الطلب

صف URL

يحتوي الصف العلوي على طريقة HTTP‏ (GET، POST، PUT، PATCH، DELETE، HEAD، OPTIONS)، ورابط URL المستهدف، وزر Send. تدعم أوضاع Single و Proxy و Auto جميع الطرق. بينما يتجاهل Browser طريقة الطلب (يستخدم Chrome دائمًا GET للتنقل) ويتجاهل الـ body أيضًا.

تبويبات الطلب

أسفل صف URL، تتيح لك خمسة تبويبات ملء بقية التفاصيل:

علامة التبويب	ما تتحكم فيه
UI	حقول النموذج لمهلات الانتظار، وإعادة التوجيه، والرايات (flags)، والـ proxy، والخيارات الخاصة بالمتصفح، وقواعد التحقق
Body	جسم الطلب بصيغة حرة لطلبات POST / PUT / PATCH
Headers	ترويسات الطلب المخصصة كأزواج مفتاح وقيمة
Cookies	ملفات تعريف الارتباط لإرسالها مع الطلب
Raw	حمولة JSON الدقيقة التي سيتم إرسالها، كمعاينة للقراءة فقط مع Copy JSON، وأمر cURL لإعادة الإنتاج أسفلها

أي تغيير تجريه في UI / Body / Headers / Cookies ينعكس في Raw. لا يمكنك الكتابة داخل Raw: عدل الطلب من علامات التبويب الأخرى. تظهر نقطة حمراء على أي علامة تبويب أو قسم قابل للطي يحتوي على قيمة تختلف عن القيم الافتراضية للمحرك، حتى تتمكن من ملاحظة ما قمت بتخصيصه بنظرة سريعة.

أقسام لوحة UI

تجمع علامة التبويب UI الإعدادات في أقسام قابلة للطي. تعود الحقول الفارغة إلى القيمة الافتراضية لمخطط المحرك. يتم إخفاء الأقسام التي لا تنطبق على الوضع الحالي.

Timeouts: timeout_ms، connect_timeout_ms، accept_timeout_ms، server_response_timeout_ms، dns_cache_timeout_sec. يعرض Auto فقط timeout_ms (إجمالي الميزانية المحددة).
Redirects: تبديل وتعيين followRedirects (0-20). Single و Proxy. يتبع المتصفح عمليات إعادة التوجيه تلقائيا.
Flags: unblocker لـ Single و Proxy و Browser (unblocker في Browser يكمل الفحوصات التي تطلبها الصفحة)؛ tryJsonData و returnBuffer لـ Single و Proxy. يعرض Auto الخيارين forceProxy و returnSession بدلا من ذلك.
Proxy: اختر معرف proxy محدد لـ Single أو Browser، أو اضبط maxTries، ومهلة الانتظار الخارجية لـ Proxy، و exitCountries، و exitClass، و ignoreProxies لمحرك Proxy. يعرض Auto أيضا ignoreProxies. تحتوي قائمة الاختيار exitClass على ثلاث حالات: يؤدي عدم التعيين إلى عدم إرسال أي حقل على الإطلاق، بينما يشير standard إلى أن الطلب يجب ألا يتم تصعيده أبدا، ويسمح premium بتصعيده إلى مخرج premium عندما يواجه التجمع القياسي صعوبات. تعد الحالة غير المعينة و standard طلبين مختلفين، لذا اترك قائمة الاختيار فارغة ما لم تقصد أحدهما. يتطلب Premium خطة تتضمن مخارج premium: راجع exitClass.
Browser profile: ثلاث قوائم منسدلة متتالية، os، و browser، و version، تسرد ما يمكن لـ FourA تقديمه فعليا. تظهر في وضعي Single و Proxy. اتركها فارغة للحصول على أحدث إصدار من Chrome. كل قائمة اختيار تضيق نطاق القائمتين الأخريين، لذا فإن أي تركيبة لا تؤدي إلى نتيجة لن تظهر أبدا. يحتاج القسم إلى تفعيل unblocker: فمع إيقافه لا يتم إرسال ترويسات المتصفح، وسيتم تطبيق ملف التعريف بشكل جزئي فقط، وسيرفض الـ API الطلب بدلا من ذلك.
Browser: خيارات خاصة بالمتصفح فقط مثل checkStatus و checkText.
Validate: يقبل status accept و status fail رموز حالة مفصولة بفواصل (validate.status)، ويقبل body accept و body fail سلاسل فرعية مع بدائل مفصولة بـ | (validate.data). متاح لـ Single و Proxy و Auto. يستخدم Browser الخيارين checkStatus و checkText بدلا من ذلك. لا يحتوي النموذج على حقل لقواعد الترويسات (validate.headers).

بمجرد أن يرجع التشغيل proxy يعمل بنجاح، يظهر قسم Working proxies في نهاية تبويب واجهة المستخدم. يسرد ما يصل إلى 20 معرف proxy، الأحدث أولاً، كل منها مع بلد الخروج والوقت الخاص به. يؤدي الزر use إلى إدراج واحد في حقل proxy في Single أو Browser (محرك Proxy يكتشف محركه الخاص)، بينما يحذفه × من القائمة.

تحديد نطاق بلد الخروج (وضع Proxy)

يقبل حقل exitCountries في Proxy قائمة مفصولة بفواصل من رموز البلدان المكونة من حرفين المرئية للهدف (CZ, GB). يتم اقتطاع المسافات من القيم وتحويلها إلى أحرف كبيرة وإزالة التكرارات عند الإرسال. الاختيار عبارة عن قائمة سماح صارمة: يتم استبعاد خوادم proxy ذات مخارج الخروج غير المعروفة ولا يعود الطلب أبداً إلى بلد آخر كبديل. إذا لم يحتوي المجمع الحالي على أي تطابق، يُرجع الاستجابة code: "no_eligible_proxy" مع تكرار النطاق المطلوب في details.exitCountries. احتفظ بالنطاق وأعد المحاولة لاحقاً.

عندما ينجح استدعاء proxy ضمن تحديد النطاق، يُظهر شريط الاستجابة exit <CODE> بجوار معرف proxy لتتمكن من التحقق من أن البلد الذي تم التقديم منه يطابق ما طلبته.

إعادة تعيين شريط الأدوات

يمسح زر Reset الموجود على شريط الأدوات (بجوار History و Saved) مساحة التجربة ليعيدها إلى حالة أولية نظيفة. نظراً لأنه إجراء حذفي، فإنه يفتح مربع حوار تأكيد يسرد بدقة ما سيتم مسحه: جميع نماذج المنتجات الثلاثة (Single و Proxy و Browser)، وأي cookies محفوظة في الجرة، وأي خوادم proxy منقولة، والاستجابة الحالية. يتم الاحتفاظ بالإعدادات المسبقة المحفوظة ومفتاح API المحدد. انقر فوق Reset everything للتأكيد؛ وأي إجراء آخر يلغي العملية.

الإرسال والإلغاء

انقر فوق Send لإطلاق الطلب. يتحول العمود الأيمن إلى حالة التحميل مع مؤشر دوار وزر Cancel أثناء تشغيل الاستدعاء. انقر فوق Cancel (أو اضغط على الزر مرة أخرى على الهاتف المحمول) للإلغاء. يستعيد الطلب الملغى العنصر النائب في وضع الخمول مع عبارة "Request canceled." بدلاً من عرض خطأ.

تتحول بطاقة الاستجابة إلى النتيجة بمجرد اكتمال الطلب (أو فشله). يمكن أن تستغرق عمليات التشغيل في الوضع Auto وقتاً أطول من المحركات اليدوية لأن السلم قد يصعد عدة درجات مع هدف بارد.

قراءة الاستجابة

يعكس عمود الاستجابة تخطيط الطلب بتبويباته الخاصة:

Tab	What it shows
Body	نص الاستجابة المُحلل. يتنقل بين عروض JSON و HTML و Text بناءً على ما تم إرجاعه.
Headers	ترويسات الاستجابة، ترويسة واحدة في كل سطر.
Cookies	ملفات cookies التي أرجعها الهدف، في كل من العرض المُحلل (مجمعة حسب المضيف) وعرض النص الخام (Set-Cookie). يعرض العرض المُحلل شارة `HO` على ملفات cookies الخاصة بالمضيف فقط؛ وتظل ملفات cookies الخاصة بالنطاق بدون علامة.
Raw	غلاف JSON الكامل الذي تم إرجاعه بواسطة API.

يحتوي شريط أدوات الاستجابة على Copy و Download للاستجابة بأكملها، و Find in response (Ctrl+K أو Cmd+K) للبحث في التبويب المفتوح، مع استخدام Enter و Shift+Enter للتنقل بين التطابقات. تحتوي تبويبات Body و Headers و Cookies أيضاً على أزرار Copy و Download خاصة بها لكل تبويب على حدة.

يعرض شريط البيانات الوصفية أعلى علامات التبويب حالة HTTP المصدرية، والوقت الإجمالي، ومُعرّف proxy الذي تعامل مع الطلب، بالإضافة إلى رمز exit <CODE> المكون من حرفين (لطلبات Proxy المحددة النطاق). بالنسبة لعمليات تشغيل Auto، يعرض الشريط أيضًا درجة السلم التي قدمت الاستجابة، وعدد المحاولات الفرعية التي تم إجراؤها، والرصيد المستهلك.

ما تطلبه الاستدعاء

توضح جملة أسفل شريط البيانات الوصفية الآلية التي نفذت الصفحة نصيًا. بالنسبة لعملية تشغيل Auto، تحدد الجملة درجة السلم (جلسة كانت لدى FourA بالفعل للمستضيف، أو request عادي، أو rotating proxy، أو متصفح حقيقي، أو متصفح أولاً ثم إعادة تشغيل منخفضة التكلفة)، وما إذا كان قد تم حل تحدٍ، وعدد المحاولات المستغرقة، وتكلفتها.

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

نقل القيم بين عمليات التشغيل

بعد أي عملية تشغيل تُرجع بيانات جلسة قابلة لإعادة الاستخدام، يوضح عنصر تحكم Carry صغير في شريط أدوات الاستجابة ما هو متاح:

توفر عمليات تشغيل Auto الثلاثية الكاملة session (وهي proxy، وcookies، وuserAgent).
توفر عمليات تشغيل Browser استجابة userAgent، بالإضافة إلى مُعرّف proxy في حال استخدامه.
توفر عمليات تشغيل Proxy مُعرّف proxy المُرجع، وملف تعريف المتصفح عندما يختار التدوير ملفًا لم تطلبه، وexitClass الذي خدم الاستدعاء، مما يتيح إعادة إرسال إجابة premium مباشرة.

انقر فوق Carry واختر مكان تطبيق كل قيمة بنقرة واحدة: يصبح userAgent عبارة عن ترويسة User-Agent في Single أو Proxy، ويتم إدراج مُعرّف proxy في حقل proxy في Single أو Browser. تظهر الحقول التي تتلقى قيمة منقولة النقطة الحمراء "المعدلة" حتى تتمكن من رؤية ما تغير.

يؤدي ملف تعريف المتصفح المنقول إلى ملء حقول التحديد الثلاثة لنظام التشغيل، والمتصفح، والإصدار وتفعيل unblocker، وهي نفس القاعدة التي تنطبق عند اختيار ملف تعريف يدويًا. لا يُتاح ذلك إلا بعد تحميل كتالوج ملفات التعريف، نظرًا لأن النموذج يتكون من ثلاثة حقول تحديد وليس حقل id.

ملف التعريف هو القيمة الوحيدة التي تشير إلى أن الطلب الذي نجح لم يكن الطلب الذي أدخلته: حيث يُبلغ Proxy عن profile فقط عندما ينتقل إلى عائلة متصفح لم تطلبها. وإذا أعدت التشغيل بدونه، فستعيد تشغيل الإصدار الذي فشل. راجع سبب استنفاد محاولات طلب Proxy‏.

التوسيع إلى ملء الشاشة

ينقل رمز التوسيع الموجود في شريط أدوات الاستجابة بطاقة الاستجابة من التخطيط المنقسم إلى طبقة تغطي كامل الشاشة. استخدمه لشاشات فحص تدرجات JSON العميقة، أو سجلات Set-Cookie الطويلة، أو نصوص HTML العريضة حيث يصبح العمود ذو نصف العرض ضيقًا. تتوقف الصفحة نفسها عن التمرير أثناء فتح التراكب. انقر فوق الرمز مرة أخرى (أو اضغط على مفتاح Escape) للتصغير.

أداة إعادة إنتاج cURL‏

في علامة تبويب Raw الخاصة بالطلب، أسفل JSON، يعرض كتل curl المعادل الدقيق لسطر الأوامر للطلب الذي تقوم بإنشائه، مع زر Copy curl. انسخه لإعادة إنتاج الطلب من terminal، أو مشاركته مع زميل، أو لصقه في تقرير خطأ.

بالنسبة للمفاتيح القابلة للإظهار، يقوم زر Reveal key بجوار المقتطف بإدراج المفتاح الحقيقي كنص عادي مباشرة في curl لتتمكن من النسخ والتشغيل كما هو. انقر مرة أخرى للإخفاء. تحتفظ المفاتيح القديمة (التي تم إنشاؤها قبل إطلاق ميزة الإظهار) بعنصر نائب PASTE_PLAINTEXT_FOR_<key-name>؛ أعد إنشاء المفتاح من صفحة API Keys لجعله قابلاً للإظهار.

يتم تسجيل عملية الإظهار في سجل تدقيق الخادم في كل مرة، ويبقى المفتاح النصي في الذاكرة فقط لجلسة الصفحة الحالية.

حفظ الإعدادات المسبقة (Presets)

إذا وجدت نفسك تعيد ضبط نفس الهدف بشكل متكرر، فاحفظه. انقر فوق Save في صف علامات تبويب الطلب لتخزين التكوين الحالي كإعداد مسبق مسمى.

افتح Saved في شريط الأدوات لعرض إعداداتك المسبقة. انقر فوق Load لملء النموذج، أو Delete لإزالة أحدها.

يتم تحميل الطلب المفتوح من علامة تبويب DevTools الخاصة بملحق FourA Chrome مع تحديد مفتاح الملحق عندما يكون هذا المفتاح في حسابك، وتشير الصفحة إلى ذلك. خلاف ذلك، يطلب منك اختيار مفتاح. الطلب المعاد تشغيله الذي لا يحدد unblocker يعمل مع تفعيله، كما تفعل API.

حقل الإعداد المسبق	ما يخزنه
Name	تسمية قصيرة (حتى 100 حرف)
Description	ملاحظات اختيارية (حتى 500 حرف)
Endpoint	المحرك المخصص له الإعداد المسبق (auto / single / proxy / browser)
Config	حمولة الطلب الكاملة، بما في ذلك حقول واجهة المستخدم، و headers، و cookies، و body

يقتصر نطاق الإعدادات المسبقة على حساب المستخدم الخاص بك ولا تتم مشاركتها مع أعضاء الفريق.

إعادة التشغيل من السجل (History)

يتم تسجيل كل طلب تقوم بتشغيله. افتح History في شريط الأدوات لرؤية آخر 20 عملية تشغيل، مرتبة من الأحدث إلى الأقدم.

يعرض كل صف الـ endpoint، و URL الهدف، والحالة، والوقت. انقر فوق Replay في أي صف لإعادة تحميل هذا الطلب في النموذج، ثم Send لتشغيله مرة أخرى.

يقتصر نطاق السجل تلقائياً على حسابك: ترى عمليات التشغيل الخاصة بك فقط.

الفتح من النشاط (Activity)

يحتوي مربع حوار تفاصيل Activity Log على زر Open in Playground. انقر فوقه وسيتم تحميل Playground مع كل من الطلب المؤرشف والاستجابة المؤرشفة. يتم ملء النموذج من الحمولة المخزنة، وتُظهر بطاقة الاستجابة ما أرجعته API في تلك اللحظة مع شارة "archived" على شريط بيانات proxy الوصفية ("archived [, truncated] [, via ]").

من هناك يمكنك تغيير معلمة والضغط على Send لتشغيل طلب جديد مقابل API المباشرة، أو مجرد فحص الحمولة المؤرشفة دون إعادة تشغيلها. يتم الاحتفاظ بالحمولات لمدة 24 ساعة، لذلك لن تحتوي صفوف Activity الأقدم على استجابة قابلة لإعادة التحميل.

نصائح

ابدأ في Playground قبل كتابة الكود لأي هدف جديد. مع تفعيل وضع Auto، ستعرف خلال ثوانٍ ما إذا كان fetch منخفض التكلفة كافيًا أو ما إذا كان الموقع يفرض المعالجة عبر browser.
بالنسبة للأهداف المقيدة جغرافيًا، نفذ استدعاء Proxy واحدًا مع تعيين exitCountries، ثم انقل proxy ID الناتج إلى استدعاء Browser حتى تتم معالجة JavaScript عبر نقطة الخروج نفسها.
احفظ إعدادًا مسبقًا لكل هدف تقوم بعمل scraping له بانتظام. إعادة تشغيل الإعداد المسبق المحفوظ تتطلب نقرة واحدة، بينما إعادة بناء request من الذاكرة تستغرق وقتًا أطول.
استخدم تبويب Cookies لتصحيح أخطاء الـ scraping المعتمد على الجلسات. يعرض لك عرض Set-Cookie المباشر ما أرسله الهدف بدقة.
عندما يرفضك هدف ما، جرب خيارًا آخر من قوائم Browser profile قبل اللجوء إلى محرك أثقل. تغيير المتصفح المعروض مجاني، بينما تشغيل browser render ليس كذلك.
يتم احتساب طلبات Playground على مفتاح API الذي تختاره. استخدم مفتاحًا مخصصًا بحصة منخفضة للاستكشاف العادي إذا كنت ترغب في الحفاظ على نظافة استخدام بيئة الإنتاج.