مشاركة عبر

أفضل الممارسات لـ Bicep

  • مقالة

تصف هذه المقالة ممارسات، لاتباعها عند تطوير الملفات Bicep. هذه الممارسات تجعل ملف Bicep أسهل في الفهم، والاستخدام.

موارد التدريب

إذا كنت تفضل التعرف على أفضل ممارسات Bicep من خلال إرشادات خطوة بخطوة، فشاهد هيكلة التعليمات البرمجية ل Bicep للتعاون.

المعلمات

  • استخدام تسمية جيدة لإعلانات المعلمات. تجعل الأسماء الجيدة قوالبك سهلة القراءة والفهم. تأكد من استخدامك أسماء واضحة ووصفية، وكن متسقًا في التسمية.

  • فكر بعناية في المعلمات التي يستخدمها القالب. حاول استخدام معلمات الإعدادات التي تتغير بين عمليات النشر. يمكن استخدام المتغيرات وتعليمات برمجية مضمّنة للإعدادات التي لا تتغير بين عمليات النشر.

  • ضع في اعتبارك القيم الافتراضية التي تستخدمها. تأكد من أن القيم الافتراضية آمنة لأي شخص يريد نشرها. على سبيل المثال، فكر في استخدام مستويات أسعار منخفضة التكلفة، ووحدات حفظ المخزون (SKUs)، بحيث لا يتحمل شخص ما يوزع القالب في بيئة اختبار تكلفة كبيرة دون داعٍ.

  • استخدم المُحسن ⁧@allowed⁩ باعتدال. إذا كنت تستخدم مصمم الديكور هذا على نطاق واسع للغاية، فقد تمنع عمليات النشر الصالحة. حيث إن خدمات Azure تضيف وحدات حفظ المخزون (SKUs)، والأحجام، قد لا تكون القائمة المسموح بها محدثة. على سبيل المثال، السماح لـ Premium v3 SKUs فقط قد يكون منطقياً في عملية الإنتاج، ولكنه يمنعك من استخدام نفس القالب في البيئات غير المنتجة.

  • من الممارسات الجيدة تقديم أوصاف للمعلمات الخاصة بك. حاول جعل الأوصاف مفيدة، وتوفير أية معلومات هامة حول ما يحتاج القالب لقيم المعلمة أن تكون.

    يمكنك أيضا استخدام // التعليقات لإضافة ملاحظات داخل ملفات Bicep.

  • يمكنك وضع إعلانات المعلمات بالربط في أي مكان في ملف القالب، على الرغم من أنها عادةً ما يكون وضعها في أعلى الملف فكرة جيدة، بحيث يكون رمز Bicep سهل القراءة.

  • من الجيد تحديد الحد الأدنى، والحد الأقصى لطول الأحرف للمعلمات التي تتحكم في التسمية. تساعد هذه القيود في تجنب الأخطاء لاحقاً أثناء النشر.

لمزيد من المعلومات حول معلمات Bicep، راجع المعلمات في Bicep.

المتغيرات

  • عند تحديد متغير، لا يلزم إدخال نوع البيانات. تستدل المتغيرات على النوع، من قيمة الحل.

  • يمكنك استخدام وظائف Bicep، لإنشاء متغير.

  • بعد تحديد المتغير في ملف Bicep الخاص بك، يمكنك الرجوع إلى القيمة باستخدام اسم المتغير.

لمزيد من المعلومات حول متغيرات Bicep، راجع المتغيرات في Bicep.

الأسماء

  • استخدم الحروف الصغيرة للأسماء، مثل myVariableName أو myResource.

  • الدالة uniqueString() مفيدة لإنشاء أسماء موارد فريدة. عند توفير نفس المَعلمات، فإنه يُرجِع نفس السلسلة كل مرة. إن تمرير معرف مجموعة الموارد يعني أن السلسلة هي نفسها في كل عملية نشر إلى نفس مجموعة الموارد، ولكنها تختلف عند النشر إلى مجموعات موارد أو اشتراكات مختلفة.

  • من الممارسات الجيدة استخدام تعبيرات القالب لإنشاء أسماء الموارد، كما هو الحال في هذا المثال:

    param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'

    يمنحك استخدام تعبيرات القالب لإنشاء أسماء الموارد العديد من الفوائد:

    • السلاسل التي تم إنشاؤها بواسطة uniqueString() ليست ذات معنى. من المفيد استخدام تعبير قالب لإنشاء اسم يتضمن معلومات ذات معنى، مثل واصف قصير لاسم المشروع أو البيئة، بالإضافة إلى مكون عشوائي لجعل الاسم فريدا على الأرجح.

    • لا تضمن الدالة uniqueString() أسماء فريدة عالميا. بإضافة نص إضافي إلى أسماء الموارد الخاصة بك، فإنك تقلل من احتمالية إعادة استخدام اسم مورد موجود.

    • أحياناً تنشئ دالة uniqueString() السلاسل التي تبدأ برقم. لا تسمح بعض موارد Azure، مثل حسابات التخزين، ببدء أسمائها بالأرقام. يعني هذا المطلب أن استخدام استنتاج السلسلة يُعد فكرة جيدة لإنشاء أسماء الموارد. يمكنك إضافة بادئة إلى السلسلة الفريدة.

    • يحتوي العديد من أنواع موارد Azure على قواعد بشأن الأحرف المسموح بها وطول أسمائها. إن تضمين إنشاء أسماء الموارد في القالب يعني أن أي شخص يستخدم القالب لا يجب أن يتذكر اتباع هذه القواعد بنفسه.

  • تجنب استخدام name في اسم رمزي. يمثل الاسم الرمزي المورد، وليس اسم المورد. على سبيل المثال، بدلاً من بناء الجملة التالي:

    resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

    استخدم ما يلي:

    resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

  • تجنب تمييز المتغيرات والمعلمات باستخدام اللاحقات.

تعريفات الموارد

  • بدلا من تضمين التعبيرات المعقدة مباشرة في خصائص المورد، استخدم المتغيرات لاحتواء التعبيرات. هذا النهج يجعل ملف Bicep أسهل للقراءة والفهم. حيث يتجنب تكدس تعريفات المورد بالمنطق.

  • حاول استخدام خصائص الموارد كمخرجات، بدلاً من وضع افتراضات حول كيفية سلوك الموارد. على سبيل المثال، إذا كنت بحاجة إلى إخراج عنوان URL إلى تطبيق خدمة التطبيق، فاستخدم الخاصية defaultHostname، لتطبيقها بدلاً من إنشاء سلسلة لعنوان URL بنفسك. في بعض الأحيان، تكون هذه الافتراضات غير صحيحة في بيئات مختلفة، أو تغير الموارد الطريقة التي تعمل بها. من الآمن أن يخبرك المورد بخصائصه الخاصة.

  • من الجيد استخدام إصدار حديث لواجهة برمجة تطبيقات كل مورد. تتوفر الميزات الجديدة في خدمات Azure أحيانًا فقط في الإصدارات الأحدث من واجهة برمجة التطبيقات.

  • عند الإمكان، تجنب استخدام الدالتين reference، وresourceId في ملف Bicep. يمكنك الوصول إلى أي مورد في Bicep باستخدام الاسم الرمزي. على سبيل المثال، إذا حددت حساب تخزين بالاسم الرمزي toyDesignDocumentsStorageAccount، يمكنك الوصول إلى معرف المورد الخاص به باستخدام التعبير toyDesignDocumentsStorageAccount.id. باستخدام الاسم الرمزي، يمكنك إنشاء تبعية ضمنية بين الموارد.

  • تفضل استخدام التبعيات الضمنية على التبعيات الصريحة. على الرغم من أن خاصية المورد dependsOn تمكنك من التصريح عن تبعية صريحة بين الموارد، فإنه من الممكن عادة استخدام خصائص المورد الآخر باستخدام اسمه الرمزي. هذا الأسلوب يخلق تبعية ضمنية بين هذين الموردين، ويمكّن Bicep من إدارة العلاقة نفسها.

  • إذا لم يتم نشر المورد في ملف Bicep، يمكنك الحصول على المرجع الرمزي للمورد باستخدام الكلمة الأساسية existing.

الموارد التابعة

  • تجنب تضمين العديد من الطبقات العميقة. يؤدي الإفراط في التضمين إلى جعل رمز Bicep أصعب في القراءة والتعامل معه.

  • تجنب إنشاء أسماء موارد للموارد التابعة. تفقد الفوائد التي يوفرها Bicep عندما يفهم العلاقات بين الموارد الخاصة بك. استخدم الخاصية parent أو التضمين بدلاً من ذلك.

المخرجات

  • تأكد من عدم إنشاء مخرجات للبيانات الحساسة. يمكن الوصول إلى قيم الإخراج من قبل أي شخص لديه حق الوصول إلى محفوظات النشر. إنها ليست مناسبة للتعامل مع الأسرار.

  • بدلاً من تمرير قيم الخصائص عبر المخرجات، استخدم الكلمة الأساسية الموجودة للبحث عن خصائص الموارد الموجودة بالفعل. من أفضل الممارسات البحث عن مفاتيح من موارد أخرى بهذه الطريقة بدلاً من تمريرها عبر المخرجات. ستحصل دائمًا على أحدث البيانات.

لمزيد من المعلومات حول مخرجات Bicep، راجع المخرجات في Bicep.

نطاقات المستأجر

لا يمكنك إنشاء نُهج أو تعيينات أدوار في نطاق المستأجر. ومع ذلك، إذا كنت بحاجة إلى منح الوصول أو تطبيق النُّهج عبر المؤسسة بأكملها، يمكنك نشر هذه الموارد إلى مجموعة إدارة الجذر.

الخطوات التالية