تكامل البروكسي مع عملاء REST API: إعداد Postman وInsomnia وcURL وHTTPie

عند تطوير واختبار API، غالبًا ما تكون هناك حاجة لإرسال الطلبات عبر خوادم البروكسي. قد يكون ذلك مطلوبًا لتجاوز القيود الجغرافية، واختبار سلوك API من مناطق مختلفة، وضمان الخصوصية، أو العمل مع خدمات تحظر عناوين IP لمراكز البيانات. في هذا الدليل، سنستعرض كيفية إعداد البروكسي بشكل صحيح في عملاء REST API الشائعين وتجنب الأخطاء الشائعة.

سنستعرض أربعة من أكثر الأدوات شعبية للعمل مع API: Postman (واجهة رسومية لمعظم المطورين)، Insomnia (بديل حديث مع واجهة مستخدم مريحة)، cURL (أداة سطر أوامر تقليدية) و HTTPie (عميل سطر أوامر حديث مع بناء جملة سهل القراءة). سنقدم أمثلة على الشيفرة لكل أداة وسنستعرض ميزات التكوين.

ما هي أنواع البروكسي المناسبة للعمل مع API

قبل إعداد البروكسي في عملاء API، من المهم فهم نوع البروكسي المناسب لمهمتك. تدعم عملاء REST API بروتوكولين رئيسيين: HTTP/HTTPS و SOCKS5. يعتمد الاختيار على متطلبات API المحدد ومستوى الأمان الذي تحتاجه.

تعمل بروكسي HTTP/HTTPS على مستوى بروتوكول HTTP وتناسب معظم طلبات REST API. إنها تفهم بنية حركة مرور HTTP، ويمكنها تخزين الردود مؤقتًا وتعديل الرؤوس. تقوم بروكسي HTTPS بتشفير الاتصال بين العميل وخادم البروكسي، وهو أمر مهم عند نقل البيانات الحساسة، مثل مفاتيح API أو رموز المصادقة.

تعمل بروكسي SOCKS5 على مستوى أدنى وتنقل أي نوع من حركة المرور دون تعديل. إنها أبطأ من بروكسي HTTP، لكنها توفر خصوصية أفضل وتناسب الحالات التي يستخدم فيها API بروتوكولات غير قياسية أو تتطلب شفافية كاملة في الاتصال. تدعم بروكسي SOCKS5 أيضًا حركة مرور UDP، على الرغم من أن ذلك نادرًا ما يكون مطلوبًا لـ REST API.

إعداد البروكسي في Postman: الإعدادات العالمية والمحلية

Postman هو الأداة الرسومية الأكثر شعبية للعمل مع REST API، ويستخدمها ملايين المطورين. يدعم طريقتين لإعداد البروكسي: الإعدادات العالمية (تطبق على جميع الطلبات) وإعدادات على مستوى البيئة (environment). دعونا نستعرض كلا الخيارين بالتفصيل.

الإعداد العالمي للبروكسي في Postman

توجد الإعدادات العالمية للبروكسي في قائمة الإعدادات (رمز الترس في الزاوية اليمنى العليا). هذه الطريقة مريحة عندما تريد أن تمر جميع الطلبات من Postman دائمًا عبر نفس خادم البروكسي. إليك التعليمات خطوة بخطوة:

1. افتح Postman واضغط على رمز الترس (Settings) في الزاوية اليمنى العليا
2. انتقل إلى علامة التبويب "Proxy"
3. قم بتمكين خيار "Add a custom proxy configuration"
4. اختر نوع البروكسي: HTTP، HTTPS أو SOCKS5
5. أدخل عنوان خادم البروكسي (على سبيل المثال: proxy.example.com)
6. حدد المنفذ (عادةً 8080 لـ HTTP، 1080 لـ SOCKS5)
7. إذا كان البروكسي يتطلب مصادقة، قم بتمكين "Proxy Auth" وأدخل اسم المستخدم/كلمة المرور
8. اضغط على "Save" وأغلق نافذة الإعدادات

بعد ذلك، ستتم معالجة جميع الطلبات من Postman تلقائيًا عبر البروكسي المحدد. ميزة مهمة: يقوم Postman أيضًا بإرسال بيانات الاستطلاع والتحقق من التحديثات عبر البروكسي، مما قد يؤدي إلى زيادة حركة المرور. إذا كنت تستخدم بروكسي مع حركة مرور محدودة، يجب أن تأخذ ذلك في الاعتبار.

إعداد البروكسي عبر متغيرات البيئة

طريقة أكثر مرونة هي استخدام متغيرات البيئة (Environments). يتيح لك ذلك التبديل بسرعة بين بروكسيات مختلفة لمشاريع أو APIs مختلفة. أنشئ بيئة جديدة وأضف المتغيرات التالية:

PROXY_HOST = proxy.example.com
PROXY_PORT = 8080
PROXY_USER = your_username
PROXY_PASS = your_password

بعد ذلك، في الإعدادات العالمية للبروكسي، استخدم هذه المتغيرات بدلاً من القيم المحددة: {{PROXY_HOST}} و {{PROXY_PORT}}. الآن يمكنك إنشاء عدة بيئات (مثل "بروكسي الإنتاج"، "بروكسي الاختبار"، "بروكسي الولايات المتحدة") والتبديل بينها بنقرة واحدة.

استخدام البروكسي النظامي

يمكن لـ Postman أيضًا استخدام إعدادات البروكسي النظامية لنظام التشغيل الخاص بك. للقيام بذلك، في إعدادات البروكسي، اختر خيار "Use System Proxy". هذه الطريقة مريحة إذا كنت قد قمت بالفعل بإعداد البروكسي على مستوى نظام التشغيل (مثل إعدادات Windows أو macOS) وترغب في أن يستخدم Postman نفس الإعدادات التي يستخدمها المتصفح.

تكوين البروكسي في Insomnia

Insomnia هو بديل حديث لـ Postman مع واجهة نظيفة ومصدر مفتوح. إعداد البروكسي في Insomnia يختلف قليلاً عن Postman ويتطلب تعديل ملف التكوين أو استخدام متغيرات البيئة. دعونا نستعرض كلا الطريقتين.

الإعداد عبر متغيرات البيئة

أسهل طريقة لإعداد البروكسي في Insomnia هي استخدام متغيرات البيئة القياسية HTTP_PROXY و HTTPS_PROXY. يقرأ Insomnia هذه المتغيرات تلقائيًا من النظام. قم بتعيينها قبل تشغيل Insomnia:

Linux/macOS:

export HTTP_PROXY="http://username:password@proxy.example.com:8080"
export HTTPS_PROXY="http://username:password@proxy.example.com:8080"
insomnia

Windows (PowerShell):

$env:HTTP_PROXY = "http://username:password@proxy.example.com:8080"
$env:HTTPS_PROXY = "http://username:password@proxy.example.com:8080"
insomnia

لاحظ تنسيق URL: حتى لبروكسي HTTPS، يتم استخدام المخطط http://، وليس https://. هذا هو الاتفاق القياسي لمتغيرات البيئة للبروكسي. إذا لم يتطلب البروكسي مصادقة، سيكون URL أقصر: http://proxy.example.com:8080.

إعداد بروكسي SOCKS5

لبروكسي SOCKS5، استخدم متغير البيئة ALL_PROXY:

export ALL_PROXY="socks5://username:password@proxy.example.com:1080"

يدعم Insomnia بروكسي SOCKS5، لكن ليست جميع الإصدارات تعالج مصادقة SOCKS5 بشكل صحيح. إذا واجهت مشاكل مع SOCKS5 المصدق، حاول استخدام بروكسي HTTP أو قم بتحديث Insomnia إلى أحدث إصدار.

الإعداد عبر ملف التكوين

لإعداد البروكسي بشكل دائم، يمكنك تعديل ملف تكوين Insomnia. يعتمد موقع الملف على نظام التشغيل:

• Windows: %APPDATA%\Insomnia\config.json
• macOS: ~/Library/Application Support/Insomnia/config.json
• Linux: ~/.config/Insomnia/config.json

افتح الملف في محرر نصوص وأضف قسم البروكسي:

{
  "proxy": {
    "http": "http://username:password@proxy.example.com:8080",
    "https": "http://username:password@proxy.example.com:8080"
  }
}

بعد التعديل، أعد تشغيل Insomnia. ستطبق إعدادات البروكسي على جميع الطلبات تلقائيًا.

استخدام البروكسي في cURL: أمثلة على الأوامر

cURL هو أداة سطر أوامر تقليدية للعمل مع HTTP، وهو مثبت تقريبًا على جميع أنظمة Unix-like و Windows 10+. يدعم البروكسي عبر المعامل -x أو --proxy. دعونا نستعرض سيناريوهات استخدام مختلفة.

الاستخدام الأساسي لبروكسي HTTP

أبسط مثال لاستخدام بروكسي HTTP بدون مصادقة:

curl -x http://proxy.example.com:8080 https://api.example.com/users

يشير المعامل -x إلى عنوان و منفذ خادم البروكسي. سيحدد cURL تلقائيًا أنه بروكسي HTTP ويقوم بإعداد الاتصال. إذا كنت ترغب في تحديد البروتوكول بشكل صريح، استخدم URL كامل:

curl --proxy http://proxy.example.com:8080 https://api.example.com/users

بروكسي مع مصادقة

إذا كان البروكسي يتطلب مصادقة باستخدام اسم المستخدم وكلمة المرور، أضفها إلى URL البروكسي أو استخدم المعامل -U:

# الطريقة 1: اسم المستخدم وكلمة المرور في URL
curl -x http://username:password@proxy.example.com:8080 https://api.example.com/users

# الطريقة 2: المعامل -U (أكثر أمانًا، لا يتم حفظه في تاريخ الأوامر)
curl -x http://proxy.example.com:8080 -U username:password https://api.example.com/users

الطريقة الثانية مفضلة، حيث أن اسم المستخدم وكلمة المرور لن تظهر في تاريخ أوامر shell. لمزيد من الأمان، يمكنك تحديد اسم المستخدم فقط، وسيطلب منك cURL كلمة المرور بشكل تفاعلي:

curl -x http://proxy.example.com:8080 -U username https://api.example.com/users
# سيطلب cURL كلمة المرور: Enter proxy password for user 'username':

استخدام بروكسي SOCKS5

لبروكسي SOCKS5، حدد البروتوكول في URL بشكل صريح:

# SOCKS5 بدون مصادقة
curl -x socks5://proxy.example.com:1080 https://api.example.com/users

# SOCKS5 مع مصادقة
curl -x socks5://username:password@proxy.example.com:1080 https://api.example.com/users

# SOCKS5h (حل DNS عبر البروكسي)
curl -x socks5h://proxy.example.com:1080 https://api.example.com/users

الفرق بين socks5:// و socks5h://: في الحالة الأولى، يحدث حل DNS محليًا (على جهازك)، وفي الثانية، عبر خادم البروكسي. استخدم socks5h:// إذا كنت ترغب في إخفاء طلبات DNS بالكامل عن مزود الخدمة الخاص بك.

طلبات POST عبر البروكسي

يعمل البروكسي بنفس الطريقة لجميع طرق HTTP. مثال على طلب POST مع بيانات JSON عبر البروكسي:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}' \
  https://api.example.com/users

لإرسال الملفات، استخدم المعامل -F:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -F "file=@document.pdf" \
  -F "description=Important document" \
  https://api.example.com/upload

استخدام متغيرات البيئة

بدلاً من تحديد البروكسي في كل أمر، يمكنك استخدام متغيرات البيئة. يقرأ cURL تلقائيًا http_proxy، https_proxy و all_proxy:

# تعيين متغيرات البيئة
export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# الآن جميع أوامر cURL تستخدم البروكسي تلقائيًا
curl https://api.example.com/users

# تعطيل البروكسي لأمر معين
curl --noproxy "*" https://api.example.com/users

يسمح المعامل --noproxy باستثناء مجالات معينة من استخدام البروكسي. على سبيل المثال، لتجنب استخدام البروكسي لـ localhost والمجالات الداخلية:

export no_proxy="localhost,127.0.0.1,.internal.company.com"

إعداد البروكسي في HTTPie

HTTPie هو بديل حديث لـ cURL مع بناء جملة سهل القراءة وإخراج ملون. إنه مريح بشكل خاص للعمل التفاعلي مع API في الطرفية. يدعم HTTPie البروكسي عبر المعامل --proxy أو متغيرات البيئة.

الاستخدام الأساسي للبروكسي

بناء جملة HTTPie للبروكسي يختلف قليلاً عن cURL. يجب تحديد البروتوكول و URL البروكسي بشكل منفصل:

# بروكسي HTTP
http --proxy=http:http://proxy.example.com:8080 \
     --proxy=https:http://proxy.example.com:8080 \
     GET https://api.example.com/users

# الشكل المختصر (إذا كان البروكسي نفسه لـ HTTP و HTTPS)
http --proxy=all:http://proxy.example.com:8080 GET https://api.example.com/users

التنسيق: --proxy=protocol:proxy_url. عادةً ما يتم استخدام بروكسي HTTP للطلبات HTTPS (ليس HTTPS)، وهذا هو السلوك القياسي.

بروكسي مع مصادقة

لإجراء المصادقة، أضف اسم المستخدم وكلمة المرور إلى URL البروكسي:

http --proxy=all:http://username:password@proxy.example.com:8080 \
     GET https://api.example.com/users

يدعم HTTPie أيضًا المعامل --proxy-auth لتحديد بيانات الاعتماد بشكل أكثر وضوحًا، لكن في الإصدارات الأخيرة، يعتبر هذا المعامل قديمًا، ويُوصى بإدراج المصادقة في URL.

بروكسي SOCKS5 في HTTPie

يدعم HTTPie بروكسي SOCKS5 بدءًا من الإصدار 2.0.0. تأكد من أن لديك الإصدار الأحدث:

# تحقق من إصدار HTTPie
http --version

# تحديث HTTPie عبر pip
pip install --upgrade httpie

# استخدام بروكسي SOCKS5
http --proxy=all:socks5://proxy.example.com:1080 GET https://api.example.com/users

لبروكسي SOCKS5 مع مصادقة، ستحتاج إلى تثبيت مكتبة إضافية pysocks:

pip install pysocks
http --proxy=all:socks5://username:password@proxy.example.com:1080 \
     GET https://api.example.com/users

طلبات POST وإرسال البيانات

يحتوي HTTPie على بناء جملة مريح لطلبات POST. مثال على إرسال JSON عبر البروكسي:

# POST مع JSON (يحدد HTTPie نوع المحتوى تلقائيًا)
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/users \
     name="John Doe" \
     email="john@example.com" \
     age:=30

# إرسال ملف
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/upload \
     file@document.pdf \
     description="Important document"

لاحظ بناء الجملة: key=value للسلاسل، key:=value للأرقام والقيم المنطقية، key@file للملفات.

استخدام متغيرات البيئة

مثل cURL، يقرأ HTTPie متغيرات البيئة القياسية http_proxy و https_proxy:

export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# الآن جميع الأوامر تستخدم البروكسي تلقائيًا
http GET https://api.example.com/users

لتعطيل البروكسي مؤقتًا، استخدم المعامل --proxy= (قيمة فارغة):

http --proxy= GET https://api.example.com/users

مصادقة البروكسي: اسم المستخدم وكلمة المرور

تتطلب معظم خدمات البروكسي التجارية مصادقة لحماية الاستخدام غير المصرح به. هناك طريقتان رئيسيتان للمصادقة: المصادقة الأساسية (اسم المستخدم/كلمة المرور) وقائمة العناوين IP المصرح بها (ربط بالعناوين IP). دعونا نستعرض ميزات كل طريقة وكيفية إعدادها بشكل صحيح في عملاء API.

المصادقة الأساسية (اسم المستخدم وكلمة المرور)

المصادقة الأساسية هي الطريقة الأكثر شيوعًا. يتطلب خادم البروكسي اسم المستخدم وكلمة المرور عند كل اتصال. يتم تمرير بيانات الاعتماد في رأس Proxy-Authorization بتنسيق Base64. تقوم جميع عملاء API الحديثة بتكوين هذا الرأس تلقائيًا إذا قمت بإدخال اسم المستخدم وكلمة المرور في URL البروكسي.

تنسيق URL مع المصادقة:

protocol://username:password@proxy_host:proxy_port

أمثلة لبروتوكولات مختلفة:

# بروكسي HTTP
http://user123:pass456@proxy.example.com:8080

# بروكسي HTTPS (نفس التنسيق)
http://user123:pass456@proxy.example.com:8080

# بروكسي SOCKS5
socks5://user123:pass456@proxy.example.com:1080

قائمة العناوين IP المصرح بها (الربط بالعناوين IP)

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

عند استخدام قائمة العناوين IP المصرح بها، يتم تبسيط تنسيق URL للبروكسي:

# بدون اسم المستخدم وكلمة المرور
http://proxy.example.com:8080

# مثال في cURL
curl -x http://proxy.example.com:8080 https://api.example.com/users

عيب هذه الطريقة هو أنه إذا كان عنوان IP الخاص بك ديناميكيًا (يتغير عند إعادة الاتصال بالإنترنت)، سيتعين عليك تحديث القائمة المصرح بها في كل مرة. بالنسبة للخوادم ذات عنوان IP ثابت، هذه هي الخيار المثالي.

الرموز الخاصة في كلمة المرور

إذا كانت كلمة مرور البروكسي تحتوي على رموز خاصة (@، :، /، ?)، يجب ترميزها بتنسيق ترميز URL (ترميز النسبة المئوية). على سبيل المثال:

مثال على استخدام كلمة مرور تحتوي على رموز خاصة:

# كلمة المرور الأصلية: P@ss:w0rd/123
# كلمة المرور المشفرة: P%40ss%3Aw0rd%2F123

curl -x http://username:P%40ss%3Aw0rd%2F123@proxy.example.com:8080 \
     https://api.example.com/users

للتشفير التلقائي، يمكنك استخدام أدوات الإنترنت لترميز URL أو الأمر في Python:

python3 -c "import urllib.parse; print(urllib.parse.quote('P@ss:w0rd/123'))"
# الإخراج: P%40ss%3Aw0rd%2F123

حل المشكلات والأخطاء الشائعة

عند العمل مع البروكسي في عملاء API، غالبًا ما تحدث أخطاء شائعة. دعونا نستعرض أكثر المشكلات انتشارًا وطرق حلها.

خطأ "407 Proxy Authentication Required"

يعني هذا الخطأ أن خادم البروكسي يتطلب مصادقة، لكن بيانات الاعتماد لم يتم تقديمها أو أنها غير صحيحة. الحلول:

• تحقق من صحة اسم المستخدم وكلمة المرور في لوحة التحكم الخاصة بمزود البروكسي
• تأكد من ترميز الرموز الخاصة في كلمة المرور (انظر القسم أعلاه)
• تحقق من تنسيق URL: http://username:password@host:port
• إذا كنت تستخدم قائمة العناوين IP المصرح بها، تأكد من إضافة IP الحالي إلى القائمة

مثال على التشخيص في cURL مع إخراج تفصيلي:

curl -v -x http://username:password@proxy.example.com:8080 https://api.example.com/users
# العلم -v (verbose) سيظهر جميع الرؤوس وعملية المصادقة

خطأ "Connection timeout" أو "Failed to connect"

يحدث هذا الخطأ عندما لا يستطيع عميل API إنشاء اتصال مع خادم البروكسي. الأسباب المحتملة:

• عنوان أو منفذ خادم البروكسي غير صحيح - تحقق من الإعدادات مع المزود
• خادم البروكسي غير متاح أو محمّل - حاول استخدام خادم آخر من القائمة
• قد يقوم جدار الحماية الخاص بك بحظر الاتصالات الصادرة على منفذ البروكسي
• قد يكون مزود البروكسي قد حظر IP الخاص بك بسبب تجاوز الحدود

للتشخيص، حاول الاتصال بالبروكسي مباشرة عبر telnet أو nc:

# تحقق من توفر البروكسي
telnet proxy.example.com 8080
# أو
nc -zv proxy.example.com 8080

# إذا لم يتم إنشاء الاتصال، فالمشكلة في الشبكة أو خادم البروكسي غير متاح

خطأ "SSL certificate problem"

عند استخدام بروكسي HTTPS، قد تحدث مشاكل في التحقق من شهادات SSL. هذا مهم بشكل خاص للبروكسيات MITM (Man-in-the-Middle) التي تعترض وتفكك حركة مرور HTTPS. الحلول:

• في cURL، استخدم العلم -k أو --insecure لتعطيل التحقق من الشهادة (فقط للاختبار!)
• في Postman، قم بتعطيل "SSL certificate verification" في Settings → General
• قم بتثبيت الشهادة الجذرية للبروكسي في النظام (لبيئة الإنتاج)

# تعطيل التحقق من الشهادة
curl -k -x http://username:password@proxy.example.com:8080 https://api.example.com/users