المعلمات في Bicep

  • مقالة

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

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

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

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

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

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

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

إعلان بالربط

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

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 ويتم وضعها فوق إعلان المعلمة. يمكنك وضع علامة على معلمة كآمنة، وتحديد القيم المسموح بها، وتعيين الحد الأدنى والحد الأقصى لطول سلسلة، وتعيين الحد الأدنى والحد الأقصى للقيمة لعدد صحيح، وتوفير وصف للمعلمة.

يظهر المثال التالي استخدامين شائعين لمصممي الديكور.

@secure()
param demoPassword string

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

يصف الجدول التالي عناصر المصمم المتوفرة وكيفية استخدامها.

المصمم ينطبق على الوسيطة ‏‏الوصف
يسمح all صفيف القيم المسموح بها للمعلمة. استخدم Decorator هذا للتأكد من أن المستخدم يوفر القيم الصحيحة.
الوصف all سلسلة النص الذي يشرح كيفية استخدام المعلمة. يتم عرض الوصف للمستخدمين من خلال المدخل.
maxLength صفيف، سلسلة العدد الصحيح الحد الأقصى لطول معلمات السلسلة والصفيف. القيمة شاملة.
maxValue العدد الصحيح العدد الصحيح الحد الأقصى لقيمة معلمة العدد الصحيح. هذه القيمة شاملة.
بيانات التعريف all كائن خصائص مخصصة تُطبق على المعلمة. يمكن أن تتضمن خاصية الوصف، التي تعادل المصمم الخاص بالوصف.
minLength صفيف، سلسلة العدد الصحيح الحد الأدنى لطول معلمات السلسلة والصفيف. القيمة شاملة.
minValue العدد الصحيح العدد الصحيح الحد الأدنى لقيمة معلمة العدد الصحيح. هذه القيمة شاملة.
تامين سلسلة، عنصر لا شيء لتحديد المعلمة على أنها آمنة. لا تُحفظ قيمة المعلمة الآمنة في محفوظات التوزيع ولا يتم تسجيلها. لمزيد من المعلومات، يرجى مراجعة العناصر والسلاسل الآمنة.

يوجد مصممي الديكور في 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

يتم وصف مصممي الديكور المتوفرين في الأقسام التالية.

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

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

@secure()
param demoPassword string

@secure()
param demoSecretObject object

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

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

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

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

قيود المدى

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

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

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

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

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

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

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

‏‏الوصف

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

@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 في VS Code، سترى النص المنسق:

استخدام نص Markdown في VSCode

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

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

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

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

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

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

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

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

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@2020-06-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
        }
      }
    ]
  }
}

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