التحكم الآمن في المرحّلات
حالة الاستخدام
استخدم هذا النمط عندما تؤثر عمليات المرحّل على معدات حقيقية ويحتاج المستدعي إلى التعامل مع إعادة المحاولة والنتائج غير المؤكدة وعدة قنوات مرحّل دون إحداث آثار جانبية مكررة.
التدفق الموصى به
أرسل جميع تغيّرات مرحّل جهاز واحد في مصفوفة relays واحدة. تصبح الدفعة الواحدة أمر جهاز واحد وتتجنب الإرسالات المتتالية التي قد لا يعالجها الجهاز بشكل موثوق.
التنفيذ خطوة بخطوة
- استخدم سرد تعريفات نوع الجهاز (بالإنجليزية) لتأكيد
device.relay.set، وعدد المرحّلات، والإجراءات المسموحة. - ابنِ مصفوفة المرحّلات المطلوبة. استخدم عنصرًا واحدًا للتحكم بقناة واحدة وعدة فهارس فريدة لتغيير منسّق.
- ولّد
Idempotency-Keyجديدًا يملكه المستدعي لهذه النية من العملية. - استدعِ تنفيذ أمر مرحّل (بالإنجليزية) بصلاحية
device:control. - اقرأ
data.command.idوdata.command.status. إذا كانت الحالةSENT، استخدم الحصول على نتيجة أمر (بالإنجليزية) حتى تصل إلى حالة نهائية أو موعدك الأقصى المحدود للاستعلام. - استخدم
data.stateعندما يتضمنها تأكيد الجهاز. لا تُطلق تحديثًا آخر فقط لملء حقل اختياري. - إذا كانت النتيجة
TIMEOUT، اقرأ الحالة الحالية للجهاز قبل تقرير ما إذا كانت عملية أخرى آمنة.
دورة حياة الأمر
| النتيجة | المعنى | إجراء العميل |
|---|---|---|
HTTP 202 + COMMAND_ACCEPTED | قبلت المنصة الطلب؛ ليست حالة أمر مستقلة | اقرأ data.command.status واحتفظ بمعرّف الأمر |
SENT | لا يزال الأمر ينتظر التأكيد | استعلم عن النتيجة بسحب محدود |
SUCCESS | أكّد الجهاز التنفيذ | طبّق الحالة المُعادة عند وجودها |
FAILED | أكّدت المنصة أن الأمر لم يكتمل | أوقف إعادة المحاولة التلقائية وعالج الفشل |
TIMEOUT | لم يصل أي تأكيد نهائي ضمن نافذة الانتظار | لا تفترض أن الجهاز نفّذ أو لم ينفّذ؛ اقرأ الحالة الحالية أولًا |
الواجهات الرئيسية
- تنفيذ أمر مرحّل (بالإنجليزية)
- الحصول على نتيجة أمر (بالإنجليزية)
- الحصول على حالة الجهاز (بالإنجليزية)
- حدود التكرار والتماثلية (بالإنجليزية)
- التحكم في المرحّلات عبر WebSocket (بالإنجليزية)
الفشل والتعافي
- إذا كانت نتيجة HTTP غير معروفة بسبب فشل الشبكة، أعِد المحاولة بالطلب نفسه باستخدام
Idempotency-Keyنفسه. - بعد
429 RATE_LIMITED، انتظرRetry-After، ثم أعِد محاولة العملية نفسها بالمفتاح الأصلي. - لا تُعِد استخدام مفتاح لجهاز أو مصفوفة مرحّلات أو إجراء مختلف أبدًا؛ يُعيد ذلك
IDEMPOTENCY_CONFLICT. - بعد
TIMEOUT، حدّث الحالة أولًا. إذا ظلت غير معروفة، تطلّب قرار عمل قبل إرسال عملية فعلية أخرى. - يمكن أن يُنتج تكرار
JOGأو إجراءات معدات أخرى آثارًا جانبية حقيقية حتى عندما تُفقد الاستجابة السابقة. صمّم التأكيدات وضمانات المشغّل وفقًا لذلك.
اعتبارات الإنتاج
- خزّن معًا مفتاح التماثلية، ومعرّف الأمر، ومصفوفة المرحّلات المطلوبة، والحالة، و
requestIdللتدقيق والتعافي. - سلسل أو نسّق العمليات الموجّهة إلى الجهاز نفسه في تطبيقك.
- استخدم سحب نتائج محدودًا واحترم حدود التكرار.
- تحقّق من القناة المستهدفة والسلامة الفعلية قبل السماح بالتحكم من واجهة أو قاعدة أتمتة.
الخطوات التالية
- حدث تغيّر حالة الجهاز (بالإنجليزية)
- أخطاء الموارد والأوامر (بالإنجليزية)
- بناء لوحة مراقبة للأجهزة