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

2024-07-11

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

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

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

المعلمات

استخدم تسمية جيدة لإعلانات المعلمات. تجعل الأسماء الجيدة قوالبك سهلة القراءة والفهم. تأكد من أنك تستخدم أسماء واضحة ووصفية، وأن تكون متسقا في التسمية.
فكر بعناية في المعلمات التي يستخدمها القالب. حاول استخدام معلمات الإعدادات التي تتغير بين عمليات النشر. يمكن استخدام المتغيرات وتعليمات برمجية مضمّنة للإعدادات التي لا تتغير بين عمليات النشر.
ضع في اعتبارك القيم الافتراضية التي تستخدمها. تأكد من أن القيم الافتراضية آمنة لأي شخص لنشرها. على سبيل المثال، ضع في اعتبارك استخدام مستويات التسعير منخفضة التكلفة ووحدات SKU بحيث لا يتحمل شخص ما ينشر القالب في بيئة اختبار تكلفة كبيرة دون داع.
@allowed استخدم مصمم الديكور باعتدال. إذا كنت تستخدم مصمم الديكور هذا على نطاق واسع جدا، فقد تمنع عمليات النشر الصالحة. نظرا لأن خدمات Azure تضيف وحدات SKU وأحجاما، فقد لا تكون القائمة المسموح بها محدثة. على سبيل المثال، قد يكون السماح لوحدات SKU Premium v3 فقط منطقيا في الإنتاج، ولكنه يمنعك من استخدام نفس القالب في البيئات غير الإنتاجية.
من الممارسات الجيدة تقديم أوصاف للمعلمات الخاصة بك. حاول جعل الأوصاف مفيدة، وتوفير أية معلومات هامة حول ما يحتاج القالب لقيم المعلمة أن تكون.

يمكنك أيضا استخدام // التعليقات لإضافة ملاحظات داخل ملفات 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 إلى تطبيق App Service، فاستخدم الخاصية defaultHostname للتطبيق بدلا من إنشاء سلسلة لعنون URL بنفسك. في بعض الأحيان لا تكون هذه الافتراضات صحيحة في بيئات مختلفة، أو تغير الموارد طريقة عملها. من الآمن أن يخبرك المورد بخصائصه الخاصة.
من الجيد استخدام إصدار API حديث لكل مورد. تتوفر الميزات الجديدة في خدمات Azure في بعض الأحيان فقط في إصدارات واجهة برمجة التطبيقات الأحدث.
عندما يكون ذلك ممكنا، تجنب استخدام الدالتين reference و resourceId في ملف Bicep الخاص بك. يمكنك الوصول إلى أي مورد في Bicep باستخدام الاسم الرمزي. على سبيل المثال، إذا قمت بتعريف حساب تخزين بالاسم الرمزي toyDesignDocumentsStorageAccount، يمكنك الوصول إلى معرف المورد الخاص به باستخدام التعبير toyDesignDocumentsStorageAccount.id. باستخدام الاسم الرمزي، يمكنك إنشاء تبعية ضمنية بين الموارد.
يفضل استخدام التبعيات الضمنية على التبعيات الصريحة. dependsOn على الرغم من أن خاصية المورد تمكنك من الإعلان عن تبعية صريحة بين الموارد، فمن الممكن عادة استخدام خصائص المورد الآخر باستخدام اسمه الرمزي. ينشئ هذا الأسلوب تبعية ضمنية بين الموردين، ويمكن Bicep من إدارة العلاقة نفسها.
إذا لم يتم نشر المورد في ملف Bicep، فلا يزال بإمكانك الحصول على مرجع رمزي للمورد باستخدام existing الكلمة الأساسية .

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

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

المخرجات

وضع علامة على البيانات الحساسة في المخرجات باستخدام مصمم @secure() الذي يمنع تسجيل المخرجات الحساسة أو عرضها. وإلا، يمكن لأي شخص لديه حق الوصول إلى محفوظات النشر الوصول إلى قيم الإخراج.
بدلا من تمرير قيم الخصائص من خلال المخرجات، استخدم الكلمة الأساسية الموجودة للبحث عن خصائص الموارد الموجودة بالفعل. من أفضل الممارسات البحث عن مفاتيح من موارد أخرى بهذه الطريقة بدلا من تمريرها من خلال المخرجات. ستحصل دائما على معظم البيانات up-to-date.

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

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

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

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

للحصول على مقدمة حول Bicep، راجع التشغيل السريع ل Bicep.
للحصول على معلومات حول أجزاء ملف Bicep، راجع فهم بنية وبناء جملة ملفات Bicep.