ARM テンプレートの構文と式

[アーティクル]
09/04/2023

Azure Resource Manager テンプレート (ARM テンプレート) の基本構文は JavaScript Object Notation (JSON) です。ただし、式を使用して、テンプレート内で使用できる JSON の値を拡張できます。式の始まりと終わりは、それぞれ角かっこ [ と ] です。式の値は、テンプレートのデプロイ時に評価されます。式では、文字列、整数、ブール値、配列、またはオブジェクトを返すことができます。

テンプレート式は、24,576 文字を超えることはできません。

関数を使用する

Azure Resource Manager には、テンプレートで使用できる関数が提供されています。次の例では、パラメーターの既定値で関数を使用する式を示します。

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

式の構文 resourceGroup() では、Resource Manager によってテンプレート内で使用するために提供されている関数の 1 つを呼び出します。このケースでは、resourceGroup 関数です。 JavaScript の場合と同様に、関数呼び出しは functionName(arg1,arg2,arg3) という形式になります。構文 .location では、その関数によって返されたオブジェクトから 1 つのプロパティを取得します。

テンプレート関数とそのパラメーターでは大文字と小文字が区別されません。たとえば、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 式の出力で単一引用符をエスケープするには、単一引用符を 2 重に囲みます。次のテンプレートの出力は、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 値

次のステップ

その他のリソース