> 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-request.md).

# REST API - Request

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

## 📥 المدخلات <a href="#inputs" id="inputs"></a>

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

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

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

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

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

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

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

## 📤 المخرجات <a href="#outputs" id="outputs"></a>

`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 إذا لم توجد).

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

## 🕹️ عناصر التحكم <a href="#controls" id="controls"></a>

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

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

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

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

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

## ⚙️ كيف يعمل <a href="#how-it-works" id="how-it-works"></a>

* عندما يكون `Enable` صحيحًا يبني البلوك الطلب باستخدام `Server Address` و`Headers` و`Query Params` و`Payload` مع `Method` و`Body Mode` المختارين.
* في وضع `Sync` ينتظر البلوك حتى يكتمل الطلب HTTP ويعيد النتيجة الحديثة في نفس دورة التقييم.
* في وضع `Async` يرسل البلوك الطلب دون حظر؛ يحتفظ البلوك بآخر نتيجة مكتملة ويحدّث المخرجات عند انتهاء الطلب في الخلفية.
* إذا وُفر مسار استخراج JSON في `Response Path` فسيتم حله ووضعه في `Extracted Data` إذا وُجد؛ المسار الفارغ لا يؤدي لاستخراج.
* عند أخطاء HTTP أو الشبكة يعرض البلوك رسالة في `Error` ويضع نتيجة البلوك كغير صالحة لمساعدة على اكتشاف الفشل.

## 📝 الاستخدام <a href="#usage" id="usage"></a>

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 أو بتغذية مشغل بولياني من بلوكات أخرى.

## 💡 نصائح وحيل <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* حضّر أحمال JSON باستخدام بلوك `Data to JSON` قبل تغذيتها في `Payload` للحصول على بنية أنظف وأخطاء تنسيقية أقل.
* استخدم `Parse Data Dictionary` بعد `Response JSON` للوصول الآمن إلى حقول الاستجابة وتوجيهها بصريًا إذا فضّلت تحليل القواميس.
* سجّل الاستجابات أو النتائج الدورية باستخدام `CSV Export` للحفاظ على سجل مؤشَّن بالزمن لتحليل الاستجابات.
* لأغراض تصحيح الأخطاء، أربط `Error` أو `Response Text` إلى `Debug Input` لطباعة أو فحص المخرجات غير المتوقعة.
* امزجه مع `Logic Input` أو `Rising Edge` للتحكم بدقة في توقيت إرسال الطلبات (مثلاً الإرسال مرة واحدة لكل حدث).

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

## 🛠️ استكشاف الأخطاء وإصلاحها <a href="#troubleshooting" id="troubleshooting"></a>

* Server Address فارغ أو غير صالح: تأكد أن `Server Address` عنوان URL كامل (بما في ذلك البروتوكول إذا لزم الأمر).
* انتهاء مهلة الطلب: زد قيمة `Timeout (s)` أو تحقق من اتصال الشبكة بالخادم.
* أخطاء التحقق من SSL في بيئات الاختبار: عطّل `Verify SSL` مؤقتًا فقط إذا كنت تثق بالهدف.
* تحليل JSON غير متوقع: افحص أولاً `Response Text`؛ استخدم حمولة JSON صالحة واضبط `Body Mode` إلى `json` عند إرسال بيانات مهيكلة.
* لا توجد بيانات مستخرجة: تحقق من بنية الاستجابة بفحص `Response JSON` واضبط `Response Path` باستخدام تدوين النقاط/الفهارس (مثال: items\[0].id).

## 🔒 الخصوصية والسلامة <a href="#privacy-and-safety" id="privacy-and-safety"></a>

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

## 🧭 أمثلة على سيناريوهات <a href="#examples" id="examples"></a>

* إرسال بيانات مستشعر دوريًا إلى خدمة ويب وتسجيل عدادات النجاح/الفشل باستخدام `CSV Export`.
* نشر كائن JSON مهيكل تم إنشاؤه بواسطة `Data to JSON` ثم تغذية `Extracted Data` إلى تدفق قرار (`Logic Input` / حدود).
* استخدم `Debug Input` لفحص أخطاء الخادم أثناء التطوير قبل الانتقال إلى تسجيل الإنتاج.