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

Wir empfehlen Bicep , da es die gleichen 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 in Serial oder Parallel beschrieben.

Kopiergrenzwerte

Die Anzahl darf 800 nicht überschreiten.

Die Anzahl kann keine negative Zahl sein. Dies kann null sein, wenn Sie die Vorlage mit einer aktuellen Version von 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
  • Verknüpfte Bereitstellungen müssen API-Version 2019-05-10 oder höher für den Bereitstellungsressourcentyp verwenden.

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

Seien Sie vorsichtig, wenn Sie die Bereitstellung im vollständigen Modus mit der Kopierschleife 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 parallel bereitgestellten Ressourcen an, außer der Gesamtgrenze von 800 Ressourcen in der Vorlage. 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, möchten Sie die Updates möglicherweise staffeln, sodass nur eine bestimmte Anzahl von Ressourcen gleichzeitig aktualisiert wird.

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 Resource Manager eine Abhängigkeit von früheren Instanzen in der Schleife, sodass ein Batch erst dann gestartet wird, wenn der vorherige Batch abgeschlossen wurde.

Der Wert für batchSize darf den Wert für count im 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 normalerweise ein Dataset als untergeordnete Ressource innerhalb einer Datenfabrik.

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

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

Um eine Eltern-Kind-Beziehung mit einer Instanz der Datenfabrik herzustellen, geben Sie einen Namen für den Datensatz an, der den Namen der übergeordneten Ressource enthält. Verwenden Sie das folgende 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