دليل استعلامات JSONPath: كيفية البحث في بيانات JSON

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

ما هو JSONPath؟

JSONPath هي لغة استعلام JSON اقترحها Stefan Goessner في عام 2007. توفر صيغة مضغوطة لاختيار العقد من مستندات JSON، مشابهة لكيفية استهداف محددات CSS لعناصر HTML أو تعبيرات XPath لعقد XML. بدلاً من كتابة حلقات ومنطق شرطي للتنقل في هياكل JSON، تكتب ببساطة تعبيرًا يصف المسار إلى البيانات المطلوبة.

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

مثال مستند JSON

في هذا الدليل، سنستخدم مستند JSON التالي كمثال عملي. هذا هو المثال الكلاسيكي من اقتراح JSONPath الأصلي، مع بيانات إضافية:

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J.R.R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}

مرجع صيغة JSONPath

تستخدم JSONPath مجموعة صغيرة من العوامل التي تتحد لتشكل استعلامات قوية. إليك المرجع الكامل للصيغة:

تعبيرات JSONPath الأساسية

الوصول إلى العقدة الجذرية والعقد الفرعية المباشرة

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

صيغة الأقواس

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

$.store['book'][0]['title']
$['store']['bicycle']['color']

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

عامل البدل (*)

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

النزول التكراري: عامل النقطتين (..)

عامل النقطتين .. هو أحد أقوى ميزات JSONPath. يبحث عن المفتاح المحدد في كل مستوى من شجرة JSON، وليس فقط العقد الفرعية المباشرة. فكر فيه كبحث عميق عبر المستند بأكمله.

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

تقطيع المصفوفات

تقطيع المصفوفات يتيح لك اختيار مجموعة من العناصر من مصفوفة. الصيغة [start:end] تختار العناصر من فهرس البداية إلى (ولكن لا تشمل) فهرس النهاية. الفهارس الموجبة والسالبة مدعومة.

لاحظ أن سلوك التقطيع قد يختلف قليلاً بين تطبيقات JSONPath المختلفة. الصيغة أعلاه تتبع الاصطلاح المستخدم من قبل معظم المكتبات الشائعة ومعيار IETF RFC 9535.

تعبيرات التصفية

تعبيرات التصفية هي حيث تصبح JSONPath قوية حقًا. تتيح لك اختيار العناصر بناءً على الشروط بدلاً من الموضع. صيغة التصفية تستخدم [?(condition)]، حيث يتم تقييم الشرط لكل عنصر.

عوامل المقارنة

تدعم JSONPath عوامل المقارنة التالية في تعبيرات التصفية:

أمثلة تصفية عملية

باستخدام مستند المثال الخاص بنا، إليك تعبيرات تصفية عملية ونتائجها:

Find all books cheaper than $10:

< 10)]

ترجع الكتب 'Sayings of the Century' (8.95 دولار) و 'Moby Dick' (8.99 دولار).

Find all fiction books:

$.store.book[?(@.category == "fiction")]

ترجع ثلاثة كتب: 'Sword of Honour' و 'Moby Dick' و 'The Lord of the Rings'.

Find books with an ISBN:

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

ترجع الكتب التي لها خاصية isbn: 'Moby Dick' و 'The Lord of the Rings'. هذا لأن المرشح يتحقق من وجود الخاصية.

Find the most expensive book:

$.store.book[?(@.price > 20)]

ترجع 'The Lord of the Rings' (22.99 دولار).

العوامل المنطقية في المرشحات

يمكنك دمج الشروط باستخدام العوامل المنطقية:

< 10 && @.category == "fiction")]
$.store.book[?(@.price > 15 || @.category == "reference")]

التعبير الأول يجد كتب الخيال التي يقل سعرها عن 10 دولارات (فقط 'Moby Dick'). الثاني يجد الكتب التي يزيد سعرها عن 15 دولارًا أو تنتمي إلى فئة reference (ترجع 'Sayings of the Century' و 'The Lord of the Rings').

JSONPath مقابل XPath

تم نمذجة JSONPath صراحةً على XPath، وتشترك اللغتان في العديد من أوجه التشابه المفاهيمي. إذا كنت معتادًا على معالجة XML، فإن فهم هذه العلاقة مفيد.

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

تطبيقات JSONPath العملية

اختبار API

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

على سبيل المثال، في اختبار قد تتحقق من أن سعر الكتاب الأول أقل من 10 دولارات:

// Using a JSONPath assertion in testing
response.jsonPath().get("store.book[0].price").should(equals(8.95));

// Find all books by a specific author
response.jsonPath().get("store.book[?(@.author == 'Herman Melville')].title");
// Returns: ["Moby Dick"]

تحويل البيانات

عند دمج أنظمة تستخدم تنسيقات بيانات مختلفة، تساعد JSONPath في استخراج وتحويل حقول محددة. يمكنك استخراج القيم من هيكل JSON وتعيينها إلى آخر دون كتابة كود تنقل معقد.

إدارة التكوين

غالبًا ما تحتوي ملفات التكوين المعقدة على JSON متداخل بعمق. تتيح لك JSONPath الاستعلام عن قيم تكوين محددة دون تحميل وتحليل الهيكل بأكمله. أدوات مثل jq تستخدم صيغة مشابهة لـ JSONPath لمعالجة JSON في خطوط أنابيب سطر الأوامر.

المراقبة والتنبيهات

في أنظمة المراقبة، يمكن لاستعلامات JSONPath استخراج المقاييس من سجلات JSON واستجابات API. يمكنك إعداد تنبيهات تشغل عندما ترجع استعلامات JSONPath قيمًا تتجاوز الحدود.

تطبيقات JSONPath

JSONPath متاحة في كل لغة برمجة تقريبًا. إليك المكتبات الأكثر شيوعًا:

مثال JavaScript

< 10)]',
  json: data
});
// Returns books with price < 10

Python Example

from jsonpath_ng import parse

data = { /* our sample JSON */ }

# Find all authors
author_expr = parse('$..author')
authors = [match.value for match in author_expr.find(data)]
# ["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J.R.R. Tolkien"]

# Find cheap books
cheap_expr = parse('$.store.book[?(@.price < 10)]')
cheap_books = [match.value for match in cheap_expr.find(data)]

Common Pitfalls and Tips

• Zero-based vs one-based indexing: JSONPath uses zero-based indexing (the first element is [0]), while XPath uses one-based indexing (the first element is [1]). This is a common source of off-by-one errors.
• Implementation differences: Before the IETF standard (RFC 9535), JSONPath implementations varied in their handling of edge cases like empty results, null values, and filter syntax. Always test your expressions with the specific library you are using.
• Filter performance: Recursive descent with filters ($..book[?(@.price < 10)]) can be slow on large documents because it must traverse the entire tree. For performance-critical applications, use more specific paths when possible.
• Case sensitivity: JSONPath is case-sensitive. $.Store will not match $.store. This is consistent with JSON's case-sensitive nature.
• الفهرسة من الصفر مقابل الفهرسة من الواحد: تستخدم JSONPath فهرسة من الصفر (العنصر الأول هو [0])، بينما يستخدم XPath فهرسة من الواحد (العنصر الأول هو [1]). هذا مصدر شائع لأخطاء الفرق بواحد.
• اختلافات التطبيقات: قبل معيار IETF (RFC 9535)، اختلفت تطبيقات JSONPath في التعامل مع الحالات الحدية مثل النتائج الفارغة وقيم null وصيغة التصفية. اختبر التعبيرات دائمًا مع مكتبتك المحددة.

المزالق والنصائح الشائعة

في عام 2024، نشرت IETF معيار RFC 9535، الذي وحد JSONPath رسميًا. يعالج المواصفات العديد من الغموض والتناقضات التي كانت موجودة بين التطبيقات. تشمل الجوانب الرئيسية للمعيار:

• < 10)]) يمكن أن يكون بطيئًا على المستندات الكبيرة لأنه يجب أن يتنقل في الشجرة بأكملها. للتطبيقات الحرجة للأداء، استخدم مسارات أكثر تحديدًا كلما أمكن.
• حساسية حالة الأحرف: JSONPath حساسة لحالة الأحرف. $.Store لن يطابق $.store. هذا متسق مع طبيعة JSON الحساسة لحالة الأحرف.
• هروب الأحرف الخاصة: إذا كانت أسماء المفاتيح تحتوي على نقاط أو أقواس، يجب استخدام صيغة الأقواس المقتبسة: $['key.with.dots'] بدلاً من $.key.with.dots.
• لا يوجد تنقل للأصل: على عكس XPath، لا يمكن لـ JSONPath التنقل إلى العقدة الأصلية. لا يوجد مكافئ لـ .. (محور الأصل) في XPath. .. في JSONPath تعني النزول التكراري، وليس الأصل.

إذا كنت تبدأ مشروعًا جديدًا، فضل المكتبات التي تطبق RFC 9535 للحصول على أقصى توافق وسلوك متوقع.