你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

Bicep 的对象函数

本文介绍用于处理对象的 Bicep 函数。

contains

contains(container, itemToFind)

检查数组是否包含某个值、某个对象是否包含某个键,或者某个字符串是否包含某个子字符串。 字符串比较区分大小写。 但在测试某个对象是否包含某个键时,该比较不区分大小写。

命名空间:sys

参数

参数 必选 类型​​ 说明
container 数组、对象或字符串 包含要查找的值的值。
itemToFind 字符串或整数 要查找的值。

返回值

如果找到该项,则为 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 数组、对象或字符串 要检查其是否为空或 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

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

返回包含参数中通用元素的单个数组或对象。

命名空间:sys

参数

参数 必选 类型​​ 说明
arg1 数组或对象 用于查找通用元素的第一个值。
arg2 数组或对象 用于查找通用元素的第二个值。
其他参数 数组或对象 用于查找通用元素的其他值。

返回值

包含通用元素的数组或对象。

示例

以下示例演示如何对数组和对象使用 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 对象 {"one": "a", "three": "c"}
arrayOutput Array ["two", "three"]

items

items(object)

将字典对象转换为数组。 有关将数组转换为对象的信息,请参阅 toObject

命名空间:sys

参数

参数 必选 类型​​ 说明
object 对象 (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"
    }
  ]
}

下面的示例演示 items 函数返回的数组。

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 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, '"}'))

上述示例中使用默认值的输出为:

名称 类型 Value
emptyObjectOutput 布尔 True
objectOutput Object {"a": "b"}
stringOutput String 测试
booleanOutput 布尔 True
intOutput Integer 3
arrayOutput Array [ 1, 2, 3 ]
concatObjectOutput 对象 { "a": "demo value" }

length

length(arg1)

返回数组中的元素数、字符串中的字符数或对象中的根级属性数。

命名空间:sys

参数

参数 必选 类型​​ 说明
arg1 数组、字符串或对象 用于获取元素数的数组、用于获取字符数的字符串,或用于获取根级属性数的对象。

返回值

一个整数。

示例

以下示例演示如何对数组和字符串使用 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 对象 (object) 对象,是键值对的集合。

返回值

一个数组。

示例

以下示例演示如何对对象使用 objectKeys

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

output keyArray array = objectKeys(obj)

前述示例的输出为:

名称 类型
keyArray 数组 [ "a", "b" ]

keyArray 返回输入对象的键列表。

在 JSON 中,对象是零个或更多键/值对的无序集合。 排序可能会根据实现而有所不同。 例如,Bicep items() 函数按字母顺序对对象进行排序。 在其他位置,可以保留原始排序。 由于这种非确定性,在编写代码时避免对对象键排序做出任何假设,因为这会与部署参数和输出交互。

shallowMerge

shallowMerge(inputArray)

合并对象数组,其中仅合并顶级对象。 这意味着如果要合并的对象包含嵌套对象,则不会将这些嵌套对象深度合并, 而是将它们完全替换为合并对象中的相应属性。

命名空间:sys

参数

参数 必选 类型​​ 说明
inputArray array 一个 对象数组。

返回值

一个对象。

示例

下面的示例演示如何使用 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 数组或对象 用于联接元素的第一个值。
arg2 数组或对象 用于联接元素的第二个值。
其他参数 数组或对象 用于联接元素的其他值。

返回值

数组或对象。

备注

联合函数使用参数序列来确定结果的顺序和值。

对于数组,该函数会循环访问第一个参数中的每个元素,并将其添加到结果中(如果尚不存在)。 然后,它会对第二个参数和任何其他参数重复该过程。 如果某个值已存在,则保留其此前在数组中的放置位置。

对于对象,来自第一个参数的属性名称和值将添加到结果中。 对于稍后的参数,任何新名称都将添加到结果中。 如果稍后的参数具有同名的属性,该值将覆盖现有值。 不保证属性的顺序。

联合函数不仅合并顶级元素,而且还以递归方式合并其中的嵌套对象。 嵌套数组值不会合并。 请参阅以下部分中的第二个示例。

示例

以下示例演示如何对数组和对象使用 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 Array ["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"]]。

后续步骤