解決無效範本的錯誤

  • 發行項

此文章描述如何針對 Bicep 檔案和 Azure Resource Manager 範本 (ARM 範本) 解決無效範本錯誤。 發生此錯誤的原因有好幾種，例如語法錯誤、參數值無效或循環相依性。

徵兆

部署範本時，您收到錯誤，指出：

Code=InvalidTemplate
Message=<varies>

錯誤訊息取決於錯誤類型。

原因

此錯誤可能起因於數個不同類型的錯誤。 通常涉及範本中的語法或結構錯誤。

解決方案 1：語法錯誤

如果您收到錯誤訊息指出無法驗證範本，則可能是範本中發生語法問題。

Code=InvalidTemplate
Message=Deployment template validation failed

因為範本運算式有許多元素，所以可能會發生語法錯誤。 例如，儲存體帳戶的名稱指派包括成對的單引號或雙引號、大括弧、方括弧和括弧。 運算式也會包含函式，以及貨幣符號、逗號和點等字元。

name: 'storage${uniqueString(resourceGroup().id)}'

當您收到此類型的錯誤時，請檢閱運算式的語法。 若要識別範本錯誤，您可以使用 Visual Studio Code (英文) 搭配最新的 Bicep 延伸模組 (英文) 或 Azure Resource Manager 工具延伸模組 (英文)。

解決方案 2：不正確的區段長度

資源名稱的格式不正確時，就會發生另一種無效範本錯誤。 若要解決該錯誤，請參閱解決名稱和類型不符的錯誤。

解決方案 3：參數無效

您可以在範本中指定參數的允許值。 如果您在部署期間提供的值不是允許的值，則會收到類似下列錯誤的訊息：

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

檢查範本中是否有參數的允許值，並在部署期間使用允許的值。 如需詳細資訊，請參閱 Bicep 或 ARM 範本的允許值。

解決方案 4：目標資源群組數量太多

您可能會在先前的部署中看到此錯誤，因為您在單一部署中的限制為五個目標資源群組。 在 2020 年 5 月，該限制已增加到 800 個資源群組。 如需詳細資訊，請參閱如何針對 Bicep 或 ARM 範本部署至多個資源群組。

解決方案 5：偵測到循環相依性

當資源以防止部署啟動的方式互相相依，您會收到這個錯誤。 只要有相互相依性的組合，就會讓兩個以上資源等候其他也正在等候的資源。 例如，resource1 相依於 resource3、resource2 相依於 resource1，而 resource3 相依於 resource2。 您通常可以移除不必要的相依性來解決此問題。

當某一個資源使用另一個資源的符號名稱時，Bicep 會建立隱含相依性。 通常不需要使用 dependsOn 的明確相依性。 如需詳細資訊，請參閱 Bicep 相依性。

解決循環相依性︰

  1. 在範本中，找出循環相依性中所識別的資源。
  2. 針對該資源，檢查 dependsOn 屬性及 reference 或 resourceId 函式的任何使用，以查看所相依的資源。
  3. 檢查這些資源，查看所相依的資源。 跟隨相依性，直到您找出相依於原始資源的資源。
  4. 針對涉及循環相依性的資源，仔細檢查 dependsOn 屬性的所有用法，以識別任何不需要的相依性。 若要針對部署進行疑難排解，請移除循環相依性。 您可以使用註解，讓程式碼不會在下次部署期間執行，而不用刪除程式碼。 您可以在 ARM 範本或 Bicep 檔案中使用單行註解 (//) 或多行 (/* ... */)。
  5. 重新部署範本。

移除 dependsOn 屬性的值可能會在您部署範本時導致錯誤。 如果您收到錯誤，請將相依性新增回範本。 如果您使用註解來略過範本中的程式碼，移除註解即可還原程式碼。

如果該方法無法解決循環相依性，請考慮將一部分部署邏輯移到子資源 (例如擴充功能或設定值)。 設定這些子資源在參與循環相依性的資源之後才進行部署。 例如，假設您要部署兩部虛擬機器，但是您必須分別在上面設定互相參考的屬性。 您可以採取下列順序部署︰

  1. vm1
  2. vm2
  3. vm1 的擴充相依於 vm1 和 vm2。 擴充在 vm1 上設定從 vm2 取得的值。
  4. vm2 的擴充相依於 vm1 和 vm2。 擴充在 vm2 上設定從 vm1 取得的值。

相同的方法也適用於 App Service 應用程式。 請考慮將設定值移入應用程式資源的子資源。 您可以採取下列順序部署兩個 Web 應用程式︰

  1. webapp1
  2. webapp2
  3. webapp1 的設定相依於 webapp1 和 webapp2。 它包含使用 webapp2 的值的應用程式設定。
  4. webapp2 的設定相依於 webapp1 和 webapp2。 它包含使用 webapp1 的值的應用程式設定。

解決方案 6：驗證所匯出範本的語法

在 Azure 中部署資源之後，可以匯出 ARM 範本 JSON，並對其他部署加以修改。 您應該先驗證匯出的範本語法是否正確，然後再用範本來部署資源。

您可以從入口網站、Azure CLI 或 Azure PowerShell 匯出範本。 無論您從資源或資源群組，還是從部署歷程記錄匯出範本，都有適用的建議。

匯出 ARM 範本之後，您可以將 JSON 範本反向組譯為 Bicep。 然後使用最佳做法和 Linter 來驗證您的程式碼。

如需詳細資訊，請移至下列文章：