Resurs iteration i ARM-mallar

  • Artikel

Den här artikeln visar hur du skapar fler än en instans av en resurs i din Azure Resource Manager-mall (ARM-mall). Genom att lägga till en kopieringsloop i resursavsnittet i mallen kan du dynamiskt ange antalet resurser som ska distribueras. Du kan också undvika att behöva upprepa mallsyntaxen.

Du kan också använda en kopieringsloop med egenskaper, variabler och utdata.

Om du behöver ange om en resurs alls distribueras kan du läsa villkorselementet.

Tips

Vi rekommenderar Bicep eftersom det har samma funktioner som ARM-mallar och syntaxen är enklare att använda. Mer information finns i loopar.

Syntax

Lägg till elementet copy i resursavsnittet i mallen för att distribuera flera instanser av resursen. Elementet copy har följande allmänna format:

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

Egenskapen name är ett värde som identifierar loopen. Egenskapen count anger det antal iterationer som du vill ha för resurstypen.

mode Använd egenskaperna och batchSize för att ange om resurserna distribueras parallellt eller i följd. Dessa egenskaper beskrivs i Seriell eller Parallell.

Kopieringsgränser

Antalet får inte överstiga 800.

Antalet får inte vara ett negativt tal. Det kan vara noll om du distribuerar mallen med en ny version av Azure CLI, PowerShell eller REST API. Mer specifikt måste du använda:

  • Azure PowerShell 2.6 eller senare
  • Azure CLI 2.0.74 eller senare
  • REST API version 2019-05-10 eller senare
  • Länkade distributioner måste använda API-version 2019-05-10 eller senare för distributionsresurstypen

Tidigare versioner av PowerShell, CLI och REST API stöder inte noll för antal.

Var försiktig med att använda distribution i fullständigt läge med kopieringsloop. Om du distribuerar om med fullständigt läge till en resursgrupp tas alla resurser som inte anges i mallen efter att kopieringsloopen har lösts bort.

Resurs iteration

I följande exempel skapas antalet lagringskonton som anges i parametern storageCount .

{
  "$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": "2022-09-01",
      "name": "[format('{0}storage{1}', range(0, parameters('storageCount'))[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

Observera att namnet på varje resurs innehåller copyIndex() funktionen som returnerar den aktuella iterationen i loopen. copyIndex() är nollbaserat. Så, följande exempel:

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

Skapar följande namn:

  • storage0
  • storage1
  • storage2

Om du vill förskjuta indexvärdet kan du skicka ett värde i copyIndex() funktionen. Antalet iterationer anges fortfarande i kopieringselementet, men värdet copyIndex för förskjuts av det angivna värdet. Så, följande exempel:

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

Skapar följande namn:

  • storage1
  • storage2
  • storage3

Kopieringsåtgärden är användbar när du arbetar med matriser eftersom du kan iterera genom varje element i matrisen. length Använd funktionen i matrisen för att ange antalet iterationer och copyIndex för att hämta det aktuella indexet i matrisen.

I följande exempel skapas ett lagringskonto för varje namn som anges i parametern.

{
  "$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": "2022-09-01",
      "name": "[format('{0}{1}', parameters('storageNames')[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

Om du vill returnera värden från de distribuerade resurserna kan du använda kopiera i avsnittet utdata.

Använd symboliskt namn

Symboliskt namn tilldelas till resurskopieringsloopar. Loopindexet är nollbaserat. I följande exempel myStorages[1] refererar till den andra resursen i resursloopen.

{
  "$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": "2022-09-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]"
    }
  }
}

Om indexet är ett körningsvärde formaterar du referensen själv. Till exempel

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

Symboliska namn kan användas i dependsOn-matriser. Om ett symboliskt namn är för en kopieringsloop läggs alla resurser i loopen till som beroenden. Mer information finns i Beroenden på resurser i en loop.

Seriell eller parallell

Som standard skapar Resource Manager resurserna parallellt. Den tillämpar ingen gräns för antalet resurser som distribueras parallellt, förutom den totala gränsen på 800 resurser i mallen. Ordningen som de skapas i är inte garanterad.

Men du kanske vill ange att resurserna distribueras i följd. När du till exempel uppdaterar en produktionsmiljö kanske du vill flytta uppdateringarna så att endast ett visst nummer uppdateras samtidigt.

Om du vill distribuera fler än en instans av en resurs mode seriellt ochbatchSize till antalet instanser som ska distribueras åt gången. Med seriellt läge skapar Resource Manager ett beroende av tidigare instanser i loopen, så den startar inte en batch förrän den föregående batchen har slutförts.

Värdet för batchSize får inte överskrida värdet för count i kopieringselementet.

{
  "$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": "2022-09-01",
      "name": "[format('{0}storage{1}', range(0, 4)[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

Egenskapen mode accepterar också parallell, vilket är standardvärdet.

Iteration för en underordnad resurs

Du kan inte använda en kopieringsloop för en underordnad resurs. Om du vill skapa fler än en instans av en resurs som du vanligtvis definierar som kapslad i en annan resurs måste du i stället skapa den resursen som en resurs på den översta nivån. Du definierar relationen med den överordnade resursen via egenskaperna typ och namn.

Anta till exempel att du vanligtvis definierar en datauppsättning som en underordnad resurs i en datafabrik.

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

Om du vill skapa fler än en datauppsättning flyttar du den utanför datafabriken. Datauppsättningen måste vara på samma nivå som datafabriken, men den är fortfarande en underordnad resurs i datafabriken. Du bevarar relationen mellan datauppsättningen och datafabriken via egenskaperna typ och namn. Eftersom typen inte längre kan härledas från dess position i mallen måste du ange den fullständigt kvalificerade typen i formatet: {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}.

Om du vill upprätta en överordnad/underordnad relation med en instans av datafabriken anger du ett namn för datauppsättningen som innehåller det överordnade resursnamnet. Använd formatet {parent-resource-name}/{child-resource-name}.

I följande exempel visas implementeringen.

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

Exempelmallar

I följande exempel visas vanliga scenarier för att skapa fler än en instans av en resurs eller egenskap.

Mall Description
Kopiera lagring Distribuerar mer än ett lagringskonto med ett indexnummer i namnet.
Lagring av seriekopior Distribuerar flera lagringskonton en i taget. Namnet innehåller indexnumret.
Kopiera lagring med matris Distribuerar flera lagringskonton. Namnet innehåller ett värde från en matris.
Kopiera resursgrupp Distribuerar flera resursgrupper.

Nästa steg