解决无效模板错误Resolve errors for invalid template

本文说明如何解决无效模板错误。This article describes how to resolve invalid template errors.

症状Symptom

部署模板时将收到一个指示以下内容的错误:When deploying a template, you receive an error indicating:

Code=InvalidTemplate
Message=<varies>

错误消息取决于错误的类型。The error message depends on the type of error.

原因Cause

此错误可由多种不同类型的错误导致。This error can result from several different types of errors. 它们通常涉及模板中的语法或结构错误。They usually involve a syntax or structural error in the template.

解决方案 1 - 语法错误Solution 1 - syntax error

如果有错误消息指出模板验证失败,则可能是模板中存在语法问题。If you receive an error message that indicates the template failed validation, you may have a syntax problem in your template.

Code=InvalidTemplate
Message=Deployment template validation failed

此错误很容易发生,因为模板表达式可能很复杂。This error is easy to make because template expressions can be intricate. 例如,存储帐户的以下名称分配具有一组方括号、三个函数、三组圆括号、一组单引号和一个属性:For example, the following name assignment for a storage account has one set of brackets, three functions, three sets of parentheses, one set of single quotes, and one property:

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

如果未提供匹配的语法,该模板会生成一个不同于所需的值。If you don't provide the matching syntax, the template produces a value that is different than your intention.

收到此类错误时,请仔细检查表达式语法。When you receive this type of error, carefully review the expression syntax. 考虑使用 Visual StudioVisual Studio Code 等 JSON 编辑器,此类编辑器在出现语法错误时可以发出警告。Consider using a JSON editor like Visual Studio or Visual Studio Code, which can warn you about syntax errors.

解决方案 2 - 段长度不正确Solution 2 - incorrect segment lengths

当资源名称的格式不正确时,会发生另一种模板无效错误。Another invalid template error occurs when the resource name isn't in the correct format.

Code=InvalidTemplate
Message=Deployment template validation failed: 'The template resource {resource-name}'
for type {resource-type} has incorrect segment lengths.

根级别的资源其名称中的段必须比资源类型中的段少一个。A root level resource must have one less segment in the name than in the resource type. 段之间用斜杠隔开。Each segment is differentiated by a slash. 在下面的示例中,类型有两个段,名称有一个段,因此为有效名称。In the following example, the type has two segments and the name has one segment, so it's a valid name.

{
  "type": "Microsoft.Web/serverfarms",
  "name": "myHostingPlanName",
  ...
}

但下一个示例 不是有效名称 ,因为其段数与类型的段数相同。But the next example is not a valid name because it has the same number of segments as the type.

{
  "type": "Microsoft.Web/serverfarms",
  "name": "appPlan/myHostingPlanName",
  ...
}

对于子资源来说,类型和名称的段数必须相同。For child resources, the type and name have the same number of segments. 之所以必须这样,是因为子资源的完整名称和类型包含父名称和类型。This number of segments makes sense because the full name and type for the child includes the parent name and type. 因此,完整名称的段仍比完整类型的段少一个。Therefore, the full name still has one less segment than the full type.

"resources": [
  {
    "type": "Microsoft.KeyVault/vaults",
    "name": "contosokeyvault",
    ...
    "resources": [
      {
        "type": "secrets",
        "name": "appPassword",
        ...
      }
    ]
  }
]

确保段数正确对于 Resource Manager 类型来说可能很困难,这些类型应用到各个资源提供程序。Getting the segments right can be tricky with Resource Manager types that are applied across resource providers. 例如,对网站应用资源锁需要使用包含四个段的类型。For example, applying a resource lock to a web site requires a type with four segments. 因此,该名称包含三个段:Therefore, the name is three segments:

{
  "type": "Microsoft.Web/sites/providers/locks",
  "name": "[concat(variables('siteName'),'/Microsoft.Authorization/MySiteLock')]",
  ...
}

解决方案 3 - 参数无效Solution 3 - parameter is not valid

如果你提供的参数值不是允许值之一,则会收到类似于以下错误的消息:If you provide a parameter value that isn't one of the allowed values, you receive a message similar to the following error:

Code=InvalidTemplate;
Message=Deployment template validation failed: 'The provided value {parameter value}
for the template parameter {parameter name} is not valid. The parameter value is not
part of the allowed values

请仔细检查模板中的允许值,并提供在部署过程中提供这些值之一。Double check the allowed values in the template, and provide one during deployment. 有关允许参数值的详细信息,请参阅 Azure 资源管理器模板的参数部分For more information about allowed parameter values, see Parameters section of Azure Resource Manager templates.

解决方案 4 - 太多目标资源组Solution 4 - Too many target resource groups

你可能在之前的部署中看到此错误,原因是你被限制为一个部署使用 5 个目标资源组。You may see this error in earlier deployments because you were limited to five target resource groups in a single deployment. 在 2020 年 5 月,此限额被上调到了 800 个资源组。In May 2020, that limit was increased to 800 resource groups. 有关详细信息,将 Azure 资源部署到多个订阅或资源组For more information, see Deploy Azure resources to more than one subscription or resource group.

解决方案 5 - 检测到循环依赖项Solution 5 - circular dependency detected

当资源以某种方式互相依赖,导致部署无法启动时,就会出现此错误。You receive this error when resources depend on each other in a way that prevents the deployment from starting. 将多个相互依赖的项组合在一起时,会导致两个或两个以上的资源等待其他资源,而后者也在进行等待。A combination of interdependencies makes two or more resource wait for other resources that are also waiting. 例如,resource1 依赖于 resource3,resource2 依赖于 resource1,resource3 依赖于 resource2。For example, resource1 depends on resource3, resource2 depends on resource1, and resource3 depends on resource2. 通常情况下,删除不必要的依赖项即可解决此问题。You can usually solve this problem by removing unnecessary dependencies.

解决循环依赖项问题的步骤:To solve a circular dependency:

  1. 在模板中找到循环依赖项中标识的资源。In your template, find the resource identified in the circular dependency.
  2. 检查该资源的 dependsOn 属性并使用 reference 函数查看其所依赖的资源。For that resource, examine the dependsOn property and any uses of the reference function to see which resources it depends on.
  3. 检查这些资源,看其依赖于哪些资源。Examine those resources to see which resources they depend on. 顺着这些依赖项检查下去,直到找到依赖于原始资源的资源。Follow the dependencies until you notice a resource that depends on the original resource.
  4. 对于循环依赖项所牵涉的资源,请仔细检查所有使用 dependsOn 属性的情况,确定不需要的依赖项。For the resources involved in the circular dependency, carefully examine all uses of the dependsOn property to identify any dependencies that aren't needed. 删除这些依赖项。Remove those dependencies. 如果不确定某个依赖项是否必需,可尝试删除它。If you're unsure that a dependency is needed, try removing it.
  5. 重新部署模板。Redeploy the template.

部署模板时,删除 dependsOn 属性中的值可能导致错误。Removing values from the dependsOn property can cause errors when you deploy the template. 如果遇到错误,可将依赖项添加回模板。If you get an error, add the dependency back into the template.

如果该方法无法解决循环依赖项问题,可考虑将部分部署逻辑移至子资源(例如扩展或配置设置)中。If that approach doesn't solve the circular dependency, consider moving part of your deployment logic into child resources (such as extensions or configuration settings). 将这些子资源配置为在循环依赖项所牵涉的资源之后部署。Configure those child resources to deploy after the resources involved in the circular dependency. 例如,假设要部署两个虚拟机,但必须在每个虚拟机上设置引用另一虚拟机的属性。For example, suppose you're deploying two virtual machines but you must set properties on each one that refer to the other. 可以按下述顺序部署这两个虚拟机:You can deploy them in the following order:

  1. vm1vm1
  2. vm2vm2
  3. vm1 上的扩展依赖于 vm1 和 vm2。Extension on vm1 depends on vm1 and vm2. 扩展在 vm1 上设置的值是从 vm2 获取的。The extension sets values on vm1 that it gets from vm2.
  4. vm2 上的扩展依赖于 vm1 和 vm2。Extension on vm2 depends on vm1 and vm2. 扩展在 vm2 上设置的值是从 vm1 获取的。The extension sets values on vm2 that it gets from vm1.

同一方法适用于应用服务应用。The same approach works for App Service apps. 可以考虑将配置值移到应用资源的子资源中。Consider moving configuration values into a child resource of the app resource. 可以按下述顺序部署两个 Web 应用:You can deploy two web apps in the following order:

  1. webapp1webapp1
  2. webapp2webapp2
  3. webapp1 的配置依赖于 webapp1 和 webapp2。config for webapp1 depends on webapp1 and webapp2. 它包含应用设置,其值来自 webapp2。It contains app settings with values from webapp2.
  4. webapp2 的配置依赖于 webapp1 和 webapp2。config for webapp2 depends on webapp1 and webapp2. 它包含应用设置,其值来自 webapp1。It contains app settings with values from webapp1.