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

هل هذه الصفحة مفيدة؟

هل لديك ملاحظات إضافية؟

سيتم إرسال الملاحظات إلى Microsoft: بالضغط على الزر «إرسال»، سيتم استخدام ملاحظاتك لتحسين منتجات Microsoft وخدماتها. نهج الخصوصية.

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

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

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

كُتبت نماذج Azure CLI للواجهة bash. لتشغيل هذا النموذج في Windows PowerShell أو موجه الأوامر، يلزم تغيير عناصر البرنامج النصي.

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

تلميح

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

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

لنشر ملف Bicep أو قالب ARM، يلزم الوصول إلى الكتابة على الموارد التي تنشرها والوصول إلى جميع العمليات على نوع المورد Microsoft.Resources/deployments. على سبيل المثال، لنشر جهاز ظاهري، تحتاج إلى أذونات Microsoft.Compute/virtualMachines/write وMicrosoft.Resources/deployments/*.

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

نطاق النشر

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

• للنشر إلى مجموعة موارد، استخدم الأمر az deployment group create:

  az deployment group create --resource-group <resource-group-name> --template-file <path-to-template>
  

• للنشر إلى اشتراك، استخدم الأمر az deployment sub create:

  az deployment sub create --location <location> --template-file <path-to-template>
  

  لمزيد من المعلومات حول عمليات النشر على مستوى الاشتراك، راجع إنشاء مجموعات موارد وموارد على مستوى الاشتراك.

• للنشر إلى مجموعة إدارة، استخدم الأمر az deployment mg create:

  az deployment mg create --location <location> --template-file <path-to-template>
  

  لمزيد من المعلومات حول النشر على مستوى مجموعة الإدارة، راجع إنشاء موارد على مستوى مجموعة الإدارة.

• للنشر إلى مستأجر، استخدم الأمر az deployment tenant create:

  az deployment tenant create --location <location> --template-file <path-to-template>
  

  لمزيد من المعلومات حول النشر على مستوى المستأجر، راجع إنشاء موارد على مستوى المستأجر.

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

توزيع قالب محلي

يمكنك توزيع قالب 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

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

"provisioningState": "Succeeded",

توزيع قالب بعيد

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

ملاحظة

لتوزيع قالب أو الرجوع إلى قالب مرتبط مخزن في مستودع GitHub خاص، راجع الحل المخصص الموثق في إنشاء عرض مدخل Microsoft Azure مخصص وآمن. يمكنك إنشاء Azure Function التي تسحب رمز 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

عند توزيع قالب 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، فسيكون لديك حسابان للتخزين وإدخالان في محفوظات النشر.

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

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

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

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

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

المعلمات

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

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

لتمرير المعلمات المضمنة، يرجى توفير القيم في 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 Command Prompt (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 Command Prompt (CMD) أو PowerShell، قم بتعيين المتغير إلى سلسلة JSON. الابتعاد عن علامات الاقتباس: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

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

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

لمزيد من المعلومات حول ملف المعلمة، راجع إنشاء ملف معلمة لمدير الموارد.

لتمرير ملف معلمة محلية، استخدم @ لتحديد ملف محلي يسمى storage.parameters.json.

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

معالجة صيغة JSON الممتدة

لتوزيع قالب مع سلاسل متعدد الأسطر أو تعليقات باستخدام Azure CLI مع الإصدار 2.3.0 أو أقدم، يجب استخدام رمز التبديل --handle-extended-json-format. على سبيل المثال:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-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'))]"
  ],

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

• للرجوع إلى النشر الناجح عندما تحصل على خطأ، راجع التراجع عن الخطأ إلى نشر ناجح.
• لتحديد كيفية معالجة الموارد الموجودة في مجموعة الموارد ولكن لم تُعرّف في القالب، راجع أوضاع نشر Azure Resource Manager.
• لفهم كيفية تعريف المعلمات في القالب، راجع فهم بنية قوالب ARM وبناء الجملة لها.
• للحصول على نصائح حول حل أخطاء التوزيع الشائعة، راجع استكشاف أخطاء توزيع Azure الشائعة وإصلاحها باستخدام Azure Resource Manager.