إنشاء ملفات المعلمات لتوزيع Bicep

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

إشعار

يتم دعم ملف معلمات Bicep فقط في إصدار Bicep CLI 0.18.4 أو أحدث، الإصدار 2.47.0 من Azure CLI أو أحدث، والإصدار 9.7.1 من Azure PowerShell أو أحدث.

يمكن أن يحتوي ملف Bicep واحد على ملفات معلمات Bicep متعددة مقترنة به. ومع ذلك، كل ملف معلمات Bicep مخصص لملف Bicep معين واحد. يتم تأسيس هذه العلاقة باستخدام العبارة using داخل ملف معلمات Bicep.

يمكنك تحويل ملفات معلمات Bicep برمجيا إلى ملفات معلمات JSON لنشرها مع ملف Bicep. راجع build-params. يمكنك أيضا إلغاء تحويل ملف معلمات JSON برمجيا إلى ملف معلمات Bicep. راجع إلغاء التحويل البرمجي للبارمات.

ملف المعلمات

يستخدم ملف المعلمات التنسيق التالي:

ملف معلمات Bicep

using '<path>/<file-name>.bicep'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>

يمكنك استخدام عبارة الاستخدام مع ملف Bicep وقوالب ARM JSON ووحدات Bicep ومواصفات القالب. على سبيل المثال:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

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

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

using 'main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

يمكنك الرجوع إلى متغيرات البيئة كقيم معلمات. على سبيل المثال:

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

يمكنك تعريف المتغيرات واستخدامها. مطلوب إصدار Bicep CLI 0.21.X أو أعلى لاستخدام المتغيرات في ملف .bicepparam. إليك بعض الأمثلة:

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

ملف معلمات JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

تجدر الإشارة إلى أن ملف المعلمات يحفظ قيم المعلمات كنص عادي. لأسباب أمنية، لا ينصح بهذا الأسلوب للقيم الحساسة مثل كلمات المرور. إذا كان يجب تمرير معلمة بقيمة حساسة، فاحتفظ بالقيمة في key vault. بدلا من إضافة القيمة الحساسة إلى ملف المعلمات، استخدم الدالة getSecret لاستردادها. لمزيد من المعلومات، راجع استخدام Azure Key Vault لتمرير قيمة المعلمة الآمنة أثناء توزيع Bicep.

تنسيقات نوع المعلمة

يوضح المثال التالي تنسيقات أنواع مختلفة من المعلمات: سلسلة، وعدد صحيح، ومنطقي، ومصفوفة، وكائن.

ملف معلمات Bicep

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

استخدم بناء جملة Bicep للإعلان عن الكائنات والصفائف.

ملف معلمات JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

اسم الملف

ملف معلمات Bicep

يحتوي ملف معلمات Bicep على ملحق .bicepparamملف .

للنشر في بيئات مختلفة، يمكنك إنشاء أكثر من ملف معلمات واحد. عند تسمية ملفات المعلمات، حدد استخدامها مثل التطوير والإنتاج. على سبيل المثال، استخدم main.dev.bicepparam و main.prod.bicepparam لنشر الموارد.

ملف معلمات JSON

اصطلاح التسمية العام لملف المعلمات هو تضمين معلمات في اسم ملف Bicep. على سبيل المثال، إذا تمت تسمية ملف Bicep باسم azuredeploy.bicep، تتم تسمية ملف المعلمات azuredeploy.parameters.json. يساعدك اصطلاح التسمية هذا على رؤية العلاقة بين ملف Bicep والمعلمات.

للنشر في بيئات مختلفة، يمكنك إنشاء أكثر من ملف معلمات واحد. عند تسمية ملفات المعلمات، حدد استخدامها مثل التطوير والإنتاج. على سبيل المثال، استخدم azuredeploy.parameters-dev.json وazuredeploy.parameters-prod.json لتوزيع الموارد.

تعريف قيم المعلمات

لتحديد كيفية تحديد أسماء وقيم المعلمات، افتح ملف Bicep الخاص بك. انظر إلى قسم المعلمات في ملف Bicep. توضح الأمثلة التالية المعلمات من ملف Bicep يسمى main.bicep.

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

في ملف المعلمات، التفاصيل الأولى التي يجب ملاحظتها هي اسم كل معلمة. يجب أن تتطابق أسماء المعلمات في ملف المعلمات مع أسماء المعلمات في ملف Bicep الخاص بك.

ملف معلمات Bicep

using 'main.bicep'

param storagePrefix
param storageAccountType

تربط using العبارة ملف معلمات Bicep إلى ملف Bicep. لمزيد من المعلومات، راجع استخدام عبارة .

بعد كتابة الكلمة الأساسية param في Visual Studio Code، فإنه يطالبك بالمعلمات المتوفرة ووصفها من ملف Bicep المرتبط:

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

ملف معلمات JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

لاحظ نوع المعلمة. يجب أن تستخدم أنواع المعلمات في ملف المعلمات نفس أنواع ملف Bicep الخاص بك. وفي المثال التالي، نوعا المعلمة كلاهما من السلاسل.

ملف معلمات Bicep

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

ملف معلمات JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": ""
    },
    "storageAccountType": {
      "value": ""
    }
  }
}

تحقق من ملف Bicep للمعلمات ذات القيمة الافتراضية. إذا كانت المعلمة تحتوي على قيمة افتراضية، يمكنك توفير قيمة في ملف المعلمات، ولكنها غير مطلوبة. تتجاوز قيمة ملف المعلمات القيمة الافتراضية لملف Bicep.

ملف معلمات Bicep

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep will use default value if not provided.

ملف معلمات JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Bicep will use default value if not provided.
    }
  }
}

إشعار

للتعليقات المضمنة ، يمكنك استخدام إما // أو / * ... * /. في Visual Studio Code، احفظ ملفات المعلمات بنوع ملف JSONC ، وإلا فستتلقى رسالة خطأ تقول "التعليقات غير مسموح بها في JSON".

تحقق من القيم المسموح بها لـ Bicep وأي قيود مثل الحد الأقصى للطول. تحدد هذه القيم نطاق القيم التي يمكنك توفيرها للمعلمة. في هذا المثال، يمكن أن يحتوي storagePrefix على 11 حرفاً كحد أقصى ويجب أن يحدد storageAccountType قيمة مسموح بها.

ملف معلمات Bicep

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

ملف معلمات JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

إشعار

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

إنشاء ملف المعلمات

لإنشاء ملف معلمات، لديك خياران: إما من خلال Visual Studio Code أو باستخدام Bicep CLI. تسمح لك كلتا الطريقتين اشتقاق ملف المعلمات من ملف Bicep. من Visual Studio Code، راجع إنشاء ملف المعلمات. من Bicep CLI، راجع إنشاء ملف المعلمات.

إنشاء ملف معلمات Bicep

من Bicep CLI، يمكنك إنشاء ملف معلمات Bicep في ملف معلمات JSON. لمزيد من المعلومات، راجع إنشاء ملف معلمات.

نشر ملف Bicep مع ملف المعلمات

Azure CLI

من Azure CLI، يمكنك تمرير ملف معلمة مع نشر ملف Bicep الخاص بك.

ملف معلمات Bicep

باستخدام الإصدار 2.53.0 من Azure CLI أو أحدث، وإصدار Bicep CLI 0.22.X أو أعلى، يمكنك نشر ملف Bicep باستخدام ملف معلمة Bicep. باستخدام العبارة using داخل ملف معلمات Bicep، ليست هناك حاجة لتوفير --template-file مفتاح التبديل عند تحديد ملف معلمة Bicep للتبديل --parameters .

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

ملف معلمات JSON

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json

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

ملف معلمات Bicep

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

ملف معلمات JSON

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json \
  --parameters storageAccountType=Standard_LRS

لمزيد من المعلومات، راجع توزيع الموارد باستخدام Bicep وAzure CLI.

Azure PowerShell

من Azure PowerShell، مرر ملف معلمات محلي باستخدام المعلمة TemplateParameterFile .

ملف معلمات Bicep

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

ملف معلمات JSON

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json

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

ملف معلمات Bicep

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

ملف معلمات JSON

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json `
  -storageAccountType Standard_LRS

لمزيد من المعلومات، راجع توزيع الموارد باستخدام Bicep وAzure PowerShell. لنشر ملفات .bicep تحتاج إلى الإصدار 5.6.0 من Azure PowerShell أو أحدث.

أسبقية المعلمة

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

من الممكن استخدام ملف معلمات JSON خارجي، من خلال توفير URI للملف. ملف معلمات Bicep الخارجي غير مدعوم حاليا. عند استخدام ملف معلمات خارجي، لا يمكنك تمرير قيم أخرى إما مضمنة أو من ملف محلي. يتم تجاهل جميع المعلمات المضمنة. أدخل جميع قيم المعلمات في الملف الخارجي.

تعارضات اسم المعلمة

إذا كان ملف Bicep الخاص بك يتضمن معلمة بنفس الاسم كأحد المعلمات في أمر PowerShell، فإن PowerShell يقدم المعلمة من ملف Bicep الخاص بك مع postfix FromTemplate. على سبيل المثال، تتعارض معلمة باسم ResourceGroupName في ملف Bicep مع المعلمة ResourceGroupName في الأمر New-AzResourceGroupDeployment. يجب توفير قيمة للمعلمة ResourceGroupNameFromTemplate. لتجنب هذا الالتباس، استخدم أسماء المعلمات التي لا تُستخدم لأوامر التوزيع.

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

• لمزيد من المعلومات حول كيفية تحديد المعلمات في ملف Bicep، راجع المعلمات في Bicep.
• للحصول على القيم الحساسة، راجع استخدام Azure Key Vault لتمرير قيمة المعلمة الآمنة أثناء التوزيع.