Описание структуры и синтаксиса шаблонов ARM

В этой статье описывается структура шаблона Azure Resource Manager (ARM). Статья содержит информацию о разных разделах шаблона и свойствах, которые доступны в этих разделах.

Эта статья предназначена для пользователей, у которых есть опыт работы с шаблонами ARM. Она содержит подробные сведения о структуре шаблона. Пошаговые инструкции по созданию шаблона см. в статье Учебник. Создание и развертывание первого шаблона ARM. Чтобы узнать больше о шаблонах Resource Manager из модулей Microsoft Learn, см. статью Развертывание ресурсов и управление ими в Azure с помощью шаблонов Resoure Manager.

Совет

Bicep — это новый язык, который предлагает те же возможности, что и шаблоны ARM, но имеет более простой в использовании синтаксис. Если вы рассматриваете инфраструктуру в качестве параметров кода, рекомендуем Bicep.

Чтобы узнать больше о разделах файла Bicep, ознакомьтесь со статьей Описание структуры и синтаксиса файлов Bicep.

Формат шаблона

Шаблон с самой простой структурой содержит следующие элементы:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}
Имя элемента Обязательно Описание
$schema Да Расположение файла схемы в нотации объектов JavaScript (JSON), в котором описывается версия языка шаблона. Номер используемой вами версии зависит от области развертывания и вашего редактора JSON.

Если вы используете Visual Studio Code с расширением инструментов Azure Resource Manager, установите последнюю версию для развертывания групп ресурсов:
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

Другие редакторы (в том числе Visual Studio) могут не подойти для обработки этой схемы. Для таких редакторов используйте:
https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

Для развертывания подписок используйте:
https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#

Для развертывания групп управления используйте:
https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#

Для развертывания клиентов используйте:
https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#
contentVersion Да Версия шаблона (например, 1.0.0.0). Для этого элемента можно предоставить любое значение. Это значение позволяет задокументировать важные изменения в шаблоне. При развертывании ресурсов с помощью шаблона это значение позволяет убедиться в том, что используется нужный шаблон.
apiProfile Нет Версия API, которая служит в качестве коллекции версий API для типов ресурсов. Используйте это значение, чтобы не указывать версии API для каждого ресурса в шаблоне. Если указать версию профиля API, не указав версию API для типа ресурса, Resource Manager использует для этого типа ресурса версию API, определенную в профиле.

Свойство профиля API особенно полезно при развертывании шаблона в других средах, например Azure Stack и глобальной среде Azure. Используйте версию профиля API, чтобы шаблон автоматически применял версии, поддерживаемые в обеих средах. Список текущих версий профиля API и определенных в нем версий API ресурсов см. в статье Профиль API.

Дополнительные сведения см. в разделе Отслеживание версий с помощью профилей API.
parameters Нет Значения, которые предоставляются при выполнении развертывания для настройки развертывания ресурсов.
variables Нет Значения, используемые в виде фрагментов JSON в шаблоне для упрощения выражений на языке шаблона.
Функции Нет Определяемые пользователем функции, доступные в шаблоне.
resources Да Типы ресурсов, которые развертываются или обновляются в группе ресурсов или подписке.
outputs Нет Значения, возвращаемые после развертывания.

Каждый элемент содержит свойства, которые можно задать. В этой статье подробнее описаны разделы шаблона.

Параметры

В разделе parameters шаблона указываются значения, которые вы можете вводить во время развертывания ресурсов. В шаблоне может быть не более 256 параметров. Вы можете сократить число параметров, используя объекты с несколькими свойствами.

Доступные свойства для параметра

"parameters": {
  "<parameter-name>" : {
    "type" : "<type-of-parameter-value>",
    "defaultValue": "<default-value-of-parameter>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array-parameters>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}
Имя элемента Обязательно Описание
parameter-name Да Имя параметра. Должно быть допустимым идентификатором JavaScript.
тип Да Тип значения параметра. Допустимые типы и значения: string, securestring, int, bool, object, secureObject и array. См. статью Типы данных в шаблонах ARM.
defaultValue Нет Значение параметра, используемое по умолчанию, если пользователь не задал иное значение.
allowedValues Нет Массив допустимых значений параметра, по которому сверяются правильные значения.
minValue Нет Минимальное значение для параметров типа int. Это включающее значение.
maxValue Нет Максимальное значение для параметров типа int. Это включающее значение.
minLength Нет Минимальная длина (включительно) параметров типа string, secure string и array.
maxLength Нет Максимальная длина (включительно) параметров типа string, secure string и array.
description Нет Описание параметра, отображаемого для пользователей на портале. Дополнительные сведения см. в разделе комментариев в шаблонах.

Примеры использования параметров см. в статье Параметры в шаблонах ARM.

Найдите в Bicep раздел параметров.

Переменные

В разделе variables указываются значения, которые можно использовать в разных частях шаблона. Переменные определять не обязательно, однако они часто упрощают шаблон, снижая число сложных выражений. Формат каждой переменной соответствует одному из типов данных.

В приведенном ниже примере показаны доступные параметры для определения переменных.

"variables": {
  "<variable-name>": "<variable-value>",
  "<variable-name>": {
    <variable-complex-type-value>
  },
  "<variable-object-name>": {
    "copy": [
      {
        "name": "<name-of-array-property>",
        "count": <number-of-iterations>,
        "input": <object-or-value-to-repeat>
      }
    ]
  },
  "copy": [
    {
      "name": "<variable-array-name>",
      "count": <number-of-iterations>,
      "input": <object-or-value-to-repeat>
    }
  ]
}

Сведения о том, как задать несколько значений для переменной с помощью свойства copy, см. в статье Итерация переменной в шаблонах ARM.

Примеры использования переменных см. в статье Переменные в шаблонах ARM.

Найдите в Bicep раздел переменных.

Функции

В шаблоне можно создать свои собственные функции. Эти функции доступны для использования в шаблоне. Как правило, определяются сложные выражения, которые вы не хотите повторять в шаблоне. Создаются определяемые пользователем функции на основе выражений и функции, которые поддерживаются в шаблонах.

При определении пользовательской функции есть несколько ограничений:

  • Функция не может обращаться к переменным.
  • Функция может использовать только параметры, определенные в самой функции. При использовании функции parameters внутри пользовательской функции доступны только параметры этой функции.
  • Функция не может вызывать другие функции, определяемые пользователем.
  • Для функции нельзя использовать ссылочную функцию.
  • Для параметров этой функции нельзя задавать значения по умолчанию.
"functions": [
  {
    "namespace": "<namespace-for-functions>",
    "members": {
      "<function-name>": {
        "parameters": [
          {
            "name": "<parameter-name>",
            "type": "<type-of-parameter-value>"
          }
        ],
        "output": {
          "type": "<type-of-output-value>",
          "value": "<function-return-value>"
        }
      }
    }
  }
],
Имя элемента Обязательно Описание
namespace Да Пространство имен для пользовательских функций. Используется для предотвращения конфликтов имен с функциями шаблона.
function-name Да Имя пользовательской функции. При вызове функции объедините ее имя с пространством имен. Например, чтобы вызвать функцию с именем uniqueName в пространстве имен contoso, используйте имя "[contoso.uniqueName()]".
parameter-name Нет Имя параметра, используемого в пользовательской функции.
значение параметра Нет Тип значения параметра. Допустимые типы и значения: string, securestring, int, bool, object, secureObject и array.
output-type Да Тип выходного значения. Выходные значения поддерживают те же типы, что и входные параметры функции.
output-value Да Выражение языка шаблона, которое оценивается и возвращается из функции.

Примеры использования пользовательских функций см. в статье Пользовательские функции в шаблоне ARM.

В Bicep не поддерживаются определяемые пользователем функции. Bicep поддерживает много разных функций и операторов.

Ресурсы

В разделе resources определяются ресурсы, которые развертываются или обновляются.

Ресурсы определяются с помощью следующей структуры:

"resources": [
  {
      "condition": "<true-to-deploy-this-resource>",
      "type": "<resource-provider-namespace/resource-type-name>",
      "apiVersion": "<api-version-of-resource>",
      "name": "<name-of-the-resource>",
      "comments": "<your-reference-notes>",
      "location": "<location-of-resource>",
      "dependsOn": [
          "<array-of-related-resource-names>"
      ],
      "tags": {
          "<tag-name1>": "<tag-value1>",
          "<tag-name2>": "<tag-value2>"
      },
      "identity": {
        "type": "<system-assigned-or-user-assigned-identity>",
        "userAssignedIdentities": {
          "<resource-id-of-identity>": {}
        }
      },
      "sku": {
          "name": "<sku-name>",
          "tier": "<sku-tier>",
          "size": "<sku-size>",
          "family": "<sku-family>",
          "capacity": <sku-capacity>
      },
      "kind": "<type-of-resource>",
      "scope": "<target-scope-for-extension-resources>",
      "copy": {
          "name": "<name-of-copy-loop>",
          "count": <number-of-iterations>,
          "mode": "<serial-or-parallel>",
          "batchSize": <number-to-deploy-serially>
      },
      "plan": {
          "name": "<plan-name>",
          "promotionCode": "<plan-promotion-code>",
          "publisher": "<plan-publisher>",
          "product": "<plan-product>",
          "version": "<plan-version>"
      },
      "properties": {
          "<settings-for-the-resource>",
          "copy": [
              {
                  "name": ,
                  "count": ,
                  "input": {}
              }
          ]
      },
      "resources": [
          "<array-of-child-resources>"
      ]
  }
]
Имя элемента Обязательно Описание
condition Нет Логическое значение, указывающее, будет ли подготавливаться ресурс во время этого развертывания. Если установлено значение true, при развертывании создается ресурс. Если установлено значение false, при развертывании ресурс не создается. См. статью Условное развертывание в шаблонах ARM.
тип Да Тип ресурса. Это значение представляет собой сочетание пространства имен поставщика ресурсов и типа ресурса (например, Microsoft.Storage/storageAccounts). Чтобы определить доступные значения, см. справочник по шаблонам. Для дочернего ресурса формат типа зависит от того, вложен он в родительский ресурс или определен за его пределами. См. о настройке имени и типа дочернего ресурса.
версия_API Да Версия REST API, которая будет использована для создания ресурса. При создании нового шаблона укажите в качестве значения последнюю версию развертываемого ресурса. Пока шаблон работает надлежащим образом, продолжайте использовать ту же версию API. Продолжая использовать ту же версию API, вы можете не опасаться того, что с новой версией API изменится принцип работы шаблона. Рекомендуем обновлять версию API только в том случае, если требуется использовать новую функцию, появившуюся в более поздней версии. Чтобы определить доступные значения, см. справочник по шаблонам.
name Да Имя ресурса. Имя должно соответствовать ограничениям компонентов URI, определенным в RFC3986. Службы Azure, предоставляющие имя ресурса внешним пользователям, проверяют это имя, чтобы убедиться, что это не попытка подделки другого удостоверения. Для дочернего ресурса формат имени зависит от того, вложен он в родительский ресурс или определен за его пределами. См. о настройке имени и типа дочернего ресурса.
comments Нет Заметки по ресурсам в шаблоне. Дополнительные сведения см. в разделе комментариев в шаблонах.
location Различается Поддерживаемые географические расположения указанного ресурса. Вы можете выбрать любое из доступных расположений. Но обычно имеет смысл выбрать расположение, которое находится недалеко от пользователей. Кроме того, целесообразно разместить взаимодействующие ресурсы в одном регионе. Большинству типов ресурсов нужно расположение, но некоторым типам (например, назначению роли) оно не требуется. См. статью Задание расположения ресурса в шаблоне ARM.
Свойство dependsOn Нет Ресурсы, которые должны быть развернуты перед развертыванием этого ресурса. Resource Manager оценивает зависимости между ресурсами и развертывает эти ресурсы в правильном порядке. Если ресурсы не зависят друг от друга, они развертываются параллельно. Значение может представлять собой разделенный запятыми список имен ресурсов или уникальных идентификаторов ресурсов. Выводится только список ресурсов, развертываемых в этом шаблоне. Ресурсы, которые не определены в этом шаблоне, уже должны существовать. Избегайте добавления ненужных зависимостей, так как это может замедлить развертывание и привести к созданию циклических зависимостей. Руководство по установке зависимостей см. в статье Определение порядка развертывания ресурсов в шаблонах ARM.
tags Нет Теги, связанные с ресурсом. Примените теги, чтобы логически организовать ресурсы в подписке.
удостоверение Нет Некоторые ресурсы поддерживают управляемые удостоверения для ресурсов Azure. У них на корневом уровне объявления ресурса есть объект Identity. Вы можете указать, назначается ли удостоверение пользователем или системой. Для назначаемых пользователем удостоверений укажите список идентификаторов ресурсов для удостоверений. Задайте для ключа идентификатор ресурса, а для значения — пустой объект. Дополнительные сведения см. в статье Настройка управляемых удостоверений для ресурсов Azure на виртуальной машине Azure с помощью шаблонов.
sku нет В некоторых ресурсах допускается использовать значения, определяющие номер SKU для развертывания. Например, можно указать тип избыточности для учетной записи хранения.
kind Нет В некоторых ресурсах допускается использовать значение, которое определяет тип развертываемого ресурса. Например, можно указать в качестве типа создаваемой базы данных Cosmos DB.
область Нет Свойство scope доступно только для типов ресурсов расширений. С его помощью можно указать область действия, отличную от области развертывания. См. статью Настройка области для ресурсов расширения в шаблонах ARM.
copy Нет Количество создаваемых ресурсов (если нужно несколько экземпляров). Параллельный режим используется по умолчанию. Используйте последовательный режим, если вы не хотите развертывать все ресурсы одновременно. Дополнительные сведения см. в статье Создание нескольких экземпляров ресурсов в Azure Resource Manager.
План Нет В некоторых ресурсах допускается использовать значения, определяющие номер плана для развертывания. Например, можно указать образ Marketplace для виртуальной машины.
properties Нет Параметры конфигурации ресурса. Значения свойств совпадают со значениями, указываемыми в тексте запроса для операции REST API (метод PUT) для создания ресурса. Кроме того, можно указать массив copy для создания нескольких экземпляров свойства. Чтобы определить доступные значения, см. справочник по шаблонам.
ресурсов нет Дочерние ресурсы, которые зависят от определяемого ресурса. Следует указать только те типы ресурсов, которые разрешены в схеме родительского ресурса. Зависимость от родительского ресурса не подразумевается. Ее необходимо определить явным образом. См. о настройке имени и типа дочернего ресурса.

Найдите в Bicep раздел ресурсов.

Выходные данные

В разделе outputs указываются значения, которые возвращаются после развертывания. Как правило, возвращаются значения из развернутых ресурсов.

В следующем примере показана структура определения выходных данных:

"outputs": {
  "<output-name>": {
    "condition": "<boolean-value-whether-to-output-value>",
    "type": "<type-of-output-value>",
    "value": "<output-value-expression>",
    "copy": {
      "count": <number-of-iterations>,
      "input": <values-for-the-variable>
    }
  }
}
Имя элемента Обязательно Описание
output-name Да Имя выходного значения. Должно быть допустимым идентификатором JavaScript.
condition Нет Логическое значение, которое указывает, возвращается ли выходное значение. Если установлено значение true, то при развертывании значение является частью выходных данных. Если установлено значение false, при развертывании выходное значение не создается. Когда не задано, по умолчанию используется значение true.
тип Да Тип выходного значения. Выходные значения поддерживает те же типы, что и входные параметры шаблона. Если указан тип выходных данных securestring, значение не отображается в журнале развертывания и его невозможно получить из другого шаблона. Чтобы использовать значение секрета в нескольких шаблонах, храните секрет в Key Vault и ссылайтесь на него в файле параметров. Дополнительные сведения см. в статье Использование Azure Key Vault для передачи защищенного значения параметра во время развертывания.
value Нет Выражение на языке шаблона, которое вычисляется и возвращается в качестве выходного значения. Укажите value или copy.
copy Нет Используется для возврата нескольких значений выходных данных. Укажите value или copy. Дополнительные сведения см. в статье Итерация выходных данных в шаблонах ARM.

Примеры использования выходных данных см. в статье Выходные данные в шаблонах ARM.

Найдите в Bicep раздел выходных данных.

Комментарии и метаданные

Есть несколько вариантов добавления комментариев и метаданных к шаблону.

Комментарии

Для встроенных комментариев можно использовать символы // или /* ... */.

Примечание

При развертывании шаблонов с комментариями с помощью Azure CLI используйте версию 2.3.0 или более позднюю и укажите параметр --handle-extended-json-format.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

В Visual Studio Code расширение инструментов Azure Resource Manager может автоматически определять шаблоны ARM и менять режим языка. Если в правом нижнем углу окна Visual Studio Code отображается надпись Шаблон Azure Resource Manager, то вы можете использовать встроенные комментарии. В таком случае встроенные комментарии больше не будут помечены как недопустимые.

Visual Studio Code Azure Resource Manager template mode

Найдите в Bicep раздел комментариев.

Метаданные

Вы можете добавить объект metadata практически в любом месте шаблона. Resource Manager игнорирует объект, но ваш редактор JSON может предупредить вас, что свойство недопустимо. Определите необходимые свойства в объекте.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "comments": "This template was developed for demonstration purposes.",
    "author": "Example Name"
  },

Для parameters добавьте объект metadata со свойством description.

"parameters": {
  "adminUsername": {
    "type": "string",
    "metadata": {
      "description": "User name for the Virtual Machine."
    }
  },

При развертывании шаблона через портал текст, который вы указываете в описании, автоматически используется в качестве подсказки для этого параметра.

Show parameter tip

Для resources добавьте элемент comments или объект metadata. В приведенном ниже примере показаны элемент comments и объект metadata.

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2018-07-01",
    "name": "[concat('storage', uniqueString(resourceGroup().id))]",
    "comments": "Storage account used to store VM disks",
    "location": "[parameters('location')]",
    "metadata": {
      "comments": "These tags are needed for policy compliance."
    },
    "tags": {
      "Dept": "[parameters('deptName')]",
      "Environment": "[parameters('environment')]"
    },
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "properties": {}
  }
]

Для outputs добавьте объект metadata к выходному значению.

"outputs": {
  "hostname": {
    "type": "string",
    "value": "[reference(variables('publicIPAddressName')).dnsSettings.fqdn]",
    "metadata": {
      "comments": "Return the fully qualified domain name"
    }
  },

Добавить объект metadata в пользовательские функции невозможно.

Многострочные строки

Строку можно разбить на несколько строк. Обратите внимание на свойство location и один из комментариев в приведенном ниже примере JSON.

Примечание

Для развертывания шаблонов с многострочными литералами используйте Azure PowerShell или Azure CLI. Что касается CLI, используйте версию не ниже 2.3.0 и укажите переключатель --handle-extended-json-format.

Многострочные литералы не поддерживаются при развертывании шаблона через портал Azure, конвейер DevOps или REST API.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Найдите в Bicep раздел мультиломаных.

Следующие шаги