كيفية نشر الموارد مع Bicep و Azure CLI

مقالة
03/22/2024

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

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

تحتاج إلى ملف Bicep للنشر. يجب أن يكون الملف محلياً.

تحتاج إلى Azure CLI وأن تكون متصلاً بـ Azure:

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

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

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

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

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

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

نطاق النشر

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

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

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

للنشر إلى اشتراك، استخدم الأمر az deployment sub create:
```
az deployment sub create --location <location> --template-file <path-to-bicep>
```
لمزيد من المعلومات عن النشر على مستوى الاشتراك، يُرجى الرجوع إلى إنشاء موارد ومجموعات موارد على مستوى الاشتراك.
للنشر إلى مجموعة إدارة، استخدم الأمر az deployment mg create:
```
az deployment mg create --location <location> --template-file <path-to-bicep>
```
لمزيد من المعلومات حول النشر على مستوى مجموعة الإدارة، راجع إنشاء موارد على مستوى مجموعة الإدارة.
للتوزيع إلى مستأجر، استخدم az deployment tenant create:
```
az deployment tenant create --location <location> --template-file <path-to-bicep>
```
لمزيد من المعلومات حول النشر على مستوى المستأجر، راجع إنشاء موارد على مستوى المستأجر.

لكل نطاق، يجب أن يكون لدى المستخدم الذي يقوم بنشر ملف 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 إلى الموقع البعيد. لمزيد من المعلومات، راجع نشر قوالب ARM 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 مع Windows Command Prompt (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"
  }
}

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

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

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

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

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

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

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

باستخدام الإصدار 2.53.0 من Azure CLI أو أحدث، وإصدار Bicep CLI 0.22.X أو أعلى، يمكنك نشر ملف Bicep باستخدام ملف معلمة Bicep. باستخدام العبارة 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'

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

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

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

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

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

حالياً، لا يدعم Azure CLI إنشاء مواصفات القالب من خلال توفير ملفات Bicep. ومع ذلك، يمكنك إنشاء ملف Bicep باستخدام المورد Microsoft.Resources/templateSpecss لنشر مواصفات قالب. تعرض إنشاء عينة مواصفات قالب كيفية إنشاء مواصفات قالب في ملف 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 وبناء الجملة.

Share via