بنية ملف Bicep وبناء الجملة

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

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

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

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

تنسيق Bicep

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

يحتوي ملف البايسيب على العناصر التالية:

#<directive-name> <argument> [<argument> ...]

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

@<decorator>(<argument>)
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@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

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

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

البيانات الوصفية في العضلة ذات الرأس هي قيمة غير مكتوبة يمكنك تضمينها في ملفات العضلة ذات الرأس. توفر البيانات الوصفية معلومات إضافية عن ملفات البايسيب، مثل الاسم، الوصف، المؤلف، وتاريخ الإنشاء.

نطاق الهدف

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

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

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

المعلمات

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

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

param storageSKU string = 'Standard_LRS'

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

sku: {
  name: storageSKU
}

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

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

المتغيرات

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

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

استخدم هذا المتغير أينما تحتاج إلى التعبير المركب.

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

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

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

الموارد

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

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

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

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

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

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

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

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

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

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2025-06-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.

الأنواع

استخدم العبارة 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@2025-06-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

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

الوظائف

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

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

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

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

الديكور

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

الجدول التالي يسرد المصممين:

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

التوجيهات

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

#<directive-name> <argument1> [<argument2> ... ]

يجب أن تحدد معرفا واحدا على الأقل بعد التوجيه. إذا لم تقدم أي معرفات، يقوم المترجم بالإبلاغ عن خطأ. المعرفات التي تحددها بعد التوجيه يمكن أن تشير إلى:

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

يدعم العضلة الذراعية حاليا ثلاثة أنواع من التوجيهات:

  • #disable-next-line - يعطل تشخيصا واحدا أو أكثر للسطر التالي فقط
  • #disable-diagnostics - يعطل تشخيصا واحدا أو أكثر لملف كامل أو حتى يتم إعادة تفعيله
  • #restore-diagnostics - إعادة تفعيل التشخيصات التي كانت معطلة سابقا

المثال التالي يثبط عدة تشخيصات وقواعد:

#disable-diagnostics no-unused-vars BCP335

var location = 'eastus'

param storageCount int

resource accounts 'Microsoft.Storage/storageAccounts@2025-06-01' = [for i in range(0, storageCount): if (i % 2 == 0) {
  name: 'sa0820${i}'
  location: resourceGroup().location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}]

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

التكرارات

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

  • مورد
  • وحدة
  • متغير
  • عقار
  • مخرج

استخدم التعبير 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'
}

لمزيد من المعلومات، انظر النشر الشرطي في العضلة ذات الرأسين مع تعبير if.

مسافة فارغة

ملفات الذراعين تتجاهل الفراغات وعلامات التبويب.

العضلة ذات الرأسين حساسة للخطوط الجديدة. على سبيل المثال:

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

لا يمكنك كتابتها كالتالي:

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

يمكنك تعريف الكائناتوالمصفوفات عبر عدة خطوط.

التعليقات

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

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

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2025-01-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 CLI 0.7.X أو أعلى.

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

var foo = resourceGroup(
  mySubscription,
  myRgName)

للحصول على عينات إعلان متعدد الأسطر، انظر المصفوفاتوالكائنات.

المحتويات ذات الصلة

  • Last updated on