كيفية استخدام قوالب النشر Azure Resource Manager (ARM) مع Azure CLI

تشرح هذه المقالة كيفية استخدام Azure CLI مع قوالب Azure Resource Manager (قوالب ARM) لنشر مواردك على Azure. إذا لم تكن على دراية بمفاهيم نشر وإدارة حلول Azure الخاصة بك، راجع template deployment generalreview.

تغيرت أوامر النشر في إصدار Azure CLI 2.2.0. تتطلب الأمثلة في هذا المقال Azure CLI الإصدار 2.20.0 أو أحدث.

لتشغيل هذه العينة، قم بتثبيت أحدث إصدار من Azure CLI. للبدء، شغل az login لإنشاء اتصال مع Azure.

العينات الخاصة ب Azure CLI مكتوبة لغلاف bash. لتشغيل هذا العينة في Windows PowerShell أو Command Prompt، قد تحتاج إلى تغيير عناصر السكريبت.

إذا لم يكن لديك Azure CLI مثبتا، يمكنك استخدام Azure Cloud Shell. لمزيد من المعلومات، راجع Deploy ARM قوالب من Azure Cloud Shell.

تلميح

نوصي ب Bicep لأنه يوفر نفس القدرات مثل قوالب ARM وصياغة الجملة أسهل في الاستخدام. لمعرفة المزيد، راجع كيفية نشر الموارد باستخدام Bicep و Azure CLI.

المتطلبات الأساسية

الأذونات المطلوبة

لنشر قالب ملف أو Azure Resource Manager Bicep (ARM)، تحتاج إلى وصول كتابي على الموارد التي تقوم بنشرها والوصول إلى جميع العمليات على نوع المورد Microsoft.Resources/deployments. على سبيل المثال، لنشر آلة افتراضية، تحتاج إلى صلاحيات Microsoft.Compute/virtualMachines/write و Microsoft.Resources/deployments/*. عملية "ماذا لو" لها متطلبات الإذن نفسها.

Azure CLI الإصدار 2.76.0 أو أحدث والإصدار Azure PowerShell 13.4.0 أو أحدث تقدم مفتاح ValidationLevel لتحديد مدى استقرار ARM لنموذج Bicep خلال هذه العملية. لمزيد من المعلومات، راجع أوامر ماذا لو

للحصول على قائمة الأدوار والأصوات، راجع Azure الأدوار المدمجة.

نطاق النشر

يمكنك استهداف قالب نشر Azure الخاص بك لمجموعة موارد أو اشتراك أو مجموعة إدارة أو مستأجر. اعتماداً على نطاق النشر، يمكنك استخدام أوامر مختلفة.

لكل نطاق، يجب أن يكون لدى المستخدم الذي يقوم بتوزيع القالب الأذونات المطلوبة لإنشاء الموارد.

نشر قالب محلي

يمكنك توزيع قالب ARM من الجهاز المحلي أو قالب مخزن خارجيًّا. يصف هذا القسم نشر قالب محلي.

إذا كنت تقوم بالتوزيع في مجموعة موارد غير موجودة، قم بإنشاء مجموعة الموارد. يمكن أن يتضمن اسم مجموعة الموارد أحرفاً أبجدية رقمية ونقاط وتسطيرات أسفل السطر وواصلات وأقواساً فقط. يمكن أن يصل إلى 90 حرفاً. لا يمكن أن ينتهي الاسم بنقطة.

az group create --name ExampleGroup --location "Central US"

لنشر قالب محلي، استخدم المعلمة --template-fileفي أمر النشر. يوضح المثال التالي أيضًا كيفية تعيين قيمة معلمة.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-template> \
  --parameters storageAccountType=Standard_GRS

يجب أن تكون قيمة معامل --template-file ملف Bicep أو ملف .json أو .jsonc. يشير ملحق الملف .jsonc إلى أن الملف يمكن أن يحتوي على تعليقات النمط //. يقبل نظام ARM التعليقات // في الملفات .json. لا يهتم بامتداد الملف. لمزيد من المعلومات حول التعليقات وبيانات التعريف، راجع فهم بناء جملة قوالب ARM وبنيتها.

قد يستغرق إكمالها قالب نشر Azure بضع دقائق. عند الانتهاء، سترى رسالة تتضمن النتيجة:

"provisioningState": "Succeeded",

نشر قالب بعيد

بدلا من تخزين قوالب ARM على جهازك المحلي، قد تفضل تخزينها في موقع خارجي. يمكنك تخزين القوالب في مستودع تحكم المصدر (مثل GitHub). أو يمكنك تخزينها في حساب تخزين Azure للوصول المشترك داخل مؤسستك.

إشعار

لنشر قالب أو الرجوع إلى قالب مرتبط مخزن في مستودع GitHub خاص، راجع الحل المخصص الموثق في إنشاء عرض مدخل Azure مخصص وآمن. يمكنك إنشاء دالة Azure التي تسحب رمز GitHub من Azure Key Vault.

إذا كنت تقوم بالتوزيع في مجموعة موارد غير موجودة، قم بإنشاء مجموعة الموارد. يمكن أن يتضمن اسم مجموعة الموارد أحرفاً أبجدية رقمية ونقاط وتسطيرات أسفل السطر وواصلات وأقواساً فقط. يمكن أن يصل إلى 90 حرفاً. لا يمكن أن ينتهي الاسم بنقطة.

az group create --name ExampleGroup --location "Central US"

لنشر قالب خارجي، استخدم المعلمة template-uri.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

يتطلب المثال السابق عنوان URI يمكن الوصول إليه بشكل عام للقالب، والذي يعمل لمعظم السيناريوهات لأنه لا يجب أن يتضمن القالب بيانات حساسة. إذا احتجت إلى تحديد بيانات حساسة (مثل كلمة مرور المسؤول)، قم بتمرير هذه القيمة كمعلمة آمنة. ومع ذلك، إن أردت إدارة الوصول إلى القالب، فضع في اعتبارك استخدام مواصفات القالب.

لتوزيع قوالب مرتبطة بعيدة ذات مسار نسبي مخزنة في حساب تخزين، استخدم query-string لتحديد رمز SAS المميز:

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

لمزيد من المعلومات، راجع استخدام المسار النسبي للقوالب المرتبطة.

Azure deployment template name

عند نشر قالب ARM، يمكنك إعطاء قالب نشر Azure اسما. يمكن أن يساعدك هذا الاسم في استرداد النشر من محفوظات النشر. إذا لم تُوفر اسمًا للنشر، يُستخدم اسم ملف القالب. على سبيل المثال، إذا قمت بتوزيع قالب مسمى azuredeploy.json ولم تحدد اسم توزيع، يُسمى التوزيع azuredeploy.

في كل مرة تُشغل فيها النشر، تتم إضافة إدخال إلى محفوظات نشر مجموعة الموارد باسم النشر. إذا قمت بتشغيل نشر آخر وأعطيته نفس الاسم، يُستبدل الإدخال السابق بالنشر الحالي. إذا كنت ترغب في الاحتفاظ بإدخالات فريدة في محفوظات النشر، قم بإعطاء كل نشر اسماً فريداً.

لإنشاء اسماً فريداً، يمكنك تعيين رقم عشوائي.

deploymentName='ExampleDeployment'$RANDOM

أو إضافة قيمة تاريخ.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

إذا قمت بتشغيل عمليات النشر المتزامنة إلى نفس مجموعة الموارد بنفس اسم النشر، فسيتم إكمال النشر الأخير فقط. تُستبدل أي عمليات نشر تحمل نفس الاسم، ولم تكتمل بعد، بعملية النشر الأخيرة. على سبيل المثال، إذا قمت بتشغيل نشر اسمه newStorage ينشر حساب تخزين مسمى storage1، وفي نفس الوقت قمت بتشغيل نشر آخر يسمى newStorage ينشر حساب تخزين مسمى storage2، فإنك تنشر حساب تخزين واحد فقط. يتم تسمية حساب التخزين الناتج بـ storage2.

ومع ذلك،، إذا قمت بتشغيل نشر اسمه newStorage ينشر حساب تخزين مسمى storage1، وبمجرد اكتماله قمت بتشغيل نشر آخر يسمى newStorage ينشر حساب تخزين مسمى storage2، فإنك تنشر حسابيّ تخزين. أحدهما يسمى storage1، والآخر يسمى storage2. ولكن لديك إدخال واحد فقط في محفوظات النشر.

عند تحديد اسم فريد لكل نشر، يمكنك تشغيلهم بشكل متزامن دون تعارض. إذا قمت بتشغيل نشر اسمه newStorage1 ينشر حساب تخزين مسمى storage1، وفي نفس الوقت قمت بتشغيل نشر آخر اسمه newStorage2 ينشر حساب تخزين مسمى storage2، فسيكون لديك حسابان للتخزين وإدخالان في محفوظات النشر.

لتجنب تعارض مع عمليات التوزيع المتزامنة ولضمان إدخالات فريدة في محفوظات التوزيع، قم بإعطاء كل توزيع اسمًا فريدًا.

مواصفات قالب التوزيع

بدلا من نشر قالب محلي أو بعيد، يمكنك إنشاء template spec. مواصفة القالب هي مورد في اشتراكك في Azure يحتوي على قالب ARM. فهو يسهل مشاركة القالب بأمان مع المستخدمين في مؤسستك. تستخدم Azure التحكم في الوصول القائم على الأدوار (Azure RBAC) لمنح الوصول إلى مواصفات القالب. هذه الميزة حاليا في مرحلة المعاينة.

توضح الأمثلة التالية كيفية إنشاء مواصفات قالب وتوزيعها.

أولًا، إنشاء مواصفات قالب عن طريق توفير قالب ARM.

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

ثم، احصل على معرف مواصفات القالب وقم بتوزيعه.

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

لمزيد من المعلومات، راجع مواصفات Azure Resource Manager في قالب المواصفات.

معاينة التغييرات

قبل نشر قالب ARM الخاص بك، يمكنك معاينة التغييرات التي يقوم بها القالب على بيئتك. استخدم عملية ماذا لو للتحقق من أن القالب يقوم بالتغييرات التي تتوقعها. عملية ماذا لو تقوم أيضًا بالتحقق من صحة القالب بحثًا عن الأخطاء.

المعلمات

لتمرير قيم المعلمات، يمكنك استخدام معلمات مضمنة أو ملف معلمات. يمكن أن يكون ملف المعلمات إما ملف معلمات Bicep أو ملف معلمات JSON.

المعلمات المُضمنة

لتمرير المعلمات المضمنة، يرجى توفير القيم في parameters. على سبيل المثال، لتمرير سلسلة وصفيف إلى قالب في Bash shell، استخدم:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

إذا كنت تستخدم Azure CLI مع Windows موجه الأوامر (CMD) أو PowerShell، مرر المصفوفة بالصيغة: exampleArray="['value1','value2']".

يمكنك أيضاً الحصول على محتويات الملف وتوفير هذا المحتوى كمعلمة مُضمنة.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

يُعد الحصول على قيمة معلمة من ملف مفيداً عندما تحتاج إلى توفير قيم التكوين. على سبيل المثال، يمكنك توفير قيم تهيئة السحابة لجهاز Linux ظاهري.

تنسيق arrayContent.json هو:

[
  "value1",
  "value2"
]

لتمرير كائن، على سبيل المثال، لتعيين علامات، استخدم JSON. على سبيل المثال، قد يتضمن القالب معلمة مثل هذه:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

في هذه الحالة، يمكنك تمرير سلسلة JSON لتعيين المعلمة كما هو موضح في البرنامج النصي Bash التالي:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $templateFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

استخدام علامات الاقتباس المزدوجة حول JSON التي تريد تمريرها إلى الكائن.

يمكنك استخدام متغير لاحتواء قيم المعلمات. في Bash، قم بتعيين المتغير إلى كافة قيم المعلمة وإضافته إلى أمر النشر.

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters $params

ومع ذلك، إذا كنت تستخدم Azure CLI مع موجه أوامر Windows (CMD) أو PowerShell، قم بتعيين المتغير إلى سلسلة JSON. الابتعاد عن علامات الاقتباس: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

ملفات معلمات JSON

بدلا من تمرير المعلمات كقيم مضمنة في البرنامج النصي الخاص بك، قد تجد أنه من الأسهل استخدام ملف معلمات، إما .bicepparam ملف أو ملف معلمات JSON، يحتوي على قيم المعلمات. يجب أن يكون ملف المعلمات ملفا محليا. ملفات المعلمات الخارجية غير مدعومة مع Azure CLI.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters 'storage.parameters.json'

لمزيد من المعلومات حول ملف المعاملات، انظر إنشاء ملف المعلمات Resource Manager.

ملفات معلمات Bicep

مع إصدار Azure CLI 2.53.0 أو أحدث، وإصدار Bicep CLI 0.22.6 أو أحدث، يمكنك نشر ملف Bicep باستخدام ملف معلمات Bicep. مع عبارة using داخل ملف معلمات Bicep، لا حاجة لتوفير مفتاح --template-file عند تحديد ملف معلمات Bicep لمفتاح --parameters. بما في --template-file ذلك نتائج التبديل، "يسمح فقط بملف .bicep مع ملف .bicepparam"، خطأ.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

يجب أن يكون ملف المعلمات ملفا محليا. ملفات المعلمات الخارجية غير مدعومة مع Azure CLI. لمزيد من المعلومات حول ملف المعلمات، راجع إنشاء ملف Resource Manager المعلمات.

التعليقات وتنسيق JSON المُوسع

يمكنك تضمين تعليقات النمط // في ملف المعلمة، ولكن يجب تسمية الملف بملحق .jsonc.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters '@storage.parameters.jsonc'

لمزيد من التفاصيل حول التعليقات وبيانات التعريف، راجع فهم بنية وبناء جملة قوالب ARM.

إذا كنت تستخدم Azure CLI مع الإصدار 2.3.0 أو أقدم، يمكنك نشر قالب يحتوي على سلاسل أو تعليقات متعددة الأسطر باستخدام مفتاح --handle-extended-json-format. على سبيل المثال:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2025-04-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

الخطوات التالية

  • Last updated on