Iteração de propriedades em modelos do ARM

  • Artigo

Este artigo mostra-lhe como criar mais do que uma instância de uma propriedade no modelo do Azure Resource Manager (modelo arm). Ao adicionar um ciclo de cópia à secção de propriedades de um recurso no seu modelo, pode definir dinamicamente o número de itens de uma propriedade durante a implementação. Também evita ter de repetir a sintaxe do modelo.

Só pode utilizar o ciclo de cópia com recursos de nível superior, mesmo ao aplicar o ciclo de cópia a uma propriedade. Para saber mais sobre como alterar um recurso subordinado para um recurso de nível superior, veja Iteração de um recurso subordinado.

Também pode utilizar o ciclo de cópia com recursos, variáveis e saídas.

Dica

Recomendamos o Bicep porque oferece as mesmas capacidades que os modelos do ARM e a sintaxe é mais fácil de utilizar. Para saber mais, veja ciclos.

Syntax

Adicione o copy elemento à secção de recursos do modelo para definir o número de itens de uma propriedade. O elemento copy tem o seguinte formato geral:

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

Para name, indique o nome da propriedade de recurso que pretende criar.

A count propriedade especifica o número de iterações que pretende para a propriedade .

A input propriedade especifica as propriedades que pretende repetir. Pode criar uma matriz de elementos construídos a partir do valor na input propriedade .

Copiar limites

A contagem não pode exceder os 800.

A contagem não pode ser um número negativo. Pode ser zero se implementar o modelo com uma versão recente da CLI do Azure, do PowerShell ou da API REST. Especificamente, tem de utilizar:

  • Azure PowerShell 2.6 ou posterior
  • CLI do Azure 2.0.74 ou posterior
  • Versão da API REST 2019-05-10 ou posterior
  • As implementações ligadas têm de utilizar a versão de API 2019-05-10 ou posterior para o tipo de recurso de implementação

As versões anteriores do PowerShell, da CLI e da API REST não suportam zero para contagem.

Iteração de propriedades

O exemplo seguinte mostra como aplicar o ciclo de cópia à dataDisks propriedade numa máquina virtual:

{
  "$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": 3,
      "metadata": {
        "description": "The number of dataDisks to create."
      }
    },
    ...
  },
  "resources": [
    {
      "type": "Microsoft.Compute/virtualMachines",
      "apiVersion": "2022-11-01",
      ...
      "properties": {
        "storageProfile": {
          ...
          "copy": [
            {
              "name": "dataDisks",
              "count": "[parameters('numberOfDataDisks')]",
              "input": {
                "lun": "[copyIndex('dataDisks')]",
                "createOption": "Empty",
                "diskSizeGB": 1023
              }
            }
          ]
        }
        ...
      }
    }
  ]
}

Repare que ao utilizar copyIndex dentro de uma iteração de propriedade, tem de indicar o nome da iteração. A iteração da propriedade também suporta um argumento de deslocamento. O desvio tem de ser apresentado a seguir ao nome da iteração, como copyIndex('dataDisks', 1).

O modelo implementado torna-se:

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

A operação de cópia é útil ao trabalhar com matrizes porque pode iterar através de cada elemento na matriz. Utilize a função length na matriz para especificar a contagem de iterações e copyIndex para obter o índice atual na matriz.

O modelo de exemplo seguinte cria um grupo de ativação pós-falha para bases de dados transmitidas como uma matriz.

{
  "$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": "[format('{0}/{1}failovergroups', parameters('primaryServerName'), parameters('primaryServerName'))]"
  },
  "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": {
  }
}

O copy elemento é uma matriz, pelo que pode especificar mais do que uma propriedade para o recurso.

{
  "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": {
          ...
        }
      }
    ]
  }
}

Pode utilizar iterações de recursos e propriedades em conjunto. Referenciar a iteração da propriedade por nome.

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

Modelos de exemplo

O exemplo seguinte mostra um cenário comum para criar mais do que um valor para uma propriedade.

Modelo Descrição
Implementação da VM com um número variável de discos de dados Implementa vários discos de dados com uma máquina virtual.

Passos seguintes