適用於 Bicep 的物件函式

發行項
03/27/2024

此文章將描述用來處理物件的 Bicep 函式。

contains

contains(container, itemToFind)

檢查陣列中是否包含值、物件中是否包含索引鍵，或字串中是否包含子字串。字串比較會區分大小寫。不過，測試時，如果物件包含索引鍵，比較便不區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
容器	Yes	陣列、物件或字串	其中包含要尋找之值的值。
itemToFind	Yes	字串或整數	要尋找的值。

傳回值

找到項目則傳回 True，否則會傳回 False。

範例

下列範例顯示如何使用不同類型的 contains：

param stringToTest string = 'OneTwoThree'
param objectToTest object = {
  one: 'a'
  two: 'b'
  three: 'c'
}
param arrayToTest array = [
  'one'
  'two'
  'three'
]

output stringTrue bool = contains(stringToTest, 'e')
output stringFalse bool = contains(stringToTest, 'z')
output objectTrue bool = contains(objectToTest, 'one')
output objectFalse bool = contains(objectToTest, 'a')
output arrayTrue bool = contains(arrayToTest, 'three')
output arrayFalse bool = contains(arrayToTest, 'four')

上述範例中具有預設值的輸出如下：

名稱	類型	值
stringTrue	Bool	True
stringFalse	Bool	False
objectTrue	Bool	True
objectFalse	Bool	False
arrayTrue	Bool	True
arrayFalse	Bool	False

empty

empty(itemToTest)

判斷陣列、物件或字串是否空白。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
itemToTest	Yes	陣列、物件或字串	檢查其是否為空白的值。

傳回值

如果值空白則傳回 True，否則會傳回 False。

範例

下列範例會檢查陣列、物件和字串是否空白。

param testArray array = []
param testObject object = {}
param testString string = ''

output arrayEmpty bool = empty(testArray)
output objectEmpty bool = empty(testObject)
output stringEmpty bool = empty(testString)

上述範例中具有預設值的輸出如下：

名稱	類型	值
arrayEmpty	Bool	True
objectEmpty	Bool	True
stringEmpty	Bool	True

交集

intersection(arg1, arg2, arg3, ...)

從參數中傳回具有共同元素的單一陣列或物件。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	陣列或物件	要用來尋找共同元素的第一個值。
arg2	Yes	陣列或物件	要用來尋找共同元素的第二個值。
其他引數	No	陣列或物件	要用來尋找共同元素的其他值。

傳回值

具有共同元素的陣列或物件。

範例

下列範例顯示如何搭配使用 intersection 與陣列和物件︰

param firstObject object = {
  one: 'a'
  two: 'b'
  three: 'c'
}
param secondObject object = {
  one: 'a'
  two: 'z'
  three: 'c'
}
param firstArray array = [
  'one'
  'two'
  'three'
]
param secondArray array = [
  'two'
  'three'
]

output objectOutput object = intersection(firstObject, secondObject)
output arrayOutput array = intersection(firstArray, secondArray)

上述範例中具有預設值的輸出如下：

名稱	類型	值
objectOutput	Object	{"one": "a", "three": "c"}
arrayOutput	陣列	["two", "three"]

項目

items(object)

將字典物件轉換成陣列。請參閱 toObject 以了解如何將陣列轉換為物件。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
object	Yes	object	要轉換為陣列的字典物件。

傳回值

已轉換字典的物件陣列。陣列中的每個物件都有一個 key 屬性，其中包含字典的索引鍵值。每個物件也都有一個 value 屬性，其中包含物件的屬性。

範例

下列範例會將字典物件轉換成陣列。針對陣列中的每個物件，它會以修改過的值來建立新的物件。

var entities = {
  item002: {
    enabled: false
    displayName: 'Example item 2'
    number: 200
  }
  item001: {
    enabled: true
    displayName: 'Example item 1'
    number: 300
  }
}

var modifiedListOfEntities = [for entity in items(entities): {
  key: entity.key
  fullName: entity.value.displayName
  itemEnabled: entity.value.enabled
}]

output modifiedResult array = modifiedListOfEntities

上述範例會傳回：

"modifiedResult": {
  "type": "Array",
  "value": [
    {
      "fullName": "Example item 1",
      "itemEnabled": true,
      "key": "item001"
    },
    {
      "fullName": "Example item 2",
      "itemEnabled": false,
      "key": "item002"
    }
  ]
}

下列範例顯示從項目函式傳回的陣列。

var entities = {
  item002: {
    enabled: false
    displayName: 'Example item 2'
    number: 200
  }
  item001: {
    enabled: true
    displayName: 'Example item 1'
    number: 300
  }
}

var entitiesArray = items(entities)

output itemsResult array = entitiesArray

範例會傳回：

"itemsResult": {
  "type": "Array",
  "value": [
    {
      "key": "item001",
      "value": {
        "displayName": "Example item 1",
        "enabled": true,
        "number": 300
      }
    },
    {
      "key": "item002",
      "value": {
        "displayName": "Example item 2",
        "enabled": false,
        "number": 200
      }
    }
  ]
}

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

json

json(arg1)

將有效的 JSON 字串轉換成 JSON 資料類型。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	string	要轉換為 JSON 的值。字串必須是格式正確的 JSON 字串。

傳回值

指定字串的 JSON 資料類型，如果指定 Null 則為空值。

備註

如果您需要在 JSON 物件中包含參數值或變數，請使用 concat 函式來建立傳遞給函式的字串。

範例

下列範例示範如何使用 json 函式。請注意，針對空物件，您可以傳入 null。

param jsonEmptyObject string = 'null'
param jsonObject string = '{\'a\': \'b\'}'
param jsonString string = '\'test\''
param jsonBoolean string = 'true'
param jsonInt string = '3'
param jsonArray string = '[[1,2,3]]'
param concatValue string = 'demo value'

output emptyObjectOutput bool = empty(json(jsonEmptyObject))
output objectOutput object = json(jsonObject)
output stringOutput string =json(jsonString)
output booleanOutput bool = json(jsonBoolean)
output intOutput int = json(jsonInt)
output arrayOutput array = json(jsonArray)
output concatObjectOutput object = json(concat('{"a": "', concatValue, '"}'))

上述範例中具有預設值的輸出如下：

名稱	類型	值
emptyObjectOutput	布林值	True
objectOutput	Object	{"a": "b"}
stringOutput	String	測試
booleanOutput	布林值	True
intOutput	整數	3
arrayOutput	陣列	[ 1, 2, 3 ]
concatObjectOutput	Object	{ "a": "demo value" }

length

length(arg1)

傳回陣列中的元素、字串中的字元，或物件中的根層級屬性的數目。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	陣列、字串或物件	用於取得元素數目的陣列、用於取得字元數目的字串，或用於取得根層級屬性數目的物件。

傳回值

整數。

範例

下列範例顯示如何搭配使用 length 與陣列和字串：

param arrayToTest array = [
  'one'
  'two'
  'three'
]
param stringToTest string = 'One Two Three'
param objectToTest object = {
  propA: 'one'
  propB: 'two'
  propC: 'three'
  propD: {
      'propD-1': 'sub'
      'propD-2': 'sub'
  }
}

output arrayLength int = length(arrayToTest)
output stringLength int = length(stringToTest)
output objectLength int = length(objectToTest)

上述範例中具有預設值的輸出如下：

名稱	類型	值
arrayLength	int	3
stringLength	int	13
objectLength	int	4

union

union(arg1, arg2, arg3, ...)

從參數中傳回具有所有元素的單一陣列或物件。針對陣列，會包括重複的值一次。針對物件，只會包括重複的屬性名稱一次。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	陣列或物件	用來聯結元素的第一個值。
arg2	Yes	陣列或物件	用來聯結元素的第二個值。
其他引數	No	陣列或物件	用來聯結元素的其他值。

傳回值

陣列或物件。

備註

Union 函式會使用參數的順序來決定結果的順序和值。

針對陣列，此函式會逐一查看第一個參數中的每個元素；若其尚未出現在結果中，便會將其新增至結果。接著，會對第二個參數和任何其他參數重複上述程序。如果值已經存在，則會保留較早放置於陣列中的值。

針對物件，會將來自第一個參數的屬性名稱和值新增至結果。針對較後面的參數，則會將所有新名稱新增至結果。如果較後面的參數具有相同名稱的屬性，該值就會覆寫現有的值。無法保證屬性的順序。

Union 函式不僅會合併最上層元素，也會以遞迴方式合併其中的任何巢狀物件。巢狀陣列值則不會合併。請參閱下一節的第二個範例。

範例

下列範例顯示如何搭配使用 union 與陣列和物件︰

param firstObject object = {
  one: 'a'
  two: 'b'
  three: 'c1'
}

param secondObject object = {
  three: 'c2'
  four: 'd'
  five: 'e'
}

param firstArray array = [
  'one'
  'two'
  'three'
]

param secondArray array = [
  'three'
  'four'
  'two'
]

output objectOutput object = union(firstObject, secondObject)
output arrayOutput array = union(firstArray, secondArray)

上述範例中具有預設值的輸出如下：

名稱	類型	值
objectOutput	Object	{"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput	陣列	["one", "two", "three", "four"]

下列範例顯示深層合併功能：

var firstObject = {
  property: {
    one: 'a'
    two: 'b'
    three: 'c1'
  }
  nestedArray: [
    1
    2
  ]
}
var secondObject = {
  property: {
    three: 'c2'
    four: 'd'
    five: 'e'
  }
  nestedArray: [
    3
    4
  ]
}
var firstArray = [
  [
    'one'
    'two'
  ]
  [
    'three'
  ]
]
var secondArray = [
  [
    'three'
  ]
  [
    'four'
    'two'
  ]
]

output objectOutput object = union(firstObject, secondObject)
output arrayOutput array = union(firstArray, secondArray)

前述範例的輸出為：

名稱	類型	值
objectOutput	Object	{"property":{"one":"a","two":"b","three":"c2","four":"d","five":"e"},"nestedArray":[3,4]}
arrayOutput	陣列	[["one","two"],["three"],["four","two"]]

如果已合併巢狀陣列，則 objectOutput.nestedArray 的值會是 [1, 2, 3, 4]，而 arrayOutput 的值會是 [["one", "two", "three"], ["three", "four", "two"]]。

下一步

如需 Bicep 檔案中各區段的描述，請參閱了解 Bicep 檔案的結構和語法。

適用於 Bicep 的物件函式

contains

參數

傳回值

範例

empty

參數

傳回值

範例

交集

參數

傳回值

範例

項目

參數

傳回值

範例

json

參數

傳回值

備註

範例

length

參數

傳回值

範例

union

參數

傳回值

備註

範例

下一步

其他資源