[دليل] ماذا يعني JSONPath في Postman؟

تتعلق فعالية اختبار واجهات برمجة التطبيقات (API) باستخراج البيانات ومعالجتها بكفاءة من استجابات JSON. منصة Postman، وهي منصة تطوير API شائعة، تمنح المستخدمين أداة JSONPath، وهي لغة استعلام قوية مصممة خصيصًا للتنقل في هياكل JSON.

تتناول هذه المقالة عالم JSONPath في Postman، مما يزودك بالمهارات اللازمة للاستفادة الكاملة من تفاعلات واجهة برمجة التطبيقات الخاصة بك.

ما هو JSONPath؟

JSON (تنسيق كائن JavaScript) هو تنسيق بيانات شائع لتبادل المعلومات بين واجهات برمجة التطبيقات والتطبيقات. بينما تعتبر طبيعته القابلة للقراءة البشرية نقطة إيجابية، إلا أن استجابات JSON المعقدة ذات الكائنات المتداخلة والمصفوفات قد تكون صعبة التنقل. هنا يأتي دور JSONPath - إنها لغة استعلام موجزة مصممة خصيصًا للتنقل واستخراج البيانات من هياكل JSON.

تشبه تعبيرات JSONPath خارطة طريق، ترشدك عبر هرم JSON. إليك كيف يعمل:

العنصر الجذري

تمثل العناصر الجذرية بـ $، والتي تشير إلى الوثيقة الكاملة لـ JSON.

العقد الفرعية

تستخدم نقطة الترميز (.) أو ترميز الأقواس ([]) للوصول إلى العقد الفرعية.

• تفضل نقطة الترميز لأسماء الخصائص البسيطة: $.name تختار خاصية "name" من الكائن الجذري.
• يتم استخدام ترميز الأقواس للوصول إلى الخصائص ذات الأحرف الخاصة أو المسافات: $['full name'] تستهدف خاصية "full name".

المصفوفات

تسمح الأقواس المربعة مع فهرس الوصول إلى عناصر محددة: $.items[1] تختار العنصر الثاني في مصفوفة "items". يمكن استخدام الرموز النجمية (*) لاستهداف جميع العناصر: $.products[*] تختار جميع العناصر في مصفوفة "products".

المرشحات

تسمح لك المرشحات بتضييق النتائج بناءً على الشروط. على سبيل المثال، $..[?(@.price > 100)] تختار جميع الكائنات داخل هيكل JSON (المشار إليه بـ ..) حيث تكون "price" الخاصية أكبر من 100.

كيف يعمل Postman مع JSONPath؟

نصوص الاختبار

يمكن تضمين تعبيرات JSONPath ضمن نصوص الاختبار في Postman لاستخراج بيانات محددة من الاستجابات وإجراء التأكيدات.

• مثال: pm.test("رمز الحالة هو 200", () => pm.response.json().statusCode === 200);
• مثال (مع JSONPath): pm.test("معرّف المستخدم هو 123", () => pm.response.jsonPath("$.id") === 123);

المجموعات

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

• مثال: استرجع معرّف مستخدم من استجابة سابقة واستخدمه في طلب لاحق: pm.collectionVariables.set("userId", pm.response.jsonPath("$.id"));

نصوص ما قبل الطلب

يمكن استخدام تعبيرات JSONPath ضمن نصوص ما قبل الطلب لمعالجة البيانات قبل إرسال الطلب.

• مثال: تعديل جسم الطلب بناءً على قيم محددة من متغير بيئة اختبار: pm.request.body.set("productId", pm.environment.variables.selectedProduct.id);

أمثلة على استعلامات JSONPath

هذه بعض أمثلة استعلامات JSONPath التي يمكن تنفيذها في قسم ما قبل الطلب في Postman.

المثال 1 - المنطق الشرطي باستخدام دالة if

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

$.users[*].if(@.isActive, $.name, "غير نشط")

يستخدم هذا الكود دالة if. إذا كانت خاصية "isActive" في كائن المستخدم الحالي تم إعدادها على true، فإنه يستخرج اسمهم. خلاف ذلك، يعود السلسلة "غير نشط".

المثال 2 - العثور على القيم الدنيا/القصوى

دعنا نقول لديك مصفوفة "الأوامر" مع خاصية "المبلغ" لكل طلب. تريد العثور على الطلب ذو المبلغ الأدنى والأقصى.

$..[?(@.type == "order")].amount.min()  // أقل مبلغ
$..[?(@.type == "order")].amount.max()  // أكبر مبلغ

تستخدم هذه الاستعلامات دالات min() و max() لتحديد القيم المعنية في خاصية "المبلغ" عبر جميع الأوامر.

المثال 3 - تسطيح المصفوفات المتداخلة

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

$.categories..[*] | flatten

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

المثال 4 - العمل مع التواريخ والأرقام

يمكن لـ JSONPath معالجة التواريخ والأرقام. دعنا نقول لديك طابع زمني "createdAt" للمستخدمين. تريد تنسيقه إلى تنسيق تاريخ معين.

pm.response.json().users[*].createdAt.toString(pm.timestampFormat("YYYY-MM-DD"))  // افترض وجود دالة تنسيق محددة مسبقًا

يجمع هذا المثال بين JSONPath مع وظيفة برمجة نصية في Postman (pm.timestampFormat) لتنسيق الطابع الزمني "createdAt" إلى التنسيق المطلوب (YYYY-MM-DD) ضمن نص ما قبل الطلب.

المثال 5 - دمج JSONPath مع متغيرات Postman

يمكنك التحكم ديناميكيًا في استعلامات JSONPath باستخدام متغيرات Postman. افترض أنك تريد تصفية المستخدمين بناءً على معرف مستخدم مخزن في متغير.

$.users[?(@.id == pm.variables.get("selectedUserId"))]

هنا، يقوم pm.variables.get("selectedUserId") باسترداد القيمة المخزنة في متغير "selectedUserId" ويستخدمها ضمن مرشح JSONPath للاختيار الديناميكي للمستخدم.

Apidog - إعداد نصوص المعالجة المسبقة بسرعة

Apidog هي أداة شاملة لتطوير واجهات برمجة التطبيقات يمكن أن تكون بديلًا مثاليًا لـ Postman.

مع أدوات كاملة لدورة حياة API بأكملها، يمكن للمطورين بناء، واختبار، وتقديم نماذج، وتوثيق واجهات برمجة التطبيقات داخل Apidog فقط!

إعداد نصوص واجهة برمجة التطبيقات المخصصة باستخدام Apidog

يوفر Apidog للمطورين ميزات توليد كود لنصوص مخصصة. يمكنك الحصول على وتعيين كل من المتغيرات البيئية والمحلية.

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

إنشاء واجهات برمجة التطبيقات الجديدة باستخدام Apidog

يمكن لـ Apidog تمكين المستخدمين بقدر عالٍ من مرونة التصميم في عملية إنشاء واجهات برمجة التطبيقات. هذا يمكّن تطوير واجهات برمجة التطبيقات التي تتماشى بدقة مع المتطلبات الوظيفية لتطبيقك أو الاحتياجات المحددة لمستخدميها المستهدفين.

ابدأ بالضغط على زر New API، كما هو موضح في الصورة أعلاه.

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

• طرق HTTP: اختيار طريقة HTTP المناسبة (GET، POST، PUT، DELETE) أمر بالغ الأهمية. هذه الطرق تحكم كيفية تفاعل المستخدمين والتلاعب بالمعلومات داخل واجهة برمجة التطبيقات الخاصة بك.
• نقطة نهاية واجهة برمجة التطبيقات: يجب اختيار عنوان ويب فريد (نقطة نهاية) ليكون نقطة الوصول للمستخدمين للعثور على واجهة برمجة التطبيقات الخاصة بك والتفاعل معها.
• معلمات الإدخال: من الضروري توضيح أي عناصر بيانات يمكن للمستخدمين إدراجها في عنوان واجهة برمجة التطبيقات لاسترداد استجابات محددة.
• الوظائف: يتطلب الأمر شرحًا واضحًا لتفصيل الإجراءات والنتائج الدقيقة التي توفرها واجهة برمجة التطبيقات الخاصة بك.

لضمان بناء واجهات برمجة تطبيقات فعالة، ضع في اعتبارك مراجعة هذه المقالات المفيدة حول أفضل الممارسات لواجهات برمجة التطبيقات REST.

الخاتمة

يفتح تكامل Postman مع JSONPath أداة قوية ومتعددة الاستخدامات للتنقل ومعالجة البيانات داخل استجابات JSON. من خلال إتقان تعبيرات JSONPath، يمكنك استخراج قيم محددة بكفاءة، وتصفيه النتائج بناءً على الشروط، وحتى إجراء تحولات بيانات معقدة. وهذا يمكّنك من تنظيم سير عمل اختبار واجهة برمجة التطبيقات، والحصول على رؤى أعمق من الاستجابات، وبناء حالات اختبار قوية تضمن وظيفة وموثوقية واجهات برمجة التطبيقات الخاصة بك.

علاوة على ذلك، يفتح التكامل السلس لـ JSONPath مع قدرات برمجة Postman النصية أبوابًا لمزيد من حالات الاستخدام المتقدمة. يمكنك التحكم ديناميكيًا في الاستعلامات باستخدام المتغيرات، والاستفادة من الدوال لمعالجة البيانات بشكل متطور، ودمج JSONPath مع نصوص ما قبل الطلب أو نصوص الاختبار لأتمتة المهام المعقدة. من خلال اعتماد قوة JSONPath في Postman، ترتقي بعملية تطوير واجهة برمجة التطبيقات الخاصة بك إلى مستوى جديد تمامًا من الكفاءة والفاعلية.