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} 或任何没有 foobar 属性的对象。

"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')]"
    }
  }
}

后续步骤