Freigeben über

Ressourceniteration in ARM-Vorlagen

In diesem Artikel erfahren Sie, wie Sie mehr als eine Instanz einer Ressource in Ihrer Azure Resource Manager-Vorlage (ARM-Vorlage) erstellen. Durch Hinzufügen einer Kopierschleife zum Ressourcenabschnitt Ihrer Vorlage können Sie die Anzahl der bereitzustellenden Ressourcen dynamisch festlegen. Sie müssen auch keine Vorlagensyntax wiederholen.

Sie können auch kopierschleifen mit Eigenschaften, Variablen und Ausgaben verwenden.

Wenn Sie angeben müssen, ob eine Ressource überhaupt bereitgestellt wird, lesen Sie das Bedingungselement .

Tipp

Bicep wird empfohlen, da sie dieselben Funktionen wie ARM-Vorlagen bietet und die Syntax einfacher zu verwenden ist. Weitere Informationen finden Sie unter Schleifen.

Syntax

Fügen Sie das copy Element zum Ressourcenabschnitt Ihrer Vorlage hinzu, um mehrere Instanzen der Ressource bereitzustellen. Das copy Element weist das folgende allgemeine Format auf:

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

Die name Eigenschaft ist ein beliebiger Wert, der die Schleife identifiziert. Die count Eigenschaft gibt die Anzahl der Gewünschten Iterationen für den Ressourcentyp an.

Verwenden Sie die Eigenschaften mode und batchSize, um anzugeben, ob die Ressourcen parallel oder in Reihenfolge bereitgestellt werden. Diese Eigenschaften werden serial oder parallel beschrieben.

Kopiergrenzwerte

Die Anzahl darf 800 nicht überschreiten oder eine negative Zahl sein. Dies kann null sein, wenn Sie die Vorlage mit einer aktuellen Version der Azure CLI, PowerShell oder REST-API bereitstellen. Insbesondere müssen Sie Folgendes verwenden:

  • Azure PowerShell 2.6 oder höher.
  • Azure CLI 2.0.74 oder höher.
  • REST API Version 2019-05-10 oder höher.
  • API-Version 2019-05-10 oder höher für den Bereitstellungsressourcentyp während verknüpfter Bereitstellungen.

Frühere Versionen von PowerShell, CLI und der REST-API unterstützen keine Null für die Anzahl.

Achten Sie darauf, die Vollständige Modusbereitstellung mit der Kopierschleife zu verwenden. Wenn Sie den vollständigen Modus für eine Ressourcengruppe erneut bereitstellen, werden alle Ressourcen, die nach dem Auflösen der Kopierschleife nicht in der Vorlage angegeben sind, gelöscht.

Ressourceniteration

Im folgenden Beispiel wird die Anzahl der im storageCount Parameter angegebenen Speicherkonten erstellt:

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

Beachten Sie, dass der Name jeder Ressource die copyIndex() Funktion enthält, die die aktuelle Iteration in der Schleife zurückgibt. copyIndex() ist nullbasiert. Im folgenden Beispiel geschieht Folgendes:

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

Erstellt diese Namen:

  • Speicher0
  • Speicher1
  • Speicher2

Zum Versetzen des Indexwerts können Sie einen Wert in der copyIndex()-Funktion übergeben. Die Anzahl der Iterationen wird weiterhin im Copy-Element angegeben, aber der Wert von copyIndex wird um den angegebenen Wert verschoben. Im folgenden Beispiel geschieht Folgendes:

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

Erstellt diese Namen:

  • Speicher1
  • Speicher2
  • Speicher3

Der Kopiervorgang ist beim Arbeiten mit Arrays hilfreich, da Sie jedes Element im Array durchlaufen können. Verwenden Sie die length Funktion im Array, um die Anzahl für Iterationen anzugeben und copyIndex den aktuellen Index im Array abzurufen.

Im folgenden Beispiel wird für jeden im Parameter angegebenen Namen ein Speicherkonto erstellt:

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

Wenn Sie Werte aus den bereitgestellten Ressourcen zurückgeben möchten, können Sie die Kopie im Ausgabeabschnitt verwenden.

Symbolischen Namen verwenden

Der symbolische Name wird Ressourcenkopierschleifen zugewiesen. Der Schleifenindex ist nullbasiert. Im folgenden Beispiel myStorages[1] wird auf die zweite Ressource in der Ressourcenschleife verwiesen:

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

Wenn der Index ein Laufzeitwert ist, formatieren Sie den Verweis selbst. Beispiel:

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

Symbolische Namen können in dependsOn-Arrays verwendet werden. Wenn ein symbolischer Name für eine Kopierschleife steht, werden alle Ressourcen in der Schleife als Abhängigkeiten hinzugefügt. Weitere Informationen finden Sie unter "Abhängig von Ressourcen in einer Schleife".

Seriell oder parallel

Standardmäßig erstellt der Ressourcen-Manager die Ressourcen parallel. Sie wendet keine Beschränkung auf die Anzahl der ressourcen an, die parallel zur Gesamtgrenze von 800 Ressourcen in der Vorlage bereitgestellt werden. Die Reihenfolge, in der sie erstellt werden, ist nicht garantiert.

Möglicherweise möchten Sie jedoch angeben, dass die Ressourcen in Sequenz bereitgestellt werden. Wenn Sie z. B. eine Produktionsumgebung aktualisieren, können Sie die Updates so gestaffelt, dass jeweils nur eine bestimmte Nummernaktualisierung möglich ist.

Um mehr als eine Instanz einer Ressource nacheinander bereitzustellen, setzen Sie mode auf seriell und batchSize auf die Anzahl der Instanzen, die jeweils bereitgestellt werden sollen. Im seriellen Modus erstellt der Ressourcen-Manager eine Abhängigkeit von früheren Instanzen in der Schleife, sodass erst ein Batch gestartet wird, wenn der vorherige Batch abgeschlossen ist.

Der Wert für batchSize den Wert für das Copy-Element darf den Wert count für das Copy-Element nicht überschreiten:

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

Die mode Eigenschaft akzeptiert auch parallel, was der Standardwert ist.

Iteration für eine untergeordnete Ressource

Für eine untergeordnete Ressource kann keine Kopierschleife verwendet werden. Um mehr als eine Instanz einer Ressource zu erstellen, die Sie in der Regel als in einer anderen Ressource geschachtelt definieren, müssen Sie diese Ressource stattdessen als Ressource auf oberster Ebene erstellen. Sie definieren die Beziehung mit der übergeordneten Ressource über die Typ- und Namenseigenschaften.

Angenommen, Sie definieren ein Dataset in der Regel als untergeordnete Ressource innerhalb einer Datenfactory:

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

Um mehr als ein Dataset zu erstellen, verschieben Sie es außerhalb der Datenfactory. Der Datensatz muss auf derselben Ebene wie die Datenfabrik sein, ist jedoch immer noch eine untergeordnete Ressource der Datenfabrik. Die Typ- und Namenseigenschaften behalten die Beziehung zwischen dem Dataset und der Datenfactory bei. Da der Typ nicht mehr von seiner Position in der Vorlage abgeleitet werden kann, müssen Sie den vollqualifizierten Typ in diesem Format angeben: {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}

Um eine Beziehung zwischen übergeordneten und untergeordneten Elementen mit einer Instanz der Datenfactory herzustellen, geben Sie einen Namen für das Dataset an, das den übergeordneten Ressourcennamen enthält. Verwenden Sie dieses Format: {parent-resource-name}/{child-resource-name}.

Das folgende Beispiel zeigt die Implementierung:

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

Beispielvorlagen

Die folgenden Beispiele zeigen allgemeine Szenarien zum Erstellen mehrerer Instanzen einer Ressource oder Eigenschaft.

Schablone BESCHREIBUNG
Kopieren des Speichers Stellt mehrere Speicherkonten mit einer Indexnummer im Namen bereit.
Serieller Kopierspeicher Stellt mehrere Speicherkonten gleichzeitig bereit. Der Name enthält die Indexnummer.
Kopieren von Speicher mit Array Stellt mehrere Speicherkonten bereit. Der Name enthält einen Wert aus einem Array.
Ressourcengruppe kopieren Stellt mehrere Ressourcengruppen bereit.

Nächste Schritte