Bicep のパラメーター

この記事では、Bicep ファイルでパラメーターを定義および使用する方法について説明します。 パラメーターに異なる値を指定することにより、さまざまな環境で Bicep ファイルを再利用できます。

Azure Resource Manager は、デプロイ操作を開始する前にパラメーター値を解決します。 パラメーターが使用されている場合、Resource Manager はそれを解決済みの値に置き換えます。

各パラメーターは、いずれかのデータ型に設定する必要があります。

Bicep では、最大 256 個のパラメーターを使用できます。 詳細については、「テンプレートの制限」を参照してください。

パラメーターのベスト プラクティスについては、「パラメーター」を参照してください。

トレーニング リソース

パラメーターに関する詳細なガイダンスについては、「 パラメーターを使用して再利用可能な Bicep ファイルをビルド する」Learn モジュールを参照してください。

パラメーターの定義

それぞれのパラメーターには、名前とデータ型があります。 パラメーターには、必要に応じて既定値を指定できます。

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

パラメーターに、同じスコープ内の変数、リソース、出力、またはその他のパラメーターと同じ名前を付けることはできません。

次に示したのは、基本的なパラメーター宣言の例です。

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

param キーワードは .bicepparam ファイルの中でも使用されています。 Bicep ファイルの中で定義されているため、.bicepparam ファイルの中でデータ型を指定する必要はありません。

param <parameter-name> = <value>

ユーザー定義型の式は、param ステートメントの type 句として使用できます。 次に例を示します。

param storageAccountConfig {
  name: string
  sku: string
}

詳細については、「 Bicep のユーザー定義データ型」を参照してください。

既定値を設定する

パラメーターの既定値を指定できます。 既定値は、デプロイ時に値が指定されない場合に使用されます。

param demoParam string = 'Contoso'

既定値を指定した式を使用できます。 他のパラメーター プロパティと共に式を使用することはできません。 パラメーター セクションで、 reference 関数または list 関数を使用することはできません。 これらの関数はリソースのランタイム状態を取得し、パラメーターが解決されたときにデプロイ前に実行することはできません。

param ___location string = resourceGroup().___location

別のパラメーター値を使用して既定値を作成できます。 次のテンプレートを使用すると、サイト名からホスト プラン名が作成されます。

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

ただし、既定値として変数を参照することはできません。

デコレーターを使用する

パラメーターでは、制約またはメタデータにデコレーターを使用します。 デコレーターは @expression という形で使用し、パラメーターの宣言の上に配置されます。 次の表に、パラメーターに使用できるデコレーターを示します。

デコレーターは、sys 名前空間にあります。 このデコレーターを同じ名前の別の項目と区別する必要がある場合は、デコレータの前に「sys」を付けます。 たとえば、Bicep ファイルに description という名前のパラメーターが含まれている場合、description デコレーターを使用するときに、sys 名前空間を追加する必要があります。

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

使用できる値

パラメーターに使用できる値を定義できます。 使用できる値は配列で指定します。 使用できる値の 1 つではない値がパラメーターに渡された場合、検証時にデプロイは失敗します。

@allowed([
  'one'
  'two'
])
param demoEnum string

配列パラメーターの許容値を定義する場合、実際の値には、許容値の任意のサブセットを指定できます。

説明

指定する値をユーザーが理解できるように、パラメーターに説明を追加します。 ユーザーが Azure portal を使用してテンプレートをデプロイすると、説明のテキストがそのパラメーターのヒントとして自動的に使用されます。 パラメーター名から推測できる情報よりもテキストからわかる情報の方が多い場合にのみ、説明を追加します。

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

Markdown 形式のテキストは、説明のテキストに使用できます。

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and can only contain numbers and lowercase letters.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

Visual Studio Code の中の storageAccountName にカーソルを合わせると、書式付きテキストが表示されます。

テキストが適切な Markdown 書式に従っていることを確認します。そうしないと、レンダリング時に正しく表示されないことがあります。

識別子

「カスタム タグ付き共用体データ型」を参照してください。

整数の制約

整数パラメーターの最小値と最大値を設定できます。 一方または両方の制約を設定できます。

@minValue(1)
@maxValue(12)
param month int

長さの制限

文字列と配列のパラメーターの最小長と最大長を指定できます。 一方または両方の制約を設定できます。 文字列の場合、長さは文字数を示します。 配列の場合、長さは配列内の項目数を示します。

次の例では、2 つのパラメーターを宣言しています。 1 つのパラメーターは、3 ~ 24 文字のストレージ アカウント名用です。 もう 1 つのパラメーターは、1 ~ 5 個の項目が必要な配列です。

@minLength(3)
@maxLength(24)
param storageAccountName string

@minLength(1)
@maxLength(5)
param appNames array

メタデータ

パラメーターに適用するカスタム プロパティがある場合は、メタデータ デコレーターを追加します。 メタデータ内で、カスタムの名前と値を持つオブジェクトを定義します。 メタデータに対して定義するオブジェクトには、任意の名前と型のプロパティを含めることができます。

このデコレーターを使用して、 説明に追加しても意味のないパラメーターに関する情報を追跡できます。

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

別のデコレーターと競合するプロパティを持つ @metadata() デコレーターを指定すると、そのデコレーターは常に @metadata() デコレーター内の何よりも優先されるため、 @metadata() 値内の競合するプロパティは冗長になり、置き換えられます。 詳細については、「 リンター ルール - 競合するメタデータなし」を参照してください。

密封

「エラー レベルを昇格させる」を参照してください。

セキュリティで保護されたパラメーター

文字列またはオブジェクトのパラメーターをセキュリティで保護されたものとマークすることができます。 パラメーターが @secure()で修飾されている場合、Azure Resource Manager はパラメーター値を機密性の高い値として扱い、デプロイ履歴、Azure Portal、またはコマンド ライン出力に記録または表示されないようにします。

@secure()
param demoPassword string

@secure()
param demoSecretObject object

「パラメーターの既定値をセキュリティで保護する」、「入れ子になったデプロイでのパラメーターのセキュリティ保護」、「パラメーター内のシークレットをセキュリティで保護する」など、このデコレーターに関連するいくつかのリンター ルールがあります。

パラメーターを使用する

パラメーターの値を参照するには、パラメーター名を使用します。 次の例では、キー コンテナー名のパラメーター値を使用します。

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

@secure()デコレーターは、ARM テンプレートの secureString 型と secureObject 型と一致するため、文字列型またはオブジェクト型のパラメーターに対してのみ有効です。 配列または数値を安全に渡すには、それらを secureObject でラップするか、secureString としてシリアル化します。

パラメーターとしてオブジェクトを使用する

関連する値は 1 つのオブジェクトとして渡すことにより整理しやすくなります。 この方法により、テンプレート内のパラメータ数も減少します。

次の例は、オブジェクトであるパラメーターを示しています。 既定値は、オブジェクトの予想されるプロパティを示しています。 これらのプロパティは、デプロイするリソースを定義するときに使用されます。

param vNetSettings object = {
  name: 'VNet1'
  ___location: 'eastus'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: vNetSettings.name
  ___location: vNetSettings.___location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

次のステップ

• パラメーターに使用できるプロパティの詳細については、 Bicep ファイルの構造と構文に関するページを参照してください。
• パラメーター値をファイルとして渡す方法については、「 Bicep デプロイ用のパラメーター ファイルを作成する」を参照してください。
• デプロイ時にパラメーター値を指定する方法については「Azure CLI を使用して Bicep ファイルをデプロイする」および「Azure PowerShell を使用して Bicep ファイルをデプロイする」を参照してください。