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

[アーティクル]
10/23/2024

Bicep でユーザー定義データ型を作成する方法を学習します。システム定義データ型については、データ型に関するページをご覧してください。ユーザー定義データ型を使用すると、言語バージョン 2.0 コード生成が自動的に有効になります。

この機能を使用するには、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 形式で記述され、ユーザー定義データ型の宣言の上に配置されます。次の表に、ユーザー定義データ型で使用できるデコレーターを示します。

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

デコレーターは、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 を使用するつもりだったがスペルミスであると見なします。 Bicep は不整合を警告します。

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

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

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

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

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

@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 のデータ型一覧については、データ型に関するページを参照してください。

次の方法で共有

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

型を定義する

デコレーターを使用する

識別子

説明

Export

整数の制約

長さの制限

Metadata

Sealed

安全な型

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

タグ付き共用体データ型

フィードバック

その他のリソース

次の方法で共有

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

型を定義する

デコレーターを使用する

識別子

説明

Export

整数の制約

長さの制限

Metadata

Sealed

安全な型

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

タグ付き共用体データ型

関連するコンテンツ

フィードバック

その他のリソース

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