مشاركة عبر

نشر ملفات Bicep باستخدام Azure CLI

  • مقالة

توضح هذه المقالة كيفية استخدام Azure CLI مع ملفات Bicep لنشر مواردك إلى Azure. إذا لم تكن على دراية بنشر حلول Azure وإدارتها، فشاهد ما هو Bicep؟.

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

تحتاج إلى ملف Bicep لنشره، ويجب أن يكون الملف محليا. تحتاج أيضا إلى Azure CLI وأن تكون متصلا ب Azure:

  • تثبيت أوامر Azure CLI على الكمبيوتر المحلي. لنشر ملفات Bicep تحتاج إلى Azure CLI الإصدار 2.20.0 أو أحدث.
  • استخدم az login للاتصال ب Azure. إذا كان لديك العديد من اشتراكات Azure، فقد تحتاج أيضا إلى تشغيل az account set.

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

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

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

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

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

نطاق النشر

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

نشر ملف Bicep المحلي

يمكنك نشر ملف Bicep من جهازك المحلي أو ملف خارجي. يصف هذا القسم كيفية نشر ملف Bicep محلي.

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

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

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

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

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

"provisioningState": "Succeeded",

نشر ملف Bicep عن بُعد

لا يدعم Azure CLI حاليا نشر ملفات Bicep البعيدة. يمكنك استخدام Bicep CLI لإنشاء ملف Bicep إلى قالب JSON ثم تحميل ملف JSON إلى موقع بعيد. لمزيد من المعلومات، راجع نشر قالب بعيد.

المعلمات

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

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

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

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

إذا كنت تستخدم Azure CLI مع cmd أو PowerShell، فمرر الصفيف بالتنسيق: exampleArray="['value1','value2']".

يمكنك أيضا الحصول على محتويات الملف لتوفير هذا المحتوى كمعلمة مضمنة. مقدمة اسم الملف ب @:

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

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

تنسيق arrayContent.json هو:

[
  "value1",
  "value2"
]

لتمرير عنصر، استخدم JSON (عند تعيين العلامات، على سبيل المثال). قد يتضمن ملف Bicep معلمة مثل هذه:

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

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

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

إذا كنت تستخدم Azure CLI مع cmd أو PowerShell، فمرر الكائن بالتنسيق التالي:

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

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

params="prefix=start suffix=end"

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

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

يتبع تقييم المعلمات ترتيبا تسلسليا، ما يعني أنه إذا تم تعيين قيمة عدة مرات، استخدام القيمة الأخيرة المعينة فقط. لتعيين المعلمات بشكل صحيح، يوصى بتوفير ملف المعلمات في البداية ثم استخدام بناء جملة KEY=VALUE لتجاوز معلمات معينة بشكل انتقائي. إذا كنت تقوم بتوفير .bicepparam ملف معلمات، يمكنك استخدام هذه الوسيطة مرة واحدة فقط.

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

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

يمكنك استخدام ملف معلمات Bicep لنشر ملف Bicep مع الإصدار 2.53.0 من Azure CLI أو أحدث وإصدار Bicep CLI 0.22.X أو أحدث. باستخدام العبارة using داخل ملف معلمات Bicep، ليست هناك حاجة لتوفير --template-file مفتاح التبديل عند تحديد ملف معلمات Bicep للتبديل --parameters . سيؤدي تضمين مفتاح التبديل إلى --template-file ظهور رسالة الخطأ "يسمح فقط بقالب .bicep مع ملف .bicepparam".

يوضح المثال التالي ملف معلمات يسمى storage.bicepparam. الملف موجود في نفس الدليل حيث يتم تشغيل الأمر:

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

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

يوضح المثال التالي ملف معلمات يسمى storage.parameters.json. الملف موجود في نفس الدليل حيث يتم تشغيل الأمر:

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

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

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

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

نشر مواصفات القالب

حاليا، لا يوفر Azure CLI ملفات Bicep للمساعدة في إنشاء مواصفات القالب. ومع ذلك، يمكنك إنشاء ملف Bicep باستخدام مورد Microsoft.Resources/templateSpecs لنشر مواصفات قالب. يوضح نموذج Create template spec كيفية إنشاء مواصفات قالب في ملف Bicep. يمكنك أيضا إنشاء ملف Bicep الخاص بك إلى JSON باستخدام Bicep CLI ثم قالب JSON لإنشاء مواصفات قالب.

اسم التوزيع

عند نشر ملف Bicep، يمكنك إعطاء النشر اسماً. يمكن أن يساعدك هذا الاسم في استرداد النشر من محفوظات النشر. إذا لم تقدم اسما للتوزيع، يصبح اسمه اسم ملف Bicep. على سبيل المثال، إذا قمت بنشر ملف Bicep يسمى main.bicep ولم تحدد اسم نشر، تتم تسمية mainالنشر .

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

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

deploymentName='ExampleDeployment'$RANDOM

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

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

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

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

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

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

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

لفهم كيفية تعريف المعلمات في الملف، راجع فهم بنية ملفات Bicep وبناء الجملة.