Определения типов в шаблонах ARM

2025-05-03

В этой статье описывается создание и использование определений в шаблоне Azure Resource Manager (шаблон ARM). Определив собственные типы, вы можете повторно использовать эти типы. Определения типов можно использовать только с языкомVersion 2.0.

Замечание

Текущий выпуск расширения средств Azure Resource Manager для Visual Studio Code не распознает улучшения, внесенные в 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 определено, значение по умолчанию равно 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"}
          }
      }
    }
  }
}

Ограничения массива

префиксItems

Значением prefixItems является массив определений типов. Каждое определение типа в значении — это схема, используемая для проверки элемента массива по одному индексу. В следующем примере будет принято [1, true] , но отклонено [1, "string"] или [1]:

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

предметы

Значение 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"
  }
}

Вы можете использовать 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, указывает, что значение может быть 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".