ARM 模板中的类型定义

项目
10/04/2023

本文介绍如何在 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 模板的结构和语法。