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

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

定義類型

您可以使用 type 陳述式來建立使用者定義的資料類型。您也可以在某些地方使用類型運算式來定義自訂類型。

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

只有 param 陳述式上才允許 @allowed 裝飾項目。若要在 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?
}
```
下列類型定義無效，因為 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@2025-06-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@2025-06-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

使用裝飾項目

裝飾項目是以 @expression 格式撰寫的，放置於使用者定義資料類型的宣告上方。下表顯示使用者定義的資料類型可用的裝飾項目。

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

裝飾項目在 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() 與其他 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 可讓您使用 resourceInput<> 和 resourceOutput<> 建構，直接從 Azure 資源架構衍生類型。資源衍生的類型可讓您根據資源主體的一部分來檢查參數和變數，而不是使用自定義類型。需要 Bicep CLI 0.34.1 版或更高版本，才能使用這些建構。

範本可以在預期類型時重複使用資源類型。

resourceInput<'type@version'>

resourceInput<>：代表資源類型的可寫入屬性，並去除ARM範本架構中標示為ReadOnly的任何屬性。其會使用您需要傳入至資源宣告的類型。

resourceOutput<'type@version'>

resourceOutput<>：代表資源類型的可讀取屬性，將 ARM 範本架構中標示為 WriteOnly 的任何屬性移除。它符合布建完資源後傳回的值類型。

您可以套用 resourceInput<> 或 resourceOutput<> 只擷取資源架構的一部分。例如，若要根據儲存帳戶中的 kind 或 properties 來輸入變數或參數：

type accountKind = resourceInput<'Microsoft.Storage/storageAccounts@2024-01-01'>.kind

上述範例相當於：

type accountKind = 'BlobStorage' | 'BlockBlobStorage' | 'FileStorage' | 'Storage' | 'StorageV2'

下列範例顯示如何使用 resourceInput<>，以根據儲存體帳戶資源的 properties 來建立類型參數。這可讓您定義符合記憶體帳戶可寫入屬性的參數，例如 accessTier、 minimumTlsVersion和其他：

// Typed parameter using the .properties path of a storage account
param storageAccountProps resourceInput<'Microsoft.Storage/storageAccounts@2023-01-01'>.properties = {
  accessTier: 'Hot'
  minimumTlsVersion: 'TLS1_2'
  allowBlobPublicAccess: false
  supportsHttpsTrafficOnly: true
}

// Resource declaration using the typed parameter
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'mystorageacct123'
  location: resourceGroup().location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: storageAccountProps
}

下列範例顯示如何使用 resourceOutput<>，以根據儲存體帳戶資源的 primaryEndPoints 來建立類型輸出。

output storageEndpoints resourceOutput<'Microsoft.Storage/storageAccounts@2024-01-01'>.properties.primaryEndpoints = ...

不同於使用者定義數據類型，在編輯或編譯檔案時，Bicep 會檢查資源衍生的類型，但 ARM 服務不會檢查它們。

若要 Bicep 資料類型的清單，請參閱資料類型。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-07-27