AnsibleModule ومواصفات الوسائط

فئة AnsibleModule هي مجموعة أدواتك. فهي تحلل المعاملات التي ترسلها Ansible، وتتحقق من صحتها، وتمنحك أدوات مساعدة لإرجاع النتائج.

تصف كل إدخال تقبله وحدتك في قاموس argument_spec. وتقرأه Ansible للتحقق من صحة ما يمرره المستخدمون.

عيّن type مثل str أو int أو bool أو list أو dict. وتحول Ansible الأنواع وترفض الإدخالات غير الصحيحة قبل تشغيل شيفرتك.

أضف required=True، وستفشل Ansible برسالة واضحة إذا نسي المستخدم ذلك المعامل. لا حاجة إلى فحوصات دفاعية.

استخدم default حتى تحصل المعاملات الاختيارية على قيمة تلقائيًا. ولا يعيّن المستخدمون إلا ما يريدون تغييره.

تقيّد قائمة choices المعامل بالقيم المسموح بها. وتُرفض أي قيمة أخرى مسبقًا مع رسالة مفيدة.

مرّر المواصفة إلى AnsibleModule لإنشاء الكائن. ومن هذه النقطة فصاعدًا، توجد جميع مدخلاتك بأمان في module.params.

يمكنك الوصول إلى معاملاتك عبر module.params، وهو قاموس عادي. فقد كُيّفت القيم وتحققت صحتها مسبقًا، لذا استخدمها مباشرة.

هل تحتاج إلى معاملين معًا، أو تمنع وجودهما معًا؟ مرّر قواعد مثل required_together أو mutually_exclusive إلى AnsibleModule، وستفرضها.

علّم المدخلات الحساسة باستخدام no_log=True حتى لا تظهر كلمات المرور في سجلات Ansible أو مخرجات الوضع المطوّل.

يستبدل argument_spec الجيد أكوامًا من عمليات التحقق اليدوية. صِف المدخلات مرة واحدة، وسيتولى Ansible الأنواع والأخطاء والتوثيق تلقائيًا.

فكّروا في كيفية وصول مدخلات المستخدم إلى شيفرة الوحدة البرمجية الخاصة بكم.

عرّفوا المدخلات في argument_spec باستخدام الأنواع والقيم الافتراضية والحقول المطلوبة والخيارات، ثم أنشئوا AnsibleModule واقرؤوا القيم المنظّفة من module.params. ✅