ARM 模板中的语法和表达式

项目
10/04/2023

Azure 资源管理器模板（ARM 模板）的基本语法是 JavaScript 对象表示法 (JSON)。但是，可以使用表达式来扩展模板中可用的 JSON 值。表达式分别以方括号 [ 与 ] 开头和结尾。部署模板时会计算表达式的值。表达式可以返回字符串、整数、布尔值、数组或对象。

模板表达式不能超过 24,576 个字符。

使用函数

Azure 资源管理器提供了可在模板中使用的函数。以下示例显示了一个在参数的默认值中使用函数的表达式：

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

在该表达式中，语法 resourceGroup() 调用资源管理器提供的、在模板中使用的某个函数。在本例中，它是 resourceGroup 函数。如同在 JavaScript 中一样，函数调用的格式为 functionName(arg1,arg2,arg3)。语法 .location 从该函数返回的对象中检索一个属性。

模板函数及其参数不区分大小写。例如，资源管理器将 variables('var1') 和 VARIABLES('VAR1') 解析为相同内容。在求值时，除非函数明确修改大小写（例如 toUpper 或 toLower），否则函数保留大小写。某些资源类型可能有独立于函数求值方式的大小写要求。

若要将字符串值作为参数传递给函数，请使用单引号。

"name": "[concat('storage', uniqueString(resourceGroup().id))]"

无论是部署到资源组、订阅、管理组还是租户，大多数函数的工作原理都相同。以下函数根据范围有限制：

resourceGroup - 只能在部署到资源组时使用。
resourceId - 可以在任何范围内使用，但有效参数会根据范围而发生变化。
subscription - 只能在部署到资源组或订阅时使用。

转义字符

要使文本字符串以左方括号 [ 开头，以右方括号 ] 结尾，但不将其解释为表达式，请添加额外的方括号使字符串以 [[ 开头。例如，变量：

"demoVar1": "[[test value]"

解析为 [test value]。

但是，如果文本字符串没有以方括号结束，则不要转义第一个方括号。例如，变量：

"demoVar2": "[test] value"

解析为 [test] value。

若要转义表达式中的双引号（例如，在模板中添加 JSON 对象），请使用反斜杠。

"tags": {
    "CostCenter": "{\"Dept\":\"Finance\",\"Environment\":\"Production\"}"
},

若要转义 ARM 表达式输出中的单引号，请将单引号重复一次。以下模板的输出会生成 JSON 值 {"abc":"'quoted'"}。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "resources": [],
  "outputs": {
    "foo": {
      "type": "object",
      "value": "[createObject('abc', '''quoted''')]"
    }
  }
}

在资源定义中，对表达式中的值进行双重转义。以下模板中的 scriptOutput 为 de'f。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "forceUpdateTag": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    "deploymentScriptSharedProperties": {
      "forceUpdateTag": "[parameters('forceUpdateTag')]",
      "azPowerShellVersion": "10.1",
      "retentionInterval": "P1D"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "escapingTest",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": "[union(variables('deploymentScriptSharedProperties'), createObject('scriptContent', '$DeploymentScriptOutputs = @{}; $DeploymentScriptOutputs.escaped = \"de''''f\";'))]"
    }
  ],
  "outputs": {
    "scriptOutput": {
      "type": "string",
      "value": "[reference('escapingTest').outputs.escaped]"
    }
  }
}

使用 languageVersion 2.0 时，不再需要双重转义。可以将前面的示例编写为以下 JSON 以获取相同的结果 de'f。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "forceUpdateTag": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    "deploymentScriptSharedProperties": {
      "forceUpdateTag": "[parameters('forceUpdateTag')]",
      "azPowerShellVersion": "10.1",
      "retentionInterval": "P1D"
    }
  },
  "resources": {
    "escapingTest": {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "escapingTest",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": "[union(variables('deploymentScriptSharedProperties'), createObject('scriptContent', '$DeploymentScriptOutputs = @{}; $DeploymentScriptOutputs.escaped = \"de''f\";'))]"
    }
  },
  "outputs": {
    "scriptOutput": {
      "type": "string",
      "value": "[reference('escapingTest').outputs.escaped]"
    }
  }
}

传入参数值时，转义字符的使用取决于在何处指定了参数值。如果在模板中设置默认值，则需要额外的左括号。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "demoParam1": {
      "type": "string",
      "defaultValue": "[[test value]"
    }
  },
  "resources": [],
  "outputs": {
    "exampleOutput": {
      "type": "string",
      "value": "[parameters('demoParam1')]"
    }
  }
}

如果使用默认值，则模板会返回 [test value]。

但是，如果通过命令行传入参数值，则将按原义解释这些字符。使用以下命令部署上一个模板：

New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[[test value]"

返回 [[test value]。请改用：

New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[test value]"

从参数文件传入值时，将应用相同的格式设置。将按原义解释字符。与上述模板一起使用时，以下参数文件将返回 [test value]：

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "demoParam1": {
      "value": "[test value]"
    }
  }
}

Null 值

若要将属性设置为 null，可使用 null 或 [json('null')]。将 null 作为参数提供时，json 函数返回空对象。在这两种情况下，资源管理器模板都会按照属性不存在的情况对其进行处理。

"stringValue": null,
"objectValue": "[json('null')]"

若要完全删除某个元素，可以使用 filter() 函数。例如：

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "deployCaboodle": {
      "type": "bool",
      "defaultValue": false
    }
  },
  "variables": {
    "op": [
      {
        "name": "ODB"
      },
      {
        "name": "ODBRPT"
      },
      {
        "name": "Caboodle"
      }
    ]
  },
  "resources": [],
  "outputs": {
    "backendAddressPools": {
      "type": "array",
      "value": "[if(parameters('deployCaboodle'), variables('op'), filter(variables('op'), lambda('on', not(equals(lambdaVariables('on').name, 'Caboodle')))))]"
    }
  }
}

后续步骤

有关模板函数的完整列表，请参阅 ARM 模板函数。
若要详细了解模板文件，请参阅了解 ARM 模板的结构和语法。

通过

ARM 模板中的语法和表达式

使用函数

转义字符

Null 值

后续步骤

其他资源