فهم وتحليل استجابات JSON API

أهلاً بك في الدرس الرابع من رحلتنا نحو أتمتة متجرك.

في الدرس السابق، اكتشفنا كيف تُستخدم الـ Webhooks لتلقي إشعارات فورية من YouCan عند وقوع حدث معين، مثل إنشاء طلب جديد. ولاحظنا أن البيانات التي تصلنا عبر الـ Webhook تكون على شكل نص منظم. هذا النص ليس عشوائياً، بل يتبع قواعد محددة جداً.

اليوم، سنغوص في عمق هذا التنسيق ونفصّله. هذا التنسيق يسمى JSON (JavaScript Object Notation)، وهو اللغة العالمية التي تتحدث بها معظم واجهات برمجة التطبيقات (APIs) الحديثة.

بحلول نهاية هذا الدرس، ستتمكن من تحليل استجابة API بصيغة JSON وفهم بنيتها الأساسية. هذه المهارة لا غنى عنها، لأن كل قطعة بيانات ستتعامل معها في رحلة الأتمتة—سواء كانت بيانات منتج من YouCan، أو تفاصيل طلب جديد، أو رقم تتبع من شركة شحن—ستصلك بهذا الشكل. فهمك لهذه "اللغة" هو مفتاح قدرتك على استخراج المعلومات الصحيحة وتوجيهها في مسارات الأتمتة.

1. ما هو JSON ولماذا هو مهم؟

تخيل أنك طلبت من API بيانات منتج. لا يمكنك أن تتوقع من الخادم أن يرسل لك صفحة ويب جميلة ومنسقة. لماذا؟ لأن "المستلم" قد لا يكون متصفح ويب، بل قد يكون تطبيق أتمتة مثل Make.com، أو تطبيق هاتف، أو حتى ساعة ذكية. هذه الأنظمة تحتاج إلى بيانات خام ومنظمة، لا إلى تصميمات وألوان.

لهذا السبب، تم الاتفاق على استخدام تنسيق موحد وخفيف الوزن لتبادل البيانات، وأشهرها هو JSON.

كما قرأت، JSON هو مجرد نص، لكنه نص منظم بطريقة تفهمها الآلات بسهولة. دعنا نحلل هذه البنية.

2. اللبنات الأساسية لهيكل JSON

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

أ) أزواج المفتاح-القيمة (Key-Value Pairs)
هذا هو أساس JSON. كل معلومة تُمثَّل كزوج:

• المفتاح (Key): هو اسم المعلومة (مثل "name" أو "price"). يكون دائمًا نصًا مكتوبًا بين علامتي اقتباس مزدوجتين.
• القيمة (Value): هي المعلومة نفسها. يمكن أن تكون من عدة أنواع:
  • نص (String): مثل "T-shirt".
  • رقم (Number): مثل 19.99.
  • قيمة منطقية (Boolean): إما true أو false.
  • كائن (Object): مجموعة أخرى من أزواج المفتاح-القيمة (لتمثيل البيانات المتداخلة).
  • مصفوفة (Array): قائمة من القيم.

ب) الكائنات (Objects)
الكائن هو مجموعة من أزواج المفتاح-القيمة، يوضع بين قوسين معقوفين { }. يمثل الكائن شيئًا واحدًا له عدة خصائص. على سبيل المثال، بيانات منتج واحد هي "كائن".

{
  "name": "ساعة يد فاخرة",
  "price": 450.00,
  "in_stock": true
}

ج) المصفوفات (Arrays)
المصفوفة هي قائمة مرتبة من القيم، توضع بين قوسين مربعين [ ]. تُستخدم لتمثيل مجموعة من العناصر المتشابهة. على سبيل المثال، قائمة منتجات متجرك هي "مصفوفة من الكائنات". أو قائمة مقاسات قميص هي "مصفوفة من النصوص".

[
  { "name": "منتج أ", "price": 100 },
  { "name": "منتج ب", "price": 150 },
  { "name": "منتج ج", "price": 200 }
]

["Small", "Medium", "Large"]

3. تحليل استجابة JSON من متجر حقيقي

النظرية وحدها لا تكفي. بناءً على طلبك للفهم التقني العميق، دعنا نرى كيف تبدو استجابة JSON حقيقية من متجر إلكتروني عند طلب بيانات المنتجات.

كما رأيت في الفيديو، الاستجابة لم تكن مجرد كائن واحد، بل كانت مصفوفة من الكائنات. هذا شائع جداً عندما تطلب قائمة بيانات (مثل كل الطلبات، كل المنتجات).

في بعض الأحيان، تكون البيانات أكثر تعقيداً وتأتي مغلفة داخل كائن رئيسي يحتوي على معلومات إضافية (metadata) مثل حالة الطلب أو عدد النتائج.

هذا التنظيم الدقيق هو ما يسمح لنا باستخراج معلومة محددة. في أدوات الأتمتة مثل Make، ستتعامل مع هذا الهيكل بصريًا. للوصول إلى اسم العميل في طلب ما، قد تتبع مسارًا مثل order.customer.name. فهمك لبنية JSON يجعلك تعرف بالضبط أين تبحث عن كل معلومة.

{
  "id": 12345,
  "status": "confirmed",
  "customer": {
    "name": "أحمد العلي",
    "phone": "971501234567"
  },
  "line_items": [
    {
      "product_id": 987,
      "name": "منتج مميز",
      "quantity": 1
    },
    {
      "product_id": 654,
      "name": "منتج آخر",
      "quantity": 2
    }
  ],
  "shipping_country_code": "AE"
}

4. لماذا هذا الهيكل مهم؟ (نظرة تقنية عميقة)

بما أنك مهتم بالتفاصيل التقنية، من المهم أن تفهم لماذا هذا الهيكل مهم. الأمر لا يتعلق فقط بتنظيم العرض، بل بتمكين الآلات من معالجة البيانات بشكل موثوق.

الخلاصة من هذا المثال بسيطة: البرامج تحول نص JSON إلى كائن برمجي، ثم تستخدم أسماء المفاتيح (data.fact في المثال) للوصول إلى البيانات التي تحتاجها.

في منصة Make.com التي سنتعلمها، لن تكتب الكود بنفسك، لكنك ستقوم بنفس العملية بشكل مرئي. ستقوم بسحب "متغيرات" (pills) تمثل هذه المسارات (order.customer.name أو product.price) وربطها بخدمات أخرى (مثل Google Sheets أو WhatsApp). فهمك لهيكل JSON سيجعلك تعرف بالضبط أي "متغير" يجب أن تختاره لإنجاز مهمتك.

خلاصة الدرس

لقد تعلمنا اليوم أساسيات لغة الآلات في عالم الويب الحديث. إليك أهم النقاط:

• JSON هو التنسيق القياسي لتبادل البيانات في واجهات برمجة التطبيقات (APIs).
• يتكون من ثلاثة لبنات أساسية: أزواج المفتاح-القيمة، والكائنات {}، والمصفوفات [].
• يمكن للبيانات أن تكون متداخلة (كائنات داخل كائنات)، مما يسمح بتمثيل معلومات معقدة.
• فهم هذا الهيكل ضروري لاستخراج معلومات محددة بدقة واستخدامها في أنظمة الأتمتة.

الدرس القادم

الآن بعد أن فهمت بنية البيانات التي سنتعامل معها، حان الوقت لنبدأ بطلبها بأنفسنا. في الدرس القادم، سوف نستخدم أداة Postman لإرسال طلبات API بسيطة (GET, POST) ورؤية استجابات JSON هذه تعود إلينا في الوقت الفعلي. من هنا، يبدأ التطبيق العملي الممتع