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

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

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

يمكنك تنزيل Apidog مجانًا والمتابعة على نفس الشاشات.

ما هو ملف HAR ولماذا تستحق حركة المرور الملتقطة الاحتفاظ بها

يرمز HAR إلى HTTP Archive. وفقًا لوثائق Apidog، ملف .har هو "ملف بتنسيق JSON يستخدم لتسجيل تفاعل متصفح الويب مع موقع ما. يسجل طلبات الويب، والاستجابات، والرؤوس، والبيانات الأخرى المرسلة بين المتصفح والخادم."

بوضوح: ملف HAR هو نسخة كاملة من جلسة تصفح. كل طلب GET، كل طلب POST، رؤوس الطلبات، نصوص الاستجابات، والتوقيتات. لأنه بتنسيق JSON، فمن السهل نقله. يمكنك إرساله بالبريد الإلكتروني، أو إرفاقه بتقرير عن خطأ، أو إدخاله إلى أداة تعرف كيفية قراءته.

هذا الجزء الأخير هو سبب أهميته هنا. الجلسة الملتقطة هي سجل لكيفية تصرف واجهة برمجة التطبيقات (API) بالفعل في الواقع، وليس كيف ينص عليها المواصفات. عندما تحول هذا السجل إلى نقاط نهاية، تحصل على بعض الأشياء مجانًا:

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

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

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

يحدث الالتقاط في متصفحك، وليس في Apidog. يستخدم كل من Chrome و Edge نفس أدوات المطور (DevTools)، لذا فإن الخطوات متطابقة. على سبيل المثال، إذا كنت تريد التقاط حركة المرور وراء صفحة سجل الطلبات.

1. افتح الصفحة التي تريد تسجيلها. قم بتسجيل الدخول أولاً إذا كانت واجهة برمجة التطبيقات (API) تتطلب جلسة، حيث سيحمل ملف HAR تلك الطلبات أيضًا.
2. افتح أدوات المطور (Developer Tools). اضغط F12، أو Ctrl+Shift+I على Windows و Linux، أو Cmd+Opt+I على Mac.
3. انتقل إلى علامة التبويب الشبكة (Network). هذا هو المكان الذي تسرد فيه أدوات المطور كل طلب تقوم به الصفحة.
4. أعد تحميل الصفحة، أو انقر عبر الإجراءات التي تريد التقاط حركتها. يؤدي تحميل عرض سجل الطلبات إلى إطلاق الاستدعاءات إلى /api/orders و /api/orders/{id} وأي شيء آخر تحتاجه الصفحة. يظهر كل منها كصف.
5. انقر بزر الماوس الأيمن على أي صف طلب واختر حفظ الكل كـ HAR مع المحتوى (Save all as HAR with content). اختر موقعًا واحفظ الملف، على سبيل المثال order-history.har. إذا كانت صياغة القائمة مربكة لك، فإن مرجع شبكة أدوات مطور Chrome يوثق نفس سير عمل الالتقاط والتصدير.

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

فحص سريع قبل مغادرة المتصفح: إذا فتحت ملف .har في محرر نصوص، فستجده بتنسيق JSON قابل للقراءة. سترى مصفوفة entries حيث يحتوي كل إدخال على كائن request وكائن response. هذا هو الهيكل الذي يقرأه Apidog.

شيء واحد يجب أخذه في الاعتبار. تحميل الصفحة يجلب أكثر من مجرد استدعاءات API. كما يقوم بجلب الصور وأوراق الأنماط (stylesheets) والسكريبتات، وكل واحد منها يهبط في ملف HAR. لا يتعين عليك تصفيتها في المتصفح؛ يمنحك Apidog خيارًا لإسقاطها عند الاستيراد، وهو ما سنتناوله لاحقًا.

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

بعد حفظ الملف، انتقل إلى Apidog. موجود المستورد في مكان واحد.

1. افتح مشروعك وانتقل إلى الإعدادات (Settings) > استيراد البيانات (Import Data) > يدوي (Manual).
2. حدد HAR كتنسيق.
3. قم بتحميل ملف .har الخاص بك، على سبيل المثال order-history.har الذي حفظته للتو.

قبل التأكيد، يعرض Apidog ثلاثة خيارات استيراد. تحدد هذه الخيارات مدى نظافة النتيجة، لذا يستحق الأمر فهم كل منها بدلاً من النقر للمتابعة.

الخيار 1: كيفية التعامل مع عنوان URL الأساسي (BaseURL)

كل طلب ملتقط يحتوي على عنوان URL كامل، مثل https://api.shop.example.com/v1/orders/123. لديك خياران لما تفعله بجزء المضيف (host):

• تضمين (Hardcode): يحافظ على عنوان URL الأساسي (BaseURL) داخل مسار كل نقطة نهاية. تحمل كل نقطة نهاية البادئة الكاملة https://api.shop.example.com.
• إزالة (موصى به) (Remove (Recommended)): يزيل عنوان URL الأساسي بحيث يصبح مسار نقطة النهاية /v1/orders/123. ثم تتم إدارة المضيف عالميًا عبر متغيرات البيئة.

اختر خيار الإزالة (Remove) ما لم يكن لديك سبب آخر. إنه الإعداد الموصى به لسبب وجيه: عندما يكون عنوان URL الأساسي موجودًا في متغير بيئة، يمكنك توجيه نفس نقاط النهاية إلى بيئة الإنتاج أو التطوير أو خادم محلي عن طريق تبديل البيئات، دون الحاجة إلى تعديل نقاط النهاية نفسها. يؤدي التضمين الثابت (Hardcoding) إلى ربط كل نقطة نهاية بالمضيف الذي قمت بالالتقاط منه، وهو ما يصبح مزعجًا لحظة حاجتك للاختبار مقابل خادم مختلف.

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

هذا هو المفتاح الذي ينقذك من قائمة نقاط النهاية المزدحمة. يخبر خيار الموارد الثابتة (Static Resource)، عند تعيينه على استبعاد (Exclude)، Apidog بتخطي الصور وملفات CSS وجافا سكريبت الملتقطة. يمكن أن ينتج تحميل صفحة واحدة العشرات من هذه، ولا أحد منها يمثل نقاط نهاية API تريد توثيقها.

قم بتشغيل الاستبعاد (Exclude) في كل عملية استيراد تقريبًا. ما يتبقى بعد التصفية هو حركة مرور API الفعلية: استدعاءات JSON إلى /api/orders وما شابهها، وليس الطلب الخاص بـ logo.png.

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

الخيار الثالث هو إنشاء حالة نقطة نهاية (Endpoint Case Generation). قم بتشغيله (ON) وسيُنشئ Apidog حالة اختبار افتراضية لكل نقطة نهاية أثناء استيرادها. حالة الاختبار هي استدعاء محفوظ وقابل للتشغيل لنقطة النهاية مع القيم الملتقطة التي تم ملؤها بالفعل.

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

تأكيد الاستيراد. يقرأ Apidog ملف HAR، ويطبق خياراتك، ويحول تفاعلات المتصفح الملتقطة إلى نقاط نهاية API داخل مشروعك. افتح شجرة نقاط النهاية وسترى أنها مجمعة وجاهزة.

إليك تقريبًا كيف تبدو نقطة نهاية مستوردة بمجرد وصولها، باستخدام استدعاء الطلب كمثال:

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

والاستجابة الملتقطة التي يخزنها Apidog بجانبها:

{
  "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"
}

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

الخطوة 3: تنظيف نقاط النهاية المُنشأة

استيراد ملف HAR هو تمريرة أولية سريعة، وليس تعريفًا نهائيًا لواجهة برمجة التطبيقات (API). حركة المرور الملتقطة فوضوية بطبيعتها، لذا خصص بضع دقائق لترتيب النتيجة.

تخلص من الضوضاء. حتى مع تعيين المورد الثابت (Static Resource) على استبعاد (Exclude)، قد تجد إشعارات تحليلات، أو فحوصات صحة، أو استدعاءات من جهات خارجية لا تهتم بها. احذف نقاط النهاية التي لن تستخدمها بحيث تعكس الشجرة واجهة برمجة التطبيقات الفعلية الخاصة بك.

إعادة التسمية والتجميع. تُسمى نقاط النهاية الملتقطة بناءً على مساراتها، وهو أمر وظيفي ولكنه مسطح. امنحها أسماء واضحة ("الحصول على الطلب حسب المعرف" بدلاً من /v1/orders/123) ونظمها في مجلدات تتوافق مع بنية واجهة برمجة التطبيقات الخاصة بك.

إصلاح معلمات المسار. يتم استيراد التقاط لـ /v1/orders/123 كمسار حرفي. إذا كان 123 هو معرف طلب بالفعل، فقم بتعديل نقطة النهاية بحيث يصبح هذا الجزء معلمة مسار {orderId}. هذا التغيير الواحد يحول استدعاءًا واحدًا ملتقطًا إلى نقطة نهاية قابلة لإعادة الاستخدام تعمل لأي طلب.

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

التحقق من نصوص الطلبات/الاستجابات. إذا كان النص فارغًا حيث كنت تتوقع بيانات، فمن المحتمل أنك قمت بالتصدير بدون خيار "مع المحتوى (with content)". أعد الالتقاط باستخدام حفظ الكل كـ HAR مع المحتوى (Save all as HAR with content) وأعد الاستيراد.

بمجرد أن تصبح نقاط النهاية نظيفة، فإنها تتصرف مثل أي نقطة نهاية أخرى في Apidog. يمكنك توثيقها، وإنشاء محاكاة من كل استجابة، وبناء الاختبارات. يستكمل دليل كتابة سيناريو اختبار في Apidog من هنا بشكل طبيعي، وإذا كنت تريد رمز عميل (client code) مُحدد النوع من نقاط النهاية هذه، فراجع كيفية إنشاء رمز العميل باستخدام Apidog.

الاختلافات والحدود الصادقة

هناك بعض الحالات التي تظهر غالبًا بما يكفي لتوضيحها.

لا يوجد مسجل تلقائي بعد

قد تتوقع أن يعمل Apidog في الخلفية ويسجل حركة المرور مباشرة، بالطريقة التي يعمل بها الوكيل (proxy). لكنه لا يفعل ذلك، ومن الجدير أن نكون صريحين بشأن ذلك. تشير الوثائق بوضوح: "لا يدعم Apidog حاليًا وظيفة تسجيل نقاط النهاية التلقائية، ولكن هناك خطط لدعمها في المستقبل."

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

إضافة متصفح Apidog هي أداة مختلفة

توجد إضافة متصفح Apidog، ومن السهل افتراض أنها تلتقط حركة مرور HAR. لكنها لا تفعل ذلك. تسمح لك الإضافة باستخدام أدوات اختبار واجهة برمجة التطبيقات (API) وتصحيح الأخطاء في Apidog مباشرة في المتصفح دون فتح تطبيق سطح المكتب. إنها تتعلق بتشغيل الطلبات، وليس تسجيلها.

يأتي التقاط HAR من أدوات مطور متصفحك الخاصة، نقطة. إذا كنت تستخدم الإضافة للاختبار، فاعلم أن المتصفح يفرض عليها قيودًا: فهو يحظر رؤوسًا معينة مثل Cookie و Host و Origin و Content-Length، ولن يرسل نصوصًا في طلبات GET أو HEAD، ولا يمكنه الوصول إلى التعليمات البرمجية المحلية أو قاعدة بيانات خلف جهازك. لالتقاط حركة المرور للاستيراد، التزم بأدوات المطور وتصدير HAR. لتصحيح الأخطاء الأكثر تعقيدًا التي تتطلب تحكمًا كاملاً في الرؤوس، لا يفرض تطبيق Apidog لسطح المكتب مثل هذه القيود المفروضة من المتصفح.

تنسيقات أخرى يتم استيرادها بنفس الطريقة

HAR هو أحد التنسيقات العديدة التي تقبلها شاشة الإعدادات (Settings) > استيراد البيانات (Import Data) > يدوي (Manual). إذا كان لديك بالفعل ملف OpenAPI أو Swagger، فإن استيراده يمنحك نتيجة أنظف من الالتقاط، لأن المواصفة منظمة عن قصد. يغطي دليلنا حول ترحيل توثيق واجهة برمجة تطبيقات Swagger إلى Apidog هذا المسار، وإذا كنت قادمًا من Postman، فإن دليل ترحيل بيئات ومجموعات Postman يغطي ذلك أيضًا. استخدم HAR عندما لا توجد مواصفات حقيقية وتكون حركة المرور الملتقطة هي أفضل سجل لديك.

أتمتة سير العمل باستخدام واجهة سطر الأوامر (CLI) لـ Apidog

لا يجب أن يكون استيراد ملف HAR خطوة رسومية (GUI). تحتوي واجهة سطر الأوامر (CLI) لـ Apidog على أمر import يقرأ ملف HAR مباشرة، وهو ما تحتاجه عندما يحدث الالتقاط على خادم، أو عندما تكتب نصًا برمجيًا للاستيراد في مسار عمل، أو عندما تسمح لوكيل ترميز الذكاء الاصطناعي بتحويل الالتقاط إلى نقاط نهاية:

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

# Turn a captured HAR into endpoints in your project
apidog import --project <PROJECT_ID> --format har --file ./capture.har

يقبل العلم --format أيضًا openapi و postman و wsdl و insomnia والمزيد، لذا يغطي أمر واحد معظم مصادر الاستيراد. بمجرد وجود نقاط النهاية وحفظها في سيناريو اختبار، قم بتشغيل هذا السيناريو بدون واجهة رسومية في CI:

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

هنا -t هو معرف سيناريو الاختبار المحفوظ، و -e هو معرف البيئة (نفس متغيرات البيئة التي تحتوي على عنوان URL الأساسي الخاص بك)، و -r يختار المُبلغ، cli لإخراج وحدة التحكم. قم ببناء السيناريو باستخدام دليل كتابة سيناريو اختبار في Apidog، ثم اربط كلا الأمرين في مسار عملك باستخدام دليل CI/CD لـ Apidog CLI.

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

ما هي المتصفحات التي يمكنها تصدير ملف HAR؟

أي متصفح يعتمد على Chromium وبه أدوات المطور (DevTools) يفعل ذلك بنفس الطريقة، لذا يستخدم كل من Chrome و Edge علامة تبويب الشبكة (Network) وخيار القائمة حفظ الكل كـ HAR مع المحتوى (Save all as HAR with content). تغطي وثائق Apidog مسار Chrome و Edge على وجه التحديد. تمتلك المتصفحات الأخرى قوائم التصدير الخاصة بها، ولكن قد يختلف المسمى، لذا طابق صياغة أدوات مطور متصفحك.

قائمة نقاط النهاية المستوردة لدي ضخمة. ما الخطأ الذي حدث؟

من المرجح أنك تركت خيار المورد الثابت (Static Resource) مضبوطًا على تضمين كل شيء. يجلب تحميل الصفحة الصور وملفات CSS والسكريبتات، وجميعها تهبط في ملف HAR. أعد استيراد الملف مع تعيين خيار المورد الثابت (Static Resource) على استبعاد (Exclude)، وستضيق القائمة لتشمل استدعاءات API الفعلية. يمكنك أيضًا حذف العناصر المتبقية يدويًا بعد ذلك.

هل يجب أن أختار "تضمين" (Hardcode) أم "إزالة" (Remove) لعنوان URL الأساسي (BaseURL)؟

اختر إزالة (موصى به) (Remove (Recommended)) في كل حالة تقريبًا. فهو يسحب المضيف من مسار كل نقطة نهاية بحيث تديره عالميًا عبر متغير بيئة، مما يتيح لك التبديل بين بيئات الإنتاج والتطوير والمحلية دون تعديل نقاط النهاية. هذا الإعداد نفسه هو ما يقرأه سيناريو اختبار في Apidog عند تشغيله. اختر تضمين (Hardcode) فقط عندما تريد بشكل خاص تضمين عنوان URL الكامل في كل مسار.

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

نعم، وهذا هو المحك. يسجل ملف HAR الرؤوس الحقيقية المرسلة أثناء الجلسة، لذلك فإن أي رمز حامل (bearer token) أو ملف تعريف ارتباط (cookie) كان نشطًا موجود في الملف. تعامل مع ملف HAR كسر: لا تلصقه في مشكلة عامة، وبعد الاستيراد، انقل بيانات الاعتماد إلى متغيرات البيئة وامسحها من الأمثلة المحفوظة قبل مشاركة المشروع.

هل يمكنني تخطي الواجهة الرسومية (GUI) واستيراد ملف HAR من سطر الأوامر؟

نعم. يقوم الأمر apidog import --project <id> --format har --file <path> الخاص بواجهة سطر الأوامر (CLI) لـ Apidog بإدخال ملف HAR إلى مشروعك دون فتح التطبيق، وهو ما تريده عندما يحدث الالتقاط على خادم أو داخل مهمة CI. لا تزال الواجهة الرسومية توفر لك خيارات الاستيراد التفاعلية (معالجة BaseURL، تصفية الموارد الثابتة) لالتقاط لمرة واحدة، لذا اختر ما يناسبك: واجهة سطر الأوامر للاستيرادات المبرمجة أو التي يديرها الوكيل، والواجهة الرسومية عندما تريد ضبط الاستيراد يدويًا. بعد الاستيراد، يعيد apidog run تشغيل سيناريوهات الاختبار التي تبنيها من نقاط النهاية هذه.

خلاصة

ملف HAR هو الجسر بين حركة المرور التي يمكنك رؤيتها ونقاط النهاية التي يمكنك إعادة استخدامها. التقط الجلسة في أدوات مطور متصفحك باستخدام حفظ الكل كـ HAR مع المحتوى (Save all as HAR with content)، واستوردها عبر الإعدادات (Settings) > استيراد البيانات (Import Data) > يدوي (Manual) مع اختيار إزالة (Remove) لعنوان URL الأساسي و المورد الثابت (Static Resource) مضبوطًا على استبعاد (Exclude)، ثم اقضِ بضع دقائق في إعادة التسمية، وتحديد المعلمات، ومسح الأسرار. ما تحصل عليه هو مجموعة عمل من نقاط النهاية التي يمكنك توثيقها، ومحاكاتها، واختبارها.

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