Bicep のユーザー定義データ型

Bicep でユーザー定義データ型を作成する方法を学習します。 システム定義データ型については、データ型に関するページをご覧してください。

この機能を使用するには、Bicep CLI バージョン 0.12.X 以上が必要です。

型を定義する

type ステートメントを使用することで、ユーザー定義データ型を作成できます。 また、一部の場所で型式を使用してカスタム型を定義することもできます。

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

@allowed デコレーターは、param ステートメントでのみ許可されています。 type 内で定義済みの値のセットと共に型を宣言するには、共用体型構文を使用します。

有効な型式は次のとおりです。

• シンボリック参照は、"アンビエント" 型 (string または int など) や type ステートメントで宣言されるユーザー定義型シンボルを参照する識別子です。

  // Bicep data type reference
  type myStringType = string
  
  // user-defined type reference
  type myOtherStringType = myStringType
  

• 文字列、整数、ブールなどのプリミティブ リテラルは、有効な型式です。 次に例を示します。

  // a string type with three allowed values.
  type myStringLiteralType = 'bicep' | 'arm' | 'azure'
  
  // an integer type with one allowed value
  type myIntLiteralType = 10
  
  // an boolean type with one allowed value
  type myBoolLiteralType = true
  

• 以下のように任意の有効な型の式に [] を追加することで、配列型を定義できます。

  // A string type array
  type myStrStringsType1 = string[]
  // A string type array with three allowed values
  type myStrStringsType2 = ('a' | 'b' | 'c')[]
  
  type myIntArrayOfArraysType = int[][]
  
  // A mixed-type array with four allowed values
  type myMixedTypeArrayType = ('fizz' | 42 | {an: 'object'} | null)[]
  

• オブジェクト型には、中かっこの間に 0 個以上のプロパティが含まれます。

  type storageAccountConfigType = {
    name: string
    sku: string
  }
  

  オブジェクト内の各プロパティは、キーと値で構成され、コロン : で区切られます。 キーには、引用符で囲まれた非識別子の値を持つ任意の文字列を指定でき、値には任意の型の式を指定できます。

  プロパティ値の後に省略可能のマーカー (?) がない限り、プロパティは必須です。 たとえば、次の例の sku プロパティは省略可能です。

  type storageAccountConfigType = {
    name: string
    sku: string?
  }
  

  プロパティではデコレーターを使用できます。 * は、すべての値で制約を要求するために使用できます。 * を使用する場合でも、追加のプロパティを定義できます。 この例では、id という名前の int 型のキーを必要とし、オブジェクト内の他のすべてのエントリは 10 文字以上の長さの文字列値でなければならないオブジェクトを作成します。

  type obj = {
    @description('The object ID')
    id: int
  
    @description('Additional properties')
    @minLength(10)
    *: string
  }
  

  次の例は、共用体型の構文を使用して、定義済みの値のセットを一覧表示する方法を示しています。

  type directions = 'east' | 'south' | 'west' | 'north'
  
  type obj = {
    level: 'bronze' | 'silver' | 'gold'
  }
  

  再帰

  オブジェクト型では、少なくとも再帰ポイントへのパスの一区間が省略可能である限り、直接または間接再帰を使用できます。 たとえば、次の例の myObjectType 定義は、直接再帰の recursiveProp プロパティが省略可能であるため有効です。

  type myObjectType = {
    stringProp: string
    recursiveProp: myObjectType?
  }
  

  ただし、次の型定義は、level1、level2、level3、level4、または level5 のいずれも省略可能ではないため、有効ではありません。

  type invalidRecursiveObjectType = {
    level1: {
      level2: {
        level3: {
          level4: {
            level5: invalidRecursiveObjectType
          }
        }
      }
    }
  }
  

• Bicep 単項演算子は、整数またはブール リテラル、あるいは整数またはブール リテラル型シンボルへの参照と共に使用できます。

  type negativeIntLiteral = -10
  type negatedIntReference = -negativeIntLiteral
  
  type negatedBoolLiteral = !true
  type negatedBoolReference = !negatedBoolLiteral
  

• 共用体には、任意の個数のリテラル型の式を含めることができます。 共用体型は Bicep の使用できる値の制約に変換されるため、リテラルのみがメンバーとして許可されます。

  type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
  type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
  

型式は、type ステートメント内で使用するだけでなく、ユーザー定義のデータ型を作成するために以下の場所でも使用できます。

• param ステートメントの type 句として。 次に例を示します。

  param storageAccountConfig {
    name: string
    sku: string
  }
  

• オブジェクト型プロパティの : の後。 次に例を示します。

  param storageAccountConfig {
   name: string
    properties: {
      sku: string
    }
  } = {
    name: 'store$(uniqueString(resourceGroup().id)))'
    properties: {
      sku: 'Standard_LRS'
    }
  }
  

• 配列型式の [] の前。 次に例を示します。

  param mixedTypeArray ('fizz' | 42 | {an: 'object'} | null)[]
  

ストレージ アカウントを作成するための一般的な Bicep ファイルは次のようになります。

param location string = resourceGroup().location
param storageAccountName string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
])
param storageAccountSKU string = 'Standard_LRS'

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountSKU
  }
  kind: 'StorageV2'
}

ユーザー定義データ型を使用すると、次のようになります。

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

デコレーターを使用する

デコレーターは @expression 形式で記述され、ユーザー定義データ型の宣言の上に配置されます。 次の表に、ユーザー定義データ型で使用できるデコレーターを示します。

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

識別子

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

説明

ユーザー定義データ型に説明を追加します。 プロパティではデコレーターを使用できます。 次に例を示します。

@description('Define a new object type.')
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}

説明のテキストとして Markdown 形式のテキストを使用できます。

Export

@export() を使用して、ユーザー定義データ型を他の Bicep ファイルと共有します。 詳細については、変数、型、関数のエクスポートに関するページを参照してください。

整数の制約

整数型の最小値と最大値を設定できます。 一方または両方の制約を設定できます。

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

長さの制限

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

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

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

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

Metadata

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

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

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

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

Sealed

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

安全な型

文字列またはオブジェクトのユーザー定義データ型を安全なものとしてマークできます。 安全な型の値はデプロイ履歴に保存されず、ログされません。

@secure()
type demoPassword string

@secure()
type demoSecretObject object

エラー レベルを昇格させる

既定では、Bicep でオブジェクト型を宣言すると、任意の型の追加プロパティを受け入れることができます。 たとえば、次の Bicep は有効ですが、[BCP089] - The property "otionalProperty" is not allowed on objects of type "{ property: string, optionalProperty: null | string }". Did you mean "optionalProperty"? という警告を発生させます。

type anObject = {
  property: string
  optionalProperty: string?
}
 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

この警告は、anObject 型に otionalProperty という名前のプロパティが含まれていないことを通知します。 デプロイ時にエラーは発生しませんが、Bicep コンパイラは otionalProperty は入力ミスであり、ユーザーは optionalProperty を使用するつもりがそのスペルを間違えたものと考え、不整合を警告します。

これらの警告をエラーに昇格させるには、以下のように @sealed() デコレーターをオブジェクト型に適用します。

@sealed() 
type anObject = {
  property: string
  optionalProperty?: string
}

param 宣言に @sealed() デコレーターを適用すると、同じ結果が得られます。

type anObject = {
  property: string
  optionalProperty: string?
}
 
@sealed() 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

ARM デプロイ エンジンは、追加のプロパティがないかシールド型もチェックします。 シールド パラメーターに追加のプロパティを指定すると、検証エラーが発生し、デプロイが失敗する原因となります。 次に例を示します。

@sealed()
type anObject = {
  property: string
}

param aParameter anObject = {
  property: 'value'
  optionalProperty: 'value'
}

タグ付き共用体データ型

Bicep ファイル内でカスタム タグ付き共用体データ型を宣言するには、ユーザー定義型宣言の上に discriminator デコレーターを配置します。 このデコレータを使用するには、Bicep CLI バージョン 0.21.X 以上が必要です。 次の例は、タグ付けされた共用体データ型を宣言する方法を示しています。

type FooConfig = {
  type: 'foo'
  value: int
}

type BarConfig = {
  type: 'bar'
  value: bool
}

@discriminator('type')
type ServiceConfig = FooConfig | BarConfig | { type: 'baz', *: string }

param serviceConfig ServiceConfig = { type: 'bar', value: true }

output config object = serviceConfig

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

次のステップ

• Bicep のデータ型一覧については、データ型に関するページを参照してください。