Bicep のパラメーター

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

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

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

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

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

トレーニング リソース

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

宣言

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

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 という形で使用し、パラメーターの宣言の上に配置されます。 パラメータが機密であることをマークしたり、使用できる値を指定したり、文字列の最小長と最大長を設定したり、整数の最小値と最大値を設定したり、パラメータの説明を記載したりすることができます。

次の例は、デコレーターの 2 つの一般的な用途を示しています。

@secure()
param demoPassword string

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

次の表では、使用できるデコレーターとそれらの使用方法について説明します。

デコレーター	[適用対象]	引数	説明
[許可]	all	配列	このデコレーターを使用して、ユーザーが正しい値を指定するようにします。 このデコレーターは、param ステートメントでのみ使用できます。 プロパティが type または output ステートメントで定義されている値のセットのいずれかでなければならないことを宣言するには、共用体型の構文を使います。 共用体型の構文は、param ステートメントでも使用できます。
説明	all	string	パラメーターの使用方法を説明するテキスト。 説明は、ポータルを通じてユーザーに表示されます。
maxLength	array、string	INT	文字列および配列のパラメーターの最大長。 この値は包含値です。
maxValue	INT	INT	整数パラメーターの最大値。 この値は包含値です。
metadata	all	object	パラメーターに適用するカスタム プロパティ。 description デコレーターに相当する description プロパティを含めることができます。
minLength	array、string	INT	文字列および配列のパラメーターの最小長。 この値は包含値です。
minValue	INT	INT	整数パラメーターの最小値。 この値は包含値です。
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

使用可能なデコレーターについては、次のセクションで説明します。

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

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

@secure()
param demoPassword string

@secure()
param demoSecretObject object

使用できる値

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

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

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

長さの制限

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

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

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

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

整数の制約

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

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

説明

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

@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 形式に従っていることを確認します。そうでない場合、レンダリング時に正しく表示されないことがあります。

Metadata

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

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

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

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

パラメーターを使用する

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

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 を使用したデプロイ」を参照してください。