在 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)[]
  

• 物件類型包含大括弧之間的零個或多個屬性：

  type storageAccountConfigType = {
    name: string
    sku: string
  }
  

  物件中的每個屬性都包含索引鍵和值，並以冒號 : 分隔。 索引鍵可以是任何字串 (將非識別碼值放在引號中)，而值可以是任何類型的運算式。

  除非屬性在屬性值之後有選擇性標記 ?，否則需要屬性。 例如，下列範例中的 sku 屬性是選擇性的：

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

  裝飾項目可用於屬性。 * 可用來讓所有值都需要限制式。 使用 * 時，仍可能會定義其他屬性。 此範例會建立一個物件，需要類型為 int、名為 id 的索引鍵，且物件中的所有其他項目都必須是長度至少 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 陳述式的型別子句中。 例如：

  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 的變數，則在使用描述裝飾項目時，您必須新增 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 個字元的儲存體帳戶名稱。 另一個類型是必須包含 1-5 個項目的陣列。

@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 但拼字錯誤，並提醒您不一致之處。

若要將這些警告提升為錯誤，請將 @sealed() 裝飾項目套用至物件類型：

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

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

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 資料類型的清單，請參閱資料類型。