ARM 範本的物件函式

發行項
03/22/2024

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

contains
createObject
empty
intersection
items
json
length
null
union

提示

我們建議使用 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	陣列或物件	更多用於尋找共同元素的值。

傳回值

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

範例

下列範例顯示如何搭配陣列和物件使用交集。

{
  "$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

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"]]。

下一步

如需 ARM 範本中各章節的說明，請參閱了解 ARM 範本的結構和語法。

ARM 範本的物件函式

contains

參數

傳回值

範例

createObject

參數

傳回值

範例

empty

參數

傳回值

範例

交集

參數

傳回值

範例

項目

參數

傳回值

範例

json

參數

傳回值

備註

範例

length

參數

傳回值

範例

null

參數

傳回值

範例

union

參數

傳回值

備註

範例

下一步

其他資源