ترويسات الاستجابة

تتضمن كل استجابة من FourA API مجموعة صغيرة من الترويسات المخصصة. وهي مفيدة للتتبع، والدعم، وتسوية الفواتير، والتحليل اللاحق.

الترويسات التي تعينها FourA

الترويسة	تُعين في	الوصف
`X-Foura-Request-Id`	كل استجابة من `/api/*`، بما في ذلك الأخطاء و 401s	معرف UUID يحدد هذا الطلب. قم بتسجيله في سجلاتك.
`X-FourA-Credits`	كل استجابة من `/api/*` وصلت إلى الخلفية (backend)	الأرصدة المستهلكة في هذا الاستدعاء. يتم إرجاعها عند النجاح وعند الفشل (تم إنجاز العمل في كلتا الحالتين).
`Content-Type`	كل استجابة	تكون دائما `application/json` للغلاف. يعود نوع محتوى الهدف داخل حقل `headers` الخاص بالغلاف.

X-Foura-Request-Id

يتم تمييز كل استدعاء إلى POST /api/auto/، أو POST /api/single/، أو POST /api/proxy/، أو POST /api/browser/ بمعرف UUID. يتم تعيين الترويسة حتى عند فشل المصادقة، بحيث يمكنك ربط الاستدعاءات التي تم تكوينها بشكل خاطئ أيضا.

curl -i -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"}'

HTTP/1.1 200 OK
X-Foura-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...

متى تستخدمها

تذاكر الدعم: قم بتضمين معرف الطلب وسنتمكن من العثور على الاستدعاء الدقيق في سجلاتنا.
سجلاتك الخاصة: قم بتخزينه بجوار سطر سجل تطبيقك. إذا نصت شكوى عميل على "كانت البيانات خاطئة في 14:32"، فيمكنك إعادة تشغيل الطلب الدقيق.
تتبع لوحة المعلومات: يظهر المعرف نفسه في Activity feed للمفاتيح التي تديرها، بحيث يمكنك فتح الصف المطابق وفحص الطلب والاستجابة الملتقطة.

مثال: التسجيل في سجلاتك

import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-Foura-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()

async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-Foura-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}

X-FourA-Credits

يبلغ X-FourA-Credits عن تكلفة الرصيد للاستدعاء الذي أجريته للتو. إنه عداد، وليس فاتورة: تعكس الترويسة ما استهلكه العمل بغض النظر عن النتيجة. تحسب طبقة الفوترة في لوحة المعلومات النتائج القابلة للفوترة فقط مقابل خطتك (راجع Request Outcomes لمعرفة النتائج القابلة للفوترة).

مرجع التكلفة

المحرك	الأساس	مع `unblocker`
Single	1	2
Proxy	5	10
Browser	15	30 (عندما يتم حل دفاع)

لا يضيف /api/auto/ صفا منفصلا قابلا للفوترة. تكلفة رصيده هي مجموع الاستدعاءات الفرعية التي أجراها داخليا (يمكن أن تنتهي إعادة تشغيل واحدة على هدف دافئ عند 2، ويمكن أن يستهلك الحل البارد على موقع صعب أكثر من ذلك بكثير). تساوي قيمة X-FourA-Credits في الاستجابة التلقائية meta.credits في النص وتتتبع تكلفة السلم الكاملة.

لماذا يوجد حقل ترويسة ونص معا؟

الترويسة مريحة: يمكنك قراءتها قبل تحليل النص، أو تسجيلها بجوار سطر طلبك، أو جمعها عبر العديد من الاستدعاءات دون تحليل JSON. يحتفظ meta.credits (Auto) الخاص بالنص أو البيانات الوصفية لكل محرك (لوحات معلومات Single، و Proxy، و Browser) بالرقم نفسه، ولكنه قابل للقراءة داخل غلاف الاستجابة.

سلوك ذاكرة التخزين المؤقت (Cache)

لا تعين API Cache-Control أو ETag في الاستجابات. يصل كل استدعاء إلى الخلفية (backend). إذا كنت بحاجة إلى التخزين المؤقت، فأضفه من جانبك.

ترويسات استجابة الهدف

الترويسات التي أرجعها الموقع الهدف ليست موجودة في استجابة FourA API. تعود داخل غلاف JSON كحقل headers. بالنسبة لنقاط نهاية Single و Proxy، هذه مصفوفة من كائنات الترويسة لكل قفزة (إدخال واحد لكل خطوة إعادة توجيه). بالنسبة لنقطة نهاية Browser، فهو كائن مسطح لترويسات الاستجابة النهائية.

{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}

إذا كنت بحاجة إلى ترويسة هدف معينة، فاقرأها من حقل headers الخاص بالغلاف، وليس من استجابة HTTP لاستدعاء API نفسه.