共用方式為


ARM 範本的物件函式

Resource Manager 提供數個函式,可在 Azure Resource Manager 範本 (ARM 範本) 中處理物件:

提示

我們建議使用 Bicep,因為其提供的功能與 ARM 範本相同,而且語法更易於使用。 若要深入了解,請參閱物件函式。

contains

contains(container, itemToFind)

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

在 Bicep 中,使用 contains 函式。

參數

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

傳回值

找到項目則傳回 True,否則會傳回 False

範例

下列範例示範如何搭配不同類型的使用 contains

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringToTest": {
      "type": "string",
      "defaultValue": "OneTwoThree"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "stringTrue": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'e')]"
    },
    "stringFalse": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'z')]"
    },
    "objectTrue": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'one')]"
    },
    "objectFalse": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'a')]"
    },
    "arrayTrue": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'three')]"
    },
    "arrayFalse": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'four')]"
    }
  }
}

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

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

createObject

createObject(key1, value1, key2, value2, ...)

從索引碼和值建立物件。

Bicep 不支援 createObject 函式。 使用 {} 建構物件。 請參閱物件

參數

參數 必要 類型​ 描述
key1 No string 金鑰的名稱。
value1 No 整數、布林值、字串、物件或陣列 索引鍵的值。
更多索引碼 No string 更多索引碼的名稱。
更多值 No 整數、布林值、字串、物件或陣列 更多索引碼的值。

函式只接受偶數數目的參數。 每個索引碼都必須有對應的值。

傳回值

每個索引碼都和值配對的物件。

範例

下列範例會從不同類型的值建立物件。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [
  ],
  "outputs": {
    "newObject": {
      "type": "object",
      "value": "[createObject('intProp', 1, 'stringProp', 'abc', 'boolProp', true(), 'arrayProp', createArray('a', 'b', 'c'), 'objectProp', createObject('key1', 'value1'))]"
    }
  }
}

上述範例會輸出具有預設值且名為 newObject 的物件,並具有下列值:

{
  "intProp": 1,
  "stringProp": "abc",
  "boolProp": true,
  "arrayProp": ["a", "b", "c"],
  "objectProp": {"key1": "value1"}
}

empty

empty(itemToTest)

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

在 Bicep 中,使用 empty 函式。

參數

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

傳回值

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

範例

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": []
    },
    "testObject": {
      "type": "object",
      "defaultValue": {}
    },
    "testString": {
      "type": "string",
      "defaultValue": ""
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testArray'))]"
    },
    "objectEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testObject'))]"
    },
    "stringEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testString'))]"
    }
  }
}

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

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

交集

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

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

在 Bicep 中,使用 intersection 函式。

參數

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

傳回值

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

範例

下列範例示範如何搭配數位和物件使用 intersection

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "z",
        "three": "c"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[intersection(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[intersection(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

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

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

項目

items(object)

將字典物件轉換成陣列。 有關將陣列轉換為物件,請參閱 toObject

在 Bicep 中,使用項目

參數

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

傳回值

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

範例

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "copy": [
      {
        "name": "modifiedListOfEntities",
        "count": "[length(items(variables('entities')))]",
        "input": {
          "key": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].key]",
          "fullName": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].value.displayName]",
          "itemEnabled": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].value.enabled]"
        }
      }
    ],
    "entities": {
      "item002": {
        "enabled": false,
        "displayName": "Example item 2",
        "number": 200
      },
      "item001": {
        "enabled": true,
        "displayName": "Example item 1",
        "number": 300
      }
    }
  },
  "resources": [],
  "outputs": {
    "modifiedResult": {
      "type": "array",
      "value": "[variables('modifiedListOfEntities')]"
    }
  }
}

上述範例會傳回:

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

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "entities": {
      "item002": {
        "enabled": false,
        "displayName": "Example item 2",
        "number": 200
      },
      "item001": {
        "enabled": true,
        "displayName": "Example item 1",
        "number": 300
      }
    },
    "entitiesArray": "[items(variables('entities'))]"
  },
  "resources": [],
  "outputs": {
    "itemsResult": {
      "type": "array",
      "value": "[variables('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 資料類型。

在 Bicep 中,使用 json 函式。

參數

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

傳回值

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

備註

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

您也可以使用 null() 來取得 Null 值。

範例

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "jsonEmptyObject": {
      "type": "string",
      "defaultValue": "null"
    },
    "jsonObject": {
      "type": "string",
      "defaultValue": "{\"a\": \"b\"}"
    },
    "jsonString": {
      "type": "string",
      "defaultValue": "\"test\""
    },
    "jsonBoolean": {
      "type": "string",
      "defaultValue": "true"
    },
    "jsonInt": {
      "type": "string",
      "defaultValue": "3"
    },
    "jsonArray": {
      "type": "string",
      "defaultValue": "[[1,2,3 ]"
    },
    "concatValue": {
      "type": "string",
      "defaultValue": "demo value"
    }
  },
  "resources": [
  ],
  "outputs": {
    "emptyObjectOutput": {
      "type": "bool",
      "value": "[empty(json(parameters('jsonEmptyObject')))]"
    },
    "objectOutput": {
      "type": "object",
      "value": "[json(parameters('jsonObject'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[json(parameters('jsonString'))]"
    },
    "booleanOutput": {
      "type": "bool",
      "value": "[json(parameters('jsonBoolean'))]"
    },
    "intOutput": {
      "type": "int",
      "value": "[json(parameters('jsonInt'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[json(parameters('jsonArray'))]"
    },
    "concatObjectOutput": {
      "type": "object",
      "value": "[json(concat('{\"a\": \"', parameters('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)

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

在 Bicep 中,使用 length 函式。

參數

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

傳回值

整數。

範例

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "stringToTest": {
      "type": "string",
      "defaultValue": "One Two Three"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "propA": "one",
        "propB": "two",
        "propC": "three",
        "propD": {
          "propD-1": "sub",
          "propD-2": "sub"
        }
      }
    }
  },
  "resources": [],
  "outputs": {
    "arrayLength": {
      "type": "int",
      "value": "[length(parameters('arrayToTest'))]"
    },
    "stringLength": {
      "type": "int",
      "value": "[length(parameters('stringToTest'))]"
    },
    "objectLength": {
      "type": "int",
      "value": "[length(parameters('objectToTest'))]"
    }
  }
}

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

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

null

null()

傳回 null。

null 函式無法在 Bicep 中使用。 請改為使用 null 關鍵字。

參數

Null 函式不接受任何參數。

傳回值

一律為 Null 的值。

範例

下列範例使用 Null 函式。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "emptyOutput": {
      "type": "bool",
      "value": "[empty(null())]"
    }
  }
}

前述範例的輸出為:

名稱 類型
emptyOutput Bool True

objectKeys

objectKeys(object)

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

在 Bicep 中,使用 objectKeys 函 式。

參數

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

傳回值

陣列。

範例

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "obj": {
      "a": 1,
      "b": 2
    }
  },
  "resources": [],
  "outputs": {
    "keyArray": {
      "type": "array",
      "value": "[objectKeys(variables('obj'))]"
    }
  }
}

前述範例的輸出為:

名稱 類型
keyArray 陣列 [ “a”, “b” ]

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

shallowMerge

shallowMerge(inputArray)

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

在 Bicep 中,使用 淺層Merge 函 式。

參數

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

傳回值

物件。

範例

下列範例顯示如何使用 shallowMerge

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "firstArray": [
      {
        "one": "a"
      },
      {
        "two": "b"
      },
      {
        "two": "c"
      }
    ],
    "secondArray": [
      {
        "one": "a",
        "nested": {
          "a": 1,
          "nested": {
            "c": 3
          }
        }
      },
      {
        "two": "b",
        "nested": {
          "b": 2
        }
      }
    ]
  },
  "resources": [],
  "outputs": {
    "firstOutput": {
      "type": "object",
      "value": "[shallowMerge(variables('firstArray'))]"
    },
    "secondOutput": {
      "type": "object",
      "value": "[shallowMerge(variables('secondArray'))]"
    }
  }
}

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

名稱 類型
firstOutput object {“one”:“a”,“two”:“c”}
secondOutput object {“one”:“a”,“nested”:{“b”:2},“two”:“b”}

firstOutput 會顯示合併物件的屬性會合併成新的 物件。 如果有衝突的屬性(亦即具有相同名稱的屬性),則最後一個合併物件中的屬性通常優先。

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

union

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

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

在 Bicep 中,使用 union 函式。

參數

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

傳回值

陣列或物件。

備註

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

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

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

union 函式不僅會合併最上層元素,而且會以遞迴方式合併其中的任何巢狀陣列與物件。 請參閱下一節中的第二個範例。

範例

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c1"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "three": "c2",
        "four": "d",
        "five": "e"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "three", "four" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[union(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[union(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

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

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

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "firstObject": {
      "property": {
        "one": "a",
        "two": "b",
        "three": "c1"
      },
      "nestedArray": [
        1,
        2
      ]
    },
    "secondObject": {
      "property": {
        "three": "c2",
        "four": "d",
        "five": "e"
      },
      "nestedArray": [
        3,
        4
      ]
    },
    "firstArray": [
      [
        "one",
        "two"
      ],
      [
        "three"
      ]
    ],
    "secondArray": [
      [
        "three"
      ],
      [
        "four",
        "two"
      ]
    ]
  },
  "resources": [],
  "outputs": {
    "objectOutput": {
      "type": "Object",
      "value": "[union(variables('firstObject'), variables('secondObject'))]"
    },
    "arrayOutput": {
      "type": "Array",
      "value": "[union(variables('firstArray'), variables('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"]]。

下一步