REST API - Get

تقوم هذه الدالة بإجراء طلب HTTP GET إلى خادم ويب وتزويد باقي النظام بالنتيجة. استخدمها لجلب بيانات JSON أو نص عادي من نقاط نهاية REST وتمرير الاستجابة إلى كتل أخرى لتحليلها أو تسجيلها أو تخزينها.

📥 المدخلات

Enable Condition عندما تكون True ستحاول الكتلة جلب البيانات من عنوان الخادم المحدد. استخدم هذا للتحكم في توقيت إرسال الطلبات.

Server Address عنوان URL الكامل للخادم أو نقطة النهاية (مثال: https://api.example.com/data).

Response Data ID مفتاح اختياري أو مسار لاستخراج قيمة محددة من استجابة JSON. اتركه فارغًا لإرجاع كامل الاستجابة.

📤 المخرجات

Status Code رمز الحالة HTTP الذي أعاده الخادم.

Error رسالة الخطأ عند فشل الطلب أو عند إرجاع الخادم لخطأ.

Response محتوى استجابة الخادم. قد يكون نصًا عاديًا أو قيمة JSON مُحلَّلة اعتمادًا على نقطة النهاية ووجود Response Data ID.

🕹️ عناصر التحكم

Timeout (s) الوقت الأقصى (بالثواني) للانتظار حتى يستجيب الخادم قبل اعتبار الطلب فاشلاً. القيمة الافتراضية هي 2 ثانية.

🎯 الميزات

• التنفيذ غير المحظور: تُجرى الطلبات دون تجميد واجهة المستخدم، لذا تظل الكتل والعناصر الأخرى مستجيبة أثناء الانتظار.

• استخراج استجابة اختياري: قدّم Response Data ID لاختيار حقل واحد من استجابة JSON عندما تحتاج قيمة محددة فقط.

• تقارير الأخطاء: تُعرض حالات الفشل الشائعة (أخطاء الاتصال، انتهاء المهلة، رموز حالة غير OK) عبر خرج Error وسجل النظام.

• قابلية ضبط المهلة: تمنع الانتظارات الطويلة من إيقاف تدفق العمل عبر ضبط Timeout (s).

📝 تعليمات الاستخدام

1. قدّم إشارة منطقية إلى Enable Condition عندما تريد تشغيل الطلب.

2. أدخل عنوان نقطة النهاية في Server Address.

3. إذا كانت الاستجابة JSON وتحتاج قيمة واحدة فقط، ضع مفتاح JSON المطلوب في Response Data ID (اتركه فارغًا لتلقي الاستجابة كاملة).

4. عدل Timeout (s) إذا كان الخادم بطيئًا أو إذا رغبت في التعامل مع الفشل بسرعة أكبر.

5. اقرأ النتائج من مخارج Status Code, Error, وResponse واربِطها بكتل لاحقة للتحليل أو التخزين أو الإشعار.

📊 التقييم

عند تمكينه وتوفُّر عنوان خادم صالح، تصدر الكتلة طلب GET وتحدّث مخرجاتها عند وصول الاستجابة أو عند حدوث خطأ. إذا لم تكن هناك استجابة متاحة، تُقدّم مخرجات افتراضية حتى تظل الكتل اللاحقة قادرة على العمل.

💡 نصائح وحيل

• لتشغيل طلب واحد عندما تصبح الحالة True لأول مرة، اجمعها مع كتلة Rising Edge لتحويل إشارة True المستمرة إلى زناد واحد.

• إذا احتجت لإرسال POST بعد فحص استجابة GET، زوج هذه الكتلة مع REST API - Post.

• استخدم Parse Data Dictionary أو Data to JSON لاستخراج وتنسيق البيانات المُهيكلة من خرج Response قبل الحفظ أو الإرسال.

• لتسجيل أو حفظ استجابات متكررة من API، اربط المخارج بـCSV Export أو SQL-DB Operations للتخزين الدائم.

• استخدم Debug Input لعرض وفحص المخرجات الخام أثناء التطوير واستكشاف الأخطاء.

• لإرسال البيانات إلى وسطاء رسائل أو أنظمة IoT، اربط النتائج بـMQTT Publish.

🛠️ استكشاف الأخطاء وإصلاحها

• المشكلة: لا توجد استجابة أو انتهاء مهلة.

  • تحقق من عنوان URL في Server Address وتأكد من وجود وصول شبكي إلى الخادم. زِد Timeout (s) للخوادم البطيئة.

• المشكلة: خرج Error يحتوي رمز حالة HTTP أو رسالة.

  • افحص Status Code لمعرفة ما إذا أبلغ الخادم عن خطأ عميل أو خادم (4xx/5xx). تأكد من صحة نقطة النهاية وأي مصادقة مطلوبة مع مزود API.

• المشكلة: الاستجابة JSON لكن القيمة المطلوبة غير موجودة.

  • تحقق من صحة المفتاح أو المسار في Response Data ID. إذا كان التركيب متداخلاً، استخدم كتلة تحليل مثل Parse Data Dictionary للتنقل داخل JSON.

• المشكلة: الطلبات تُنفَّذ بشكل متكرر جدًا أو في أوقات غير مرغوبة.

  • تحكم في توقيت الطلب باستخدام Logic Input, Rising Edge أو كتل تحكم تدفق أخرى لضمان إرسال الطلبات فقط عند الحاجة.