مواصفات قالب Azure Resource Manager في Bicep

  • مقالة

مواصفات القالب هي نوع مورد لتخزين قالب Azure Resource Manager (قالب ARM) للتوزيع لاحقاً. يتيح لك نوع المورد هذا مشاركة قوالب ARM مع مستخدمين آخرين في مؤسستك. تماماً مثل أي مورد Azure آخر، يمكنك استخدام التحكم في الوصول استناداً إلى الدور (Azure RBAC) لمشاركة مواصفات القالب. ويمكنك استخدام Azure CLI أو Azure PowerShell لإنشاء مواصفات القالب عن طريق توفير ملفات Bicep. يتم نقل ملفات Bicep إلى قوالب ARM JSON قبل تخزينها. حالياً، لا يمكنك استيراد ملف Bicep من مدخل Azure لإنشاء مورد مواصفات قالب.

Microsoft.Resources/templateSpecs هو نوع المورد لمواصفات القالب. وهو يتألف من قالب رئيسي وأي عدد من القوالب المرتبطة. يخزن Azure مواصفات القالب بأمان في مجموعات الموارد. يجب أن يكون كل من القالب الرئيسي والقوالب المرتبطة في JSON. تدعم مواصفات القالب تعيين الإصدار.

لنشر مواصفات القالب، يمكنك استخدام أدوات Azure القياسية، مثل PowerShell وAzure CLI وبوابة Azure وREST وغيرها من عِدد تطوير البرامج والعملاء المعتمدة. يمكنك استخدام نفس الأوامر كما تفعل للقالب أو ملف Bicep.

إشعار

لاستخدام مواصفات القالب في Bicep مع Azure PowerShell، يجب عليك تثبيت الإصدار 6.3.0 أو أحدث. لاستخدامه مع Azure CLI، استخدم الإصدار 2.27.0 أو إصدار أحدث.

عند تصميم التوزيع الخاص بك، ضع في اعتبارك دائما دورة حياة الموارد وتجميع الموارد التي تشترك في دورة حياة مماثلة في مواصفات قالب واحد. على سبيل المثال، تتضمن عمليات النشر الخاصة بك مثيلات متعددة من Azure Cosmos DB مع كل مثيل يحتوي على قواعد البيانات والحاويات الخاصة به. نظراً لأن قواعد البيانات والحاويات لا تتغير كثيراً، فأنت تريد إنشاء مواصفات قالب واحدة لتضمين مثيل Cosmo DB وقواعد البيانات والحاويات الأساسية الخاصة به. يمكنك بعد ذلك استخدام عبارات شرطية في Bicep الخاص ك مع حلقات النسخ لإنشاء مثيلات متعددة من هذه الموارد.

تلميح

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

  • يتم دعم سجل الوحدة فقط من قبل Bicep. إذا لم تكن تستخدم Bicep بعد، فاستخدم مواصفات القالب.
  • لا يمكن توزيع المحتوى الموجود في سجل وحدة Bicep إلا من ملف Bicep آخر. يمكن توزيع مواصفات القالب مباشرةً من واجهة برمجة التطبيقات، وAzure PowerShell، وAzure CLI، ومدخل Azure. يمكنك حتى استخدام UiFormDefinition لتخصيص تجربة توزيع المدخل.
  • تتمتع Bicep ببعض الإمكانات المحدودة لتضمين عناصر المشروع الأخرى (بما في ذلك الملفات التي ليست من نوع Bicep وغير ذات قالب ARM. على سبيل المثال، نصوص PowerShell النصية ونصوص CLI وثنائيات أخرى) باستخدام الدالات loadTextContent وloadFileAsBase64. لا يمكن لمواصفات القالب حزم هذه البيانات الاصطناعية.

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

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

الأذونات المطلوبة

هناك دوران لإنشاء Azure معرفان لمواصفات القالب:

بالإضافة إلى ذلك، تحتاج أيضا إلى أذونات لنشر ملف Bicep. راجع Deploy - CLI أو Deploy - PowerShell.

لماذا نستخدم مواصفات القالب؟

توفر مواصفات القالب الفوائد التالية:

  • يمكنك استخدام قوالب ARM القياسية أو ملفات Bicep لمواصفات القالب الخاصة بك.
  • يمكنك إدارة الوصول من خلال Azure RBAC، بدلاً من رموز SAS المميزة.
  • يمكن للمستخدمين توزيع مواصفات القالب دون الحاجة إلى وصول عمليات الكتابة إلى ملف Bicep.
  • يمكنك دمج مواصفات القالب في عملية النشر الحالية، مثل برنامج PowerShell النصي أو مسار DevOps.

تمكنك مواصفات القالب من إنشاء قوالب أساسية ومشاركتها مع فرق العمل في مؤسستك. مواصفات القالب آمنة لأنها متوفرة لـ Azure Resource Manager للنشر، ولكن لا يمكن للمستخدمين الوصول إليها دون الإذن الصحيح. يحتاج المستخدمون فقط إلى الوصول إلى القراءة إلى مواصفات القالب لنشر قالبه، ومن ثمّ تتمكّن من مشاركة القالب دون السماح للآخرين بتعديله.

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

يجب التحقق من القوالب التي تقوم بتضمينها في مواصفات القالب بواسطة المسؤولين في مؤسستك لاتباع متطلبات المؤسسة وتوجيهاتها.

إنشاء مواصفات القالب

يُظهر المثال التالي ملف Bicep بسيطاً لإنشاء حساب تخزين في Azure.

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

resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

إنشاء مواصفات قالب باستخدام:

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.bicep

يمكنك أيضاً إنشاء مواصفات القالب باستخدام ملفات Bicep. ومع ذلك، يجب أن يكون محتوى mainTemplate في JSON. ينشئ القالب التالي مواصفات قالب لتوزيع حساب تخزين:

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2021-05-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2021-05-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  properties: {
    mainTemplate: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      'contentVersion': '1.0.0.0'
      'parameters': {
        'storageAccountType': {
          'type': 'string'
          'defaultValue': 'Standard_LRS'
          'allowedValues': [
            'Standard_LRS'
            'Standard_GRS'
            'Standard_ZRS'
            'Premium_LRS'
          ]
        }
      }
      'resources': [
        {
          'type': 'Microsoft.Storage/storageAccounts'
          'apiVersion': '2019-06-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

يجب أن يقوم قالب JSON المضمن في ملف Bicep بإجراء هذه التغييرات:

  • إزالة الفواصل في نهاية الأسطر.
  • استبدال علامات الاقتباس المزدوجة إلى علامات الاقتباس المفردة.
  • البعد عن استخدام علامات الاقتباس المفردة داخل التعبيرات. على سبيل المثال، 'name': '[parameters(\'storageAccountType\')]'.
  • للوصول إلى المعلمات والمتغيرات المعرفة في ملف Bicep، يمكنك استخدام أسماء المعلمات وأسماء المتغيرات مباشرة. للوصول إلى المعلمات والمتغيرات المعرفة في mainTemplate، لا تزال تحتاج إلى استخدام بناء جملة قالب ARM JSON. على سبيل المثال، 'name': '[parameters(\'storageAccountType\')]'.
  • استخدام بناء الجملة Bicep لاستدعاء وظائف Bicep. على سبيل المثال، 'location': resourceGroup().location.

حجم مواصفات القالب محدود بحوالي 2 ميغابايت. إذا تجاوز حجم مواصفات القالب الحد، سيظهر لك رمز الخطأ TemplateSpecTooLarge. تتضمن رسالة الخطأ:

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

يمكنك عرض كل مواصفات القالب في الاشتراك الخاص بك باستخدام:

Get-AzTemplateSpec

يمكنك عرض تفاصيل مواصفات القالب، بما في ذلك إصداراتها من خلال:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

مواصفات قالب التوزيع

بعد إنشاء مواصفات القالب، يمكن للمستخدمين الذين لديهم دور قارئ مواصفات القالب نشره. بالإضافة إلى ذلك، تحتاج أيضا إلى أذونات لنشر قالب ARM. راجع Deploy - CLI أو Deploy - PowerShell.

يمكن نشر مواصفات القالب من خلال المدخل أو PowerShell أو Azure CLI أو كوحدة Bicep في نشر قالب أكبر. يمكن للمستخدمين في مؤسسة ما نشر مواصفات قالب إلى أي نطاق في Azure (مجموعة الموارد أو الاشتراك أو مجموعة الإدارة أو المستأجر).

بدلاً من التمرير في مسار أو معرف موارد منتظم لملف Bicep، يمكنك توزيع مواصفات قالب عن طريق توفير معرف المورد الخاص به. يتميز معرف المورد بالتنسيق التالي:

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

لاحظ أن معرف المورد يتضمن اسم إصدار مواصفات القالب.

على سبيل المثال، يمكنك نشر مواصفات قالب من خلال الأمر التالي.

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

عمليّاً، سوف تقوم بشكل نمطي بتشغيل Get-AzTemplateSpec أو az ts show للحصول على معرّف مواصفات القالب الذي تريد نشره.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

يمكنك أيضاً فتح عنوان URL بالتنسيق التالي لنشر مواصفات قالب:

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

المعلمات

يعد تمرير المعلمات إلى مواصفات القالب مشابها لتمرير المعلمات إلى ملف Bicep. إضافة قيم المعلمة تكون إما بشكل مضمن أو في ملف معلمات.

المعلمات المُضمنة

لتمرير معلمة مضمّنة، استخدم:

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

ملفات المعلمات

  • استخدام ملف معلمات Bicep

    لإنشاء ملف معلمة Bicep، يجب تحديد العبارة using . إليك مثال:

    using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'

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

    لتمرير ملف المعلمة باستخدام:

    حاليا، لا يمكنك نشر مواصفات قالب مع ملف .bicepparam باستخدام Azure PowerShell.

  • استخدام ملف معلمات JSON

    JSON التالي هو نموذج ملف معلمات JSON:

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

    وقم بتمرير ملف المعلمة هذا باستخدام:

    New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

تعيين الإصدار

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

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

تساعدك العلاماتعلى تنظيم مواردك بشكل منطقي. يمكنك إضافة علامات إلى مواصفات القالب باستخدام Azure PowerShell وAzure CLI. يوضح المثال التالي كيفية تحديد العلامات عند إنشاء مواصفات القالب:

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

يوضح المثال التالي كيفية تطبيق العلامات عند تحديث مواصفات قالب موجودة:

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

يمكن أن يحتوي كل من القالب وإصداراته على علامات. يتم تطبيق العلامات أو توريثها استناداً إلى المعلمات التي تحددها.

مواصفات القالب ‏‏الإصدار معلمة الإصدار معلمة العلامة قيم العلامات
موجود ‏‫غير متوفر‬ غير محدد محدد مطبق على مواصفات القالب
موجود جديد محدد غير محدد موروث من مواصفات القالب إلى الإصدار
جديد جديد محدد محدد مطبق على كل من مواصفات القالب والإصدار
موجود جديد محدد محدد مطبق على الإصدار
موجود موجود محدد محدد مطبق على الإصدار

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

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

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

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