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

# REST API - Get

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

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

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

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

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

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

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

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

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

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

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

## 🎯 الميزات <a href="#features" id="features"></a>

* التنفيذ غير المحظور: تُجرى الطلبات دون تجميد واجهة المستخدم، لذا تظل الكتل والعناصر الأخرى مستجيبة أثناء الانتظار.
* استخراج استجابة اختياري: قدّم `Response Data ID` لاختيار حقل واحد من استجابة JSON عندما تحتاج قيمة محددة فقط.
* تقارير الأخطاء: تُعرض حالات الفشل الشائعة (أخطاء الاتصال، انتهاء المهلة، رموز حالة غير OK) عبر خرج `Error` وسجل النظام.
* قابلية ضبط المهلة: تمنع الانتظارات الطويلة من إيقاف تدفق العمل عبر ضبط `Timeout (s)`.

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

1. قدّم إشارة منطقية إلى `Enable Condition` عندما تريد تشغيل الطلب.
2. أدخل عنوان نقطة النهاية في `Server Address`.
3. إذا كانت الاستجابة JSON وتحتاج قيمة واحدة فقط، ضع مفتاح JSON المطلوب في `Response Data ID` (اتركه فارغًا لتلقي الاستجابة كاملة).
4. عدل `Timeout (s)` إذا كان الخادم بطيئًا أو إذا رغبت في التعامل مع الفشل بسرعة أكبر.
5. اقرأ النتائج من مخارج `Status Code`, `Error`, و`Response` واربِطها بكتل لاحقة للتحليل أو التخزين أو الإشعار.

## 📊 التقييم <a href="#evaluation" id="evaluation"></a>

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

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

* لتشغيل طلب واحد عندما تصبح الحالة 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`.

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

* المشكلة: لا توجد استجابة أو انتهاء مهلة.
  * تحقق من عنوان URL في `Server Address` وتأكد من وجود وصول شبكي إلى الخادم. زِد `Timeout (s)` للخوادم البطيئة.
* المشكلة: خرج `Error` يحتوي رمز حالة HTTP أو رسالة.
  * افحص `Status Code` لمعرفة ما إذا أبلغ الخادم عن خطأ عميل أو خادم (4xx/5xx). تأكد من صحة نقطة النهاية وأي مصادقة مطلوبة مع مزود API.
* المشكلة: الاستجابة JSON لكن القيمة المطلوبة غير موجودة.
  * تحقق من صحة المفتاح أو المسار في `Response Data ID`. إذا كان التركيب متداخلاً، استخدم كتلة تحليل مثل `Parse Data Dictionary` للتنقل داخل JSON.
* المشكلة: الطلبات تُنفَّذ بشكل متكرر جدًا أو في أوقات غير مرغوبة.
  * تحكم في توقيت الطلب باستخدام `Logic Input`, `Rising Edge` أو كتل تحكم تدفق أخرى لضمان إرسال الطلبات فقط عند الحاجة.