إضافة معلمات ومخرجات إلى الوحدات

مكتمل

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

عندما تخطط لإحدى الوحدات، ضع في اعتبارك:

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

معلمات الوحدة النمطية

فكر في المعلمات التي تقبلها وحدتك، وما إذا كان يجب أن تكون كل معلمة اختيارية أو مطلوبة.

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

يجب أن تفكر أيضاً في كيفية إدارة المعلمات التي تتحكم في وحدات SKU لمواردك وإعدادات التكوين المهمة الأخرى. عند إنشاء قالب Bicep مستقل، من الشائع تضمين قواعد العمل في قالبك. على سبيل المثال: عند نشر بيئة إنتاج، يجب أن يستخدم حساب التخزين طبقة GRS. ولكن الوحدات النمطية تقدم أحيانا مخاوف مختلفة.

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

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

أياً كانت المعلمات التي تضمنها في وحدتك، تأكد من إضافة وصف ذي معنى باستخدام السمة @description :

@description('The name of the storage account to deploy.')
param storageAccountName string

استخدام الشروط

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

افترض أنك تنشئ وحدة توزع حساب Azure Cosmos DB. عندما توزعها في بيئة التشغيل خاصتك، فأنت بحاجة إلى تكوين الحساب لإرسال سجلاتها إلى مساحة عمل Log Analytics. لتكوين سجلات من المقرر إرسالها إلى "Log Analytics"، يمكنك تعريف مورد diagnosticSettings.

يمكنك تحقيق متطلباتك عن طريق إضافة شرط إلى تعريف المورد، وجعل معلمة معرّف مساحة العمل اختياريةً عن طريق إضافة قيمة افتراضية:

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

عندما تضمن هذه الوحدة في قالب Bicep، يمكنك بسهولة تكوينه لإرسال سجلات حساب Azure Cosmos DB إلى Log Analytics عن طريق إعداد معرف مساحة عمل. أو، إذا لم تكن بحاجة إلى سجلات للبيئة التي تقوم بنشرها، فاحذف المعلمة . تحتوي على قيمة افتراضية. الوحدة تغلّف المنطق المطلوب لإجراء الشيء الصحيح لمتطلباتك.

تلميح

تذكر أن تختبر أن قالبك صالح لكلا السيناريوهين - عند if تقييم العبارة إما true أو false.

مخرجات الوحدة

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

تحذير

لا تستخدم المخرجات لقيم البيانات السرية. تُسجل المخرجات باعتبارها جزءاً من محفوظات التوزيع، لذا فهي غير مناسبة للقيم الآمنة. يمكنك بدلاً من ذلك التفكير في أحد الخيارات التالية:

• استخدم مخرجات لتوفير اسم المورد. ثم يمكن للقالب الأصلي إنشاء existing مورد بهذا الاسم ويمكنه البحث عن القيمة الآمنة ديناميكياً.
• اكتب القيمة إلى بيانات "Azure Key Vault" السرية. اطلب من القالب الأصل قراءة السر من المخزن عندما يحتاج إليه.

يمكن للقالب الأصلي استخدام مخرجات الوحدة في المتغيرات، ويمكنه استخدام خصائص لتعريفات الموارد الأخرى أو يمكن أن يعرض المتغيرات والخصائص باعتبارها مخرجات بحد ذاتها. من خلال كشف المخرجات واستخدامها في جميع ملفات Bicep، يمكنك إنشاء مجموعات قابلة لإعادة الاستخدام من وحدات Bicep التي يمكن مشاركتها مع فريقك وإعادة استخدامها عبر عمليات توزيع متعددة. من الممارسات الجيدة أيضاً إضافة وصف مفيد للمخرجات باستخدام السمة @description:

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

تلميح

يمكنك أيضاً استخدام الخدمات المخصصة لتخزين الإعدادات التي ينشئها نموذج Bicep وإدارتها والوصول إليها. Key Vault مصمم لتخزين القيم الآمنة. Azure App Configuration مصمم لتخزين قيم (غير آمنة) أخرى.

وحدات السلسلة معاً

من الشائع إنشاء ملف Bicep أصل ينشئ وحدات متعددة معاً. على سبيل المثال، تخيل أنك تبني قالب Bicep جديد لتوزيع الأجهزة الظاهرية التي تستخدم شبكات ظاهرية مخصصة. يمكنك إنشاء وحدة لتعريف شبكة اتصال ظاهرية. يمكنك بعد ذلك أخذ معرّف مورد الشبكة الفرعية الخاصة بالشبكة الظاهرية باعتباره مخرج من تلك الوحدة واستخدامه باعتباره مدخل إلى وحدة الجهاز الظاهري:

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

في هذا المثال، تُستخدم أسماء رمزية للمرجع بين الوحدات. يساعد هذا المرجع Bicep على فهم العلاقات بين الوحدات النمطية تلقائيا.

لأن Bicep تفهم أن هناك تبعية، فإنها توزع الوحدات بتسلسل:

1. Bicep تنشر كل شيء في الوحدة virtualNetwork.
2. إذا نجح ذلك التوزيع، تصل Bicep إلى subnetResourceId قيمة الإخراج وتمريره إلى وحدة virtualMachine باعتبارها معلمة.
3. Bicep تنشر كل شيء في الوحدة virtualMachine.

إشعار

عندما تعتمد على وحدة، تنتظر Bicep انتهاء توزيع الوحدة بأكملها. من المهم أن نتذكر هذا عند التخطيط لوحداتك. إذا أنشأت وحدة تحدد مورداً يستغرق وقتاً طويلاً للتوزيع، فستنتظر أي موارد أخرى تعتمد على هذه الوحدة حتى انتهاء توزيع الوحدة بالكامل.