Azure 资源管理器模板中的变量迭代Variable iteration in Azure Resource Manager templates

本文展示了如何为 Azure 资源管理器模板中的变量创建多个值。This article shows you how to create more than one value for a variable in your Azure Resource Manager template. 通过将 copy 元素添加到模板的 variables 节,可以在部署过程中动态设置变量的项数。By adding the copy element to the variables section of your template, you can dynamically set the number of items for a variable during deployment. 还可以避免重复模板语法。You also avoid having to repeat template syntax.

还可以将 copy 用于资源资源中的属性,以及输出You can also use copy with resources, properties in a resource, and outputs.

变量迭代Variable iteration

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

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

name 属性是标识循环的任何值。The name property is any value that identifies the loop. count 属性指定你希望该变量迭代的次数。The count property specifies the number of iterations you want for the variable.

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. 它可以是单个属性(例如字符串),也可以是具有多个属性的对象。It can be a single property (like a string), or an object with several properties.

以下示例展示了如何创建字符串值的数组:The following example shows how to create an array of string values:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "itemCount": {
            "type": "int",
            "defaultValue": 5
        }
     },
    "variables": {
        "copy": [
            {
                "name": "stringArray",
                "count": "[parameters('itemCount')]",
                "input": "[concat('item', copyIndex('stringArray', 1))]"
            }
        ]
    },
    "resources": [],
    "outputs": {
        "arrayResult": {
            "type": "array",
            "value": "[variables('stringArray')]"
        }
    }
}

前面的模板返回包含以下值的数组:The preceding template returns an array with the following values:

[
    "item1",
    "item2",
    "item3",
    "item4",
    "item5"
]

下一个示例展示了如何创建具有三个属性(name、diskSizeGB 和 diskIndex)的对象的数组。The next example shows how to create an array of objects with three properties - name, diskSizeGB, and diskIndex.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "itemCount": {
            "type": "int",
            "defaultValue": 5
        }
    },
    "variables": {
        "copy": [
            {
                "name": "objectArray",
                "count": "[parameters('itemCount')]",
                "input": {
                    "name": "[concat('myDataDisk', copyIndex('objectArray', 1))]",
                    "diskSizeGB": "1",
                    "diskIndex": "[copyIndex('objectArray')]"
                }
            }
        ]
    },
    "resources": [],
    "outputs": {
        "arrayResult": {
            "type": "array",
            "value": "[variables('objectArray')]"
        }
    }
}

前面的示例返回包含以下值的数组:The preceding example returns an array with the following values:

[
    {
        "name": "myDataDisk1",
        "diskSizeGB": "1",
        "diskIndex": 0
    },
    {
        "name": "myDataDisk2",
        "diskSizeGB": "1",
        "diskIndex": 1
    },
    {
        "name": "myDataDisk3",
        "diskSizeGB": "1",
        "diskIndex": 2
    },
    {
        "name": "myDataDisk4",
        "diskSizeGB": "1",
        "diskIndex": 3
    },
    {
        "name": "myDataDisk5",
        "diskSizeGB": "1",
        "diskIndex": 4
    }
]

Note

变量迭代支持偏移量参数。Variable iteration supports an offset argument. 偏移量必须在迭代名称之后,例如 copyIndex('diskNames', 1)。The offset must come after the name of the iteration, such as copyIndex('diskNames', 1). 如果未提供偏移量值,对于第一个实例,它将默认为 0。If you don't provide an offset value, it defaults to 0 for the first instance.

还可以在变量内使用 copy 元素。You can also use the copy element within a variable. 以下示例创建一个使用数组作为其值之一的对象。The following example creates an object that has an array as one of its values.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "itemCount": {
            "type": "int",
            "defaultValue": 5
        }
    },
    "variables": {
        "topLevelObject": {
            "sampleProperty": "sampleValue",
            "copy": [
                {
                    "name": "disks",
                    "count": "[parameters('itemCount')]",
                    "input": {
                        "name": "[concat('myDataDisk', copyIndex('disks', 1))]",
                        "diskSizeGB": "1",
                        "diskIndex": "[copyIndex('disks')]"
                    }
                }
            ]
        }
    },
    "resources": [],
    "outputs": {
        "objectResult": {
            "type": "object",
            "value": "[variables('topLevelObject')]"
        }
    }
}

前面的示例返回包含以下值的对象:The preceding example returns an object with the following values:

{
    "sampleProperty": "sampleValue",
    "disks": [
        {
            "name": "myDataDisk1",
            "diskSizeGB": "1",
            "diskIndex": 0
        },
        {
            "name": "myDataDisk2",
            "diskSizeGB": "1",
            "diskIndex": 1
        },
        {
            "name": "myDataDisk3",
            "diskSizeGB": "1",
            "diskIndex": 2
        },
        {
            "name": "myDataDisk4",
            "diskSizeGB": "1",
            "diskIndex": 3
        },
        {
            "name": "myDataDisk5",
            "diskSizeGB": "1",
            "diskIndex": 4
        }
    ]
}

下一示例显示了可以将 copy 用于变量的各种方式。The next example shows the different ways you can use copy with variables.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {
    "disk-array-on-object": {
      "copy": [
        {
          "name": "disks",
          "count": 5,
          "input": {
            "name": "[concat('myDataDisk', copyIndex('disks', 1))]",
            "diskSizeGB": "1",
            "diskIndex": "[copyIndex('disks')]"
          }
        },
        {
          "name": "diskNames",
          "count": 5,
          "input": "[concat('myDataDisk', copyIndex('diskNames', 1))]"
        }
      ]
    },
    "copy": [
      {
        "name": "top-level-object-array",
        "count": 5,
        "input": {
          "name": "[concat('myDataDisk', copyIndex('top-level-object-array', 1))]",
          "diskSizeGB": "1",
          "diskIndex": "[copyIndex('top-level-object-array')]"
        }
      },
      {
        "name": "top-level-string-array",
        "count": 5,
        "input": "[concat('myDataDisk', copyIndex('top-level-string-array', 1))]"
      },
      {
        "name": "top-level-integer-array",
        "count": 5,
        "input": "[copyIndex('top-level-integer-array')]"
      }
    ]
  },
  "resources": [],
  "outputs": {
    "exampleObject": {
      "value": "[variables('disk-array-on-object')]",
      "type": "object"
    },
    "exampleArrayOnObject": {
      "value": "[variables('disk-array-on-object').disks]",
      "type" : "array"
    },
    "exampleObjectArray": {
      "value": "[variables('top-level-object-array')]",
      "type" : "array"
    },
    "exampleStringArray": {
      "value": "[variables('top-level-string-array')]",
      "type" : "array"
    },
    "exampleIntegerArray": {
      "value": "[variables('top-level-integer-array')]",
      "type" : "array"
    }
  }
}

复制限制Copy limits

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

count 不能为负数。The count can't be a negative number. 如果使用 Azure PowerShell 2.6 或更高版本、Azure CLI 2.0.74 或更高版本或者 REST API 版本 2019-05-10 或更高版本部署模板,则可以将 count 设置为零。If you deploy a template with Azure PowerShell 2.6 or later, Azure CLI 2.0.74 or later, or REST API version 2019-05-10 or later, you can set count to zero. 更早版本的 PowerShell、CLI 和 REST API 不支持将 count 设为零。Earlier versions of PowerShell, CLI, and the REST API don't support zero for count.

示例模板Example templates

以下示例显示了为一个变量创建多个值的常见方案。The following examples show common scenarios for creating more than one value for a variable.

模板Template 说明Description
复制变量Copy variables 演示对变量进行迭代的不同方法。Demonstrates the different ways of iterating on variables.
多个安全规则Multiple security rules 将多个安全规则部署到网络安全组。Deploys several security rules to a network security group. 这会从参数构造安全规则。It constructs the security rules from a parameter. 有关参数,请参阅多个 NSG 参数文件For the parameter, see multiple NSG parameter file.

后续步骤Next steps