Iterazione delle proprietà nei modelli ARMProperty iteration in ARM templates

Questo articolo illustra come creare più di un'istanza di una proprietà nel modello di Azure Resource Manager (modello ARM).This article shows you how to create more than one instance of a property in your Azure Resource Manager template (ARM template). Aggiungendo l'elemento Copy alla sezione Properties di una risorsa nel modello, è possibile impostare dinamicamente il numero di elementi per una proprietà durante la distribuzione.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. È anche possibile evitare di ripetere la sintassi del modello.You also avoid having to repeat template syntax.

È possibile usare solo copy con risorse di livello superiore, anche quando si applica la copia a una proprietà.You can only use copy with top-level resources, even when applying copy to a property. Per informazioni sulla modifica di una risorsa figlio in una risorsa di livello superiore, vedere iterazione per una risorsa figlio.To learn about changing a child resource to a top-level resource, see Iteration for a child resource.

È anche possibile usare copia con risorse, variabilie output.You can also use copy with resources, variables, and outputs.

SintassiSyntax

Il formato generale dell'elemento Copy è il seguente:The copy element has the following general format:

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

Per nomespecificare il nome della proprietà della risorsa che si desidera creare.For name, provide the name of the resource property that you want to create.

La proprietà count specifica il numero di iterazioni desiderate per la proprietà.The count property specifies the number of iterations you want for the property.

La proprietà di input specifica le proprietà che si desidera ripetere.The input property specifies the properties that you want to repeat. Si crea una matrice di elementi costruiti dal valore nella proprietà di input .You create an array of elements constructed from the value in the input property.

Limiti di copiaCopy limits

Il conteggio non può essere maggiore di 800.The count can't exceed 800.

Il conteggio non può essere un numero negativo.The count can't be a negative number. Può essere zero se si distribuisce il modello con una versione recente dell'interfaccia della riga di comando di Azure, PowerShell o l'API REST.It can be zero if you deploy the template with a recent version of Azure CLI, PowerShell, or REST API. In particolare, è necessario usare:Specifically, you must use:

  • Azure PowerShell 2,6 o versione successivaAzure PowerShell 2.6 or later
  • INTERFACCIA della riga di comando di Azure 2.0.74 o versione successivaAzure CLI 2.0.74 or later
  • API REST versione 2019-05-10 o successivaREST API version 2019-05-10 or later
  • Le distribuzioni collegate devono usare l'API versione 2019-05-10 o successiva per il tipo di risorsa di distribuzioneLinked deployments must use API version 2019-05-10 or later for the deployment resource type

Le versioni precedenti di PowerShell, l'interfaccia della riga di comando e l'API REST non supportano zero per Count.Earlier versions of PowerShell, CLI, and the REST API don't support zero for count.

Iterazione delle proprietàProperty iteration

Nell'esempio seguente viene illustrato come applicare copy alla proprietà dataDisks in una macchina virtuale: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"
              }
            }
          ]
        }
      }
    }
  ]
}

Si noti che quando si usa copyIndex all'interno di un'iterazione di proprietà, è necessario specificare il nome dell'iterazione.Notice that when using copyIndex inside a property iteration, you must provide the name of the iteration. L'iterazione della proprietà supporta anche un argomento offset.Property iteration also supports an offset argument. L'offset deve essere successivo al nome dell'iterazione, ad esempio copyIndex (' datadisks ', 1).The offset must come after the name of the iteration, such as copyIndex('dataDisks', 1).

Resource Manager espande la matrice copy durante la distribuzione.Resource Manager expands the copy array during deployment. Il nome della matrice diventa il nome della proprietà.The name of the array becomes the name of the property. I valori di input diventano le proprietà dell'oggetto.The input values become the object properties. Il modello distribuito diventa: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
        }
      ],
      ...

L'operazione di copia è utile quando si lavora con le matrici in quanto è possibile iterare ogni elemento della matrice.The copy operation is helpful when working with arrays because you can iterate through each element in the array. Usare la funzione length nella matrice per specificare il conteggio per le iterazioni e copyIndex per recuperare l'indice corrente nella matrice.Use the length function on the array to specify the count for iterations, and copyIndex to retrieve the current index in the array.

Il modello di esempio seguente crea un gruppo di failover per i database passati come matrice.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": {
    }
}

L'elemento di copia è una matrice, pertanto è possibile specificare più di una proprietà per una risorsa.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": {
          ...
        }
      }
    ]
  }
}

È possibile usare l'iterazione di risorse e di proprietà contemporaneamente.You can use resource and property iteration together. Fare riferimento all'iterazione di proprietà con il nome.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')]]"
          }
        }
      }
    ]
  }
}

Modelli di esempioExample templates

Nell'esempio seguente viene illustrato uno scenario comune per la creazione di più di un valore per una proprietà.The following example shows a common scenario for creating more than one value for a property.

ModelloTemplate DescrizioneDescription
Distribuzione VM con un numero variabile di dischi datiVM deployment with a variable number of data disks Distribuisce più dischi dati con una macchina virtuale.Deploys several data disks with a virtual machine.

Passaggi successiviNext steps