ARM 模板中的参数

项目
07/10/2024

本文介绍如何在 Azure 资源管理器模板（ARM 模板）中定义和使用参数。为参数提供不同的值即可针对不同环境重复使用模板。

资源管理器会在启动部署操作之前解析参数值。只要在模板中使用参数，资源管理器就会将其替换为解析的值。

每个参数都必需设置为数据类型之一。

除了 minValue、maxValue、minLength、maxLength 和 allowedValues 之外，languageVersion 2.0 还引入了一些要在定义、参数和输出定义中使用的聚合类型验证约束。这些约束包括：

additionalProperties
鉴别器
项目
nullable
prefixItems
properties

注意

适用于 Visual Studio Code 的 Azure 资源管理器工具扩展的当前版本无法识别 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"
    ]
  }
}

可以使用具有默认值的表达式。不能在 parameters 节中使用 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
  }
}

对象约束

对象约束仅允许用于对象，并且只能与 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 定义根据鉴别器属性应用什么架构。以下示例将接受 {"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"}
          }
      }
    }
  }
}

数组约束

数组约束仅允许用于数组，并且只能与 languageVersion 2.0 一起使用。

prefixItems

prefixItems 的值是类型定义的数组。值中的每个类型定义都是用于验证同一索引处的数组元素的架构。以下示例将接受 [1, true] 但拒绝 [1, "string"] 或 [1]：

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

items

items 的值是类型定义或布尔值。如果未定义 items 约束，则默认值为 true。

如果 value 是类型定义，则该值描述应用于数组中索引大于 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
}

可为空约束

可为空的约束只能与 languageVersion 2.0 一起使用。它指示该值可能为 null 或被忽略。有关示例，请参阅属性。

说明

可以向参数添加说明，帮助模板用户了解要提供的值。通过门户部署模板时，在说明中提供的文本自动用作该参数的提示。仅当文本提供的信息超过可从参数名称推断出的信息时，才添加说明。

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

使用参数

若要引用参数的值，请使用参数函数。以下示例使用参数值表示密钥保管库名称。

{
  "$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": "chinaeast",
        "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 模板的结构和语法。
若要了解如何以文件形式传入参数值，请参阅创建资源管理器参数文件。
有关创建参数的建议，请参阅最佳做法 - 参数。

通过