استعلام JSONPath

ما هو مختبر JSONPath؟#

حين يكون مستند JSON صغيرًا، تقرؤه بعينيك. وحين يكون بضعة آلاف من الأسطر — استجابة واجهة برمجية، تفريغ إعداد، شجرة اعتمادات — تتوقف عيناك عن كون الأداة الصحيحة. JSONPath هو لغة الاستعلام لتلك الحالة: تعبير مُختصر يقول “أعطني كل حقل price”، أو “عناوين الكتب الأرخص من 10”، أو “كل عقدة اسمها isbn بغضّ النظر عن عمق دفنها”.

تخيّلها تهجينًا بين مسار ملف ولغة ترشيح صغيرة. فـ $.store.book[0].title ينزل عبر بنية معروفة كما يفعل مسار نظام ملفات. و$..author يقول “انحدر تكراريًّا واجمع كل author تجده”. و[?(@.price < 10)] ترشيح: أبقِ فقط العناصر حيث price للعقدة الحالية أقل من عشرة. و@ تعني دائمًا “العقدة التي أنظر إليها حاليًا”.

تُشغّل هذه الصفحة تعبير JSONPath مقابل JSON، تسرد كل تطابق، و— الجزء الذي يوفّر أكثر وقت — تُبرز النطاقات المتطابقة مباشرةً على المستند المُنسَّق لترى بنظرة إن كان تعبيرك قد اختار ما تظن أنه اختاره. تُقيَّم الترشيحات بمحلّل تعبيرات آمن، لا بتنفيذ كود، فلا يمكن لكتلة غير موثوقة تشغيل شيء.

كيفية الاستخدام#

1. الصق JSON في لوحة الإدخال على اليسار، أو انقر مثال لتحميل بيانات مكتبة الكلاسيكية.
2. اكتب تعبير JSONPath في حقل JSONPath على اليمين. نقاط بداية شائعة:
   • $.store.book[*].author — author لكل عنصر مصفوفة.
   • $..author — انحدار تكراري: كل author، في أي مكان.
   • $.store.book[?(@.price < 10)].title — تعبير ترشيح.
   • $.store.book[?(@.isbn)].isbn — اختبار وجود (لديه مفتاح isbn).
3. تملأ قائمة التطابقات تحت الحقل بإدخال واحد لكل نتيجة، ويُبرز معاين JSON بعرض كامل كل نطاق متطابق في مكانه.
4. تُظهر الترويسة بجانب التطابقات العدد. التعبير الذي يطابق صفر عقد لا يزال يُبلِّغ عن نجاح (قائمة فارغة) — فقط التعبير المكسور بنيويًّا يُظهر خطأً.
5. انقر نسخ التطابقات في شريط الأدوات لأخذ القيم المتطابقة كمصفوفة JSON، أو مسح لضبط اللوحتين.

تُطلق الاستعلامات أثناء الكتابة. إن كان JSON نفسه غير صالح، يشير شريط الحالة إلى الصف والعمود الدقيقين للإصلاح.

الميزات الرئيسية#

• تظليل في مكانه. كل قيمة متطابقة تُطبَّق على المستند المُنسَّق، فـ $.. تكراري يلتقط ثلاثين عقدة يصير مرئيًا فورًا بدلًا من دفنه في قائمة.
• تقييم ترشيح آمن. تُحلَّل التعابير مثل [?(@.price < 10)] بمُقيِّم تعبيرات، لا تُسلَّم لتنفيذ كود ديناميكي — تبقى الصفحة آمنة لـ CSP حتى على إدخال عدائي.
• تمييز “لا تطابق” عن “خطأ”. التعبير الصالح الذي لا يختار شيئًا يُبلَّغ عنه كصفر تطابقات؛ فقط التعبير المُشوَّه يُعلَّم كخطأ. لا تخلط أبدًا بين “لم يجد شيئًا” و”انكسر”.
• مؤشر لكل تطابق. يحمل كل نتيجة مؤشر JSON Pointer (مثلًا /store/book/2/title)، فتعرف بالضبط من أين في الشجرة أتت قيمة.
• نسخ كمصفوفة. تُصدَّر القيم المتطابقة كمصفوفة JSON نظيفة، جاهزة للتمرير إلى الخطوة التالية.
• محلي فقط. تُستعلم بياناتك في المتصفح. فلا خادم خلفي ولا رفع.

مثال عملي#

حمِّل مثال، ثم شغّل ترشيحًا يجد عناوين الكتب الرخيصة. أدخل هذا في حقل JSONPath:

$.store.book[?(@.price < 10)].title

تُعيد قائمة التطابقات عنوانَين، لأن اثنين فقط من الكتب الأربعة في البيانات سعرهما دون 10:

[
  "Sayings of the Century",
  "Moby Dick"
]

يُبرز معاين JSON قيمتي title تلك في مكانهما، وترى لماذا استُبعدت الأخرى — Sword of Honour (12.99) وThe Lord of the Rings (22.99) فوق الحد. بدِّل إلى اختبار وجود لمعرفة أي الكتب تحمل ISBN:

$.store.book[?(@.isbn)].isbn

يُعيد ذلك سلسلتي ISBN فقط ولا شيء غيرهما، لأن الترشيح يبقي فقط العناصر التي لديها فعلًا مفتاح isbn — نمط مفيد لإيجاد “أي السجلات تفتقد حقلًا” بنفيه.

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

ما الفرق بين $ و@؟#

$ هو جذر المستند — قيمة JSON بالكامل التي لصقتها. و@ هي العقدة الحالية قيد النظر داخل ترشيح. ففي [?(@.price < 10)]، تشير @ إلى أي كتاب يختبره الترشيح الآن؛ وكتابة $.price هناك ستقفز عودةً إلى الجذر وتبحث عن price ذي مستوى أعلى غير موجود.

تعبيري يطابق لا شيء. هل هذا خطأ؟#

غالبًا لا. التعبير الصالح الذي يختار صفر عقد هو استعلام ناجح بنتيجة فارغة — مثلًا، $.store.book[?(@.price > 1000)] على المثال تعني ببساطة لا كتاب بهذا الغلاء. تقرأ الترويسة “0 تطابقات” دون خطأ. فقط حين يكون التعبير نفسه غير قابل للتحليل تُبلِّغ الصفحة عن خطأ.

لماذا لا يُنفِّذ الترشيح JavaScript عشوائيًا؟#

تُقيَّم الترشيحات بمحلّل تعبيرات مخصص يفهم المقارنات، والعوامل المنطقية، ومراجع @ — لا يبني كودًا ولا يشغّله. هذا متعمَّد: فهو يبقي الأداة آمنة لتوجيهها إلى JSON لا تثق به تمامًا، ويُبقي الصفحة داخل سياسة أمان المحتوى للمتصفح.

هل يستطيع JSONPath تحرير العقد أو إزالتها؟#

لا — هذه أداة استعلام للقراءة فقط. تختار وتعرض، لا تُطفِّر JSON. إن أردت رؤية كيف يختلف مستندان بدلًا من ذلك، فاستخدم أداة /en/json/diff/.