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

مقالة
09/26/2024

مواصفات القالب هي نوع مورد لتخزين قالب 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@2023-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

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep"

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

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

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2022-02-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@2022-02-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': '2023-04-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

az ts list

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

بوويرشيل
المبادره القطريه

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

az ts show \
    --name storageSpec \
    --resource-group templateSpecRG \
    --version "1.0a"

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

بعد إنشاء مواصفات القالب، يمكن للمستخدمين الذين لديهم دور قارئ مواصفات القالب نشره. بالإضافة إلى ذلك، تحتاج أيضا إلى أذونات لنشر قالب 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

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

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

بوويرشيل
المبادره القطريه

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

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

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0a" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters 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.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
بسبب العبارة using في ملف bicepparam. لا تحتاج إلى تحديد المعلمة --template-spec .

استخدام ملف معلمات 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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./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"}

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

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

بوويرشيل
المبادره القطريه

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

az ts update \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

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

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

ارتباط بمواصفات القالب

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

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

مشاركة عبر