في المرة الأولى التي كتبت فيها تعبير JSONPath المهم، أخطأت في فهمه ثلاث مرات قبل أن يعمل، ولم أكن أعلم أنه كان خاطئًا إلا لأن بوابة API التي كنت أقوم بتكوينها أعادت سياسة فارغة بدلاً من الحقل الذي أردته. لم تكن هناك حلقة ردود فعل. سأقوم بتحرير التعبير وإعادة النشر والانتظار. بمجرد أن بدأت في إبقاء جهاز اختبار JSONPath مفتوحًا في علامة تبويب أخرى، استغرق نفس العمل دقيقتين بدلاً من فترة ما بعد الظهر. يدور هذا الدليل حول كيفية استخدام اختبار JSONPath في Toolz.dev، ما يفعله بناء الجملة فعليًا، والفخاخ الصغيرة التي تجعل التعبير لا تُرجع شيئًا عندما تكون متأكدًا من أنه يجب أن يتطابق.
ليرة تركية؛DR: JSONPath هي لغة استعلام لـ JSON، كما هو الحال مع XPath لـ XML. يقوم أحد مختبري JSONPath بتقييم تعبير مثل
$.store.book[*].authorمقابل مستند وإرجاع كل قيمة مطابقة بالإضافة إلى مسارها. ال اختبار JSONPath قم بذلك بالكامل في متصفحك، مع دعم أحرف البدل، والنسب العودي، والشرائح، والاتحادات، وتعبيرات التصفية، حتى تتمكن من إنشاء استعلام وتصحيح أخطائه مقابل البيانات الحقيقية قبل لصقه في التعليمات البرمجية.
ما هو JSONPath؟
JSONPath عبارة عن بناء جملة مدمج لتحديد أجزاء من مستند JSON. تكتب مسارًا قصيرًا يصف مسارًا عبر البيانات، ويقوم تقييمه بإرجاع القيمة أو القيم على هذا المسار. الفكرة تأتي من ستيفان جوسنر '؛s اقتراح 2007، والذي يعكس XPath عمدًا حتى يشعر أي شخص استفسر عن XML بأنه في بيته. لسنوات لم تكن هناك مواصفات رسمية، فقط تلك المقالة ومجموعة من التطبيقات التي وافق معظمها، وفي أوائل عام 2024 نشرت IETF RFC 9535 لتثبيت القواعد.
تقابل JSONPath أكثر مما قد تتوقع. إنها لغة التحديد في أدوات اختبار API مثل Postman وKarate في Kubernetes kubectl تنسيق الإخراج، في AWS CloudWatch وStep Functions، وفي معالجات السجل، وفي العشرات من الأنظمة الأساسية ذات التعليمات البرمجية المنخفضة حيث يحتاج المستخدم إلى سحب حقل واحد من حمولة خطاف الويب دون كتابة التعليمات البرمجية. تعلم ذلك مرة واحدة يسدد كل ذلك.
النموذج العقلي بسيط. وثيقة JSON عبارة عن شجرة. الكائنات لها فروع مسماة، والمصفوفات لها فروع مرقمة، والأوراق هي قيمك العددية. تعبير JSONPath عبارة عن مجموعة من الاتجاهات للمشي على تلك الشجرة، والنتيجة هي كل ورقة أو شجرة فرعية تهبط عليها. حيث يصبح الأمر قويًا هو أن تعبيرًا واحدًا يمكن أن يهبط في العديد من الأماكن في وقت واحد.
ماذا يفعل مختبر JSONPath بالفعل؟
يأخذ المُختبر مدخلين، JSON الخاص بك والتعبير، ويظهر لك كل عقدة يختارها التعبير. يبدو ذلك واضحًا، لكن القيمة موجودة في التعليقات. عندما لا يُرجع التعبير شيئًا، أو يُرجع أكثر مما توقعت، يقوم المُختبر بتحويل لعبة التخمين إلى فحص لمدة ثانيتين، لأنه يمكنك معرفة العقد المتطابقة بالضبط وضبط حرف واحد في كل مرة.
في Toolz.dev التدفق قصير. لصق مستند JSON، أو تحميل نموذج المكتبة التي تستخدمها معظم برامج JSONPath التعليمية، واكتب تعبيرًا، وقم بتقييمه. تسرد الأداة كل قيمة متطابقة بعدد قيد التشغيل، ويمكنك تبديل الإخراج بين ثلاث طرق عرض. تمنحك القيم النتائج فقط كمصفوفة JSON. تمنحك المسارات الموقع الطبيعي لكل تطابق، وهي أسرع طريقة لاكتشاف التعبير الذي تحتاجه بالفعل. تمنحك الإدخالات كليهما معًا، حتى تتمكن من رؤية المسار والقيمة جنبًا إلى جنب.
سبب الاختبار مقابل البيانات الحقيقية بدلاً من السبب وراء ذلك في رأسك هو أن JSON من البرية أكثر فوضوية من الأمثلة. يكون الحقل أحيانًا كائنًا وأحيانًا مصفوفة. المفتاح الذي توقعته مفقود في نصف السجلات. وصل الرقم كسلسلة. يؤدي تشغيل التعبير على سطح الحمولة الفعلية إلى ظهور تلك المفاجآت على الفور بدلاً من وقت النشر.
كيف يمكنني تحديد العناصر من المصفوفة؟
المصفوفات هي المكان الذي يحدث فيه معظم عمل JSONPath، وهناك أربع طرق لمعالجتها.
فهرس واحد يختار عنصرا واحدا. $.store.book[0] يُرجع الكتاب الأول، ويتم احتساب JSONPath، مثل معظم اللغات، من الصفر. الفهرس السلبي مهم من النهاية، لذلك $.store.book[-1] إرجاع الكتاب الأخير دون الحاجة إلى معرفة عدد الكتب الموجودة. يعد هذا النموذج السلبي مفيدًا حقًا عندما تريد أحدث عنصر في السجل أو أحدث إدخال في الخلاصة.
يحدد حرف البدل كل عنصر. $.store.book[*] إرجاع جميع الكتب الأربعة، و $.store.book[*].author يُرجع مؤلف كل منها، مما يمنحك مجموعة نظيفة من المؤلفين. يعمل حرف البدل أيضًا على الكائنات، حيث $.store.* إرجاع كل قيمة لكائن المتجر بغض النظر عن المفتاح.
يختار الاتحاد مجموعة محددة. $.store.book[0,2] يُرجع الكتابين الأول والثالث، ونفس بناء جملة الفاصلة يعمل مع الأسماء، لذا $['store']['bicycle'] وتتيح لك المفاتيح المقتبسة بين قوسين معالجة المفاتيح التي تحتوي على مسافات أو علامات ترقيم لا يستطيع نموذج النقطة القيام بها.
تحدد الشريحة نطاقًا، وتستعير Python'؛s start:end:step استمارة. $.store.book[:2] يأخذ الأولين، $.store.book[1:3] يأخذ نطاقًا متوسطًا مع فهرس النهاية حصريًا، $.store.book[::2] يأخذ كل عنصر ثان، و $.store.book[::-1] يعكس المصفوفة. الشرائح هي الجزء الأقل شهرة في بناء الجملة والجزء الذي يحفظ أكبر قدر من الكتابة بمجرد حصولها عليها.
ماذا تفعل النقطة المزدوجة؟
النقطة المزدوجة هي نزول متكرر، وهي الميزة التي تجعل JSONPath يبدو وكأنه بحث وليس مسارًا. $..author يجد كل author مفتاح في أي مكان في المستند، بغض النظر عن مدى عمق تداخله، و $..* إرجاع كل قيمة على كل مستوى. عندما لا تعرف الشكل الدقيق للمستند، أو عندما يظهر نفس الحقل على عدة أعماق، فإن النسب العودي يجدها جميعًا في تعبير واحد.
النظر في عينة المكتبة. $..price إرجاع خمس قيم، أسعار الكتب الأربعة وسعر الدراجة، لأنها تنحدر إلى كل كائن وتجمع كل شيء price يجد. سهل $.store.book[*].price سيتم إرجاع أسعار الكتب الأربعة فقط، لأنها تسير في طريق ثابت. والفرق بين هذين التعبيرين هو الفرق بين طلب الأسعار في مكان معروف وطلب الأسعار في أي مكان.
النسب العودي قوي بما يكفي ليكون خطيرًا، بمعنى أنه يمكن أن يتطابق أكثر مما قصدته. وهذا هو بالضبط سبب أهمية المختبر هنا. يجري $..name مقابل حمولة غير مألوفة وقد تكتشف أنها تتطابق مع اسم مستخدم واسم منتج واسم ملف لم يكن لديك أي فكرة عن مشاركة مفتاح. تخبرك رؤية المسارات في الإخراج بما إذا كان يجب تضييق التعبير قبل الاعتماد عليه.
كيف تعمل تعبيرات التصفية؟
يحتفظ المرشح فقط بالعناصر التي يكون الشرط صحيحًا فيها، ويتم كتابته [?(...)] مع @ الوقوف للعنصر الحالي. $.store.book[?(@.price < 10)] إرجاع الكتب بسعر أرخص من عشرة. داخل الفلتر، يمكنك مقارنة حقل بحرف حرفي مع المشغلين ==، !=، <، <=، >، و >=، اختبار مجرد وجود حقل، ودمج الشروط مع && و ||.
بعض الأمثلة الملموسة توضح الشكل
$.store.book[?(@.category == "fiction")]يختار عناوين الخيال.$.store.book[?(@.price < 10 && @.category == "fiction")]يضيق إلى الخيال الرخيص.$.store.book[?(@.isbn)]يختار فقط الكتب التي تحتوي على رقم ISBN، باستخدام الوجود بدلاً من المقارنة.$.vals[?(@ > 2)]يقوم بتصفية مجموعة عادية من الأرقام، حيث@في حد ذاته يشير إلى العنصر نفسه.
خطأ التصفية الأكثر شيوعًا هو عدم تطابق النوع. في JSON، "12" و 12 هي قيم مختلفة، لذا فإن المرشح الذي يقارن الحقل الرقمي برقم مقتبس، أو حقل سلسلة برقم مجرد، لا يطابق شيئًا بصمت. عندما يفاجئك عامل التصفية، فإن أول شيء يجب التحقق منه هو ما إذا كان الحقل والحرف هما نفس النوع. اختبار التعبير مقابل البيانات الحقيقية، حيث يمكنك رؤية القيم الفعلية، هو كيفية التقاط ذلك في ثوانٍ بدلاً من التقاطه بعد عملية نشر فاشلة.
JSONPath مقابل مؤشر JSON مقابل فرق JSON
تمس هذه الأدوات الثلاث بنية JSON، لكنها تجيب على أسئلة مختلفة، واختيار الأداة الخاطئة يضيع الوقت. وإليك كيفية المقارنة:
| يقترب | الإجابات | المباريات | الأفضل ل |
|---|---|---|---|
| JSONPath | ما هي العقد التي تلبي هذا الاستعلام؟ | صفر أو واحد أو أكثر | استخراج الحقول، وتصفية المصفوفات، واستكشاف الأشكال غير المعروفة |
| مؤشر JSON (RFC 6901) | ماذا يوجد في هذا الموقع بالضبط؟ | دائما واحد بالضبط | الإشارة إلى حقل ثابت واحد، كما في مخطط JSON $ref |
| فرق JSON | ما الذي تغير بين وثيقتين؟ | مجموعة من التغييرات | مقارنة نسختين من نفس البيانات |
مؤشر JSON، محدد في RFC 6901، يعالج مكانًا واحدًا محددًا بمسار مفصول بشرطة مائلة مثل /store/book/0/title، ولا يستخدم أبدًا أحرف البدل أو المرشحات. الوصول إليه عندما تحتاج إلى تسمية حقل واحد بشكل لا لبس فيه. الوصول إلى JSONPath عندما يجب أن يحدد تعبير واحد مجموعة من الحقول. وعندما يكون سؤالك الحقيقي هو ما الذي يختلف بين حمولتين بدلاً من ما يحدده الاستعلام، أ فرق JSON هي الأداة الصحيحة. معرفة أي من الثلاثة تحتاج إليه بالفعل هو نصف المعركة.
لماذا لا يُرجع تعبيري أي نتائج؟
تأتي النتيجة الفارغة دائمًا تقريبًا من أحد الأسباب القليلة، ويتيح لك المختبر استبعادها بسرعة.
الأول هو عدم التطابق الهيكلي. لقد كتبت $.data.items.name متى items عبارة عن مصفوفة، لذلك كنت بحاجة $.data.items[*].name مع حرف البدل. يدخل النموذج النقطي إلى كائن، والمصفوفة ليست كائنًا به name المفتاح، وبالتالي فإن المسار ينتهي. يؤدي تبديل عرض الإخراج إلى المسارات وتحريك التعبير مقطعًا تلو الآخر إلى إظهار المكان الذي يتوقف فيه عن المطابقة بالضبط.
والثاني هو خطأ إملائي أو خطأ في الغلاف. مفاتيح JSON حساسة لحالة الأحرف، لذا $.userId لن يتطابق مع أ userID الحقل والمسافة الزائدة أو الخطأ المطبعي في اسم المفتاح ينتج عنه نفس الشيء الصامت. نظرًا لأن المُختبر يعرض لك المستند بجوار التعبير مباشرةً، فمن السهل اكتشافه.
والثالث، كما هو مذكور أعلاه، هو عدم تطابق نوع المرشح، حيث يتم إجراء مقارنة رقمية مقابل قيمة سلسلة أو العكس. والرابع يفترض وجود مفتاح على كل عنصر عندما يكون موجودًا على بعضها فقط. تعتبر مرشحات النسب والوجود العودية هي العلاجات المعتادة. في كل حالة، يأتي الإصلاح من مراقبة العقد التي يلمسها التعبير، وهو بالضبط الغرض من الاختبار.
إذا قمت بالبناء عبر المكدس بالطريقة التي أقوم بها، والانتقال بين واجهة برمجة تطبيقات Laravel، والواجهة الأمامية لـ React، والنص النصي العرضي لـ Shell، فسيظهر JSONPath في الثلاثة، ويكون المختبر المستند إلى المتصفح والذي لا يقوم بتحميل بياناتك أبدًا هو الأداة التي أحتفظ بها الأقرب. لقد كتبت عن كيفية تناسب الأدوات المساعدة مثل هذه مع مجموعة أوسع في مجموعة أدوات مطور الويبوحالة الحفاظ على هذا النوع من العمل من جانب العميل هي في خصوصية البيانات في الأدوات عبر الإنترنت مرشد.
كيف يتناسب هذا مع بقية سير عمل JSON الخاص بي؟
نادرًا ما يكون جهاز اختبار JSONPath هو الأداة الوحيدة المفتوحة. عندما يصل JSON الذي أقوم بالاستعلام عنه مصغرًا أو بمسافة بادئة غير متناسقة، أقوم بتشغيله من خلال تنسيق JSON أولاً حتى أتمكن من قراءة البنية أثناء كتابة التعبير. المنسق والمختبر معًا هما الطريقة التي أنتقل بها من استجابة واجهة برمجة التطبيقات غير القابلة للقراءة إلى استعلام عمل.
بمجرد أن أعرف الحقول التي أهتم بها، غالبًا ما تكون الخطوة التالية هي إعادة تشكيلها. إذا كنت بحاجة إلى تغذية القيم المحددة في جدول بيانات أو ملف بيئة، فإن JSON فلاتنر يحول البنية المتداخلة إلى مفاتيح تدوين نقطية، ويكون بناء جملة المسار الخاص بها قريبًا بدرجة كافية من JSONPath بحيث يعزز الاثنان بعضهما البعض. إذا كنت أقوم ببناء نوع للبيانات في TypeScript، فإن json إلى TypeScript يقوم المحول بإنشاء الواجهة، وإذا كنت بحاجة إلى التحقق من صحة الشكل بدلاً من قراءته فقط، فإن مولد مخطط JSON ينتج مخططًا يمكنني إضافة قيود إليه. JSONPath هي خطوة الاستكشاف؛ هذه الأدوات هي ما أفعله بما أجده.
تستحق نقطة الخصوصية التكرار لأن عمل JSONPath يحدث غالبًا مقابل البيانات الحساسة. تحمل استجابات واجهة برمجة التطبيقات الرموز المميزة وسجلات المستخدم والمعرفات الداخلية، ولصقها في أداة من جانب الخادم يعني الثقة بشخص آخر وسجلات #39؛s. نظرًا لأن جهاز اختبار Toolz.dev يقوم بالتوزيع والتقييم بالكامل في متصفحك، فلا يترك أي من ذلك جهازك، وتستمر الأداة في العمل مع الشبكة غير متصلة. هذا هو الفرق بين الأداة التي يمكنك استخدامها على حمولة مرحلية وأداة يمكنك استخدامها على الشيء الحقيقي.
الأسئلة المتداولة
ما هي استخدامات JSONPath؟
يتم استخدام JSONPath لتحديد واستخراج أجزاء من مستند JSON بتعبير واحد. إنها لغة الاستعلام في أدوات اختبار API، وتنسيق مخرجات Kubernetes، والخدمات السحابية مثل AWS Step Functions، والعديد من الأنظمة الأساسية ذات التعليمات البرمجية المنخفضة، حيثما يحتاج شخص ما إلى سحب حقل أو تصفية مصفوفة من حمولة JSON دون كتابة تعليمات برمجية إجرائية.
كيف يمكنني تحديد كل عنصر من عناصر المصفوفة في JSONPath؟
استخدم حرف البدل، لذلك $.items[*] إرجاع كل عنصر من عناصر مصفوفة العناصر و $.items[*].id إرجاع معرف كل. يمكنك أيضًا تحديد عنصر واحد عن طريق الفهرس باستخدام $.items[0]، العنصر الأخير ذو المؤشر السلبي $.items[-1]، مجموعة مع اتحاد مثل $.items[0,2]، أو نطاق مع شريحة مثل $.items[1:3].
ماذا تعني النقطة المزدوجة في JSONPath؟
النقطة المزدوجة هي نزول متكرر، والذي يبحث في أي عمق. $..author يجد مفتاح كل مؤلف في أي مكان في المستند بغض النظر عن مدى تداخله، و $..* إرجاع كل قيمة على كل مستوى. إنها أسرع طريقة لسحب حقل من مستند لا تعرف بنيته الدقيقة مسبقًا.
كيف تعمل تعبيرات التصفية في JSONPath؟
مرشح [?(...)] يحتفظ فقط بالعناصر التي ينطبق عليها الشرط، مع @ بالإشارة إلى العنصر الحالي. على سبيل المثال $.book[?(@.price < 10)] إرجاع الكتب بسعر أرخص من عشرة، ويمكنك الجمع بين الشروط && و ||، مثل [?(@.price < 10 && @.category == "fiction")]. يمكنك أيضًا اختبار وجود الحقل '؛s مع [?(@.isbn)].
لماذا لا يُرجع تعبير JSONPath الخاص بي شيئًا؟
السببان الأكثر شيوعًا هما عدم التطابق الهيكلي وعدم تطابق النوع. تأكد من وجود كل مفتاح ومكتوب بالغلاف الدقيق، وأنك استخدمت حرف بدل حيث تكون البيانات عبارة عن مصفوفة وليست كائنًا. في المرشحات، تذكر ذلك "؛12"؛ و12 قيمة مختلفة، لذا قارن حقل السلسلة بقيمة مقتبسة وحقلًا رقميًا برقم مجرد.
ما الفرق بين JSONPath وJSON Pointer؟
يتناول مؤشر JSON موقعًا واحدًا محددًا، مثل/store/book/0/title، ويقوم دائمًا بإرجاع قيمة واحدة. JSONPath هي لغة استعلام حيث يمكن لتعبير واحد أن يطابق العديد من العقد في وقت واحد من خلال أحرف البدل والنسب العودي والمرشحات. استخدم مؤشرًا للإشارة إلى حقل ثابت واحد، وJSONPath لتحديد مجموعة من الحقول أو تصفية مجموعة.
هل يمكنني رؤية مسار كل مباراة، وليس القيمة فقط؟
نعم. قم بتبديل وضع الإخراج إلى المسارات للحصول على الموقع الطبيعي لكل مطابقة، أو الإدخالات لتجميع المسار والقيمة معًا. إن رؤية المسارات الحقيقية هي أسرع طريقة لتحسين التعبير حتى يحدد العقد التي قصدتها بالضبط، وهو أمر مفيد بشكل خاص مع النسب العودي.
هل يتم تحميل JSON الخاص بي عندما أستخدم جهاز الاختبار؟
لا. يتم تحليل المستند وتقييم التعبير في متصفحك باستخدام JavaScript، لذلك لا يتم نقل أي شيء أو تسجيله أو تخزينه. يمكنك تأكيد ذلك من خلال مشاهدة علامة تبويب الشبكة أثناء تشغيل استعلام، أو عن طريق قطع الاتصال بالإنترنت، لأن المختبر يستمر في العمل دون اتصال بمجرد تحميل الصفحة.
جربه على بياناتك الخاصة مجانًا اختبار JSONPath. يقوم بتقييم أحرف البدل، والنسب العودي، والشرائح، والاتحادات، وتعبيرات التصفية بالكامل في متصفحك، دون تحميل أي شيء.
