使用 copy 元素建立多個資源執行個體

8 分鐘

您目前已在範本的資源清單中宣告了資源。進行部署時，您最後會取得資源清單中指定之每個項目的一個執行個體。建議您為特定資源建立一個以上的執行個體。例如，您可能想要在一個虛擬網路中有多個子網路。

當您想要建立許多執行個體並逐一查看建構建構時，請考慮下列問題與要點：

我是否需要一個以上的複本：對於較簡單的案例來說，可能不需要。對於更進階的案例 (例如子網路或虛擬機器)，您可能需要考慮是否需要某個項目的多個複本。
我是否相依於資源：一般來說，Azure Resource Manager 很適合用來找出需要以何種順序建構的項目，以便制訂出 Azure Resource Manager 範本內的參考。不過在某些狀況下，您可能需要指定順序。
定義命名配置：您想要為資源提供有意義的名稱。基於該理由，您會依賴部署期間所傳遞的參數。當您具有多個複本時，建議您使用更細微的控制，並根據目前複製順序中的反覆項目來命名。
設定及控制資源建立：建議您限制在實際執行環境中建立的資源數目。若要這麼做，您可以將資源建立設定為「循序」或「平行」。
複製其他類型：資源不是您可以建立多個複本並逐一查看的唯一項目。實際上，您可以使用屬性、變數和輸出來執行相同動作。
父子式：您可能需要在資源中設定父子式關聯性。

建立多個執行個體

您可以使用迴圈建構來減少按鍵次數。如果您重複地需要使用某個項目、在名稱與類型方面相當類似，而且其中只有些許差異的話，那麼 copy 元素對您來說就可能很有用。

「copy 元素」是 JSON 的一部分，可用於許多類型的建構，例如，資源、屬性、變數與輸出。 copy 元素的語法由機碼 copy 組成，並含有一個陣列作為值。例如： "copy": [] 。

陣列採用一些元素，而每個元素都是由一組屬性所組成的物件 {}。這些屬性的內容取決於其所使用的建構類型。一般來說，所有 copy 元素建構都有一個通用屬性：count。此屬性會決定您希望特定類型的建構有多少個執行個體。大部分的建構也允許 name 屬性，為您提供可在程式碼的其他組件中進行參考的參考。其他使用的屬性則是建構特定的。

要選擇的內容

您可能會問：「如果我可以在許多類型的建構上使用 copy 元素，那麼我應該選擇哪一種及何時選擇，而我可以在範本中使用一個以上的類型嗎？」

這一切都取決於您的使用案例。「資源反覆項目」可讓您建立許多資源複本，在您需要多個儲存體帳戶時使用，這是很合理的做法。另一方面，「屬性反覆項目」可讓您在一個資源內建立許多屬性。這與儲存您的按鍵輸入和時間有關，而且您最清楚知道範本中有重複組件的位置。

您可以在範本中的許多位置使用 copy 元素。您可以使用 copy 元素來建立許多資源，但也可以在相同範本內建立許多類似的變數。

運作方式

copy 元素會根據您要評估和取代的 copy 陳述式來運作。取代是您根據 copy 欄位中指示的次數來重複 copy 陳述式中所定義內容的結果。

下列範例顯示使用 copy 的定義看起來可能會像這樣：

"copy": [
  {
    "name": "dataDisks",
    "count": 2,
    "input": {
      "diskSizeGB": 1023,
      "lun": "[copyIndex('dataDisks')]",
      "createOption": "Empty"
    }
  }
]

請注意 count: 2 項目。值 2 表示您希望上述運算式「展開」為兩個項目。結果如下：

"dataDisks": [
{
  "lun": 0,
  "createOption": "Empty",
  "diskSizeGB": 1023
},
{
  "lun": 1,
  "createOption": "Empty",
  "diskSizeGB": 1023
}

您可以看到 name 屬性的值已變成屬性名稱，而 input 屬性的內容已變成重複的 JSON 部分。

注意

複製運算式及其輸出會因為使用的運算式類型而有所不同。前述範例確實能夠很好地說明將運算式轉換成一連串重複陳述式時所發生的狀況。

可複製的數量會有限制。目前的限制為 800 個項目。

重要

如需確切限制的詳細資訊，請參閱 ARM 範本中的資源反覆項目。

控制反覆項目

有協助程式函式可協助您參考陣列中的特定索引。 copyIndex() 函式會傳回目前的索引。例如，針對第三個重複的項目，copyIndex() 會傳回值 2。 copyIndex() 的語法看起來就像這樣：

copyIndex(loopName, offset)

copyIndex() 函式有兩個不同的輸入參數，loopName 與 offset。 offset 參數一律是選擇性的，而且可用來將您從目前的索引位移。您新增來作為 offset 值的項目，都會新增到目前的索引中。如果目前的索引傳回 2，而且您指定 1 作為位移，copyIndex() 函式就會傳回 3。

loopName 參數是選擇性或必要的，視使用的位置而定。如果在 properties 建構內部使用，就是必要的，如果在 resources 陣列中使用，就是選擇性的。以下是該參數為必要項目時的範例：

"properties": {
    "storageProfile": {
      "copy": [
        {
          "name": "dataDisks",
          "count": "[parameters('numberOfDataDisks')]",
          "input": {
            "diskSizeGB": 1023,
            "lun": "[copyIndex('dataDisks')]",
            "createOption": "Empty"
          }
        }
      ]
    }
}

請注意 copy 元素如何在 properties 建構內部使用，以及 copyIndex() 具有指定為 copyIndex('dataDisks') 的 loopName。

以下提供一個 loopName 不是必要項目的範例：

{
  "type": "Microsoft.Network/virtualNetworks",
  "apiVersion": "2018-04-01",
  "name": "[concat(parameters('vnetname'), copyIndex())]",
}

其顯示已宣告的資源，而且 copyIndex() 是在未提供參數的情況下呼叫的，因為它會在資源的內容中使用。

設定部署

當您針對資源使用 copy 元素時，最終會建立許多外觀類似的資源。

有時，建議您控制資源的建立方式和順序。以下為控制順序的可能原因：

環境限制。視您部署的環境而定，建議您限制此環境受到部署影響的程度。在實際執行環境中，限制同一時間有多少資源會受到影響，是很合理的做法。您可以設定「部署模式」，以控制同時部署的資源數目。
相依性。在您嘗試建立所需資源之前，您可能會依賴已經存在的內容。為了表達這類相依性，有一個稱為 dependsOn 的建構。

部署模式和 `copy`

建議您確保 copy 建構所建立的一組資源已在其他項目之前建立。如果是這種情況，則您需要表達此狀況。請記住，這裡要執行的是 Resource Manager 使用的部署模式。支援的模式有兩種：

循序。將資源設定為此部署模式，表示其將會在另一個資源之後建立。在此模式中，您也應該預期要設定 batchSize 屬性，以判斷使用此模式部署的資源數目。在先前批次完成之前，無法啟動新的批次。建議您透過此方式限制在實際執行環境中使用的項目，例如，限制任一時點會受到影響的資源數目可能很重要。
平行。此模式為預設的部署模式。優點是高輸送量，因此範本的處理速度會比較快。缺點是您無法保證順序，而這可能不是您想要用於實際執行環境的結果。

相依性

在 copy 元素的內容中，您必須告訴具有相依性的資源，其正在等候的是哪一個區段。您透過由使用下列 JSON 依名稱進行參考，來完成此相依性：

"resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2019-04-01",
      "name": "[concat(copyIndex(),'storage', uniqueString(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "copy": {
        "name": "storagecopy",
        "count": 3
      },
      "properties": {}
    },
    {
      "type": "Microsoft.Compute/virtualMachines",
      "apiVersion": "2015-06-15",
      "name": "[concat('VM', uniqueString(resourceGroup().id))]",
      "dependsOn": ["storagecopy"],
    }
  ]

請注意，copy 元素具有 name 屬性，其值為 storagecopy。相依資源 (儲存體帳戶) 正在等候 copy 元素作業完成。這會以 "dependsOn": ["storagecopy"] 表示。

因此，ARM 範本會在這兩個資源之間切換到循序部署模式。其可能會影響部署的輸送量速度，但您已表達您在意現在具有高優先順序的特定部署順序。