Описание структуры и синтаксиса шаблонов Azure Resource ManagerUnderstand the structure and syntax of Azure Resource Manager templates

В этой статье описана структура шаблона Azure Resource Manager.This article describes the structure of an Azure Resource Manager template. Статья содержит информацию о разных разделах шаблона и свойствах, которые доступны в этих разделах.It presents the different sections of a template and the properties that are available in those sections. Шаблон состоит из JSON и выражений, на основе которых можно создавать значения для развертывания.The template consists of JSON and expressions that you can use to construct values for your deployment.

Эта статья предназначена для пользователей, знакомых с шаблонами диспетчер ресурсов.This article is intended for users who have some familiarity with Resource Manager templates. Он предоставляет подробные сведения о структуре и синтаксисе шаблона.It provides detailed information about the structure and syntax of the template. Если вы хотите ознакомиться с введением в создание шаблона, см. статью Создание первого шаблона Azure Resource Manager.If you want an introduction to creating a template, see Create your first Azure Resource Manager template.

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

Шаблон с самой простой структурой содержит следующие элементы:In its simplest structure, a template has the following elements:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}
Имя элементаElement name Обязательное значениеRequired ОписаниеDescription
$schema$schema ДаYes Расположение файла схемы JSON, который описывает версию языка шаблона.Location of the JSON schema file that describes the version of the template language.

Для развертывания групп ресурсов используйте https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#For resource group deployments, use: https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

Для развертывания подписки используйте https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#For subscription deployments, use: https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#
contentVersioncontentVersion ДаYes Версия шаблона (например, 1.0.0.0).Version of the template (such as 1.0.0.0). Для этого элемента можно предоставить любое значение.You can provide any value for this element. Это значение позволяет задокументировать важные изменения в шаблоне.Use this value to document significant changes in your template. При развертывании ресурсов с помощью шаблона это значение позволяет убедиться в том, что используется нужный шаблон.When deploying resources using the template, this value can be used to make sure that the right template is being used.
апипрофилеapiProfile НетNo Версия API, которая служит коллекцией версий API для типов ресурсов.An API version that serves as a collection of API versions for resource types. Используйте это значение, чтобы не указывать версии API для каждого ресурса в шаблоне.Use this value to avoid having to specify API versions for each resource in the template. Если указана версия профиля API и не указана версия API для типа ресурса, диспетчер ресурсов использует версию API для этого типа ресурсов, который определен в профиле.When you specify an API profile version and don't specify an API version for the resource type, Resource Manager uses the API version for that resource type that is defined in the profile.

Свойство профиля API особенно полезно при развертывании шаблона в различных средах, таких как Azure Stack и глобальные Azure.The API profile property is especially helpful when deploying a template to different environments, such as Azure Stack and global Azure. Используйте версию профиля API, чтобы убедиться, что шаблон автоматически использует версии, поддерживаемые в обеих средах.Use the API profile version to make sure your template automatically uses versions that are supported in both environments. Список текущих версий профиля API и версий API ресурсов, определенных в профиле, см. в разделе профиль API.For a list of the current API profile versions and the resources API versions defined in the profile, see API Profile.

Дополнительные сведения см. в статье Tracking Versions using API Profiles.For more information, see Track versions using API profiles.
parametersparameters НетNo Значения, которые предоставляются при выполнении развертывания для настройки развертывания ресурсов.Values that are provided when deployment is executed to customize resource deployment.
variablesvariables НетNo Значения, используемые в виде фрагментов JSON в шаблоне для упрощения выражений на языке шаблона.Values that are used as JSON fragments in the template to simplify template language expressions.
functionsfunctions НетNo Определяемые пользователем функции, доступные в шаблоне.User-defined functions that are available within the template.
resourcesresources ДаYes Типы ресурсов, которые развертываются или обновляются в группе ресурсов или подписке.Resource types that are deployed or updated in a resource group or subscription.
outputsoutputs НетNo Значения, возвращаемые после развертывания.Values that are returned after deployment.

Каждый элемент содержит свойства, которые можно задать.Each element has properties you can set. В этой статье подробнее описаны разделы шаблона.This article describes the sections of the template in greater detail.

СинтаксисSyntax

Базовый синтаксис шаблона — это JSON.The basic syntax of the template is JSON. Однако можно использовать выражения для расширения значений JSON, доступных в шаблоне.However, you can use expressions to extend the JSON values available within the template. Выражения начинаются и заканчиваются скобками [ : ]и соответственно.Expressions start and end with brackets: [ and ], respectively. Значение выражения вычисляется при развертывании шаблона.The value of the expression is evaluated when the template is deployed. Выражение может возвращать строку, целое число, логическое значение, массив или объект.An expression can return a string, integer, boolean, array, or object. В следующем примере показано выражение в значении параметра по умолчанию:The following example shows an expression in the default value of a parameter:

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
},

В выражении синтаксис resourceGroup() вызывает одну из функций, которые диспетчер ресурсов предоставляет для использования в шаблоне.Within the expression, the syntax resourceGroup() calls one of the functions that Resource Manager provides for use within a template. Как и в языке JavaScript, вызовы функций форматируются так: functionName(arg1,arg2,arg3).Just like in JavaScript, function calls are formatted as functionName(arg1,arg2,arg3). Синтаксис .location получает одно свойство из объекта, возвращаемого этой функцией.The syntax .location retrieves one property from the object returned by that function.

Функции шаблонов и их параметры зависят от регистра.Template functions and their parameters are case-insensitive. Например, Resource Manager одинаково преобразует variables('var1') и VARIABLES('VAR1') .For example, Resource Manager resolves variables('var1') and VARIABLES('VAR1') as the same. При вычислении функция сохранит регистр, если его изменение не является ее явным предназначением (например, функции toUpper и toLower).When evaluated, unless the function expressly modifies case (such as toUpper or toLower), the function preserves the case. Для некоторых типов ресурсов требования к регистру могут не зависеть от того, как происходит вычисление функций.Certain resource types may have case requirements irrespective of how functions are evaluated.

Чтобы литеральная строка начинались с левой квадратной [ скобки и заканчиваться правой ]квадратной скобкой, но не интерпретировать ее как выражение, добавьте лишнюю скобку, чтобы начать строку [[с.To have a literal string start with a left bracket [ and end with a right bracket ], but not have it interpreted as an expression, add an extra bracket to start the string with [[. Например, переменная:For example, the variable:

"demoVar1": "[[test value]"

Разрешается в [test value].Resolves to [test value].

Однако если литеральная строка не заканчивается квадратной скобкой, не нужно заключать первую квадратную скобку.However, if the literal string doesn't end with a bracket, don't escape the first bracket. Например, переменная:For example, the variable:

"demoVar2": "[test] value"

Разрешается в [test] value.Resolves to [test] value.

Чтобы передать строковое значение в качестве параметра функции, используйте одинарные кавычки.To pass a string value as a parameter to a function, use single quotes.

"name": "[concat('storage', uniqueString(resourceGroup().id))]"

Для экранирования двойных кавычек в выражении, например для добавления объекта JSON в шаблон, используйте обратную косую черту.To escape double quotes in an expression, such as adding a JSON object in the template, use the backslash.

"tags": {
    "CostCenter": "{\"Dept\":\"Finance\",\"Environment\":\"Production\"}"
},

Выражение шаблона не может содержать более 24 576 символов.A template expression can't exceed 24,576 characters.

Полный список функций шаблонов см. в статье Функции шаблонов диспетчера ресурсов Azure.For the full list of template functions, see Azure Resource Manager template functions.

ПараметрыParameters

В разделе параметров шаблона указываются значения, которые вы можете вводить во время развертывания ресурсов.In the parameters section of the template, you specify which values you can input when deploying the resources. Значения этих параметров позволяют настраивать развертывание путем предоставления значений, предназначенных для конкретной среды (например, для среды разработки, тестирования и рабочей среды).These parameter values enable you to customize the deployment by providing values that are tailored for a particular environment (such as dev, test, and production). Задавать параметры в шаблоне не обязательно, однако без них шаблон всегда будет развертывать одни и те же ресурсы с одинаковыми именами, расположениями и свойствами.You don't have to provide parameters in your template, but without parameters your template would always deploy the same resources with the same names, locations, and properties.

Существует ограничение в 256 параметров на один шаблон.You're limited to 256 parameters in a template. Вы можете сократить число параметров, создавая объекты с несколькими свойствами. Этот метод описан далее в этой статье.You can reduce the number of parameters by using objects that contain multiple properties, as shown in this article.

Доступные свойстваAvailable properties

Для параметра доступны следующие свойства:The available properties for a parameter are:

"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>" 
    }
  }
}
Имя элементаElement name Обязательное значениеRequired ОписаниеDescription
parameterNameparameterName ДаYes Имя параметра.Name of the parameter. Должно быть допустимым идентификатором JavaScript.Must be a valid JavaScript identifier.
typetype ДаYes Тип значения параметра.Type of the parameter value. Допустимые типы и значения: string, securestring, int, bool, object, secureObject и array.The allowed types and values are string, securestring, int, bool, object, secureObject, and array.
defaultValuedefaultValue НетNo Значение параметра, используемое по умолчанию, если пользователь не задал иное значение.Default value for the parameter, if no value is provided for the parameter.
allowedValuesallowedValues НетNo Массив допустимых значений параметра, по которому сверяются правильные значения.Array of allowed values for the parameter to make sure that the right value is provided.
minValueminValue НетNo Минимальное значение для параметров типа int. Это включающее значение.The minimum value for int type parameters, this value is inclusive.
maxValuemaxValue НетNo Максимальное значение для параметров типа int. Это включающее значение.The maximum value for int type parameters, this value is inclusive.
minLengthminLength НетNo Минимальная длина (включительно) параметров типа string, secure string и array.The minimum length for string, secure string, and array type parameters, this value is inclusive.
maxLengthmaxLength НетNo Максимальная длина (включительно) параметров типа string, secure string и array.The maximum length for string, secure string, and array type parameters, this value is inclusive.
descriptiondescription НетNo Описание параметра, отображаемого для пользователей на портале.Description of the parameter that is displayed to users through the portal. Дополнительные сведения см. в разделе комментариев в шаблонах.For more information, see Comments in templates.

Определение и применение параметраDefine and use a parameter

Следующий пример демонстрирует определение простого параметра.The following example shows a simple parameter definition. Здесь указывается имя параметра и тип его значения (строковое значение).It defines the name of the parameter, and specifies that it takes a string value. Параметр принимает только те значения, которые имеют смысл для его назначения.The parameter only accepts values that make sense for its intended use. Также указано значение по умолчанию, которое используется, если во время развертывания значение параметра не указано.It specifies a default value when no value is provided during deployment. И наконец, в определении параметра есть описание его назначения.Finally, the parameter includes a description of its use.

"parameters": {
  "storageSKU": {
    "type": "string",
    "allowedValues": [
      "Standard_LRS",
      "Standard_ZRS",
      "Standard_GRS",
      "Standard_RAGRS",
      "Premium_LRS"
    ],
    "defaultValue": "Standard_LRS",
    "metadata": {
      "description": "The type of replication to use for the storage account."
    }
  }   
}

Ссылка на значение параметра указывается в шаблоне следующим образом:In the template, you reference the value for the parameter with the following syntax:

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "sku": {
      "name": "[parameters('storageSKU')]"
    },
    ...
  }
]

Использование функций шаблонов с параметрамиTemplate functions with parameters

Чтобы определить значение по умолчанию для параметра, можно использовать большинство функций шаблонов.When specifying the default value for a parameter, you can use most template functions. Также для создания значения по умолчанию можно использовать значение другого параметра.You can use another parameter value to build a default value. Следующий шаблон демонстрирует применение функций в значениях по умолчанию:The following template demonstrates the use of functions in the default value:

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]",
    "metadata": {
      "description": "The site name. To use the default value, do not specify a new value."
    }
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]",
    "metadata": {
      "description": "The host name. To use the default value, do not specify a new value."
    }
  }
}

В разделе параметров недоступна функция reference.You can't use the reference function in the parameters section. Параметры вычисляются до развертывания, поэтому функция reference не может получить состояние выполнения ресурса.Parameters are evaluated before deployment so the reference function can't get the runtime state of a resource.

Объекты в качестве параметровObjects as parameters

Чтобы структурировать связанные друг с другом значения, их можно передать в виде объекта.It can be easier to organize related values by passing them in as an object. Что не менее важно, этот подход сокращает число параметров в шаблоне.This approach also reduces the number of parameters in the template.

Задайте в шаблоне параметр обычным образом, а во время развертывания передайте для этого параметра не одно значение, а объект в формате JSON.Define the parameter in your template and specify a JSON object instead of a single value during deployment.

"parameters": {
  "VNetSettings": {
    "type": "object",
    "defaultValue": {
      "name": "VNet1",
      "location": "eastus",
      "addressPrefixes": [
        {
          "name": "firstPrefix",
          "addressPrefix": "10.0.0.0/22"
        }
      ],
      "subnets": [
        {
          "name": "firstSubnet",
          "addressPrefix": "10.0.0.0/24"
        },
        {
          "name": "secondSubnet",
          "addressPrefix": "10.0.1.0/24"
        }
      ]
    }
  }
},

Тогда вы сможете ссылаться в шаблоне на вложенные свойства этого параметра с помощью оператора-точки.Then, reference the subproperties of the parameter by using the dot operator.

"resources": [
  {
    "apiVersion": "2015-06-15",
    "type": "Microsoft.Network/virtualNetworks",
    "name": "[parameters('VNetSettings').name]",
    "location": "[parameters('VNetSettings').location]",
    "properties": {
      "addressSpace":{
        "addressPrefixes": [
          "[parameters('VNetSettings').addressPrefixes[0].addressPrefix]"
        ]
      },
      "subnets":[
        {
          "name":"[parameters('VNetSettings').subnets[0].name]",
          "properties": {
            "addressPrefix": "[parameters('VNetSettings').subnets[0].addressPrefix]"
          }
        },
        {
          "name":"[parameters('VNetSettings').subnets[1].name]",
          "properties": {
            "addressPrefix": "[parameters('VNetSettings').subnets[1].addressPrefix]"
          }
        }
      ]
    }
  }
]

Примеры шаблонов параметровParameter example templates

Эти примеры шаблонов демонстрируют разные сценарии использования параметров.These example templates demonstrate some scenarios for using parameters. Разверните их и изучите, как обрабатываются параметры в различных сценариях.Deploy them to test how parameters are handled in different scenarios.

ШаблонTemplate ОписаниеDescription
Использование параметров с функциями для определения значений по умолчаниюparameters with functions for default values Демонстрирует, как можно применить функции шаблонов при определении значений по умолчанию для параметров.Demonstrates how to use template functions when defining default values for parameters. Шаблон не развертывает ресурсы.The template doesn't deploy any resources. Он только создает значения параметров и возвращает их.It constructs parameter values and returns those values.
Объект параметровparameter object Демонстрирует использование объекта в качестве параметра.Demonstrates using an object for a parameter. Шаблон не развертывает ресурсы.The template doesn't deploy any resources. Он только создает значения параметров и возвращает их.It constructs parameter values and returns those values.

ПеременныеVariables

В разделе переменных вы создаете значения, которые можно использовать в разных частях шаблона.In the variables section, you construct values that can be used throughout your template. Переменные определять не обязательно, однако они часто упрощают шаблон, снижая число сложных выражений.You don't need to define variables, but they often simplify your template by reducing complex expressions.

Доступные определенияAvailable definitions

В следующем примере показаны доступные параметры для определения переменной.The following example shows the available options for defining a variable:

"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 для создания нескольких значений для переменной см. в разделе Переменная iteration.For information about using copy to create several values for a variable, see Variable iteration.

Определение и применение переменнойDefine and use a variable

В приведенном ниже примере показано определение переменной.The following example shows a variable definition. В нем создается строковое значение имени учетной записи хранения.It creates a string value for a storage account name. Он использует несколько функций шаблона для получения значения параметра и объединяет его в уникальную строку.It uses several template functions to get a parameter value, and concatenates it to a unique string.

"variables": {
  "storageName": "[concat(toLower(parameters('storageNamePrefix')), uniqueString(resourceGroup().id))]"
},

Переменная используется при определении ресурса.You use the variable when defining the resource.

"resources": [
  {
    "name": "[variables('storageName')]",
    "type": "Microsoft.Storage/storageAccounts",
    ...

Переменные конфигурацииConfiguration variables

С помощью сложных типов JSON можно определить связанные значения для среды.You can use complex JSON types to define related values for an environment.

"variables": {
  "environmentSettings": {
    "test": {
      "instanceSize": "Small",
      "instanceCount": 1
    },
    "prod": {
      "instanceSize": "Large",
      "instanceCount": 4
    }
  }
},

В параметрах следует создать значение, указывающее, какие значения конфигурации будут использоваться.In parameters, you create a value that indicates which configuration values to use.

"parameters": {
  "environmentName": {
    "type": "string",
    "allowedValues": [
      "test",
      "prod"
    ]
  }
},

Получить текущие настройки можно следующим образом:You retrieve the current settings with:

"[variables('environmentSettings')[parameters('environmentName')].instanceSize]"

Примеры шаблонов переменныхVariable example templates

Эти примеры шаблонов демонстрируют разные сценарии использования переменных.These example templates demonstrate some scenarios for using variables. Разверните их и изучите, как обрабатываются переменные в различных сценариях.Deploy them to test how variables are handled in different scenarios.

ШаблонTemplate ОписаниеDescription
variable definitionsvariable definitions Демонстрирует различные типы переменных.Demonstrates the different types of variables. Шаблон не развертывает ресурсы.The template doesn't deploy any resources. При его помощи только создаются и возвращаются значения переменных.It constructs variable values and returns those values.
configuration variableconfiguration variable Демонстрирует использование переменной, определяющей значения конфигурации.Demonstrates the use of a variable that defines configuration values. Шаблон не развертывает ресурсы.The template doesn't deploy any resources. При его помощи только создаются и возвращаются значения переменных.It constructs variable values and returns those values.
network security rules и parameter filenetwork security rules and parameter file Отвечает за создание массива в правильном формате для назначения правил безопасности в группе безопасности сети.Constructs an array in the correct format for assigning security rules to a network security group.

ФункцииFunctions

В шаблоне можно создать свои собственные функции.Within your template, you can create your own functions. Эти функции доступны для использования в шаблоне.These functions are available for use in your template. Как правило, определяется сложное выражение, которое вы не хотите повторять в шаблоне.Typically, you define complicated expression that you don't want to repeat throughout your template. Создаются определяемые пользователем функции на основе выражений и функции, которые поддерживаются в шаблонах.You create the user-defined functions from expressions and functions that are supported in templates.

При определении пользовательской функции есть несколько ограничений:When defining a user function, there are some restrictions:

  • Функция не может обращаться к переменным.The function can't access variables.
  • Функция может использовать только параметры, определенные в самой функции.The function can only use parameters that are defined in the function. При использовании функции Parameters в определяемой пользователем функции вы можете использовать только параметры этой функции.When you use the parameters function within a user-defined function, you're restricted to the parameters for that function.
  • Функция не может вызывать другие функции, определяемые пользователем.The function can't call other user-defined functions.
  • Для функции нельзя использовать ссылочную функцию.The function can't use the reference function.
  • Для параметров этой функции нельзя задавать значения по умолчанию.Parameters for the function can't have default values.

Для функции требуется значение пространства имен, чтобы избежать конфликтов именования с функциями шаблона.Your functions require a namespace value to avoid naming conflicts with template functions. В следующем примере показана функция, которая возвращает имя учетной записи хранения:The following example shows a function that returns a storage account name:

"functions": [
  {
    "namespace": "contoso",
    "members": {
      "uniqueName": {
        "parameters": [
          {
            "name": "namePrefix",
            "type": "string"
          }
        ],
        "output": {
          "type": "string",
          "value": "[concat(toLower(parameters('namePrefix')), uniqueString(resourceGroup().id))]"
        }
      }
    }
  }
],

Вызов функции выполняется с помощью следующего кода:You call the function with:

"resources": [
  {
    "name": "[contoso.uniqueName(parameters('storageNamePrefix'))]",
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2016-01-01",
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "location": "South Central US",
    "tags": {},
    "properties": {}
  }
]

РесурсыResources

В разделе resources определяются ресурсы, которые развертываются или обновляются.In the resources section, you define the resources that are deployed or updated.

Доступные свойстваAvailable properties

Ресурсы определяются с помощью следующей структуры:You define resources with the following structure:

"resources": [
  {
      "condition": "<true-to-deploy-this-resource>",
      "apiVersion": "<api-version-of-resource>",
      "type": "<resource-provider-namespace/resource-type-name>",
      "name": "<name-of-the-resource>",
      "location": "<location-of-resource>",
      "tags": {
          "<tag-name1>": "<tag-value1>",
          "<tag-name2>": "<tag-value2>"
      },
      "comments": "<your-reference-notes>",
      "copy": {
          "name": "<name-of-copy-loop>",
          "count": <number-of-iterations>,
          "mode": "<serial-or-parallel>",
          "batchSize": <number-to-deploy-serially>
      },
      "dependsOn": [
          "<array-of-related-resource-names>"
      ],
      "properties": {
          "<settings-for-the-resource>",
          "copy": [
              {
                  "name": ,
                  "count": ,
                  "input": {}
              }
          ]
      },
      "sku": {
          "name": "<sku-name>",
          "tier": "<sku-tier>",
          "size": "<sku-size>",
          "family": "<sku-family>",
          "capacity": <sku-capacity>
      },
      "kind": "<type-of-resource>",
      "plan": {
          "name": "<plan-name>",
          "promotionCode": "<plan-promotion-code>",
          "publisher": "<plan-publisher>",
          "product": "<plan-product>",
          "version": "<plan-version>"
      },
      "resources": [
          "<array-of-child-resources>"
      ]
  }
]
Имя элементаElement name Обязательное значениеRequired ОписаниеDescription
условиеcondition НетNo Логическое значение, указывающее, будет ли подготавливаться ресурс во время этого развертывания.Boolean value that indicates whether the resource will be provisioned during this deployment. Если установлено значение true, при развертывании создается ресурс.When true, the resource is created during deployment. Если установлено значение false, при развертывании ресурс не создается.When false, the resource is skipped for this deployment. См. условие.See condition.
apiVersionapiVersion ДаYes Версия REST API, которая будет использована для создания ресурса.Version of the REST API to use for creating the resource. Чтобы определить доступные значения, см. раздел Справочникпо шаблону.To determine available values, see template reference.
typetype ДаYes Тип ресурса.Type of the resource. Это значение представляет собой сочетание пространства имен поставщика ресурсов и типа ресурса (например, Microsoft.Storage/storageAccounts).This value is a combination of the namespace of the resource provider and the resource type (such as Microsoft.Storage/storageAccounts). Чтобы определить доступные значения, см. раздел Справочникпо шаблону.To determine available values, see template reference. Для дочернего ресурса формат типа зависит от того, является ли он вложенным в родительский ресурс или определен за пределами родительского ресурса.For a child resource, the format of the type depends on whether it's nested within the parent resource or defined outside of the parent resource. См. раздел Задание имени и типа для дочерних ресурсов.See Set name and type for child resources.
namename ДаYes Имя ресурса.Name of the resource. Имя должно соответствовать ограничениям компонентов URI, определенным в RFC3986.The name must follow URI component restrictions defined in RFC3986. Кроме того, службы Azure, которые предоставляют имя ресурса внешним пользователям, проверяют это имя, чтобы убедиться, что это не попытка подделки другого удостоверения.In addition, Azure services that expose the resource name to outside parties validate the name to make sure it isn't an attempt to spoof another identity. Для дочернего ресурса формат имени зависит от того, является ли он вложенным в родительский ресурс или определен за пределами родительского ресурса.For a child resource, the format of the name depends on whether it's nested within the parent resource or defined outside of the parent resource. См. раздел Задание имени и типа для дочерних ресурсов.See Set name and type for child resources.
расположениеlocation VariesVaries Поддерживаемые географические расположения указанного ресурса.Supported geo-locations of the provided resource. Вы можете выбрать любое из доступных расположений. Но обычно имеет смысл выбрать расположение, которое находится недалеко от пользователей.You can select any of the available locations, but typically it makes sense to pick one that is close to your users. Кроме того, целесообразно разместить взаимодействующие ресурсы в одном регионе.Usually, it also makes sense to place resources that interact with each other in the same region. Большинству типов ресурсов нужно расположение, но некоторым типам (например, назначению роли) оно не требуется.Most resource types require a location, but some types (such as a role assignment) don't require a location.
тегиtags НетNo Теги, связанные с ресурсом.Tags that are associated with the resource. Примените теги, чтобы логически организовать ресурсы в подписке.Apply tags to logically organize resources across your subscription.
комментарииcomments НетNo Заметки по ресурсам в шаблоне.Your notes for documenting the resources in your template. Дополнительные сведения см. в разделе комментариев в шаблонах.For more information, see Comments in templates.
копироватьcopy НетNo Количество создаваемых ресурсов (если нужно несколько экземпляров).If more than one instance is needed, the number of resources to create. Параллельный режим используется по умолчанию.The default mode is parallel. Используйте последовательный режим, если вы не хотите развертывать все ресурсы одновременно.Specify serial mode when you don't want all or the resources to deploy at the same time. Дополнительные сведения см. в статье Создание нескольких экземпляров ресурсов в Azure Resource Manager.For more information, see Create several instances of resources in Azure Resource Manager.
dependsOndependsOn НетNo Ресурсы, которые должны быть развернуты перед развертыванием этого ресурса.Resources that must be deployed before this resource is deployed. Resource Manager оценивает зависимости между ресурсами и развертывает эти ресурсы в правильном порядке.Resource Manager evaluates the dependencies between resources and deploys them in the correct order. Если ресурсы не зависят друг от друга, они развертываются параллельно.When resources aren't dependent on each other, they're deployed in parallel. Значение может представлять собой разделенный запятыми список имен ресурсов или уникальных идентификаторов ресурсов.The value can be a comma-separated list of a resource names or resource unique identifiers. Выводится только список ресурсов, развертываемых в этом шаблоне.Only list resources that are deployed in this template. Ресурсы, которые не определены в этом шаблоне, уже должны существовать.Resources that aren't defined in this template must already exist. Избегайте добавления ненужных зависимостей, так как это может замедлить развертывание и привести к созданию циклических зависимостей.Avoid adding unnecessary dependencies as they can slow your deployment and create circular dependencies. Рекомендации по настройке зависимостей см. в статье Определение зависимостей в шаблонах диспетчера ресурсов Azure.For guidance on setting dependencies, see Defining dependencies in Azure Resource Manager templates.
свойстваproperties НетNo Параметры конфигурации ресурса.Resource-specific configuration settings. Значения свойств совпадают со значениями, указываемыми в тексте запроса для операции REST API (метод PUT) для создания ресурса.The values for the properties are the same as the values you provide in the request body for the REST API operation (PUT method) to create the resource. Кроме того, можно указать массив copy для создания нескольких экземпляров свойства.You can also specify a copy array to create several instances of a property. Чтобы определить доступные значения, см. раздел Справочникпо шаблону.To determine available values, see template reference.
skusku НетNo В некоторых ресурсах допускается использовать значения, определяющие номер SKU для развертывания.Some resources allow values that define the SKU to deploy. Например, можно указать тип избыточности для учетной записи хранения.For example, you can specify the type of redundancy for a storage account.
kindkind НетNo В некоторых ресурсах допускается использовать значение, которое определяет тип развертываемого ресурса.Some resources allow a value that defines the type of resource you deploy. Например, можно указать в качестве типа создаваемой базы данных Cosmos DB.For example, you can specify the type of Cosmos DB to create.
Планplan НетNo В некоторых ресурсах допускается использовать значения, определяющие номер плана для развертывания.Some resources allow values that define the plan to deploy. Например, можно указать образ Marketplace для виртуальной машины.For example, you can specify the marketplace image for a virtual machine.
ресурсыresources НетNo Дочерние ресурсы, которые зависят от определяемого ресурса.Child resources that depend on the resource being defined. Следует указать только те типы ресурсов, которые разрешены в схеме родительского ресурса.Only provide resource types that are permitted by the schema of the parent resource. Зависимость от родительского ресурса не подразумевается.Dependency on the parent resource isn't implied. Ее необходимо определить явным образом.You must explicitly define that dependency. См. раздел Задание имени и типа для дочерних ресурсов.See Set name and type for child resources.

УсловиеCondition

Если во время развертывания необходимо решить, следует ли создать ресурс, используйте condition элемент.When you must decide during deployment whether to create a resource, use the condition element. Этот элемент возвращает значение True или False.The value for this element resolves to true or false. Если значение true, ресурс создан.When the value is true, the resource is created. Если значение false, ресурс не создан.When the value is false, the resource isn't created. Значение может применяться только ко всему ресурсу.The value can only be applied to the whole resource.

Как правило, это значение применяется для создания нового ресурса или использования существующего.Typically, you use this value when you want to create a new resource or use an existing one. Например, чтобы указать, развернута ли новая учетная запись хранения или используется ли имеющаяся, сделайте следующее:For example, to specify whether a new storage account is deployed or an existing storage account is used, use:

{
    "condition": "[equals(parameters('newOrExisting'),'new')]",
    "type": "Microsoft.Storage/storageAccounts",
    "name": "[variables('storageAccountName')]",
    "apiVersion": "2017-06-01",
    "location": "[resourceGroup().location]",
    "sku": {
        "name": "[variables('storageAccountType')]"
    },
    "kind": "Storage",
    "properties": {}
}

Полный пример шаблона с использованием элемента condition см. по адресу VM with a new or existing Virtual Network, Storage, and Public IP (Виртуальная машина с новой или существующей виртуальной сетью, хранилищем и общедоступным IP-адресом).For a complete example template that uses the condition element, see VM with a new or existing Virtual Network, Storage, and Public IP.

Если вы используете функцию ссылки или списка с ресурсом, который условно развернут, функция вычисляется, даже если ресурс не развернут.If you use a reference or list function with a resource that is conditionally deployed, the function is evaluated even if the resource isn't deployed. Если функция ссылается на несуществующий ресурс, возникает ошибка.You get an error if the function refers to a resource that doesn't exist. Используйте функцию If , чтобы убедиться, что функция вычисляется только для условий при развертывании ресурса.Use the if function to make sure the function is only evaluated for conditions when the resource is deployed. См. функцию if для примера шаблона, который использует оператор If и ссылку с условно развернутым ресурсом.See the if function for a sample template that uses if and reference with a conditionally deployed resource.

Имена ресурсовResource names

Обычно в Resource Manager вы работаете с именами ресурсов трех типов:Generally, you work with three types of resource names in Resource Manager:

  • имена ресурсов, которые должны быть уникальными;Resource names that must be unique.
  • имена ресурсов, которые могут не быть уникальными, но должны помогать в определении ресурса;Resource names that aren't required to be unique, but you choose to provide a name that can help you identify the resource.
  • имена ресурсов, которые могут быть универсальными.Resource names that can be generic.

Укажите уникальное имя ресурса для любого типа ресурса, имеющего конечную точку доступа к данным.Provide a unique resource name for any resource type that has a data access endpoint. Ниже приведено несколько распространенных типов ресурсов, для которых требуются уникальные имена:Some common resource types that require a unique name include:

  • служба хранилища Azure1;Azure Storage1
  • веб-приложения службы приложений Azure;Web Apps feature of Azure App Service
  • SQL ServerSQL Server
  • Хранилище Azure Key VaultAzure Key Vault
  • Кэш Azure для RedisAzure Cache for Redis
  • Пакетная служба AzureAzure Batch
  • Диспетчер трафика AzureAzure Traffic Manager
  • Поиск AzureAzure Search
  • Azure HDInsightAzure HDInsight

1 Имена учетных записей хранения также должны содержать до 24 знаков в нижнем регистре без дефисов.1 Storage account names also must be lowercase, 24 characters or less, and not have any hyphens.

При задании имени можно вручную создать уникальное имя или использовать для этого функцию uniqueString().When setting the name, you can either manually create a unique name or use the uniqueString() function to generate a name. Вам также может потребоваться добавить префикс или суффикс к результату uniqueString.You also might want to add a prefix or suffix to the uniqueString result. Измените уникальное имя, чтобы было проще определить тип ресурса по его имени.Modifying the unique name can help you more easily identify the resource type from the name. Например, можно создать уникальное имя учетной записи хранения с помощью следующей переменной:For example, you can generate a unique name for a storage account by using the following variable:

"variables": {
  "storageAccountName": "[concat(uniqueString(resourceGroup().id),'storage')]"
}

Для некоторых типов ресурсов может потребоваться указать имя для идентификации, но имя не обязательно должно быть уникальным.For some resource types, you might want to provide a name for identification, but the name doesn't have to be unique. Для этих типов ресурсов укажите имя, описывающее его использование или характеристики.For these resource types, provide a name that describes it use or characteristics.

"parameters": {
  "vmName": { 
    "type": "string",
    "defaultValue": "demoLinuxVM",
    "metadata": {
      "description": "The name of the VM to create."
    }
  }
}

Для типов ресурсов, доступ к которым осуществляется в основном через другой ресурс, можно использовать универсальное имя , жестко запрограммированное в шаблоне.For resource types that you mostly access through a different resource, you can use a generic name that is hard-coded in the template. Например, можно задать стандартное универсальное имя для правил брандмауэра на SQL Server:For example, you can set a standard, generic name for firewall rules on a SQL server:

{
  "type": "firewallrules",
  "name": "AllowAllWindowsAzureIps",
  ...
}

Расположение ресурсаResource location

При развертывании шаблона вам нужно указать расположение для каждого ресурса.When deploying a template, you must provide a location for each resource. Различные типы ресурсов поддерживаются в разных расположениях.Different resource types are supported in different locations. Сведения о получении поддерживаемых расположений для типа ресурса см. в статье Поставщики и типы ресурсов.To get the supported locations for a resource type, see Azure resource providers and types.

Используйте параметр для указания расположения ресурсов и задайте значения по умолчанию для resourceGroup().location.Use a parameter to specify the location for resources, and set the default value to resourceGroup().location.

В следующем примере показана учетная запись хранения, которая развертывается в расположении, указанном как параметр:The following example shows a storage account that is deployed to a location specified as a parameter:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ],
      "metadata": {
        "description": "Storage Account type"
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    }
  },
  "variables": {
    "storageAccountName": "[concat('storage', uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "apiVersion": "2018-07-01",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    }
  }
}

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

В разделе выходных данных следует указать значения, которые возвращаются после развертывания.In the Outputs section, you specify values that are returned from deployment. Как правило, значения возвращаются из ресурсов, которые были развернуты.Typically, you return values from resources that were deployed.

Доступные свойстваAvailable properties

В следующем примере показана структура определения выходных данных:The following example shows the structure of an output definition:

"outputs": {
  "<outputName>" : {
    "condition": "<boolean-value-whether-to-output-value>",
    "type" : "<type-of-output-value>",
    "value": "<output-value-expression>"
  }
}
Имя элементаElement name Обязательное значениеRequired ОписаниеDescription
outputNameoutputName ДаYes Имя выходного значения.Name of the output value. Должно быть допустимым идентификатором JavaScript.Must be a valid JavaScript identifier.
условиеcondition НетNo Логическое значение, которое указывает, возвращается ли выходное значение.Boolean value that indicates whether this output value is returned. Если установлено значение true, то при развертывании значение является частью выходных данных.When true, the value is included in the output for the deployment. Если установлено значение false, при развертывании выходное значение не создается.When false, the output value is skipped for this deployment. Когда не задано, по умолчанию используется значение true.When not specified, the default value is true.
typetype ДаYes Тип выходного значения.Type of the output value. Выходные значения поддерживает те же типы, что и входные параметры шаблона.Output values support the same types as template input parameters. Если для типа выходных данных указано значение SecureString , оно не отображается в журнале развертывания и не может быть извлечено из другого шаблона.If you specify securestring for the output type, the value isn't displayed in the deployment history and can't be retrieved from another template. Чтобы использовать значение секрета в нескольких шаблонах, сохраните секрет в Key Vault и сослаться на секрет в файле параметров.To use a secret value in more than one template, store the secret in a Key Vault and reference the secret in the parameter file. Дополнительные сведения см. в статье Использование Azure Key Vault для передачи защищенного значения параметра во время развертывания.For more information, see Use Azure Key Vault to pass secure parameter value during deployment.
valuevalue ДаYes Выражение на языке шаблона, которое вычисляется и возвращается в качестве выходного значения.Template language expression that is evaluated and returned as output value.

Определение и использование выходных значенийDefine and use output values

В следующем примере показано, как вернуть идентификатор ресурса для общедоступного IP-адреса.The following example shows how to return the resource ID for a public IP address:

"outputs": {
  "resourceID": {
    "type": "string",
    "value": "[resourceId('Microsoft.Network/publicIPAddresses', parameters('publicIPAddresses_name'))]"
  }
}

В следующем примере показано, как условно вернуть идентификатор ресурса для общедоступного IP-адреса на основе развертывания нового.The next example shows how to conditionally return the resource ID for a public IP address based on whether a new one was deployed:

"outputs": {
  "resourceID": {
    "condition": "[equals(parameters('publicIpNewOrExisting'), 'new')]",
    "type": "string",
    "value": "[resourceId('Microsoft.Network/publicIPAddresses', parameters('publicIPAddresses_name'))]"
  }
}

Простой пример условного вывода см. в разделе шаблон условного вывода.For a simple example of conditional output, see conditional output template.

После развертывания вы можете извлечь значение с помощью скрипта.After the deployment, you can retrieve the value with script. Для PowerShell используйте команду:For PowerShell, use:

(Get-AzResourceGroupDeployment -ResourceGroupName <resource-group-name> -Name <deployment-name>).Outputs.resourceID.value

Для интерфейса командной строки Azure:For Azure CLI, use:

az group deployment show -g <resource-group-name> -n <deployment-name> --query properties.outputs.resourceID.value

Вы можете получить выходное значение из связанного шаблона с помощью функции reference.You can retrieve the output value from a linked template by using the reference function. Чтобы получить выходные значения из связанного шаблона, извлеките значение свойства с синтаксисом, например: "[reference('deploymentName').outputs.propertyName.value]".To get an output value from a linked template, retrieve the property value with syntax like: "[reference('deploymentName').outputs.propertyName.value]".

При получении выходного свойства из связанного шаблона имя свойства не должно содержать тире.When getting an output property from a linked template, the property name can't include a dash.

В следующем примере показано, как задать IP-адрес в подсистеме балансировки нагрузки, извлекая значение из связанного шаблона.The following example shows how to set the IP address on a load balancer by retrieving a value from a linked template.

"publicIPAddress": {
  "id": "[reference('linkedTemplate').outputs.resourceID.value]"
}

Вы не можете использовать функцию reference в разделе выходных данных вложенного шаблона.You can't use the reference function in the outputs section of a nested template. Чтобы извлечь значения для развернутого ресурса во вложенном шаблоне, преобразуйте этот шаблон в связанный.To return the values for a deployed resource in a nested template, convert your nested template to a linked template.

Примеры шаблонов выходных данныхOutput example templates

ШаблонTemplate ОписаниеDescription
Копирование переменныхCopy variables Позволяет создать сложные переменные и вывести эти значения.Creates complex variables and outputs those values. Не используется для развертывания ресурсов.Doesn't deploy any resources.
Общедоступный IP-адресPublic IP address Позволяет создать общедоступный IP-адрес и вывести идентификатор ресурса.Creates a public IP address and outputs the resource ID.
Подсистема балансировки нагрузкиLoad balancer Позволяет создать ссылку на предыдущий шаблон.Links to the preceding template. При создании подсистемы балансировки нагрузки использует идентификатор ресурса в выходных данных.Uses the resource ID in the output when creating the load balancer.

Комментарии и метаданныеComments and metadata

Есть несколько вариантов добавления комментариев и метаданных к шаблону.You have a few options for adding comments and metadata to your template.

Вы можете добавить объект metadata практически в любом месте шаблона.You can add a metadata object almost anywhere in your template. Resource Manager игнорирует объект, но ваш редактор JSON может предупредить вас, что свойство недопустимо.Resource Manager ignores the object, but your JSON editor may warn you that the property isn't valid. Определите необходимые свойства в объекте.In the object, define the properties you need.

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

В разделе параметров добавьте объект metadata со свойством description.For parameters, add a metadata object with a description property.

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

При развертывании шаблона через портал текст, который вы указываете в описании, автоматически используется в качестве подсказки для этого параметра.When deploying the template through the portal, the text you provide in the description is automatically used as a tip for that parameter.

Отображается подсказка для параметра

В разделе ресурсов добавьте элемент comments или объект метаданных.For resources, add a comments element or a metadata object. В следующем примере показан и элемент комментариев, и объект метаданных.The following example shows both a comments element and a metadata object.

"resources": [
  {
    "comments": "Storage account used to store VM disks",
    "apiVersion": "2018-07-01",
    "type": "Microsoft.Storage/storageAccounts",
    "name": "[concat('storage', uniqueString(resourceGroup().id))]",
    "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": {}
  }
]

В разделе выходных данных добавьте объект метаданных в выходное значение.For outputs, add a metadata object to the output value.

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

Добавить объект метаданных в определяемые пользователем функции невозможно.You can't add a metadata object to user-defined functions.

Для встроенных комментариев можно использовать //, но этот синтаксис поддерживается не во всех инструментах.For inline comments, you can use // but this syntax doesn't work with all tools. Вы не можете использовать интерфейс командной строки Azure для развертывания шаблона со встроенными комментариями,You can't use Azure CLI to deploy the template with inline comments. а также применять редактор шаблонов на портале для работы с шаблонами со встроенными комментариями.And, you can't use the portal template editor to work on templates with inline comments. Если вы добавляете этот стиль комментариев, убедитесь, что используемые инструменты поддерживают встроенные комментарии JSON.If you add this style of comment, be sure the tools you use support inline JSON comments.

{
  "type": "Microsoft.Compute/virtualMachines",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "apiVersion": "2018-10-01",
  "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 вы можете установить языковой режим, поддерживающий JSON-файл с комментариями.In VS Code, you can set the language mode to JSON with comments. В таком случае встроенные комментарии больше не будут помечены как недопустимые.The inline comments are no longer marked as invalid. Чтобы изменить режим:To change the mode:

  1. Откройте раздел выбора языкового режима, нажав клавиши CTRL+K+M.Open language mode selection (Ctrl+K M)

  2. Выберите JSON with Comments (JSON с комментариями).Select JSON with Comments.

    Выбор языкового режима

Краткие руководстваQuickstarts and tutorials

В следующих кратких руководствах вы узнаете, как создавать шаблоны диспетчера ресурсов.Use the following quickstarts and tutorials to learn how to develop resource manager templates:

Эти руководства можно использовать по отдельности или в рамках комплексного изучения основных принципов разработки шаблона Resource Manager.These tutorials can be used individually, or as a series to learn the major Resource Manager template development concepts.

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