ARM テンプレートの型定義

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

この記事では、Azure Resource Manager テンプレート (ARM テンプレート) で定義を作成および使用する方法について説明します。独自の型を定義することで、これらの型を再利用できます。型定義は languageVersion 2.0 でのみ使用できます。

注意

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

ヒント

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

最小限の宣言

少なくとも、すべての型定義には名前と、type または $ref のいずれかが必要です。

"definitions": {
  "demoStringType": {
    "type": "string"
  },
  "demoIntType": {
    "type": "int"
  },
  "demoBoolType": {
    "type": "bool"
  },
  "demoObjectType": {
    "type": "object"
  },
  "demoArrayType": {
    "type": "array"
  }
}

使用できる値

型定義に使用できる値を定義できます。使用できる値は配列で指定します。使用できる値の 1 つではない値が型定義に渡された場合、検証時にデプロイは失敗します。

"definitions": {
  "demoEnumType": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

長さの制限

文字列と配列の型定義の最小長と最大長を指定できます。一方または両方の制約を設定できます。文字列の場合、長さは文字数を示します。配列の場合、長さは配列内の項目数を示します。

次の例では、2 つの型定義を宣言しています。 1 つ目の型定義は、文字数が 3-24 である必要があるストレージアカウント名用です。もう 1 つの型定義は、項目数が 1-5 個である必要がある配列です。

"definitions": {
  "storageAccountNameType": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNameType": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

整数の制約

整数型定義の最小値と最大値を設定できます。一方または両方の制約を設定できます。

"definitions": {
  "monthType": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

オブジェクトの制約

プロパティ

properties の値は、プロパティ名 => 型定義のマップです。

次の例では、{"foo": "string", "bar": 1} を受け入れますが、foo または bar プロパティを持たない {"foo": "string", "bar": -1} オブジェクト、{"foo": "", "bar": 1}、または任意のオブジェクトを拒否します。

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
},
"parameters": {
  "objectParameter": {
    "$ref": "#/definitions/objectDefinition",
  }
}

プロパティの型定義に "nullable": true 制約がない限り、すべてのプロパティが必要です。前の例の両方のプロパティを省略可能にするには、次のようになります。

"definitions": {
  "objectDefinition": {
    "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} を拒否します。

"definitions": {
  "dictionaryDefinition": {
    "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"} を拒否します。

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

値が true の場合、properties 制約で定義されていないプロパティは任意の値を受け入れます。次の例では、{"foo": "string", "bar": 1, "fizz": "buzz"} を受け入れます。

"definitions": {
  "dictionaryDefinition": {
    "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"} を拒否します。

"definitions": {
  "taggedUnionDefinition": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

配列の制約

prefixItems

prefixItems の値は、型定義の配列です。値の各型定義は、配列の要素を同じインデックスで検証するために使用されるスキーマです。次の例では、[1, true] を受け入れますが、[1, "string"] または [1] を拒否します。

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ]
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

items

items の値は、型定義またはブール値です。 items 制約が定義されていない場合、既定値は true です。

値が型定義の場合、値はインデックスが prefixItems 制約の最大インデックスより大きい配列のすべての要素に適用されるスキーマを記述します。次の例では、[1, true, 1] または [1, true, 1, 1] を受け入れますが、[1, true, "foo"] を拒否します。

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" }
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

prefixItems を使用せずに items を使用できます。次の例では、[1, 2] または [1] を受け入れますが、["foo"] を拒否します。

"definitions": {
  "intArrayDefinition": {
    "type": "array",
    "items": { "type": "int" }
  }
},
"parameters": {
  "intArrayParameter": {
    "$ref": "#/definitions/intArrayDefinition"
  }
}

値が false の場合、検証される配列は prefixItems 制約とまったく同じ長さである必要があります。次の例では、[1, true] を受け入れますが、[1, true, 1] および [1, true, false, "foo", "bar"] を拒否します。

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": false
}

値が true の場合、インデックスが prefixItems 制約の最大インデックスより大きい配列の要素は、任意の値を受け入れます。次の例は [1, true]、[1, true, 1]、および [1, true, false, "foo", "bar"] を受け入れます。

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

NULL 許容制約

NULL 許容制約は、値を null または省略できないことを示します。例については、「プロパティ」を参照してください。

説明

テンプレートのユーザーが指定する値を理解できるように、型定義に説明を追加することができます。

"definitions": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

定義の使用

型定義を参照するには、次の構文を使用します。

"$ref": "#/definitions/<definition-name>"

次の例は、パラメーターと出力から型定義を参照する方法を示しています。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "languageVersion": "2.0",

  "definitions": {
    "naturalNumber": {
      "type": "int",
      "minValue": 1
    }
  },
  "parameters": {
    "numberParam": {
      "$ref": "#/definitions/naturalNumber",
      "defaultValue": 0
    }
  },
  "resources": {},
  "outputs": {
    "output1": {
      "$ref": "#/definitions/naturalNumber",
      "value": "[parameters('numberParam')]"
    }
  }
}

次のステップ

型定義に使用できるプロパティの詳細については、「ARM テンプレートの構造と構文について」を参照してください。