تكرار المورد في قوالب ARM

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

يمكنك أيضاً استخدام حلقة النسخ مع خصائص، متغيرات، ومخرجات.

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

تلميح

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

بناء الجملة

أضف العنصر copy إلى قسم الموارد في قالبك لنشر مثيلات متعددة من المورد. يحتوي العنصر copy على التنسيق العام التالي:

"copy": {
  "name": "<name-of-loop>",
  "count": <number-of-iterations>,
  "mode": "serial" <or> "parallel",
  "batchSize": <number-to-deploy-serially>
}

الخاصية name هي أي قيمة تُعرف الحلقة. تحدد الخاصية count عدد التكرارات التي تريدها لنوع المورد.

استخدم خصائص mode وbatchSize لتحديد ما إذا كانت الموارد يتم نشرها بالتوازي أو تُنشر في تسلسل. تُوصف هذه الخصائص في تسلسلي أو متوازي.

حدود النسخ

لا يمكن أن يتجاوز العدد 800.

لا يمكن أن يكون العدد رقماً سالباً. يمكن أن يكون صفراً إذا قمت بتوزيع القالب باستخدام إصدار حديث من Azure CLI، أو PowerShell، أو REST API. تحديداً، يجب عليك استخدام:

• Azure PowerShell⁧⁩2.6⁧⁩أو أحدث
• Azure CLI⁧⁩2.0.74⁧⁩أو أحدث
• إصدار REST API ⁩2019-05-10⁦ أو أحدث
• ⁧⁩في عمليات التوزيع المرتبط⁧⁩يجب استخدام إصدار API⁧⁩2019-05-10⁧⁩أو أحدث لنوع مورد التوزيع

الإصدارات السابقة من PowerShell وCLI وواجهة برمجة تطبيقات REST لا تدعم الصفر للعد.

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

تكرار المورد

يُنشئ المثال التالي عدد حسابات التخزين المحددة في المعلمة storageCount.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "storageCount": {
      "type": "int",
      "defaultValue": 3
    }
  },
  "resources": [
    {
      "copy": {
        "name": "storagecopy",
        "count": "[length(range(0, parameters('storageCount')))]"
      },
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[format('{0}storage{1}', range(0, parameters('storageCount'))[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

لاحظ أن اسم كل مورد يتضمن الدالة copyIndex() التي ترجع التكرار الحالي في الحلقة. copyIndex() قائم على صفر. لذلك، فإن المثال التالي:

"name": "[format('storage{0}', copyIndex())]",

يقوم بإنشاء هذه الأسماء:

• storage0
• storage1
• storage2

لإزاحة قيمة الفهرس، يمكنك إدخال قيمة في الدالة copyIndex(). لا يزال عدد التكرارات محدداً في عنصر النسخ، ولكن يتم إزاحة قيمة copyIndex بواسطة القيمة المحددة. لذلك، فإن المثال التالي:

"name": "[format('storage{0}', copyIndex(1))]",

يقوم بإنشاء هذه الأسماء:

• storage1
• storage2
• storage3

عملية النسخ مفيدة عند العمل مع الصفائف لأنه يمكنك التكرار خلال كل عنصر في الصفيف. استخدم دالة length على الصفيف لتحديد عدد التكرارات، واستخدم copyIndex لاسترداد الفهرس الحالي في الصفيف.

يُنشئ المثال التالي حساب تخزين واحد لكل اسم متوفر في المعلمة.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageNames": {
      "type": "array",
      "defaultValue": [
        "contoso",
        "fabrikam",
        "coho"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "copy": {
        "name": "storagecopy",
        "count": "[length(parameters('storageNames'))]"
      },
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[format('{0}{1}', parameters('storageNames')[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

إذا كنت تريد إرجاع قيم من الموارد المنشورة، يمكنك استخدام النسخ في قسم المخرجات.

استخدام اسم رمزي

سيتم تعيين الاسم الرمزي إلى حلقات نسخ الموارد. فهرس التكرار الحلقي يستند إلى الصفر. في المثال التالي، myStorages[1] يشير إلى المورد الثاني في حلقة المورد.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "storageCount": {
      "type": "int",
      "defaultValue": 2
    }
  },
  "resources": {
    "myStorages": {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[format('{0}storage{1}', copyIndex(), uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {},
      "copy": {
        "name": "storagecopy",
        "count": "[parameters('storageCount')]"
      }
    }
  },
  "outputs": {
    "storageEndpoint":{
      "type": "object",
      "value": "[reference('myStorages[1]').primaryEndpoints]"
    }
  }
}

إذا كان الفهرس قيمة وقت التشغيل، فقم بتنسيق المرجع بنفسك. على سبيل المثال

"outputs": {
  "storageEndpoint":{
    "type": "object",
    "value": "[reference(format('myStorages[{0}]', variables('runtimeIndex'))).primaryEndpoints]"
  }
}

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

تسلسلي أو متوازي

بشكل افتراضي، يقوم Azure Resource Manager بإنشاء الموارد بالتوازي. ولا يُطبق أي حد لعدد الموارد التي يتم نشرها بالتوازي، بخلاف الحد الإجمالي للموارد في القالب وهو 800 مورد. الترتيب الذي يتم إنشاؤها به غير مضمون.

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

لنشر أكثر من مثيل واحد من مورد بشكل تسلسلي، قم بتعيين mode إلى تسلسلي وbatchSize إلى عدد المثيلات التي يتم نشرها في كل مرة. مع الوضع التسلسلي، ينشئ Azure Resource Manager تبعية على مثيلات سابقة في الحلقة، بحيث لا يبدأ دُفعة واحدة حتى تكتمل الدفعة السابقة.

لا يمكن أن تتجاوز قيمة batchSize القيمة count في عنصر النسخ.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "copy": {
        "name": "storagecopy",
        "count": 4,
        "mode": "serial",
        "batchSize": 2
      },
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[format('{0}storage{1}', range(0, 4)[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

تقبل الخاصية mode أيضاً التوازي، وهي القيمة الافتراضية.

تكرار لمورد تابع

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

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

{
  "resources": [
    {
      "type": "Microsoft.DataFactory/factories",
      "name": "exampleDataFactory",
      ...
      "resources": [
        {
          "type": "datasets",
          "name": "exampleDataSet",
          "dependsOn": [
            "exampleDataFactory"
          ],
          ...
        }
      ]
      ...
    }
  ]
}

لإنشاء أكثر من مجموعة بيانات، قم بنقلها خارج Data Factory. يجب أن تكون مجموعة البيانات في نفس مستوى Data Factory، ولكنها لا تزال مورداً تابعاً لData Factory. يمكنك الحفاظ على العلاقة بين مجموعة البيانات وData Factory من خلال نوع الخصائص واسمها. وبما أنه لم يعد بالإمكان استنتاج النوع من موقعه في القالب، يجب توفير النوع المؤهّل بالكامل بالتنسيق: {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}.

لتأسيس علاقة أصل/تابع مع مثيل Data Factory، قم بتوفير اسم لمجموعة البيانات التي تتضمن اسم المورد الأصل. استخدم التنسيق: {parent-resource-name}/{child-resource-name}.

يوضح المثال التالي التطبيق.

"resources": [
{
  "type": "Microsoft.DataFactory/factories",
  "name": "exampleDataFactory",
  ...
},
{
  "type": "Microsoft.DataFactory/factories/datasets",
  "name": "[format('exampleDataFactory/exampleDataSet{0}', copyIndex())]",
  "dependsOn": [
    "exampleDataFactory"
  ],
  "copy": {
    "name": "datasetcopy",
    "count": "3"
  },
  ...
}]

قوالب المثال

تعرض الأمثلة التالية سيناريوهات شائعة لإنشاء أكثر من مثيل واحد من مورد أو خاصية.

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

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

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