لديك أربعون نقطة نهاية في مشروع، وكل واحدة منها تحتاج إلى نفس رأس `Authorization: Bearer ...` ورأس `X-Api-Version` في كل استدعاء. إضافة هذين السطرين يدويًا إلى كل طلب بطيئة، والأسوأ من ذلك أنها غير متسقة. تحصل نقطة نهاية واحدة على الرمز، وتُنسى أخرى، وتُضيّع فترة ما بعد الظهر في مطاردة خطأ 401 يظهر في ثلاثة مسارات فقط من أصل أربعين.
هناك طريقة أفضل. يتيح لك Apidog تعريف المعلمات مرة واحدة وتطبيقها على كل طلب تلقائيًا. اضبط الرأس على مستوى المشروع، وارجع إلى الرمز الخاص بك كمتغير، وستورث كل نقطة نهاية ذلك دون أن تضطر إلى لمس طلب واحد. يرشدك هذا الدليل إلى ثلاث آليات موثقة لذلك: المعلمات العامة، ومتغيرات البيئة، وخيار احتياطي لسكريبت محدد النطاق للمجلد. ستنتهي بإعداد عملي يرفق رأس مصادقة ورأس إصدار بكل شيء، بالإضافة إلى طريقة لإثبات أن الرأس قد تم إرساله بالفعل. إذا كنت ترغب في الحصول على خلفية أعمق حول المتغيرات أولاً، فإن دليلنا حول إتقان المتغيرات في Apidog يتناسب جيدًا مع هذا الدليل.
فكرة الطلب الذي يحمل رأسًا قياسيًا في كل استدعاء ليست فريدة من نوعها لـ Apidog. إنه نفس النمط الذي يصفه مرجع رؤوس HTTP من MDN: مجموعة صغيرة من أزواج المفتاح/القيمة التي تصاحب كل طلب. وظيفة Apidog هي تمكينك من تعيين هذه المجموعة مرة واحدة.
ماذا تعني "المعلمات العامة" حقًا
المعلمة العامة في Apidog هي معلمة طلب تنطبق على المشروع بأكمله بدلاً من نقطة نهاية واحدة. تقوم بتعريفها مرة واحدة، ويقوم Apidog بإرفاقها بالطلبات المطابقة تلقائيًا.
تغطي المعلمات العامة أربعة مواقع، وهذا هو مفتاح الميزة بأكملها:
- الرؤوس (رأس الطلب) لأشياء مثل `Authorization` أو `X-Api-Version`.
- ملفات تعريف الارتباط (معلومات ملف تعريف الارتباط) لملفات تعريف الارتباط الخاصة بالجلسة.
- الاستعلام (معلمة استعلام URL) لقيم مثل `?api_key=` التي تضاف إلى كل URL.
- الجسم (معلمة جسم الطلب) لحقل يجب أن يحمله كل جسم طلب.
بالنسبة لحالة استخدام رأس المصادقة، فأنت تريد الرؤوس. الثلاثة الأخرى تعمل بنفس الطريقة إذا كانت قيمتك القياسية موجودة في ملف تعريف ارتباط، أو سلسلة استعلام، أو حقل نص بدلاً من ذلك.
قاعدة واحدة مهمة قبل أن تبدأ: المعلمات العامة لها أولوية أقل من المعلمات المعرفة على مستوى نقطة النهاية. إذا كان طلب معين يحدد رأس `Authorization` الخاص به بالفعل، فإن تلك القيمة على مستوى نقطة النهاية تفوز وتتراجع القيمة العامة. فكر في المعلمة العامة كقيمة افتراضية تملأ الفراغ عندما لا تكون نقطة النهاية قد تحدثت عن نفسها، وليست تجاوزًا صارمًا يطغى على كل شيء. هذا الترتيب للأولوية هو ما يجعل تفعيل المعلمات العامة آمنًا عبر مشروع كبير.
ضبط رأس عام على كل طلب
إليك الشرح الأساسي. الهدف: إرفاق `Authorization` و `X-Api-Version` بكل نقطة نهاية في المشروع دون تعديل أي منها.
الخطوة 1: فتح إدارة البيئة
توجد المعلمات العامة في **إدارة البيئة**، والتي تفتحها من الزاوية العلوية اليمنى للصفحة. هذه هي نقطة الدخول للمعلمات التي تنطبق على مستوى المشروع، و وثائق Apidog تصفها بأنها المكان للقيم التي تصاحب كل طلب. افتحها، وسترى الأقسام التي تضيف فيها المعلمات حسب الموقع.
الخطوة 2: اختر موقع الرؤوس
اختر **الرؤوس** (موقع رأس الطلب) لأنك تضيف رأس مصادقة. إذا كانت قيمتك القياسية عبارة عن ملف تعريف ارتباط، أو معلمة استعلام، أو حقل نص، فستختار ملفات تعريف الارتباط، أو الاستعلام، أو النص بدلاً من ذلك. الآليات متطابقة عبر الأربعة.
الخطوة 3: املأ تفاصيل المعلمة
لكل معلمة عامة مجموعة ثابتة من الخصائص. املأها لرأسك الأول:
- الاسم: `Authorization`
- النوع: نوع المعلمة (سلسلة لقيمة الرأس).
- القيمة الافتراضية: `Bearer {{token}}` (مزيد من التفاصيل حول `{{token}}` أدناه).
- الوصف: ملاحظة قصيرة مثل "رمز حامل لجميع نقاط النهاية الموثقة."
يظهر حقل `Default` وعلامة مطلوب (نجمة `*`) أيضًا على المعلمات المطلوبة. أضف صفًا ثانيًا بنفس الطريقة لرأس الإصدار:
- الاسم: `X-Api-Version`
- النوع: سلسلة
- القيمة الافتراضية: `2024-08-01`
- الوصف: "إصدار API ثابت لكل طلب."
الخطوة 4: تفعيل المعلمة
تحتوي كل معلمة على مفتاح تشغيل/إيقاف على الجانب الأيمن. قم بتشغيله لتفعيل المعلمة. هذا التبديل مفيد لاحقًا: إذا احتجت يومًا إلى إسكات رأس عام لجلسة تصحيح الأخطاء، يمكنك تعطيله هنا بدلاً من حذفه وإعادة كتابة كل شيء.
الخطوة 5: حفظ
احفظ التكوين. كلا الرأسين أصبحا الآن عموميين. سيحمل كل طلب في المشروع `Authorization` و `X-Api-Version` ما لم تقم نقطة نهاية معينة بتجاوز أحدهما.
الخطوة 6: إثبات أنه تم إرساله بالفعل
لا تثق في أنه يعمل؛ تحقق. أرسل أي طلب في المشروع، ثم افتح علامة التبويب **Actual Request** (الطلب الفعلي) في نافذة استجابة الكونسول. تُظهر هذه العلامة التبويب الطلب تمامًا كما تم إرساله، مع استبدال المتغيرات بالفعل بقيمها الحقيقية. يجب أن ترى كلا الرأسين مدرجين هناك:
GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
إذا ظهرت الرؤوس في Actual Request (الطلب الفعلي)، فقد تم إرسالها. هذه هي النقطة الأكثر فائدة في الإعداد بأكمله، لأنها تحول "أعتقد أنه تم تطبيقه" إلى "يمكنني رؤية أنه تم تطبيقه."
أبعد السر عن الرأس: استخدم متغيرًا
لاحظ أن القيمة الافتراضية أعلاه كانت `Bearer {{token}}`، وليست `Bearer sk_live_7f3a9c2e1b8d4056`. تشير صيغة الأقواس المزدوجة هذه إلى متغير بدلاً من ترميز الرمز الخام مباشرة في المعلمة. مخطط `Bearer` نفسه معرف في RFC 6750، و مرجع رأس Authorization من MDN يغطي كيفية قراءة الخوادم له. وثائق Apidog صريحة بشأن جانب الأمان: بالنسبة للبيانات الحساسة مثل رموز المصادقة ومفاتيح API، استخدم متغيرات البيئة بدلاً من تخزين القيمة الخام كقيمة افتراضية نصية عادية. المتغير هو عنصر نائب ديناميكي لقيمة تستخدمها عبر العديد من الطلبات والسكريبتات، ويحافظ على السرية بعيدًا عن تعريف المعلمة.
إليك كيفية إعداد متغير `token`:
- انقر على أيقونة البيئة (الأيقونة `≡`) في الزاوية العلوية اليمنى. لاحظ أن هذه نقطة دخول مختلفة عن إدارة البيئة: أيقونة `≡` هي حيث توجد المتغيرات.
- ابحث عن قسم **المتغيرات العامة**.
- أنشئ متغيرًا، على سبيل المثال `token` بقيمة السر الخاص بالرمز الحامل.
- انقر على **حفظ**.
الآن، قيمة رأسك العام `Bearer {{token}}` تتحول إلى `Bearer <السر_الحقيقي_الخاص_بك>` عند وقت الإرسال، وتؤكد علامة تبويب الطلب الفعلي (Actual Request) الاستبدال. عند تمرير مؤشر الفأرة فوق اسم متغير في أي مكان، يظهر قيمته ونطاقه الحاليين، وهي طريقة سريعة للتحقق من أنك أشرت إلى المتغير الصحيح.
هذا الاقتران هو النمط الموصى به: **المعلمة العامة** تمتلك فتحة الرأس، و**المتغير** يمتلك السر. يتعمق مقالنا الشامل حول بيئة عميل API وإدارة الأسرار في كيفية إبعاد الرموز عن أي شيء قد تشاركه أو تلتزم به.
تبديل القيم حسب البيئة
تصبح المتغيرات أكثر فائدة عندما يكون لديك أكثر من واحد. تتصل المشاريع الحقيقية بخوادم مختلفة للتطوير والاختبار والإنتاج، وعادة ما يريد كل منها رمزًا مميزًا مختلفًا. قم بتجميع كل مجموعة تحت بيئتها الخاصة، ثم قم بالتبديل بينها باستخدام **القائمة المنسدلة للبيئات** بجوار أيقونة `≡` (قد تُسمى بيئة مثال `Local Mock`). تبديل البيئة يوجه طلباتك إلى مجموعة مختلفة من الخوادم ويستبدل قيم متغيرات تلك البيئة. يظل رأسك العام `Bearer {{token}}` كما هو؛ يتغير السر المحلول فقط مع البيئة. إذا كنت تبني تدفقات مصادقة فوق هذا، فإن المفاهيم الواردة في دليل مخططات الأمان لدينا تشرح كيفية تعيين تعريفات Bearer و API-key و OAuth على الطلبات الفعلية.
عندما تريد الرأس على مجلد واحد فقط
تؤثر المعلمات العامة على المشروع بأكمله. في بعض الأحيان يكون ذلك واسعًا جدًا. قل إن نقاط نهاية `/admin` فقط تحتاج إلى رأس `X-Admin-Scope`، ولا ينبغي لبقية المشروع أن تحمل هذا الرأس.
إليك القيود الصريحة: لا يحتوي Apidog على حقل "إضافة رأس" أصلي في إعدادات المجلد. لا توجد واجهة مستخدم لرأس على مستوى المجلد لملئها. ما توثقه المستندات بدلاً من ذلك هو حل بديل باستخدام سكريبت ما قبل الطلب على مستوى المجلد، بحيث يرث كل طلب داخل هذا المجلد الرأس. يستخدم السكريبت برمجة `pm.*` المتوافقة مع Postman:
pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
أضف ذلك كسكريبت ما قبل الطلب على المجلد، وسيلتقط كل طلب في المجلد الرأس، بينما الطلبات خارج المجلد لا تفعل ذلك. إنه سكريبت، وليس مفتاح إعدادات، لذا تعامل معه كحل احتياطي مدروس للاحتياجات ذات النطاق المجلد بدلاً من المسار الأساسي. للحصول على نموذج السكريبت الأوسع الذي يعتمد عليه هذا، راجع دليلنا إلى سكريبتات ما قبل الطلب وما بعد الطلب في Apidog.
أي رافعة، ومتى
لديك الآن ثلاث طرق لإرفاق رأس دون تعديل نقاط النهاية. اختر حسب النطاق:
- **معلمة عامة (رؤوس)** عبر إدارة البيئة: ينطبق الرأس على المشروع بأكمله. هذا هو الإعداد الافتراضي الخاص بك لرأس مصادقة مشترك أو رأس إصدار.
- **متغير بيئة** (`{{token}}`): قم بإقرانه بالمعلمة العامة بحيث تكون فتحة الرأس عالمية ولكن يتم تخزين السر بأمان وتبديله حسب البيئة.
- **سكريبت ما قبل الطلب على مستوى المجلد** (`pm.request.headers.add`): ينطبق الرأس على مجلد واحد فقط. الجأ إلى هذا عندما يكون النطاق على مستوى المشروع واسعًا جدًا.
أمرين يجب الانتباه إليهما. تحقق من عدم وجود أسماء معلمات مكررة حتى لا تتصادم رأسين عامين، وتأكد من أن نوع كل معلمة يتطابق مع كيفية استخدامها. وتذكر قاعدة الأسبقية: نقطة نهاية تحدد رأس `Authorization` الخاص بها تلغي الرأس العام، وهي ميزة عندما يحتاج مسار واحد إلى رمز مميز مختلف، ولكنها مفاجأة إذا نسيت أن هذا المسار كان له قيمته الخاصة. لا تحمل أي من هذه الميزات الثلاث أي قيود على الخطط في الوثائق، لذا لا تحتاج إلى مستوى معين لاستخدامها.
أتمتة سير العمل باستخدام واجهة سطر الأوامر (CLI) لـ Apidog
ليست المعلمات العامة والبيئات مجرد سهولة في واجهة المستخدم الرسومية؛ بل تنتقل أيضًا إلى التشغيلات الآلية. عندما تقوم بإنشاء سيناريو اختبار محفوظ في Apidog وتشغيله من سطر الأوامر، فإن التشغيل يرث بيئة تمررها بواسطة المعرف، لذلك فإن نفس رأس `Bearer {{token}}` وقيمة `X-Api-Version` التي عملت في واجهة المستخدم الرسومية يتم حلها بنفس الطريقة في التكامل المستمر (CI).
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
تحدد العلامة `-e` البيئة، لذلك يلتقط السيناريو متغيرات تلك البيئة، بما في ذلك الرمز الخاص بك. العلامة `-t` هي معرف سيناريو الاختبار و `-r` هي المُبلغ (`cli`، `html`، أو `junit`). هذا هو الربط: حدد الرأس والمتغير مرة واحدة، وكل تشغيل سيناريو عبر CLI يحملها. للحصول على تفاصيل الإعداد والرموز، راجع دليل تثبيت Apidog CLI، ولربط التشغيلات بالأتمتة، يُظهر دليلنا Apidog CLI في GitHub Actions الخطوات الكاملة.
الأسئلة الشائعة
هل تتجاوز المعلمات العامة رأسًا قمت بتعيينه على نقطة نهاية محددة؟
لا. المعلمات العامة لها أولوية أقل من المعلمات على مستوى نقطة النهاية. إذا حدد طلب رأس `Authorization` الخاص به، فإن تلك القيمة تفوز ويتم تجاهل القيمة العامة لهذا الطلب. تعمل المعلمات العامة كقيمة افتراضية للمشروع، حيث تملأ الفراغات حيثما لم تحدد نقطة النهاية قيمتها الخاصة.
أين يجب أن أخزن الرمز الفعلي حتى لا يكون موجودًا كنص عادي؟
استخدم متغير بيئة أو متغيرًا عامًا، وليس قيمة افتراضية خام. اضبط الرأس العام على `Bearer {{token}}` واحتفظ بالسر الحقيقي في متغير تم إنشاؤه عبر أيقونة البيئة `≡`. توصي الوثائق باستخدام المتغيرات أو الطرق الآمنة للبيانات الحساسة تحديدًا حتى لا يتم تخزين الرمز بشكل مباشر. يغطي دليلنا حول استخراج المتغيرات باستخدام JSONPath كيفية التقاط رمز من استجابة تسجيل الدخول وإعادة استخدامه بنفس الطريقة.
كيف أؤكد أن الرأس العام قد تم إرساله بالفعل؟
أرسل أي طلب، ثم افتح علامة التبويب **Actual Request** (الطلب الفعلي) في نافذة استجابة الكونسول. تُظهر الطلب كما تم إرساله بالفعل، مع استبدال `{{token}}` والمتغيرات الأخرى بقيمها. إذا ظهر رأسك هناك، فقد تم إرساله.
هل يمكنني إضافة رأس افتراضي إلى مجلد واحد فقط بدلاً من المشروع بأكمله؟
نعم، ولكن ليس من خلال حقل إعدادات، لأن Apidog لا يحتوي على واجهة مستخدم أصلية لرأس المجلد. أضف سكريبت ما قبل الطلب على المجلد باستخدام `pm.request.headers.add({ key, value })`، وسيرث كل طلب في هذا المجلد الرأس بينما لا يرثه بقية المشروع.
هل أحتاج إلى خطة مدفوعة لاستخدام المعلمات العامة أو متغيرات البيئة؟
لا تذكر وثائق هذه الميزات أي قيود على المستويات. فالمعلمات العامة، ومتغيرات البيئة، وسكريبتات ما قبل الطلب على مستوى المجلد موثقة جميعها دون تمييز بين المجاني والمدفوع.
خاتمة
تحديد رأس لكل طلب هو مهمة لمرة واحدة في Apidog: عرّف الرأس كمعلمة عامة ضمن إدارة البيئة، وارجع إلى السر كمتغير `{{token}}` ليبقى خارج النص العادي، وتأكد من إرساله باستخدام علامة التبويب "الطلب الفعلي" (Actual Request). عندما تحتاج إلى رأس في مجلد واحد فقط، فإن سكريبت ما قبل الطلب الاحتياطي يغطي ذلك. لمتابعة العمل في مشروعك الخاص، قم بتنزيل Apidog وقم بإعداد رأسك العام الأول. إنه مجاني، ولا يتطلب بطاقة ائتمان.