Sdílet prostřednictvím

Iterace prostředků v šablonách ARM

  • Článek

Tento článek ukazuje, jak vytvořit více než jednu instanci prostředku v šabloně Azure Resource Manageru (šablona ARM). Přidáním smyčky kopírování do oddílu prostředků šablony můžete dynamicky nastavit počet prostředků, které se mají nasadit. Nemusíte také opakovat syntaxi šablony.

Můžete také použít smyčku kopírování s vlastnostmi, proměnnými a výstupy.

Pokud potřebujete určit, jestli je prostředek nasazený vůbec, podívejte se na prvek podmínky.

Tip

Doporučujeme Bicep, protože nabízí stejné možnosti jako šablony ARM a syntaxe se snadněji používá. Další informace najdete ve smyčce.

Syntaxe

copy Přidejte prvek do oddílu prostředků šablony pro nasazení více instancí prostředku. Element copy má následující obecný formát:

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

Vlastnost name je libovolná hodnota, která identifikuje smyčku. Vlastnost count určuje požadovaný počet iterací pro typ prostředku.

Pomocí vlastností mode můžete batchSize určit, jestli jsou prostředky nasazeny paralelně nebo v sekvenci. Tyto vlastnosti jsou popsány v sériovém nebo paralelním prostředí.

Omezení kopírování

Počet nesmí překročit 800.

Počet nemůže být záporné číslo. Pokud šablonu nasadíte pomocí nejnovější verze Azure CLI, PowerShellu nebo rozhraní REST API, může to být nula. Konkrétně musíte použít:

  • Azure PowerShell 2.6 nebo novější
  • Azure CLI 2.0.74 nebo novější
  • Rozhraní REST API verze 2019-05-10 nebo novější
  • Propojená nasazení musí pro typ prostředku nasazení používat rozhraní API verze 2019-05-10 nebo novější.

Starší verze PowerShellu, rozhraní příkazového řádku a rozhraní REST API nepodporují nulu pro počet.

Buďte opatrní při nasazování v úplném režimu se smyčkou kopírování. Pokud znovu nasadíte úplný režim do skupiny prostředků, odstraní se všechny prostředky, které nejsou zadané v šabloně po vyřešení smyčky kopírování.

Iterace prostředků

Následující příklad vytvoří počet účtů úložiště zadaných v parametru 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": {}
    }
  ]
}

Všimněte si, že název každého prostředku obsahuje copyIndex() funkci, která vrací aktuální iteraci ve smyčce. copyIndex() je založen na nule. Proto následující příklad:

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

Vytvoří tyto názvy:

  • storage0
  • storage1
  • storage2

Pokud chcete hodnotu indexu odsadit, můžete předat hodnotu ve copyIndex() funkci. Počet iterací je stále zadaný v elementu copy, ale hodnota copyIndex je posun o zadanou hodnotu. Proto následující příklad:

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

Vytvoří tyto názvy:

  • storage1
  • storage2
  • storage3

Operace kopírování je užitečná při práci s poli, protože můžete iterovat jednotlivé prvky v poli. length Pomocí funkce v poli můžete určit počet iterací a copyIndex načíst aktuální index v poli.

Následující příklad vytvoří jeden účet úložiště pro každý název zadaný v parametru.

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

Pokud chcete vracet hodnoty z nasazených prostředků, můžete použít kopírování v části Výstupy.

Použít symbolický název

Symbolický název se přiřadí smyčkám kopírování prostředků. Index smyčky je založený na nule. V následujícím příkladu myStorages[1] odkazuje na druhý prostředek ve smyčce prostředků.

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

Pokud je index hodnotou modulu runtime, naformátujte odkaz sami. Například

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

Symbolické názvy lze použít v polích dependsOn. Pokud je symbolický název smyčky kopírování, všechny prostředky ve smyčce se přidají jako závislosti. Další informace naleznete v tématu Závisí na prostředcích ve smyčce.

Sériové nebo paralelní

Ve výchozím nastavení Resource Manager vytvoří prostředky paralelně. Neplatí žádné omezení počtu paralelně nasazených prostředků, kromě celkového limitu 800 prostředků v šabloně. Pořadí, ve kterém jsou vytvořené, není zaručeno.

Můžete ale chtít určit, že se prostředky nasadí v sekvenci. Například při aktualizaci produkčního prostředí můžete chtít aktualizace rozmístit tak, aby se aktualizovalo jenom určité číslo najednou.

Pokud chcete sériově nasadit více než jednu instanci prostředku, nastavte mode na serial a batchSize na počet instancí, které se mají nasadit najednou. Pomocí sériového režimu Resource Manager vytvoří závislost na dřívějších instancích ve smyčce, takže nespustí jednu dávku, dokud se předchozí dávka nedokončí.

Hodnota batchSize nemůže překročit hodnotu prvku count copy.

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

Vlastnost mode také přijímá paralelně, což je výchozí hodnota.

Iterace pro podřízený prostředek

Smyčku kopírování nemůžete použít pro podřízený prostředek. Pokud chcete vytvořit více instancí prostředku, který obvykle definujete jako vnořený v rámci jiného prostředku, musíte tento prostředek vytvořit jako prostředek nejvyšší úrovně. Vztah s nadřazeným prostředkem definujete pomocí vlastností typu a názvu.

Předpokládejme například, že v datové továrně obvykle definujete datovou sadu jako podřízený prostředek.

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

Pokud chcete vytvořit více než jednu sadu dat, přesuňte ji mimo objekt pro vytváření dat. Datová sada musí být na stejné úrovni jako datová továrna, ale stále se jedná o podřízený prostředek datové továrny. Vztah mezi sadou dat a objektem pro vytváření dat zachováte prostřednictvím vlastností typu a názvu. Vzhledem k tomu, že typ již nelze odvodit z jeho pozice v šabloně, je nutné zadat plně kvalifikovaný typ ve formátu: {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}.

Pokud chcete vytvořit vztah nadřazenosti nebo podřízenosti s instancí datové továrny, zadejte název datové sady, která obsahuje nadřazený název prostředku. Použijte formát: {parent-resource-name}/{child-resource-name}.

Následující příklad ukazuje implementaci.

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

Ukázkové šablony

Následující příklady ukazují běžné scénáře pro vytvoření více instancí prostředku nebo vlastnosti.

Template Popis
Kopírování úložiště Nasadí více než jeden účet úložiště s číslem indexu v názvu.
Úložiště sériového kopírování Nasadí několik účtů úložiště najednou. Název obsahuje číslo indexu.
Kopírování úložiště s polem Nasadí několik účtů úložiště. Název obsahuje hodnotu z pole.
Kopírování skupiny prostředků Nasadí více skupin prostředků.

Další kroky