فهم وإتقان المتغيرات في Apidog

تتيح لك المتغيرات إعطاء اسم لقيمة وإعادة استخدامها في أي مكان تحتاج إليه.

على سبيل المثال، بدلاً من لصق رمز API يتغير بشكل متكرر في كل طلب، قم بتعريف متغير مثل ACCESS_TOKEN واستخدم {{ACCESS_TOKEN}} في طلباتك. عندما تنتهي صلاحية الرمز، قم بتحديث المتغير مرة واحدة وستلتقط جميع الطلبات التي تستخدمه القيمة الجديدة تلقائيًا.

أنواع المتغيرات في لمحة

يدعم Apidog عدة أنواع من المتغيرات، كل منها مصمم لسيناريوهات محددة. يمكنك استخدام: المتغيرات العامة على مستوى الفريق، والمتغيرات العامة على مستوى المشروع، ومتغيرات الوحدة النمطية، ومتغيرات البيئة، ومتغيرات بيانات الاختبار، والمتغيرات المحلية.

المتغيرات العامة

تتيح لك المتغيرات العامة مشاركة البيانات على نطاق واسع. هناك نوعان:

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

المتغيرات العامة على مستوى الفريق: يتم مشاركتها عبر جميع المشاريع في الفريق. مثالية للتعاون بين المشاريع. على سبيل المثال، إذا كانت خدمة المصادقة تصدر رمزًا يستخدمه عدة مشاريع، فقم بتخزينه كمتغير عام للفريق.

ملاحظة الأذونات: يمكن للأعضاء العاديين فقط عرض وتغيير القيم الحالية للمتغيرات العامة الموجودة على مستوى الفريق. لا يمكنهم إضافة/حذف المتغيرات أو إعادة تسميتها. يمكن لمسؤولي الفريق فقط إدارة المتغيرات على مستوى الفريق بشكل كامل في موارد الفريق ← المتغيرات.

متغيرات الوحدة النمطية

تقتصر متغيرات الوحدة النمطية على وحدة نمطية محددة. إذا قمت باستيراد مجموعة Postman، فسيتم استيراد متغيرات المجموعة الخاصة بها كمتغيرات وحدة نمطية في Apidog.

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

تأكد من تحديث Apidog لاستخدام متغيرات الوحدة النمطية.

متغيرات البيئة

متغيرات البيئة هي على الأرجح النوع الأكثر استخدامًا لديك. إنها تتيح لك التبديل بين البيئات دون تغيير التكوين لكل طلب.

في الممارسة العملية، عادة ما يكون لديك بيئات متعددة (محلية، اختبار، تدريج، إنتاج). لكل منها عناوين خادم مختلفة، أو اتصالات قاعدة بيانات، أو تكوينات طرف ثالث. باستخدام متغيرات البيئة، يمكنك التبديل بينها على الفور.

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

متغيرات بيانات الاختبار

تُشغل متغيرات بيانات الاختبار الاختبارات المعتمدة على البيانات. عندما تحتاج إلى اختبار نفس نقطة النهاية بالعديد من مجموعات البيانات، فهذا هو صديقك.

قم بإعداد ملف CSV أو JSON يحتوي على صفوف متعددة (أو كائنات). في سيناريو اختبار آلي، قم باستيراد الملف، وسيقوم Apidog بتكرار كل صف كمجموعة متغيرات واحدة وتنفيذ الاختبار لكل منها.

المتغيرات المحلية

تتمتع المتغيرات المحلية بأقصر عمر — صالحة فقط أثناء طلب واحد أو تشغيل اختبار واحد. تختفي بعد التنفيذ.

نظرًا لأن المتغيرات المحلية لها الأولوية القصوى، فهي مثالية لتجاوز أنواع المتغيرات الأخرى مؤقتًا. على سبيل المثال، تحدد بيئتك user_id، ولكن لاختبار خاص واحد، تحتاج إلى قيمة مختلفة — قم بتعيين متغير محلي بنفس الاسم بدلاً من تغيير البيئة.

أولوية المتغيرات

عندما تشترك متغيرات متعددة في نفس الاسم، يحلها Apidog حسب الأولوية (من الأعلى إلى الأقل): المتغيرات المحلية > متغيرات بيانات الاختبار > متغيرات البيئة > متغيرات الوحدة النمطية > المتغيرات العامة على مستوى المشروع > المتغيرات العامة على مستوى الفريق

مثال: إذا قمت بتعريف ثلاثة متغيرات باسم userId:

• المتغيرات العامة على مستوى المشروع userId = 1000
• متغيرات الوحدة النمطية: userId = 2000
• متغيرات البيئة: userId = 3000

عند استخدام {{userId}} في طلب، تكون القيمة الفعالة هي 3000 (من البيئة). إذا لم تكن هناك قيمة بيئة، فإنها تعود إلى قيمة الوحدة النمطية (2000)، ثم إلى قيمة المشروع العامة (1000).

القيم الأولية مقابل القيم الحالية

تحتوي المتغيرات العامة والوحدات النمطية والبيئية على قيم أولية وحالية — وهذا يوازن بين مشاركة الفريق والخصوصية الشخصية.

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

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

يتم تخزين القيم الحالية على جهازك ويمكن أن تفقد إذا قمت بمسح ذاكرة التخزين المؤقت أو تبديل الأجهزة. في إصدار الويب من Apidog، يتم تخزينها في المتصفح. للانتقال إلى جهاز جديد، قم بتصدير/استيراد البيئات لترحيل القيم الحالية.

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

طرق تعيين المتغيرات

اختر الطريقة التي تتناسب بشكل أفضل مع مصدر القيمة وكيف ستستخدمها.

تعيين المتغيرات مباشرة في صفحة إدارة البيئة

الطريقة الأكثر وضوحًا. انقر على زر إدارة البيئة (أعلى اليمين)، ثم قم بالتبديل إلى البيئة العامة أو بيئة محددة، ثم أضف الأسماء والقيم.

هذه الطريقة رائعة للتكوينات المستقرة مثل اتصالات قاعدة البيانات. يمكنك تعيين كل من القيم الأولية (المشتركة) والقيم الحالية (الخاصة).

استخدام ميزة "تخزين المتغير"

غالبًا ما تأتي قيمة المتغير من استجابة — مثل رمز مميز من نقطة نهاية تسجيل الدخول أو معرف مستخدم من نقطة نهاية إنشاء مستخدم. استخدم "تخزين المتغير" المرئي في Post Processors لإعداد متغير جديد.

في Post Processors لطلب ما، أضف "تخزين المتغير"، واختر المصدر (عادةً استجابة JSON)، وحدد الحقل باستخدام JSONPath.

على سبيل المثال، إذا كان JSON للاستجابة هو:

{
    "user": {
        "id": "69",
        "email": "Ralph85@gmail.com",
        "first_name": "Katlynn",
        "last_name": "Reichert",
        "api_token": "dolore ut mollit Duis sit",
        "created_at": "2025-09-19T01:03:50.236Z",
        "updated_at": "2025-05-10",
        "deleted_at": "2025-09-18T18:30:51.217Z",
        "role": "developer",
        "metadata": {}
    }
}

استخدم $.user.email لاستخراج الرمز.

يمكنك أيضًا تعيين المتغيرات مباشرة من قسم الاستجابة لطلب.

تعيين المتغيرات عبر السكربتات

للمنطق الأكثر تعقيدًا، استخدم السكربت المخصص في Pre Processors أو Post Processors. يوفر Apidog واجهة برمجة تطبيقات (API) كاملة للسكربتات لمعالجة جميع أنواع المتغيرات.

// Set a project‑level global variable

pm.globals.set('variable_key', 'variable_value');

// Set a team‑level global variable (must be defined on the Team Resources page first)

pm.globals.set('variable_key', 'variable_value', 'TEAM');

// Set an environment variable

pm.environment.set('variable_key', 'variable_value');

// Set a module variable

pm.moduleVariables.set('variable_key', 'variable_value');

// Set a local variable

pm.variables.set('variable_key', 'variable_value');

عند تخزين الكائنات أو المصفوفات، قم بتحويلها إلى سلسلة نصية أولاً ثم قم بتحليلها عند القراءة. على سبيل المثال:

pm.environment.set('user', JSON.stringify(userObj));

const users = JSON.parse(pm.environment.get('user'));

ملاحظة: يمكن للسكربتات فقط تعيين القيم الحالية للمتغيرات. يجب تعيين القيم الأولية في صفحة إدارة البيئة.

استخدام بيانات قاعدة البيانات كمتغيرات

يمكن لـ Apidog جلب البيانات مباشرة من قاعدة بيانات وتعيينها كمتغيرات — وهو أمر رائع للاختبارات التي تعتمد على سجلات حقيقية.

أضف عملية قاعدة بيانات في Post Processors، وقم بتكوين الاتصال، واكتب SQL. ثم استخرج الحقول إلى متغيرات باستخدام JSONPath.

نصائح لاستخدام المتغيرات

أين تعمل المتغيرات

يتم حل المتغيرات فقط عند إرسال الطلب فعليًا. هذا يعني أنه يمكنك استخدامها في الرؤوس، والمعاملات، والنص الأساسي، وسيناريوهات الاختبار، والسكربتات — في أي مكان يشارك في إرسال الطلب.

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

بناء الجملة الأساسي

استخدم الأقواس المعقوفة المزدوجة للإشارة إلى متغير: {{variableName}}. يعمل هذا في URL، والرؤوس، والمعاملات، والنص الأساسي.

على سبيل المثال، في المعاملات:

وفي النص الأساسي:

ملاحظات حول نصوص JSON: تحتاج متغيرات السلسلة إلى علامات اقتباس، بينما لا تحتاج المتغيرات الرقمية إليها. قد تؤدي الأقواس المعقوفة المزدوجة إلى تحذيرات JSON lint، ولكن يمكن تجاهلها بأمان.

إذا رأيت "متغير غير محلول"، فلا داعي للذعر. قد لا توجد المتغيرات المعينة في Post Processors أو السكربتات حتى يتم تشغيل الطلب، وتختفي المتغيرات المحلية بعد التشغيل. أفضل طريقة للتأكد هي إرسال الطلب فعليًا.

جلب الحقول الفرعية من متغير

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

لنفترض أنك قمت بتخزين كائن الاستجابة هذا كمتغير باسم user:

{
  "id": 1001,
  "name": "Joe",
  "email": "joe@example.com",
  "role": "admin"
}

يمكنك الإشارة إلى حقول محددة باستخدام تدوين النقطة، مثل {{user.id}} (1001) أو {{user.name}} ("Joe").

بالنسبة للمصفوفات، الأمر مشابه. إذا كان لديك متغير users:

[
  {"id": 1001, "name": "Joe"},
  {"id": 1002, "name": "Rio"},
  {"id": 1003, "name": "Outher"}
]

استخدم {{users[0].name}} للحصول على اسم المستخدم الأول، أو {{users[1].id}} لمعرف المستخدم الثاني.

يتبع هذا دلالات تشبه JSONPath — يعمل اسم المتغير كالجذر ($).

استخدام المتغيرات في السكربتات

يمكنك استخدام المتغيرات في السكربتات المخصصة لـ Pre Processors أو Post Processors. يوفر Apidog مجموعة كاملة من واجهات برمجة تطبيقات السكربتات، مما يتيح لك الوصول بمرونة إلى أنواع مختلفة من المتغيرات.

// Get a project‑level global variable

pm.globals.get('variable_key');

// Get a team‑level global variable

pm.globals.get('variable_key', 'TEAM');



// Get an environment variable

pm.environment.get('variable_key');



// Get a module variable

pm.moduleVariables.get('variable_key');



// Get a local variable

pm.variables.get('variable_key');

بالنسبة للكائنات/المصفوفات المخزنة كسلاسل، قم بالتحليل أولاً:

const userObj = JSON.parse(pm.environment.get('user'));

console.log(userObj.name);

الاختبار المعتمد على البيانات باستخدام متغيرات بيانات الاختبار

قم بتحميل ملف CSV أو JSON يحتوي على صفوف بيانات متعددة. أثناء التنفيذ، يستبدل Apidog {{variableName}} بالقيم من كل صف ويقوم بتشغيل الاختبار مرة واحدة لكل صف — وهو مثالي للتحقق من المتانة مع العديد من المدخلات.

تعبيرات القيمة الديناميكية

بالإضافة إلى متغيراتك الخاصة، يدعم Apidog القيم الديناميكية، التي تولد بيانات عشوائية باتباع قواعد محددة.

في السكربتات، يمكنك معالجة السلاسل التي تتضمن تعبيرات ديناميكية باستخدام await pm.variables.replaceInAsync():

const template = "Hello, {{$person.fullName}}";

const result = await pm.variables.replaceInAsync(template);

console.log(result); // Outputs a randomly generated name

تعد القيم الديناميكية مثالية لتوليد بيانات اختبار عشوائية دون إعداد مجموعة بيانات مسبقًا.

ملخص

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