您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

了解 Azure 资源管理器模板的结构和语法Understand the structure and syntax of Azure Resource Manager Templates

本文介绍 Azure 资源管理器模板的结构。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. 有关创建模板的分步教程,请参阅创建第一个 Azure 资源管理器模板For a step-by-step tutorial on creating a template, see Create your first Azure Resource Manager template.

模板格式Template format

使用最简单的结构时,模板有以下元素:In its simplest structure, a template has the following elements:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "",
    "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. 使用上一示例中所示的 URL。Use the URL shown in the preceding example.
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.
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.
资源resources Yes 已在资源组中部署或更新的资源类型。Resource types that are deployed or updated in a resource group.
outputsoutputs No 部署后返回的值。Values that are returned after deployment.

每个元素均有可设置的属性。Each element has properties you can set. 下例显示一个模板的完整语法:The following example shows the full syntax for a template:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "",
    "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>" 
            }
        }
    },
    "variables": {
        "<variable-name>": "<variable-value>",
        "<variable-object-name>": {
            <variable-complex-type-value>
        },
        "<variable-object-name>": {
            "copy": [
                {
                    "name": "<name-of-array-property>",
                    "count": <number-of-iterations>,
                    "input": {
                        <properties-to-repeat>
                    }
                }
            ]
        },
        "copy": [
            {
                "name": "<variable-array-name>",
                "count": <number-of-iterations>,
                "input": {
                    <properties-to-repeat>
                }
            }
        ]
    },
    "functions": [
      {
        "namespace": "<namespace-for-your-function>",
        "members": {
          "<function-name>": {
            "parameters": [
              {
                "name": "<parameter-name>",
                "type": "<type-of-parameter-value>"
              }
            ],
            "output": {
              "type": "<type-of-output-value>",
              "value": "<function-expression>"
            }
          }
        }
      }
    ],
    "resources": [
      {
          "condition": "<boolean-value-whether-to-deploy>",
          "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": {}
                  }
              ]
          },
          "resources": [
              "<array-of-child-resources>"
          ]
      }
    ],
    "outputs": {
        "<outputName>" : {
            "type" : "<type-of-output-value>",
            "value": "<output-value-expression>"
        }
    }
}

本文稍后将更详细地介绍模板的各个节。This article describes the sections of the template in greater detail.

语法Syntax

模板的基本语法为 JSON。The basic syntax of the template is JSON. 但是,表达式和函数扩展了模板中可用的 JSON 值。However, expressions and functions extend the JSON values available within the template. 表达式在 JSON 字符串文本中编写,其中第一个和最后一个字符分别是 [] 括号。Expressions are written within JSON string literals whose first and last characters are the brackets: [ and ], respectively. 部署模板时会计算表达式的值。The value of the expression is evaluated when the template is deployed. 尽管编写为字符串文本,但表达式的计算结果可以是不同的 JSON 类型,例如数组或整数,具体取决于实际的表达式。While written as a string literal, the result of evaluating the expression can be of a different JSON type, such as an array or integer, depending on the actual expression. 要使用一个括号 [ 在开头括住文本字符串但不将其解释为表达式,请额外添加一个括号,使字符串以 [[ 开头。To have a literal string start with a bracket [, but not have it interpreted as an expression, add an extra bracket to start the string with [[.

通常,会将表达式与函数一起使用,以执行用于配置部署的操作。Typically, you use expressions with functions to perform operations for configuring the deployment. 如同在 JavaScript 中一样,函数调用的格式为 functionName(arg1,arg2,arg3)Just like in JavaScript, function calls are formatted as functionName(arg1,arg2,arg3). 使用点和 [index] 运算符引用属性。You reference properties by using the dot and [index] operators.

以下示例演示如何在构造值时使用一些函数:The following example shows how to use several functions when constructing a value:

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

有关模板函数的完整列表,请参阅 Azure 资源管理器模板函数For the full list of template functions, see Azure Resource Manager template functions.

parametersParameters

在模板的 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.

以下示例展示了一个简单的参数定义:The following example shows a simple parameter definition:

"parameters": {
  "siteNamePrefix": {
    "type": "string",
    "metadata": {
      "description": "The name prefix of the web app that you wish to create."
    }
  },
},

有关定义参数的信息,请参阅 Azure 资源管理器模板的参数部分For information about defining parameters, see Parameters section of Azure Resource Manager templates.

变量Variables

在 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.

以下示例展示了一个简单的变量定义:The following example shows a simple variable definition:

"variables": {
  "webSiteName": "[concat(parameters('siteNamePrefix'), uniqueString(resourceGroup().id))]",
},

有关定义变量的信息,请参阅 Azure 资源管理器模板的变量部分For information about defining variables, see Variables section of Azure Resource Manager templates.

函数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'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. 本部分可能比较复杂,因为必须了解所部署类型才能提供正确的值。This section can get complicated because you must understand the types you're deploying to provide the right values.

"resources": [
  {
    "apiVersion": "2016-08-01",
    "name": "[variables('webSiteName')]",
    "type": "Microsoft.Web/sites",
    "location": "[resourceGroup().location]",
    "properties": {
      "serverFarmId": "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.Web/serverFarms/<plan-name>"
    }
  }
],

有关详细信息,请参阅 Azure 资源管理器模板的资源部分For more information, see Resources section of Azure Resource Manager templates.

OutputsOutputs

在 Outputs 节中,可以指定从部署返回的值。In the Outputs section, you specify values that are returned from deployment. 例如,可能会返回用于访问已部署资源的 URI。For example, you could return the URI to access a deployed resource.

"outputs": {
  "newHostName": {
    "type": "string",
    "value": "[reference(variables('webSiteName')).defaultHostName]"
  }
}

有关详细信息,请参阅 Azure 资源管理器模板的输出部分For more information, see Outputs section of Azure Resource Manager templates.

模板限制Template limits

将模板大小限制为 1 MB 以内,每个参数文件大小限制为 64 KB 以内。Limit the size of your template to 1 MB, and each parameter file to 64 KB. 已完成对迭代资源定义、变量值和参数值的扩展后,1 MB 的限制将适用于该模板的最终状态。The 1-MB limit applies to the final state of the template after it has been expanded with iterative resource definitions, and values for variables and parameters.

还将受限于:You're also limited to:

  • 256 个参数256 parameters
  • 256 个变量256 variables
  • 800 个资源(包括副本计数)800 resources (including copy count)
  • 64 个输出值64 output values
  • 模板表达式中 24,576 个字符24,576 characters in a template expression

通过使用嵌套模板,可超出某些模板限制。You can exceed some template limits by using a nested template. 有关详细信息,请参阅部署 Azure 资源时使用链接的模板For more information, see Using linked templates when deploying Azure resources. 若要减少参数、变量或输出的数量,可以将几个值合并为一个对象。To reduce the number of parameters, variables, or outputs, you can combine several values into an object. 有关详细信息,请参阅对象即参数For more information, see Objects as parameters.

后续步骤Next steps