DEV Community

Cover image for كيفية ضبط البارامترات العامة في Apidog (إرسال رؤوس المصادقة مع كل طلب)
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية ضبط البارامترات العامة في Apidog (إرسال رؤوس المصادقة مع كل طلب)

لديك 40 نقطة نهاية في مشروعك، وكل طلب يحتاج إلى رأسي Authorization: Bearer ... وX-Api-Version. إضافتهما يدويًا إلى كل طلب بطيئة ومعرّضة للأخطاء: قد تنسى رمز المصادقة في مسار واحد، ثم تقضي وقتًا في تتبع أخطاء 401 في بعض المسارات فقط.

جرّب Apidog اليوم

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

فكرة إرسال رؤوس قياسية مع كل طلب ليست حصرية على Apidog؛ فهي تتبع نموذج رؤوس HTTP في MDN: أزواج مفتاح/قيمة ترافق الطلب. ما يضيفه Apidog هو القدرة على تعريف هذه القيم مرة واحدة.

ماذا تعني المعلمات العامة؟

المعلمة العامة في Apidog هي معلمة طلب تُطبق على المشروع بالكامل بدلًا من نقطة نهاية واحدة. تعرّفها مرة واحدة، ثم يضيفها Apidog تلقائيًا إلى الطلبات المطابقة.

يمكن تعريف المعلمات العامة في أربعة مواقع:

  • الرؤوس: لقيم مثل Authorization وX-Api-Version.
  • ملفات تعريف الارتباط: لملفات تعريف ارتباط الجلسات.
  • الاستعلام: لقيم URL مثل ?api_key=.
  • الجسم: لحقول يجب أن تظهر في جسم كل طلب.

في حالة المصادقة، استخدم الرؤوس.

المعلمات العامة لها أولوية أقل من المعلمات المعرفة على مستوى نقطة النهاية. إذا عرّف طلب معين رأس Authorization خاصًا به، فستُستخدم قيمة الطلب بدل القيمة العامة. لذلك تعمل المعلمات العامة كإعداد افتراضي آمن للمشروع.

إضافة رأس عام إلى كل طلب

الهدف هو إرفاق Authorization وX-Api-Version بكل نقطة نهاية دون تعديل الطلبات واحدةً واحدة.

1. افتح إدارة البيئة

افتح إدارة البيئة من الزاوية العلوية اليمنى في Apidog. هنا يمكنك إدارة المعلمات التي تُطبق على مستوى المشروع. راجع أيضًا وثائق Apidog للتفاصيل.

2. اختر الرؤوس

اختر قسم الرؤوس لأنك تريد إضافة رأس مصادقة.

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

3. أضف رأس Authorization

أضف صفًا جديدًا بالقيم التالية:

الحقل القيمة
الاسم Authorization
النوع سلسلة
القيمة الافتراضية Bearer {{token}}
الوصف رمز Bearer لجميع نقاط النهاية الموثقة

ثم أضف رأس الإصدار:

الحقل القيمة
الاسم X-Api-Version
النوع سلسلة
القيمة الافتراضية 2024-08-01
الوصف إصدار API ثابت لكل طلب

4. فعّل المعلمات

فعّل مفتاح التشغيل بجانب كل معلمة. يمكنك لاحقًا تعطيل رأس مؤقتًا أثناء التصحيح دون حذف تعريفه.

5. احفظ التكوين

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

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

6. تحقق من الطلب الفعلي

لا تفترض أن الإعداد يعمل؛ تحقّق منه.

  1. أرسل أي طلب في المشروع.
  2. افتح علامة التبويب Actual Request في نافذة الاستجابة.
  3. ابحث عن الرؤوس المرسلة.

يجب أن ترى شيئًا مشابهًا للتالي:

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

تعرض علامة Actual Request الطلب كما أُرسل فعليًا، بعد استبدال المتغيرات بقيمها. إذا ظهر الرأس هناك، فقد أُرسل.

خزّن السر في متغير

لا تضع الرمز مباشرة في قيمة الرأس، مثل:

Authorization: Bearer sk_live_7f3a9c2e1b8d4056
Enter fullscreen mode Exit fullscreen mode

استخدم متغيرًا بدلًا من ذلك:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

صيغة {{token}} تشير إلى متغير. مخطط Bearer موثق في RFC 6750، ويمكنك الرجوع إلى مرجع رأس Authorization في MDN لفهم كيفية تعامل الخوادم معه.

لإنشاء المتغير:

  1. انقر أيقونة البيئة ≡ في الزاوية العلوية اليمنى.
  2. افتح قسم المتغيرات العامة.
  3. أنشئ متغيرًا باسم token.
  4. ضع قيمة رمز Bearer الفعلية في المتغير.
  5. اضغط حفظ.

الآن يحل Apidog:

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

إلى:

Bearer <الرمز_الفعلي>
Enter fullscreen mode Exit fullscreen mode

عند إرسال الطلب.

هذا هو النمط العملي الموصى به:

  • المعلمة العامة تحدد مكان الرأس.
  • المتغير يخزن السر.
  • Actual Request يؤكد القيمة المرسلة.

لمزيد من التفاصيل حول إبقاء الأسرار خارج التعريفات المشتركة، راجع بيئة عميل API وإدارة الأسرار.

التبديل بين البيئات

غالبًا ما تحتاج بيئات التطوير والاختبار والإنتاج إلى رموز مختلفة. أنشئ قيمة token مختلفة لكل بيئة، ثم بدّل البيئة من القائمة المنسدلة بجانب أيقونة ≡.

يبقى تعريف الرأس ثابتًا:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

بينما تتغير القيمة المحلولة حسب البيئة النشطة.

إذا كنت تبني تدفقات مصادقة أكثر تقدمًا، فراجع دليل مخططات الأمان لتطبيق Bearer وAPI Key وOAuth على الطلبات.

إضافة رأس إلى مجلد واحد فقط

المعلمات العامة تنطبق على المشروع بالكامل. لكن قد تحتاج أحيانًا إلى رأس لمسارات داخل مجلد معين فقط، مثل نقاط النهاية في /admin.

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

X-Admin-Scope: full
Enter fullscreen mode Exit fullscreen mode

لا يوفر Apidog حقل إعدادات أصليًا لإضافة رأس على مستوى المجلد. البديل هو استخدام سكريبت ما قبل الطلب على المجلد:

pm.request.headers.add({
  key: 'X-Admin-Scope',
  value: 'full'
});
Enter fullscreen mode Exit fullscreen mode

أضف هذا السكريبت إلى إعدادات المجلد. سترث كل الطلبات داخله الرأس، بينما لن تتأثر الطلبات خارج المجلد.

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

أي أسلوب تستخدم؟

اختر الآلية حسب النطاق المطلوب:

  • معلمة عامة للرؤوس: عندما يجب أن يُرسل الرأس مع كل طلبات المشروع، مثل Authorization أو X-Api-Version.
  • متغير بيئة مثل {{token}}: عندما تحتاج إلى تخزين السر وتبديل قيمته بين البيئات.
  • سكريبت ما قبل الطلب على مستوى المجلد: عندما يجب أن يُرسل الرأس مع طلبات مجلد واحد فقط.

انتبه إلى نقطتين:

  1. لا تنشئ رؤوسًا عامة مكررة بالاسم نفسه.
  2. تذكر أن قيمة الرأس المعرفة على مستوى نقطة النهاية تتقدم على القيمة العامة.

تشغيل السيناريوهات عبر Apidog CLI

المعلمات العامة ومتغيرات البيئة لا تقتصر على واجهة Apidog. عند تشغيل سيناريو اختبار محفوظ عبر CLI، يرث التشغيل البيئة التي تحددها، وبالتالي تُحل قيمة Bearer {{token}} بالطريقة نفسها المستخدمة في الواجهة.

ثبّت CLI وسجّل الدخول:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

ثم شغّل سيناريو اختبار مقابل بيئة محددة:

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 أو html أو junit.

بما أن -e يحدد البيئة، سيستخدم السيناريو متغيرات تلك البيئة، بما فيها token.

للتثبيت والإعداد، راجع دليل تثبيت Apidog CLI. ولتشغيله في التكامل المستمر، راجع Apidog CLI في GitHub Actions.

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

هل تتجاوز المعلمات العامة رأسًا محددًا على نقطة نهاية؟

لا. إعدادات نقطة النهاية لها أولوية أعلى. إذا عرّفت نقطة نهاية رأس Authorization خاصًا بها، فستُستخدم قيمتها بدل القيمة العامة.

أين أخزن رمز المصادقة؟

استخدم متغيرًا مثل {{token}} بدل وضع الرمز كنص صريح في المعلمة العامة:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

يمكنك أيضًا استخراج رمز من استجابة تسجيل الدخول وإعادة استخدامه. راجع استخراج المتغيرات باستخدام JSONPath.

كيف أتأكد من إرسال الرأس؟

أرسل طلبًا ثم افتح Actual Request. إذا ظهر الرأس والقيمة المحلولة في الطلب المعروض، فقد أُرسل الرأس.

هل يمكنني إضافة رأس افتراضي إلى مجلد فقط؟

نعم، باستخدام سكريبت ما قبل الطلب على المجلد:

pm.request.headers.add({
  key: 'X-Admin-Scope',
  value: 'full'
});
Enter fullscreen mode Exit fullscreen mode

هل تتطلب هذه الميزات خطة مدفوعة؟

لا تذكر الوثائق قيودًا على الخطط للمعلمات العامة أو متغيرات البيئة أو سكريبتات ما قبل الطلب على مستوى المجلد.

الخلاصة

لتوحيد رؤوس المصادقة والإصدار عبر مشروعك:

  1. عرّف الرأس ضمن المعلمات العامة في إدارة البيئة.
  2. استخدم Bearer {{token}} بدل تخزين السر في نص عادي.
  3. أنشئ قيمة token في البيئة المناسبة.
  4. تحقق من النتيجة في Actual Request.
  5. استخدم سكريبت ما قبل الطلب عندما تحتاج إلى نطاق مجلد فقط.

للبدء، نزّل Apidog واضبط أول رأس عام في مشروعك.

Top comments (0)