模板结构和语法 - Azure Resource Manager

相关文章推荐

安静的手套 · 选择适合你的 Azure 区域 | ...· 2 周前 ·

健身的显示器 · Azure Active ...· 2 天前 ·

帅气的企鹅 · 山东省商务厅通知公告 ...· 4 月前 ·

沉稳的火车 · 电视剧《温州一家人》观后感 - 知乎· 1 年前 ·

沉着的脸盆 · 百度一下· 1 年前 ·

逆袭的电梯 · 零点零一公分的距离_头条· 1 年前 ·

低调的枇杷 · 【一口气看完】超火漫画《惊世狂妃》2小时30 ...· 1 年前 ·

本文介绍 Azure 资源管理器模板（ARM 模板）的结构。演示了模板的不同部分，以及可在相应部分使用的属性。

本文面向对 ARM 模板有一定了解的用户，其中提供了有关模板结构的详细信息。有关引导你完成模板创建过程的分步教程，请参阅教程：创建和部署第一个 ARM 模板。要通过一组引导式 Learn 模块了解 ARM 模板，请参阅使用 ARM 模板在 Azure 中部署和管理资源。

Bicep 是一种新语言，它的功能与 ARM 模板相同，但语法更易于使用。如果正在考虑基础结构即代码选项，建议查看 Bicep。

若要了解 Bicep 文件的元素，请参阅了解 Bicep 文件的结构和语法。

使用最简单的结构时，模板有以下元素：

"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "languageVersion": "", "contentVersion": "", "apiProfile": "", "definitions": { }, "parameters": { }, "variables": { }, "functions": [ ], "resources": [ ], /* or "resources": { } with languageVersion 2.0 */ "outputs": { } $schema 用于说明模板语言版本的 JavaScript 对象表示法 (JSON) 架构文件所在的位置。所用版本号取决于部署范围和 JSON 编辑器。

如果使用的是带有 Azure 资源管理器工具扩展的 Visual Studio Code ，请使用最新版本进行资源组部署：


   https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

其他编辑器（包括 Visual Studio）可能无法处理此架构。对于这些编辑器，请使用：


   https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

对于订阅部署，请使用：


   https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#

对于管理组部署，请使用：


   https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#

对于租户部署，请使用：


   https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#

languageVersion 模板的语言版本。若要查看 languageVersion 2.0 的增强功能，请参阅 languageVersion 2.0 。 contentVersion 模板的版本（例如 1.0.0.0）。可为此元素提供任意值。使用此值记录模板中的重要更改。使用模板部署资源时，此值可用于确保使用正确的模板。 apiProfile 用作资源类型 API 版本集合的 API 版本。使用此值可以避免为模板中的每个资源指定 API 版本。如果你指定 API 配置文件版本但不指定资源类型的 API 版本，则资源管理器将使用配置文件中为该资源类型定义的 API 版本。

将模板部署到不同的环境（例如 Azure Stack 和全球 Azure）时，API 配置文件属性非常有用。使用 API 配置文件版本可确保模板自动使用两个环境均支持的版本。有关最新 API 配置文件版本以及配置文件中定义的资源 API 版本的列表，请参阅 API 配置文件。

有关详细信息，请参阅使用 API 配置文件跟踪版本。用于验证数组和对象值的架构。仅在 languageVersion 2.0 中支持定义。 parameters 执行部署以自定义资源部署时提供的值。 variables 在模板中用作 JSON 片段以简化模板语言表达式的值。 functions 可在模板中使用的用户定义函数。 resources 已在资源组或订阅中部署/更新的资源类型。 outputs 部署后返回的值。

每个元素均有可设置的属性。本文稍后将更详细地介绍模板的各个节。

在模板的 definitions 部分，指定用于验证数组和对象值的架构。 Definitions 只能与 languageVersion 2.0 一起使用。

"definitions": {
  "<definition-name": {
    "type": "<data-type-of-definition>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the-type-definition>"
类型定义的类型。 允许的类型和值为 string、securestring、int、bool、object、secureObject 和 array。 请参阅 ARM 模板中的数据类型。
allowedValues
用来确保提供正确值的类型定义允许值数组。
minValue
类型定义的最小值，此值是包容性的。
maxValue
类型定义的最大值，此值是包容性的。
minLength
string、secure string 和 array 类型定义的最小长度，此值是包容性的。
maxLength
string、secure string 和 array 类型定义的最大长度，此值是包容性的。
prefixItems
用于验证数组中同一索引处的元素的架构。
items
应用于索引大于 prefixItems 约束最大索引的数组中所有元素的架构，或用于控制索引大于 prefixItems 约束最大索引的数组元素的布尔值。
properties
用于验证对象的架构。
additionalProperties
应用于 properties 约束中未提及的所有属性的架构，或用于接受 properties 约束中未定义的任何属性的布尔值。
discriminator
基于鉴别器属性应用的模式。
可以为 null
一个布尔值，指示该值可以为 null 或被省略。
description
通过门户向用户显示的类型定义的描述。 有关详细信息，请参阅模板中的注释。
有关如何使用类型定义的示例，请参阅 ARM 模板中的类型定义。
在 Bicep 中，请参阅用户定义的数据类型。
parameters
在模板的 parameters 节中，可以指定在部署资源时能够输入的值。 一个模板中最多可以有 256 个参数。 可以通过使用包含多个属性的对象来减少参数的数目。
参数的可用属性为：
"parameters": {
  "<parameter-name>" : {
    "type" : "<type-of-parameter-value>",
    "defaultValue": "<default-value-of-parameter>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the parameter>"
参数值的类型。 允许的类型和值为 string、securestring、int、bool、object、secureObject 和 array。 请参阅 ARM 模板中的数据类型。
defaultValue
参数的默认值，如果没有为参数提供任何值。
allowedValues
用来确保提供正确值的参数的允许值数组。
minValue
int 类型参数的最小值，此值是包容性的。
maxValue
int 类型参数的最大值，此值是包容性的。
minLength
string、secure string 和 array 类型参数的最小长度，此值是包容性的。
maxLength
string、secure string 和 array 类型参数的最大长度，此值是包容性的。
prefixItems
用于验证数组中同一索引处的元素的类型定义。 prefixItems 仅在 languageVersion 2.0 中受支持。
items
应用于索引大于 prefixItems 约束最大索引的数组中所有元素的架构，或用于控制索引大于 prefixItems 约束最大索引的数组元素的布尔值。 items 仅在 languageVersion 2.0 中受支持。
properties
用于验证对象的架构。 properties 仅在 languageVersion 2.0 中受支持。
additionalProperties
应用于 properties 约束中未提及的所有属性的架构，或用于接受 properties 约束中未定义的任何属性的布尔值。 additionalProperties 仅在 languageVersion 2.0 中受支持。
discriminator
基于鉴别器属性应用的模式。 discriminator 仅在 languageVersion 2.0 中受支持。
可以为 null
一个布尔值，指示该值可以为 null 或被省略。 nullable 仅在 languageVersion 2.0 中受支持。
description
通过门户向用户显示的参数的说明。 有关详细信息，请参阅模板中的注释。
有关如何使用参数的示例，请参阅 ARM 模板中的参数。
在 Bicep 中，请参阅参数。
在 variables 节中，可以构造能够在整个模板中使用的值。 不需要定义变量，但使用变量可以减少复杂的表达式，从而简化模板。 每个变量的格式都与其中一种数据类型匹配。 一个模板中最多可以有 256 个变量。
以下示例演示了可用于定义变量的选项：
"variables": {
  "<variable-name>": "<variable-value>",
  "<variable-name>": {
    <variable-complex-type-value>
  "<variable-object-name>": {
    "copy": [
        "name": "<name-of-array-property>",
        "count": <number-of-iterations>,
        "input": <object-or-value-to-repeat>
  "copy": [
      "name": "<variable-array-name>",
      "count": <number-of-iterations>,
      "input": <object-or-value-to-repeat>
有关使用 copy 为变量创建多个值的信息，请参阅变量迭代。
有关如何使用变量的示例，请参阅 ARM 模板中的变量。
在 Bicep 中，请参阅变量。
在模板中，可以创建自己的函数。 这些函数可在模板中使用。 通常，定义不想要在整个模板中重复执行的复杂表达式。 从模板中支持的表达式和函数创建用户定义函数。
定义用户函数时，存在一些限制：
该函数不能访问变量。
函数仅可使用函数中定义的参数。 如果在用户定义的函数中使用参数函数，则只能使用该函数的参数。
该函数不能调用其他用户定义的函数。
该函数不能使用引用函数。
该函数的参数不能具有默认值。
"functions": [
    "namespace": "<namespace-for-functions>",
    "members": {
      "<function-name>": {
        "parameters": [
            "name": "<parameter-name>",
            "type": "<type-of-parameter-value>"
        "output": {
          "type": "<type-of-output-value>",
          "value": "<function-return-value>"
function-name
自定义函数的名称。 调用函数时，将函数名称与命名空间组合在一起。 例如，若要在命名空间 contoso 中调用名为 uniqueName 的函数，请使用 "[contoso.uniqueName()]"。
parameter-name
要在自定义函数中使用的参数的名称。
parameter-value
参数值的类型。 允许的类型和值为 string、securestring、int、bool、object、secureObject 和 array。
output-type
输出值的类型。 输出值支持的类型与函数输入参数相同。
output-value
由函数计算并返回的模板语言表达式。
有关如何使用自定义函数的示例，请参阅 ARM 模板中的用户定义函数。
在 Bicep 中不支持用户定义的函数。 Bicep 支持各种函数和运算符。
在 resources 节中，可以定义所部署或更新的资源。 一个模板中最多可以有 800 个资源。
使用以下结构定义资源：
"resources": [
    "condition": "<true-to-deploy-this-resource>",
    "type": "<resource-provider-namespace/resource-type-name>",
    "apiVersion": "<api-version-of-resource>",
    "name": "<name-of-the-resource>",
    "comments": "<your-reference-notes>",
    "location": "<location-of-resource>",
    "dependsOn": [
        "<array-of-related-resource-names>"
    "tags": {
        "<tag-name1>": "<tag-value1>",
        "<tag-name2>": "<tag-value2>"
    "identity": {
      "type": "<system-assigned-or-user-assigned-identity>",
      "userAssignedIdentities": {
        "<resource-id-of-identity>": {}
    "sku": {
        "name": "<sku-name>",
        "tier": "<sku-tier>",
        "size": "<sku-size>",
        "family": "<sku-family>",
        "capacity": <sku-capacity>
    "kind": "<type-of-resource>",
    "scope": "<target-scope-for-extension-resources>",
    "copy": {
        "name": "<name-of-copy-loop>",
        "count": <number-of-iterations>,
        "mode": "<serial-or-parallel>",
        "batchSize": <number-to-deploy-serially>
    "plan": {
        "name": "<plan-name>",
        "promotionCode": "<plan-promotion-code>",
        "publisher": "<plan-publisher>",
        "product": "<plan-product>",
        "version": "<plan-version>"
    "properties": {
        "<settings-for-the-resource>",
        "copy": [
                "name": ,
                "count": ,
                "input": {}
    "resources": [
        "<array-of-child-resources>"
资源的类型。 此值是资源提供程序的命名空间和资源类型的组合（例如 Microsoft.Storage/storageAccounts）。 若要确定可用值，请参阅模板参考。 对于子资源，类型的格式取决于该资源是嵌套在父资源中，还是在父资源的外部定义。 请参阅设置子资源的名称和类型。
apiVersion
用于创建资源的 REST API 版本。 创建新模板时，将此值设置为要部署的资源的最新版本。 只要模板可以根据需要工作，就可以继续使用同一 API 版本。 通过继续使用同一 API 版本，可以最大程度地减少新 API 版本更改模板工作方式的风险。 仅当需要使用在更高版本中引入的新功能时，才应考虑更新 API 版本。 若要确定可用值，请参阅模板参考。
资源的名称。 该名称必须遵循 RFC3986 中定义的 URI 构成部分限制。 向外部各方公开资源名称的 Azure 服务会验证名称，以确保它不是试图窃取另一标识。 对于子资源，名称的格式取决于该资源是嵌套在父资源中，还是在父资源的外部定义。 请参阅设置子资源的名称和类型。
comments
用于描述模板中资源的注释。 有关详细信息，请参阅模板中的注释。
location
提供的资源支持的地理位置。 可以选择任何可用位置，但通常选取靠近用户的位置。 通常还会将彼此交互的资源置于同一区域。 大多数资源类型需要一个位置，但某些类型（如角色分配）不需要位置。 请参阅设置资源位置。
dependsOn
部署此资源之前必须部署的资源。 Resource Manager 会评估资源之间的依赖关系，并按正确的顺序部署资源。 如果资源互不依赖，则会并行部署资源。 该值可以是资源名称或资源唯一标识符的逗号分隔列表。 在此模板中仅部署列出的资源。 未在此模板中定义的资源必须是已存在的资源。 避免添加不必要的依赖项，因为这些依赖项可能会降低部署速度并创建循环依赖项。 有关设置依赖项的指南，请参阅在 ARM 模板中定义部署资源的顺序。
与资源关联的标记。 应用可以在订阅中对资源进行逻辑组织的标记。
某些资源支持 Azure 资源托管标识。 这些资源在资源声明的根级别具有标识对象。 可以设置标识是用户分配还是系统分配。 对于用户分配的标识，请提供标识的资源 ID 列表。 将键设置为资源 ID，将值设置为空对象。 有关详细信息，请参阅使用模板在 Azure VM 上配置 Azure 资源的托管标识。
某些资源接受定义了要部署的 SKU 的值。 例如，可以为存储帐户指定冗余类型。
某些资源接受定义了你部署的资源类型的值。 例如，可以指定要创建的 Azure Cosmos DB 实例的类型。
scope
scope 属性仅适用于扩展资源类型。 指定与部署范围不同的范围时，请使用该属性。 请参阅在 ARM 模板中设置扩展资源的范围。
如果需要多个实例，则为要创建的资源数。 默认模式为并行。 若不想同时部署所有资源，请指定为串行模式。 有关详细信息，请参阅在 Azure 资源管理器中创建多个资源实例。
某些资源接受定义了要部署的计划的值。 例如，可以为虚拟机指定市场映像。
properties
特定于资源的配置设置。 properties 的值与创建资源时，在 REST API 操作（PUT 方法）的请求正文中提供的值相同。 还可以指定副本数组，为一个属性创建多个实例。 若要确定可用值，请参阅模板参考。
resources
依赖于所定义的资源的子资源。 只能提供父资源的架构允许的资源类型。 不隐式表示对父资源的依赖。 必须显式定义该依赖关系。 请参阅设置子资源的名称和类型。
若要支持 ARM JSON 模板中的 Bicep 符号名称，请添加版本 2.0 或更高版本的 languageVersion，并将资源定义从数组更改为对象。
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
有关详细信息，请参阅资源。
在 Bicep 中，请参阅资源。
Outputs
在 outputs 节中，可以指定从部署返回的值。 一般情况下，将从已部署的资源返回值。 一个模板中最多可以有 64 个输出。
以下示例演示了输出定义的结构：
"outputs": {
  "<output-name>": {
    "condition": "<boolean-value-whether-to-output-value>",
    "type": "<type-of-output-value>",
    "value": "<output-value-expression>",
    "copy": {
      "count": <number-of-iterations>,
      "input": <values-for-the-variable>
condition
指示此输出值是否返回的布尔值。 如果为 true，则该值包含在部署的输出中。 如果为 false，则此部署将跳过输出值。 如果未指定，则默认值为 true。
输出值的类型。 输出值支持的类型与模板输入参数相同。 如果指定 securestring 作为输出类型，则值不会显示在部署历史记录中，并且无法从另一个模板检索。 若要在多个模板中使用机密值，请在 Key Vault 中存储该机密，并在参数文件中引用该机密。 有关详细信息，请参阅在部署过程中使用 Azure Key Vault 传递安全参数值。
value
要求值并作为输出值返回的模板语言表达式。 请指定 value 或 copy。
用于返回多个值作为输出。 请指定 value 或 copy。 有关详细信息，请参阅 ARM 模板中的输出迭代。
有关如何使用输出的示例，请参阅 ARM 模板中的输出。
在 Bicep 中，请参阅输出。
注释和元数据
可通过几个选项向模板添加注释和元数据。
对于内联注释，可以使用 // 或 /* ... */。 在 Visual Studio Code 中，将带注释的参数文件保存为“带注释的 JSON (JSONC)”文件类型，否则你将收到一条错误消息，提示“JSON 中不允许注释”。
使用 Azure CLI 部署带有注释的模板时，请使用 2.3.0 或更高版本，并指定 --handle-extended-json-format 开关。
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
在 Visual Studio Code 中，Azure 资源管理器工具扩展可以自动检测 ARM 模板并更改语言模式。 如果在 Visual Studio Code 右下角看到 Azure 资源管理器模板，则可使用内联注释。 内联注释不再标记为无效。
在 Bicep 中，请参阅注释。
Metadata
几乎可以在模板中的任意位置添加 metadata 对象。 资源管理器会忽略该对象，但 JSON 编辑器可能会警告你该属性无效。 在对象中，定义所需的属性。
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "comments": "This template was developed for demonstration purposes.",
    "author": "Example Name"
对于 parameters，请添加具有 description 属性的 metadata 对象。
"parameters": {
  "adminUsername": {
    "type": "string",
    "metadata": {
      "description": "User name for the Virtual Machine."
通过门户部署模板时，在说明中提供的文本自动用作该参数的提示。
对于 resources，请添加 comments 元素或 metadata 对象。 以下示例显示了 comments 元素和 metadata 对象。
"resources": [
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2022-09-01",
    "name": "[format('{0}{1}', 'storage', uniqueString(resourceGroup().id))]",
    "comments": "Storage account used to store VM disks",
    "location": "[parameters('location')]",
    "metadata": {
      "comments": "These tags are needed for policy compliance."
    "tags": {
      "Dept": "[parameters('deptName')]",
      "Environment": "[parameters('environment')]"
    "sku": {
      "name": "Standard_LRS"
    "kind": "Storage",
    "properties": {}
对于 outputs，请将 metadata 对象添加到输出值。
"outputs": {
  "hostname": {
    "type": "string",
    "value": "[reference(variables('publicIPAddressName')).dnsSettings.fqdn]",
    "metadata": {
      "comments": "Return the fully qualified domain name"
无法将 metadata 对象添加到用户定义的函数。
多行字符串
可将一个字符串分成多个行。 例如，请参见以下 JSON 示例中的 location 属性和注释之一。
若要部署具有多线串的模板，请使用 Azure PowerShell 或 Azure CLI。 对于 CLI，请使用 2.3.0 或更高版本，并指定 --handle-extended-json-format 开关。
如果通过 Azure 门户、DevOps 管道或 REST API 部署模板，则不支持多线串。
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
    storage account and network interface
    must be deployed first
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
在 Bicep 中，请参阅多行字符串。
languageVersion 2.0
不建议在生产环境中使用任何以 -experimental 结尾的 languageVersion，因为试验性功能可能随时更改。
适用于 Visual Studio Code 的 Azure 资源管理器工具扩展的当前版本无法识别 languageVersion 2.0 中提供的增强功能。
若要使用 languageVersion 2.0，请将 "languageVersion": "2.0" 添加到模板：
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
languageVersion 2.0 附带的增强功能和更改：
在 ARM JSON 模板中使用符号名称。 有关详细信息，请参阅使用符号名称。
在资源复制循环中使用符号名称。 请参阅使用符号名称。
在 dependsOn 数组中使用符号名称。 请参阅 DependsOn 和依赖于循环中的资源。
在 reference 函数中使用符号名称而不是资源名称。  请参阅参考资料。
references() 函数会返回表示资源集合运行时状态的一组对象。 请参阅参考。
使用“existing”资源属性声明现有资源供 ARM 读取而不是部署资源。 请参阅声明现有资源。
创建用户定义的类型。 请参阅类型定义。
要在参数和输出中使用的其他聚合类型验证约束。
expressionEvaluationOptions 属性的默认值为 inner。 值 outer 被阻止。 请参阅嵌套模板中的表达式计算作用域。
deployment 函数返回属性的有限子集。 请参阅部署。
如果在符号名称部署中使用部署资源，请使用 apiVersion 2020-09-01 或更高版本。
在资源定义中，不再需要表达式内的双重转义值。  请参阅转义字符。
若要查看许多不同类型的解决方案的完整模型，请参阅 Azure Quickstart Templates（Azure 快速入门模板）。
有关用户可以使用的来自模板中的函数的详细信息，请参阅 ARM 模板函数。
若要在部署期间合并若干模板，请参阅部署 Azure 资源时使用链接模版和嵌套模版。
有关创建模板的建议，请参阅 ARM 模板的最佳做法。
有关常见问题的解答，请参阅有关 ARM 模板的常见问题解答。