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

Статья
09/03/2023

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

Примечание

Текущий выпуск расширения Azure Resource Manager Tools для 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",
  }
}

Все свойства являются обязательными, если определение типа свойства не содержит ограничение true , допускающее значение NULL: true . Чтобы сделать оба свойства в предыдущем примере необязательными, они будут выглядеть следующим образом:

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

Значение additionalProperties является определением типа или логическим значением. Если ограничение не additionalProperties определено, значение по умолчанию — true.

Если value является определением типа, значение описывает схему, которая применяется ко всем свойствам, не упомянутым в ограничении 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.

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