Итерация ресурсов в шаблонах ARMResource iteration in ARM templates

В этой статье показано, как создать более одного экземпляра ресурса в шаблоне Azure Resource Manager (ARM).This article shows you how to create more than one instance of a resource in your Azure Resource Manager (ARM) template. Добавив элемент Copy в раздел ресурсов шаблона, можно динамически задать число развертываемых ресурсов.By adding the copy element to the resources section of your template, you can dynamically set the number of resources to deploy. Кроме того, не нужно повторять синтаксис шаблона.You also avoid having to repeat template syntax.

Можно также использовать Copy со свойствами, переменнымии выходными данными.You can also use copy with properties, variables, and outputs.

Если вам нужно указать, развернут ли ресурс, см. описание элемента condition.If you need to specify whether a resource is deployed at all, see condition element.

СинтаксисSyntax

Элемент Copy имеет следующий общий формат:The copy element has the following general format:

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

Свойство Name — это любое значение, идентифицирующее цикл.The name property is any value that identifies the loop. Свойство Count указывает количество итераций, которое требуется для типа ресурса.The count property specifies the number of iterations you want for the resource type.

Используйте свойства mode и BatchSize , чтобы указать, развертываются ли ресурсы параллельно или последовательно.Use the mode and batchSize properties to specify if the resources are deployed in parallel or in sequence. Эти свойства описаны в разделе последовательные или параллельные.These properties are described in Serial or Parallel.

Ограничения копированияCopy limits

Число не может превышать 800.The count can't exceed 800.

Число не может быть отрицательным числом.The count can't be a negative number. Если вы развертываете шаблон с помощью последней версии Azure CLI, PowerShell или REST API, он может быть равен нулю.It can be zero if you deploy the template with a recent version of Azure CLI, PowerShell, or REST API. В частности, необходимо использовать:Specifically, you must use:

  • Azure PowerShell 2,6 или более поздней версииAzure PowerShell 2.6 or later
  • Azure CLI 2.0.74 или более поздней версииAzure CLI 2.0.74 or later
  • REST API версии 2019-05-10 или более позднейREST API version 2019-05-10 or later
  • Связанные развертывания должны использовать API версии 2019-05-10 или более поздней для типа ресурса развертывания.Linked deployments must use API version 2019-05-10 or later for the deployment resource type

Более ранние версии PowerShell, CLI и REST API не поддерживают нулевое значение для счетчика.Earlier versions of PowerShell, CLI, and the REST API don't support zero for count.

Будьте внимательны при развертывании полного режима с помощью команды Copy.Be careful using complete mode deployment with copy. При повторном развертывании с полным режимом для группы ресурсов все ресурсы, не указанные в шаблоне после разрешения цикла копирования, удаляются.If you redeploy with complete mode to a resource group, any resources that aren't specified in the template after resolving the copy loop are deleted.

Итерация ресурсаResource iteration

В следующем примере создается число учетных записей хранения, указанное в параметре сторажекаунт .The following example creates the number of storage accounts specified in the storageCount parameter.

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

Обратите внимание, что имя каждого ресурса содержит функцию copyIndex(), которая возвращает текущую итерацию в цикле.Notice that the name of each resource includes the copyIndex() function, which returns the current iteration in the loop. Индекс copyIndex() отсчитывается от нуля.copyIndex() is zero-based. См. приведенный ниже пример.So, the following example:

"name": "[concat('storage', copyIndex())]",

Он создает следующие имена:Creates these names:

  • storage0;storage0
  • storage1;storage1
  • storage2.storage2.

Чтобы сместить значение индекса, можно передать нужное значение в функцию copyIndex().To offset the index value, you can pass a value in the copyIndex() function. Число итераций по-прежнему указывается в элементе Copy, но значение copyIndex смещается на указанное значение.The number of iterations is still specified in the copy element, but the value of copyIndex is offset by the specified value. См. приведенный ниже пример.So, the following example:

"name": "[concat('storage', copyIndex(1))]",

Он создает следующие имена:Creates these names:

  • storage1;storage1
  • storage2;storage2
  • storage3.storage3

Операция копирования удобна при работе с массивами, так как позволяет выполнить итерацию по каждому элементу в массиве.The copy operation is helpful when working with arrays because you can iterate through each element in the array. Используйте функцию length в массиве, чтобы указать число итераций, а также функцию copyIndex для получения текущего индекса в массиве.Use the length function on the array to specify the count for iterations, and copyIndex to retrieve the current index in the array.

В следующем примере создается одна учетная запись хранения для каждого имени, указанного в параметре.The following example creates one storage account for each name provided in the parameter.

{
  "$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"
          ]
      }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2019-04-01",
      "name": "[concat(parameters('storageNames')[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {},
      "copy": {
        "name": "storagecopy",
        "count": "[length(parameters('storageNames'))]"
      }
    }
  ],
  "outputs": {}
}

Если требуется возвращать значения из развернутых ресурсов, можно использовать Copy в разделе Outputs.If you want to return values from the deployed resources, you can use copy in the outputs section.

Последовательный или параллельныйSerial or Parallel

По умолчанию Resource Manager создает ресурсы параллельно.By default, Resource Manager creates the resources in parallel. Оно не ограничивает количество ресурсов, развернутых параллельно, за исключением общего ограничения в 800 ресурсов в шаблоне.It applies no limit to the number of resources deployed in parallel, other than the total limit of 800 resources in the template. Порядок, в котором они создаются, не гарантируется.The order in which they're created isn't guaranteed.

Тем не менее можно настроить последовательное развертывание ресурсов.However, you may want to specify that the resources are deployed in sequence. Например, при обновлении рабочей среды может потребоваться дифференцировать обновления, чтобы только определенное число элементов могло быть обновлено в любой момент времени.For example, when updating a production environment, you may want to stagger the updates so only a certain number are updated at any one time. Чтобы последовательно развернуть несколько экземпляров ресурса, задайте параметру mode значение serial, а в качестве значения batchSize введите число экземпляров, которое необходимо развернуть за раз.To serially deploy more than one instance of a resource, set mode to serial and batchSize to the number of instances to deploy at a time. В последовательном режиме Resource Manager создает зависимость от предыдущих экземпляров в цикле, поэтому он не начинает выполнение следующего пакета до завершения предыдущего.With serial mode, Resource Manager creates a dependency on earlier instances in the loop, so it doesn't start one batch until the previous batch completes.

Значение для параметра batchSize не может превышать значение для count в элементе Copy.The value for batchSize can't exceed the value for count in the copy element.

Например, чтобы последовательно развернуть две учетные записи хранения за раз, используйте следующую команду:For example, to serially deploy storage accounts two at a time, use:

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

Свойство mode также принимает значение parallel, которое является значением по умолчанию.The mode property also accepts parallel, which is the default value.

Зависимость от ресурсов в циклеDepend on resources in a loop

С помощью элемента dependsOn можно определить последовательность развертывания ресурсов.You specify that a resource is deployed after another resource by using the dependsOn element. Чтобы развернуть ресурс, который зависит от коллекции ресурсов в цикле, укажите имя цикла копирования в элементе dependsOn.To deploy a resource that depends on the collection of resources in a loop, provide the name of the copy loop in the dependsOn element. В следующем примере показано, как развернуть три учетные записи хранения перед развертыванием виртуальной машины.The following example shows how to deploy three storage accounts before deploying the virtual machine. Полное определение виртуальной машины не показано.The full virtual machine definition isn't shown. Обратите внимание, что для элемента copy задано имя storagecopy , а элемент dependsOn для виртуальной машины также имеет значение storagecopy .Notice that the copy element has name set to storagecopy and the dependsOn element for the virtual machine is also set to storagecopy.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2019-04-01",
      "name": "[concat(copyIndex(),'storage', uniqueString(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "copy": {
        "name": "storagecopy",
        "count": 3
      },
      "properties": {}
    },
    {
      "type": "Microsoft.Compute/virtualMachines",
      "apiVersion": "2015-06-15",
      "name": "[concat('VM', uniqueString(resourceGroup().id))]",
      "dependsOn": ["storagecopy"],
      ...
    }
  ],
  "outputs": {}
}

Итерация дочерних ресурсовIteration for a child resource

Нельзя включить дочерний ресурс в цикл копирования.You can't use a copy loop for a child resource. Чтобы создать несколько экземпляров ресурса, которые определяются как вложенные в другой ресурс, необходимо создать его как ресурс верхнего уровня.To create more than one instance of a resource that you typically define as nested within another resource, you must instead create that resource as a top-level resource. Вы можете определить связь с родительским ресурсом с помощью свойств type и name.You define the relationship with the parent resource through the type and name properties.

Предположим, вы определяете набор данных как дочерний ресурс фабрики данных.For example, suppose you typically define a dataset as a child resource within a data factory.

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

Чтобы создать несколько наборов данных, переместите его за пределы фабрики данных.To create more than one data set, move it outside of the data factory. Набор данных должен находиться на том же уровне, что и фабрика данных, но при этом он должен быть дочерним ресурсом фабрики данных.The dataset must be at the same level as the data factory, but it's still a child resource of the data factory. Вы можете сохранить связь между набором данных и фабрикой данных с помощью свойств type и name.You preserve the relationship between data set and data factory through the type and name properties. Так как тип нельзя определить по положению в шаблоне, укажите полное имя типа в следующем формате: {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}.Since type can no longer be inferred from its position in the template, you must provide the fully qualified type in the format: {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}.

Чтобы установить связь между родительским и дочерним ресурсами, укажите имя набора данных, которое включает имя родительского ресурса.To establish a parent/child relationship with an instance of the data factory, provide a name for the data set that includes the parent resource name. Используйте формат {parent-resource-name}/{child-resource-name}.Use the format: {parent-resource-name}/{child-resource-name}.

В следующем примере показано, как это сделать:The following example shows the implementation:

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

Образцы шаблоновExample templates

Ниже приведены примеры распространенных сценариев для создания нескольких экземпляров ресурса или свойства.The following examples show common scenarios for creating more than one instance of a resource or property.

ШаблонTemplate ОписаниеDescription
Копирования хранилищаCopy storage Развертывает несколько учетных записей хранения с номером индекса в имени.Deploys more than one storage account with an index number in the name.
Последовательное копирование хранилищаSerial copy storage Последовательно развертывает несколько учетных записей хранения.Deploys several storage accounts one at time. Имя содержит номер индекса.The name includes the index number.
Копирования хранилища с массивомCopy storage with array Развертывает несколько учетных записей хранения.Deploys several storage accounts. Имя содержит значение из массива.The name includes a value from an array.
Развертывание виртуальной машины с переменным количеством дисков данныхVM deployment with a variable number of data disks Развертывает несколько дисков данных с виртуальной машиной.Deploys several data disks with a virtual machine.
Несколько правил безопасностиMultiple security rules Развертывает несколько правил безопасности в группу безопасности сети.Deploys several security rules to a network security group. Кроме того, этот шаблон создает правила безопасности на основе параметра.It constructs the security rules from a parameter. Чтобы узнать параметр, см. файл параметров нескольких групп безопасности сети.For the parameter, see multiple NSG parameter file.

Дальнейшие действияNext steps