ARM 範本中的參數

發行項
09/26/2024

本文描述如何在 Azure Resource Manager 範本 (ARM 範本) 中定義和使用參數。透過提供不同的參數值，您可以針對不同的環境重複使用範本。

Resource Manager 會在開始部署作業之前解析參數值。無論在範本中的哪一處使用參數，Resource Manager 都會將該參數取代為已解析的值。

每個參數都必須設為其中一種資料類型。

除了 minValue、maxValue、minLength、maxLength 與 allowedValues，languageVersion 2.0 (部分機器翻譯) 還引進一些彙總類型驗證條件約束，以用於 definitions (部分機器翻譯)、parameters (部分機器翻譯) 與 outputs (部分機器翻譯) 定義。這些條件約束包括：

additionalProperties
discriminator
items
nullable
prefixItems
properties

注意

適用於 Visual Studio Code 的 Azure Resource Manager 工具延伸模組目前版本無法辨識 languageVersion 2.0 中所做的增強功能。

提示

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

範本中限制使用 256 個參數。如需詳細資訊，請參閱範本限制。

如需參數最佳做法，請參閱參數。

基本宣告

每個參數至少需要一個名稱和類型。

當您透過 Azure 入口網站部署範本時，會將駝峰式大小寫的參數名稱變成以空格分隔的名稱。例如，下列範例中的 demoString 會顯示為 Demo String。如需詳細資訊，請參閱使用部署按鈕以從 GitHub 存放庫部署範本，以及使用 ARM 範本和 Azure 入口網站部署資源。

"parameters": {
  "demoString": {
    "type": "string"
  },
  "demoInt": {
    "type": "int"
  },
  "demoBool": {
    "type": "bool"
  },
  "demoObject": {
    "type": "object"
  },
  "demoArray": {
    "type": "array"
  }
}

安全參數

您可以將字串或物件參數標記為安全。安全參數的值不會儲存在部署歷程記錄中，而且不會記錄。

"parameters": {
  "demoPassword": {
    "type": "secureString"
  },
  "demoSecretObject": {
    "type": "secureObject"
  }
}

允許的值

您可以定義允許的參數值。您可以用陣列方式提供允許的值。如果傳入的參數值不是其中一個允許的值，則部署會在驗證期間失敗。

"parameters": {
  "demoEnum": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

預設值

您可以指定參數的預設值。當部署期間未提供值時，就會使用預設值。

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso"
  }
}

若要指定參數的預設值及其他屬性，請使用下列語法。

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso",
    "allowedValues": [
      "Contoso",
      "Fabrikam"
    ]
  }
}

您可以使用具有預設值的運算式。您無法使用 reference 函式或參數區段中的任何 list 函式。這些函式會取得資源的執行階段狀態，且在解析參數時，無法在部署之前執行函式。

運算式不能與其他參數屬性一起使用。

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

您可以使用另一個參數以建立預設值。下列範本會從網站名稱建構主機方案名稱。

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]"
  }
}

不過，您無法將變數參考為預設值。

長度限制

您可以為字串和陣列參數指定最小和最大長度。您可以設定一或兩個限制式。若為字串，長度代表字元數。若為陣列，長度代表陣列中的項目數。

下列範例會宣告兩個參數。其中一個參數用來宣告儲存體帳戶的名稱必須具有 3-24 個字元。另一個參數則宣告陣列必須包含 1-5 個項目。

"parameters": {
  "storageAccountName": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNames": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

整數限制式

您可以設定整數參數的最小值和最大值。您可以設定一或兩個限制式。

"parameters": {
  "month": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

物件條件約束

物件條件約束僅允許用於 objects (部分機器翻譯) 上，且只能搭配 languageVersion 2.0 (部分機器翻譯) 使用。

屬性

properties 的值是屬性名稱 =>類型定義 (部分機器翻譯) 的對應。

下列範例會接受 {"foo": "string", "bar": 1}，但會拒絕 {"foo": "string", "bar": -1}、{"foo": "", "bar": 1} 或任何沒有 foo 或 bar 屬性的物件。

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
}

除非屬性的類型定義 (部分機器翻譯) 具有 "nullable": true 條件約束，否則所有屬性都是必要的。若要讓上述範例中的這兩個屬性成為選擇性屬性，其外觀如下：

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

additionalProperties 的值是類型定義 (部分機器翻譯) 或布林值。如果未定義任何 additionalProperties 條件約束，則預設值為 true。

如果值是類型定義，則值會描述套用至 properties 條件約束中未提及之所有屬性的結構描述。下列範例會接受 {"fizz": "buzz", "foo": "bar"}，但拒絕 {"property": 1}。

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

如果值是 false，則可能不會提供 properties 條件約束中所定義以外的屬性。下列範例會接受 {"foo": "string", "bar": 1}，但拒絕 {"foo": "string", "bar": 1, "fizz": "buzz"}。

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

如果值是 true，則 properties 條件約束中未定義的任何屬性都接受任何值。下列範例會接受 {"foo": "string", "bar": 1, "fizz": "buzz"}。

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

discriminator

值 discriminator 定義要根據鑑別子屬性套用的結構描述。下列範例會接受 {"type": "ints", "foo": 1, "bar": 2} 或 {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}，但拒絕 {"type": "ints", "fizz": "buzz"}。

"parameters": {
  "taggedUnionParameter": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

陣列條件約束

陣列條件約束僅允許用於 arrays (部分機器翻譯) 上，且只能搭配 languageVersion 2.0 (部分機器翻譯) 使用。

prefixItems

prefixItems 的值是類型定義 (部分機器翻譯) 的陣列。值中的每個類型定義，都是用來驗證相同索引陣列元素的結構描述。下列範例會接受 [1, true]，但拒絕 [1, "string"] 或 [1]：

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

項目

items 的值是類型定義 (部分機器翻譯) 或布林值。如果未定義任何 items 條件約束，則預設值為 true。

如果值是類型定義，則值會描述套用至陣列 (其索引大於 prefixItems 條件約束的最大索引) 中所有元素的結構描述。下列範例會接受 [1, true, 1] 或 [1, true, 1, 1]，但拒絕 [1, true, "foo"]：

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" },
    "defaultValue": [1, true, "foo"]
  }
}

您可以使用 items 而不使用 prefixItems。下列範例會接受 [1, 2] 或 [1]，但拒絕 ["foo"]：

"parameters": {
  "intArrayParameter": {
    "type": "array",
    "items": {"type": "int"}
  }
}

如果值是 false，則已驗證的陣列長度必須與 prefixItems 條件約束完全相同。下列範例會接受 [1, true]，但拒絕 [1, true, 1] 和 [1, true, false, "foo", "bar"]。

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ],
    "items": false
  }
}

如果值為 true，則陣列 (其索引大於 prefixItems 條件約束的最大索引) 的元素接受任何值。下列範例會接受 [1, true]、[1, true, 1] 和 [1, true, false, "foo", "bar"]。

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

可為 Null 的條件約束

可為 Null 的條件約束只能搭配 languageVersion 2.0 (部分機器翻譯) 使用。其表示值可能為 null 或被省略。如需範例，請參閱屬性。

描述

您可以將描述新增至參數，以協助範本的使用者瞭解要提供的值。透過入口網站部署範本時，您在描述中提供的文字會自動做為該參數的提示。只有當文字提供的資訊比從參數名稱推斷出的資訊更多時，才會新增描述。

"parameters": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

使用參數

若要參考參數的值，請使用 parameters 函式。下列範例會針對金鑰保存庫名稱使用參數值。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vaultName": {
      "type": "string",
      "defaultValue": "[format('keyVault{0}', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-06-01-preview",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

作為參數的物件

您可以將相關的值作為物件，來進行傳遞並加以組織。此方法也會減少範本中的參數數目。

下列範例顯示本身為物件的參數。預設值會顯示物件的預期屬性。定義要部署的資源時，會使用那些屬性。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vNetSettings": {
      "type": "object",
      "defaultValue": {
        "name": "VNet1",
        "location": "eastus",
        "addressPrefixes": [
          {
            "name": "firstPrefix",
            "addressPrefix": "10.0.0.0/22"
          }
        ],
        "subnets": [
          {
            "name": "firstSubnet",
            "addressPrefix": "10.0.0.0/24"
          },
          {
            "name": "secondSubnet",
            "addressPrefix": "10.0.1.0/24"
          }
        ]
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2021-02-01",
      "name": "[parameters('vNetSettings').name]",
      "location": "[parameters('vNetSettings').location]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vNetSettings').addressPrefixes[0].addressPrefix]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('vNetSettings').subnets[0].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[0].addressPrefix]"
            }
          },
          {
            "name": "[parameters('vNetSettings').subnets[1].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[1].addressPrefix]"
            }
          }
        ]
      }
    }
  ]
}

範本的範例

下列範例會示範使用參數的案例。

範本	描述
具有預設值之帶有函式的參數	示範定義參數的預設值時，如何使用範本函式。範本不會部署任何資源。它會建構參數值，並傳回這些值。
參數物件	示範如何針對參數使用物件。範本不會部署任何資源。它會建構參數值，並傳回這些值。

下一步

若要瞭解參數的可用屬性，請參閱瞭解 ARM 範本的結構和語法。
若要瞭解如何以檔案形式傳遞參數值，請參閱建立 Resource Manager 參數檔案。
如需有關建立參數的建議，請參閱最佳做法 - 參數。

共用方式為