ARM テンプレートのパラメーター
この記事では、Azure Resource Manager テンプレート (ARM テンプレート) でパラメーターを定義および使用する方法について説明します。 パラメーターに異なる値を指定することにより、さまざまな環境でテンプレートを再利用できます。
Resource Manager は、デプロイ操作を開始する前にパラメーター値を解決します。 テンプレートでパラメーターが使用されている場合、Resource Manager はそれを解決済みの値に置き換えます。
各パラメーターは、いずれかのデータ型に設定する必要があります。
languageVersion 2.0 では、minValue、maxValue、minLength、maxLength、allowedValues に加え、definitions、parameters、outputs の定義で使用される集約型検証制約がいくつか導入されています。 これらの制約を次に示します。
Note
Visual Studio Code 用 Azure Resource Manager Tools 拡張機能の現在のリリースでは、languageVersion 2.0 で行われた拡張機能は認識されません。
テンプレートではパラメーターが 256 個に制限されます。 詳細については、「テンプレートの制限」を参照してください。
パラメーターのベスト プラクティスについては、「パラメーター」を参照してください。
最小限の宣言
少なくとも、すべてのパラメーターには名前と型が必要です。
テンプレートを Azure portal 経由でデプロイすると、キャメル ケースのパラメーター名はスペース区切りの名前に変換されます。 たとえば、次の例の demoString は Demo String と表示されます。 詳細については、「デプロイ ボタンを使用して GitHub リポジトリからテンプレートをデプロイする」と「ARM テンプレートと Azure portal でリソースをデプロイする」をご覧ください。
"parameters": {
"demoString": {
"type": "string"
},
"demoInt": {
"type": "int"
},
"demoBool": {
"type": "bool"
},
"demoObject": {
"type": "object"
},
"demoArray": {
"type": "array"
}
}
セキュリティで保護されたパラメーター
文字列またはオブジェクトのパラメーターをセキュリティで保護されたものとマークすることができます。 セキュリティで保護されたパラメーターの値はデプロイ履歴に保存されず、ログに記録されません。
"parameters": {
"demoPassword": {
"type": "secureString"
},
"demoSecretObject": {
"type": "secureObject"
}
}
使用できる値
パラメーターに使用できる値を定義できます。 使用できる値は配列で指定します。 使用できる値の 1 つではない値がパラメーターに渡された場合、検証時にデプロイは失敗します。
"parameters": {
"demoEnum": {
"type": "string",
"allowedValues": [
"one",
"two"
]
}
}
既定値
パラメーターの既定値を指定できます。 既定値は、デプロイ時に値が指定されない場合に使用されます。
"parameters": {
"demoParam": {
"type": "string",
"defaultValue": "Contoso"
}
}
パラメーターの他のプロパティと共に既定値を指定するには、次の構文を使用します。
"parameters": {
"demoParam": {
"type": "string",
"defaultValue": "Contoso",
"allowedValues": [
"Contoso",
"Fabrikam"
]
}
}
既定値を指定した式を使用できます。 パラメーター セクションでは、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')]"
}
}
ただし、既定値として変数を参照することはできません。
長さの制限
文字列と配列のパラメーターの最小長と最大長を指定できます。 一方または両方の制約を設定できます。 文字列の場合、長さは文字数を示します。 配列の場合、長さは配列内の項目数を示します。
次の例では、2 つのパラメーターを宣言しています。 1 つ目のパラメーターは、文字数が 3-24 である必要があるストレージ アカウント名用です。 もう 1 つのパラメーターは、項目数が 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
制約が定義されていない場合、既定値は true
です。
値が型定義の場合、この値では、インデックスが 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"]
}
}
prefixItems
を使用せずに items
を使用できます。 次の例では、[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
}
Null 許容制約
Null 許容制約は、languageVersion 2.0 でのみ使用できます。 これにより、値を null
にでき省略もできることを示します。 例については、「Properties」をご覧ください。
説明
テンプレートのユーザーが指定する値を理解できるように、パラメーターに説明を追加することができます。 ポータルからテンプレートをデプロイする場合、説明で指定したテキストがそのパラメーターのヒントとして自動的に使用されます。 パラメーター名から推測できる情報よりもテキストからわかる情報の方が多い場合にのみ、説明を追加します。
"parameters": {
"virtualMachineSize": {
"type": "string",
"metadata": {
"description": "Must be at least Standard_A3 to support 2 NICs."
},
"defaultValue": "Standard_DS1_v2"
}
}
パラメーターを使用する
パラメーターの値を参照するには、parameters 関数を使用します。 次の例では、キー コンテナー名にパラメーター値が使用されています。
{
"$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')]",
...
}
]
}
パラメーターとしてのオブジェクト
関連する値は 1 つのオブジェクトとして渡すことにより整理できます。 この方法により、テンプレート内のパラメータ数も減少します。
次の例は、オブジェクトであるパラメーターを示しています。 既定値は、オブジェクトの予想されるプロパティを示しています。 これらのプロパティは、デプロイするリソースを定義するときに使用されます。
{
"$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": "eastus",
"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]"
}
}
]
}
}
]
}
サンプル テンプレート
次の例は、パラメーターを使用するためのシナリオを示しています。
Template | 説明 |
---|---|
既定値のための関数を含むパラメーター | パラメーターの既定値を定義する際のテンプレート関数の使用方法を説明します。 このテンプレートではリソースをデプロイしません。 パラメーターの値を作成して、その値を返します。 |
パラメーター オブジェクト | パラメーターのオブジェクトの使用方法を示します。 このテンプレートではリソースをデプロイしません。 パラメーターの値を作成して、その値を返します。 |
次のステップ
- パラメーターに使用できるプロパティの詳細については、「ARM テンプレートの構造と構文について」をご覧ください。
- パラメーター値をファイルとして渡す方法については、「Resource Manager パラメーター ファイルの作成」を参照してください。
- パラメーターの作成に関する推奨事項については、ベスト プラクティス - パラメーターに関する記事をご覧ください。