パラメーターを理解する

  • 8 分

"パラメーター" を使用すると、デプロイ時に Bicep テンプレートに情報を提供できます。 テンプレート内でパラメーターを宣言することで、Bicep テンプレートを柔軟かつ再利用可能にできます。

"デコレーター" を使用すると、パラメーターに制約とメタデータをアタッチできるようになり、テンプレートのユーザーがどのような情報を提供する必要があるかを理解するのに役立ちます。

このユニットでは、パラメーターとデコレーターについて学習します。

パラメーターを宣言する

Bicep テンプレートの場合、param キーワードを使用してパラメーターを宣言します。 これらの宣言は、テンプレート ファイルのどこにでも書くことができますが、通常は Bicep のコードを読みやすくするために、ファイルの先頭に書くのが良いでしょう。

パラメーターを宣言する方法を次に示します。

param environmentName string

それぞれの部分がどのように機能するか見てみましょう。

  • param は、Bicep に対してパラメーターを宣言していることを示します。

  • environmentName は、パラメーターの名前です。 パラメーターには任意の名前を付けられますが、テンプレートのユーザーにとってわかりやすい名前にする必要があります。 同じテンプレート内で、その名前を使用してパラメーターを参照することもできます。 パラメーター名は一意である必要があります。 同じ Bicep ファイル内の変数やリソースと同じ名前にすることはできません。

    ヒント

    パラメーター宣言には名前付け規則のベスト プラクティスを使用します。 適切な名前規則を使用すると、テンプレートが読みやすく、理解しやすくなります。 明確でわかりやすい名前を使用し、名前付けの方法に一貫性を保ってください。

  • string はパラメーターの型を表します。

    ヒント

    テンプレートで使用するパラメーターは慎重に検討してください。 デプロイによって変わる設定には、パラメーターを使ってみてください。 変数やハードコーディングされた値は、デプロイによって変わらない設定に使用できます。

既定値を追加する

テンプレート内のパラメーターには既定値を割り当てることができます。 既定値を割り当てることで、パラメーターをオプションにすることができます。 パラメーターの値を指定せずにテンプレートがデプロイされた場合、既定値が割り当てられます。

既定値を追加する方法を次に示します。

param environmentName string = 'dev'

パラメーター environmentName には、既定値の dev が割り当てられます。

既定値には式を使用することができます。 location という名前の文字列パラメーターの既定値が、現在のリソース グループの場所に設定された例を次に示します。

param location string = resourceGroup().location

ヒント

使用する既定値には注意してください。 誰かが既定値を使用して Bicep ファイルをデプロイしても安全であることを確認してください。 たとえば、テスト環境にテンプレートをデプロイする人が不必要に大きなコストを負担しないように、安価な価格レベルと SKU を使用することを検討します。

パラメーターの型を理解する

パラメーターを宣言する場合は、パラメーターに含まれる情報の種類を Bicep に指示する必要があります。 Bicep により、パラメーターに割り当てられた値がパラメーターの型に適合することが確認されます。

Bicep のパラメーターには、次のいずれかの型を指定できます。

  • string: 任意のテキストを入力できます。
  • int: 数値を入力できます。
  • bool: ブール値 (true または false) 値を表します。
  • object と array: 構造化データとリストを表します。

オブジェクト

オブジェクト パラメーターを使うと、構造化データを 1 か所にまとめることができます。 オブジェクトには、異なる型の複数のプロパティを含めることができます。 オブジェクトは、リソース定義内、変数内、または Bicep ファイルの中の式内で使用できます。 オブジェクトの例を次に示します。

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

このパラメーターは、2 つの文字列プロパティ name および tier と、整数プロパティ capacity を持つオブジェクトです。 各プロパティが単独の行になっていることに注意してください。

テンプレートでパラメーターを参照する場合は、次の例のように、ドットの後にプロパティの名前を指定することで、オブジェクトの個々のプロパティを選択できます。

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

重要

オブジェクト内の各プロパティの型を指定するわけではないことに注意してください。 ただし、プロパティの値を使用する場合は、その型が想定されるものに一致する必要があります。 前の例では、App Service プラン SKU の名前とレベルの両方が文字列である必要があります。

オブジェクト パラメーターを使用する別の例として、リソース タグの指定があります。 デプロイするリソースにカスタム タグ メタデータをアタッチできます。これを使用して、リソースに関する重要な情報を識別できます。

タグは、どのチームがリソースを所有しているか、リソースが運用環境に属しているか非運用環境に属しているかなどを追跡するシナリオで役立ちます。 通常は、環境ごとに異なるタグを使用しますが、テンプレート内のすべてのリソースで同じタグ値を再利用すると便利です。 このため、次の例のように、オブジェクト パラメーターにはリソース タグの使用が適しています。

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Bicep ファイルでリソースを定義すると、tags プロパティを定義するところではどこでも再利用できます。

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

配列

配列は、項目のリストです。 例として、文字列値の配列を使用して、Azure Monitor アクション グループのメール アドレスのリストを宣言することができます。 また、オブジェクトの配列を使用して、仮想ネットワークのサブネットのリストを表すこともできます。

Note

配列に含める必要がある個々の項目の型を指定することはできません。 たとえば、配列に文字列を含める必要があることを指定することはできません。

具体的な例を考えてみましょう。 Azure Cosmos DB を使用すると、複数のリージョンにまたがるデータベース アカウントを作成し、データのレプリケーションを自動的に処理できます。 新しいデータベース アカウントをデプロイする場合は、アカウントをデプロイする Azure リージョンのリストを指定する必要があります。 多くの場合、環境ごとに異なる場所のリストを用意する必要があります。 たとえば、テスト環境ではコストを削減するために、1 つまたは 2 つの場所しか使用しないことがあります。 しかし、運用環境では、複数の場所を使用するかもしれません。

場所のリストを指定する配列パラメーターを作成することができます。

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

ヒント

上記の例は、オブジェクトの配列です。 各オブジェクトには、locationName プロパティがあります。これは Azure Cosmos DB に必要なものです。 Visual Studio Code でリソース定義を操作する場合、リソースのプロパティを入力することで、Bicep ツールから IntelliSense を使用できるようになります。 この方法を使用して、いくつかの例の値を作成できます。 構成に問題がなければ、Bicep コードのそのセクションをパラメーターに移動します。 このようにして、リソースが正しく構成されていることを確認しながら、ハードコーディングされたプロパティを、各デプロイ中に変更できるパラメーターに置き換えることができます。

Azure Cosmos DB リソースを宣言すると、配列パラメーターを参照できるようになります。

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

そうすると、パラメーター値の変更により、開発環境に応じて異なるパラメーター値を使用することが簡単になります。 また、元のテンプレートを変更せずに、さまざまなパラメーター値を指定する方法もわかるようになります。

使用できる値のリストを指定する

場合によっては、パラメーターに特定の値が含まれていることを確認する必要があります。 たとえば、チームで、Premium v3 SKU を使用して運用 App Service プランをデプロイする必要があると判断するかもしれません。 この規則を適用するには、@allowed パラメーター デコレーターを使用します。 "パラメーター デコレーター" を使用すると、パラメーター値が何でなければならないかという情報を Bicep に指定できます。 次に、appServicePlanSkuName という名前の文字列パラメーターを制限して、いくつかの特定の値のみを割り当てることができるようにする方法を示します。

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

ヒント

@allowed デコレーターの使用は控えめにしてください。 このデコレーターを広く使用すると、リストを最新の状態に保つことができない場合に、有効なデプロイがブロックされる可能性があります。 上記の例では、運用環境での Premium v3 SKU のみが許可されています。 同じテンプレートを使用して、より安価な非運用環境をデプロイする必要がある場合、使用できる値のリストによって、使う必要がある他の SKU を使用できなくなることがあります。

パラメーターの長さと値を制限する

文字列パラメーターを使用する場合は、多くの場合、文字列の長さを制限する必要があります。 Azure リソースの名前付けの例を考えてみましょう。 すべての Azure リソースの種類には、名前の長さに関する制限があります。 後でデプロイ中にエラーが発生しないように、名前付けを制御するパラメーターには最小と最大の文字数を指定することをお勧めします。 @minLength と @maxLength の各デコレーターを使用すると、パラメーターに許可する文字数の最小値と最大値を指定できます。

次の例では、storageAccountName という名前の文字列パラメーターを宣言し、その長さを 5 文字から 24 文字までとしています。

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

このパラメーターには、2 つのデコレーターが含まれています。 複数のデコレーターを 1 つのパラメーターに適用するには、各デコレーターをそれぞれの行に記述します。

Note

配列パラメーターに @minLength と @maxLength の各デコレーターを適用して、配列に格納できる項目の数を制御することもできます。

数値パラメーターを使用する場合、特定の範囲内の値が必要になることがあります。 たとえば、おもちゃ会社で、App Service プランをデプロイするときは、常に少なくとも 1 つのインスタンスをデプロイする必要があるが、そのプランのインスタンスは 10 個以下にする必要があると判断するとします。 その要件を満たすには、@minValue と @maxValue の各デコレーターを使用して、使用できる最小値と最大値を指定します。 次の例では、値が 1 から 10 (両端を含む) の範囲だけである整数パラメーター appServicePlanInstanceCount を宣言します。

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

パラメーターに説明を追加する

パラメーターは、テンプレートを他のユーザーが再利用できるようにするための優れた方法です。 テンプレートを使用する場合は、各パラメーターが何をするものかを理解して、適切な値を指定する必要があります。 Bicep には、ユーザーが判読できる方法でパラメーターの目的を文書化できるように、@description デコレーターが用意されています。

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

パラメーターには説明を記述することをお勧めします。 説明が役に立つようにして、テンプレートに必要なパラメーター値をどのようなものにするべきかという内容に関する重要な情報を記述してください。

Note

テンプレート スペックを使用する場合のように、ユーザーが Azure portal で Bicep テンプレートをデプロイできるようにすることができます。 ポータルでは、パラメーターの説明やその他のデコレーターを使用して、パラメーター値をどのようなものにする必要があるのかユーザーにわかりやすくしています。