فهم بنية ملفات Bicep وبناء الجملة الخاصة بها

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

للحصول على برنامج تعليمي خطوة بخطوة يرشدك خلال عملية إنشاء ملف Bicep، راجع تشغيل سريع: إنشاء ملفات Bicep باستخدام تعليماتVisual Studio البرمجية.

تنسيق Bicep

Bicep عبارة عن لغة تعريفية، ما يعني أن العناصر يمكن أن تظهر بأي ترتيب. على عكس اللغات الإلزامية، لا يؤثر ترتيب العناصر على كيفية معالجة التوزيع.

ملف Bicep يحتوي على العناصر التالية.

metadata <metadata-name> = ANY

targetScope = '<scope>'

type <user-defined-data-type-name> = <type-expression>

func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>

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

var <variable-name> = <variable-value>

resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

module <module-symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

output <output-name> <output-data-type> = <output-value>

يوضح المثال التالي تطبيق هذه العناصر.

metadata description = 'Creates a storage account and a web app'

@description('The prefix to use for the storage account name.')
@minLength(3)
@maxLength(11)
param storagePrefix string

param storageSKU string = 'Standard_LRS'
param location string = resourceGroup().location

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

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

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

نطاق الهدف

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

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

• resourceGroup - القيمة الافتراضية، المستخدمة في عمليات توزيع مجموعة الموارد.
• subscription - تُستخدم لعمليات توزيع الاشتراك.
• managementGroup - تُستخدم لعمليات توزيع مجموعة الإدارة.
• tenant - تُستخدم لعمليات توزيع المستأجر.

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

الأنواع

يمكنك استخدام العبارة type لتعريف أنواع البيانات المعرفة من قبل المستخدم.

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType = {
  name: 'storage${uniqueString(resourceGroup().id)}'
  sku: 'Standard_LRS'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

الوظائف (معاينة)

إشعار

لتمكين ميزة المعاينة، راجع تمكين الميزات التجريبية.

في ملف Bicep الخاص بك، يمكنك إنشاء وظائفك الخاصة بالإضافة إلى استخدام وظائف Bicep القياسية المتوفرة تلقائيا داخل ملفات Bicep الخاصة بك. إنشاء الدالات الخاصة بك عندما يكون لديك تعبيرات معقدة يتم استخدامها بشكل متكرر في ملفات Bicep الخاصة بك.

func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'

output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')

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

المعلمات

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

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

param storageSKU string = 'Standard_LRS'

المعلمة متاحة للاستخدام في ملف Bicep الخاص بك.

sku: {
  name: storageSKU
}

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

معلمات المصمم

يمكنك إضافة مصمم واحد أو أكثر لكل معلمة. تصف تلك المزخرفات المعلمة وتحدد قيود القيم التي يتم تمريرها. يوضح المثال التالي مصمما واحدا ولكن يتوفر العديد من المزخرفات الأخرى.

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

لمزيد من المعلومات، بما في ذلك وصف جميع المزخرفات المتوفرة، راجع المزخرفات.

المتغيرات

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

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

طبق هذا المتغير عندما تحتاج إلى التعبير المعقد.

resource stg 'Microsoft.Storage/storageAccounts@2019-04-01' = {
  name: uniqueStorageName

للحصول على مزيدٍ من المعلومات، راجع المتغيرات في Bicep.

الموارد

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

يتضمن إعلان المورد نوع المورد وإصدار API. ضمن نص إعلان المورد، قم بتضمين الخصائص الخاصة بنوع المورد.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

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

بعض الموارد لها علاقة أصل/تابع. يمكنك تحديد المورد التابع إما داخل المورد الأصل أو خارجه.

يوضح المثال التالي كيفية تحديد مورد تابع ضمن مورد أصل. يحتوي على حساب تخزين مع مورد تابع (خدمة ملف) تم تحديده داخل حساب التخزين. تحتوي خدمة الملف أيضاً على مورد تابع (مشاركة) تم تحديده بداخلها.

resource storage 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }

  resource service 'fileServices' = {
    name: 'default'

    resource share 'shares' = {
      name: 'exampleshare'
    }
  }
}

يوضح المثال التالي كيفية تحديد مورد تابع خارج المورد الأصل. يمكنك استخدام الخاصية الأصل لتحديد علاقة أصل/تابع. يتم تحديد نفس الموارد الثلاثة.

resource storage 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource service 'Microsoft.Storage/storageAccounts/fileServices@2022-09-01' = {
  name: 'default'
  parent: storage
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2022-09-01' = {
  name: 'exampleshare'
  parent: service
}

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

الوحدات

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

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

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

لمزيد من المعلومات، راجع استيراد وحدات Bicep النمطية.

الموردون ومصممو الوحدة النمطية

يمكنك إضافة مصمم إلى تعريف المورد أو الوحدة النمطية. المصممون المدعومون هما batchSize(int) و description. لا يمكنك تطبيقه إلا على تعريف الوحدة النمطية أو المورد الذي يستخدم تعبير for.

وبشكل افتراضي، يتم توزيع الموارد بالتوازي. عند إضافة مصمم batchSize(int)، يمكنك توزيع المثيلات بشكل تسلسلي.

@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  ...
}]

لمزيد من المعلومات، راجع التوزيع على دفعات.

الإخراجات

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

output storageEndpoint object = stg.properties.primaryEndpoints

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

التكرارات

يمكنك إضافة تكرار حلقي إلى ملف Bicep لتحديد نسخ متعددة من:

• resource
• الوحدة النمطية
• المتغير
• خاصية
• الإخراج

استخدم التعبير for لتعريف تكرار حلقي.

param moduleCount int = 2

module stgModule './example.bicep' = [for i in range(0, moduleCount): {
  name: '${i}deployModule'
  params: {
  }
}]

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

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

التوزيع الشرطي

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

param deployZone bool

resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

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

مسافة فارغة

يتم تجاهل المسافات وعلامات التبويب عند تأليف ملفات Bicep.

Bicep حساسة للخطوط الجديدة. على سبيل المثال:

resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' = if (newOrExisting == 'new') {
  ...
}

لا يمكن كتابته على النحو:

resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' =
    if (newOrExisting == 'new') {
      ...
    }

حدد العناصروالصفائف في أسطر متعددة.

تعليقات

استخدام // للتعليقات ذات الأسطر المفردة أو /* ... */ للتعليقات متعددة الأسطر

يظهر المثال التالي تعليقاً مكوّناً من سطر واحد.

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2020-06-01' = {
   ...
}

يظهر المثال التالي تعليقاً مكوّناً من عدة أسطر.

/*
  This Bicep file assumes the key vault already exists and
  is in same subscription and resource group as the deployment.
*/
param existingKeyVaultName string

مجموعة سلاسل خطية

يمكنك تقسيم سلسلة إلى عدة أسطر. استخدم ثلاثة أحرف اقتباس ''' لبدء مجموعة السلاسل الخطية وإنهائها.

تتم معالجة الأحرف داخل مجموعة السلاسل الخطية كما هي. أحرف الإلغاء غير ضرورية. لا يمكنك تضمين ''' في مجموعة السلاسل الخطية. استنتاج السلسلة غير معتمد حالياً.

يمكنك إما بدء السلسلة مباشرة بعد فتح ''' أو تضمين سطر جديد. في كلتا الحالتين، لا تتضمن السلسلة الناتجة سطراً جديداً. اعتماداً على نهايات الأسطر في ملف Bicep الخاص بك، يتم تفسير الأسطر الجديدة على أنها \r\n أو \n.

يظهر المثال التالي مجموعة سلاسل خطية.

var stringVar = '''
this is multi-line
  string with formatting
  preserved.
'''

المثال السابق يعادل JSON التالي.

"variables": {
  "stringVar": "this is multi-line\r\n  string with formatting\r\n  preserved.\r\n"
}

إعلانات متعددة الأسطر

يمكنك الآن استخدام أسطر متعددة في تعريفات الدالة والصفيف والعنصر. تتطلب هذه الميزة إصدار Bicep CLI 0.7.X أو أعلى.

في المثال التالي، resourceGroup() يتم تقسيم التعريف إلى أسطر متعددة.

var foo = resourceGroup(
  mySubscription,
  myRgName)

راجع الصفائف والكائنات للحصول على نماذج إعلان متعددة الأسطر.

القيود المعروفة

• لا يوجد دعم لمفهوم apiProfile، والذي يستخدم لتعيين apiProfile واحد إلى apiVersion مجموعة لكل نوع مورد.
• الوظائف المعرفة من قبل المستخدم غير مدعومة في الوقت الحالي. ومع ذلك، يمكن الوصول إلى ميزة تجريبية حاليا. لمزيد من المعلومات، راجع الدالات المعرفة من قبل المستخدم في Bicep.
• تتطلب بعض ميزات Bicep تغييراً مطابقاً للغة الوسيطة (قوالب Azure Resource Manager JSON). نعلن عن توفر هذه الميزات عند توزيع جميع التحديثات المطلوبة في global Azure. إذا كنت تستخدم بيئة مختلفة، مثل Azure Stack، فقد يكون هناك تأخير في توفر الميزة. تتوفر ميزة Bicep فقط عندما يتم تحديث اللغة الوسيطة في تلك البيئة.

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

للاطلاع على مقدمة إلى Bicep، راجع ما هي Bicep؟. للطلاع على أنواع بيانات Bicep، راجع أنواع البيانات.