ARM 範本中的資源反覆運算

發行項
09/26/2024

此文章示範如何在 Azure Resource Manager 範本 (ARM 範本) 中建立資源的多個執行個體。透過將複製迴圈新增至範本的 resources 區段，您可以動態設定要部署的資源數目。您也可以避免重複範本語法。

您也可以搭配屬性、變數和輸出使用複製迴圈。

若需要指定是否要部署資源，請參閱條件元素。

提示

我們建議使用 Bicep，因為其提供的功能與 ARM 範本相同，而且語法更易於使用。若要深入了解，請參閱迴圈。

語法

將 copy 元素新增至範本的 resources 區段，以部署資源的多個執行個體。 copy 元素的一般格式如下：

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

name 屬性是可識別迴圈的任何值。 count 屬性可指定您希望資源類型反覆運算的次數。

使用 mode 和 batchSize 屬性來指定資源會以平行方式部署還是循序部署。這些屬性會在循序或平行中加以描述。

複製限制

次數不能超過 800。

次數不可為負數。如果您使用最新版的 Azure CLI、PowerShell 或 REST API 來部署範本，則其可為零。具體而言，您必須使用：

Azure PowerShell 2.6 或更新版本
Azure CLI 2.0.74 或更新版本
Rest API 2019-05-10 版或更新版本
針對部署資源類型，連結的部署必須使用 API 2019-05-10 版或更新版本

舊版 PowerShell、CLI 和 REST API 不支援次數為零。

搭配複製迴圈使用完整模式部署時請小心。如果您以完整模式重新部署至資源群組，則會刪除解析複製迴圈之後未在範本中指定的任何資源。

資源反覆項目

下列範例會建立 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": {}
    }
  ]
}

請注意，每個資源的名稱均包含 copyIndex() 函式，並會傳回目前的反覆項目迴圈。 copyIndex() 以零為起始。因此，下列範例：

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

會建立這些名稱︰

storage0
storage1
storage2

若要位移索引值，您可以傳遞 copyIndex() 函式中的值。反覆運算次數仍然會在 copy 元素中指定，但 copyIndex 的值會依指定的值位移。因此，下列範例：

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

會建立這些名稱︰

storage1
storage2
storage3

使用陣列時，複製作業會有幫助，因為您可以逐一查看陣列中的每個項目。使用陣列上的 length 函式指定反覆運算的計數，並使用 copyIndex 來擷取陣列中目前的索引。

下列範例會為參數中提供的每個名稱建立一個儲存體帳戶。

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

如果您想要從已部署的資源傳回值，您可以使用 outputs 區段中的 copy。

使用符號名稱

符號名稱會指派給資源複製迴圈。迴圈索引是以零為起始。在下列範例中，myStorages[1] 參考了資源迴圈中的第二個資源。

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

如果索引是執行階段值，請自行格式化參考資源。例如：

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

符號名稱可用於 dependsOn 陣列。如果符號名稱是複製迴圈，迴圈中所有資源都會做為相依項目新增。如需詳細資訊，請參閱相依於迴圈中的資源。

循序或平行

根據預設，Resource Manager 會以平行方式建立資源。除了範本中資源的總數限制為 800 個，其對於以平行方式部署的資源數目並無限制。不保證資源會循序建立。

不過，建議您指定將資源部署在序列中。例如，在更新生產環境時，您可以錯開更新，因此任何一次就只會更新特定數目。

若要以序列方式部署資源的多個執行個體，請將 mode 設定為 serial 並將 batchSize 設為一次要部署的執行個體數目。透過序列模式，Resource Manager 會在迴圈中較早的執行個體上建立相依性，因此在前一批次完成之前，它不會啟動一個批次。

batchSize 的值不能超過 copy 元素中 count 的值。

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

mode 屬性也接受 parallel，此為預設值。

子系資源反覆項目

您無法為子資源使用複製迴圈。若要為通常會在另一個資源內定義為巢狀的資源建立多個執行個體，您必須改為將該資源建立為最上層資源。您可以透過類型和名稱屬性，定義和父資源之間的關聯性。

例如，假設您通常將資料集定義為 Data Factory 中的子資源。

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

若要建立多個資料集，請將它移出資料處理站。資料集必須位於與資料處理站相同的等級，但它仍是資料處理站的子資源。您可以透過類型和名稱屬性保留資料集與資料處理站之間的關聯性。由於無法再從類型位於範本中的位置來推斷類型，您必須以此格式提供完整的類型︰{resource-provider-namespace}/{parent-resource-type}/{child-resource-type}。

若要建立與 Data Factory 執行個體的父/子關聯性，請提供包含父資源名稱之資料集的名稱。使用格式︰{parent-resource-name}/{child-resource-name}。

下列範例顯示實作。

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

範本的範例

下列範例顯示為資源或屬性建立多個執行個體的常見案例。

範本	描述
複製儲存體	利用名稱中的索引編號來部署多個儲存體帳戶。
序列複製儲存體	一次一個部署數個儲存體帳戶。名稱包含索引編號。
以陣列複製儲存體	部署數個儲存體帳戶。名稱包含陣列中的值。
複製資源群組 (英文)	部署多個資源群組。

下一步

若要設定在複製迴圈中建立之資源的相依性，請參閱定義在 ARM 範本中部署資源的順序。
若要進行教學課程，請參閱教學課程：使用 ARM 範本建立多個資源執行個體。
如需涵蓋資源複本的 Learn 模組，請參閱使用進階 ARM 範本功能，管理複雜的雲端部署。
如需瞭解複製迴圈的其他用途，請參閱：
如需搭配使用 copy 與巢狀範本的相關資訊，請參閱使用 copy。

共用方式為