دليل تكامل API عرض صفحات الويب WebExtrator

POST https://api.acedata.cloud/webextrator/render واجهة API عرض صفحات الويب WebExtrator هي خدمة لعرض صفحات الويب تعتمد على Chromium عديم الرأس. أعطِ عنوان URL، وسيتم إرجاع HTML المعروض بالكامل (بما في ذلك المحتوى المُدرج عبر JS)، والنص الخالص، وعنوان الصفحة، وعنوان URL النهائي. Render هي الواجهة الأساسية الأدنى مستوى في WebExtrator. إذا كنت تحتاج إلى نتائج استخراج مهيكلة (النص الرئيسي للمقالة، أسعار المنتجات، مكونات الوصفات …)، فيُرجى استخدام /webextrator/extract —— فهي تُشغّل مسار استخراج كاملًا ومُصنّف الأنواع على أساس العرض نفسه.

عملية التقديم

لاستخدام صفحة خدمة WebExtrator، انتقل أولًا إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا.

إذا لم تقم بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وستعود تلقائيًا إلى الصفحة الحالية بعد الإكمال. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة إلى التقديم بشكل منفصل لكل خدمة. سيُمنح رصيد مجاني عند أول تقديم، مما يتيح تجربة مجانية؛ وعند عدم كفاية الرصيد، يمكنك إعادة شحن الرصيد العام في وحدة التحكم.

📘 الوثائق الكاملة: صفحة خدمة WebExtrator →

المصادقة

تستخدم جميع واجهات WebExtrator مصادقة Bearer Token القياسية:

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

معلمات الطلب

الحقل	النوع	مطلوب	الافتراضي	الوصف
`url`	string	✅	—	عنوان URL للصفحة المراد عرضها، ويجب أن يكون `http(s)://`.
`user_agent`	string	❌	تدوير مجموعة UA المدمجة	User-Agent مخصص.
`timeout`	integer	❌	`30`	مهلة التنقل المفردة (ثوانٍ صحيحة موجبة).
`wait_until`	enum	❌	`load`	حدث اكتمال التحميل: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	integer	❌	`0`	ثوانٍ انتظار إضافية بعد تشغيل `wait_until` (عدد صحيح غير سالب) (للعرض الثانوي لـ SPA).
`wait_for_selector`	string	❌	—	انتظر ظهور محدد CSS هذا، وهو أكثر استقرارًا من `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	أنواع الموارد المحظورة، الخيارات: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	رؤوس طلبات HTTP إضافية (مثل `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	ملفات Cookie المُدرجة قبل التنقل، انظر البنية أدناه.
`callback_url`	string	❌	—	عنوان رد الاتصال في الوضع غير المتزامن، تقوم المنصة عند اكتمال المهمة بعمل `POST` للنتيجة الكاملة إلى هذا العنوان.
`bypass_cache`	boolean	❌	`false`	تجاوز قراءة ذاكرة Redis المؤقتة (لكن سيستمر كتابة نتيجة هذه المرة إلى الذاكرة المؤقتة).
`cache_ttl_seconds`	integer	❌	`3600`	تخصيص TTL للذاكرة المؤقتة المكتوبة هذه المرة، مرّر `0` لعدم تخزين هذه الاستجابة مؤقتًا.
`async`	boolean	❌	`false`	اضبطه على `true` لإرجاع `task_id` فورًا، واسترد النتيجة عبر `callback_url` أو Tasks API.

يستخدم عقد المنصة بشكل موحّد snake_case. تدعم خدمة العرض الداخلية camelCase، لكن يجب في الاستدعاءات الخارجية دائمًا استخدام snake_case.

{
  "name":      "string",
  "value":     "string",
  "domain":    "string",
  "path":      "/",
  "expires":   1735689600,
  "httpOnly":  false,
  "secure":    true,
  "sameSite":  "Lax"
}

الاستجابة المتزامنة

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717801.234,
  "elapsed": 1.111,
  "data": {
    "kind": "render",
    "url": "https://example.com",
    "finalUrl": "https://example.com/",
    "title": "Example Domain",
    "status": 200,
    "html": "<!DOCTYPE html><html>...</html>",
    "text": "Example Domain\nThis domain is for use in illustrative examples...",
    "userAgent": "Mozilla/5.0 ...",
    "elapsedMs": 1108
  }
}

الحقل	النوع	الوصف
`data.kind`	string	ثابت `"render"`.
`data.url`	string	عنوان URL الذي أرسلته.
`data.finalUrl`	string	عنوان URL النهائي بعد اتباع عمليات إعادة التوجيه.
`data.title`	string	`document.title` بعد العرض.
`data.status`	number \| null	رمز حالة HTTP للتنقل الرئيسي.
`data.html`	string	HTML الكامل بعد العرض.
`data.text`	string	لقطة `document.body.innerText` (إذا كنت تحتاج إلى نص رئيسي أنظف، فاستخدم Extract).
`data.userAgent`	string	UA المستخدم فعليًا.
`data.elapsedMs`	number	وقت عرض المتصفح فقط.
`data.cached`	boolean?	تكون `true` عند إصابة الذاكرة المؤقتة.
`data.cacheStoredAt`	number?	طابع زمني بوحدة Unix بالمللي ثانية عند أول كتابة لعنصر الذاكرة المؤقتة.

الاستجابة غير المتزامنة

عند async=true (أو توفير callback_url) يتم الإرجاع فورًا (HTTP 200):

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

سيتم دفع النتيجة عبر POST إلى callback_url (إذا تم تكوينه)، أو عبر /webextrator/tasks للاستعلام النشط.

بنية رد الاتصال

تقوم المنصة بعمل POST لغلاف مطابق تمامًا للوضع المتزامن إلى callback_url، بـ Content-Type: application/json. وتُعد أي استجابة 2xx تأكيدًا؛ أما 5xx فستتم إعادة محاولتها بتراجع أُسّي لمدة تقارب 5 دقائق.

استجابة الخطأ

HTTP	`error.code`	المعنى
400	`bad_request`	لم يجتز جسم الطلب تحقق Zod (يفتقد `url`، النوع غير صحيح …).
401	`unauthorized`	`Authorization: Bearer …` مفقود أو غير صالح.
402	(x402)	رصيد المنصة غير كافٍ، ويُرجع envelope لمتطلبات دفع x402.
408	`timeout`	تجاوز التنقل `timeout`.
429	`queue_busy`	قائمة الانتظار المتزامنة مزدحمة، يرجى إعادة المحاولة أو استخدام `async=true`.
500	`internal_error`	استثناء غير معالج من جانب الخادم (مثل تعطل المتصفح)، ويعيد Worker المحاولة تلقائيًا مرة واحدة.

بنية الخطأ:

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": 1777717800.123,
  "finished_at": 1777717800.135,
  "elapsed": 0.012,
  "error": { "code": "bad_request", "message": "url: Invalid url" }
}

أمثلة

cURL

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "wait_until": "networkidle",
    "block_resources": ["image", "media", "font"]
  }'

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/render",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "wait_until": "networkidle",
        "block_resources": ["image", "media", "font"],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["title"], data["status"], len(data["html"]))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/render', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    wait_until: 'networkidle',
    block_resources: ['image', 'media', 'font'],
  }),
});
const { data } = await res.json();
console.log(data.title, data.status, data.html.length);

غير متزامن + رد اتصال

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async": true,
    "callback_url": "https://your-app.example.com/hooks/webextrator"
  }'

يُرجع فورًا { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 }؛ عند اكتمال المهمة، سترسل المنصة النتيجة الكاملة عبر POST إلى callback_url الخاص بك.

فرض تجاوز ذاكرة التخزين المؤقت

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "bypass_cache": true
  }'

تلميحات ومطبات

اختيار wait_until الصحيح مهم جدًا. networkidle هو الأكثر استقرارًا لكنه الأبطأ؛ أما domcontentloaded فهو سريع لكنه قد يفوّت المحتوى المُدرج بشكل غير متزامن؛ وload مناسب للصفحات الثابتة التقليدية.
يتجاهل مفتاح التخزين المؤقت async. الطلبات المتزامنة وغير المتزامنة لنفس عنوان URL تصيب إدخال التخزين المؤقت نفسه، ولن يؤدي التبديل العشوائي إلى إبطاله.
يتجاهل مفتاح التخزين المؤقت bypass_cache وcache_ttl_seconds. هذان مفتاحا تشغيل، ولا يؤثران في محتوى الاستجابة.
يقوم cookies وheaders بتقسيم التخزين المؤقت إلى مجموعات. تخصيص هذين سيؤدي إلى فشل التطابق الأول للتركيبة نفسها.
غالبًا ما تتجاوز تطبيقات SPA الثقيلة 30 ثانية الافتراضية. يُنصح باستخدام timeout: 60 وwait_until: "domcontentloaded" وdelay: 4، ثم استخدام wait_for_selector وغيرها لانتظار العناصر التي تهمك بالفعل.
block_resources هو أسرع طريق لتقليل التأخير. يتم حجب الصور / الخطوط / الوسائط افتراضيًا؛ إذا كان الاستخراج لا يعتمد على تخطيط CSS، فإن إضافة stylesheet ستجعله أسرع أيضًا.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

Coding

المزيد من الأدلة

دليل تكامل API عرض صفحات الويب WebExtrator

عملية التقديم

المصادقة

معلمات الطلب

الاستجابة المتزامنة

الاستجابة غير المتزامنة

بنية رد الاتصال

استجابة الخطأ

أمثلة

cURL

Python (requests)

Node.js (fetch)

غير متزامن + رد اتصال

فرض تجاوز ذاكرة التخزين المؤقت

تلميحات ومطبات

​عملية التقديم

​المصادقة

​معلمات الطلب

​بنية Cookie

​الاستجابة المتزامنة

​الاستجابة غير المتزامنة

​بنية رد الاتصال

​استجابة الخطأ

​أمثلة

​cURL

​Python (requests)

​Node.js (fetch)

​غير متزامن + رد اتصال

​فرض تجاوز ذاكرة التخزين المؤقت

​تلميحات ومطبات

عملية التقديم

المصادقة

معلمات الطلب

بنية Cookie

الاستجابة المتزامنة

الاستجابة غير المتزامنة

بنية رد الاتصال

استجابة الخطأ

أمثلة

cURL

Python (requests)

Node.js (fetch)

غير متزامن + رد اتصال

فرض تجاوز ذاكرة التخزين المؤقت

تلميحات ومطبات