Objektfunktionen für ARM-Vorlagen

Artikel
01/12/2024

Resource Manager stellt mehrere Funktionen für das Arbeiten mit Objekten in Ihrer Azure Resource Manager-Vorlage (ARM-Vorlage) bereit:

contains
createObject
empty
intersection
items
json
length
null
union

Tipp

Wir empfehlen Bicep, weil es dieselben Funktionen wie ARM-Vorlagen bietet und die Syntax einfacher zu verwenden ist. Weitere Informationen finden Sie unter Objektfunktionen.

contains

contains(container, itemToFind)

Überprüft, ob ein Array einen Wert enthält, ein Objekt einen Schlüssel enthält oder eine Zeichenfolge eine Teilzeichenfolge enthält. Die Groß-/Kleinschreibung wird beim Zeichenfolgenvergleich beachtet. Wenn Sie jedoch testen, ob ein Objekt einen Schlüssel enthält, wird die Groß-/Kleinschreibung beim Vergleich nicht beachtet.

Verwenden Sie in Bicep die contains-Funktion.

Parameter

Parameter	Erforderlich	Type	BESCHREIBUNG
Container	Ja	Array, Objekt oder Zeichenfolge	Der Wert, der den zu suchenden Wert enthält.
itemToFind	Ja	Zeichenfolge oder ganze Zahl	Der zu suchende Wert.

Rückgabewert

True, wenn das Element gefunden wurde; andernfalls False.

Beispiel

Das folgende Beispiel zeigt die Verwendung von „contains“ mit unterschiedlichen Typen:

{
  "$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')]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel mit den Standardwerten lautet:

Name	type	Wert
stringTrue	Bool	True
stringFalse	Bool	False
objectTrue	Bool	True
objectFalse	Bool	False
arrayTrue	Bool	True
arrayFalse	Bool	False

createObject

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

Erstellt ein Objekt aus den Schlüsseln und Werten.

Die createObject-Funktion wird von Bicep nicht unterstützt. Erstellen Sie ein-Objekt, indem Sie {} verwenden. Weitere Informationen finden Sie unter Objekte.

Parameter

Parameter	Erforderlich	Type	BESCHREIBUNG
key1	Nein	Zeichenfolge	Der Name des Schlüssels.
value1	Nein	int, boolean, string, object oder array	Der Wert für den Schlüssel.
Mehr Schlüssel	Nein	Zeichenfolge	Mehr Namen der Schlüssel.
Mehr Werte	Nein	int, boolean, string, object oder array	Mehr Werte für die Schlüssel.

Die Funktion akzeptiert nur eine gerade Anzahl von Parametern. Jeder Schlüssel muss über einen entsprechenden Wert verfügen.

Rückgabewert

Ein Objekt mit jedem Schlüssel-Wert-Paar.

Beispiel

Im folgenden Beispiel wird ein Objekt aus verschiedenen Werttypen erstellt.

{
  "$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'))]"
    }
  }
}

Die Ausgabe des vorherigen Beispiels mit den Standardwerten ist ein Objekt namens newObject mit folgendem Wert:

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

empty

empty(itemToTest)

Bestimmt, ob ein Array, Objekt oder eine Zeichenfolge leer ist.

Verwenden Sie in Bicep die empty-Funktion.

Parameter

Parameter	Erforderlich	Type	BESCHREIBUNG
itemToTest	Ja	Array, Objekt oder Zeichenfolge	Der Wert, für den überprüft werden soll, ob er leer ist.

Rückgabewert

Gibt True zurück, wenn der Werte leer ist. Andernfalls wird False zurückgegeben.

Beispiel

Im folgenden Beispiel wird überprüft, ob ein Array, Objekt und eine Zeichenfolge leer sind.

{
  "$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'))]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel mit den Standardwerten lautet:

Name	type	Wert
arrayEmpty	Bool	True
objectEmpty	Bool	True
stringEmpty	Bool	True

Schnittmenge

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

Gibt ein einzelnes Array oder ein Objekt mit den gemeinsamen Elementen aus den Parametern zurück.

Verwenden Sie in Bicep die intersection-Funktion.

Parameter

Parameter	Erforderlich	Type	BESCHREIBUNG
arg1	Ja	Array oder Objekt	Der erste Wert für die Suche nach gemeinsamen Elementen.
arg2	Ja	Array oder Objekt	Der zweite Wert für die Suche nach gemeinsamen Elementen.
mehr Argumente	Nein	Array oder Objekt	Mehr Werte für die Suche nach gemeinsamen Elementen.

Rückgabewert

Ein Array oder Objekt mit den gemeinsamen Elementen.

Beispiel

Das folgende Beispiel zeigt, wie Sie die Schnittmenge mit Arrays und Objekten verwenden können.

{
  "$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'))]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel mit den Standardwerten lautet:

Name	type	Wert
objectOutput	Object	{"one": "a", "three": "c"}
arrayOutput	Array	["two", "three"]

items

items(object)

Konvertiert ein Wörterbuchobjekt in ein Array. Informationen zum Konvertieren eines Arrays in ein Objekt finden Sie unter toObject.

Verwenden Sie in Bicep die Elemente.

Parameter

Parameter	Erforderlich	Type	Beschreibung
Objekt (object)	Ja	Objekt (object)	Das Wörterbuchobjekt, das in ein Array konvertiert werden soll.

Rückgabewert

Ein Array von Objekten für das konvertierte Wörterbuch. Jedes Objekt in dem Array verfügt über eine key-Eigenschaft, die den Schlüsselwert für das Wörterbuch enthält. Jedes Objekt verfügt außerdem über eine value-Eigenschaft, die die Eigenschaften für das Objekt enthält.

Beispiel

Im folgenden Beispiel wird ein Wörterbuchobjekt in ein Array konvertiert. Für jedes Objekt im Array wird ein neues Objekt mit geänderten Werten erstellt.

{
  "$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')]"
    }
  }
}

Im vorherigen Beispiel wird Folgendes zurückgegeben:

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

Im folgenden Beispiel wird das Array angezeigt, das von der items-Funktion zurückgegeben wird.

{
  "$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')]"
    }
  }
}

Die Rückgabe des Beispiels lautet wie folgt:

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

In JSON ist ein Objekt eine nicht geordnete Auflistung von null oder mehr Schlüssel-Wert-Paaren. Die Reihenfolge kann je nach Implementierung unterschiedlich sein. Die Items()-Funktion von Bicep sortiert die Objekte beispielsweise in alphabetischer Reihenfolge. An anderen Stellen kann die ursprüngliche Reihenfolge beibehalten werden. Aufgrund dieses Nicht-Determinismus sollten Sie beim Schreiben von Code, der mit den Parametern und Ausgaben der Bereitstellung interagiert, keine Annahmen über die Reihenfolge der Objektschlüssel anstellen.

json

json(arg1)

Konvertiert eine gültige JSON-Zeichenfolge in einen JSON-Datentyp.

Verwenden Sie in Bicep die json-Funktion.

Parameter

Parameter	Erforderlich	Type	BESCHREIBUNG
arg1	Ja	Zeichenfolge	Der in JSON zu konvertierende Wert. Die Zeichenfolge muss eine ordnungsgemäß formatierte JSON-Zeichenfolge sein.

Rückgabewert

Der JSON-Datentyp aus der angegebenen Zeichenfolge oder ein leerer Wert, wenn null angegeben ist.

Hinweise

Wenn Sie einen Parameterwert oder eine Variable in das JSON-Objekt einschließen möchten, verwenden Sie die Funktion Format, um die Zeichenfolge zu erstellen, die Sie an die Funktion übergeben.

Sie können auch null() verwenden, um einen NULL-Wert zu erhalten.

Beispiel

Das folgende Beispiel zeigt die Verwendung der Funktion json. Beachten Sie, dass Sie null für ein leeres Objekt übergeben können.

{
  "$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'), '\"}'))]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel mit den Standardwerten lautet:

Name	type	Wert
emptyObjectOutput	Boolesch	True
objectOutput	Object	{"a": "b"}
stringOutput	String	test
booleanOutput	Boolesch	True
intOutput	Integer	3
arrayOutput	Array	[ 1, 2, 3 ]
concatObjectOutput	Object	{ "a": "demo value" }

length

length(arg1)

Gibt die Anzahl von Elementen in einem Array, Zeichen in einer Zeichenfolge oder Eigenschaften auf Stammebene in einem Objekt zurück.

Verwenden Sie in Bicep die length-Funktion.

Parameter

Parameter	Erforderlich	Type	BESCHREIBUNG
arg1	Ja	Array, Zeichenfolge oder Objekt	Das Array, von dem die Anzahl der Elemente ermittelt werden soll, die Zeichenfolge, von der die Anzahl der Zeichen ermittelt werden soll, oder das Objekt, von dem die Anzahl der Eigenschaften auf Stammebene ermittelt werden soll.

Rückgabewert

Eine ganze Zahl.

Beispiel

Im folgenden Beispiel wird die Verwendung von „length“ mit einem Array und einer Zeichenfolge gezeigt:

{
  "$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'))]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel mit den Standardwerten lautet:

Name	type	Wert
arraylength	Int	3
stringLength	Int	13
objectLength	Int	4

NULL

null()

Gibt NULL zurück.

Die Funktion null ist in Bicep nicht verfügbar. Verwenden Sie stattdessen das Schlüsselwort null.

Parameter

Die Funktion „null“ akzeptiert keine Parameter.

Rückgabewert

Ein Wert, der immer „NULL“ lautet.

Beispiel

Das folgende Beispiel verwendet die „null“-Funktion.

{
  "$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())]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel lautet wie folgt:

Name	type	Wert
emptyOutput	Bool	True

union

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

Gibt ein einzelnes Array oder Objekt mit allen Elementen aus den Parametern zurück. Bei Arrays werden doppelte Werte einmal einbezogen. Bei Objekten werden doppelte Eigenschaftsnamen nur einmal einbezogen.

Verwenden Sie in Bicep die union-Funktion.

Parameter

Parameter	Erforderlich	Type	BESCHREIBUNG
arg1	Ja	Array oder Objekt	Der erste zum Verknüpfen von Elementen zu verwendende Wert.
arg2	Ja	Array oder Objekt	Der zweite zum Verknüpfen von Elementen zu verwendende Wert.
mehr Argumente	Nein	Array oder Objekt	Mehr zum Verknüpfen von Elementen zu verwendende Werte.

Rückgabewert

Ein Array oder Objekt.

Hinweise

Die Union-Funktion bestimmt anhand der Abfolge der Parameter die Reihenfolge und die Werte des Ergebnisses.

Bei Arrays durchläuft die Funktion jedes Element im ersten Parameter und fügt es dem Ergebnis hinzu, falls nicht bereits vorhanden. Dann wird der Vorgang für den zweiten und alle weiteren Parameter wiederholt. Wenn ein Wert bereits vorhanden ist, wird seine frühere Platzierung im Array beibehalten.

Für Objekte werden Eigenschaftennamen und Werte aus dem ersten Parameter zum Ergebnis hinzugefügt. Bei späteren Parametern werden dem Ergebnis alle neuen Namen hinzugefügt. Wenn ein späterer Parameter über eine Eigenschaft mit demselben Namen verfügt, überschreibt dieser Wert den vorhandenen Wert. Die Reihenfolge der Eigenschaften ist nicht garantiert.

Die Union-Funktion führt nicht nur die Elemente der obersten Ebene zusammen, sondern auch rekursiv alle darin enthaltenen geschachtelten Arrays und Objekte. Sehen Sie sich das zweite Beispiel im folgenden Abschnitt an.

Beispiel

Im folgenden Beispiel wird die Verwendung von „union“ mit Arrays und Objekten gezeigt:

{
  "$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'))]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel mit den Standardwerten lautet:

Name	type	Wert
objectOutput	Object	{"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput	Array	["one", "two", "three", "four"]

Das folgende Beispiel zeigt die Funktion „Deep Merge“:

{
  "$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'))]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel lautet wie folgt:

Name	type	Wert
objectOutput	Object	{"property":{"one":"a","two":"b","three":"c2","four":"d","five":"e"},"nestedArray":[3,4]}
arrayOutput	Array	[["one","two"],["three"],["four","two"]]

Wenn geschachtelte Arrays zusammengeführt wurden, lautet der Wert von objectOutput.nestedArray [1, 2, 3, 4], und der Wert von arrayOutput wäre [["one", "two", "three"], ["three", "four", "two"]].

Nächste Schritte

Eine Beschreibung der Abschnitte in einer ARM-Vorlage finden Sie unter Grundlegendes zur Struktur und Syntax von ARM-Vorlagen.

Objektfunktionen für ARM-Vorlagen

contains

Parameter

Rückgabewert

Beispiel

createObject

Parameter

Rückgabewert

Beispiel

empty

Parameter

Rückgabewert

Beispiel

Schnittmenge

Parameter

Rückgabewert

Beispiel

items

Parameter

Rückgabewert

Beispiel

json

Parameter

Rückgabewert

Hinweise

Beispiel

length

Parameter

Rückgabewert

Beispiel

NULL

Parameter

Rückgabewert

Beispiel

union

Parameter

Rückgabewert

Hinweise

Beispiel

Nächste Schritte

Zusätzliche Ressourcen