ما هو JSONPath؟
JSONPath هي لغة استعلام لاستخراج القيم من مستندات JSON. اقترحها أصلًا Stefan Goessner عام 2007 كبديل لـ XPath في XML، وتتيح لك JSONPath كتابة تعبيرات مثل $.store.book[*].author لتحديد جميع حقول المؤلف داخل مصفوفة كتب دون كتابة حلقات أو كود اجتياز يدوي. وقد تم توحيد هذه اللغة في فبراير 2024 كـ RFC 9535 الصادر عن IETF.
يبدأ تعبير JSONPath دائمًا بـ $ الذي يمثل جذر المستند. ومن هناك تتتابع المحددات: الترميز النقطي لمفاتيح الكائنات، والترميز بالأقواس لمؤشرات المصفوفات، وأحرف البدل لجميع العناصر الفرعية، وعامل النزول العودي (..) للبحث في كل مستويات التداخل. كما تتيح لك تعبيرات التصفية مثل [?(@.price < 10)] تحديد العناصر بناءً على شروط تُقيَّم وفق قيمها.
تُستخدم JSONPath في أدوات اختبار API مثل Postman، ومنصات الرصد مثل Datadog وSplunk، ومحركات سير العمل مثل Apache NiFi، ومكتبات البرمجة عبر JavaScript وPython وGo وJava وC#. يمنع اختبار تعبيراتك على بيانات حقيقية قبل تضمينها في الكود أو ملفات الإعداد حدوث أخطاء صامتة عندما لا يتطابق هيكل JSON مع توقعاتك.
لماذا تستخدم هذا الاختبار لـ JSONPath؟
كتابة تعبيرات JSONPath يدويًا عرضة للأخطاء. نقطة مفقودة، أو نوع قوس خاطئ، أو صياغة تصفية غير صحيحة قد تُعيد نتائج فارغة دون أي رسالة خطأ. تمنحك هذه الأداة نتائج بصرية فورية لما يطابقه تعبيرك.
⚡
نتائج فورية
الصق JSON، اكتب تعبيرًا، وشاهد القيم المطابقة تتجدّد في الوقت الفعلي. لا حاجة لتشغيل سكريبت أو إعادة تحميل الصفحة للتحقق من استعلامك.
🔒
الخصوصية أولًا
يتم تقييم كل شيء في متصفحك. بيانات JSON الخاصة بك لا تغادر جهازك أبدًا، لذا يمكنك بأمان اختبار التعبيرات على ردود API الإنتاجية أو ملفات الإعداد التي تحتوي على بيانات اعتماد.
📋
نسخ النتائج مباشرة
انسخ المخرجات المطابقة بصيغة JSON بنقرة واحدة. الصقها في تأكيدات الاختبار أو التوثيق أو أمثلة ردود API دون الحاجة لإعادة التنسيق.
🛠️
لا يلزم إعداد مسبق
لا حاجة لتثبيت حزم npm أو إنشاء بيئات Python الافتراضية. افتح الصفحة، الصق بياناتك، وابدأ الاستعلام. يعمل على أي جهاز يحتوي على متصفح.
حالات استخدام JSONPath
تطوير الواجهة الأمامية
استخرج القيم المتداخلة التي تحتاجها بالضبط من ردود API قبل ربطها بحالة React أو خصائص Vue المحسوبة. اختبر تعبيرات المسار الخاصة بك على حمولة API الفعلية أولًا.
اختبار API الخلفية
تستخدم Postman وREST-assured لغة JSONPath لتأكيد أجسام الاستجابة. أنشئ تعبيرات التأكيد والتحقق منها هنا قبل نسخها في سكريبتات الاختبار، مما يقلل من دورات التصحيح.
إعداد DevOps
تقبل تعريفات الموارد المخصصة في Kubernetes، وAWS Step Functions، ومصادر بيانات Terraform تعبيرات JSONPath لاستخراج القيم من مخرجات JSON. تحقق من صحة مسارك قبل النشر.
أتمتة اختبار الجودة
اكتب تأكيدات مستندة إلى JSONPath لاختبارات العقود واختبارات التكامل. تحقق من أن تعبيراتك تطابق القيم المتوقعة بشكل صحيح عندما يحتوي هيكل JSON على حقول اختيارية أو قابلة للقيمة الفارغة.
استخراج بيانات خطوط الأنابيب
تستخدم Apache NiFi وLogstash وسكريبتات ETL المخصصة لغة JSONPath لاستخراج الحقول من بيانات السجلات شبه المنظمة ومجاريات الأحداث. اختبر التعبيرات على حمولات عينة قبل نشر خط الأنابيب.
التعلم والتجريب
يمكن للطلاب والمبتدئين في JSONPath تجربة تعبيرات مختلفة على JSON نموذجي لفهم كيفية عمل أحرف البدل والنزول العودي والمرشحات دون الحاجة لبيئة محلية.
مرجع صياغة JSONPath
يحدد RFC 9535 الصياغة المعيارية لـ JSONPath. يغطي الجدول أدناه العوامل التي ستستخدمها في معظم الاستعلامات. تبدأ جميع التعبيرات بـ $ (العقدة الجذرية) وتسلسل محددًا أو أكثر للتنقل في هيكل المستند.
| العامل | الوصف | مثال |
|---|---|---|
| $ | Root element | $.store |
| .key | Child property | $.store.book |
| [n] | Array index (zero-based) | $.store.book[0] |
| [*] | All elements in array/object | $.store.book[*] |
| .. | Recursive descent | $..author |
| [start:end] | Array slice | $.store.book[0:2] |
| [?()] | Filter expression | $.store.book[?(@.price<10)] |
| @ | Current node (inside filter) | $.store.book[?(@.isbn)] |
مقارنة بين JSONPath وjq وXPath
تحل JSONPath وjq وXPath المشكلة ذاتها (الاستعلام عن البيانات المنظمة) لصيغ وحالات استخدام مختلفة. تستهدف JSONPath صيغة JSON وهي متاحة كمكتبة في معظم اللغات. أما jq فهي أداة CLI مستقلة بلغة تصفية كاملة تورينج. وتعمل XPath على XML وهي جزء من مجموعة مواصفات W3C.
| الميزة | JSONPath | jq | XPath |
|---|---|---|---|
| صيغة البيانات | JSON | JSON | XML |
| الوصول إلى العنصر الأول | $.store.book[0] | .store.book[0] | /store/book[1] |
| البحث العودي | $..price | .. | .price? | //price |
| تعبير التصفية | [?(@.price<10)] | select(.price < 10) | [price<10] |
| المواصفة | RFC 9535 | stedolan.github.io | W3C XPath 3.1 |
أمثلة الكود
كيفية تقييم تعبيرات JSONPath في اللغات والأدوات الشائعة. يستخدم كل مثال هيكل JSON نفسه لمتجر الكتب للمقارنة.
JavaScript (jsonpath-plus)
import { JSONPath } from 'jsonpath-plus';
const data = {
store: {
book: [
{ title: 'Moby Dick', price: 8.99 },
{ title: 'The Great Gatsby', price: 12.99 }
]
}
};
// Get all book titles
JSONPath({ path: '$.store.book[*].title', json: data });
// → ['Moby Dick', 'The Great Gatsby']
// Recursive descent — find every price in the document
JSONPath({ path: '$..price', json: data });
// → [8.99, 12.99]
// Filter — books under $10
JSONPath({ path: '$.store.book[?(@.price < 10)]', json: data });
// → [{ title: 'Moby Dick', price: 8.99 }]Python (jsonpath-ng)
from jsonpath_ng.ext import parse
import json
data = {
"store": {
"book": [
{"title": "Moby Dick", "price": 8.99},
{"title": "The Great Gatsby", "price": 12.99}
]
}
}
# Get all book titles
expr = parse("$.store.book[*].title")
titles = [match.value for match in expr.find(data)]
# → ['Moby Dick', 'The Great Gatsby']
# Recursive descent — all prices
expr = parse("$..price")
prices = [match.value for match in expr.find(data)]
# → [8.99, 12.99]
# Filter — books under $10
expr = parse("$.store.book[?price < 10]")
cheap = [match.value for match in expr.find(data)]
# → [{"title": "Moby Dick", "price": 8.99}]Go (ohler55/ojg)
package main
import (
"fmt"
"github.com/ohler55/ojg/jp"
"github.com/ohler55/ojg/oj"
)
func main() {
src := `{
"store": {
"book": [
{"title": "Moby Dick", "price": 8.99},
{"title": "The Great Gatsby", "price": 12.99}
]
}
}`
obj, _ := oj.ParseString(src)
// Get all book titles
expr, _ := jp.ParseString("$.store.book[*].title")
results := expr.Get(obj)
fmt.Println(results)
// → [Moby Dick The Great Gatsby]
// Recursive descent — all prices
expr2, _ := jp.ParseString("$..price")
fmt.Println(expr2.Get(obj))
// → [8.99 12.99]
}CLI (jq alternative syntax)
# jq uses its own syntax, not JSONPath, but solves the same problem.
# Mapping common JSONPath patterns to jq:
# $.store.book[*].title → get all titles
echo '{"store":{"book":[{"title":"Moby Dick"},{"title":"Gatsby"}]}}' | \
jq '.store.book[].title'
# → "Moby Dick"
# → "Gatsby"
# $..price → recursive descent for "price" keys
echo '{"a":{"price":1},"b":{"price":2}}' | \
jq '.. | .price? // empty'
# → 1
# → 2
# Filter: books where price < 10
echo '{"store":{"book":[{"title":"A","price":8},{"title":"B","price":12}]}}' | \
jq '.store.book[] | select(.price < 10)'
# → {"title":"A","price":8}الأسئلة الشائعة
ما الفرق بين JSONPath وjq؟
JSONPath هي لغة استعلام مصممة للتضمين في التطبيقات كمكتبة. تُعيد القيم المطابقة من مستند JSON باستخدام تعبيرات المسار. أما jq فهي أداة سطر أوامر مستقلة بلغة برمجة كاملة لتحويل JSON، تشمل الشرطيات والدوال واستيفاء السلاسل. استخدم JSONPath عندما تحتاج إلى استعلام مضمن في كود أو أداة مثل Postman. استخدم jq لتحويل البيانات المخصصة عبر سطر الأوامر.
هل JSONPath معيار رسمي؟
نعم. نشرت IETF RFC 9535 ("JSONPath: Query Expressions for JSON") في فبراير 2024. قبل ذلك، كانت JSONPath موجودة فقط كمواصفة غير رسمية من Stefan Goessner منذ عام 2007، مما أدى إلى تناقضات بين التطبيقات. يحدد RFC 9535 الصياغة والدلالات وصيغة التطبيع للتشغيل البيني.
كيف يعمل عامل النزول العودي (..) في JSONPath؟
يبحث عامل النزول العودي (..) في كل مستوى من مستندات JSON عن المفتاح الذي يليه. على سبيل المثال، يُعيد $..price جميع القيم المرتبطة بالمفتاح "price" بغض النظر عن عمق تداخلها. وهو ما يعادل اجتياز العمق الأول الذي يجمع العقد المطابقة. كن على علم بأن النزول العودي على المستندات الكبيرة قد يُعيد نتائج كثيرة وقد يكون أبطأ من المسار المباشر.
هل يمكن لـ JSONPath تعديل بيانات JSON؟
لا. JSONPath هي لغة استعلام للقراءة فقط. تحدد القيم وتُعيدها لكنها لا تستطيع إدراج أو تحديث أو حذف العقد. لتعديل JSON بناءً على تعبير JSONPath، تحتاج إلى استخدام دوال معالجة JSON في لغة البرمجة الخاصة بك بعد الاستعلام. توفر بعض المكتبات مثل jsonpath-ng في Python طريقة set() على كائنات التطابق، لكن هذا امتداد للمكتبة وليس جزءًا من مواصفة JSONPath.
ماذا يعني الرمز @ في تعبيرات مرشح JSONPath؟
يشير الرمز @ إلى العقدة الحالية التي يتم تقييمها في تعبير المرشح. في $.store.book[?(@.price < 10)]، يُطبَّق المرشح على كل عنصر في مصفوفة book، ويمثل @ كل كائن كتاب بدوره. يصل @.price إلى حقل السعر في الكتاب الحالي. بدون @، لن يعرف المرشح خصائص أي عقدة يتحقق منها.
كيف أتعامل مع المفاتيح التي تحتوي على أحرف خاصة أو مسافات في JSONPath؟
استخدم الترميز بالأقواس مع علامات الاقتباس: $['store']['book title']. يعمل الترميز بالأقواس مع أي مفتاح، بما فيها تلك التي تحتوي على نقاط أو مسافات أو أحرف Unicode. لا يعمل الترميز النقطي ($.store.key) إلا مع المفاتيح التي تُعدّ معرفات صالحة (حروف وأرقام وشرطات سفلية). يتطلب RFC 9535 من التطبيقات دعم كل من الترميز بالأقواس المفردة والمزدوجة.
لماذا يُعيد تعبير JSONPath الخاص بي نتائج فارغة؟
أشيع الأسباب هي: خطأ إملائي في اسم المفتاح (JSONPath حساسة لحالة الأحرف)، واستخدام الترميز النقطي لمفتاح يحتوي على أحرف خاصة، وغياب رمز الجذر $ في البداية، أو الافتراض بأن قيمةً ما مصفوفة في حين أنها كائن واحد. الصق JSON في أداة الاختبار وجرب تعبيرات فرعية أبسط أولًا (مثل $.store) للتحقق من أن كل جزء من مسارك يحل بشكل صحيح قبل إضافة محددات أكثر.