> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/arabic/alblwkat-alwzyfyh/blocks-reference/input-output/communication/rest-api-post.md).

# 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` لأنماط التكامل الشائعة.