المعلمات في Bicep

توضح هذه المقالة كيفية تعريف واستخدام معلمات في ملف Bicep. من خلال توفير قيم مختلفة للمعلمات، يمكنك إعادة استخدام ملف Bicep لبيئات مختلفة.

يحل Azure Resource Manager قيم المعلمات قبل بدء عمليات التوزيع. أينما يتم استخدام المعلمة، يستبدلها Resource Manager بالقيمة التي تم حلها.

يجب تحديد كل معلمة ضمن واحدة منأنواع البيانات.

يسمح Bicep بحد أقصى 256 معلمة. لمزيد من المعلومات، راجع حدود القالب.

للحصول على أفضل ممارسات المعلمات، راجع المعلمات.

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

راجع إنشاء قوالب Bicep القابلة لإعادة الاستخدام باستخدام وحدة تعلم المعلمات للحصول على إرشادات خطوة بخطوة حول المعلمات.

تحديد المعلمات

يكون لكل معلمة اسم ونوع البيانات. يمكنك، بشكل اختياري، تقديم قيمة افتراضية للمعلمة.

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

لا يمكن أن يكون للمعلمة نفس اسم المتغير أو المورد أو الإخراج أو معلمة أخرى في نفس النطاق.

يوضح المثال التالي التعريفات الأساسية للمعلّمات.

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

param يتم استخدام الكلمة الأساسية أيضا في .bicepparam الملفات. لا تحتاج إلى تحديد نوع البيانات في .bicepparam الملفات نظرا لتعريفه في ملفات Bicep.

param <parameter-name> = <value>

يمكن استخدام تعبيرات النوع المعرفة من قبل المستخدم كجملة نوع من param عبارة . على سبيل المثال:

param storageAccountConfig {
  name: string
  sku: string
}

لمزيد من المعلومات، راجع أنواع البيانات المعرفة من قبل المستخدم.

تعيين القيم الافتراضية

يمكنك تحديد قيمة افتراضية لمعلمة. تُستخدم القيمة الافتراضية عندما لا تتوفر قيمة أثناء الاستخدام.

param demoParam string = 'Contoso'

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

param location string = resourceGroup().location

من الممكن استخدام قيمة معلمة أخرى لبناء قيمة افتراضية. يُنشئ القالب التالي اسم خطة مضيف من اسم الموقع.

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

ومع ذلك، لا يمكنك الإشارة إلى متغير كقيمة افتراضية.

استخدام مصممي الديكور

تستخدم المعلمات الديكور للقيود أو بيانات التعريف. الديكور بتنسيق @expression ويتم وضعها فوق إعلان المعلمة. يعرض الجدول التالي المحسنات المتوفرة للمعلمات.

يوجد مصممي الديكور في sys namespace. إذا كنت بحاجة إلى تمييز مصمم ديكور عن عنصر آخر يحمل نفس الاسم، فاكتب في مقدمة مصمم الديكور sys. على سبيل المثال، إذا كان ملف Bicep يتضمن معلمة باسم description، يجب إضافة مساحة الاسم sys عند استخدام مصمم ديكور الوصف.

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

القيم المسموح بها

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

@allowed([
  'one'
  'two'
])
param demoEnum string

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

‏‏الوصف

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

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

يمكن استخدام النص المنسق بMarkdown في نص الوصف:

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

عند تمرير المؤشر فوق storageAccountName في Visual Studio Code، سترى النص المنسق:

تأكد من أن النص يتبع تنسيق Markdown المناسب؛ وإلا، فقد لا يتم عرضه بشكل صحيح عند عرضه.

مميز

راجع نوع بيانات الاتحاد ذات العلامات المخصصة.

قيود العدد الصحيح

يمكنك تعيين قيم الحد الأدنى والأقصى لمعلمات عدد صحيح. يمكنك تعيين قيد أو كليهما.

@minValue(1)
@maxValue(12)
param month int

قيود المدى

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

يوضح المثال التالي اثنتين من المعلمات. معلمة واحدة تكون لاسم حساب موقع تخزين يجب أن تحتوي على 3-24 حرفاً. المعلمة الأخرى عبارة عن صفيف يجب أن يكون من 1-5 عناصر.

@minLength(3)
@maxLength(24)
param storageAccountName string

@minLength(1)
@maxLength(5)
param appNames array

بيانات التعريف

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

يمكنك استخدام هذا المصمم لتعقب المعلومات حول المعلمة التي ليس من المنطقي إضافتها إلى الوصف.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

عند تزويد @metadata() مصمم الديكور بخاصية تتعارض مع مصمم ديكور آخر، فإن هذا المصمم دائما له الأسبقية على أي شيء في @metadata() مصمم الديكور. لذلك، الخاصية المتعارضة @metadata() داخل القيمة زائدة عن الحاجة وسيتم استبدالها. لمزيد من المعلومات، راجع لا توجد بيانات تعريف متعارضة.

سدود

راجع رفع مستوى الخطأ.

معلمات تتميز بالأمان

يمكنك وضع علامة على معلمات السلسلة أو الكائن على أنها آمنة. لا يتم حفظ قيمة معلمة آمنة في محفوظات النشر ولا يتم تسجيلها.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

هناك العديد من قواعد linter المتعلقة بهذا المصمم: المعلمة الآمنة الافتراضية، والمعلمات الآمنة في عمليات النشر المتداخلة، والأسرار الآمنة في المعلمات.

استخدام المعلمات

للإشارة إلى قيمة معلمة، استخدم اسم المعلمة. يستخدم المثال التالي قيمة المعلمة لاسم "المخزن الرئيسي".

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

استخدام الكائنات كمعلمات

يمكن أن يكون من الأسهل تنظيم القيم ذات الصلة من خلال تمريرها كعنصر. يحد هذا الأسلوب أيضًا من عدد المعلمات في القالب.

يوضح المثال التالي أن المعلمة تمثل عنصراً. تُظهر القيمة الافتراضية الخصائص المتوقعة للعنصر. تُستخدم هذه الخصائص عند تعريف المورد للاستخدام.

param vNetSettings object = {
  name: 'VNet1'
  location: 'eastus'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

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

• للتعرف على الخصائص المتوفرة للمعلمات، راجع فهم بنية وبناء جملة ملفات Bicep.
• للتعرف على تمرير قيم المعلمات كملف، راجع إنشاء ملفات المعلمات لتوزيع Bicep.
• للتعرف على توفير قيم المعلمات عند النشر، راجع نشر ملفات Bicep باستخدام Azure CLI وAzure PowerShell.