REST API - Post

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

📥 المدخلات

Enable Condition — إشارة منطقية لبدء طلب POST عندما تكون True.

Server Address — إدخال نصي لنقطة النهاية الكاملة للخادم (استخدم عنوان URL الكامل يبدأ بـ http:// أو https://).

Response Data ID — اسم مفتاح اختياري لاستخراج حقل محدد من استجابة JSON.

Post Data — الحمولة العامة التي سترسل كـ JSON في جسم الطلب.

📤 المخرجات

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

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

Response — جسم استجابة الخادم أو القيمة المستخرجة عندما يتم توفير Response Data ID.

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

Timeout (s) — عدد الثواني للانتظار قبل انتهاء مهلة الطلب (يمكن ضبطه ليتناسب مع خوادم بطيئة/سريعة).

🎨 الميزات

• طلبات غير متزامنة: عمليات POST تعمل في الخلفية حتى تظل الواجهة الاستجابية.

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

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

⚙️ آلية التشغيل

عندما تكون Enable Condition True ومقدّم Server Address صحيح، ترسل الدالة طلب POST بالـ Post Data. يستخدم الطلب قيمة Timeout (s) المُعدة ويعمل دون حظر واجهة المستخدم. عند استلام استجابة الخادم، تُحدث الدالة مخرجاتها بـ Status Code وError (إن وُجِد) وResponse (أو الحقل المستخرج).

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

1. أدخل نقطة النهاية في Server Address (تضمّن http:// أو https://).

2. وصل أو حضّر الحمولة على مدخل Post Data (استخدم كتل أخرى لبناء بيانات مُنظّمة إذا لزم).

3. استخدم إشارة منطقية على Enable Condition لبدء الإرسال (مثلاً تبديل يدوي أو كتلة شرطية).

4. اختياريًا ضع Response Data ID لاستخراج حقل محدد من استجابة JSON.

5. عدّل Timeout (s) إذا كان الخادم بطيئًا أو لتجنب الانتظار الطويل.

💡 نصائح وحيل

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

• حضّر الحمولات المُنظّمة باستخدام Data to JSON قبل توصيلها إلى Post Data لضمان تنسيق JSON صحيح.

• استخدم String Input لتزويد Server Address أو Number Input للحقول الرقمية داخل الحمولة.

• سجّل أو خزّن الاستجابات باستخدام CSV Export أو Image Logger (إذا كانت الحمولة/الاستجابة تحتوي صورًا أو طوابع زمنية).

• اجمعها مع REST API - Get عندما تحتاج إلى كلتا العمليتين POST و GET مع نفس الخدمة (مثلاً: إرسال بيانات ثم الاستعلام عن النتائج).

• أضِف Date-Time أو Date-Time List إلى الحمولة لوضع طابع زمني على الطلبات.

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

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

• لا توجد استجابة / خطأ في الشبكة: تحقق أن Server Address صحيح، ويمكن الوصول إليه من الجهاز، ويتضمن البروتوكول (http/https). افحص إعدادات الجدار الناري أو الشبكة.

• تتطلب مصادقة: تأكد أن واجهة الواجهة تقبل POST بدون مصادقة أو قم بتوفير آلية المصادقة المطلوبة خارج هذه الدالة (مثلاً عبر رؤوس يديرها الخادم).

• JSON غير صالح أو استجابة غير متوقعة: استخدم Data to JSON للتأكد من صحة الحمولة كـ JSON، وتحقّق من وثائق الـ API لأسماء الحقول المتوقعة. إذا طلبت Response Data ID وكان الحقل مفقودًا فقد يكون مخرج Response فارغًا.

• انتهاء المهلة: زِد قيمة Timeout (s) للنقاط الطرفية البطيئة أو تحقق من حمل الخادم. إذا كانت الطلبات تنتهي مهلاتها بشكل متكرر، اختبر الخدمة بشكل مستقل للتأكد من استجابتها.

• تكرار المحفزات: إذا أردت إرسال POST واحد لكل حدث، استخدم Rising Edge لتحويل إشارة True مستمرة إلى محفز لمرة واحدة.

إذا رغبت أمثلة على كيفية ربط هذه الدالة مع تنسيق البيانات، التسجيل أو عناصر تحكم المحفزات، فاجمعها مع كتل مثل Data to JSON, Logic Input, Rising Edge, CSV Export و REST API - Get لأنماط التكامل الشائعة.