ForHosting KIT · البيانات والملفات: تحويل وتنظيف

استعلم عن JSON بتعبيرات على نمط JSONPath

استخرج القيم من مستند البيانات بمسار قصير: يعيد $.store.books[*].title القيمتين North وSouth، عنواناً لكل كتاب وبترتيب ظهورهما. والمسار الذي لا يجد شيئاً يعطي قائمة فارغة لا خطأ. مجاناً في متصفحك.

مجاني
يعمل في متصفحك
دون تسجيل
بياناتك لا تغادر جهازك

شغّل الأداة مجانًا اطّلع على الـAPI

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

مثال محلول

إذا أدخلت

المسار: $.store.books[*].title

تحصل على

التطابقات: North, South

تشمل الصياغة المدعومة الخصائص المباشرة والخصائص المقتبسة وفهارس المصفوفات والمحارف البديلة، بينما ترفض عمداً المرشحات والنزول العودي والشرائح والاتحادات والتعبيرات القابلة للتنفيذ. يجعل هذا العقد المحدد النتائج قابلة للتوقع عند تصحيح الأخطاء وإجراء الاختبارات وفحص البيانات وبناء عمليات أتمتة خفيفة.

ابنِ المسار من بداية المستند

يبدأ كل تعبير بالرمز <code>$</code> الذي يمثل المستند المحلل كاملاً. أضيفوا نقطة يتبعها اسم خاصية بسيط، مثل <code>$.customer.name</code>، للتنقل داخل الكائنات. يجب أن يبدأ اسم الخاصية في صياغة النقطة بحرف أو شرطة سفلية، ثم يمكن أن يتضمن حروفاً أو أرقاماً أو شرطات سفلية.

إذا احتوى المفتاح على مسافة أو شرطة أو نقطة أو محرف آخر لا يوافق هذه القاعدة، فاستخدموا خطوة مقتبسة بين قوسين، مثل <code>$['display-name']</code> أو <code>$["shipping address"]</code>. تقبل الخطوة علامتي الاقتباس المفردة والمزدوجة، ويمكن تخطي علامة الاقتباس المطابقة أو الشرطة المائلة العكسية. تُقيّم المسارات من اليسار إلى اليمين، ولا تنتج الخاصية الغائبة قيمة لذلك الفرع.

تتضمن الاستجابة دائماً مصفوفة <code>matches</code> حتى إذا حدد المسار قيمة مفردة واحدة. وبذلك تستطيعون معالجة النتيجة الواحدة ونتائج المحارف البديلة والنتائج الفارغة بالشكل نفسه.

حددوا عناصر المصفوفة ووسعوا المحارف البديلة

استخدموا عدداً صحيحاً غير سالب بين قوسين لتحديد موضع في مصفوفة، مثل <code>$.orders[0].id</code>. تبدأ الفهارس من الصفر، ولذلك يكون فهرس العنصر الأول صفراً، أما الفهرس الذي يتجاوز طول المصفوفة فلا يعطي نتيجة. استخدموا <code>[*]</code> لتوسيع كل عناصر المصفوفة، ثم تابعوا المسار لقراءة حقل من كل عنصر.

فعلى سبيل المثال، يعيد <code>$.store.books[*].title</code> عنوان كل كائن كتاب يملك تلك الخاصية. وتُدعم أيضاً صيغة النقطة <code>.*</code>. يمكن جمع المحارف البديلة مع خطوات خصائص أو فهارس لاحقة، وتُستبعد الفروع التي لا تطابق من دون التأثير في الفروع الأخرى.

لذلك يتبع الترتيب النهائي ترتيب المستند المصدر وتسلسل الاجتياز.

تعرفوا إلى الصياغة غير المدعومة عمداً

تنفذ هذه القدرة لغة صغيرة على نمط JSONPath، ولا تنفذ كل اللهجات المتاحة. فهي ترفض النزول العودي مثل <code>$..name</code>، والمرشحات مثل <code>$[?( @.price < 10)]</code>، والشرائح والاتحادات والفهارس السالبة والتعبيرات النصية والدوال.

هذا الرفض مقصود لأن هذه الميزات تختلف بين المكتبات، ولأن بعضها يسمح بتقييم لا يلائم محللاً حتمياً. أما المسار الصحيح من حيث الصياغة الذي لا يجد شيئاً فليس خطأ؛ بل يعيد مصفوفة <code>matches</code> فارغة. يتيح ذلك لعمليات الأتمتة التمييز بين التعليمات المشوهة والاستعلامات الصحيحة عن بيانات اختيارية غائبة.

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

حالات الاستخدام

إنشاء تأكيدات اختبار مستقرة

اختاروا الحقول التي يحتاجها اختبار الانحدار فقط بدلاً من مقارنة مستند كامل يتغير.

الأسئلة الشائعة

ما ميزات JSONPath المدعومة؟

تشمل المجموعة الفرعية رمز الجذر وخصائص النقطة والخصائص المقتبسة بين قوسين وفهارس المصفوفات غير السالبة والمحارف البديلة.

ماذا يحدث إذا لم يجد المسار أي نتيجة؟

ينجح الطلب ويعيد مصفوفة matches فارغة. تختلف البيانات الغائبة عن صياغة المسار غير الصالحة.

هل يمكن استخدام المرشحات أو النزول العودي؟

لا. تُرفض المرشحات والنزول العودي والشرائح والاتحادات والبرامج النصية والدوال والفهارس السالبة.

كيف أقرأ مفتاحاً يحتوي على مسافة أو شرطة؟

ضع الاسم بين علامتي اقتباس داخل قوسين مربعين، مثل $['display-name'] أو $["shipping address"]. أما النقطة البسيطة فتصلح فقط للأسماء التي تبدأ بحرف أو شرطة سفلية وتتكون من حروف وأرقام وشرطات سفلية.

هل تبدأ مواضع المصفوفة من 0 أم من 1؟

من 0: يقرأ $.orders[0].id الطلب الأول. والموضع الذي يتجاوز طول المصفوفة لا يعطي أي نتيجة لكنه لا يسبب خطأ، ولا تُقبل المواضع السالبة.

أدوات ذات صلة

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/dev2/json-path-query

صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.

استدعِ الخدمة من بيئتك

curl -X POST https://api.kit.forhosting.com/dev2/json-path-query \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"json":"{\"store\":{\"books\":[{\"title\":\"North\",\"price\":12},{\"title\":\"South\",\"price\":18}]}}","path":"$.store.books[*].title"}'

const res = await fetch("https://api.kit.forhosting.com/dev2/json-path-query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "json": "{\"store\":{\"books\":[{\"title\":\"North\",\"price\":12},{\"title\":\"South\",\"price\":18}]}}",
    "path": "$.store.books[*].title"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/dev2/json-path-query",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "json": "{\"store\":{\"books\":[{\"title\":\"North\",\"price\":12},{\"title\":\"South\",\"price\":18}]}}",
    "path": "$.store.books[*].title"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev2/json-path-query", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"json":"{\\"store\\":{\\"books\\":[{\\"title\\":\\"North\\",\\"price\\":12},{\\"title\\":\\"South\\",\\"price\\":18}]}}","path":"$.store.books[*].title"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"json":"{\"store\":{\"books\":[{\"title\":\"North\",\"price\":12},{\"title\":\"South\",\"price\":18}]}}","path":"$.store.books[*].title"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev2/json-path-query", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

مثال على الطلب

{
  "json": "{\"store\":{\"books\":[{\"title\":\"North\",\"price\":12},{\"title\":\"South\",\"price\":18}]}}",
  "path": "$.store.books[*].title"
}

مثال على الاستجابة

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "dev2.json_path_query",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

ملاحظات تقنية

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

ابنوا المسار انطلاقاً من جذر JSON

تعبير الجذر وحده صالح ويعيد قيمة JSON كاملة بوصفها النتيجة الوحيدة.

حددوا عناصر المصفوفة ووسعوا المحارف البديلة

يزور المحرف البديل في الكائن قيم الخصائص وفق ترتيب JSON المعتاد، ويزور عناصر المصفوفة من الأول إلى الأخير. تحتفظ القيم بأنواع JSON الأصلية: تبقى السلاسل سلاسل والأرقام أرقاماً، وتُعاد الكائنات والمصفوفات والقيم المنطقية والقيم الخالية من دون تحويل.

تعرفوا إلى الصياغة غير المدعومة عمداً

تعيد التعبيرات غير المدعومة خطأ <code>invalid_input</code> مع رسالة تحدد مشكلة الصياغة، ولا تُعامل أبداً على أنها مسار صالح جزئياً. ويُرفض JSON غير الصالح بصورة مستقلة قبل بدء الاجتياز. يبدأ سعر API من $0.002 لكل طلب، ويمكن للمتصفح استخدام المنطق الحتمي نفسه.

حالات التكامل

فحص استجابة API

استخرجوا حالة أو معرفاً أو قائمة قيم متداخلة بعمق أثناء تصحيح حمولة الاستجابة.

إعداد أتمتة خفيفة

استخرجوا قيماً من JSON للإعداد أو Webhook أو التصدير قبل تمريرها إلى الخطوة الحتمية التالية.

أسئلة تقنية

هل تتحول القيم المطابقة إلى نص؟

لا. تحتفظ بأنواع JSON، ومنها الأرقام والقيم المنطقية والقيم الخالية والكائنات والمصفوفات.

كم تبلغ تكلفة طلب API؟

يبدأ سعر API من $0.002 لكل طلب. ويمكن أيضاً تشغيل هذه القدرة مجاناً في المتصفح.

اطّلع على توثيق KIT الكامل ←

شغّل الأداة مجانًا

مثال محلول

ابنِ المسار من بداية المستند

حددوا عناصر المصفوفة ووسعوا المحارف البديلة

تعرفوا إلى الصياغة غير المدعومة عمداً

حالات الاستخدام

إنشاء تأكيدات اختبار مستقرة

الأسئلة الشائعة

أدوات ذات صلة

للمطوّرين — الوصول عبر API

الـEndpoint

استدعِ الخدمة من بيئتك

مثال على الطلب

مثال على الاستجابة

الأسعار

الأخطاء

ملاحظات تقنية

ابنوا المسار انطلاقاً من جذر JSON

حددوا عناصر المصفوفة ووسعوا المحارف البديلة

تعرفوا إلى الصياغة غير المدعومة عمداً

حالات التكامل

فحص استجابة API

إعداد أتمتة خفيفة

أسئلة تقنية

شكرًا