ToolDeck

تستر JSONPath

عبارت‌های JSONPath را روی داده‌های JSON آزمایش کنید و نتایج تطبیق را مشاهده کنید

یک مثال امتحان کنید

ورودی JSON

نتایج

به‌صورت محلی اجرا می‌شود · جای‌گذاری اسرار امن است
نتایج اینجا نمایش داده می‌شوند…

JSONPath چیست؟

JSONPath یک زبان پرس‌وجو برای استخراج مقادیر از اسناد JSON است. این زبان در سال ۲۰۰۷ توسط Stefan Goessner به عنوان معادلی برای XPath در XML پیشنهاد شد و به شما امکان می‌دهد عبارت‌هایی مانند $.store.book[*].author بنویسید تا همه فیلدهای نویسنده درون یک آرایه کتاب را بدون نوشتن حلقه یا کد پیمایش دستی انتخاب کنید. این زبان در فوریه ۲۰۲۴ به عنوان RFC 9535 توسط IETF استانداردسازی شد.

یک عبارت JSONPath همیشه با $ شروع می‌شود که ریشه سند را نشان می‌دهد. از آنجا می‌توانید انتخابگرها را زنجیر کنید: نشانه‌گذاری نقطه‌ای برای کلیدهای شیء، نشانه‌گذاری براکتی برای شاخص‌های آرایه، wildcard برای همه فرزندان، و recursive descent (..) برای جستجو در همه سطوح تودرتویی. عبارت‌های فیلتر مانند [?(@.price < 10)] به شما اجازه می‌دهند عناصر را بر اساس شرایط ارزیابی شده روی مقادیرشان انتخاب کنید.

JSONPath در ابزارهای تست API مانند Postman، پلتفرم‌های observability مانند Datadog و Splunk، موتورهای گردش کار مانند Apache NiFi، و کتابخانه‌های برنامه‌نویسی در JavaScript، Python، Go، Java و C# استفاده می‌شود. آزمایش عبارت‌های خود روی داده‌های واقعی پیش از تعبیه آن‌ها در کد یا فایل‌های پیکربندی، از خرابی‌های بی‌صدا هنگامی که ساختار JSON با فرض‌های شما مطابقت ندارد جلوگیری می‌کند.

چرا از این تستر JSONPath استفاده کنیم؟

نوشتن عبارت‌های JSONPath به صورت دستی مستعد خطا است. یک نقطه گم‌شده، نوع براکت اشتباه، یا نحو فیلتر نادرست می‌تواند نتایج خالی بدون هیچ پیام خطایی برگرداند. این ابزار بازخورد بصری فوری درباره آنچه عبارت شما با آن تطابق دارد به شما می‌دهد.

نتایج فوری
JSON را بچسبانید، یک عبارت بنویسید، و مقادیر تطبیق‌یافته را بلادرنگ ببینید. نیازی به اجرای اسکریپت یا بارگذاری مجدد صفحه برای بررسی پرس‌وجوی خود نیست.
🔒
حریم خصوصی اول
همه ارزیابی‌ها در مرورگر شما اجرا می‌شوند. داده‌های JSON شما هرگز از دستگاهتان خارج نمی‌شوند، بنابراین می‌توانید با خیال راحت عبارت‌ها را روی پاسخ‌های API تولیدی یا فایل‌های پیکربندی حاوی credential آزمایش کنید.
📋
کپی مستقیم نتایج
خروجی تطبیق‌یافته را با یک کلیک به صورت JSON کپی کنید. آن را در assertion های تست، مستندات، یا مثال‌های پاسخ API بدون قالب‌بندی مجدد بچسبانید.
🛠️
بدون نیاز به راه‌اندازی
نیازی به نصب پکیج‌های npm یا ایجاد محیط‌های مجازی Python نیست. صفحه را باز کنید، داده‌هایتان را بچسبانید، و شروع به پرس‌وجو کنید. روی هر دستگاهی با مرورگر کار می‌کند.

موارد استفاده از JSONPath

توسعه فرانت‌اند
مقادیر تودرتوی مورد نیاز را از پاسخ‌های API قبل از اتصال آن‌ها به state ری‌اکت یا computed property های ویو استخراج کنید. ابتدا عبارت‌های مسیر خود را روی payload واقعی API آزمایش کنید.
تست API بک‌اند
Postman و REST-assured از JSONPath برای assert کردن بدنه‌های پاسخ استفاده می‌کنند. عبارت‌های assertion خود را اینجا بسازید و تأیید کنید، سپس آن‌ها را در اسکریپت‌های تست کپی کنید تا چرخه‌های debug کاهش یابد.
پیکربندی DevOps
تعریف منابع سفارشی Kubernetes، AWS Step Functions، و منابع داده Terraform عبارت‌های JSONPath را برای استخراج مقادیر از خروجی‌های JSON می‌پذیرند. مسیر خود را قبل از استقرار اعتبارسنجی کنید.
اتوماسیون تست QA
assertion های مبتنی بر JSONPath را برای تست‌های قراردادی و تست‌های یکپارچه‌سازی بنویسید. تأیید کنید که عبارت‌هایتان وقتی ساختار JSON دارای فیلدهای اختیاری یا nullable است، مقادیر مورد انتظار را درست تطبیق می‌دهند.
استخراج در pipeline داده
Apache NiFi، Logstash و اسکریپت‌های ETL سفارشی از JSONPath برای استخراج فیلدها از داده‌های log نیمه‌ساختاریافته و جریان‌های رویداد استفاده می‌کنند. عبارت‌ها را روی نمونه payload ها قبل از استقرار pipeline آزمایش کنید.
یادگیری و آزمایش
دانشجویان و توسعه‌دهندگانی که تازه با JSONPath آشنا می‌شوند می‌توانند عبارت‌های مختلف را روی JSON نمونه امتحان کنند تا بدون نیاز به محیط محلی بفهمند کاراکترهای جایگزین، نزول بازگشتی و فیلترها چگونه کار می‌کنند.

مرجع نحو JSONPath

RFC 9535 نحو استاندارد JSONPath را تعریف می‌کند. جدول زیر عملگرهایی را که در اکثر پرس‌وجوها استفاده می‌کنید پوشش می‌دهد. همه عبارت‌ها با $ (گره ریشه) شروع می‌شوند و یک یا چند انتخابگر را برای پیمایش ساختار سند زنجیر می‌کنند.

عملگرتوضیحمثال
$Root element$.store
.keyChild 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 مستقل با زبان فیلتر Turing-complete خودش است. XPath روی XML عمل می‌کند و بخشی از مجموعه مشخصات W3C است.

ویژگیJSONPathjqXPath
فرمت دادهJSONJSONXML
دسترسی به اولین عنصر$.store.book[0].store.book[0]/store/book[1]
جستجوی بازگشتی$..price.. | .price?//price
عبارت فیلتر[?(@.price<10)]select(.price < 10)[price<10]
مشخصاتRFC 9535stedolan.github.ioW3C 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 است که شامل شرط‌بندی‌ها، توابع و string interpolation می‌شود. از JSONPath زمانی استفاده کنید که به پرس‌وجوی تعبیه‌شده در کد یا ابزاری مثل Postman نیاز دارید. از jq برای تبدیل داده‌های خط فرمانی موقتی استفاده کنید.
آیا JSONPath یک استاندارد رسمی است؟
بله. IETF در فوریه ۲۰۲۴ RFC 9535 («JSONPath: عبارت‌های پرس‌وجو برای JSON») را منتشر کرد. پیش از آن، JSONPath تنها به عنوان یک مشخصات غیررسمی توسط Stefan Goessner از سال ۲۰۰۷ وجود داشت که به ناسازگاری‌هایی بین پیاده‌سازی‌ها منجر شد. RFC 9535 نحو، معناشناسی و یک فرمت نرمال‌سازی برای قابلیت همکاری را تعریف می‌کند.
recursive descent (..) در JSONPath چگونه کار می‌کند؟
recursive descent (..) هر سطحی از سند JSON را برای کلیدی که به دنبال آن می‌آید جستجو می‌کند. به عنوان مثال، $..price همه مقادیر مرتبط با کلید «price» را صرف‌نظر از عمق تودرتویی آن‌ها برمی‌گرداند. معادل depth-first traversal است که گره‌های تطبیق‌یافته را جمع‌آوری می‌کند. توجه داشته باشید که در اسناد بزرگ، نزول بازگشتی می‌تواند نتایج زیادی برگرداند و ممکن است از مسیر مستقیم کندتر باشد.
آیا JSONPath می‌تواند داده‌های JSON را تغییر دهد؟
خیر. JSONPath یک زبان پرس‌وجوی فقط‌خواندنی است. مقادیر را انتخاب و برمی‌گرداند اما نمی‌تواند گره‌ها را درج، به‌روزرسانی یا حذف کند. برای تغییر JSON بر اساس یک عبارت JSONPath، باید از توابع دستکاری JSON زبان برنامه‌نویسی خود پس از پرس‌وجو استفاده کنید. برخی کتابخانه‌ها مثل jsonpath-ng در Python یک متد set() روی اشیاء match ارائه می‌دهند، اما این یک افزونه کتابخانه است، نه بخشی از مشخصات JSONPath.
نماد @ در عبارت‌های فیلتر JSONPath به چه معناست؟
نماد @ به گره فعلی در حال ارزیابی در یک عبارت فیلتر اشاره می‌کند. در $.store.book[?(@.price < 10)]، فیلتر روی هر عنصر آرایه book تکرار می‌شود، و @ هر شیء کتاب را به نوبت نمایش می‌دهد. @.price به فیلد price کتاب فعلی دسترسی پیدا می‌کند. بدون @، فیلتر نمی‌داند خواص کدام گره را باید بررسی کند.
چگونه با کلیدهایی که کاراکترهای خاص یا فاصله دارند در JSONPath کار کنم؟
از نشانه‌گذاری براکتی با نقل‌قول استفاده کنید: $['store']['book title']. نشانه‌گذاری براکتی برای هر کلیدی، از جمله کلیدهایی با نقطه، فاصله یا کاراکترهای Unicode کار می‌کند. نشانه‌گذاری نقطه‌ای ($.store.key) فقط برای کلیدهایی که شناسه‌های معتبر هستند (حروف، اعداد، زیرخط) کار می‌کند. RFC 9535 از پیاده‌سازی‌ها می‌خواهد که هر دو نشانه‌گذاری براکتی با نقل‌قول تک و دوتایی را پشتیبانی کنند.
چرا عبارت JSONPath من نتایج خالی برمی‌گرداند؟
شایع‌ترین دلایل عبارتند از: اشتباه تایپی در نام کلید (JSONPath به حروف بزرگ و کوچک حساس است)، استفاده از نشانه‌گذاری نقطه‌ای برای کلیدی که کاراکترهای خاص دارد، فراموش کردن نماد ریشه $ در ابتدا، یا فرض اینکه یک مقدار آرایه است در حالی که یک شیء تکی است. JSON خود را در یک ابزار تست بچسبانید و ابتدا زیرعبارت‌های ساده‌تر (مانند $.store) را امتحان کنید تا هر بخش از مسیرتان را قبل از افزودن انتخابگرهای بیشتر تأیید کنید.