أوامر Bicep CLI

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

يوضح هذا التوجيه كيفية تشغيل الأوامر في Azure CLI. عند تشغيل الأوامر في Azure CLI، ابدأ بتشغيلها az. إذا كنت لا تستخدم Azure CLI، فقم بتشغيل الأوامر دون az في بداية كل منها. على سبيل المثال، az bicep build يصبح bicep build، ويصبح az bicep versionbicep --version.

الإنشاء

يقوم الأمر build بتحويل ملف Bicep إلى قالب Azure Resource Manager JSON (قالب ARM). عادة، لا تحتاج إلى تشغيل هذا الأمر لأنه يعمل تلقائيا عند نشر ملف Bicep. قم بتشغيله يدويا عندما تريد رؤية قالب JSON ARM الذي تم إنشاؤه من ملف Bicep.

يؤدي استخدام أي من ميزات Bicep التالية إلى تمكين إنشاء التعليمات البرمجية لإصدار اللغة 2.0 تلقائيا:

يحول المثال التالي ملف Bicep باسم main.bicep إلى قالب ARM يسمى main.json. يتم إنشاء الملف الجديد في نفس الدليل مثل ملف Bicep:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep build main.bicep

يحفظ المثال التالي main.json إلى دليل مختلف:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep build main.bicep --outdir c:\jsontemplates

يحدد المثال التالي اسم الملف وموقعه لإنشاء:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep build main.bicep --outfile c:\jsontemplates\azuredeploy.json

لطباعة الملف إلى stdout، استخدم:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep build main.bicep --stdout

إذا كان ملف Bicep يتضمن وحدة نمطية تشير إلى سجل خارجي، فإن الأمر build يستدعي تلقائيا restore. restore يحصل الأمر على الملف من السجل ويخزنه في ذاكرة التخزين المؤقت المحلية.

إشعار

لا يقوم restore الأمر بتحديث ذاكرة التخزين المؤقت. لمزيد من المعلومات، راجع استعادة.

لمنع الاستعادة التلقائية --no-restore ، استخدم مفتاح التبديل:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep build --no-restore <bicep-file>

لاستخدام مفتاح التبديل --no-restore، يجب أن يكون لديك Bicep CLI الإصدار 0.4.X أو أحدث.

تفشل عملية الإنشاء باستخدام المفتاح --no-restore إذا لم تكن إحدى الوحدات الخارجية مخزنة مؤقتاً بالفعل:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" hasn't been restored.

عندما تحصل على هذا الخطأ، قم بتشغيل build الأمر بدون --no-restore مفتاح التبديل، أو قم بتشغيله bicep restore أولا.

بناء المعلمات

ينشئ build-params الأمر ملفا .bicepparam في ملف معلمات JSON:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep build-params params.bicepparam

يحول هذا الأمر ملف معلمات params.bicepparam إلى ملف معلمات JSON params.json .

عزى

يتوفر الأمر console في Bicep CLI v0.42.1 أو أحدث. يوفر بيئة تفاعلية للقراءةEval-Print Loop (REPL) للتعبيرات Bicep. يسمح لك بتجربة Bicep الدالات والتعبيرات في جلسة وحدة تحكم تفاعلية، مفيدة بشكل خاص عند تأليف أو اختبار منطق Bicep مثل التعبيرات والوظائف والوظائف المعرفة من قبل المستخدم. وهو يدعم الميزات التالية:

  • تقييم التعبير غير النشط: أدخل تعبيرات Bicep واطلع على نتائجها التي تم تقييمها على الفور
  • تعريفات المتغير: تعريف المتغيرات باستخدام 'var name = بناء جملة التعبير وإعادة استخدامها في التعبيرات اللاحقة
  • الإدخال متعدد الأسطر: دعم التعبيرات المعقدة متعددة الأسطر مع الكشف التلقائي عن الإكمال الهيكلي
  • تمييز بناء الجملة: تمييز بناء الجملة في الوقت الحقيقي للإدخل والإخراج

console يحتوي الأمر على هذه القيود:

  • لا يوجد دعم للتعبيرات التي تتطلب سياقا Azure، على سبيل المثال resourceGroup()
  • لا يوجد دعم لتعبيرات التكرار الحلقي، على سبيل المثال. [for i in range(0, x): i]
  • لا توجد حالة مستمرة بين جلسات عمل وحدة التحكم
  • لا يوجد دعم للإكمال

استخدم الأمر التالي لبدء جلسة Bicep وحدة التحكم:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep console

للخروج من وحدة التحكم، اضغط ESC على الأمر أو استخدمه exit .

أمثلة

تعبيرات بسيطة

> 1 + 2
3

> 'Hello, ${'World!'}'
'Hello, World!'

> length(['a', 'b', 'c'])
3

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

> var myName = 'John'
> var greeting = 'Hello, ${myName}!'
> greeting
'Hello, John!'

تعبيرات متعددة الأسطر

تكتشف وحدة التحكم تلقائيا متى تكتمل التعبيرات هيكليا:

> var config = {
  name: 'myApp'
  version: '1.0.0'
  settings: {
    debug: true
    timeout: 30
  }
}
> config.settings.debug
true

تعبيرات معقدة

Lambdas
> var users = [
  { name: 'Alice', age: 30 }
  { name: 'Bob', age: 25 }
]
> map(users, user => user.name)
['Alice', 'Bob']

> filter(users, user => user.age > 26)
[
  {
    age: 30
    name: 'Alice'
  }
]
الأنواع والوظائف المعرفة من قبل المستخدم
> type PersonType = {
  name: string
  age: int
}
> func sayHi(person PersonType) string => 'Hello ${person.name}, you are ${person.age} years old!'
> var alice = {
  name: 'Alice'
  age: 30
}
> [ sayHi(alice), sayHi({ name: 'Bob', age: 25 })]
[
  'Hello Alice, you are 30 years old!'
  'Hello Bob, you are 25 years old!'
]

تحميل المحتوى من الملفات

تدعم وحدة التحكم Bicep أيضا وظائف load*(). يتم استخدام الدليل الذي bicep console يتم تشغيل الأمر منه كدليل حالي عند تقييم load*() الوظائف

يوضح المثال التالي كيفية استخدام loadDirectoryFileInfo() لتحميل معلومات حول جميع ملفات Bicep في دليل:

> loadDirectoryFileInfo('./modules/', '*.bicep')
[
  {
    relativePath: 'C:/Bicep/modules/appService.bicep'
    baseName: 'appService.bicep'
    extension: '.bicep'
  }
]

أنابيب وإعادة توجيه الإدخال/الإخراج القياسية

يدعم أمر وحدة التحكم تقييم التعبيرات المقدمة من خلال الأنابيب أو الإدخال القياسي المعاد توجيهه، ما يتيح سيناريوهات مثل:

  • تمرير نص التعبير عبر echo
  • إنشاء البرامج النصية التي تغذي التعبيرات في وحدة التحكم
  • الاختبار السريع للمقتطفات Bicep التي تم إنشاؤها أو تحويلها

Powershell:

# piped input
"parseCidr('10.144.0.0/20')" | bicep console

Bash:

# piped input
echo "parseCidr('10.144.0.0/20')" | bicep console
# stdin redirection from file content
bicep console < test.txt

يتم أيضا دعم الإدخال متعدد الأسطر:

"{
> foo: 'bar'
> }.foo" | bicep console

تكون النتيجة 'bar'.

يتم أيضا دعم إعادة توجيه الإخراج:

"toObject([{name:'Evie', age:4},{name:'Casper', age:3}], x => x.name)" | bicep console > output.json
more output.json

الإخراج هو :

{
  Evie: {
    name: 'Evie'
    age: 4
  }
  Casper: {
    name: 'Casper'
    age: 3
  }
}

إلغاء التحويل البرمجي

يحول الأمر decompile قالب JSON ARM إلى ملف Bicep:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep decompile main.json

ينشئ هذا الأمر ملفا باسم main.bicep في نفس الدليل مثل main.json. إذا main. bicep موجود في نفس الدليل، استخدم المفتاح --force للكتابة فوق ملف Bicep الموجود.

لمزيد من المعلومات حول استخدام هذا الأمر، راجع قالب JSON ARM Decompile إلى Bicep.

إلغاء التحويل البرمجي للبارامات

يقوم decompile-params الأمر بإلغاء التحويل البرمجي لملف معلمات JSON إلى .bicepparam ملف معلمات.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep decompile-params azuredeploy.parameters.json --bicep-file ./dir/main.bicep

يؤدي هذا الأمر إلى إلغاء تحويل ملف معلمات azuredeploy.parameters.json إلى ملف azuredeploy.parameters.bicepparam . استخدم --bicep-file لتحديد المسار إلى ملف Bicep (بالنسبة إلى ملف .bicepparam) المشار إليه في الإعلان using.

format

يقوم الأمر format بتنسيق ملف Bicep بحيث يتبع اصطلاحات النمط الموصى بها. فكر في الأمر كمنسق تعليمات برمجية أو "أجمل" لملفات Bicep. له نفس وظيفة اختصار SHIFT+ALT+F في Visual Studio Code.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep format main.bicep

إنشاء معلمات

يقوم الأمر generate-params بإنشاء ملف معلمات من ملف Bicep المحدد وتحديثه إذا كان هناك ملف معلمات موجود.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep generate-params main.bicep --output-format bicepparam --include-params all

ينشئ هذا الأمر ملف معلمات Bicep باسم main.bicepparam. يحتوي ملف المعلمات على كافة المعلمات في ملف Bicep، سواء تم تكوينه بقيم افتراضية أم لا.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep generate-params main.bicep --outfile main.parameters.json

ينشئ هذا الأمر ملف معلمات يسمى main.parameters.json. يحتوي ملف المعلمات فقط على المعلمات دون قيم افتراضية تم تكوينها في ملف Bicep.

تثبيت

يضيف الأمر install Bicep CLI إلى بيئتك المحلية، وهو متاح فقط من خلال Azure CLI. لمزيد من المعلومات، راجع تثبيت أدوات Bicep.

‏‏تثبيت أحدث إصدار، استخدم:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI)

غير متوفر

لتثبيت إصدار معين، استخدم الأمر التالي:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI)

غير متوفر

jsonrpc

يقوم الأمر jsonrpc بتشغيل Bicep CLI بواجهة JSON-RPC، ما يتيح التفاعل البرمجي السريع مع ملفات Bicep. للحصول على الاستخدام التفصيلي والتنسيق السلكي والأساليب المتوفرة وخيارات الاتصال، راجع الأمر Bicep CLI jsonrpc.

lint

يقوم الأمر lint بإرجاع الأخطاء وقاعدة linter انتهاكات لملف Bicep.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep lint main.bicep

إذا كان ملف Bicep يتضمن وحدة نمطية تشير إلى سجل خارجي، فإن الأمر lint يستدعي تلقائيا restore. restore يحصل الأمر على الملف من السجل ويخزنه في ذاكرة التخزين المؤقت المحلية.

إشعار

لا يقوم restore الأمر بتحديث ذاكرة التخزين المؤقت. لمزيد من المعلومات، راجع استعادة.

لمنع الاستعادة التلقائية --no-restore ، استخدم مفتاح التبديل:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep lint --no-restore <bicep-file>

تفشل عملية التحليل مع --no-restore مفتاح التبديل إذا لم يتم تخزين إحدى الوحدات النمطية الخارجية مؤقتا بالفعل:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

عندما تحصل على هذا الخطأ، قم بتشغيل الأمر lint دون المفتاح --no-restore أو قم بتشغيل bicep restore أولاً.

قائمة الإصدارات

يقوم الأمر list-versions بإرجاع كافة الإصدارات المتوفرة من Bicep CLI. استخدم هذا الأمر لمعرفة ما إذا كنت تريد ترقية أو تثبيت إصدار جديد. يتوفر هذا الأمر فقط من خلال Azure CLI.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI)

غير متوفر

النشر

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

بعد نشر الملف على السجل، يمكنك الرجوع إليه في وحدة نمطية .

يجب أن يكون لديك Bicep CLI الإصدار 0.14.X أو أحدث لاستخدام الأمر publish والمعلمة --documentationUri/-d.

لنشر وحدة نمطية إلى سجل، استخدم:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep publish <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag> --documentationUri <documentation-uri>

على سبيل المثال:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep publish storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html

publish لا يتعرف الأمر على الأسماء المستعارة المحددة في ملف bicepconfig.json. توفير مسار الوحدة النمطية الكامل.

تحذير

يؤدي النشر إلى نفس الهدف إلى الكتابة فوق الوحدة النمطية القديمة. زيادة الإصدار عند التحديث.

الاستعادة

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

لاستعادة الوحدات النمطية الخارجية إلى ذاكرة التخزين المؤقت المحلية، يجب أن يكون للحساب ملف التعريف الصحيح والأذونات للوصول إلى السجل. يمكنك تكوين profile وأسبقية بيانات الاعتماد للمصادقة على السجل في ملف التكوين Bicep.

لاستخدام الأمر restore، يجب أن يكون لديك Bicep CLI الإصدار 0.14.X أو أحدث.

لاستعادة الوحدات الخارجية يدوياً لملف، استخدم:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep restore <bicep-file>

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

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

يمكنك العثور على ذاكرة التخزين المؤقت المحلية في:

  • في Windows

    %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

  • على Linux

    /home/<username>/.bicep

  • على Mac

    ~/.bicep

لا يقوم restore الأمر بتحديث ذاكرة التخزين المؤقت إذا تم تخزين وحدة نمطية مؤقتا بالفعل. لتحديث ذاكرة التخزين المؤقت، يمكنك إما حذف مسار الوحدة النمطية من ذاكرة التخزين المؤقت أو استخدام --force مفتاح التبديل مع restore الأمر .

snapshot

باستخدام Bicep CLI v0.41.2 أو أحدث، يمكنك استخدام الأمر snapshot لإنشاء تمثيل عادي وحيادي لنشر Bicep من ملف .bicepparam. يمكنك مقارنة هذه اللقطة مع اللقطات اللاحقة لفهم التغييرات التي قد تتسبب فيها إعادة بناء التعليمات البرمجية، دون نشر أي شيء Azure. هذا الأمر مفيد بشكل خاص ل:

  • Visual Diffs: رؤية كيفية تغيير إعادة بناء التعليمات البرمجية (مثل نقل التعليمات البرمجية إلى وحدة نمطية) تعريفات الموارد الأساسية بالضبط.
  • التعبيرات المعقدة: فهم ما تقيمه سلسلة معقدة أو متغير بالفعل قبل النشر.
  • التحقق من صحة CI/CD: التقاط التغييرات غير المقصودة تلقائيا في منطق البنية الأساسية أثناء طلبات السحب.

إنشاء لقطة

ينشئ هذا الأمر ملفا .snapshot.json . يتم "تطبيع" هذا الملف، مما يعني أنه يزيل الضوضاء مثل حدود الوحدة النمطية حتى تتمكن من التركيز على الموارد نفسها.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep snapshot --mode overwrite <bicep-param-file>

يعرض ملف JSON التالي مثالا للقطة:

{
  "predictedResources": [
    {
      "id": "[format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]",
      "type": "Microsoft.Storage/storageAccounts",
      "name": "stmyappstorage001",
      "apiVersion": "2025-01-01",
      "location": "eastus",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2"
    }
  ],
  "diagnostics": []
}

التحقق من صحة التغييرات

بعد إنشاء لقطة، قم بتشغيل الأمر في وضع التحقق من الصحة. وهو يقارن التعليمات البرمجية Bicep الحالية مقابل اللقطة المحفوظة ويعرض شفرة تحكم مرئية، مثل الأمر what-if ولكنه محلي تماما.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep snapshot --mode validate <bicep-param-file>

يبدو إخراج العينة كما يلي:

PS C:\bicep> bicep snapshot --mode validate main.bicepparam
Snapshot validation failed. Expected no changes, but found the following:

Scope: <unknown>

  ~ [format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]
    ~ apiVersion: "2025-01-01" => "2025-06-01"
    ~ sku.name:   "Standard_LRS" => "Standard_GRS"

يشير "فشل التحقق من صحة اللقطة" إلى الاختلافات بين اللقطتين.

تحتوي لقطة Bicep CLI و What-if على هذه الاختلافات:

الميزة bicep snapshot az deployment group what-if
تنفيذ محلي فقط (غير متصل) مستند إلى السحابة (عبر الإنترنت)
Comparison مقارنة التعليمات البرمجية مقابل ملف محفوظ مقارنة التعليمات البرمجية مقابل حالة Azure المباشرة
السرعة سريع للغاية أبطأ (يتطلب استدعاءات واجهة برمجة التطبيقات)
حالة الاستخدام إعادة بناء التعليمات البرمجية واختبار المنطق الفحص النهائي قبل النشر

توفير السياق

عند تشغيل Bicep اللقطة، يقوم CLI بإجراء تقييم محلي للتعليمات البرمجية الخاصة بك. نظرا لأنه لا يتحدث إلى Azure، فإنه لا يمكنه "طلب" السحابة لمعرف الاشتراك أو اسم مجموعة الموارد الحالي.

إذا كانت التعليمات البرمجية تستخدم وظائف البيئة (مثل subscription().id)، فستفشل اللقطة أو ترجع العناصر النائبة ما لم توفر سياقا محددا عبر وسيطات CLI.

لمحاكاة بيئة توزيع حقيقية، يمكنك تمرير العلامات التالية:

الوسيطة الغرض مثال للقيمة
--subscription-id استبدال القيمة التي تم إرجاعها بواسطة subscription().subscriptionId 00000000-1111-2222-3333-444444444444
--resource-group استبدال القيمة التي تم إرجاعها بواسطة resourceGroup().name my-production-rg
--location تعيين الموقع الافتراضي ل deployment().location westeurope
--tenant-id استبدال القيمة التي تم إرجاعها بواسطة tenant().tenantId 72f988bf-86f1-41af-91ab-2d7cd011db47
--management-group استبدال القيمة التي تم إرجاعها بواسطة managementGroup().name my-corp-mg
  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep snapshot main.bicepparam \
  --subscription-id 00000000-0000-0000-0000-000000000000 \
  --resource-group my-temp-rg \
  --location eastus \
  --mode overwrite

الترقية

يقوم الأمر upgrade بتحديث الإصدار المثبت باستخدام أحدث إصدار. يتوفر هذا الأمر فقط من خلال Azure CLI.

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI)

غير متوفر

إصدار

يقوم version الأمر بإرجاع الإصدار المثبت:

  • Bicep CLI
  • واجهة سطر الأوامر Azure (Azure CLI) 
bicep --version

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

يعرض الأمر رقم الإصدار:

Bicep CLI version 0.29.45 (57a44c0230)

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

لمعرفة المزيد حول نشر ملف Bicep، راجع:

  • Last updated on