منشئ أوامر cURL وبنّاؤها

ما هو أمر curl؟

# Plain GET — curl defaults to GET
curl https://api.example.com/users

# GET with a Bearer token (auth is just a header)
curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

# POST a JSON body — note the Content-Type header
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

# Multipart file upload — '@' reads the file from disk
curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

الميزات الرئيسية

بدائل curl وعملاء HTTP

أمثلة على أوامر curl

curl https://api.example.com/users

curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

curl -X POST https://api.example.com/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=ada&password=s3cret'

curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

curl -L -o archive.zip \
  https://example.com/files/archive.zip

curl -u ada:s3cret \
  https://api.example.com/private

curl -v -i https://api.example.com/health

كيفية بناء أمر curl

1. 1

   اختر طريقة HTTP

   اختر GET أو POST أو PUT أو PATCH أو DELETE أو HEAD أو OPTIONS. افتراضي curl هو GET؛ اختيار POST أو أفعال أخرى يضيف -X METHOD للأمر المُنشأ. أو انقر شريحة إعداد مسبق لضبط الطريقة وجسم مطابق بنقرة واحدة.

2. 2

   أدخل الرابط ومعاملات الاستعلام

   اكتب رابط الطلب (مثلاً https://api.example.com/users). أضف معاملات الاستعلام كأزواج مفتاح/قيمة والأداة تُرمّزها بترميز URL وتُلحق ?key=value&… بالرابط تلقائياً — لا ترميز يدوي مطلوب.

3. 3

   أضف الترويسات والمصادقة

   أضف ترويسات الطلب كأزواج مفتاح/قيمة، ثم اختر مخطط المصادقة: بلا، أو رمز Bearer، أو Basic (اسم مستخدم/كلمة مرور)، أو ترويسة مفتاح API مخصصة. تُولَّد ترويسة Authorization الصحيحة أو الترويسة المخصصة بالشكل الدقيق الذي يتوقعه الخادم.

4. 4

   عيّن جسم الطلب

   لطلبات POST/PUT/PATCH، اختر نوع الجسم: الصق JSON خاماً (تُضاف ترويسة Content-Type تلقائياً)، أو أنشئ حقول نموذج مُرمَّزة بـ URL، أو اجمع رفعاً متعدد الأجزاء وحوّل أي حقل إلى ملف بالبادئة @.

5. 5

   فعّل الخيارات

   شغّل الأعلام التي تحتاجها — اتباع إعادة التوجيه (-L)، أو TLS غير الآمن (-k)، أو تفصيلي (-v)، أو تضمين الترويسات (-i)، أو مضغوط (--compressed)، أو إخراج إلى ملف (-o)، أو مهلة اتصال، أو وكيل (-x). كل تبديل يحدّث الأمر فورياً.

6. 6

   انسخ أو صدّر أو أعد ضبط

   انسخ الأمر المنتهي، أو صدّر .sh لتنزيله كسكريبت، أو أعد الضبط لمسح النموذج. استخدم مفتاح تعدد الأسطر للتبديل بين مخرج سطر واحد ومتعدد الأسطر مع شرطة مائلة عكسية قبل النسخ.

أخطاء curl الشائعة

# Intended a PATCH, but -d alone implies POST
curl -d '{"role":"admin"}' \
  https://api.example.com/users/7

# Set the verb explicitly
curl -X PATCH -d '{"role":"admin"}' \
  -H 'Content-Type: application/json' \
  https://api.example.com/users/7

# Server sees urlencoded, not JSON — 400/415
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

# Declare the JSON content type
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

# $name gets expanded by the shell to empty string
curl -d "{\"user\":\"$name\"}" \
  https://api.example.com/users

# Single quotes send the body literally
curl -d '{"user":"$name"}' \
  https://api.example.com/users

# -d makes this a POST, not a GET
curl -d 'page=2&limit=50' \
  https://api.example.com/users

# Query string on the URL keeps it a GET
curl 'https://api.example.com/users?page=2&limit=50'

:: cmd.exe — backslash is not a continuation char
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

:: cmd.exe — one line, or use ^ to continue
curl -X POST https://api.example.com/users -d "{\"name\":\"Ada\"}"

# Space splits the argument — curl sees two args
curl https://api.example.com/search?q=hello world

# Encode the space (or quote the whole URL)
curl 'https://api.example.com/search?q=hello%20world'

حالات الاستخدام الشائعة

اختبار REST API

أنشئ الطلبات وأطلقها ضد نقطة نهاية REST دون مغادرة الطرفية: عيّن الطريقة، والصق رمز Bearer، وأرسل جسم JSON، واقرأ الاستجابة. أسرع طريقة للتأكد أن واجهة API تتصرف صحيحاً قبل كتابة كود العميل.

إعادة إنتاج طلب من التوثيق

يُظهر توثيق API النقاط النهائية والمعاملات لكن نادراً أمراً كاملاً جاهزاً للنسخ. أدخل الطريقة والرابط والترويسات والمصادقة هنا واحصل على أمر curl يعمل كما هو — لا صراع مع الاقتباس أو ترويسات Content-Type مفقودة.

سكريبتات اختبار دخان CI/CD

أنشئ أمر curl لفحص السلامة أو اختبار دخان ما بعد النشر، ثم صدّر .sh لإدراجه في خط أنابيب. أضف --connect-timeout و--max-time حتى لا تتمكن نقطة نهاية معلقة من حجب البناء، وتحقق من رموز الحالة بـ -w.

رفع الملفات وتنزيلها

اجمع رفع multipart/form-data بـ -F field=@file، أو أنشئ تنزيلاً بـ -L -o filename يتبع إعادة التوجيه إلى CDN. رمّز أي أسماء ملفات أو قيم استعلام صعبة أولاً بـ مُرمِّز URL لدينا.

تصحيح خطافات الويب

أعد تشغيل حمولة خطاف ويب بـ POST لجسم JSON نفسه الذي يرسله المزوّد، مع الترويسات الصحيحة للتوقيع وContent-Type. أعد إنتاج الطلب الدقيق محلياً لتصحيح سبب رفض معالجك له.

تقارير الأخطاء القابلة للإعادة

الصق أمر curl واحداً مكتفياً بذاته في تقرير خلل أو طلب سحب حتى يتمكن أي شخص من إعادة إنتاج الطلب الدقيق — الطريقة والترويسات وعنصر نائب للمصادقة والجسم. أوضح بكثير من وصف الطلب بلغة عادية.

تعلّم أعلام curl

شاهد كيف يرتبط كل خيار نموذج بعلم حقيقي — اختر مصادقة Basic وشاهد -u يظهر، أضف جسم JSON وشاهد ترويسة Content-Type تُرفق. طريقة عملية لتعلّم الصياغة، مقترنة بـ ورقة غش curl لدينا.

تحضير طلب للتحويل إلى كود

أنشئ الطلب وتحقق منه كـ curl أولاً، ثم ترجمه إلى عميل HTTP في تطبيقك. سيُحوّل تبويب التحويل القادم أمر curl ملصوقاً إلى fetch وrequests وGo وPHP وRuby وNode.js — ابدأ من أمر curl تعرف أنه يعمل.

مرجع أعلام curl والصياغة

اقتباس الصدفة والهروب

تلفّ الأداة القيم بعلامات اقتباس مفردة، الشكل الأأمن في صدفات POSIX لأنه لا يُوسَّع شيء داخل سلسلة مقتبسة بعلامة مفردة. تُصدَر علامة الاقتباس المفردة الحرفية داخل قيمة كتسلسل '\'' (إغلاق الاقتباس، ثم الاقتباس المهروب، ثم إعادة الفتح). في cmd.exe بدّل إلى علامات اقتباس مزدوجة؛ يُشغّل Git Bash وWSL الأوامر المُنشأة بعلامة اقتباس مفردة دون تعديل.

-d مقابل --data-raw مقابل --data-binary

يُزيل -d/--data أسطر السطر والإرجاع من الجسم — مناسب لأزواج key=value، مُسرِّب للمحتوى متعدد الأسطر. --data-raw مماثل لكنه لن يعامل @ الأولية كاسم ملف. --data-binary يُرسل البايتات كما هي (استخدم @file لرفع محتوى الملف الخام). الثلاثة تعني POST إلا إذا جاوزت الطريقة.

متعدد الأجزاء (-F) مقابل مُرمَّز بـ URL (-d)

ينتج -F field=value نوع multipart/form-data بحد مُولَّد — مطلوب لرفع الملفات (-F file=@path) والنماذج المختلطة من ملفات ونصوص. ينتج -d field=value نوع application/x-www-form-urlencoded، سلسلة واحدة مربوطة بـ &. لا تضبط Content-Type يدوياً للمتعدد الأجزاء؛ يحسب curl الحد ويضبط الترويسة بنفسه.

ترميز ترويسة المصادقة

ترسل مصادقة Bearer ترويسة Authorization: Bearer token كما هي (RFC 6750). تُرمَّز مصادقة Basic من -u user:pass بـ Base64 في Authorization: Basic base64 على الشبكة — ترميز فقط وليس حماية، استخدم HTTPS. مفتاح API هو أي ترويسة مخصصة تتطلبها الخدمة، مثلاً X-API-Key: value.

ترميز سلسلة الاستعلام

تُرمَّز معاملات الاستعلام المضافة في البنّاء بترميز النسبة المئوية وتُلحق كـ ?key=value&key2=value2. تُهرَب الأحرف المحجوزة (المسافات، &، =، #) حتى يكون الرابط صالحاً. لحقول الجسم التي يجب ترميزها، يتولى --data-urlencode في curl الترميز وقت الطلب.

سلوك إعادة التوجيه (-L)

بدون -L، يطبع curl استجابة 301/302 ويتوقف. مع -L يتبع ترويسة Location إلى الرابط النهائي. لاحظ أن curl يحذف ترويسة Authorization حين تعبر إعادة التوجيه إلى مضيف مختلف (افتراضي أمني)؛ استخدم --location-trusted فقط حين تفهم الآثار.

الاستجابات المضغوطة

تُضيف --compressed ترويسة Accept-Encoding مُعلنةً دعم gzip/deflate/brotli وتفك ضغط الاستجابة بشفافية، موفّرةً عرض النطاق الترددي. الجسم المفكوك مطابق لطلب غير مضغوط — تحسين نقل بحت، آمن للتمكين في معظم استدعاءات API.

المخرج: -o مقابل -O

تكتب -o filename جسم الاستجابة في ملف تسمّيه؛ تحفظ -O تحت اسم الملف البعيد من مسار الرابط. كلتاهما تمنع التفريغ المعتاد على stdout. اجمع مع -L حتى تحلّ إعادات التوجيه إلى الأصل الحقيقي قبل كتابة الملف.

أفضل الممارسات لطلبات curl

لا تُضمِّن الأسرار بشكل ثابت في الأوامر المشتركة

أمر curl تلصقه في طلب سحب أو تذكرة أو محادثة سيقرأه آخرون وتُفهرسه أدوات. استبدل الرموز وكلمات المرور بعنصر نائب (YOUR_TOKEN) أو أشر إلى متغير بيئة (-H "Authorization: Bearer $API_TOKEN"). لبيانات الاعتماد الطويلة، يمكن لـ curl قراءة ترويسة من ملف بـ -H @headerfile حتى لا يظهر السرّ في سجل الصدفة.

فضّل --data-binary @file للحمولات الثنائية

حين يكون الجسم ملفاً بايتاته مهمة — صورة أو حمولة موقّعة أو JSON المسافات البيضاء فيه مهمة — استخدم --data-binary @file بدلاً من -d @file. تُزيل -d العادية أسطر السطر والإرجاع بصمت، مُتلفةً المحتوى الثنائي ومتعدد الأسطر. --data-binary يُرسل الملف كما هو على القرص.

اقتبس قيم الترويسات

اعرض دائماً قيم -H بين اقتباسات: -H 'Content-Type: application/json'. بدون اقتباس، تُقسّم المسافة بعد النقطتين المعامل ويرى curl ترويسة مشوّهة. علامات الاقتباس المفردة تمنع الصدفة أيضاً من توسيع $ و* وغيرها من الأحرف الخاصة داخل القيمة — بالضبط ما تُصدره هذه الأداة افتراضياً.

استخدم --compressed لتوفير عرض النطاق

أضف --compressed إلى استدعاءات API والتنزيلات لطلب ترميز gzip/brotli وليفك curl الضغط بشفافية. لواجهات API ذات بيانات JSON الكثيفة يمكن تقليل حجم النقل بنسبة 70–90% دون أي تغيير على الاستجابة التي تراها — مكسب مجاني في السكريبتات التي تستعلم النقاط النهائية بتكرار.

ثبّت المهلات في السكريبتات

في أي سياق آلي، أضف --connect-timeout و--max-time حتى لا تتمكن نقطة نهاية بطيئة أو معلقة من حجب خط أنابيب للأبد. فحص سلامة بـ --max-time 10 يفشل بسرعة ويتيح لـ CI المتابعة. اجمع مع --retry N لاستيعاب التذبذبات العابرة في الشبكة دون الاستسلام فوراً.

تحقق بـ -v قبل الأتمتة

قبل إدراج أمر curl في سكريبت أو وظيفة cron، شغّله مرة واحدة بـ -v لرؤية سطر الطلب الدقيق والترويسات ومصافحة TLS. هي أسرع طريقة لاكتشاف طريقة خاطئة، أو Content-Type مفقودة، أو ترويسة مصادقة لم تُرفق — صحّح تفاعلياً، ثم احذف -v للإنتاج.

الأسئلة الشائعة