Bicep のパラメーター

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

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

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

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

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

トレーニング リソース

段階的なガイダンスを通じてパラメーターの詳細を学習する場合は、「パラメーターを使用して再利用可能な Bicep テンプレートを構築する」を参照してください。

パラメーターの定義

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

@<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 ファイルでも使用されます。 .bicepparam ファイルでは、データ型が Bicep ファイルで定義されるため、データ型を指定する必要はありません。

param <parameter-name> = <value>

詳細については、「パラメータ ファイル」を参照してください。

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

param storageAccountConfig {
  name: string
  sku: string
}

詳しくは、ユーザー定義関数 をご覧ください。

既定値を設定する

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

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 という形で使用し、パラメーターの宣言の上に配置されます。 パラメーターに使用できるデコレーターを次の表に示します。

デコレーター	[適用対象]	引数	説明
[許可]	all	配列	このデコレーターを使用して、ユーザーが正しい値を指定するようにします。 このデコレーターは、param ステートメントでのみ使用できます。 プロパティが type または output ステートメントで定義されている値のセットのいずれかでなければならないことを宣言するには、共用体型の構文を使います。 共用体型の構文は、param ステートメントでも使用できます。
説明	all	string	パラメーターの使用方法を説明するテキスト。 説明は、ポータルを通じてユーザーに表示されます。
discriminator	オブジェクト	string	このデコレーターを使用して、正しいサブクラスが識別され管理されていることを確認します。 詳細については、「カスタム タグ付き共用体データ型」を参照してください。
maxLength	array、string	INT	文字列および配列のパラメーターの最大長。 この値は包含値です。
maxValue	INT	INT	整数パラメーターの最大値。 この値は包含値です。
metadata	all	object	パラメーターに適用するカスタム プロパティ。 description デコレーターに相当する description プロパティを含めることができます。
minLength	array、string	INT	文字列および配列のパラメーターの最小長。 この値は包含値です。
minValue	INT	INT	整数パラメーターの最小値。 この値は包含値です。
sealed	オブジェクト	なし	ユーザー定義データ型のプロパティ名が入力ミスである可能性が高い場合に、BCP089 を警告からエラーに昇格させます。 詳細については、「エラー レベルを昇格させる」を参照してください。
secure	string、object	なし	パラメーターを、セキュリティで保護されているとしてマークします。 セキュリティで保護されたパラメーターの値はデプロイ履歴に保存されず、ログに記録されません。 詳細については、「セキュリティで保護された文字列とオブジェクト」を参照してください。

デコレーターは、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

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

説明

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

@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 may contain numbers and lowercase letters only.
- 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

VS 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

Metadata

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

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

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

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

Sealed

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

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

文字列またはオブジェクトのパラメーターをセキュリティで保護されたものとマークすることができます。 セキュリティで保護されたパラメーターの値はデプロイ履歴に保存されず、ログに記録されません。

@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
  ...
}

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

関連する値は 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 を使用したデプロイ」および「Azure PowerShell を使用したデプロイ」を参照してください。