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

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

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

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

إشعار

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

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

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

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

تلميح

نوصي باستخدام Bicep لأنها تقدم نفس الإمكانات التي توفرها نماذج ARM ولأن البنية أسهل في الاستخدام. لمعرفة المزيد، راجع مواصفات قالب Azure Resource Manager في Bicep.

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

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

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

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

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

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

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

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

• قارئ مواصفات القالب
• مساهم مواصفات القالب

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

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

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

{
  "$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": "[concat('store', uniquestring(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "kind": "StorageV2",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      }
    }
  ]
}

عند إنشاء مواصفات القالب، يتم تمرير أوامر PowerShell أو CLI عبر ملف القالب الرئيسي. إذا كانت مراجع القالب الرئيسية مرتبطة بقوالب، فسوف تجدها الأوامر وتقوم بحزمها لإنشاء مواصفات القالب. لمعرفة المزيد، راجع إنشاء مواصفات قالب مع قوالب مرتبطة.

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

بوويرشيل

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

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

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

يمكنك أيضاً إنشاء مواصفات القالب باستخدام قوالب Azure Resource Manager. ينشئ القالب التالي مواصفات قالب لتوزيع حساب تخزين:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "templateSpecName": {
      "type": "string",
      "defaultValue": "CreateStorageAccount"
    },
    "templateSpecVersionName": {
      "type": "string",
      "defaultValue": "0.1"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/templateSpecs",
      "apiVersion": "2021-05-01",
      "name": "[parameters('templateSpecName')]",
      "location": "[parameters('location')]",
      "properties": {
        "description": "A basic templateSpec - creates a storage account.",
        "displayName": "Storage account (Standard_LRS)"
      }
    },
    {
      "type": "Microsoft.Resources/templateSpecs/versions",
      "apiVersion": "2021-05-01",
      "name": "[format('{0}/{1}', parameters('templateSpecName'), parameters('templateSpecVersionName'))]",
      "location": "[parameters('location')]",
      "dependsOn": [
        "[resourceId('Microsoft.Resources/templateSpecs', parameters('templateSpecName'))]"
      ],
      "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": "[concat('store', uniquestring(resourceGroup().id))]",
              "location": "[resourceGroup().location]",
              "kind": "StorageV2",
              "sku": {
                "name": "[parameters('storageAccountType')]"
              }
            }
          ]
        }
      }
    }
  ]
}

حجم مواصفات القالب محدود بحوالي 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 أو كقالب مرتبط في عملية نشر أكبر للقوالب. يمكن للمستخدمين في مؤسسة ما نشر مواصفات قالب إلى أي نطاق في Azure (مجموعة الموارد أو الاشتراك أو مجموعة الإدارة أو المستأجر).

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

/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}

المعلمات

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

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

بوويرشيل

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

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters storageAccountType='Standard_GRS'

لإنشاء ملف معلمة محلي، استخدم ما يلي:

{
  "$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.json `
  -Tag @{Dept="Finance";Environment="Production"}

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

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

بوويرشيل

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

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

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

عند إنشاء أو تعديل مواصفات قالب مع معلمة الإصدار المحددة، ولكن من دون معلمة العلامة/العلامات:

• إذا كانت مواصفات القالب موجودة ولها علامات، ولكن الإصدار غير موجود، فإن الإصدار الجديد يرث العلامات نفسها التي تتوفر لمواصفات القالب الحالية.

عند إنشاء أو تعديل مواصفات قالب تتميز بمعلمة العلامة/العلامات ومعلمة الإصدار المحددتين:

• إذا لم تكن مواصفات القالب والإصدار موجودين، تتم إضافة العلامات إلى كلّ من مواصفات القالب الجديدة والإصدار الجديد.
• إذا كانت مواصفات القالب موجودة، ولكن الإصدار غير موجود، تتم إضافة العلامات فقط إلى الإصدار الجديد.
• إذا كان كلّ من مواصفات القالب والإصدار موجودين، فإن العلامات تنطبق فقط على الإصدار.

عند تعديل قالب يتميز بمعلمة العلامة /العلامات المحددة ولكن من دون تحديد معلمة الإصدار، تتم إضافة العلامات فقط إلى مواصفات القالب.

إنشاء مواصفات قالب مع قوالب مرتبطة

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

يتكون المثال التالي من قالب رئيسي مع قالبين مرتبطين. المثال هو مجرد اقتباس من القالب. لاحظ أنه يستخدم خاصية تُسمى relativePath للارتباط بالقوالب الأخرى. يجب عليك استخدام apiVersion من 2020-06-01 أو في وقت لاحق لموارد عمليات النشر.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/webapp.json"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/database.json"
        }
      }
    }
  ],
  "outputs": {}
}

عند تنفيذ أمر PowerShell أو CLI لإنشاء مواصفات القالب للمثال السابق، يجد الأمر ثلاثة ملفات: القالب الرئيسي، وقالب تطبيق الويب (webapp.json)، وقالب قاعدة البيانات (database.json)، ويقوم بحزمها في مواصفات القالب.

لمزيد من المعلومات، راجع البرنامج التعليمي: إنشاء مواصفات قالب مع قوالب مرتبطة.

نشر مواصفات القالب كقالب مرتبط

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

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

المثال التالي مشابه للمثال السابق، ولكن يمكنك استخدام خاصية id للارتباط بمواصفات قالب بدلاً من خاصية relativePath للارتباط بقالب محلي. استخدم 2020-06-01 لإصدار واجهة برمجة التطبيقات لمورد عمليات النشر. في المثال، تكون مواصفات القالب في مجموعة موارد تُسمى templateSpecsRG.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "networkingDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'networkingSpec', '1.0a')]"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "storageDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'storageSpec', '1.0a')]"
        }
      }
    }
  ],
  "outputs": {}
}

لمزيد من المعلومات حول ربط مواصفات القالب، راجع البرنامج التعليمي: نشر مواصفات قالب كقالب مرتبط.

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

• لإنشاء مواصفات القالب ونشرها، راجع التشغيل السريع: إنشاء مواصفات القالب ونشرها.

• لمزيد من المعلومات حول ربط القوالب في مواصفات القالب، راجع البرنامج التعليمي: إنشاء مواصفات قالب مع قوالب مرتبطة.

• لمزيد من المعلومات حول نشر مواصفات قالب كقالب مرتبط، راجع البرنامج التعليمي: نشر مواصفات قالب كقالب مرتبط.