لقد أنشأت نقطة نهاية تستقبل ملفًا. يقوم المستخدم بتحميل صورة ملف شخصي إلى POST /avatars، أو يدفع تطبيقك ملف PDF موقّعًا إلى POST /documents. المسار يعمل في ذهنك. الآن تحتاج إلى إثبات أنه يعمل عبر HTTP: اختر ملفًا حقيقيًا، أرفقه بحقل نموذج، أرسل الطلب، وتحقق من الاستجابة.
هنا تصبح العديد من أدوات واجهة برمجة التطبيقات معقدة. تستخدم عمليات تحميل الملفات multipart/form-data، وليس JSON، لذلك لا يمكنك لصق نص وطلب إرساله. تحتاج إلى منشئ طلبات يفهم حقول الملفات، ومُشغّل اختبار يمكنه العثور على الملف عندما يتم تشغيل الاختبار لاحقًا. Apidog يتعامل مع كليهما، ويشرح هذا الدليل المسار بأكمله: إرسال تحميل واحد، إرسال ملف جنبًا إلى جنب مع JSON، تأكيد الاستجابة، ثم الجزء الصادق الذي لا يحذرك أحد بشأنه، وهو ما يحدث عندما تعمل نفس خطوة التحميل هذه بدون واجهة رسومية في Runner أو CLI ولا تستطيع العثور على الملف. إذا كنت تريد الخلفية عن التنسيق نفسه أولاً، فإن الدليل التمهيدي حول تحميل الملفات في واجهات برمجة التطبيقات يغطي كيفية هيكلة طلبات multipart. مرجع MDN حول FormData هو رفيق جيد لجانب المتصفح.
ما هو multipart/form-data ولماذا تحتاجه عمليات التحميل
يمكن أن يتخذ نص طلب واجهة برمجة التطبيقات عدة أشكال. في قسم Body (النص) الخاص بطلبات Apidog، يمكنك اختيار form-data، أو x-www-form-urlencoded، أو JSON، أو XML، أو raw (خام)، أو binary (ثنائي). في معظم الأوقات، تلجأ إلى JSON. عمليات تحميل الملفات هي الاستثناء.
يتوافق نوع النص form-data مع رأس Content-Type: multipart/form-data. إنه التنسيق المصمم لتحميل الملفات جنبًا إلى جنب مع البيانات الأخرى. بدلاً من كتلة واحدة، يتم تقسيم النص إلى أجزاء، لكل جزء اسمه ومحتواه الخاص. يمكن أن يكون جزء واحد عبارة عن سلسلة نصية بسيطة مثل تعليق، ويمكن أن يكون جزء آخر عبارة عن بايتات خام لصورة. لهذا السبب يمكن أن ينتقل تحميل الصورة وبياناتها الوصفية في نفس الطلب.
القريب هو x-www-form-urlencoded. يبدو مشابهًا في المحرر، أزواج مفتاح-قيمة تُرسل في النص، ولكنه مخصص للنماذج البسيطة بدون ملفات. إذا كانت نقطة النهاية الخاصة بك تستقبل ملفًا، فإن form-data هو ما تريده. استخدم x-www-form-urlencoded فقط عندما يكون كل حقل قيمة بسيطة قصيرة ولا توجد بايتات متضمنة.
في form-data، يعرض Apidog كل معلمة كزوج مفتاح-قيمة، وتحمل كل معلمة نوعًا: نص، عدد صحيح، ملف، وما إلى ذلك. هذا النوع لكل معلمة هو كل الحيلة. عيّن حقلًا إلى file وسيتعامل Apidog مع قيمته كملف لإرفاقه بدلاً من نص لإرساله.
إرسال تحميل ملف واحد وتأكيد الاستجابة
لنفترض أنك تختبر POST /avatars. يستقبل حقلًا واحدًا، avatar، يحتوي على صورة، ويعيد JSON مع عنوان URL المخزن. إليك شرح الخطوات.
1. افتح قسم Body (النص) واختر form-data. في نقطة النهاية الخاصة بك أو طلب جديد، اضبط الطريقة على POST وعنوان URL إلى مسار الصور الرمزية الخاص بك. افتح علامة التبويب Body واختر نوع النص form-data. يضبط Apidog Content-Type: multipart/form-data لك تلقائيًا.
2. أضف معلمة الملف واضبط نوعها على file. أضف معلمة بالمفتاح avatar. بجانب المفتاح، استخدم محدد النوع لتغيير نوعه من string إلى file. تتحول خلية القيمة إلى منتقي ملفات بدلاً من مربع نص.
3. انقر على Upload (تحميل) واختر ملفًا محليًا. انقر على Upload في صف avatar واختر صورة من جهازك، على سبيل المثال jane-profile.png. يسجل Apidog المسار إلى هذا الملف.
4. أرسل الطلب. اضغط على إرسال. يقرأ Apidog الملف من المسار المحلي المخزن، وينشئ نص multipart، ويرسله. من المهم معرفة ذلك مسبقًا: يرسل Apidog الملف في الطلب ولكنه لا يخزنه في السحابة. إنه يحفظ المسار المحلي فقط، وليس البايتات. هذه التفاصيل مهمة لاحقًا، لذا احتفظ بها في ذهنك.
طلب ناجح يعود بشيء مثل هذا:
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. تأكيد الاستجابة. الطلب الذي يعيد 200 ليس اختبارًا ناجحًا بحد ذاته. أضف تأكيدات ليكون التحقق حقيقيًا. في Apidog، يمكنك إضافة هذه كتأكيدات بعد الطلب على نقطة النهاية أو خطوة السيناريو. بشكل مبسط، تريد تأكيد الحالة وأن النص يحمل عنوان URL صالحًا:
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
تتوافق هذه مباشرة مع واجهة مستخدم تأكيدات Apidog: تأكيد واحد على رمز الحالة، وآخر على وجود $.avatarUrl في JSONPath، وآخر على $.contentType. إذا كنت جديدًا على التأكيدات، فإن دليل تأكيدات واجهة برمجة التطبيقات يوضح المجموعة الكاملة من العمليات وكيف يستهدف JSONPath حقلًا.
لإجراء فحص واقعي سريع خارج الأداة، تبدو عملية التحميل نفسها في curl كالتالي:
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
العلامة -F هي طريقة curl لبناء جزء multipart، وعلامة @ تخبره بقراءة محتويات الملف. تقوم معلمة ملف form-data في Apidog بنفس الشيء باستخدام منتقي بدلاً من علامة.
إرسال ملف و JSON معًا
نادراً ما تستقبل نقاط النهاية الحقيقية ملفًا خامًا. قد يحتاج POST /documents إلى الملف بالإضافة إلى البيانات الوصفية: عنوان، فئة، وربما مصفوفة علامات. لديك طريقتان واضحتان للقيام بذلك في طلب multipart واحد.
الحالة البسيطة هي الحقول القياسية (scalar fields). أضف المزيد من معلمات form-data بجانب حقل الملف الخاص بك واتركها كـ string أو integer. سلسلة title، وسلسلة category، وملف file تم تعيين نوعه إلى file. تسافر الثلاثة جميعها في نفس الطلب.
عندما تكون البيانات الوصفية مهيكلة، مثل كائن متداخل أو مصفوفة، فإنك ترسلها كـ JSON داخل جزء نصي. أضف معلمة form-data باسم metadata، وحافظ على نوعها كـ string، والصق JSON مباشرة في القيمة:
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
إذًا، يتكون الطلب من جزأين: file (من نوع file) يحمل q3-invoice.pdf، وmetadata (من نوع string) يحمل JSON هذا. يقرأ الخادم الملف من جزء واحد ويحلل JSON من الجزء الآخر. العديد من واجهات برمجة التطبيقات العامة تستقبل التحميلات بهذه الطريقة تمامًا؛ تعد وثائق تحميل ملفات Stripe مثالًا جيدًا لنقطة نهاية multipart حقيقية تقرن جزء ملف بحقول عادية. هذا النمط شائع بما يكفي ليستخدمه مستخدمو Postman أيضًا؛ إذا كنت تقوم بالترحيل، فإن الشرح التفصيلي حول تحميل ملف وبيانات JSON في Postman يتوافق بشكل واضح مع حقول form-data في Apidog.
هل تحتاج إلى إرفاق أكثر من ملف واحد؟ أضف معلمة أخرى من نوع file. طلب POST /documents الذي يقبل ملفًا رئيسيًا وصورة مصغرة يحصل على صفين للملفات، file وthumbnail، ولكل منهما زر Upload خاص به. لا يوجد وضع خاص للملفات المتعددة؛ ما عليك سوى إضافة معلمات من نوع الملف حتى تغطي كل جزء تتوقعه نقطة النهاية.
تحويل الطلب إلى سيناريو اختبار قابل للتكرار
إرسال واحد يثبت أن نقطة النهاية تعمل لمرة واحدة. للتصدي للانحدارات، تريد أن يكون التحميل ضمن سيناريو اختبار محفوظ يعمل عند الطلب أو بجدول زمني. ربط الخطوات: تحميل الصورة الرمزية، التقاط id المُعاد، ثم استدعاء GET /users/{id} وتأكيد استمرارية عنوان URL للصورة الرمزية.
قم ببناء هذا بنفس الطريقة التي بنيت بها الطلب الفردي، ثم احفظه كخطوة في سيناريو. يغطي دليل كيفية كتابة سيناريو اختبار باستخدام Apidog ربط الخطوات وتمرير القيم بينها. بمجرد أن يصبح التحميل جزءًا من سيناريو، يمكنك تشغيله مقابل بيئة الاختبار في كل نشر، أو إضافة فروع شرطية باستخدام المنطق الشرطي في سيناريوهات اختبار API، أو ضبطه على مؤقت باستخدام اختبارات API المجدولة.
كل ما سبق يعمل بشكل جيد على جهازك، لأن جهازك يحتوي على الملف. هذا الافتراض هو بالضبط ما سيتعطل لاحقًا.
المطب الخفي: التحميلات التي تعمل في مكان آخر
هذا هو الجزء الذي تخفيه المسارات السعيدة (happy paths). يخزن Apidog مسار الملف، وليس الملف نفسه. على جهاز الكمبيوتر المحمول الخاص بك، هذا غير مرئي، لأن المسار يشير إلى ملف حقيقي في كل مرة. في اللحظة التي تعمل فيها نفس الخطوة على جهاز مختلف، يشير المسار إلى لا شيء.
ستواجه هذا في مكانين.
التعاون الفريقي. عندما يفتح زميل في الفريق طلب POST /avatars الخاص بك، فإنه يرى معلمة الملف والمسار الذي اخترته، على سبيل المثال /Users/jane/pics/jane-profile.png. يمكنهم رؤية الطلب، لكن لا يمكنهم إرساله، لأن هذا الملف موجود على قرصك، وليس على قرصهم. المسار محلي للجهاز الذي اختاره.
تشغيل Runner و CLI. هذا هو الأمر الذي يسبب المشاكل في الأتمتة. سيناريو التحميل الخاص بك ينجح محليًا، تقوم بجدولته في Runner أو تشغيله من CLI، وتفشل خطوة تحميل الملف. لا يوجد خطأ في تأكيداتك. لا يستطيع Runner العثور على ملف في المسار الذي حفظه جهاز الكمبيوتر المحمول الخاص بك، لأن هذا المسار غير موجود على مضيف Runner.
يتبع الحل السبب. يجب أن يكون الملف موجودًا على الجهاز الذي يقوم بالإرسال، ويجب أن يشير مسار الخطوة إليه هناك.
بالنسبة لـ Runner: يقرأ Runner الملفات من دليل مضيف مُثبت في وحدة التخزين الخاصة به. تقوم بتعيين هذا التثبيت عند نشر Runner، باستخدام العلامة -v. انسخ ملف التحميل الخاص بك إلى دليل المضيف المثبت هذا. ثم افتح تفاصيل خطوة تحميل الملف في السيناريو، وانقر على زر Batch Edit في الزاوية العلوية اليمنى، واستبدل قيمة حقل الملف بالمسار داخل دليل Runner، على سبيل المثال:
/opt/runner/jane-profile.png
بالنسبة لـ CLI: نفس الشكل. ضع الملف على جهاز CLI، ثم استخدم Batch Edit في الخطوة لتوجيه المسار إلى موقعه هناك، على سبيل المثال:
/opt/apidog/runner/jane-profile.png
أنظف من التشفير الثابت: استخدم متغيرًا. بدلاً من تثبيت مسار حرفي في الخطوة، استبدل القيمة بمتغير واضبط قيمة المتغير على مسار الملف الفعلي لكل بيئة. بعد ذلك، يتم تشغيل نفس السيناريو على جهاز الكمبيوتر المحمول الخاص بك، وRunner، و CI دون تحرير الخطوة في كل مرة. توجه المتغير إلى /Users/jane/pics/jane-profile.png محليًا و/opt/runner/jane-profile.png على Runner، والخطوة نفسها لا تتغير أبدًا.
شرط مسبق واحد يستحق الذكر بوضوح: يصل Runner فقط إلى ملفات المضيف الموجودة تحت الدليل الذي قمت بتثبيته باستخدام -v في وقت النشر. إذا لم يكن ملفك تحت هذا التثبيت، فلن يعثر عليه أي مسار. هذه تفصيلة لإعداد النشر، وليست حدًا للخطة. توثيقات Apidog حول طلبات تحميل الملفات توضح خطوات التثبيت والتحرير بالجملة إذا كنت تريد الإصدار الرسمي.
أتمتة سير العمل باستخدام Apidog CLI
بمجرد حفظ سيناريو التحميل الخاص بك، يمكنك تشغيله بدون واجهة رسومية (headless) في CI. قم بتثبيت CLI والمصادقة:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
ثم قم بتشغيل السيناريو المحفوظ بواسطة المعرف، موجهًا إياه إلى بيئة معينة:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
هنا، -t هو معرف سيناريو الاختبار، و-e هو معرف البيئة، و-r هو أداة الإبلاغ (استخدم cli، أو html، أو junit، مفصولة بفاصلة لعدة خيارات). يقوم CLI بتشغيل السيناريوهات المحفوظة الخاصة بك من المشروع السحابي ويبلغ عن النجاح/الفشل باستخدام رموز الخروج، وهو ما يسمح له بالتحكم في خط الأنابيب (pipeline). توجد تفاصيل الإعداد في دليل تثبيت Apidog CLI.
تحذير صريح واحد، وهو نفس التحذير من القسم الأخير: السيناريو الذي يتضمن خطوة تحميل ملف يحتاج إلى وجود الملف على جهاز CLI، ويجب أن يشير مسار الخطوة إليه هناك. ضع الملف على Runner، ثم قم بـ Batch Edit للمسار (أو استخدم متغيرًا) قبل التشغيل. تجاهل ذلك وستفشل خطوة التحميل في العثور على الملف على الرغم من أن بقية السيناريو بخير. لإعداد CI أكثر اكتمالاً، بما في ذلك تمرير المدخلات لكل صف، راجع الاختبار المدفوع بالبيانات باستخدام Apidog CLI.
الأسئلة الشائعة
لماذا لا يستطيع زميلي في الفريق إرسال طلب تحميل الملف الخاص بي؟ يخزن Apidog مسار الملف المحلي، وليس الملف نفسه، ولا يقوم أبدًا بتحميل الملف إلى السحابة. يرى زميلك في الفريق الطلب والمسار الذي اخترته، لكن هذا المسار يشير إلى ملف على قرصك، وليس على قرصهم. اطلب منهم وضع نسخة من الملف على جهازهم وتوجيه الحقل إلى مسارهم الخاص. تفسر الآلية نفسها سبب حاجة الاختبارات المجدولة ومهام Runner إلى أن يكون الملف معدًا حيث يتم تشغيلها.
كيف أرسل JSON مع ملف في نفس الطلب؟ حافظ على نوع النص كـ form-data. أضف حقل الملف الخاص بك من نوع file، ثم أضف معلمة أخرى من نوع string والصق JSON في قيمتها. يتلقى الخادم الجزأين في طلب multipart واحد: الملف في جزء واحد، وسلسلة JSON في جزء آخر. هذه هي الطريقة القياسية لإرفاق البيانات الوصفية بتحميل.
ما المسار الذي يجب أن أستخدمه لملف في Runner؟ استخدم مسارًا داخل دليل المضيف الذي قمت بتثبيته في وحدة تخزين Runner باستخدام العلامة -v في وقت النشر، على سبيل المثال /opt/runner/yourfile.jpg. انسخ الملف إلى هذا الدليل المثبت، ثم افتح الخطوة، وانقر على Batch Edit، واضبط قيمة الحقل على هذا المسار. المعادل في CLI يبدو كـ /opt/apidog/runner/yourfile.jpg.
هل هناك حد لحجم الملف أو قائمة بأنواع الملفات المسموح بها؟ يتعلق سلوك التحميل في Apidog بكيفية بناء الطلب ومن أين يتم قراءة الملف. تأتي حدودك الفعلية على الحجم والنوع من واجهة برمجة التطبيقات التي تختبرها، لذا تحقق من قواعد التحقق الخاصة بالخادم الخاص بك واكتب تأكيدات ضد الاستجابات التي يعيدها للملفات ذات الحجم الزائد أو المرفوضة.
هل يجب أن أستخدم form-data أم x-www-form-urlencoded للتحميلات؟ استخدم form-data. إنه يتوافق مع multipart/form-data ومصمم لنقل الملفات. x-www-form-urlencoded مخصص للنماذج البسيطة التي تحتوي على حقول قياسية قصيرة بدون ملف، لذلك لن ينقل صورتك أو ملف PDF الخاص بك.
خاتمة
يتلخص اختبار تحميل الملفات في أمرين: بناء طلب multipart بشكل صحيح، والتأكد من أن الملف يمكن الوصول إليه أينما يتم تشغيل الاختبار. في Apidog، تقوم بتعيين Body إلى form-data، وتغيير نوع حقلك إلى file، والنقر على Upload، وإضافة أي JSON كجزء نصي، ثم الإرسال والتأكيد. عندما تنقل نفس السيناريو إلى Runner أو CLI، قم بإعداد الملف على هذا الجهاز وأعد توجيه المسار باستخدام Batch Edit أو متغير، وسيعمل التشغيل التلقائي مثل تشغيلك المحلي.
هل تريد تجربته على نقطة النهاية الخاصة بك؟ حمل Apidog، وجه طلب form-data إلى مسار التحميل الخاص بك، وشاهد الاستجابة تعود. البدء مجاني، ولا يتطلب بطاقة ائتمان.