Membuat file parameter untuk penyebaran Bicep

Daripada meneruskan parameter sebagai nilai sebaris dalam skrip, Anda dapat menggunakan file parameter Bicep dengan .bicepparam ekstensi file atau file parameter JSON yang berisi nilai parameter. Artikel ini memperlihatkan cara membuat file parameter.

Catatan

File parameter Bicep hanya didukung di Bicep CLI versi 0.18.4 atau yang lebih baru, Azure CLI versi 2.47.0 atau yang lebih baru, dan Azure PowerShell versi 9.7.1 atau yang lebih baru.

Satu file Bicep dapat memiliki beberapa file parameter Bicep yang terkait dengannya. Namun, setiap file parameter Bicep ditujukan untuk satu file Bicep tertentu. Hubungan ini dibuat menggunakan using pernyataan dalam file parameter Bicep.

Anda dapat mengkompilasi file parameter Bicep ke dalam file parameter JSON untuk disebarkan dengan file Bicep. Lihat build-params. Anda juga dapat mendekompilasi file parameter JSON ke dalam file parameter Bicep. Lihat dekompresi-params.

File parameter

File parameter menggunakan format berikut:

File parameter Bicep

using '<path>/<file-name>.bicep'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>

Anda dapat menggunakan pernyataan penggunaan dengan file Bicep, templat ARM JSON, modul Bicep, dan spesifikasi templat. Contohnya:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

Untuk informasi selengkapnya, lihat pernyataan penggunaan.

Anda dapat menggunakan ekspresi dengan nilai default. Contohnya:

using 'main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

Anda dapat mereferensikan variabel lingkungan sebagai nilai parameter. Contohnya:

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

Anda dapat menentukan dan menggunakan variabel. Bicep CLI versi 0.21.X atau yang lebih tinggi diperlukan untuk menggunakan variabel dalam file .bicepparam. Berikut adalah beberapa contoh:

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

File parameter JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

Perlu dicatat bahwa file parameter menyimpan nilai parameter sebagai teks biasa. Untuk alasan keamanan, pendekatan ini tidak disarankan untuk nilai sensitif seperti kata sandi. Jika Anda harus meneruskan parameter dengan nilai sensitif, pertahankan nilai dalam brankas kunci. Alih-alih menambahkan nilai sensitif ke file parameter Anda, gunakan fungsi getSecret untuk mengambilnya. Untuk informasi lebih lanjut, lihat Gunakan Azure Key Vault untuk meneruskan nilai parameter aman selama penyebaran Bicep.

Format jenis parameter

Contoh berikut menunjukkan format jenis parameter yang berbeda: untai (karakter), bilangan bulat, boolean, array, dan objek.

File parameter Bicep

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

Gunakan sintaks Bicep untuk mendeklarasikan objek dan array.

File parameter JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

Nama file

File parameter Bicep

File parameter Bicep memiliki ekstensi file ..bicepparam

Untuk menyebarkan ke lingkungan yang berbeda, Anda membuat lebih dari satu file parameter. Saat Anda memberi nama file parameter, identifikasi penggunaannya seperti pengembangan dan produksi. Misalnya, gunakan main.dev.bicepparam dan main.prod.bicepparam untuk menyebarkan sumber daya.

File parameter JSON

Konvensi penamaan umum untuk file parameter adalah menyertakan parameter dalam nama file Bicep. Misalnya, jika file Bicep Anda diberi nama azuredeploy.bicep, file parameter Anda diberi nama azuredeploy.parameters.json. Konvensi penamaan ini membantu Anda melihat koneksi antara file Bicep dan parameter.

Untuk menyebarkan ke lingkungan yang berbeda, Anda membuat lebih dari satu file parameter. Saat Anda memberi nama file parameter, identifikasi penggunaannya seperti pengembangan dan produksi. Misalnya, gunakan azuredeploy.parameters-dev.json dan azuredeploy.parameters-prod.json untuk menyebarkan sumber daya.

Menentukan nilai parameter

Untuk mengetahui cara menentukan nama dan nilai parameter, buka file Bicep Anda. Lihat bagian parameter dari file Bicep. Contoh berikut menunjukkan parameter dari file Bicep yang disebut main.bicep.

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

Dalam file parameter, detail pertama yang perlu diperhatikan adalah nama setiap parameter. Nama parameter dalam file parameter Anda harus cocok dengan nama parameter dalam file Bicep Anda.

File parameter Bicep

using 'main.bicep'

param storagePrefix
param storageAccountType

Pernyataan ini using mengikat file parameter Bicep ke file Bicep. Untuk informasi selengkapnya, lihat menggunakan pernyataan.

Setelah mengetik kata kunci di Visual Studio Code, kata kunci param akan meminta parameter yang tersedia dan deskripsinya dari file Bicep yang ditautkan:

Saat mengarahkan mouse ke atas nama param, Anda dapat melihat jenis dan deskripsi data parameter.

File parameter JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

Perhatikan jenis parameter. Jenis parameter dalam file parameter Anda harus menggunakan jenis yang sama dengan file Bicep Anda. Dalam contoh ini, kedua jenis parameter adalah untai (karakter).

File parameter Bicep

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

File parameter JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": ""
    },
    "storageAccountType": {
      "value": ""
    }
  }
}

Periksa file Bicep untuk parameter dengan nilai default. Jika parameter memiliki nilai default, Anda dapat memberikan nilai dalam file parameter, tetapi tidak diperlukan. Nilai file parameter mengambil alih nilai default file Bicep.

File parameter Bicep

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep will use default value if not provided.

File parameter JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Bicep will use default value if not provided.
    }
  }
}

Catatan

Untuk komentar sebaris, Anda dapat menggunakan // atau /* ... */. Di Visual Studio Code, simpan file parameter dengan jenis file JSONC , jika tidak, Anda akan mendapatkan pesan kesalahan yang mengatakan "Komentar tidak diizinkan di JSON".

Periksa nilai Bicep yang diizinkan dan batasan apa pun seperti panjang maksimum. Nilai-nilai tersebut menentukan rentang nilai yang dapat Anda berikan untuk parameter. Dalam contoh ini, storagePrefix dapat memiliki maksimal 11 karakter dan storageAccountType harus menentukan nilai yang diizinkan.

File parameter Bicep

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

File parameter JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

Catatan

File parameter Anda hanya dapat berisi nilai untuk parameter yang ditentukan dalam file Bicep. Jika file parameter Anda berisi parameter tambahan yang tidak cocok dengan parameter file Bicep, Anda menerima kesalahan.

Membuat file parameter

Untuk menghasilkan file parameter, Anda memiliki dua opsi: baik melalui Visual Studio Code atau dengan menggunakan Bicep CLI. Kedua metode memungkinkan Anda memperoleh file parameter dari file Bicep. Dari Visual Studio Code, lihat Membuat file parameter. Dari Bicep CLI, lihat Membuat file parameter.

Membuat file parameter Bicep

Dari Bicep CLI, Anda dapat membuat file parameter Bicep ke dalam file parameter JSON. Untuk informasi selengkapnya, lihat File parameter build.

Menyebarkan file Bicep dengan file parameter

Azure CLI

Dari Azure CLI, Anda dapat meneruskan file parameter dengan penyebaran file Bicep Anda.

File parameter Bicep

Dengan Azure CLI versi 2.53.0 atau yang lebih baru, dan Bicep CLI versi 0.22.X atau yang lebih tinggi, Anda dapat menyebarkan file Bicep dengan menggunakan file parameter Bicep. using Dengan pernyataan dalam file parameter Bicep, tidak perlu memberikan --template-file sakelar saat menentukan file parameter Bicep untuk --parameters sakelar.

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

File parameter JSON

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

Anda dapat menggunakan parameter sebaris dan file parameter lokasi dalam operasi penyebaran yang sama. Contohnya:

File parameter Bicep

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

File parameter JSON

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json \
  --parameters storageAccountType=Standard_LRS

Untuk informasi selengkapnya, lihat Menyebarkan sumber daya dengan Bicep dan Azure CLI.

Azure PowerShell

Dari Azure PowerShell, teruskan file parameter lokal menggunakan TemplateParameterFile parameter .

File parameter Bicep

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

File parameter JSON

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json

Anda dapat menggunakan parameter sebaris dan file parameter lokasi dalam operasi penyebaran yang sama. Contohnya:

File parameter Bicep

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

File parameter JSON

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json `
  -storageAccountType Standard_LRS

Untuk informasi selengkapnya, lihat Menyebarkan sumber daya dengan Bicep dan Azure PowerShell. Untuk menyebarkan file .bicep , Anda memerlukan Azure PowerShell versi 5.6.0 atau yang lebih baru.

Parameter diutamakan

Anda dapat menggunakan parameter sebaris dan file parameter lokal dalam operasi penyebaran yang sama. Misalnya, Anda dapat menentukan beberapa nilai dalam file parameter lokal dan menambahkan nilai lain sebaris selama penyebaran. Jika Anda memberikan nilai untuk parameter dalam file parameter lokal dan sebaris, nilai sebaris lebih diutamakan.

Dimungkinkan untuk menggunakan file parameter JSON eksternal, dengan menyediakan URI ke file. File parameter Bicep eksternal saat ini tidak didukung. Saat menggunakan file parameter eksternal, Anda tidak dapat meneruskan nilai lain baik sebaris atau dari file lokal. Semua parameter sebaris diabaikan. Sediakan semua nilai parameter dalam file eksternal.

Konflik nama parameter

Jika file Bicep menyertakan parameter dengan nama yang sama dengan salah satu parameter dalam perintah PowerShell, PowerShell menyajikan parameter dari file Bicep dengan postfix FromTemplate. Misalnya, parameter bernama ResourceGroupName dalam file Bicep Anda bertentangan dengan parameter ResourceGroupName di cmdlet New-AzResourceGroupDeployment. Anda diminta memberikan nilai untuk ResourceGroupNameFromTemplate. Untuk menghindari kebingungan ini, gunakan nama parameter yang tidak digunakan untuk perintah penyebaran.

Langkah berikutnya

• Untuk informasi selengkapnya tentang cara menentukan parameter dalam file Bicep, lihat Parameter dalam Bicep.
• Untuk mendapatkan nilai sensitif, lihat Gunakan Azure Key Vault untuk melewati nilai parameter aman selama penyebaran.