REST API - Request

موحد Request block لنداء واجهات برمجة تطبيقات الويب (web APIs). قم بتكوين Method، Headers، Query Params وPayload. اختر وضع التشغيل Async (غير حظرٍ للعملية) أو Sync (انتظار الاستجابة). اختياريًا يمكنك استخراج قيمة من استجابة JSON باستخدام مسار نقطي/مصفوفي (Response Path).

📥 المدخلات

Enable قيمة بوليانية اختيارية لتشغيل الطلب. عندما تكون False يمكن للبلوك تخطي إرسال الطلب (الإعداد الافتراضي True).

Server Address عنوان URL أو endpoint للنداء (مطلوب).

Headers رؤوس اختيارية على شكل قاموس أو سلسلة JSON.

Query Params معاملات استعلام اختيارية على شكل قاموس أو سلسلة JSON.

Payload جسم الطلب الاختياري (سيُرسل وفقًا لطريقة Body Mode المحددة).

Response Path مسار نصي اختياري لاستخراج قيمة من استجابة JSON (أمثلة: data.items[0].id أو items[2]).

(المقابس هنا هي مدخلات)

📤 المخرجات

OK قيمة بوليانية True عندما تشير استجابة HTTP إلى نجاح.

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

Error رسالة خطأ في حال مشاكل الشبكة/HTTP أو أخطاء التحليل.

Response Text نص خام لجسم الاستجابة.

Response JSON كائن JSON محلل عندما يكون متاحًا (وإلا فـ None).

Response Headers خريطة رؤوس الاستجابة.

Elapsed (ms) مدة الطلب بالميلي ثانية.

Extracted Data القيمة المستخرجة من Response JSON باستخدام Response Path (أو None إذا لم توجد).

(المقابس هنا هي مخرجات)

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

Method اختر طريقة HTTP: GET / POST / PUT / PATCH / DELETE.

Body Mode حدد كيفية إرسال Payload: json / form / raw.

Runtime Mode اختر وضع التنفيذ: Async (غير حظر، يحتفظ بآخر نتيجة مكتملة) أو Sync (ينتظر الاستجابة).

Timeout (s) مهلة الطلب بالثواني (القيم غير الصالحة تعود إلى قيمة افتراضية آمنة).

Verify SSL تفعيل/تعطيل التحقق من شهادة TLS (عطّله فقط في بيئات اختبار موثوقة).

⚙️ كيف يعمل

• عندما يكون Enable صحيحًا يبني البلوك الطلب باستخدام Server Address وHeaders وQuery Params وPayload مع Method وBody Mode المختارين.

• في وضع Sync ينتظر البلوك حتى يكتمل الطلب HTTP ويعيد النتيجة الحديثة في نفس دورة التقييم.

• في وضع Async يرسل البلوك الطلب دون حظر؛ يحتفظ البلوك بآخر نتيجة مكتملة ويحدّث المخرجات عند انتهاء الطلب في الخلفية.

• إذا وُفر مسار استخراج JSON في Response Path فسيتم حله ووضعه في Extracted Data إذا وُجد؛ المسار الفارغ لا يؤدي لاستخراج.

• عند أخطاء HTTP أو الشبكة يعرض البلوك رسالة في Error ويضع نتيجة البلوك كغير صالحة لمساعدة على اكتشاف الفشل.

📝 الاستخدام

1. عين Server Address إلى endpoint الخاص بالـ API.

2. قدّم Headers وQuery Params الاختياريين كقواميس أو سلاسل JSON.

3. ضع جسم الطلب في Payload واختر Body Mode (استخدم json للبيانات المهيكلة).

4. اختر Runtime Mode:

   • استخدم Async لتفادي حظر السيناريو (مناسب لواجهات المستخدم/خطوط أنابيب مستمرة).

   • استخدم Sync عندما تحتاج الاستجابة فورًا في نفس التشغيل.

5. (اختياري) أضف Response Path لاستخراج قيمة متداخلة من استجابة JSON للاستخدام لاحقًا.

6. فعّل النداء بتعيين Enable إلى True أو بتغذية مشغل بولياني من بلوكات أخرى.

💡 نصائح وحيل

• حضّر أحمال JSON باستخدام بلوك Data to JSON قبل تغذيتها في Payload للحصول على بنية أنظف وأخطاء تنسيقية أقل.

• استخدم Parse Data Dictionary بعد Response JSON للوصول الآمن إلى حقول الاستجابة وتوجيهها بصريًا إذا فضّلت تحليل القواميس.

• سجّل الاستجابات أو النتائج الدورية باستخدام CSV Export للحفاظ على سجل مؤشَّن بالزمن لتحليل الاستجابات.

• لأغراض تصحيح الأخطاء، أربط Error أو Response Text إلى Debug Input لطباعة أو فحص المخرجات غير المتوقعة.

• امزجه مع Logic Input أو Rising Edge للتحكم بدقة في توقيت إرسال الطلبات (مثلاً الإرسال مرة واحدة لكل حدث).

(البلوكات المقترحة مأخوذة من القائمة المقدّمة)

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

• Server Address فارغ أو غير صالح: تأكد أن Server Address عنوان URL كامل (بما في ذلك البروتوكول إذا لزم الأمر).

• انتهاء مهلة الطلب: زد قيمة Timeout (s) أو تحقق من اتصال الشبكة بالخادم.

• أخطاء التحقق من SSL في بيئات الاختبار: عطّل Verify SSL مؤقتًا فقط إذا كنت تثق بالهدف.

• تحليل JSON غير متوقع: افحص أولاً Response Text؛ استخدم حمولة JSON صالحة واضبط Body Mode إلى json عند إرسال بيانات مهيكلة.

• لا توجد بيانات مستخرجة: تحقق من بنية الاستجابة بفحص Response JSON واضبط Response Path باستخدام تدوين النقاط/الفهارس (مثال: items[0].id).

🔒 الخصوصية والسلامة

كن حذرًا مع البيانات الحساسة في Headers أو Payload (مفاتيح API، كلمات مرور). عند تسجيل الاستجابات أو تصدير البيانات تأكد من إزالة أو إخفاء الحقول الحساسة.

🧭 أمثلة على سيناريوهات

• إرسال بيانات مستشعر دوريًا إلى خدمة ويب وتسجيل عدادات النجاح/الفشل باستخدام CSV Export.

• نشر كائن JSON مهيكل تم إنشاؤه بواسطة Data to JSON ثم تغذية Extracted Data إلى تدفق قرار (Logic Input / حدود).

• استخدم Debug Input لفحص أخطاء الخادم أثناء التطوير قبل الانتقال إلى تسجيل الإنتاج.