Iteração de recursos em modelos do ARM

Este artigo mostra como criar mais de uma instância de um recurso em seu modelo do ARM (Azure Resource Manager). Ao adicionar o loop de cópia à seção de recursos do modelo, você pode definir dinamicamente o número de recursos a serem implantados. Você também evita ter que repetir a sintaxe do modelo.

Você também pode usar o loop de cópia com propriedades, variáveis e saídas.

Se você precisar especificar se um recurso está implantado de fato, consulte o elemento condição.

Dica

O Bicep é recomendado, pois oferece os mesmos recursos que os modelos do ARM e a sintaxe é mais fácil de usar. Para saber mais, confira loops.

Sintaxe

Adicione o copy elemento à seção de recursos do modelo para implantar várias instâncias do recurso. O copy elemento tem o seguinte formato geral:

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

A name propriedade é qualquer valor que identifique o loop. A count propriedade especifica o número de iterações desejadas para o tipo de recurso.

Use as propriedades mode e batchSize para especificar se os recursos são implantados em paralelo ou em sequência. Essas propriedades são descritas em série ou paralela.

Limites de cópia

A contagem não pode exceder 800 ou ser um número negativo. Pode ser zero se você implantar o modelo com uma versão recente da CLI do Azure, do PowerShell ou da API REST. Especificamente, você deve usar:

Azure PowerShell 2.6 ou posterior.
CLI do Azure 2.0.74 ou posterior.
API REST versão 2019-05-10 ou posterior.
Versão da API 2019-05-10 ou posterior para o tipo de recurso de implantação durante implantações vinculadas.

Versões anteriores do PowerShell, da CLI e da API REST não dão suporte a zero para a contagem.

Tenha cuidado ao usar implantação no modo completo com o loop de cópia. Se você reimplantar com o modo completo para um grupo de recursos, todos os recursos que não forem especificados no modelo após a resolução do loop de cópia serão excluídos.

Iteração de recursos

O exemplo a seguir cria o número de contas de armazenamento especificadas no storageCount parâmetro:

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

Observe que o nome de cada recurso inclui a copyIndex() função, que retorna a iteração atual no loop. copyIndex()é baseado em zero. Portanto, o exemplo a seguir:

"name": "[format('storage{0}', copyIndex())]",

Cria estes nomes:

storage0
armazenamento1
armazenamento2

Para deslocar o valor do índice, você pode passar um valor na função copyIndex(). O número de iterações ainda é especificado no elemento de cópia, mas o valor de copyIndex é deslocado pelo valor especificado. Portanto, o exemplo a seguir:

"name": "[format('storage{0}', copyIndex(1))]",

Cria estes nomes:

armazenamento1
armazenamento2
armazenamento3

A operação de cópia é útil ao trabalhar com matrizes porque você pode percorrer cada elemento da matriz. Use a length função na matriz para especificar a contagem de iterações e copyIndex recuperar o índice atual na matriz.

O exemplo a seguir cria uma conta de armazenamento para cada nome fornecido no parâmetro:

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

Se você quiser retornar valores dos recursos implantados, poderá usar a cópia na seção de saídas.

Usar nome simbólico

Nome simbólico será atribuído a ciclos de cópia de recursos. O índice de loop é baseado em zero. No exemplo a seguir, myStorages[1] faz referência ao segundo recurso no loop de recursos:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "storageCount": {
      "type": "int",
      "defaultValue": 2
    }
  },
  "resources": {
    "myStorages": {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2025-06-01",
      "name": "[format('{0}storage{1}', copyIndex(), uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {},
      "copy": {
        "name": "storagecopy",
        "count": "[parameters('storageCount')]"
      }
    }
  },
  "outputs": {
    "storageEndpoint":{
      "type": "object",
      "value": "[reference('myStorages[1]').primaryEndpoints]"
    }
  }
}

Se o índice for um valor em tempo de execução, formate a referência por conta própria. Por exemplo:

"outputs": {
  "storageEndpoint":{
    "type": "object",
    "value": "[reference(format('myStorages[{0}]', variables('runtimeIndex'))).primaryEndpoints]"
  }
}

Nomes simbólicos podem ser usados em matrizes dependsOn. Se um nome simbólico for para um loop de cópia, todos os recursos no loop serão adicionados como dependências. Para obter mais informações, confira recursos dependentes em um loop.

Serial ou paralelo

Por padrão, o Resource Manager cria os recursos em paralelo. Ele não aplica nenhum limite ao número de recursos implantados em paralelo além do limite total de 800 recursos no modelo. A ordem em que eles são criados não é garantida.

No entanto, convém especificar que os recursos são implantados em sequência. Por exemplo, ao atualizar um ambiente de produção, você pode escalonar as atualizações para que apenas um determinado número seja atualizado de uma só vez.

Para implantar serialmente mais de uma instância de um recurso, defina mode como serial e batchSize para o número de instâncias a serem implantadas de cada vez. Com o modo serial, o Resource Manager cria uma dependência em instâncias anteriores no loop para que ele não inicie um lote até que o lote anterior seja concluído.

O valor de batchSize não pode exceder o valor de count no elemento de cópia.

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

A mode propriedade também aceita paralelo, que é o valor padrão.

Iteração para um recurso filho

Você não pode usar um loop de cópia para um recurso filho. Para criar mais de uma instância de um recurso que você normalmente define como aninhado em outro recurso, você deve criar esse recurso como um recurso de nível superior. Você define a relação com o recurso pai por meio das propriedades de tipo e nome.

Por exemplo, suponha que você normalmente defina um conjunto de dados como um recurso filho dentro de uma fábrica de dados.

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

Para criar mais de um conjunto de dados, mova-os para fora da fábrica de dados. O conjunto de dados deve estar no mesmo nível hierárquico que a fábrica de dados, mas ainda assim continua sendo um recurso subordinado da fábrica de dados. As propriedades de tipo e nome preservam a relação entre o conjunto de dados e o Data Factory. Como o tipo não pode mais ser inferido de sua posição no modelo, você deve fornecer o tipo totalmente qualificado neste formato: {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}.

Para estabelecer uma relação pai/filho com uma instância do Azure Data Factory, forneça um nome para o conjunto de dados que inclui o nome do recurso pai. Use este formato: {parent-resource-name}/{child-resource-name}.

O exemplo a seguir mostra a implementação:

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

Modelos de exemplo

Os exemplos a seguir mostram cenários comuns para criar mais de uma instância de um recurso ou propriedade.

Modelo	Descrição
Armazenamento de cópia	Implanta várias contas de armazenamento, cada uma identificada por um número de índice no nome.
Armazenamento de cópia serial	Implanta várias contas de armazenamento uma por vez. O nome inclui o número do índice.
Armazenamento de cópia com matriz	Implanta várias contas de armazenamento. O nome inclui um valor de uma matriz.
Copiar grupo de recursos	Implanta vários grupos de recursos.

Próximas etapas

Para definir dependências de recursos criados em um loop de cópia, confira como definir a ordem para implantar recursos em modelos do ARM.
Para passar por um tutorial, consulte um para saber como criar várias instâncias de recursos com modelos do ARM.
Para um módulo do Microsoft Learn que aborda a cópia de recursos, veja como gerenciar implantações complexas na nuvem usando recursos avançados de modelos do ARM.
Para outros usos do loop de cópia, consulte:
Para obter informações sobre como usar cópia com modelos aninhados, confira como usar cópia.

Comentários

Esta página foi útil?

Last updated on 2025-08-07