Iterace prostředků v šablonách ARM

  • Článek

V tomto článku se dozvíte, jak v šabloně Azure Resource Manager (šablona ARM) vytvořit více instancí prostředku. 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. Vyhnete se také opakování syntaxe š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 se prostředek vůbec nasadí, projděte si element condition.

Tip

Doporučujeme Bicep , protože nabízí stejné funkce jako šablony ARM a jeho použití je jednodušší. Další informace najdete v tématu Smyčky.

Syntax

Přidáním elementu copy do oddílu resources šablony nasaďte 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.

mode Pomocí vlastností a batchSize určete, jestli se prostředky nasadí paralelně nebo postupně. Tyto vlastnosti jsou popsány v části Sériové nebo Paralelní.

Limity kopírování

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

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

  • Azure PowerShell 2.6 nebo novější
  • Azure CLI 2.0.74 nebo novější
  • 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.

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

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. Následující příklad:

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

Vytvoří tyto názvy:

  • storage0
  • storage1
  • storage2

Pokud chcete hodnotu indexu posunout, můžete předat hodnotu ve copyIndex() funkci . Počet iterací je stále zadán v elementu copy, ale hodnota copyIndex je posunutá o zadanou hodnotu. 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ými prvky pole. length Pomocí funkce v poli můžete zadat 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 vrátit hodnoty z nasazených prostředků, můžete v části outputs použít kopírování.

Použít symbolický název

Smyčkám kopírování prostředků se přiřadí symbolický název. 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 pro smyčku kopírování, všechny prostředky ve smyčce se přidají jako závislosti. Další informace najdete v tématu Závisí na prostředcích ve smyčce.

Sériové nebo paralelní

Ve výchozím nastavení Resource Manager vytváří 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řeny, není zaručeno.

Můžete ale chtít určit, že se prostředky nasadí postupně. Například při aktualizaci produkčního prostředí můžete chtít rozmístit aktualizace tak, aby se v jednom okamžiku aktualizoval pouze určitý počet.

Pokud chcete sériově nasadit více instancí prostředku, nastavte mode na sériové a batchSize na počet instancí, které se mají nasadit najednou. V sériovém 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 pro batchSize nemůže překročit hodnotu pro count v elementu 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á parallel, 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 než jednu instanci prostředku, kterou obvykle definujete jako vnořenou v rámci jiného prostředku, musíte místo toho vytvořit tento prostředek jako prostředek nejvyšší úrovně. Vztah s nadřazeným prostředkem definujete prostřednictvím vlastností typu a názvu.

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

{
  "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 datovku. 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 odvozovat z jeho pozice v šabloně, musíte zadat plně kvalifikovaný typ ve formátu . {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}

Pokud chcete vytvořit vztah nadřazenosti a podřízenosti s instancí datové továrny, zadejte název datové sady, který obsahuje název nadřazeného 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 (Šablona) Description
Úložiště kopírování Nasadí více účtů úložiště s číslem indexu v názvu.
Úložiště sériové kopie 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írovat skupinu prostředků Nasadí několik skupin prostředků.

Další kroky