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

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

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

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

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "",
  "contentVersion": "",
  "apiProfile": "",
  "definitions": { },
  "parameters": { },
  "variables": { },
  "functions": [ ],
  "resources": [ ], /* or "resources": { } with languageVersion 2.0 */
  "outputs": { }
}

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

Определения

definitions В разделе шаблона укажите схемы, используемые для проверки значений массива и объектов. Definitions можно использовать только с languageVersion 2.0.

"definitions": {
  "<definition-name": {
    "type": "<data-type-of-definition>",
    "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>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the-type-definition>"
    }
  }
}

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

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

Параметры

В разделе 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>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}

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

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

Переменные

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

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

"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>"
        }
      }
    }
  }
],

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

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

Ресурсы

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

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

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

Для поддержки символьного имени Bicep в шаблонах JSON ARM добавьте languageVersion версию или более новую версию 2.0 и измените определение ресурса из массива на объект.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Дополнительные сведения см. в статье о ресурсах DSC.

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

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

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

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

"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>
    }
  }
}

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

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

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

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

Комментарии

Для встроенных комментариев можно использовать символы // или /* ... */. В Visual Studio Code сохраните файлы параметров с комментариями в формате JSON с типом файла примечаний (JSONC), в противном случае вы получите сообщение об ошибке с сообщением "Комментарии, не разрешенные в JSON".

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-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, то вы можете использовать встроенные комментарии. В таком случае встроенные комментарии больше не будут помечены как недопустимые.

Найдите в 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."
    }
  },

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

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

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2022-09-01",
    "name": "[format('{0}{1}', '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.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-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 раздел мультиломаных.

languageVersion 2.0

Чтобы использовать languageVersion 2.0, добавьте "languageVersion": "2.0" в шаблон:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Улучшения и изменения, которые приходят с languageVersion 2.0:

• Используйте символьные имена в шаблоне ARM JSON. Дополнительные сведения см. в разделе "Использование символьного имени".
• Используйте символьные имена в циклах копирования ресурсов. См . раздел "Использование символьного имени".
• Используйте символьные имена в dependsOn массивах. См . раздел "Зависит от ресурсов" в цикле.
• Используйте символическое имя вместо имени ресурса в reference функции. См. справочные материалы.
• Функция references(), которая возвращает массив объектов, представляющих состояния среды выполнения коллекции ресурсов. См . ссылки.
• Используйте свойство ресурса "существующий" для объявления существующих ресурсов для ARM для чтения, а не для развертывания ресурса. См. раздел "Объявление существующих ресурсов".
• Создание определяемых пользователем типов. См . определение типа.
• Дополнительные ограничения проверки агрегатного типа для использования в параметрах и выходных данных.
• Значение по умолчанию для expressionEvaluationOptions свойства inner. Значение outer заблокировано. См . область оценки выражений в вложенных шаблонах.
• Функция deployment возвращает ограниченное подмножество свойств. См . развертывание.
• Если ресурс deployments используется в развертывании символьного имени, используйте apiVersion 2020-09-01 или более поздней версии.
• В определении ресурсов двойные экранирование значений в выражении больше не требуется. См . экранные символы.

При использовании любой из следующих функций Bicep автоматически включается создание кода версии 2.0:

• определяемые пользователем типы
• определяемые пользователем функции
• Импорт во время компиляции
• экспериментальные функции

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

• Полные шаблоны для различных типов решений доступны на странице Шаблоны быстрого запуска Azure.
• Дополнительные сведения о функциях, которые можно использовать в шаблонах, см. в статье Функции шаблонов ARM.
• Инструкции по объединению нескольких шаблонов при развертывании см. в статье Использование связанных и вложенных шаблонов при развертывании ресурсов Azure.
• Рекомендации по созданию шаблонов см. в статье Рекомендации по работе с шаблонами ARM.
• Ответы на распространенные вопросы см. в разделе Часто задаваемые вопросы о шаблонах ARM.