ARM テンプレートのパラメーター

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

この記事では、Azure Resource Manager テンプレート (ARM テンプレート) でパラメーターを定義および使用する方法について説明します。パラメーターに異なる値を指定することにより、さまざまな環境でテンプレートを再利用できます。

Resource Manager は、デプロイ操作を開始する前にパラメーター値を解決します。テンプレートでパラメーターが使用されている場合、Resource Manager はそれを解決済みの値に置き換えます。

各パラメーターは、いずれかのデータ型に設定する必要があります。

languageVersion 2.0 では、minValue、maxValue、minLength、maxLength、allowedValues に加え、definitions、parameters、outputs の定義で使用される集約型検証制約がいくつか導入されています。これらの制約を次に示します。

additionalProperties
discriminator
items
nullable
prefixItems
properties

注意

Visual Studio Code 用 Azure Resource Manager Tools 拡張機能の現行リリースでは、languageVersion 2.0 で作成された拡張機能は認識されません。

ヒント

ARM テンプレートと同じ機能を備え、構文も使いやすいため、Bicep をお勧めします。詳細については、「パラメーター」を参照してください。

テンプレートではパラメーターが 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

値 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 の値は、型定義またはブール値です。 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 パラメーターファイルの作成」を参照してください。
パラメーターの作成に関する推奨事項については、ベストプラクティス - パラメーターに関する記事をご覧ください。