مشاركة عبر

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

  • مقالة

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

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

تنسيق Bicep

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

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

metadata <metadata-name> = ANY

targetScope = '<scope>'

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

@<decorator>(<argument>)
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>

@<decorator>(<argument>)
var <variable-name> = <variable-value>

@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

@<decorator>(<argument>)
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@2023-04-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.

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

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

الديكور

يمكنك إضافة مصمم واحد أو أكثر لكل عنصر من العناصر التالية:

المصمم تطبيق على العنصر تطبيق على نوع البيانات الوسيطة ‏‏الوصف
سمح بارام all صفيف استخدم Decorator هذا للتأكد من أن المستخدم يوفر القيم الصحيحة. يسمح بهذا المصمم فقط في param العبارات. للإعلان عن أن الخاصية يجب أن تكون واحدة من مجموعة من القيم المعرفة مسبقا في عبارة type أو output ، استخدم بناء جملة نوع الاتحاد. يمكن أيضا استخدام بناء جملة نوع الاتحاد في param عبارات .
batchSize المورد، الوحدة النمطية ‏‫غير متوفر‬ integer إعداد مثيلات للنشر بشكل تسلسلي.
الوصف param, var, resource, module, output, type, func all سلسلة توفير أوصاف للعناصر. يمكن استخدام نص بتنسيق Markdown لنص الوصف.
مميز param، النوع، الإخراج كائن سلسلة استخدم مصمم الديكور هذا لضمان تحديد الفئة الفرعية الصحيحة وإدارتها. لمزيد من المعلومات، راجع نوع بيانات الاتحاد ذات العلامات المخصصة.
تصدير var، النوع، func all لا شيء يشير إلى أنه يمكن استيراد العنصر بواسطة ملف Bicep آخر.
maxLength المعلمة، الإخراج صفيف، سلسلة العدد الصحيح الحد الأقصى لطول عناصر السلسلة والصفيف. القيمة شاملة.
maxValue المعلمة، الإخراج العدد الصحيح العدد الصحيح الحد الأقصى لقيمة عناصر العدد الصحيح. هذه القيمة شاملة.
بيانات التعريف المعلمة، الإخراج all كائن خصائص مخصصة لتطبيقها على العناصر. يمكن أن تتضمن خاصية الوصف، التي تعادل المصمم الخاص بالوصف.
minLength المعلمة، الإخراج صفيف، سلسلة العدد الصحيح الحد الأدنى لطول عناصر السلسلة والصفيف. القيمة شاملة.
minValue المعلمة، الإخراج العدد الصحيح العدد الصحيح الحد الأدنى لقيمة عناصر العدد الصحيح. هذه القيمة شاملة.
سدود param، النوع، الإخراج كائن لا شيء رفع BCP089 من تحذير إلى خطأ عندما يكون اسم خاصية نوع بيانات تعريف الاستخدام خطأ مطبعيا على الأرجح. لمزيد من المعلومات، راجع رفع مستوى الخطأ.
secure بارام سلسلة، عنصر لا شيء لتحديد المعلمة على أنها آمنة. لا تُحفظ قيمة المعلمة الآمنة في محفوظات التوزيع ولا يتم تسجيلها. لمزيد من المعلومات، يرجى مراجعة العناصر والسلاسل الآمنة.

المعلمات

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

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

param storageSKU string = 'Standard_LRS'

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

sku: {
  name: storageSKU
}

يمكنك إضافة مصمم واحد أو أكثر لكل معلمة. لمزيد من المعلومات، راجع استخدام المحسنات.

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

المتغيرات

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

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

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

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

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

للحصول على مزيدٍ من المعلومات، راجع المتغيرات في 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@2023-04-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')

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

الموارد

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

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

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

يمكنك إضافة مصمم واحد أو أكثر لكل مورد. لمزيد من المعلومات، راجع استخدام المحسنات.

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

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

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

resource storage 'Microsoft.Storage/storageAccounts@2023-04-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@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

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

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

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

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

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

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

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

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

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

المخرجات

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

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@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

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

مسافة فارغة

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

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

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

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

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

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

التعليقات

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

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

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2023-11-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، راجع أنواع البيانات.