Bicep 中的資料類型

發行項
08/20/2024

本文說明 Bicep 支援的資料類型。若要定義自訂資料類型，請參閱使用者定義的資料類型。

支援的類型

在 Bicep 中，您可使用下列資料類型：

array
bool
int
object
secureObject - 由 Bicep 中的裝飾項目表示
secureString - 由 Bicep 中的裝飾項目表示
string

陣列

陣列開頭為左括弧 ([)，結尾為右括弧 (])。在 Bicep 中，陣列可在單行或多行中宣告。逗號 (,) 可用於單行宣告中的值之間，但不能用於多行宣告中，您可以混合並比對單行和多行宣告。多行宣告需要 Bicep CLI 0.7.X 版或更新版本。

var multiLineArray = [
  'abc'
  'def'
  'ghi'
]

var singleLineArray = ['abc', 'def', 'ghi']

var mixedArray = ['abc', 'def'
    'ghi']

每個數位元素都可以是任何類型。您的陣列各項目可皆為相同的資料類型，也可為不同的資料類型。

下列範例顯示整數陣列及不同類型的陣列。

var integerArray = [
  1
  2
  3
]

var mixedArray = [
  resourceGroup().name
  1
  true
  'example string'
]

Bicep 中的陣列以零為起始。在下列範例中，運算式 exampleArray[0] 評估為 1，且 exampleArray[2] 評估為 3。索引器索引可以是另一個表達式。運算式 exampleArray[index] 評估為 2。僅限陣列類型的運算式使用整數索引子。

var index = 1

var exampleArray = [
  1
  2
  3
]

當索引超出界限時，您會收到下列錯誤：

The language expression property array index 'x' is out of bounds

若要避免此例外狀況，您可以如下列範例所示，使用 Or 邏輯運算子：

param emptyArray array = []
param numberArray array = [1, 2, 3]

output foo bool = empty(emptyArray) || emptyArray[0] == 'bar'
output bar bool = length(numberArray) <= 3 || numberArray[3] == 4

布林值

指定布林值時，請使用 true 或 false。請勿用引號括住值。

param exampleBool bool = true

整數

指定整數值時，請勿使用引號。

param exampleInt int = 1

Bicep 整數是 64 位整數。當傳遞為內嵌參數時，值範圍可以受到您用於部署的 SDK 或命令行工具所限制。例如，使用 PowerShell 來部署 Bicep 時，整數類型的範圍可介於 -2147483648 和2147483647。若要避免這項限制，請在參數檔案中指定較大的整數值。資源類型自身具有整數屬性的限制。

Bicep 支援整數常值類型，該類型參考的是確切整數的特定值。在下列範例中， 1 是整數常值類型， foo 只能指派值 1 ，而沒有其他值。

output foo 1 = 1

整數常值類型可以內嵌宣告，如上述範例所示，或在語句中type所示。

type oneType = 1

output foo oneType = 1
output bar oneType = 2

在上述範例中，將 2 指派給列會導致 BCP033 錯誤 - 必須是類型「1」的值，但所提供的值的類型為「2」。。

下列範例示範搭配聯集類型使用整數常值類型：

output bar 1 | 2 | 3 = 3

目前不支援浮點數、十進位或二進位格式。

物件

物件開頭為左大括弧 ({)，結尾為右大括弧 (})。在 Bicep 中，物件可以在單行或多行中宣告。物件中的每個屬性都是由索引鍵和值所組成。索引鍵和值以冒號 (:) 分隔。物件允許任何類型的任何屬性。單行宣告的屬性之間會使用逗號 (,)，但在多行宣告的屬性之間不會使用。您可以混合並比對單行和多行宣告。多行宣告需要 Bicep CLI 0.7.X 版或更新版本。

param singleLineObject object = {name: 'test name', id: '123-abc', isCurrent: true, tier: 1}

param multiLineObject object = {
  name: 'test name'
  id: '123-abc'
  isCurrent: true
  tier: 1
}

param mixedObject object = {name: 'test name', id: '123-abc', isCurrent: true
    tier: 1}

在 Bicep 中，物件屬性索引鍵可選擇性使用引號：

var test = {
  'my - special. key': 'value'
}

在上述範例中，當物件屬性索引鍵包含特殊字元時，則使用引號。例如：空格、'-' 或 '.'。下列範例示範如何在物件屬性索引鍵中使用插補。

var stringVar = 'example value'
var objectVar = {
  '${stringVar}': 'this value'
}

屬性存取子用於存取物件的屬性。這類存取子由 . 運算子所組成。

var a = {
  b: 'Dev'
  c: 42
  d: {
    e: true
  }
}

output result1 string = a.b // returns 'Dev'
output result2 int = a.c // returns 42
output result3 bool = a.d.e // returns true

屬性存取子可與任何物件一併使用，包括物件類型和物件常值的參數和變數。若非物件類型的運算式使用屬性存取子，則為錯誤。

您也可使用 [] 語法來存取屬性。下列範例會傳回 Development。

var environmentSettings = {
  dev: {
    name: 'Development'
  }
  prod: {
    name: 'Production'
  }
}

output accessorResult string = environmentSettings['dev'].name

在 JSON 中，物件是零或多個索引鍵/值組的未排序集合。根據實作而定，排序可能會不同。例如，Bicep items() 函式會依字母順序排序物件。在其他位置，可以保留原始排序。由於這種非確定性，請避免在編寫與部署參數和輸出互動的程式碼時，對物件索引鍵的排序進行任何假設。

存取物件的非存在屬性時，您會收到下列錯誤：

The language expression property 'foo' doesn't exist

若要避免例外狀況，您可以如下列範例所示，使用 And 邏輯運算子：

param objectToTest object = {
  one: 1
  two: 2
  three: 3
}

output bar bool = contains(objectToTest, 'four') && objectToTest.four == 4

字串

在 Bicep 中，字串以單引號標示，且須以單一行來宣告。允許使用字碼指標介於 0 和 10FFFF 間的所有 Unicode 字元。

param exampleString string = 'test value'

下表列出必須以反斜線 (\) 字元逸出的一系列保留字元：

逸出序列	表示值	備註
`\\`	`\`
`\'`	`'`
`\n`	換行字元 (LF)
`\r`	歸位字元 (CR)
`\t`	定位字元
`\u{x}`	Unicode 字碼指標 `x`	x 代表介於 0 和 10FFFF (含此二值) 的十六進位字碼指標值。允許以零開頭。 FFFF 以上的字碼指標會以代理字組的形式發出。
`\$`	`$`	僅限後面接著 `{` 時逸出。

// evaluates to "what's up?"
var myVar = 'what\'s up?'

Bicep 支援參考特定字串值的字串常值類型。在下列範例中，red 是字串常值類型，redColor 只能指派紅色值，而沒有其他值。

output redColor 'red' = 'red'

字串常值類型可以內嵌宣告，如上述範例所示，或在語句中type所示。

type redColor = 'red'

output colorRed redColor = 'red'
output colorBlue redColor = 'blue'

在上述範例中，將藍色指派給 colorBlue 會產生 BCP033 錯誤 - 必須是類型 “'red'” 的值，但所提供的值的類型為 “'blue'”。

下列範例示範搭配聯集類型使用字串常值類型：

type direction = 'north' | 'south' | 'east' | 'west'

output west direction = 'west'
output northWest direction = 'northwest'

Bicep 中的所有字串皆支援插補。若要插入運算式，請在其前後使用 ${ 和 }。參考的運算式不可跨越多行。

var storageName = 'storage${uniqueString(resourceGroup().id)}'

多行字串

在 Bicep 中，多行字串的定義位於三個單引號字元 (''') 之間，接著可選擇性使用新行 (開頭序列)，以及三個單引號字元 (''' -結尾序列)。在開頭和結尾序列間輸入的字元會逐字讀取，並且無須也無法逸出。

注意

由於 Bicep 剖析器會如實讀取所有字元，因此根據 Bicep 檔案的行尾結束符號，新行可解讀為 \r\n 或 \n。

多行字串目前不支援插補。由於這項限制，您可能需要使用 concat 函式，而不是使用內插補點。

不支援包含 ''' 的多行字串。

// evaluates to "hello!"
var myVar = '''hello!'''

// evaluates to "hello!" because the first newline is skipped
var myVar2 = '''
hello!'''

// evaluates to "hello!\n" because the final newline is included
var myVar3 = '''
hello!
'''

// evaluates to "  this\n    is\n      indented\n"
var myVar4 = '''
  this
    is
      indented
'''

// evaluates to "comments // are included\n/* because everything is read as-is */\n"
var myVar5 = '''
comments // are included
/* because everything is read as-is */
'''

// evaluates to "interpolation\nis ${blocked}"
// note ${blocked} is part of the string, and is not evaluated as an expression
var myVar6 = '''interpolation
is ${blocked}'''

聯集類型

在 Bicep 中，等位類型允許建立由一組子類型組成的合併類型。如果允許任何個別子類型指派，則指派有效。字元會 | 使用或條件分隔個別子類型。例如，語法 'a' |'b' 表示有效的指派可以是 'a' 或 'b'。 等位型別會轉譯成 Bicep 中允許值限制式，因此只有常值可以做為成員。等位可以包含任意數目的常值型別表達式。

type color = 'Red' | 'Blue' | 'White'
type trueOrFalse = 'true' | 'false'
type permittedIntegers = 1 | 2 | 3
type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]

類型等位必須可縮減為單一 ARM 類型，例如『string』、'int' 或 'bool'。否則，您會取得 BCP294 錯誤碼。例如：

type foo = 'a' | 1

任何類型表達式都可以當做等位型別宣告中的子類型（在字元之間 | ）。例如，下列範例都是有效的：

type foo = 1 | 2
type bar = foo | 3
type baz = bar | (4 | 5) | 6

自訂標記聯集數據類型

Bicep 支援自定義標記聯集數據類型，用來表示可以是數種不同類型之一的值。若要宣告自定義標記聯集數據類型，您可以使用 @discriminator() 裝飾專案。需要 Bicep CLI 0.21.X 版或更高版本才能使用此裝飾項目。語法為：

@discriminator('<property-name>')

鑑別子屬性裝飾項目會採用單一參數，代表所有集合聯集成員之間的共用屬性名稱。這個屬性名稱必須是所有成員的必要字串常值，而且區分大小寫。等位成員上鑑別子屬性的值必須是唯一的，且不區分大小寫。

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

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

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

參數值會根據鑑別子屬性的屬性值進行驗證。例如，在上述範例中，如果 serviceConfig 參數的類型 為 foo，則會使用 FooConfig 類型進行驗證。同樣地，如果參數的類型為列，則會使用 BarConfig 類型進行驗證。此模式也適用於其他類型。

聯集類型有一些限制。

聯集類型必須可縮減為單一 Azure Resource Manager （ARM）類型。下列定義無效：
```
type foo = 'a' | 1
```
只有常值可以做為成員。
所有常值都必須是相同的基本數據類型（例如，所有字串或所有整數）。

聯集類型語法可用於使用者定義數據類型。

安全字串和物件

安全字串所用的格式與字串相同，安全物件所用的格式則與物件相同。使用 Bicep 時，您會將@secure()裝飾專案新增至字串或物件。

將參數設為安全字串或安全物件時，參數的值不會儲存至部署歷程記錄，且不會記錄。但若將該安全值設為不需要安全值的屬性，此值則不受保護。例如，若將安全字串設為標記，該值便會儲存為純文字。密碼及秘密請使用安全字串。

下列範例示範兩個安全參數：

@secure()
param password string

@secure()
param configValues object

資料類型的可指派性

在 Bicep 中，您可將某類型 (來源類型) 的值指派給其他類型 (目標類型)。下表顯示可供指派或無法指派的來源類型 (水平陳列) 及目標類型 (垂直陳列)。在資料表中，X 表示可指派；空格表示無法指派；? 則表示其類型相容。

類型	`any`	`string`	`number`	`int`	`bool`	`null`	`object`	`array`	具名資源	具名模組	`scope`
`any`	X	X	X	X	X	X	X	X	X	X	X
`error`
`string`	X	X
`number`	X		X	X
`int`	X			X
`bool`	X				X
`null`	X					X
`object`	X						X
`array`	X							X
`resource`	X								X
`module`	X									X
`scope`											?
具名資源	X						?		?
具名模組	X						?			?

下一步

若要深入了解 Bicep 的結構和語法，請參閱 Bicep 檔案結構。

共用方式為