إنشاء مهمة
يشرح هذا الدليل كيفية إنشاء مفتاح API وإرسال أول request لك باستخدام Dashboard في FourA.
الخطوة 1: افتح Dashboard
انتقل إلى Dashboard وسجل الدخول باستخدام حساب FourA الخاص بك.
الخطوة 2: أنشئ مفتاح API
انتقل إلى صفحة API Keys وانقر على Create API key. بمجرد حصولك على مفتاح، سيظهر الزر أعلى القائمة بالنص Create Key.
أدخل اسما وصفيا للمفتاح (مثل "production-scraper" أو "dev-testing"). يعرض مربع الحوار API Key Created المفتاح كنص صريح مع زر نسخ، وأسفل Test your first request يظهر أمر curl جاهز للتشغيل مع Copy command. على الهاتف أو الجهاز اللوحي، ينقلك Try it in the Playground إلى هناك بدلا من ذلك.
إذا فاتتك هذه الخطوة، فانقر على أيقونة العين في صف المفتاح لاحقا لإظهاره مرة أخرى. المفاتيح القديمة التي تم إنشاؤها قبل إطلاق ميزة الإظهار لا يمكن استعادتها؛ أعد إنشاءها مرة واحدة للتبديل إلى النظام الجديد. المسار الكامل: Managing API Keys.
يبدو المفتاح الخاص بك بهذا الشكل: pk_live_a1b2c3d4e5f6...
الخطوة 3: اختر Endpoint
توفر FourA أربعة endpoints لسيناريوهات مختلفة:
Auto (POST /api/auto/)
الخيار الافتراضي الذكي. مرر URL، ويفضل أن يتضمن قاعدة validate، وسيتدرج FourA عبر خطوات تبدأ من proxy متناوب وصولا إلى متصفح كامل عبر proxy، ليتوقف عند أول response تنجح. عيّن forceProxy: false للسماح له بتجربة request مباشر أولا. هو الخيار الأفضل عند استهداف موقع جديد لا تعرف متطلباته بعد.
Single (POST /api/single/)
يرسل HTTP request سريعا. هو الأنسب لصفحات HTML الثابتة و endpoints الخاصة بـ API. زمن الاستجابة: أقل من ثانيتين عادة.
Browser (POST /api/browser/)
يشغل مثيل متصفح Chrome لتصيير JavaScript. هو الأنسب لتطبيقات SPA، والمحتوى الذي يتم تحميله تدريجيا، والصفحات التي تتطلب تنفيذ JS. زمن الاستجابة: من 2 إلى 10 ثوان.
Proxy (POST /api/proxy/)
يوجه الـ request عبر proxies متناوبة مع إعادة محاولة تلقائية. هو الأنسب للمواقع التي تتحقق من هوية المرسل، أو التي تختلف استجابتها بحسب البلد.
الخطوة 4: أرسل أول Request لك
افتح وحدة التحكم الطرفية وشغل:
curl -X POST https://eu.api.foura.ai/api/single/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method": "GET", "url": "https://example.com"}'
الخطوة 5: قراءة الـ response
{
"status": 200,
"headers": [
{
"result": { "version": "HTTP/2", "code": 200, "reason": "" },
"content-type": "text/html; charset=UTF-8",
"content-length": "1256"
}
],
"data": "<html>...</html>",
"total_time": 0.45
}
الحقل headers عبارة عن مصفوفة من الكائنات، كائن واحد لكل قفزة إعادة توجيه. يحتوي كل إدخال على result مع سطر الحالة بالإضافة إلى كل response header أرجعته الوجهة المستهدفة.
الحقول الأساسية:
- status: رمز حالة HTTP من الموقع المستهدف
- data: جسم الاستجابة (HTML أو JSON أو نص خام)
- total_time: مدة الـ request بالثواني
الخطوة 6: تجربة Browser Request
إذا كانت الصفحة المستهدفة تستخدم JavaScript لعرض المحتوى، فاستخدم endpoint المتصفح بدلا من ذلك:
curl -X POST https://eu.api.foura.ai/api/browser/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/products", "timeout_ms": 15000}'
يستخدم response المتصفح body بدلاً من data:
{
"status": 200,
"headers": {"content-type": "text/html"},
"body": "<html>...</html>"
}
المشكلات الشائعة
| المشكلة | الحل |
|---|---|
| غير متأكد من المحرك المناسب للاستخدام | ابدأ باستخدام endpoint auto. فهو يحدد المسار المناسب ويتذكر ما نجح سابقًا. |
| محتوى فارغ | انتقل من single endpoint إلى browser endpoint: من المحتمل أن الصفحة تتطلب تصيير JS |
| ظهور صفحة تحقق في response | انتقل إلى proxy endpoint للاستفادة من التدوير التلقائي لعناوين IP |
| انتهاء مهلة الطلب (Timeout) | قم بزيادة timeout_ms أو تحقق من صحة URL |
| فقدت مفتاحك | انقر فوق رمز العين في صف المفتاح داخل API Keys لإظهاره، أو أعد إنشاءه إذا كان المفتاح قديمًا (legacy) |
الخطوات التالية
- نظرة عامة على لوحة التحكم: جولة شاملة في لوحة التحكم
- Playground: اختبار requests في لوحة التحكم قبل كتابة الكود
- Smart Fetch (Auto): دليل تفصيلي حول auto endpoint
- اختيار الـ Endpoint المناسب: مقارنة تفصيلية
- المشكلات الشائعة: حل المشكلات بسرعة