在 Bicep 中使用者自訂資料類型

發行項
10/29/2024

了解如何在 Bicep 中建立使用者定義的資料類型。如需系統定義的資料類型，請參閱資料類型。使用使用者定義的數據類型會自動啟用語言 2.0 版程式代碼產生。

定義類型

您可以使用 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)[]

物件類型包含大括弧之間的零個或多個屬性：
```
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?
}
```
下列類型定義無效，因為、、 level4level3或 level5 都不是level1level2選擇性的。
```
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 陳述式的型別子句中。例如：

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 格式撰寫的，放置於使用者定義資料類型的宣告上方。下表顯示使用者定義的資料類型可用的裝飾項目。

裝飾項目	套用到	Argument	描述
description	全部	字串	提供使用者定義資料類型的描述。
discriminator	object	字串	使用此裝飾項目，確保會正確識別及管理子類別。
export	全部	none	表示使用者定義的資料類型可供其他 Bicep 檔案匯入。
maxLength	陣列、字串	int	字串和陣列資料類型的最大長度。此值為內含。
maxValue	int	int	整數資料類型的最大值。此值為內含。
中繼資料	全部	object	要套用至資料類型的自訂屬性。可以包含與描述裝飾專案相等的描述屬性。
minLength	陣列、字串	int	字串和陣列資料類型的最小長度。此值為內含。
minValue	int	int	整數資料類型的最小值。此值為內含。
sealed	object	none	當使用者定義數據類型的屬性名稱可能是錯字時，將 BCP089 從警告提升為錯誤。如需詳細資訊，請參閱提升錯誤層級。
secure	字串、物件	none	將類型標示為安全。安全類型的值不會儲存在部署歷程記錄中，且不會記錄。如需詳細資訊，請參閱安全字串和物件。

裝飾項目在 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

長度限制

您可以指定字串和陣列類型的最小和最大長度。您可以設定一或兩個限制式。若為字串，長度代表字元數。若為陣列，長度代表陣列中的項目數。

下列範例會宣告兩種類型。其中一種類型適用於必須有 3 到 24 個字元的記憶體帳戶名稱。另一種類型是必須有一到五個項目的陣列。

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

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

中繼資料

如果您有自訂屬性要套用至使用者定義的資料類型，請新增中繼資料裝飾項目。在中繼資料內，使用自訂名稱和值定義物件。您為中繼資料定義的物件可以包含任何名稱和類型的屬性。

您可以使用此裝飾項目，追蹤對於新增至描述並無意義之資料類型的相關資訊。

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

若您提供的 @metadata() 裝飾項目含有的屬性與另一個裝飾項目衝突，該裝飾項目一律優先於 @metadata() 裝飾項目中任何元素，因此，值內的 @metadata() 衝突屬性是多餘的，而且會取代。如需詳細資訊，請參閱沒有衝突的中繼資料 (機器翻譯)。

密封

請參閱提升錯誤層級。

安全類型

您可以將字串或物件使用者定義資料類型標示為安全。安全類型的值不會儲存在部署歷程記錄中，且不會記錄。

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

將 @sealed() 裝飾項目套用至 param 宣告，會取得相同的結果：

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

整數限制式

長度限制

中繼資料

密封

安全類型

提升錯誤層級

標記的等位資料類型

意見反應

其他資源

共用方式為

在 Bicep 中使用者自訂資料類型

定義類型

使用裝飾項目

鑑別子

描述

Export

整數限制式

長度限制

中繼資料

密封

安全類型

提升錯誤層級

標記的等位資料類型

相關內容

意見反應

其他資源