ورقة غش curl: أكثر من 40 مثالاً لأوامر HTTP وAPI

أنت غارق في ثلاث قفزات SSH داخل خادم تجهيز (staging)، وثمة API يُعيد شيئاً خاطئاً، وعميل HTTP الوحيد المثبَّت هو curl. أو ربما تقرأ سكربت CI يفحص صحة خدمة وتريد أن تعرف ما الذي يفعله -fsS فعلاً. أو لصق زميل سطراً واحداً في Slack وتحتاج إلى تكييفه. curl موجود في كل مكان، ورايّاته (flags) مقتضبة بما يكفي ليعجز الجميع عن تذكّرها كلها.

ورقة غش curl هذه مبنية تماماً لتلك اللحظات. تحصل على جدول مرجعي سريع يضم العشرات من الرايّات التي تستخدمها يومياً، ثم أمثلة أوامر جاهزة للنسخ لكل مهمة شائعة: طلبات GET وPOST، إرسال الترويسات، مصادقة Bearer بالرمز، رفع الملفات وتنزيلها، واختبار API داخل السكربتات. كل أمر يستخدم رابط URL حقيقياً قابلاً للتشغيل (httpbin.org أو عنصراً نائباً من نوع api.example.com)، فيمكنك أن تلصقه وتجرّبه. السلوك مستند إلى توثيق curl الرسمي وRFC 9110، وهو المعيار الحالي لدلالات HTTP.

مرجع سريع — رايّات curl التي ستستخدمها فعلاً

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

الرايّة	المعنى	المثال
`-X`	تعيين طريقة HTTP	`curl -X DELETE https://api.example.com/items/42`
`-H`	إضافة ترويسة طلب (قابلة للتكرار)	`curl -H "Accept: application/json" https://httpbin.org/get`
`-d`	إرسال جسم طلب (يستلزم POST)	`curl -d "name=alice" https://httpbin.org/post`
`--json`	إرسال جسم JSON + ضبط ترويسات JSON	`curl --json '{"id":1}' https://httpbin.org/post`
`-F`	إرسال حقل نموذج متعدد الأجزاء / ملف	`curl -F "file=@report.pdf" https://httpbin.org/post`
`-o`	حفظ الخرج في ملف باسم محدد	`curl -o page.html https://example.com`
`-O`	الحفظ باسم الملف البعيد	`curl -O https://example.com/archive.zip`
`-L`	اتباع عمليات إعادة التوجيه	`curl -L https://httpbin.org/redirect/2`
`-u`	مصادقة أساسية `user:pass`	`curl -u alice:s3cret https://httpbin.org/basic-auth/alice/s3cret`
`-i`	تضمين ترويسات الاستجابة في الخرج	`curl -i https://httpbin.org/get`
`-I`	جلب الترويسات فقط (HEAD)	`curl -I https://example.com`
`-v`	مُسهَب: إظهار الطلب + مصافحة TLS	`curl -v https://example.com`
`-s`	صامت (بلا مقياس تقدم)	`curl -s https://httpbin.org/get`
`-w`	كتابة متغيرات بعد النقل	`curl -s -o /dev/null -w "%{http_code}" https://example.com`
`-b`	إرسال ملفات تعريف الارتباط (نص أو ملف)	`curl -b cookies.txt https://httpbin.org/cookies`
`-c`	حفظ ملفات تعريف الارتباط المُستلَمة في جرّة	`curl -c cookies.txt https://httpbin.org/cookies/set/a/1`
`-k`	تخطّي التحقق من شهادة TLS	`curl -k https://self-signed.example.com`
`--http2`	طلب HTTP/2	`curl --http2 https://example.com`
`--http3`	طلب HTTP/3 (QUIC)	`curl --http3 https://example.com`
`-T`	رفع ملف بطريقة PUT	`curl -T backup.tar https://api.example.com/files/backup.tar`
`--data-urlencode`	ترميز URL لحقل في الجسم	`curl --data-urlencode "q=hello world" https://httpbin.org/get -G`
`--max-time`	تحديد عدد ثوانٍ للنقل بأكمله	`curl --max-time 10 https://api.example.com/health`
`--connect-timeout`	تحديد عدد ثوانٍ لإنشاء الاتصال	`curl --connect-timeout 5 https://api.example.com/health`
`--retry`	إعادة المحاولة N مرة عند الإخفاق	`curl --retry 3 https://api.example.com/health`
`--limit-rate`	تحديد عرض النطاق	`curl --limit-rate 2M -O https://example.com/big.iso`

أساسيات صياغة curl — تشريح طلب

أمر curl هو الملف التنفيذي، وبعض الرايّات، ورابط URL. يمكن أن يأتي الرابط قبل الرايّات أو بعدها؛ لا يأبه curl بالترتيب. ما يأبه له هو أي الرايّات تستلزم طريقة أو جسماً، لأن هذه تتفاعل فيما بينها.

طلب GET بسيط

بدون رايّة طريقة، يرسل curl طلب GET. هذا هو الأمر كاملاً:

curl https://httpbin.org/get

يعكس httpbin طلبك ويعيده بصيغة JSON، ما يجعله مثالياً للاختبار. أضف سلسلة استعلام بالطريقة نفسها التي تفعلها في المتصفح:

curl "https://httpbin.org/get?page=2&sort=desc"

ضع الرابط بين علامتي اقتباس. علامة & المجردة تأمر صَدفتك (shell) بتشغيل الأمر في الخلفية وتُسقِط بصمت كل ما بعدها — وهي من أكثر أخطاء curl شيوعاً، وقد غطّيناها في قسم المطبّات أدناه.

رؤية الاستجابة: الجسم، الترويسات، كلاهما

افتراضياً يطبع curl جسم الاستجابة فقط. ثلاث رايّات تغيّر ما تراه:

# الجسم + سطر الحالة + ترويسات الاستجابة
curl -i https://httpbin.org/get

# الترويسات فقط — يرسل طلب HEAD، بلا جسم
curl -I https://example.com

# تتبّع كامل: سطر الطلب، ترويسات الطلب، مصافحة TLS، الاستجابة
curl -v https://example.com

استخدم -i حين تريد الجسم مع نظرة سريعة على Content-Type أو Set-Cookie. استخدم -I لفحص مورد دون تنزيله (حجم الملف، تاريخ آخر تعديل، وجهة إعادة التوجيه). والجأ إلى -v حين يحدث خطأ ما وتحتاج إلى رؤية ما أرسله curl بالضبط.

اتباع عمليات إعادة التوجيه

لا يتبع curl عمليات إعادة التوجيه ما لم تطلب ذلك. أصِبْ رابطاً يُعيد 301 أو 302 دون -L فتحصل على استجابة إعادة التوجيه نفسها، لا الوجهة:

# يتوقف عند 302، ولا يطبع شيئاً مفيداً
curl https://httpbin.org/redirect/1

# يتبع السلسلة حتى الـ 200 النهائي
curl -L https://httpbin.org/redirect/1

إن لم تكن متأكداً لماذا يصل طلبٌ إلى حيث يصل، يُظهِر -IL كود حالة كل قفزة. ولمعرفة معنى كل من تلك الأكواد — ولماذا ليس 301 و302 قابلين للتبادل — راجع ورقة غش أكواد حالة HTTP.

طرق HTTP مع curl (GET، POST، PUT، PATCH، DELETE)

يختار curl الطريقة تلقائياً بناءً على رايّاتك: -d أو —json يستلزم POST، والروابط المجردة تستلزم GET. استخدم -X فقط حين تحتاج إلى طريقة لا تطابق الجسم الذي ترسله.

GET مع معاملات الاستعلام

بناء سلسلة استعلام يدوياً عرضة للخطأ ما إن تحتوي القيم على مسافات أو علامة &. تأمر رايّة -G الأمرَ curl بإلحاق حقول —data-urlencode بالرابط كسلسلة استعلام مُرمَّزة بشكل صحيح:

curl -G https://httpbin.org/get \
  --data-urlencode "q=hello world" \
  --data-urlencode "tag=c++"

ينتج عن هذا ?q=hello%20world&tag=c%2B%2B — يتولى curl الترميز بالنسبة المئوية كي لا تشحن رابطاً معطوباً.

POST: بيانات النموذج مقابل JSON

يأتي طلب POST في curl بشكلين شائعين. مُرمَّز كنموذج (جسم نموذج HTML الكلاسيكي):

curl -d "name=alice&role=admin" https://httpbin.org/post

تضبط -d الترويسة Content-Type: application/x-www-form-urlencoded وتبدّل الطريقة إلى POST نيابةً عنك. ولأجل API من نوع JSON، أرسِل JSON بدلاً من ذلك:

curl -d '{"name":"alice","role":"admin"}' \
  -H "Content-Type: application/json" \
  https://httpbin.org/post

ثمة طريقة أنظف للقيام بذلك، وهي مشروحة في القسم التالي.

PUT وPATCH

PUT يستبدل مورداً؛ وPATCH يحدّث جزءاً منه. وPUT عديمة الأثر التراكمي (idempotent) — إرسالها مرتين يُبقي الحالة نفسها.

# استبدال المورد بأكمله
curl -X PUT -d '{"name":"alice","role":"owner"}' \
  -H "Content-Type: application/json" \
  https://api.example.com/users/7

# تحديث حقل واحد
curl -X PATCH -d '{"role":"owner"}' \
  -H "Content-Type: application/json" \
  https://api.example.com/users/7

DELETE

عادةً لا يحمل DELETE جسماً، لذا تكفيك -X وحدها:

curl -X DELETE https://api.example.com/users/7

إرسال الترويسات وأجسام JSON

معظم العمل الحقيقي مع API هو ترويسات وJSON. رايّتان تتحمّلان العبء: -H و—json.

ترويسات curl المخصصة بـ -H

تضيف -H ترويسة واحدة ويمكن تكرارها بقدر ما تحتاج. هكذا تضبط Accept وAuthorization وترويسات X- المخصصة ومعرّفات الطلب:

curl https://httpbin.org/headers \
  -H "Accept: application/json" \
  -H "X-Request-Id: 9f3c1a" \
  -H "User-Agent: my-cli/1.0"

لإزالة ترويسة افتراضية كان curl سيرسلها لولا ذلك، أعطها قيمة فارغة (-H “User-Agent:”). ولإرسال ترويسة بلا قيمة، استخدم فاصلة منقوطة (-H “X-Empty;”).

إرسال JSON عبر POST: -d مقابل رايّة —json الحديثة

منذ curl 7.82، صارت —json الطريقة الاصطلاحية لإرسال طلب POST من نوع JSON. تفعل ثلاثة أشياء دفعةً واحدة: تضبط Content-Type: application/json، وتضبط Accept: application/json، وترسل الجسم حرفياً.

# الطريقة المُسهَبة القديمة — ثلاث قطع يجب إبقاؤها متزامنة
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name":"alice"}' \
  https://httpbin.org/post

# المكافئ الحديث
curl --json '{"name":"alice"}' https://httpbin.org/post

—json قابلة للتكرار وتُسَلسِل القيم، و—json @file.json تقرأ الجسم من ملف. فضّلها لأي API من نوع JSON.

Content-Type وAccept

هاتان الترويستان هما من حيث تأتي أخطاء 415 و406. تصف Content-Type الجسم الذي ترسله؛ وتقول Accept ما تريد استرجاعه. أرسِل JSON إلى نقطة نهاية لا تقبل سوى بيانات النموذج فتحصل على 415 Unsupported Media Type. اطلب XML من API لا يدعم سوى JSON فقد تحصل على 406 Not Acceptable. (هذه الأكواد مشروحة في دليل أكواد حالة HTTP.)

حين تعود الاستجابة كجدار من JSON المُصغَّر، نسّقه بإتقان عبر منسق JSON، أو مرّره مباشرةً إلى jq لاستخراج حقل واحد:

curl -s https://httpbin.org/json | jq '.slideshow.title'

ولمجموعة مرشّحات jq الكاملة — الانتقاء والتعيين وإعادة تشكيل استجابات API — راجع ورقة غش jq لمعالجة JSON من سطر الأوامر.

المصادقة مع curl

أربعة أنماط مصادقة تغطي كل API تقريباً: المصادقة الأساسية، ورموز Bearer، ومفاتيح API، وملفات تعريف الارتباط.

المصادقة الأساسية (-u user:pass)

ترسل -u ترويسة HTTP بصيغة Authorization: Basic تحمل بيانات اعتمادك مُرمَّزة بـ Base64:

curl -u alice:s3cret https://httpbin.org/basic-auth/alice/s3cret

احذف كلمة المرور (-u alice) فيطالبك curl بها، مبقياً إياها خارج سجل صَدفتك.

رموز Bearer وOAuth

تستخدم معظم واجهات API الحديثة رمز Bearer في curl: رمز وصول OAuth 2.0 أو رمز API في ترويسة Authorization. لدى curl اختصار، —oauth2-bearer، يكافئ كتابة الترويسة يدوياً:

# ترويسة صريحة
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0.abc" \
  https://api.example.com/me

# الاختصار
curl --oauth2-bearer "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0.abc" \
  https://api.example.com/me

إذا رفض الخادم الخلفي الرمز، فك ترميزه عبر محلّل JWT للتحقق من مطالبات exp (انتهاء الصلاحية) وaud (الجمهور) وiss (المُصدِر) قبل أن تلوم curl — فالرمز المنتهي أو ذو الجمهور الخاطئ هو السبب المعتاد.

مفاتيح API (ترويسة مقابل معامل استعلام)

بعض واجهات API تريد المفتاح في ترويسة، وأخرى في معامل استعلام. الترويسات أكثر أماناً لأن الروابط تتسرّب إلى السجلات وتاريخ المتصفح:

# المفضّل: المفتاح في ترويسة
curl -H "X-API-Key: sk_live_a1b2c3" https://api.example.com/data

# أقل أماناً: المفتاح في الرابط (ينتهي في سجلات الوصول)
curl "https://api.example.com/data?api_key=sk_live_a1b2c3"

ملفات تعريف الارتباط (-b للإرسال، -c للحفظ)

تكتب -c جرّة ملفات تعريف ارتباط؛ وتقرأ -b واحدة منها. هكذا تحمل جلسةً عبر عدة طلبات:

# سجّل الدخول واحفظ ملف تعريف ارتباط الجلسة
curl -c jar.txt -d "user=alice&pass=s3cret" https://httpbin.org/cookies/set/session/abc123

# أعِد استخدامه في الاستدعاء التالي
curl -b jar.txt https://httpbin.org/cookies

ملاحظة أمنية: الرموز وبيانات الاعتماد لا تنتمي إلا إلى اتصالات HTTPS — يشفّر TLS الترويسات، أما HTTP العادي فلا. تجنّب وضع الأسرار مباشرةً على سطر الأوامر، حيث تنتهي في سجل صَدفتك وفي خرج ps. اقرأ ترويسة من ملف عبر -H @authfile أو اسحب القيمة من متغيّر بيئة (-H “Authorization: Bearer $TOKEN”).

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

سُمّي curl “client URL” لأن نقل الملفات هو مهمته الأصلية. لكل من التنزيل والرفع رايّتان أو ثلاث جديرة بالمعرفة.

التنزيل: -O مقابل -o مقابل -C -

-O (حرف O كبير) يحفظ الملف باسمه البعيد. و-o (صغير) يتيح لك اختيار الاسم. و-C - يستأنف تنزيلاً جزئياً من حيث توقّف:

# احفظ باسم الملف البعيد: archive.zip
curl -O https://example.com/downloads/archive.zip

# احفظ باسم تختاره أنت
curl -o backup.zip https://example.com/downloads/archive.zip

# استئناف تنزيل مقطوع
curl -C - -O https://example.com/downloads/archive.zip

# اتبع عمليات إعادة التوجيه إلى الملف الحقيقي (شائع مع شبكات CDN)
curl -OL https://example.com/latest/archive.zip

لتنزيل محتوى ملف عبر curl يقع خلف إعادة توجيه، أضِف -L — فصفحات الإصدارات وروابط CDN تكاد تعيد التوجيه دائماً.

الرفع: -T مقابل -F

-T يرفع ملفاً بطريقة PUT، مرسلاً البايتات الخام كجسم (شائع لتخزين الكائنات ونقاط نهاية ملفات REST). و-F يرسل طلب multipart/form-data، وهي الصيغة نفسها التي يستخدمها المتصفح لمدخلات الملفات:

# PUT للبايتات الخام
curl -T report.pdf https://api.example.com/files/report.pdf

# رفع multipart/form-data (لاحظ السابقة @)
curl -F "file=@report.pdf" -F "title=Q2 report" https://httpbin.org/post

تأمر السابقة @ الأمرَ curl بقراءة محتويات الملف. وبدونها، يرسل -F “file=report.pdf” السلسلة الحرفية report.pdf، لا الملف.

—data-urlencode والترميز بالنسبة المئوية

حين تحتوي قيمة على مسافات أو & أو = أو محارف غير ASCII، ترسلها -d كما هي فتُعطِب طلبك. أما —data-urlencode فترمّزها بشكل صحيح:

# خطأ: علامة & تقسّم الجسم، والمسافة غير صالحة
curl -d "q=hello world&filter=a&b" https://httpbin.org/post

# صواب: كل حقل مُرمَّز بالنسبة المئوية
curl --data-urlencode "q=hello world" \
  --data-urlencode "filter=a&b" \
  https://httpbin.org/post

إن احتجت إلى فهم معنى تسلسلات %20 و%26 تلك — أو تنقيح قيمة مُرمَّزة مرتين — فالصقها في أداة ترميز وفك ترميز URL أو اقرأ الشرح على مستوى البايت في دليل ترميز وفك ترميز URL.

اختبار API وفحص الاستجابات

curl مناسب تماماً للسكربتات وCI: تكشف -w كل تفاصيل النقل، وتجعل أكواد الخروج الإخفاقات قابلة للكشف.

كود الحالة فقط

لالتقاط كود حالة HTTP وحده، تخلّص من الجسم عبر -o /dev/null واطبع الكود عبر -w:

curl -s -o /dev/null -w "%{http_code}\n" https://httpbin.org/status/204
# → 204

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

تفصيل التوقيت

تكشف -w متغيّرات التوقيت، فترى أين يذهب الوقت — DNS، أو اتصال TCP، أو TLS، أو الخادم نفسه:

curl -s -o /dev/null \
  -w "dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s total=%{time_total}s\n" \
  https://example.com
# → dns=0.004s connect=0.021s tls=0.058s total=0.142s

ارتفاع time_appconnect يشير إلى TLS، وارتفاع time_starttransfer يشير إلى خادم خلفي بطيء.

صامت لكن مع إظهار الأخطاء

تخفي -s مقياس التقدم، لكنها تخفي رسائل الأخطاء أيضاً — وهذا فخّ في السكربتات. اقرنها بـ -S كي يبقى curl صامتاً عند النجاح ويبلّغ عن الإخفاقات رغم ذلك:

curl -sS https://api.example.com/health

curl في CI / السكربتات: الإخفاق عند أخطاء HTTP

افتراضياً يخرج curl بالكود 0 حتى عند 404 أو 500، لأن النقل نفسه نجح. وفي فحص صحة، هذا عكس ما تريد. تجعل -f (fail) الأمر curl يخرج بكود غير صفري عند أخطاء HTTP، فيلتقطها خط أنابيبك:

# يُفشِل البناء إذا أعادت نقطة النهاية 4xx/5xx
curl -fsS https://api.example.com/health || exit 1

-fsS (fail، silent، show-errors) هي تركيبة فحص الصحة المعيارية. ولتشخيص أغنى، لا تزال —fail-with-body (curl 7.76+) تطبع استجابة الخطأ قبل الخروج.

المهلات وإعادة المحاولة

فحص صحة يعلّق إلى الأبد أسوأ من فحص يُخفِق بسرعة. أضِف —max-time (الحد الأقصى للنقل بأكمله) و—connect-timeout (الحد الأقصى لإنشاء الاتصال فقط) إلى كل طلب مُبرمَج:

# الاستسلام بعد 5 ثوانٍ للاتصال، و10 ثوانٍ إجمالاً
curl --connect-timeout 5 --max-time 10 -fsS https://api.example.com/health

حين تكون الشبكة غير مستقرة، تعيد —retry المحاولة على عمليات النقل المُخفِقة بتراجع أُسّي. افتراضياً تعيد المحاولة على الأعطال العابرة فقط (المهلات و5xx)؛ وإضافة —retry-all-errors تعيد المحاولة كذلك عند رفض الاتصال:

# حتى 3 محاولات، مع تراجع بين كل منها
curl --retry 3 --retry-all-errors --max-time 30 -fsS https://api.example.com/health

حين يسحب السكربت ملفاً كبيراً ولا تريد إشباع عرض النطاق، تحدّ —limit-rate من عرض النطاق — فـ —limit-rate 2M يخفض السرعة إلى 2 ميغابايت/ثانية.

HTTP/1.1 وHTTP/2 وHTTP/3 مع curl

يتفاوض curl على إصدار HTTP عبر TLS باستخدام ALPN. يمكنك فرض إصدار حين تحتاج إلى اختبار مسار بروتوكول معيّن.

—http2 و—http3

# طلب HTTP/2 (يتراجع إلى 1.1 إن لم يتوفر)
curl --http2 https://example.com

# طلب HTTP/3 عبر QUIC
curl --http3 https://example.com

يعمل HTTP/3 فوق QUIC ويتطلب TLS 1.3. ولا يعمل إلا إذا كان curl لديك مبنياً بخلفية داعمة لـ HTTP/3 و كان الخادم يعلن عنه عبر ترويسة Alt-Svc. شغّل curl —version للتأكد من ظهور HTTP3 في سطر المزايا؛ وإن لم يظهر، فستُخطئ —http3.

معلومات TLS / ALPN المُسهَبة

تُظهِر -v البروتوكول المُتفاوَض عليه ومصافحة TLS، وهكذا تؤكّد أن إصداراً ما دخل حيّز التنفيذ فعلاً:

curl -v --http2 https://example.com 2>&1 | grep -i "ALPN\|HTTP/2"
# → * ALPN: server accepted h2
# → > GET / HTTP/2

ابحث عن ALPN: server accepted h2 (HTTP/2) أو h3 (HTTP/3) في خرج المصافحة.

8 مطبّات شائعة في curl (وكيفية إصلاحها)

علامات الاقتباس المفردة مقابل المزدوجة. تتيح علامات الاقتباس المزدوجة للصَدفة توسيع $VARS؛ أما المفردة فتمرّر كل شيء حرفياً. استخدم علامات الاقتباس المفردة لأجسام JSON كي لا يُفسَّر $ و!: curl --json '{"price":"$5"}'. واستخدم المزدوجة حين تريد التوسيع: -H "Authorization: Bearer $TOKEN".
-d لا تُرمّز URL. مسافة أو & في قيمة -d تُفسِد الجسم. انتقل إلى —data-urlencode لأي قيمة ليست مُرمَّزة سلفاً.
-X POST الزائدة مع -d. -d تستلزم POST أصلاً. كتابة -X POST -d … غير ضارّة لكنها زائدة؛ والأسوأ، أن -X GET -d … ترسل جسماً مع GET، ما يفاجئ بعض الخوادم. دع رايّة الجسم تضبط الطريقة.
نسيان @ عند القراءة من ملف. -d @body.json تقرأ الملف؛ و-d body.json ترسل النص الحرفي body.json. الفخّ نفسه مع -F “file=@upload.png” مقابل -F “file=upload.png”.
اللجوء إلى -k عند أخطاء الشهادات. تعطّل -k التحقق من TLS وتُخفي مشكلات حقيقية (شهادات منتهية، اسم مضيف خاطئ، وسيط مفقود). أصلِح السبب الجذري: ثبّت الـ CA عبر —cacert ca.pem، أو حدّث مخزن الثقة في نظامك. واحفظ -k لخادم تطوير ذي شهادة موقّعة ذاتياً تتحكم فيه بالكامل.
-s تبتلع الأخطاء. الوضع الصامت يخفي الإخفاقات في السكربتات. استخدم -sS دائماً كي تظل الأخطاء بارزة.
[ ] { } في الروابط تتعرّض للتوسيع (globbing). يعامل curl الرمزين [1-5] و{a,b} كنطاقات/قوائم في الرابط. ورابط يحوي أقواساً حرفية (شائع في معاملات استعلام من نوع المصفوفات مثل arr[]=1) يتعرّض للتشويه. عطّل التوسيع عبر -g: curl -g "https://api.example.com/items?id[]=1&id[]=2".
حالة الأحرف في الترويسات والتكرارات. أسماء ترويسات HTTP غير حساسة لحالة الأحرف، لكن إرسال الترويسة نفسها مرتين يرسل كليهما عادةً — بعض الخوادم تأخذ الأولى، وبعضها الأخيرة، وبعضها يرفضها. إن تجاوزت قيمة افتراضية مثل User-Agent، فاضبطها مرة واحدة عبر -H بدلاً من الاعتماد على الترتيب.

curl مقابل wget مقابل HTTPie — أيّها تستخدم

ثلاثتها تجلب عبر HTTP، لكن كلاً منها مُحسَّن لمهام مختلفة، ويلخّص الجدول التالي قرار curl مقابل wget (إضافةً إلى HTTPie):

المهمة	curl	wget	HTTPie
استدعاء/تنقيح API سريع	ممتاز	محدود	ممتاز
أجسام JSON	جيد (`--json`)	غير مريح	ممتاز (أصلي)
تنزيل/نسخ موقع بشكل تكراري	لا	ممتاز (`-r`)	لا
استئناف + إعادة محاولة التنزيلات الكبيرة	جيد (`-C -`)	ممتاز (مدمج)	لا
البرمجة النصية / CI (أكواد الخروج، `-w`)	ممتاز	جيد	جيد
خرج منسّق وملوّن افتراضياً	لا	لا	ممتاز
مثبَّت مسبقاً في كل مكان تقريباً	نعم	غالباً	نادراً

باختصار: الجأ إلى curl لتنقيح API والسكربتات (فهو في كل مكان و-w لا يُضاهى)، وإلى HTTPie حين تريد بيئة JSON مريحة وقابلة للقراءة على جهازك، وإلى wget لنسخ المواقع أو تنزيل الملفات دفعةً واحدة مع إعادة محاولة تلقائية.

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

فيمَ يُستخدم curl؟

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

كيف أرسل طلب POST عبر curl؟

استخدم -d لبيانات النموذج أو —json لأجل JSON: curl --json '{"name":"alice"}' https://httpbin.org/post. كلتا الرايّتين تضبطان الطريقة إلى POST تلقائياً، فلا تحتاج إلى -X POST.

كيف أضيف ترويسة في curl؟

استخدم -H "Name: value"، وكرّرها لعدة ترويسات: curl -H "Accept: application/json" -H "X-Request-Id: 9f3c1a" https://httpbin.org/headers. ولا حدّ لعدد مرات تمرير -H.

كيف أرسل رمز Bearer عبر curl؟

مرّر ترويسة Authorization: curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/me، أو استخدم الاختصار —oauth2-bearer YOUR_TOKEN. أرسِل الرموز عبر HTTPS فقط، وفك ترميزها عبر محلّل JWT عند التنقيح.

كيف أنزّل ملفاً عبر curl؟

استخدم -O للاحتفاظ باسم الملف البعيد أو -o name لاختيار اسمك الخاص: curl -O https://example.com/archive.zip. أضِف -L لاتباع عمليات إعادة التوجيه و-C - لاستئناف تنزيل مقطوع.

كيف أرى كود حالة HTTP فقط عبر curl؟

تخلّص من الجسم واطبع الكود: curl -s -o /dev/null -w "%{http_code}" https://example.com. هذا هو النمط المعياري لفحوص الصحة في السكربتات.

ما الفرق بين curl وwget؟

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

هل curl متوفر على Windows؟

نعم. يأتي curl مع Windows 10 (بناء 1803+) وWindows 11، ومتاح بوصفه curl في موجّه الأوامر وPowerShell. لاحظ أن PowerShell كان تاريخياً يجعل curl اسماً مستعاراً لـ Invoke-WebRequest، لذا نادِ curl.exe صراحةً إذا تصرّفت الرايّات على نحو غير متوقع.

خلاصة

يكافئ curl قدراً صغيراً من الحفظ: جدول الرايّات في الأعلى يغطي الأغلبية الساحقة مما ستكتبه، والباقي هو معرفة أي الرايّات تستلزم طريقة، وأيها يحتاج إلى علامات اقتباس، وأيها يكذب عليك في السكربتات (والكلام موجّه إليك يا -s المجردة). أبقِ ورقة غش curl هذه مفتوحةً بجوار طرفيّتك. إن كنت تفضّل تجميع الأوامر بشكل تفاعلي، جرّب منشئ أوامر cURL لإنشائها بصرياً.

الخطوات التالية الطبيعية في سير عمل API تبعد نقرةً واحدة. أرسِل الطلب عبر curl، واقرأ ما عاد إليك مع ورقة غش أكواد حالة HTTP، ثم نسّق JSON بإتقان في منسق JSON أو قطّعه عبر ورقة غش jq لمعالجة JSON من سطر الأوامر. ولقائمة الخيارات الكاملة، دليل curl شامل، ومرجع HTTP من MDN يشرح الدلالات وراء كل طريقة وترويسة.