منفذ Proxy

أرسل حركة المرور الخاصة بك عبر منافذ خروج FourA من أي عميل يقبل proxy URL: متصفح، أو أداة تنزيل، أو scraper تقوم بتشغيله بالفعل. يفتح منفذ الـ proxy نفقا إلى الهدف الذي تحدده وينسخ البايتات في كلا الاتجاهين، لذلك فهو ينقل ما لا يوفره JSON API: عمليات البث، والتنزيلات الكبيرة، وجلسات المتصفح الكاملة.

إصدار تجريبي (Beta). منفذ الـ proxy في مرحلة تجريبية. حركة المرور عبره لا تتم فوترتها بعد، ولا تغطيها المراقبة أو التزام وقت التشغيل، وقد تتغير أسماء الخيارات لاحقا. أخبرنا بما يواجهك من أعطال.

الاتصال

الإعداد	القيمة
Host	`proxy.foura.ai`
Port	`34004`
Protocol	HTTP CONNECT مع مصادقة Basic
المنافذ المستهدفة	`443` و `80`

يتم الحصول على بيانات الاعتماد من لوحة التحكم. أنشئ مستخدم proxy ضمن Proxy في الشريط الجانبي وستحصل على اسم مستخدم وكلمة مرور يتم إنشاؤهما تلقائيا. وهي منفصلة عن API key الخاص بك عن قصد: ينتقل proxy handshake بنص صريح مع كل اتصال، ويمكن تدوير مستخدم الـ proxy دون تعديل تكامل الـ API الخاص بك. راجع Proxy Users.

curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 https://example.com

import requests

proxy = "http://USERNAME:PASSWORD@proxy.foura.ai:34004"
r = requests.get("https://example.com", proxies={"https": proxy, "http": proxy})
print(r.status_code)

يتعامل المنفذ مع CONNECT فقط. يتم إنشاء نفق (tunnel) لهدف https:// بواسطة كل عميل. ويعمل هدف http:// العادي عندما يقوم عميلك بإنشاء نفق له أيضًا (curl: --proxytunnel)؛ أما العميل الذي يعيد توجيه الطلب العادي إلى الـ proxy مباشرةً فسيحصل على 405 Method Not Allowed.

الخيارات تُمرَّر داخل اسم المستخدم

كل ما يلي بيانات الاعتماد هو قائمة بأزواج -key-value، بأي ترتيب:

USERNAME-network-residential-country-de-session-a1

القيم عبارة عن كلمات بأحرف صغيرة (lowercase). تبدأ الشرطة داخل القيمة خيارا جديدا، لذا يُقرأ -city-new-york كخيارين ويتم رفضه. كما يُرفض المفتاح غير المعروف أيضا ولا يتم تجاهله أبدا: كتابة -contry-de غير صحيحة ترجع خطأ 400 يحدد المفاتيح المدعومة، بدلا من توجيه الطلب من الدولة الخاطئة.

الخيار	القيم	الوظيفة
`network`	`shared` (افتراضي، الاسم المستعار `pool`)، `residential`	الشبكة التي يأتي منها العنوان. المشتركة (Shared) هي نقاط خروج FourA الخاصة، ومضمنة في خطتك. السكنية (Residential) هي عناوين منزلية، مأخوذة من حركة مرور premium التي تتضمنها خطتك بالإضافة إلى أي حركة مرور قمت بشرائها.
`fallback`	`residential`، `off`	الشبكة المشتركة فقط. استخدام نقطة خروج سكنية عندما يتعذر على الشبكة المشتركة تنفيذ الطلب. يكون متوقفا ما لم يُطلب، ويعمل فقط عندما تتضمن خطتك حركة مرور premium مع توفر رصيد متبقٍ.
`country`	ISO 3166-1 alpha-2، قابل للتكرار	بلد الخروج الذي يراه الهدف. كرره لتحديد نطاق يشمل عدة بلدان: `-country-de-country-fr`.
`session`	من 1 إلى 32 حرفا أو رقما أو شرطة سفلية	الاتصالات التي تشترك في نفس الاسم تتشارك نفس العنوان (sticky). اتركه فارغا للحصول على عنوان جديد لكل اتصال (rotating).
`state`	كلمة	المنطقة. للشبكة السكنية فقط.
`city`	كلمة	المدينة. للشبكة السكنية فقط.
`asn`	رقم	الشبكة، عبر رقم AS. للشبكة السكنية فقط.
`os`	`windows`، `android`، `ios`، `mac`	نوع الجهاز الذي ينتمي إليه العنوان. للشبكة السكنية فقط.
`lifetime`	من `3` إلى `1440`	عدد الدقائق التي يتم فيها الاحتفاظ بالعنوان السكني الثابت (sticky). للشبكة السكنية فقط.

يقبل كل خيار باستثناء network وfallback وsession القيمة any، والتي تمسح القيمة المحفوظة لمستخدم proxy لهذا الاتصال المحدد فقط.

يتم رفض ثلاثة تركيبات بالرمز 400 بدلا من تنفيذها جزئيا:

استخدام state أو city أو asn أو os أو lifetime على الشبكة المشتركة. يتم اختيار الشبكة المشتركة حسب البلد فقط دون أي تفصيل أدق؛ أضف -network-residential لاستهداف مدينة معينة.
استخدام -fallback-residential مع -network-residential. لا فائدة من التوجيه الاحتياطي (fallback) على الشبكة التي يرجع إليها احتياطيا.
الاستهداف الأكثر تفصيلا مع تفعيل التوجيه الاحتياطي. قد يتم تشغيل التوجيه الاحتياطي أو لا، لذلك يُرفض تحديد مدينة لا يمكن تلبيتها إلا في بعض الأحيان.

Sessions

على الشبكة المشتركة، تحتفظ الجلسة المسماة (named session) بنقطة الخروج نفسها طالما استمر استخدامها، وفق نافذة زمنية متحركة مدتها عشر دقائق. وإذا توقفت نقطة الخروج تلك عن العمل، تنتقل الجلسة إلى نقطة أخرى بدلا من إظهار فشل. يجب دائما تضمين اسم جلسة لأي متصفح يتم تشغيله عبر المنفذ: يؤدي تحميل الصفحة إلى فتح عشرات الاتصالات، وبدون جلسة يخرج كل اتصال منها من عنوان مختلف.

على الشبكة السكنية، تحتفظ الجلسة المسماة بعنوانها لمدة lifetime دقيقة، أو المدة الافتراضية للشبكة في حال عدم تحديد مدة.

الإعدادات الافتراضية المحفوظة

يُطبَّق الاستهداف المحفوظ لمستخدم proxy في لوحة التحكم على كل اتصال يتم عبره، مما يُبقي اسم المستخدم قصيراً. أي قيمة تضعها في اسم المستخدم تكون لها الأولوية لهذا الاتصال فقط، ويُعيد any القيمة المحفوظة السابقة. الإعداد الافتراضي السكني المحفوظ يستهلك الرصيد فقط عندما تسمح خطتك بذلك؛ وإلا فسيتم تقديم الاتصال من الشبكة المشتركة.

ترويسات CONNECT

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

الترويسة	مطابقة لـ
`X-Foura-Network`	`-network-`
`X-Foura-Fallback`	`-fallback-` (`residential` أو `off`)
`X-Foura-Country`	`-country-`، مفصولة بفواصل للقيم المتعددة
`X-Foura-Session`	`-session-`
`X-Foura-State`	`-state-`
`X-Foura-City`	`-city-`
`X-Foura-Asn`	`-asn-`
`X-Foura-Lifetime`	`-lifetime-`

curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 \
  --proxy-header "X-Foura-Country: de" \
  https://example.com

الاستجابات

النفق الذي يفتح يستجيب بـ 200 Connection established. يحمل كل رفض ترويسة X-Foura-Error مع سبب من سطر واحد، لذا اقرأ هذه الترويسة قبل أي شيء آخر.

الحالة	متى تحدث
400 Bad Request	طلب غير صالح، أو خيار لا يمكن لـ FourA تنفيذه. يوضح `X-Foura-Error` الخيار والقيم المدعومة.
403 Forbidden	المنفذ المستهدف غير مدعوم، أو أن الهدف ليس مضيف إنترنت عام.
405 Method Not Allowed	تم إرسال طلب عادي بدلا من CONNECT.
407 Proxy Authentication Required	بيانات الاعتماد مفقودة أو غير صحيحة. لا تحدد الاستجابة مطلقا أي جزء كان خاطئا.
408 Request Timeout	اتصل العميل ولم يرسل أي بيانات لمدة 15 ثانية.
429 Too Many Requests	لدى مستخدم الـ proxy بالفعل 200 نفق مفتوح، أو أن المنفذ وصل إلى سعته القصوى أو معدل الفتح المسموح به.
502 Bad Gateway	لم يتم العثور على نقطة خروج صالحة للعمل لهذا الهدف ضمن ميزانية الاختيار المحددة، أو لم يتمكن محلل FourA من البحث عن المضيف. تظهر هاتان الحالتان كرسالتين مختلفتين في `X-Foura-Error`.
503 Service Unavailable	منفذ الـ proxy معطل.

الحدود

ما يصل إلى 200 نفق مفتوح في وقت واحد لكل مستخدم proxy.
يستغرق العثور على نقطة خروج ما يصل إلى 45 ثانية قبل أن يستسلم المنفذ بخطأ 502. الجلسة التي تمتلك نقطة خروج بالفعل تتصل عادة في أقل من ثانية.
يتم إغلاق النفق الذي لا يمرر أي بايتات في كلا الاتجاهين بعد دقيقتين من الخمول.
مستخدم الـ proxy الذي تقوم بتعطيله أو حذفه في لوحة التحكم يتوقف عن المصادقة في غضون دقيقة واحدة.

القياس والاحتساب

تحتسب البايتات التي تمر عبر المنفذ ضمن استهلاك النطاق الترددي في صفحة الاستخدام والحدود الخاصة بك، كما تحتسب البايتات المارة عبر نقطة خروج سكنية (residential) ضمن استهلاك Premium traffic أيضا. الاتصال الذي يحدد -network-residential بعد استنفاد رصيد Premium يتم تنفيذه على أي حال؛ ولا يتم استخدام نقطة احتياطية أو الإعداد الافتراضي السكني المحفوظ في هذه الحالة، وتتولى الشبكة المشتركة خدمة الاتصال بدلا من ذلك.