ARM 模板中的属性迭代Property iteration in ARM templates

本文介绍如何在 Azure 资源管理器 (ARM) 模板中创建一个属性的多个实例。This article shows you how to create more than one instance of a property in your Azure Resource Manager (ARM) template. 通过将 copy 元素添加到模板中资源的 properties 节,可以在部署过程中动态设置属性的项数。By adding the copy element to the properties section of a resource in your template, you can dynamically set the number of items for a property during deployment. 还可以避免重复模板语法。You also avoid having to repeat template syntax.

还可以将 copy 用于 resourcesvariablesoutputsYou can also use copy with resources, variables, and outputs.

语法Syntax

copy 元素采用以下常规格式:The copy element has the following general format:

"copy": [
  {
    "name": "<name-of-loop>",
    "count": <number-of-iterations>,
    "input": <values-for-the-property>
  }
]

对于 name,提供要创建的资源属性的名称。For name, provide the name of the resource property that you want to create.

count 属性指定要对该属性进行的迭代次数。The count property specifies the number of iterations you want for the property.

input 属性指定要重复的属性。The input property specifies the properties that you want to repeat. 你将创建一个由 input 属性中的值构造的元素数组。You create an array of elements constructed from the value in the input property.

复制限制Copy limits

count 不能超过 800。The count can't exceed 800.

count 不能为负数。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 不支持将 count 设为零。Earlier versions of PowerShell, CLI, and the REST API don't support zero for count.

属性迭代Property iteration

以下示例演示如何将 copy 应用到虚拟机上的 dataDisks 属性:The following example shows how to apply copy to the dataDisks property on a virtual machine:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "numberOfDataDisks": {
      "type": "int",
      "minValue": 0,
      "maxValue": 16,
      "defaultValue": 16,
      "metadata": {
        "description": "The number of dataDisks to create."
      }
    },
    ...
  },
  "resources": [
    {
      "type": "Microsoft.Compute/virtualMachines",
      "apiVersion": "2017-03-30",
      ...
      "properties": {
        "storageProfile": {
          ...
          "copy": [
            {
              "name": "dataDisks",
              "count": "[parameters('numberOfDataDisks')]",
              "input": {
                "diskSizeGB": 1023,
                "lun": "[copyIndex('dataDisks')]",
                "createOption": "Empty"
              }
            }
          ]
        }
      }
    }
  ]
}

请注意,在属性迭代中使用 copyIndex 时,必须提供迭代的名称。Notice that when using copyIndex inside a property iteration, you must provide the name of the iteration. 属性迭代还支持 offset 参数。Property iteration also supports an offset argument. 偏移量必须在迭代名称之后,例如 copyIndex('dataDisks', 1)。The offset must come after the name of the iteration, such as copyIndex('dataDisks', 1).

Resource Manager 在部署期间会扩展 copy 数组。Resource Manager expands the copy array during deployment. 该数组的名称将成为属性的名称。The name of the array becomes the name of the property. 输入值将成为对象属性。The input values become the object properties. 已部署的模板将成为:The deployed template becomes:

{
  "name": "examplevm",
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2017-03-30",
  "properties": {
    "storageProfile": {
      "dataDisks": [
        {
          "lun": 0,
          "createOption": "Empty",
          "diskSizeGB": 1023
        },
        {
          "lun": 1,
          "createOption": "Empty",
          "diskSizeGB": 1023
        },
        {
          "lun": 2,
          "createOption": "Empty",
          "diskSizeGB": 1023
        }
      ],
      ...

处理数组时可以使用复制操作,因为可对数组中的每个元素执行迭代操作。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 template creates a failover group for databases that are passed in as an array.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "primaryServerName": {
            "type": "string"
        },
        "secondaryServerName": {
            "type": "string"
        },
        "databaseNames": {
            "type": "array",
            "defaultValue": [
                "mydb1",
                "mydb2",
                "mydb3"
            ]
        }
    },
    "variables": {
        "failoverName": "[concat(parameters('primaryServerName'),'/', parameters('primaryServerName'),'failovergroups')]"
    },
    "resources": [
        {
            "type": "Microsoft.Sql/servers/failoverGroups",
            "apiVersion": "2015-05-01-preview",
            "name": "[variables('failoverName')]",
            "properties": {
                "readWriteEndpoint": {
                    "failoverPolicy": "Automatic",
                    "failoverWithDataLossGracePeriodMinutes": 60
                },
                "readOnlyEndpoint": {
                    "failoverPolicy": "Disabled"
                },
                "partnerServers": [
                    {
                        "id": "[resourceId('Microsoft.Sql/servers', parameters('secondaryServerName'))]"
                    }
                ],
                "copy": [
                    {
                        "name": "databases",
                        "count": "[length(parameters('databaseNames'))]",
                        "input": "[resourceId('Microsoft.Sql/servers/databases', parameters('primaryServerName'), parameters('databaseNames')[copyIndex('databases')])]"
                    }
                ]
            }
        }
    ],
    "outputs": {
    }
}

copy 元素是一个数组,因此,可以为资源指定多个属性。The copy element is an array so you can specify more than one property for the resource.

{
  "type": "Microsoft.Network/loadBalancers",
  "apiVersion": "2017-10-01",
  "name": "exampleLB",
  "properties": {
    "copy": [
      {
        "name": "loadBalancingRules",
        "count": "[length(parameters('loadBalancingRules'))]",
        "input": {
          ...
        }
      },
      {
        "name": "probes",
        "count": "[length(parameters('loadBalancingRules'))]",
        "input": {
          ...
        }
      }
    ]
  }
}

可将资源迭代和属性迭代结合使用。You can use resource and property iteration together. 按名称引用属性迭代。Reference the property iteration by name.

{
  "type": "Microsoft.Network/virtualNetworks",
  "apiVersion": "2018-04-01",
  "name": "[concat(parameters('vnetname'), copyIndex())]",
  "copy":{
    "count": 2,
    "name": "vnetloop"
  },
  "location": "[resourceGroup().location]",
  "properties": {
    "addressSpace": {
      "addressPrefixes": [
        "[parameters('addressPrefix')]"
      ]
    },
    "copy": [
      {
        "name": "subnets",
        "count": 2,
        "input": {
          "name": "[concat('subnet-', copyIndex('subnets'))]",
          "properties": {
            "addressPrefix": "[variables('subnetAddressPrefix')[copyIndex('subnets')]]"
          }
        }
      }
    ]
  }
}

示例模板Example templates

以下示例显示了为一个属性创建多个值的常见方案。The following example shows a common scenario for creating more than one value for a property.

模板Template 说明Description
数据磁盘数可变的 VM 部署VM deployment with a variable number of data disks 通过虚拟机部署多个数据磁盘。Deploys several data disks with a virtual machine.

后续步骤Next steps