طريقة الاستخدام
- الصق مستند JSON في مستند JSON. استخدم المثال لتجربة الأداة أولاً.
- اكتب استعلام JSONPath في الحقل تحته، ويبدأ بـ $. توضع المرشحات بين أقواس: [[email protected] < 10].
- اقرأ عدد التطابقات، ثم جدول التطابقات بالترتيب: كل صف فيه مسار تطابق وقيمته.
- إذا أظهرت رسالة مكان المشكلة، فانظر إلى ذلك الحرف في الاستعلام، وأصلح الأقواس أو علامات الاقتباس أو النقاط.
كيف يختار الاستعلام العقد
الاستعلام قائمة من المقاطع بعد $. يختار المقطع الفرعي مثل .store أو [0] أبناء كل عقدة يصلها، ويزور مقطع الأحفاد مثل ..author العقدة وكل أحفادها قبل أن يختار. وتأتي عقد المقطع الواحد بترتيب المدخل، ويُقرأ المصفوفة دائماً بترتيبها (RFC 9535، القسمان 2.5 و2.5.2.2).
يطابق محدد الاسم عضواً له هذا الاسم بالضبط، وفقط داخل كائن. والفهرس السالب يُعد من نهاية المصفوفة، فـ -1 هو آخر عنصر. والشريحة مثل [1:5:2] تأخذ البداية والنهاية والخطوة، والخطوة 0 لا تختار شيئاً (القسم 2.3.4.2).
المرشحات والدوال وما ترفضه الأداة
المرشح [?...] يختبر كل ابن في مصفوفة أو كائن. وتستخدم المقارنات ==، و!=، و<، و<=، و> و>=، وتجمع &&، و||، و ! الاختبارات، وتجمّعها الأقواس. والعضو الغائب هو Nothing، وقيمتا Nothing متساويتان. وتُقارن الأعداد بالأعداد والنصوص بالنصوص، ولا تتساوى قيمة من نوع مع قيمة من نوع آخر أبداً (القسم 2.3.5.2).
الدوال length وcount وvalue وmatch وsearch مدعومة كما يعرّفها RFC 9535. ويأخذ match وsearch تعبيراً نمطياً بصيغة I-Regexp، وهي صيغة RFC 9485، والنمط غير الصالح كصيغة I-Regexp لا يطابق شيئاً. ولا تدخل المصفوفات والكائنات الحرفية في القواعد، لذلك ترفضها الأداة، وترفض نتيجة الدالة إذا استُخدمت وحدها في مرشح، لأن RFC 9535 يعدّها غير صحيحة النوع.
مثال متجر الكتب
مع مستند المثال والاستعلام $.store.book[[email protected] < 10].title، تكون الكتب الأرخص من 10 هي الأول والثالث. وعناوينهما هي التطابقان أدناه، مع المسار المعياري لكل منهما.
| المسار المعياري | القيمة (JSON) |
|---|---|
| $['store']['book'][0]['title'] | "Sayings of the Century" |
| $['store']['book'][2]['title'] | "Moby Dick" |
الأسئلة الشائعة
لماذا لا يعيد الاستعلام شيئاً مع أن المفتاح موجود؟
يطابق محدد الاسم عضواً في كائن له اسم مطابق تماماً، والمقارنة حساسة لحالة الأحرف. ولا يطابق أبداً عنصراً في مصفوفة، لذلك استخدم فهرساً أو حرف البدل للمصفوفة.
لماذا لا يتساوى 13 و”13“ في المرشح؟
يقارن RFC 9535 القيم من أنواع مختلفة على أنها غير متساوية (القسم 2.3.5.3). فالعدد والنص قيمتان مختلفتان، لذلك تكون == خطأ و!= صحيحة، حتى لو بدت الأحرف متشابهة.
ماذا يختار الفهرس السالب؟
يُعد الفهرس السالب من نهاية المصفوفة: فـ -1 هو آخر عنصر، و-2 هو العنصر الذي قبله. والفهرس الذي يقع خارج المصفوفة لا يختار شيئاً، وليس خطأً (القسم 2.3.3.2).
لماذا ترفض الأداة length(@) إذا كانت وحدها في مرشح؟
تعيد length عدداً، والمرشح يحتاج إلى اختبار صحيح أو خطأ. قارن النتيجة، كما في [?length(@.title) > 15]، فهذا التعبير صحيح النوع.
هل ترسل الأداة JSON الخاص بي إلى خادم؟
لا. يقرأ متصفحك المستند بـ JSON.parse، ويعمل الاستعلام هناك أيضاً، ولا يُخزَّن شيء. ولا تجري الصفحة أي طلب شبكة.
المصادر
- RFC 9535 (باللغة الإنجليزية): JSONPath: Query Expressions for JSON, sections 1.5, 2.3, 2.4, 2.5 and 2.7
- RFC 9485 (باللغة الإنجليزية): I-Regexp: An Interoperable Regular Expression Format, sections 3 and 5.3
آخر مراجعة للأرقام والنص: الثلاثاء، 30 جمادى الأولى 1448 بعد الهجرة.