مشاركة عبر

حل الأخطاء الخاصة بالقالب غير الصالح

  • مقالة

توضح هذه المقالة كيفية حل أخطاء القوالب غير الصالحة لملفات 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، تم زيادة هذا الحد إلى 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. فكر في نقل قيم التكوين إلى مورد تابع لمورد التطبيق. يمكنك نشر تطبيقين ويب بالترتيب التالي:

  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. ثم استخدم أفضل الممارسات وأداة التحليل للتحقق من صحة التعليمات البرمجية الخاصة بك.

لمزيد من المعلومات، انتقل إلى المقالات التالية: