استخدام cURL في ServBay

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

توفر ServBay، باعتبارها بيئة تطوير ويب محلية مخصّصة للمطورين، أحدث إصدار مضمّن من cURL دون الحاجة لتثبيت منفصل. هذا يعني أنه يمكنك استخدام أمر curl مباشرة من طرفية ServBay لتسهيل جميع عمليات التفاعل والاختبار الشبكي.

في هذا الدليل سوف نشرح بالتفصيل كيفية استخدام cURL في بيئة ServBay مع تقديم أمثلة شائعة ونصائح متقدمة.

التثبيت والإعداد

تثبيت cURL

يأتي cURL مثبتًا تلقائيًا مع ServBay ولا يحتاج المستخدم لتركيبه بشكل يدوي. هذا يعني أنه يمكنك استخدام أمر curl فورًا من الطرفية في ServBay.

للتحقق من توافر cURL وإصدار الأداة، اكتب الأمر التالي في طرفية ServBay:

curl --version

سيعرض لك هذا الأمر معلومات حول إصدار cURL والبروتوكولات والخصائص المدعومة، مما يؤكد أن cURL جاهز للاستخدام.

إعداد cURL

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

أمثلة أساسية للاستخدام

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

إرسال طلب HTTP GET

إرسال طلب GET هو أحد استخدامات cURL الأكثر شيوعًا، ويُستخدم لجلب الموارد من عنوان URL معين.

curl -X GET https://api.servbay.demo/data

وبما أن GET هو الوضع الافتراضي، يمكنك تبسيط الأمر ليصبح:

curl https://api.servbay.demo/data

إرسال طلب HTTP POST

عادة يُستخدم طلب POST لإرسال البيانات إلى الخادم، مثل بيانات النماذج أو حمولة JSON. استخدم الخيار -d (أو --data) لتحديد البيانات المرسلة.

curl -X POST -d "param1=value1&param2=value2" https://api.servbay.demo/data

تحميل ملف

يعد تحميل الملفات باستخدام cURL أمرًا سهلاً. الخيار -O يحفظ الملف باسم الملف الأصلي في نفس الدليل الحالي.

curl -O https://servbay.demo/file.zip

إذا رغبت في تحديد اسم الملف المحلي بنفسك، استخدم الخيار -o:

curl -o local_filename.zip https://servbay.demo/file.zip

رفع ملف

يمكنك محاكاة رفع الملفات بسهولة مع cURL. استخدم الخيار -F (أو --form) لتحديد الملف المراد رفعه باستخدام الصيغة name=@/path/to/file.

curl -X POST -F "file=@/Applications/ServBay/www/servbay.demo/upload/document.pdf" https://api.servbay.demo/upload

يرجى استبدال /Applications/ServBay/www/servbay.demo/upload/document.pdf بمسار الملف الفعلي الذي تريد رفعه.

نصائح استخدام متقدمة

بالإضافة للعمليات الأساسية، توفر cURL العديد من الخيارات المتقدمة التي تجعلها أداة شبكية غاية في المرونة.

تعيين رؤوس HTTP مخصصة

بواسطة الخيار -H (أو --header) يمكنك إضافة رؤوس HTTP مخصصة إلى الطلبات، وهذا مفيد عند إرسال أنواع محتوى محددة مثل JSON أو تمرير بيانات المصادقة مثل رموز API أو Bearer token.

curl -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" https://api.servbay.demo/data

التعامل مع بيانات JSON

في تطوير واجهات برمجة التطبيقات (API) الحديثة، تُستخدم صيغة JSON بكثرة. cURL تسهّل إرسال واستقبال بيانات JSON.

إرسال بيانات JSON

عند إرسال JSON، يجب تعيين رأس Content-Type إلى application/json واستخدام -d لإرسال نص JSON.

curl -X POST -H "Content-Type: application/json" -d '{"key1":"value1", "key2":"value2"}' https://api.servbay.demo/data

جلب وتحليل استجابة JSON (بالاشتراك مع jq)

الاستجابات من cURL عادة ما تظهر كنص خام. إذا أردت إبراز وعرض JSON بطريقة منظمة، يمكنك استخدام الأداة القوية jq.

curl -s https://api.servbay.demo/data | jq .

ملاحظة: jq ليست أداة مدمجة مع ServBay، وربما ستحتاج لتثبيتها يدويًا. على نظام macOS، إذا كان لديك Homebrew، يمكنك تنفيذ brew install jq لتثبيتها. الخيار -s في cURL يفعل الوضع الصامت لضمان أن فقط الجسم يتم تمريره إلى jq. لمزيد من المعلومات تصفح موقع jq الرسمي.

التعامل مع ملفات تعريف الارتباط (Cookies)

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

حفظ ملفات تعريف الارتباط في ملف

استخدم الخيار -c (أو --cookie-jar) لتخزين الكوكيز التي يرسلها الخادم في ملف معين.

curl -c cookies.txt https://servbay.demo

استخدام ملفات تعريف الارتباط من ملف

استخدم الخيار -b (أو --cookie) لتحميل الكوكيز من ملف وإرسالها في الطلبات اللاحقة.

curl -b cookies.txt https://servbay.demo/profile

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

إذا كنت بحاجة للوصول إلى الإنترنت عبر خادم وسيط (بروكسي)، استخدم الخيار -x (أو --proxy) لتحديد عنوان البروكسي.

curl -x http://proxy.servbay.demo:8080 https://api.servbay.demo/data

تحديد معدل نقل البيانات

استخدم الخيار --limit-rate لتحديد سرعة نقل البيانات (مثلا بالبايت أو بالكيلو أو الميجا). هذا مفيد لاختبار سيناريوهات تقييد السرعة أو تجنب استهلاك النطاق الترددي الزائد.

curl --limit-rate 100K https://servbay.demo/largefile.zip -O

استئناف التحميل المتقطع

عند تحميل ملفات كبيرة، يدعم cURL خاصية استئناف التحميل في حال الانقطاع. استخدم الخيار -C - ليستكمل التحميل من المكان الذي توقف فيه.

curl -C - -O https://servbay.demo/largefile.zip

التحقق من شهادات SSL

افتراضياً، يتحقق cURL من صحة شهادات SSL عند الاتصال عبر HTTPS. إذا احتجت لتحديد شهادة CA معيّنة، استخدم الخيار --cacert.

curl --cacert /path/to/custom_ca.crt https://secure.servbay.demo

في حال قمت بإعداد موقع HTTPS في ServBay وتستخدم شهادة موقّعة من CA الخاصة بـ ServBay (ServBay User CA أو ServBay Public CA)، يمكنك الاستفادة من حزمة شهادات CA الموجودة عادة في مسار etc/ssl ضمن دليل تثبيت ServBay. راجع وثائق SSL/HTTPS في ServBay للحصول على المسار الدقيق.

تحذير: في بعض حالات الاختبار، يمكن استخدام الخيار --insecure (أو -k) لتجاوز خطأ التحقق من شهادة SSL، ولكن لا يُنصح أبدًا استخدامه في بيئة الإنتاج أو عند التعامل مع بيانات حساسة لأنه يعطل تحقق الأمان الأساسي.

curl --insecure https://secure.servbay.demo

الأسئلة الشائعة (FAQ)

1. تظهر رسالة أن أمر curl غير موجود في طرفية ServBay

• السبب: عادة سببه عدم ضبط مسار الملفات التنفيذية لـ ServBay في الطرفية بشكل صحيح.
• الحل: تأكد من ضبط متغيرات البيئة لـ ServBay بشكل صحيح. إذا استمرت المشكلة، افتح قائمة "الإعدادات" في ServBay ثم "أدوات سطر الأوامر" واضبطها لكل من zsh وbash، ثم أعد تشغيل الطرفية.

2. تظهر أخطاء في الاتصال أو انقطاع أثناء إرسال الطلب

• السبب: غالبًا يكون نتيجة تعذّر الوصول إلى الخادم المستهدف، أو مشاكل في الشبكة، أو وجود جدار ناري، أو عنوان URL غير صحيح.
• الحل:
  • تحقق من صحة عنوان URL.
  • تأكد من عمل اتصال الشبكة بشكل طبيعي.
  • إذا كنت تصل إلى موقع ServBay محلي (مثل servbay.demo)، تحقق من تشغيل ServBay وأن خادم الويب (مثل Caddy أو Nginx) فعّال.
  • افحص وجود جدران نارية أو برامج أمان تمنع cURL من الاتصال بالخارج.
  • بالنسبة لاتصالات HTTPS، تحقق من صلاحية شهادة SSL (راجع فقرة شهادة SSL أعلاه).

3. فشل تحميل أو رفع الملفات

• السبب: قد يعود ذلك لخطأ في مسار الملف، أو لعدم كفاية الصلاحيات، أو لعدم دعم الخادم للعمليات المطلوبة، أو وجود أخطاء في الخادم.
• الحل:
  • تحقق من صحة مسار الملف المُدرج في الأمر.
  • تأكد أن المستخدم الذي يشغل ServBay أو المستخدم الحالي للطرفية يمتلك صلاحيات القراءة/الكتابة على الملف.
  • عند الرفع إلى موقع ServBay محلي، تأكد من إعداد الخادم للسماح بالرفع وأن الدليل الهدف موجود وقابل للكتابة.
  • راجع رسائل الخطأ من cURL لمعرفة التفاصيل.

4. فشل التحقق من شهادة SSL

• السبب: قد يكون السبب أن شهادة الموقع غير صالحة أو منتهية الصلاحية أو لا تتطابق مع اسم النطاق أو أن السلسلة غير مكتملة أو cURL لا يجد CA الجذر الموقعة للشهادة.
• الحل:
  • تحقق من صلاحية شهادة الموقع الهدف.
  • إذا كنت تتعامل مع موقع ServBay محلي يستخدم CA مخصص، اتبع تعليمات هذا الدليل أو وثائق SSL الخاصة بـ ServBay، وحدد مسار حزمة CA باستخدام الخيار --cacert.
  • في حالات الاختبار غير الحساسة فقط، يمكن استخدام الخيار --insecure لتجاهل التحقق مؤقتًا (غير موصى به للإنتاج).

الخلاصة

تعد cURL أداة فعالة ومرنة لا غنى عنها لمطوري الويب، فهي تتيح إجراء جميع عمليات التفاعل الشبكي ونقل البيانات من بيئة التطوير المحلية بسهولة، سواء كانت طلبات HTTP بسيطة أو عمليات استدعاء API معقدة أو التعامل مع الملفات. الإلمام بأساسيات واستخدامات cURL المتقدمة من خلال ServBay سيعزز من إنتاجيتك وسرعة تشخيص وحل المشكلات أثناء التطوير.