Objektfunktionen für ARM-Vorlagen

Der Ressourcen-Manager bietet mehrere Funktionen zum Arbeiten mit Objekten in Ihrer Azure Resource Manager-Vorlage (ARM-Vorlage):

• enthält
• createObject
• leer
• Schnittpunkt
• Elemente
• json
• Länge
• null
• Gewerkschaft

enthält

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.

Die Parameter

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 der Standardwerte aus dem vorherigen Beispiel lautet:

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 eines Objekts mithilfe von {}. Siehe Objekte.

Die Parameter

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

Rückgabewert

Ein Objekt mit jedem Schlüssel- und Wertpaar.

Beispiel

Im folgenden Beispiel wird ein Objekt aus verschiedenen Typen von Werten 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 aus dem vorherigen Beispiel mit den Standardwerten ist ein Objekt newObject mit dem folgenden Wert:

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

leer

empty(itemToTest)

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

Verwenden Sie in Bicep die empty Funktion.

Die Parameter

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, ein 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 der Standardwerte aus dem vorherigen Beispiel lautet:

Schnittmenge

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

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

Verwenden Sie in Bicep die intersection Funktion.

Die Parameter

Rückgabewert

Ein Array oder Objekt mit den gemeinsamen Elementen.

Beispiel

Das folgende Beispiel zeigt die Verwendung von intersection mit Arrays und Objekten:

{
  "$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 der Standardwerte aus dem vorherigen Beispiel lautet:

Gegenstände

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 items Funktion.

Die Parameter

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, wobei ein neues Objekt mit geänderten Werten für jedes Objekt im Array erstellt wird:

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

Das folgende Beispiel zeigt das Array, das die items Funktion zurückgibt:

{
  "$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. Beispielsweise sortiert die Bicep items() -Funktion die Objekte in der alphabetischen 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.

Die Parameter

Rückgabewert

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

Bemerkungen

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

Sie können auch einen null() NULL-Wert abrufen.

Beispiel

Das folgende Beispiel zeigt die Verwendung der Funktion json. Beachten Sie, dass Sie ein leeres Objekt übergeben null 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 der Standardwerte aus dem vorherigen Beispiel lautet:

Länge

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.

Die Parameter

Rückgabewert

Eine ganze Zahl.

Beispiel

Das folgende Beispiel zeigt die Verwendung von length mit einem Array und einer Zeichenfolge:

{
  "$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 der Standardwerte aus dem vorherigen Beispiel lautet:

NULL

null()

Gibt NULL zurück.

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

Die Parameter

Die null Funktion akzeptiert keine Parameter.

Rückgabewert

Ein Wert, der immer NULL ist.

Beispiel

Im folgenden Beispiel wird die null Funktion verwendet:

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

objectKeys

objectKeys(object)

Gibt die Schlüssel aus einem Objekt zurück, das eine Auflistung von Schlüssel-Wert-Paaren ist.

Verwenden Sie in Bicep die objectKeys Funktion.

Die Parameter

Rückgabewert

Ein -Array.

Beispiel

Das folgende Beispiel zeigt die Verwendung von objectKeys mit einem Objekt:

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

Die Ausgabe aus dem vorherigen Beispiel lautet wie folgt:

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. Beispielsweise sortiert die Bicep items() -Funktion die Objekte in der alphabetischen 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.

flacheMerge

shallowMerge(inputArray)

Kombiniert ein Array von Objekten, bei denen nur die Objekte der obersten Ebene zusammengeführt werden. Wenn die zusammengeführten Objekte geschachtelte Objekte enthalten, werden diese verschachtelten Objekte nicht tief zusammengeführt; Stattdessen werden sie vollständig durch die entsprechende Eigenschaft aus dem zusammenführenden Objekt ersetzt.

Verwenden Sie in Bicep die shallowMerge Funktion.

Die Parameter

Rückgabewert

Ein Objekt.

Beispiel

Das folgende Beispiel zeigt die Verwendung von 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'))]"
    }
  }
}

Die Ausgabe der Standardwerte aus dem vorherigen Beispiel lautet:

firstOutput zeigt die Eigenschaften der zusammenzuführenden Objekte in einem neuen Objekt an. Wenn konfliktende Eigenschaften (d. h. Eigenschaften mit demselben Namen) vorhanden sind, hat die Eigenschaft aus dem letzten zusammengeführten Objekt in der Regel Vorrang.

secondOutput zeigt, dass die flache Zusammenführung diese geschachtelten Objekte nicht rekursiv zusammenführt. Stattdessen wird das gesamte geschachtelte Objekt durch die entsprechende Eigenschaft aus dem zusammenzuführenden Objekt ersetzt.

tryGet

tryGet(itemToTest, keyOrIndex)

tryGet hilft Ihnen, Bereitstellungsfehler zu vermeiden, wenn Sie versuchen, auf eine nicht vorhandene Eigenschaft oder einen Index in einem Objekt oder Array zuzugreifen. Wenn der angegebene Schlüssel oder Index nicht vorhanden ist, wird null zurückgegeben, tryGet anstatt einen Fehler zu auslösen.

Verwenden Sie in Bicep den Operator "safe-dereference" .

Die Parameter

Rückgabewert

Gibt den Wert am Schlüssel/Index zurück, wenn er vorhanden ist. Gibt NULL zurück, wenn der Schlüssel/Index fehlt oder außerhalb der Grenzen liegt.

Beispiel

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "variables": {
    "users": {
      "name": "John Doe",
      "age": 30
    },
    "colors": [
      "red",
      "green"
    ]
  },
  "resources": [],
  "outputs": {
    "region": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('users'), 'region')]"
    },
    "name": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('users'), 'name')]"
    },
    "firstColor": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('colors'), 0)]"
    }
  }
}

Die Ausgabe aus dem vorherigen Beispiel lautet wie folgt:

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.

Die Parameter

Rückgabewert

Ein Array oder Objekt.

Bemerkungen

Die union Funktion verwendet die Sequenz der Parameter, um die Reihenfolge und Werte des Ergebnisses zu bestimmen.

Bei Arrays durchläuft die Funktion jedes Element im ersten Parameter und fügt es dem Ergebnis hinzu, falls nicht bereits vorhanden. Danach 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 führt auch rekursiv alle geschachtelten Arrays und Objekte darin zusammen. Sehen Sie sich das zweite Beispiel im folgenden Abschnitt an.

Beispiel

Das folgende Beispiel zeigt die Verwendung von union mit Arrays und Objekten:

{
  "$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 der Standardwerte aus dem vorherigen Beispiel lautet:

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:

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.