DEV Community

Cover image for كيفية استيراد ملفات HAR في Apidog: حول حركة المرور الملتقطة إلى نقاط نهاية API
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استيراد ملفات HAR في Apidog: حول حركة المرور الملتقطة إلى نقاط نهاية API

لقد شاهدت تطبيقًا يرسل طلبًا من المتصفح، والطلب يعمل وتظهر بياناته في علامة تبويب Network. الآن تريد تحويل هذا الاستدعاء إلى نقطة نهاية موثقة يمكنك حفظها ومحاكاتها واختبارها، بدل إعادة كتابة عنوان URL والرؤوس ونص JSON يدويًا.

جرّب Apidog اليوم

ملف HAR يسد الفجوة بين «حركة المرور التي تراها» و«نقطة نهاية قابلة لإعادة الاستخدام». يسجل المتصفح الطلبات والاستجابات التي ينفذها بالفعل؛ صدّر هذا السجل ثم استورده إلى Apidog لتحويل الاستدعاءات الملتقطة إلى نقاط نهاية داخل مشروعك. وللسياق الأوسع، راجع دليل أدوات التقاط الحزم مع Apidog.

يمكنك تنزيل Apidog مجانًا ومتابعة الخطوات نفسها.

ما هو ملف HAR ولماذا يجب الاحتفاظ به؟

HAR اختصار لـ HTTP Archive. ملف .har هو ملف JSON يسجل تفاعل المتصفح مع موقع ما، بما في ذلك:

  • الطلبات والاستجابات
  • الرؤوس
  • نصوص الطلبات والاستجابات
  • رموز الحالة
  • التوقيتات

ببساطة، يمثل ملف HAR لقطة كاملة لجلسة التصفح. ولأنه JSON، يمكنك نقله أو إرفاقه بتقرير خطأ أو استيراده إلى أداة تقرأ هذا التنسيق.

القيمة العملية هنا أن ملف HAR يسجل ما حدث فعليًا، وليس ما يفترض أن تقوله المواصفات. عند تحويله إلى نقاط نهاية تحصل على:

  • طلب حقيقي: عنوان URL ومعلمات الاستعلام والرؤوس والنص الفعلي.
  • استجابة حقيقية: رمز الحالة والحمولة التي أعادها الخادم.
  • بداية للتوثيق: تحويل واجهة داخلية غير موثقة إلى نقاط نهاية قابلة للتسمية والتنظيم.

استخدم هذا المسار عندما ترث خدمة بلا مواصفات OpenAPI، أو تحتاج إلى إعادة إنتاج خطأ، أو تريد فهم طريقة اتصال تطبيق بواجهته الخلفية.

الخطوة 1: التقاط ملف HAR من أدوات مطور المتصفح

يتم الالتقاط من المتصفح، وليس من Apidog. يستخدم Chrome وEdge أدوات مطور متشابهة، لذلك تكون الخطوات متطابقة تقريبًا.

  1. افتح الصفحة التي تريد تسجيل حركة مرورها.
  2. سجّل الدخول أولًا إذا كانت API تتطلب جلسة مصادقة.
  3. افتح أدوات المطور:
    • F12
    • Ctrl+Shift+I على Windows وLinux
    • Cmd+Opt+I على macOS
  4. افتح علامة تبويب Network.
  5. أعد تحميل الصفحة أو نفّذ الإجراء الذي تريد التقاطه.
  6. انقر بزر الفأرة الأيمن على أي طلب، ثم اختر Save all as HAR with content.
  7. احفظ الملف، مثلًا: 
order-history.har
Enter fullscreen mode Exit fullscreen mode

راجع مرجع Network في أدوات مطور Chrome إذا اختلفت التسمية في واجهتك.

اختر دائمًا with content. بدون هذا الخيار قد تحصل على بيانات الطلبات فقط دون نصوص الاستجابات، وبالتالي لن تتوفر أمثلة استجابة مفيدة بعد الاستيراد.

يمكنك التحقق من الملف بفتحه في محرر نصوص. ستجد بنية JSON تتضمن مصفوفة entries، وكل عنصر يحتوي عادةً على كائني request وresponse.

لا تقلق من كثرة الملفات الثابتة مثل الصور وCSS وJavaScript في ملف HAR؛ ستتمكن من تصفيتها أثناء الاستيراد.

الخطوة 2: استيراد ملف HAR إلى Apidog

بعد حفظ الملف:

  1. افتح مشروعك في Apidog.
  2. انتقل إلى Settings > Import Data > Manual.
  3. اختر تنسيق HAR.
  4. ارفع ملف .har.

قبل تأكيد الاستيراد، اضبط الخيارات التالية.

الخيار 1: التعامل مع BaseURL

قد يحتوي الطلب الملتقط على عنوان كامل مثل:

https://api.shop.example.com/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

يوفر الاستيراد خيارين:

  • Hardcode: يحتفظ بعنوان المضيف داخل مسار كل نقطة نهاية.
  • Remove (Recommended): يزيل المضيف من المسار، ليصبح: 
/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

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

راجع أيضًا إدارة التوثيق وترحيل Swagger إلى Apidog.

الخيار 2: استبعاد الموارد الثابتة

اضبط خيار Static Resource على Exclude.

بهذا تتجاهل الصور وملفات CSS وJavaScript التي يلتقطها المتصفح، وتحتفظ باستدعاءات API المهمة مثل:

GET /api/orders
GET /api/orders/123
POST /api/orders
Enter fullscreen mode Exit fullscreen mode

هذا الإعداد يمنع امتلاء شجرة نقاط النهاية بملفات مثل:

logo.png
app.css
bundle.js
Enter fullscreen mode Exit fullscreen mode

الخيار 3: إنشاء حالة اختبار لكل نقطة نهاية

فعّل Endpoint Case Generation إذا كنت تريد تشغيل واختبار الطلبات المستوردة مباشرة.

ينشئ Apidog حالة اختبار افتراضية لكل نقطة نهاية باستخدام القيم التي التقطها ملف HAR. إذا كان هدفك الحالي هو التوثيق فقط، يمكنك ترك الخيار معطلًا وإضافة الحالات لاحقًا.

بعد تأكيد الاستيراد، ستظهر الاستدعاءات الملتقطة كنقاط نهاية في مشروعك.

مثال لطلب مستورد:

GET /v1/orders/123
Host: api.shop.example.com
Authorization: Bearer <token-from-capture>
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

ومثال للاستجابة التي قد تُحفظ معه:

{
  "id": 123,
  "status": "shipped",
  "total": 48.5,
  "currency": "USD",
  "items": [
    {
      "sku": "TSHIRT-BLK-M",
      "qty": 2,
      "price": 19.25
    }
  ],
  "createdAt": "2026-07-14T09:31:00Z"
}
Enter fullscreen mode Exit fullscreen mode

يمكنك استخدام هذه الاستجابة كأساس للمحاكاة أو لتأكيدات الاختبار.

الخطوة 3: تنظيف نقاط النهاية المستوردة

استيراد HAR هو نقطة بداية، وليس تعريفًا نهائيًا للـ API. خصص عدة دقائق لتنظيف الناتج.

احذف الضوضاء

حتى بعد استبعاد الموارد الثابتة، قد تجد طلبات لا تحتاج إليها، مثل:

  • طلبات التحليلات
  • فحوصات الصحة
  • استدعاءات خدمات خارجية
  • نقاط نهاية تجريبية

احذفها لتبقى شجرة المشروع ممثلة للـ API الفعلية.

أعد التسمية والتنظيم

قد تُسمى نقاط النهاية باسم المسار الملتقط، مثل:

/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

حوّلها إلى اسم واضح مثل:

الحصول على طلب حسب المعرّف
Enter fullscreen mode Exit fullscreen mode

ثم نظمها داخل مجلدات مثل:

Orders
Users
Authentication
Reports
Enter fullscreen mode Exit fullscreen mode

حوّل القيم الثابتة إلى معلمات مسار

قد يستورد Apidog هذا المسار كما هو:

/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

إذا كان 123 معرّف طلب، عدّل المسار إلى:

/v1/orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

بهذا تتحول لقطة واحدة إلى نقطة نهاية قابلة لإعادة الاستخدام لأي طلب.

انقل الأسرار إلى متغيرات البيئة

ملف HAR قد يحتوي على رموز Bearer أو Cookies أو رؤوس مصادقة حقيقية. قبل مشاركة المشروع:

  1. انقل الرموز والأسرار إلى متغيرات البيئة.
  2. احذف بيانات الاعتماد من أمثلة الطلبات.
  3. لا ترفع ملف HAR إلى مستودع عام.
  4. لا ترفقه بتذكرة عامة دون تنظيفه.

تؤكد وثائق Stripe حول المفاتيح المبدأ نفسه: لا تسمح بتسرب المفاتيح الحية إلى الملفات أو المرفقات المشتركة.

تحقق من نصوص الطلبات والاستجابات

إذا وجدت أن الاستجابة أو نص الطلب فارغ، أعد الالتقاط باستخدام:

Save all as HAR with content

ثم أعد الاستيراد.

بعد التنظيف، تعامل مع النقاط المستوردة كأي نقاط نهاية أخرى في Apidog: وثقها، أنشئ محاكاة من الاستجابات، وابنِ اختبارات عليها. يمكنك المتابعة عبر دليل كتابة سيناريو اختبار في Apidog أو دليل إنشاء رمز العميل باستخدام Apidog.

الاختلافات والحدود

لا يوجد مسجل تلقائي لحركة المرور

لا يعمل Apidog كوكيل يسجل حركة المرور مباشرة في الخلفية. المسار المدعوم هو:

  1. التقاط الحركة من أدوات مطور المتصفح.
  2. تصدير ملف HAR.
  3. استيراد الملف إلى Apidog.
  4. تنظيف نقاط النهاية وتشغيل الاختبارات.

أي أن العملية تتضمن التقاطًا يدويًا واستيرادًا سريعًا، وليست تسجيلًا مباشرًا.

إضافة متصفح Apidog ليست أداة التقاط HAR

توجد إضافة متصفح Apidog، لكنها مخصصة لاستخدام أدوات الاختبار والتصحيح في المتصفح، وليست لتسجيل HAR.

التقط HAR من أدوات المطور في المتصفح. وانتبه إلى أن بيئة المتصفح تفرض قيودًا على بعض الرؤوس مثل:

  • Cookie
  • Host
  • Origin
  • Content-Length

كما لا تسمح بإرسال نصوص مع طلبات GET وHEAD. عندما تحتاج إلى تحكم أوسع في الرؤوس أو التشغيل خارج قيود المتصفح، استخدم تطبيق سطح المكتب.

استخدم تنسيقًا آخر عندما تتوفر مواصفة

يدعم المسار Settings > Import Data > Manual تنسيقات متعددة. إذا كانت لديك مواصفة OpenAPI أو Swagger، فاستيرادها عادةً أنظف من ملف HAR لأنها منظمة مسبقًا.

راجع:

استخدم HAR عندما لا توجد مواصفة موثوقة وتكون حركة المرور الملتقطة أفضل مصدر متاح.

أتمتة الاستيراد باستخدام Apidog CLI

لا يلزم أن يكون استيراد HAR خطوة يدوية من الواجهة الرسومية. تتيح واجهة سطر الأوامر لـ Apidog استيراد ملف HAR مباشرة:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

# تحويل ملف HAR ملتقط إلى نقاط نهاية داخل المشروع
apidog import --project <PROJECT_ID> --format har --file ./capture.har
Enter fullscreen mode Exit fullscreen mode

يدعم الخيار --format تنسيقات أخرى، منها:

openapi
postman
wsdl
insomnia
Enter fullscreen mode Exit fullscreen mode

بعد حفظ نقاط النهاية داخل سيناريو اختبار، شغّل السيناريو في CI دون واجهة رسومية:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t <SCENARIO_ID> \
  -e <ENV_ID> \
  -r cli
Enter fullscreen mode Exit fullscreen mode

المعاملات المستخدمة:

  • -t: معرّف سيناريو الاختبار.
  • -e: معرّف البيئة.
  • -r cli: إخراج النتائج إلى الطرفية.

أنشئ السيناريو عبر دليل كتابة سيناريو اختبار في Apidog، ثم أضفه إلى خط الأنابيب باستخدام دليل CI/CD لـ Apidog CLI.

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

ما المتصفحات التي تستطيع تصدير HAR؟

المتصفحات المبنية على Chromium، مثل Chrome وEdge، تدعم تصدير HAR من علامة تبويب Network باستخدام خيار Save all as HAR with content. قد تختلف التسمية في المتصفحات الأخرى، لكن الفكرة نفسها موجودة ضمن أدوات المطور.

لماذا أصبحت قائمة نقاط النهاية كبيرة جدًا؟

غالبًا لأن خيار Static Resource لم يكن مضبوطًا على Exclude. أعد الاستيراد مع استبعاد الموارد الثابتة، ثم احذف أي طلبات متبقية لا تخص API.

هل أختار Hardcode أم Remove لـ BaseURL؟

اختر Remove في أغلب الحالات. سيبقى المسار مستقلًا عن المضيف، وستتحكم بعنوان الخادم من متغيرات البيئة.

اختر Hardcode فقط إذا كنت تريد الاحتفاظ بعنوان URL الكامل داخل كل نقطة نهاية عمدًا.

هل يتضمن HAR رموز المصادقة؟

نعم. يسجل HAR الرؤوس والكوكيز التي كانت فعالة أثناء الجلسة، وقد يتضمن رموز Bearer أو بيانات اعتماد أخرى. تعامل معه كملف حساس، ثم انقل الأسرار إلى متغيرات البيئة بعد الاستيراد.

هل يمكن استيراد HAR من سطر الأوامر؟

نعم:

apidog import --project <id> --format har --file <path>
Enter fullscreen mode Exit fullscreen mode

استخدم CLI للاستيرادات المبرمجة أو مهام CI، واستخدم الواجهة الرسومية عندما تريد ضبط خيارات الاستيراد يدويًا، مثل معالجة BaseURL وتصفية الموارد الثابتة.

خلاصة

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

اتبع هذا التسلسل:

  1. التقط الحركة من Network.
  2. اختر Save all as HAR with content.
  3. استورد الملف عبر Settings > Import Data > Manual.
  4. اختر Remove لـ BaseURL.
  5. اختر Exclude للموارد الثابتة.
  6. أعد تسمية النقاط، وحوّل القيم إلى معلمات، واحذف الأسرار.
  7. استخدم النقاط الناتجة للتوثيق والمحاكاة والاختبار.

هل أنت مستعد لتحويل الالتقاط التالي إلى نقاط نهاية قابلة للاستخدام؟ نزّل Apidog وجربه مجانًا.

Top comments (0)