Buat file parameter untuk penyebaran Bicep

File parameter Bicep memungkinkan Anda menentukan nilai dalam file individual yang kemudian diteruskan ke file Anda main.bicep . File parameter mengekspos nilai yang dapat berubah dari langganan, lingkungan, dan/atau wilayah tertentu. Memanfaatkan file parameter akan mendorong konsistensi dalam penyebaran IaC Anda sekaligus memberikan fleksibilitas. Beberapa fleksibilitas ini mungkin memungkinkan organisasi untuk memanfaatkan keuntungan biaya dengan menyesuaikan ukuran lingkungan nonproduksi mereka sambil mempertahankan infrastruktur inti yang sama.

File parameter ini juga membantu mengaktifkan pendekatan penyebaran CI/CD yang disederhanakan. Setiap file parameter berada di bawah kontrol sumber dan diteruskan ke langkah-langkah penyebaran otomatis yang sesuai. File parameter ini memastikan pengalaman penyebaran yang konsisten.

Artikel ini memperlihatkan kepada Anda cara membuat file parameter, yang dapat Anda gunakan alih-alih meneruskan parameter sebagai nilai sebaris dalam skrip Anda. Anda dapat menggunakan file parameter Bicep dengan .bicepparam ekstensi file atau file parameter JSON yang berisi nilai 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. Fitur using none ini didukung di Bicep CLI versi 0.31.0 atau yang lebih baru.

Satu file Bicep dapat dikaitkan dengan beberapa file parameter. Namun, setiap file parameter biasanya terhubung ke satu file Bicep tertentu—kecuali jika using none ditentukan. Asosiasi ini dibuat menggunakan using pernyataan dalam file parameter.

Anda dapat mengkompilasi file parameter Bicep ke dalam file parameter JSON yang dapat Anda sebarkan dengan menggunakan file Bicep. Untuk informasi selengkapnya, lihat build-params . Anda juga dapat mendekompilasi file parameter JSON menjadi file parameter Bicep. Untuk informasi selengkapnya, lihat decompile-params .

Berkas parameter

File parameter menggunakan format berikut:

Parameter File Bicep

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

type <user-defined-data-type-name> = <type-expression>

var <variable-name> <data-type> = <variable-value>

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

Anda dapat menerapkan using pernyataan dengan menggunakan file Bicep, templat JSON Azure Resource Manager, modul Bicep, dan spesifikasi templat. Contohnya:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:avm/res/storage/storage-account:0.9.0' 
...

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

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

Untuk informasi selengkapnya, lihat Menggunakan pernyataan.

Anda dapat menerapkan using none pernyataan untuk menunjukkan bahwa file parameter tidak terkait dengan templat Bicep tertentu selama penulisan atau kompilasi. Ini memisahkan file parameter dari templat tertentu, memungkinkan fleksibilitas yang lebih besar dalam bagaimana parameter ditentukan dan digunakan di seluruh penyebaran. Untuk informasi selengkapnya, lihat Menggunakan pernyataan tidak ada.

Anda dapat menggunakan ekspresi sebagai nilai parameter. 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. Anda harus menggunakan Bicep CLI versi 0.21.X atau yang lebih baru untuk menggunakan variabel dalam .bicepparam file. Lihat contoh berikut:

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
}

Anda dapat menentukan jenis data yang ditentukan pengguna. Contohnya:

using './main.bicep'

// Define a reusable type for tags with optional properties
type TagValues = {
  environment: 'dev' | 'test' | 'production'
  project: string
}

var tagsExample TagValues = {
  environment: 'dev'
  project: 'bicep-sample'
}

param tags = tagsExample

File parameter dari 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>"
    }
  }
}

Catatan

File parameter menyimpan nilai parameter sebagai teks biasa. Untuk alasan keamanan, kami tidak merekomendasikan penggunaan pendekatan ini dengan nilai sensitif seperti kata sandi.

Jika Anda perlu meneruskan parameter dengan nilai sensitif, Anda harus menyimpan nilai di dalam brankas kunci. Alih-alih menambahkan nilai sensitif ke file parameter Anda, gunakan getSecret fungsi untuk mengambilnya. Untuk informasi selengkapnya, lihat Menggunakan Azure Key Vault untuk meneruskan rahasia sebagai parameter dalam penyebaran Bicep.

Format jenis parameter

Contoh berikut menunjukkan format berbagai jenis parameter: string, bilangan bulat, Boolean, array, dan objek.

Parameter File 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 dari 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

Parameter File Bicep

Ekstensi file untuk file parameter Bicep adalah .bicepparam.

Untuk menyebarkan ke beberapa lingkungan, Anda membuat lebih dari satu file parameter. Saat Anda menggunakan beberapa file parameter, beri label sesuai dengan penggunaannya. Misalnya, untuk menyebarkan sumber daya, gunakan label main.dev.bicepparam untuk pengembangan dan label main.prod.bicepparam untuk produksi.

File parameter dari JSON

Konvensi penamaan umum untuk file parameter adalah menyertakan parameter dalam nama file Bicep. Misalnya, jika file Bicep Anda diberi nama azuredeploy.bicep, maka 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 menggunakan beberapa file parameter, beri label sesuai dengan penggunaannya. Misalnya, untuk menyebarkan sumber daya, gunakan label azuredeploy.parameters-dev.json untuk pengembangan dan label azuredeploy.parameters-prod.json untuk produksi.

Menentukan nilai parameter

Untuk menentukan cara menentukan nama dan nilai parameter, buka file Bicep Anda. Lihat bagian parameter-parameter dari file Bicep. Contoh berikut menunjukkan parameter dari file Bicep bernama main.bicep:

@maxLength(11)
param storagePrefix string

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

Dalam file parameter, cari nama setiap parameter. Nama parameter dalam file parameter Anda harus cocok dengan nama parameter dalam file Bicep Anda.

Parameter File Bicep

using 'main.bicep'

param storagePrefix
param storageAccountType

Pernyataan using menghubungkan file parameter Bicep dengan file Bicep. Untuk informasi selengkapnya, lihat Menggunakan pernyataan.

Saat Anda 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 param nama, Anda dapat melihat jenis dan deskripsi data parameter.

File parameter dari JSON

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

Tinjau jenis parameter, karena jenis parameter dalam file parameter Anda harus menggunakan jenis yang sama dengan file Bicep Anda. Dalam contoh ini, kedua jenis parameter adalah string:

Parameter File Bicep

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

File parameter dari 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 yang menyertakan nilai default. Jika parameter memiliki nilai default, Anda dapat memberikan nilai dalam file parameter, tetapi tidak diperlukan. Nilai file parameter menggantikan nilai default file Bicep.

Parameter File Bicep

using 'main.bicep'

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

File parameter dari 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 uses default value if not provided.
    }
  }
}

Catatan

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

Untuk melihat apakah ada batasan seperti panjang maksimum, periksa nilai file Bicep yang diizinkan. Nilai yang diizinkan 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.

Parameter File Bicep

using 'main.bicep'

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

File parameter dari 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.

Hasilkan file parameter

Anda dapat membuat file parameter dengan menggunakan Visual Studio Code atau Bicep CLI. Kedua alat memungkinkan Anda menggunakan file Bicep untuk menghasilkan file parameter. Lihat Menghasilkan file parameter untuk metode Visual Studio Code dan Menghasilkan file parameter untuk metode Bicep CLI.

Membuat file parameter Bicep

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

Melakukan penyebaran file Bicep dengan file parameter

Azure CLI

Dari Azure CLI, Anda dapat meneruskan file parameter saat melakukan deployment file Bicep Anda.

Parameter File Bicep

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

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

File parameter dari JSON

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

Anda dapat menggunakan parameter inline dan berkas parameter lokasi dalam operasi penyebaran yang sama. Contohnya:

Parameter File Bicep

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

File parameter dari 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 file Bicep dengan menggunakan Azure CLI.

Azure PowerShell

Dari Azure PowerShell, gunakan parameter TemplateParameterFile untuk meneruskan file parameter lokal.

Parameter File Bicep

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

File parameter dari JSON

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

Anda dapat menggunakan parameter inline dan berkas parameter lokasi dalam operasi penyebaran yang sama. Contohnya:

Parameter File Bicep

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

File parameter dari 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 file Bicep dengan Azure PowerShell. Untuk menyebarkan .bicep file, 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 suatu parameter baik dalam file parameter lokal maupun nilai yang diberikan secara sebaris, maka nilai yang diberikan secara sebaris lebih diutamakan.

Meskipun file parameter Bicep eksternal saat ini tidak didukung, Anda dapat menggunakan file parameter JSON eksternal dengan menyediakan URI ke file. Saat Anda menggunakan file parameter eksternal, berikan semua nilai parameter dalam file eksternal. Saat menggunakan file eksternal, Anda tidak dapat meneruskan nilai lain sebaris atau dari file lokal, dan semua parameter sebaris diabaikan.

Konflik pada nama parameter

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

Konten terkait

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