Bagikan melalui

perintah CLI Bicep

Artikel ini menjelaskan perintah yang bisa Anda gunakan di CLI Bicep. Anda dapat menjalankan perintah ini dengan menggunakan Azure CLI atau dengan langsung memanggil perintah CLI Bicep. Setiap metode memerlukan proses penginstalan yang berbeda. Untuk informasi selengkapnya tentang penginstalan, lihat Azure CLI dan Azure PowerShell.

Panduan ini menunjukkan cara menjalankan perintah di Azure CLI. Saat menjalankan perintah di Azure CLI, mulai dengan az. Jika Anda tidak menggunakan Azure CLI, jalankan perintah tanpa az di awal masing-masing. Misalnya, az bicep build menjadi bicep build, dan az bicep version menjadi bicep --version.

bangun

Perintah build mengonversi file Bicep ke templat Azure Resource Manager JSON (templat ARM). Biasanya, Anda tidak perlu menjalankan perintah ini karena berjalan secara otomatis saat Anda menyebarkan file Bicep. Jalankan secara manual saat Anda ingin melihat templat JSON ARM yang dibuat dari file Bicep Anda.

Menggunakan salah satu fitur Bicep berikut secara otomatis mengaktifkan pembuatan kode bahasa versi 2.0:

Contoh berikut mengonversi file Bicep bernama main.bicep ke templat ARM bernama main.json. File baru dibuat dalam direktori yang sama dengan file Bicep:

bicep build main.bicep

Contoh berikutnya menyimpan main.json ke direktori lain:

bicep build main.bicep --outdir c:\jsontemplates

Contoh berikut menentukan nama dan lokasi file yang akan dibuat:

bicep build main.bicep --outfile c:\jsontemplates\azuredeploy.json

Untuk mencetak file ke stdout, gunakan:

bicep build main.bicep --stdout

Jika file Bicep Anda menyertakan modul yang mereferensikan registri eksternal, perintah build secara otomatis memanggil restore. restore Perintah mendapatkan file dari registri dan menyimpannya di cache lokal.

Catatan

Perintah restore tidak menyegarkan cache. Untuk mengetahui informasi selengkapnya, lihat memulihkan.

Untuk mencegah pemulihan otomatis, gunakan sakelar --no-restore :

bicep build --no-restore <bicep-file>

Untuk menggunakan sakelar --no-restore, Anda harus memiliki Bicep CLI versi 0.4.X atau yang lebih baru.

Proses build dengan sakelar --no-restore gagal jika salah satu modul eksternal belum di-cache:

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

Saat Anda mendapatkan kesalahan ini, jalankan build perintah tanpa --no-restore sakelar, atau jalankan bicep restore terlebih dahulu.

build-params

Perintah build-params membuat .bicepparam file ke dalam file parameter JSON:

bicep build-params params.bicepparam

Perintah ini mengonversi file parameter params.bicepparam menjadi file parameter JSON params.json .

dekompilasi

Perintah decompile mengonversi templat JSON ARM menjadi file Bicep:

bicep decompile main.json

Perintah ini membuat file bernama main.bicep di direktori yang sama dengan main.json. Jika main. bicep ada di direktori yang sama, gunakan sakelar --force untuk menimpa file Bicep yang ada.

Untuk informasi selengkapnya tentang menggunakan perintah ini, lihat templat ARM JSON Decompile ke Bicep.

decompile-params

Perintah decompile-params mendekompresi file parameter JSON ke .bicepparam file parameter.

bicep decompile-params azuredeploy.parameters.json --bicep-file ./dir/main.bicep

Perintah ini mendekompilasi file parameter azuredeploy.parameters.json ke dalam file azuredeploy.parameters.bicepparam . Gunakan --bicep-file untuk menentukan jalur ke file Bicep (relatif terhadap file .bicepparam) yang direferensikan dalam deklarasi using.

format

Perintah format memformat file Bicep sehingga mengikuti konvensi gaya yang direkomendasikan. Anggap saja sebagai pemformat kode atau "lebih cantik" untuk file Bicep Anda. Ini memiliki fungsi yang sama dengan pintasan SHIFT+ALT+F di Visual Studio Code.

bicep format main.bicep

generate-params

Perintah generate-params membangun file parameter dari file Bicep yang diberikan dan memperbaruinya jika ada file parameter yang ada.

bicep generate-params main.bicep --output-format bicepparam --include-params all

Perintah ini membuat file parameter Bicep bernama main.bicepparam. File parameter berisi semua parameter dalam file Bicep, baik dikonfigurasi dengan nilai default atau tidak.

bicep generate-params main.bicep --outfile main.parameters.json

Perintah ini membuat file parameter bernama main.parameters.json. File parameter hanya berisi parameter tanpa nilai default yang dikonfigurasi dalam file Bicep.

pasang

Perintah install menambahkan CLI Bicep ke lingkungan lokal Anda, dan hanya tersedia melalui Azure CLI. Untuk informasi selengkapnya, lihat alat Install Bicep.

Untuk menginstal versi terkini, gunakan:

N/A

Untuk menginstal versi tertentu, gunakan perintah berikut:

N/A

jsonrpc

Perintah jsonrpc menjalankan CLI Bicep dengan antarmuka JSON-RPC. Dengan menggunakan antarmuka ini, Anda dapat berinteraksi secara terprogram dengan output terstruktur. Anda juga menghindari penundaan cold-start saat mengkompilasi beberapa file. Penyiapan ini mendukung pembuatan pustaka untuk berinteraksi dengan file Bicep secara terprogram dalam bahasa yang tidak .NET.

Format kawat untuk mengirim dan menerima input dan output dibatasi header. Ini menggunakan struktur berikut, di mana \r dan \n mewakili karakter pengembalian pengangkutan dan umpan baris:

Content-Length: <length>\r\n\r\n<message>\r\n\r\n
  • <length> adalah panjang <message> string, termasuk trailing \r\n\r\n.
  • <message> adalah pesan JSON mentah.

Contohnya:

Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n

Metode berikut tersedia melalui antarmuka JSON-RPC:

  • bicep/format

    Memformat file Bicep.

    • Permintaan:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bicep/format",
  "params": {
    "path": "/path/to/file.bicep"
  }
}

    • Respons:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "diagnostics": [],
    "contents": "param foo string\n\nresource storage 'Microsoft.Storage/storageAccounts@2025-01-01' = {\n  name: 'mystorageaccount'\n  location: 'East US'\n}\n"
  }
}

      Setelah berhasil, "success": true dikembalikan, dengan konten yang menyimpan sumber Bicep yang diformat. Jika gagal, "success": false dengan diagnostics menjelaskan kegagalan.

  • bicep/versi

    Mengembalikan versi CLI Bicep.

    • Permintaan:

      {
  "jsonrpc": "2.0",
  "id": 0,
  "method": "bicep/version",
  "params": {}
}

    • Respons:

      {
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "version": "0.24.211"
  }
}

Untuk metode dan badan permintaan dan respons yang tersedia, lihat ICliJsonRpcProtocol.cs. Misalnya membuat koneksi JSONRPC dan berinteraksi dengan file Bicep secara terprogram dengan menggunakan Node, lihat jsonrpc.test.ts.

Penggunaan untuk pipa bernama

Gunakan sintaks berikut untuk menyambungkan ke pipa bernama yang sudah ada sebagai klien JSONRPC:

bicep jsonrpc --pipe <named_pipe>`

<named_pipe> adalah pipa bernama yang sudah ada untuk menyambungkan klien JSONRPC.

Untuk menyambungkan ke pipa bernama di macOS atau Linux:

bicep jsonrpc --pipe /tmp/bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock

Untuk menyambungkan ke pipa bernama di Windows:

bicep jsonrpc --pipe \\.\pipe\\bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock`

Untuk contoh selengkapnya, lihat C# dan node.js.

Penggunaan untuk soket TCP

Gunakan sintaks berikut untuk menyambungkan ke soket TCP yang ada sebagai klien JSONRPC:

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> adalah nomor soket tempat klien JSONRPC terhubung.

Untuk menyambungkan ke soket TCP:

bicep jsonrpc --socket 12345

Penggunaan untuk stdin dan stdout

Untuk menjalankan antarmuka JSONRPC, gunakan sintaks berikut. Gunakan stdin dan stdout untuk pesan:

bicep jsonrpc --stdio

lint

Perintah lint mengembalikan kesalahan dan aturan linter pelanggaran file Bicep.

bicep lint main.bicep

Jika file Bicep Anda menyertakan modul yang mereferensikan registri eksternal, perintah lint secara otomatis memanggil restore. restore Perintah mendapatkan file dari registri dan menyimpannya di cache lokal.

Catatan

Perintah restore tidak menyegarkan cache. Untuk mengetahui informasi selengkapnya, lihat memulihkan.

Untuk mencegah pemulihan otomatis, gunakan sakelar --no-restore :

bicep lint --no-restore <bicep-file>

Proses lint dengan --no-restore sakelar gagal jika salah satu modul eksternal belum di-cache:

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

Ketika Anda mendapatkan kesalahan ini, jalankan perintah lint tanpa sakelar --no-restore atau jalankan bicep restore terlebih dahulu.

versi daftar

Perintah list-versions mengembalikan semua versi CLI Bicep yang tersedia. Gunakan perintah ini untuk melihat apakah Anda ingin meningkatkan atau menginstal versi baru. Perintah ini hanya tersedia melalui Azure CLI.

N/A

terbitkan

Perintah publish menambahkan modul ke registri. Registri kontainer Azure harus ada, dan penerbitan akun ke registri harus memiliki izin yang benar. Untuk informasi selengkapnya tentang menyiapkan registri modul, lihat Menggunakan registri privat untuk modul Bicep. Untuk menerbitkan modul, akun harus memiliki profil dan izin yang benar untuk mengakses registri. Anda dapat mengonfigurasi profil dan prioritas kredensial untuk mengautentikasi ke registri dalam file konfigurasi Bicep.

Setelah menerbitkan file ke registri, Anda dapat mereferensikannya dalam modul.

Anda harus memiliki Bicep CLI versi 0.14.X atau yang lebih baru untuk menggunakan perintah publish dan parameter --documentationUri/-d.

Untuk menerbitkan modul ke registri, gunakan:

bicep publish <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag> --documentationUri <documentation-uri>

Contohnya:

bicep publish storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html

Perintah publish tidak mengenali alias yang ditentukan dalam file bicepconfig.json. Berikan jalur modul lengkap.

Peringatan

Penerbitan ke target yang sama menimpa modul lama. Meningkatkan versi saat memperbarui.

memulihkan

Saat file Bicep Anda menggunakan modul yang Anda terbitkan ke registri, perintah restore mendapatkan salinan semua modul yang diperlukan dari registri. Ia menyimpan salinan tersebut dalam cache lokal. File Bicep hanya dapat dibuat ketika file eksternal tersedia di cache lokal. Biasanya, menjalankan pemulihan tidak diperlukan karena secara otomatis dipicu oleh proses build.

Untuk memulihkan modul eksternal ke cache lokal, akun harus memiliki profil dan izin yang benar untuk mengakses registri. Anda dapat mengonfigurasi profile dan prioritas kredensial untuk mengautentikasi ke registri dalam file konfigurasi Bicep.

Untuk menggunakan perintah restore, Anda harus memiliki Bicep CLI versi 0.14.X atau yang lebih baru.

Untuk memulihkan modul eksternal secara manual untuk file, gunakan:

bicep restore <bicep-file>

File Bicep yang Anda sediakan adalah file yang ingin Anda sebarkan. File harus berisi modul yang menautkan ke registri. Misalnya, Anda dapat memulihkan file berikut:

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

Anda menemukan cache lokal di:

  • Pada Windows

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

  • Di Linux

    /home/<username>/.bicep

  • Di Mac

    ~/.bicep

Perintah restore tidak merefresh cache jika modul sudah di-cache. Untuk menyegarkan cache, Anda dapat menghapus jalur modul dari cache atau menggunakan sakelar --force dengan restore perintah .

rekam jepret

Dengan menggunakan Bicep CLI v0.41.2 atau yang lebih baru, Anda dapat menggunakan perintah untuk membuat representasi deterministik yang dinormalisasi dari penyebaran Bicep dari file />

  • Visual Diffs: Melihat dengan tepat bagaimana refaktor (seperti memindahkan kode ke dalam modul) mengubah definisi sumber daya yang mendasar.
  • Ekspresi Kompleks: Memahami apa string atau variabel kompleks yang benar-benar dievaluasi sebelum penyebaran.
  • Validasi CI/CD: Secara otomatis menangkap perubahan yang tidak diinginkan dalam logika infrastruktur selama permintaan pull.

Membuat rekam jepret

Perintah ini menghasilkan .snapshot.json file. File ini "dinormalisasi", yang berarti menghapus kebisingan seperti batas modul sehingga Anda dapat fokus pada sumber daya itu sendiri.

bicep snapshot --mode overwrite <bicep-param-file>

File JSON berikut menunjukkan contoh rekam jepret:

{
  "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": []
}

Memvalidasi perubahan

Setelah membuat rekam jepret, jalankan perintah dalam mode validasi. Ini membandingkan kode Bicep Anda saat ini dengan rekam jepret yang disimpan dan menunjukkan perbedaan visual, sama seperti perintah apa tetapi sepenuhnya lokal.

bicep snapshot --mode validate <bicep-param-file>

Contoh output terlihat seperti:

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"

"Validasi rekam jepret gagal" menunjukkan perbedaan antara dua rekam jepret.

Bicep rekam jepret CLI dan Bagaimana-jika memiliki perbedaan berikut:

Fitur bicep snapshot az deployment group what-if
Eksekusi Lokal saja (Offline) Berbasis cloud (Online)
Perbandingan Membandingkan kode vs. file yang disimpan Membandingkan kode vs. status Azure langsung
Kecepatan Sangat cepat Lebih lambat (memerlukan panggilan API)
Kasus Penggunaan Pemfaktoran ulang dan pengujian logika Pemeriksaan pra-penyebaran akhir

Sediakan konteks

Saat menjalankan rekam jepret Bicep, CLI melakukan evaluasi lokal kode Anda. Karena tidak berbicara dengan Azure, cloud tidak dapat "meminta" cloud untuk ID Langganan Anda atau nama Grup Sumber Daya saat ini.

Jika kode Anda menggunakan fungsi lingkungan (seperti subscription().id), rekam jepret akan gagal atau mengembalikan tempat penampung kecuali Anda memberikan konteks tertentu melalui argumen CLI.

Untuk mensimulasikan lingkungan penyebaran nyata, Anda dapat meneruskan bendera berikut:

Argumen Kegunaan Contoh Nilai
--subscription-id Menggantikan nilai yang dikembalikan oleh subscription().subscriptionId 00000000-1111-2222-3333-444444444444
--resource-group Menggantikan nilai yang dikembalikan oleh resourceGroup().name my-production-rg
--location Mengatur lokasi default untuk deployment().location westeurope
--tenant-id Menggantikan nilai yang dikembalikan oleh tenant().tenantId 72f988bf-86f1-41af-91ab-2d7cd011db47
--management-group Menggantikan nilai yang dikembalikan oleh managementGroup().name my-corp-mg 
bicep snapshot main.bicepparam \
  --subscription-id 00000000-0000-0000-0000-000000000000 \
  --resource-group my-temp-rg \
  --location eastus \
  --mode overwrite

mutakhirkan

Perintah upgrade memperbarui versi terinstal Anda dengan versi terbaru. Perintah ini hanya tersedia melalui Azure CLI.

N/A

versi

Perintah version mengembalikan versi yang diinstal:

bicep --version

Jika Anda tidak menginstal CLI Bicep, Anda akan melihat pesan kesalahan yang menyatakan bahwa CLI Bicep tidak ditemukan.

Perintah menunjukkan nomor versi:

Bicep CLI version 0.29.45 (57a44c0230)

Langkah berikutnya

Untuk mempelajari selengkapnya tentang menyebarkan file Bicep, lihat:

  • Last updated on