ARM 範本中的語法和運算式

文章
09/26/2024

Azure Resource Manager 範本 (ARM 範本) 的基本語法是 JavaScript 物件標記法 (JSON)。不過可以使用運算式來擴充範本內可用的 JSON 值。運算式開頭和結尾括號分別是 [ 和 ]。部署範本時，會評估運算式的值。運算式可以傳回字串、整數、布林值、陣列或物件。

範本運算式不能超過 24,576 個字元。

使用函式

Azure Resource Manager 提供可在範本中使用的函數。下列範例顯示在參數的預設值中使用函數的運算式：

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

在運算式中，語法 resourceGroup() 會呼叫 Resource Manager 提供在範本內使用的其中一個函數。在此範例中為 resourceGroup 函數。和在 JavaScript 中相同，函式呼叫的格式為 functionName(arg1,arg2,arg3)。語法 .location 會從該函數所傳回的物件中擷取一個屬性。

範本函數和其參數不區分大小寫。例如，Resource Manager 會將 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 函數會傳回空的物件。在這兩種情況下，Resource Manager 範本都會將其視為屬性不存在。

"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 值

下一步

意見反映

更多資源