Iterazione delle risorse nei modelli ARMResource iteration in ARM templates

  • 5 minuti per la lettura

Questo articolo illustra come creare più di un'istanza di una risorsa nel modello di 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. Aggiungendo l'elemento Copy alla sezione Resources del modello, è possibile impostare dinamicamente il numero di risorse da distribuire.By adding the copy element to the resources section of your template, you can dynamically set the number of resources to deploy. È anche possibile evitare di ripetere la sintassi del modello.You also avoid having to repeat template syntax.

È anche possibile usare copia con Proprietà, variabili e output.You can also use copy with properties, variables and outputs.

Se è necessario specificare se una risorsa viene distribuita, vedere l'elemento condizionale.If you need to specify whether a resource is deployed at all, see condition element.

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>,
  "mode": "serial" <or> "parallel",
  "batchSize": <number-to-deploy-serially>
}

La proprietà Name è qualsiasi valore che identifica il ciclo.The name property is any value that identifies the loop. La proprietà count specifica il numero di iterazioni desiderate per il tipo di risorsa.The count property specifies the number of iterations you want for the resource type.

Usare le proprietà mode e BatchSize per specificare se le risorse vengono distribuite in parallelo o in sequenza.Use the mode and batchSize properties to specify if the resources are deployed in parallel or in sequence. Queste proprietà sono descritte in serie o in parallelo.These properties are described in Serial or Parallel.

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.

Prestare attenzione quando si usa la distribuzione in modalità completa con Copy.Be careful using complete mode deployment with copy. Se si esegue la ridistribuzione con la modalità completa in un gruppo di risorse, tutte le risorse non specificate nel modello dopo la risoluzione del ciclo di copia verranno eliminate.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.

Iterazione delle risorseResource iteration

Nell'esempio seguente viene creato il numero di account di archiviazione specificato nel parametro storageCount .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": {}
}

Si noti che il nome di ogni risorsa include la funzione copyIndex() che restituisce l'iterazione corrente nel ciclo.Notice that the name of each resource includes the copyIndex() function, which returns the current iteration in the loop. copyIndex() è in base zero.copyIndex() is zero-based. Quindi l'esempio seguente:So, the following example:

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

Crea questi nomi:Creates these names:

  • storage0storage0
  • storage1storage1
  • storage2storage2.

Per eseguire l'offset del valore di indice, è possibile passare un valore nella funzione copyIndex().To offset the index value, you can pass a value in the copyIndex() function. Il numero di iterazioni è ancora specificato nell'elemento Copy, ma il valore di copyIndex è offset in base al valore specificato.The number of iterations is still specified in the copy element, but the value of copyIndex is offset by the specified value. Quindi l'esempio seguente:So, the following example:

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

Crea questi nomi:Creates these names:

  • storage1storage1
  • storage2storage2
  • storage3storage3

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.

Nell'esempio seguente viene creato un account di archiviazione per ogni nome specificato nel parametro.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": {}
}

Se si desidera restituire valori dalle risorse distribuite, è possibile usare Copy nella sezione Outputs.If you want to return values from the deployed resources, you can use copy in the outputs section.

Seriale o parallelaSerial or Parallel

Per impostazione predefinita, Gestione risorse crea le risorse in parallelo.By default, Resource Manager creates the resources in parallel. Non viene applicato alcun limite al numero di risorse distribuite in parallelo, oltre al limite totale di 800 risorse nel modello.It applies no limit to the number of resources deployed in parallel, other than the total limit of 800 resources in the template. L'ordine di creazione non è garantito.The order in which they're created isn't guaranteed.

Tuttavia è consigliabile specificare che le risorse vengano distribuite in sequenza.However, you may want to specify that the resources are deployed in sequence. Ad esempio, quando si aggiorna un ambiente di produzione, è consigliabile sfalsare gli aggiornamenti per aggiornarne solo un determinato numero in un dato momento.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. Per distribuire in modo seriale più istanze di una risorsa, impostare mode su serial e batchSize sul numero di istanze da distribuire contemporaneamente.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. Con la modalità seriale, Resource Manager crea una dipendenza da istanze precedenti nel ciclo in modo un batch venga avviato solo dopo il completamento del batch precedente.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.

Ad esempio, per distribuire in modo seriale gli account di archiviazione due alla volta, usare: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": {}
}

La proprietà mode accetta anche parallel, che è il valore predefinito.The mode property also accepts parallel, which is the default value.

In base alle risorse in un cicloDepend on resources in a loop

L'elemento dependsOn consente di specificare che una risorsa sia distribuita dopo un'altra.You specify that a resource is deployed after another resource by using the dependsOn element. Per distribuire una risorsa che dipende dalla raccolta di risorse in un ciclo, usare il nome del ciclo di copia nell'elemento 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. Nell'esempio seguente viene illustrato come distribuire tre account di archiviazione prima di distribuire la macchina virtuale.The following example shows how to deploy three storage accounts before deploying the virtual machine. La definizione completa della macchina virtuale non viene visualizzata.The full virtual machine definition isn't shown. Si noti che il nome dell'elemento Copy è impostato su storagecopy e anche l'elemento dependsOn per la macchina virtuale è impostato su 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": {}
}

Iterazione di una risorsa figlioIteration for a child resource

Non è possibile usare un ciclo di copia per una risorsa figlio.You can't use a copy loop for a child resource. Per creare più istanze di una risorsa cosiddetta "annidata" all'interno di un'altra risorsa è invece necessario creare tale risorsa come una risorsa di livello superiore.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. La relazione con la risorsa padre si definisce con le proprietà type e name.You define the relationship with the parent resource through the type and name properties.

Si supponga, ad esempio, di definire in genere un set di dati come una risorsa figlio all'interno di una data factory.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"
      ],
      ...
    }
  ]

Per creare più set di dati, spostarlo all'esterno della data factory.To create more than one data set, move it outside of the data factory. Il set di dati deve essere sullo stesso livello della data factory, di cui è comunque una risorsa figlio.The dataset must be at the same level as the data factory, but it's still a child resource of the data factory. La relazione fra set di dati e data factory viene mantenuta con le proprietà type e name.You preserve the relationship between data set and data factory through the type and name properties. Poiché non è possibile dedurre il tipo dalla sua posizione nel modello, è necessario specificarne il nome completo nel formato: {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}.

Per stabilire una relazione padre/figlio con un'istanza della data factory, specificare il nome del set di dati che include il nome della risorsa padre.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. Usare il formato: {parent-resource-name}/{child-resource-name}.Use the format: {parent-resource-name}/{child-resource-name}.

Nell'esempio seguente viene descritta l'implementazione: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"
  },
  ...
}]

Modelli di esempioExample templates

Gli esempi seguenti mostrano alcuni scenari comuni per la creazione di più istanze di una risorsa o proprietà.The following examples show common scenarios for creating more than one instance of a resource or property.

ModelloTemplate DescrizioneDescription
Copia risorsa di archiviazioneCopy storage Distribuisce più account di archiviazione con un numero di indice nel nome.Deploys more than one storage account with an index number in the name.
Copia seriale risorse di archiviazioneSerial copy storage Distribuisce più account di archiviazione uno alla volta.Deploys several storage accounts one at time. Il nome include il numero di indice.The name includes the index number.
Copia risorsa di archiviazione con matriceCopy storage with array Distribuisce più account di archiviazione.Deploys several storage accounts. Il nome include un valore di una matrice.The name includes a value from an array.
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.
Più regole di sicurezzaMultiple security rules Distribuisce più regole di sicurezza a un gruppo di sicurezza di rete.Deploys several security rules to a network security group. Costruisce le regole di sicurezza da un parametro.It constructs the security rules from a parameter. Per il parametro, vedere il file di parametri NSG multipli.For the parameter, see multiple NSG parameter file.

Passaggi successiviNext steps