ARM 模板中的类型定义
本文介绍如何在 Azure 资源管理器模板(ARM 模板)中创建和使用定义。 通过定义自己的类型,可以重用这些类型。 类型定义只能与 languageVersion 2.0 一起使用。
注意
适用于 Visual Studio Code 的 Azure 资源管理器工具扩展的当前版本无法识别 languageVersion 2.0 中提供的增强功能。
提示
建议使用 Bicep,因为它提供与 ARM 模板相同的功能,并且该语法更易于使用。 若要了解详细信息,请参阅 Bicep 中的用户定义数据类型。
最小声明
每个类型定义至少需要一个名称以及 type
或 $ref
。
"definitions": {
"demoStringType": {
"type": "string"
},
"demoIntType": {
"type": "int"
},
"demoBoolType": {
"type": "bool"
},
"demoObjectType": {
"type": "object"
},
"demoArrayType": {
"type": "array"
}
}
允许的值
可以定义类型定义允许的值。 可在数组中提供允许的值。 如果为类型定义传入的值不是允许的值之一,则部署会在验证过程中失败。
"definitions": {
"demoEnumType": {
"type": "string",
"allowedValues": [
"one",
"two"
]
}
}
长度约束
可以为字符串和数组类型定义指定最小和最大长度。 可以设置一个或两个约束。 对于字符串,长度指示字符数。 对于数组,长度指示数组中的项数。
以下示例声明两个类型定义。 一个类型定义对应于一个必须具有 3-24 个字符的存储帐户名称。 另一个类型定义是一个必须包含 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": "string", "bar": -1}
、{"foo": "", "bar": 1}
或任何没有 foo
或 bar
属性的对象。
"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
定义根据鉴别器属性应用什么架构。 以下示例将接受 {"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
。
如果 value 是类型定义,则该值描述应用于数组中索引大于 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"
}
}
可以使用 items
,而不使用 prefixItems
。 以下示例将接受 [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
或被省略。 有关示例,请参阅 属性。
说明
可以向类型定义添加说明,帮助模板用户了解要提供的值。
"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 模板的结构和语法。