適用於 Bicep 的物件函式

發行項
05/22/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)

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

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

參數

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

傳回值

如果值為空白或 Null，則傳回 True，否則傳回 False。

範例

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

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

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

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

名稱	類型	值
arrayEmpty	Bool	True
objectEmpty	Bool	True
stringEmpty	Bool	True
stringNull	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

objectKeys

objectKeys(object)

從物件傳回索引鍵，其中對像是索引鍵/值組的集合。

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

參數

參數	必要	類型	描述
object	Yes	object	物件，這是索引鍵/值組的集合。

傳回值

陣列。

範例

下列範例示範如何搭配物件使用 objectKeys ：

var obj = { a: 1, b: 2 }

output keyArray array = objectKeys(obj)

前述範例的輸出為：

名稱	類型	值
keyArray	Array	[ “a”， “b” ]

keyArray 會傳回輸入物件的索引鍵清單。

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

shallowMerge

shallowMerge(inputArray)

合併物件的陣列，其中只會合併最上層物件。這表示，如果要合併的物件包含巢狀物件，則不會深度合併這些巢狀物件。相反地，它們會完全由合併對象的對應屬性取代。

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

參數

參數	必要	類型	描述
inputArray	Yes	陣列	物件的陣列。

傳回值

物件。

範例

下列範例顯示如何使用 shallowMerge：

var firstArray = [{ one: 'a' }, { two: 'b' }, { two: 'c'}]
var secondArray = [{ one: 'a', nested: {a: 1, nested: {c: 3}} }, { two: 'b', nested: {b: 2}}]

output firstOutput object = shallowMerge(firstArray)
output secondOutput object = shallowMerge(secondArray)

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

名稱	類型	值
firstOutput	object	{“one”：“a”，“two”：“c”}
secondOutput	object	{“one”：“a”，“nested”：{“b”：2}，“two”：“b”}

firstOutput 會顯示合併物件的屬性會合併成新的物件。如果有衝突的屬性（也就是具有相同名稱的屬性），則最後一個合併物件中的屬性通常優先。

secondOutput 顯示淺層合併不會以遞歸方式合併這些巢狀物件。相反地，整個巢狀物件會由合併對象的對應屬性所取代。

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

參數

傳回值

範例

objectKeys

參數

傳回值

範例

shallowMerge

參數

傳回值

範例

union

參數

傳回值

備註

範例

下一步

意見反應

其他資源