Funzioni degli oggetti per i modelli di Resource Manager

  • Articolo

Resource Manager offre diverse funzioni per l'uso di oggetti nel modello di Azure Resource Manager (modello di Resource Manager):

Suggerimento

È consigliabile Bicep perché offre le stesse funzionalità dei modelli di ARM e la sintassi è più semplice. Per altre informazioni, vedere Funzioni degli oggetti .

contains

contains(container, itemToFind)

Verifica se una matrice contiene un valore, se un oggetto contiene una chiave o se una stringa contiene una sottostringa. Il confronto fra stringhe fa distinzione tra maiuscole e minuscole. Tuttavia, quando si testa se un oggetto contiene una chiave, il confronto non fa distinzione tra maiuscole e minuscole.

In Bicep usare la funzione contains (contiene).

Parametri

Parametro Richiesto Type Descrizione
container Sì matrice, oggetto o stringa Valore che contiene il valore da trovare.
itemToFind Sì stringa o numero intero Valore da trovare.

Valore restituito

True se l'elemento viene individuato; in caso contrario, restituisce False.

Esempio

L'esempio seguente illustra come usare contains con tipi diversi:

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

L'output dell'esempio precedente con i valori predefiniti è il seguente:

Nome Type Valore
stringTrue Bool Vero
stringFalse Bool Falso
objectTrue Bool Vero
objectFalse Bool Falso
arrayTrue Bool Vero
arrayFalse Bool Falso

Createobject

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

Crea un oggetto dalle chiavi e dai valori.

La createObject funzione non è supportata da Bicep. Costruire un oggetto usando {}. Vedere Oggetti.

Parametri

Parametro Richiesto Type Descrizione
key1 No string Nome della chiave.
value1 No int, booleano, stringa, oggetto o matrice Valore della chiave.
altre chiavi No string Altri nomi delle chiavi.
altri valori No int, booleano, stringa, oggetto o matrice Altri valori per le chiavi.

La funzione accetta solo un numero pari di parametri. Ogni chiave deve avere un valore corrispondente.

Valore restituito

Oggetto con ogni coppia chiave e valore.

Esempio

Nell'esempio seguente viene creato un oggetto da diversi tipi di valori.

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

L'output dell'esempio precedente con i valori predefiniti è un oggetto denominato newObject con il valore seguente:

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

empty

empty(itemToTest)

Determina se una matrice, un oggetto o una stringa sono vuoti.

In Bicep usare la funzione empty (vuota).

Parametri

Parametro Richiesto Type Descrizione
itemToTest Sì matrice, oggetto o stringa Il valore per controllare se è vuota.

Valore restituito

True se il valore è vuoto; in caso contrario, restituisce False.

Esempio

L'esempio seguente controlla se una matrice, un oggetto e una stringa sono vuoti.

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

L'output dell'esempio precedente con i valori predefiniti è il seguente:

Nome Type Valore
arrayEmpty Bool Vero
objectEmpty Bool Vero
stringEmpty Bool Vero

intersection

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

Restituisce una matrice o un oggetto singoli con gli elementi comuni dei parametri.

In Bicep usare la funzione intersection (intersezione).

Parametri

Parametro Richiesto Type Descrizione
arg1 Sì matrice o oggetto Primo valore da usare per cercare elementi comuni.
arg2 Sì matrice o oggetto Secondo valore da usare per cercare elementi comuni.
altri argomenti No matrice o oggetto Valori aggiuntivi da usare per cercare elementi comuni.

Valore restituito

Una matrice o un oggetto con elementi comuni.

Esempio

Nell'esempio seguente viene illustrato come usare intersection con matrici e oggetti.

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

L'output dell'esempio precedente con i valori predefiniti è il seguente:

Nome Type Valore
objectOutput Oggetto {"one": "a", "three": "c"}
arrayOutput Matrice ["two", "three"]

articoli

items(object)

Converte in matrice un oggetto dizionario. Vedere toObject per informazioni sulla conversione di una matrice in un oggetto.

In Bicep usare gli elementi.

Parametri

Parametro Richiesto Type Descrizione
oggetto Sì oggetto L’oggetto dizionario da convertire in matrice.

Valore restituito

Matrice di oggetti per il dizionario convertito. Ogni oggetto nella matrice ha una proprietà key che contiene il valore della chiave per il dizionario. Ogni oggetto inoltre ha una proprietà value che contiene le proprietà per l'oggetto.

Esempio

Nell'esempio seguente un oggetto dizionario viene convertito in matrice. Per ciascun oggetto nella matrice, viene creato un nuovo oggetto con valori modificati.

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

L'esempio precedente restituisce:

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

L’esempio seguente mostra la matrice restituita dalla funzione elementi.

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

L’esempio restituisce:

"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 un oggetto è una raccolta non ordinata di zero o più coppie chiave/valore. L'ordinamento può variare, a seconda delle implementazioni. Ad esempio, la funzione elementi() Bicep dispone gli oggetti in ordine alfabetico. In altre posizioni, l'ordinamento di origine può essere mantenuto. Dato questo non determinismo, è preferibile evitare di fare ipotesi sull'ordinamento delle chiavi oggetto durante la scrittura del codice, che interagisce con i parametri e gli output delle distribuzioni.

JSON

json(arg1)

Converte una stringa JSON valida in un tipo di dati JSON.

In Bicep usare la funzione json .

Parametri

Parametro Richiesto Type Descrizione
arg1 Sì string Valore da convertire in JSON. La stringa deve essere una stringa JSON formattata correttamente.

Valore restituito

Il tipo di dati JSON dalla stringa specificata, o un valore vuoto quando viene specificato null.

Osservazioni:

Se è necessario includere un valore di parametro o una variabile nell'oggetto JSON, usare la funzione format per creare la stringa passata alla funzione.

È anche possibile usare null() per ottenere un valore Null.

Esempio

L'esempio seguente illustra come usare la funzione json. Si noti che è possibile passare null per un oggetto vuoto.

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

L'output dell'esempio precedente con i valori predefiniti è il seguente:

Nome Type Valore
emptyObjectOutput Booleano Vero
objectOutput Oggetto {"a": "b"}
stringOutput String test
booleanOutput Booleano Vero
intOutput Intero 3
arrayOutput Matrice [ 1, 2, 3 ]
concatObjectOutput Oggetto {"a": "valore demo"}

length

length(arg1)

Restituisce il numero di elementi in una matrice, caratteri in una stringa o proprietà a livello radice in un oggetto .

In Bicep usare la funzione length (lunghezza).

Parametri

Parametro Richiesto Type Descrizione
arg1 Sì matrice, stringa o oggetto La matrice da utilizzare per ottenere il numero di elementi, la stringa da utilizzare per ottenere il numero di caratteri o l'oggetto da utilizzare per ottenere il numero di proprietà a livello radice.

Valore restituito

Numero intero

Esempio

L'esempio seguente illustra come usare length con una matrice e una stringa:

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

L'output dell'esempio precedente con i valori predefiniti è il seguente:

Nome Type Valore
arrayLength Int 3
stringLength Int 13
objectLength Int 4

Null

null()

Restituisce Null.

La funzione null non è disponibile in Bicep. Usare invece la parola chiave null.

Parametri

La funzione null non accetta parametri.

Valore restituito

Valore sempre null.

Esempio

Nell'esempio seguente viene utilizzata la funzione 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())]"
    }
  }
}

L'output dell'esempio precedente è:

Nome Type Valore
emptyOutput Bool Vero

objectKeys

objectKeys(object)

Restituisce le chiavi di un oggetto, in cui un oggetto è una raccolta di coppie chiave-valore.

In Bicep usare la funzione objectKeys .

Parametri

Parametro Richiesto Type Descrizione
oggetto Sì oggetto Oggetto , che è una raccolta di coppie chiave-valore.

Valore restituito

Matrice .

Esempio

L'esempio seguente illustra come usare objectKeys con un oggetto :

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

L'output dell'esempio precedente è:

Nome Type Valore
keyArray Matrice [ "a", "b" ]

In JSON un oggetto è una raccolta non ordinata di zero o più coppie chiave/valore. L'ordinamento può variare, a seconda delle implementazioni. Ad esempio, la funzione elementi() Bicep dispone gli oggetti in ordine alfabetico. In altre posizioni, l'ordinamento di origine può essere mantenuto. Dato questo non determinismo, è preferibile evitare di fare ipotesi sull'ordinamento delle chiavi oggetto durante la scrittura del codice, che interagisce con i parametri e gli output delle distribuzioni.

shallowMerge

shallowMerge(inputArray)

Combina una matrice di oggetti, in cui vengono uniti solo gli oggetti di primo livello. Ciò significa che se gli oggetti uniti contengono oggetti annidati, tali oggetti annidati non vengono uniti in modo profondo; vengono invece sostituiti interamente dalla proprietà corrispondente dall'oggetto di unione.

In Bicep usare la funzione shallowMerge .

Parametri

Parametro Richiesto Type Descrizione
inputArray Sì array Matrice di oggetti .

Valore restituito

Oggetto .

Esempio

Nell'esempio riportato di seguito viene illustrato come usare 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'))]"
    }
  }
}

L'output dell'esempio precedente con i valori predefiniti è il seguente:

Nome Type Valore
firstOutput oggetto {"one":"a","two":"c"}
secondOutput oggetto {"one":"a","nested":{"b":2},"two":"b"}

firstOutput mostra che le proprietà degli oggetti di unione vengono combinate in un nuovo oggetto. Se sono presenti proprietà in conflitto(ad esempio, proprietà con lo stesso nome), la proprietà dell'ultimo oggetto da unire ha in genere la precedenza.

secondOutput mostra che l'unione superficiale non unisce in modo ricorsivo questi oggetti annidati. L'intero oggetto annidato viene invece sostituito dalla proprietà corrispondente dall'oggetto di unione.

union

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

Restituisce una matrice o un oggetto singoli con tutti gli elementi dei parametri. Per le matrici, i valori duplicati vengono inclusi una sola volta. Per gli oggetti, i nomi delle proprietà duplicati vengono inclusi una sola volta.

In Bicep usare la funzione union (unione).

Parametri

Parametro Richiesto Type Descrizione
arg1 Sì matrice o oggetto Primo valore da usare per l'aggiunta di elementi.
arg2 Sì matrice o oggetto Secondo valore da usare per l'aggiunta di elementi.
altri argomenti No matrice o oggetto Valori aggiuntivi da usare per unire gli elementi.

Valore restituito

Una matrice o un oggetto.

Osservazioni:

La funzione di unione usa la sequenza dei parametri per determinare l'ordine e i valori del risultato.

Per le matrici, la funzione itera attraverso ogni elemento nel primo parametro e lo aggiunge al risultato, se non è già presente. Ripete quindi il processo per il secondo parametro e per ogni parametro aggiuntivo. Se un valore è già presente, la sua posizione precedente nella matrice viene mantenuta.

Per gli oggetti, i nomi delle proprietà e i valori del primo parametro vengono aggiunti al risultato. Per i parametri successivi, tutti i nuovi nomi vengono aggiunti al risultato. Se un parametro successivo ha una proprietà con stesso nome, tale valore sovrascrive il valore esistente. L'ordine delle proprietà non è garantito.

La funzione di unione unisce non solo gli elementi di primo livello, ma anche l'unione ricorsiva di tutte le matrici e gli oggetti annidati all'interno di essi. Vedere il secondo esempio nella sezione seguente.

Esempio

L'esempio seguente illustra come usare union con matrici e oggetti:

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

L'output dell'esempio precedente con i valori predefiniti è il seguente:

Nome Type Valore
objectOutput Oggetto {"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput Matrice ["one", "two", "three", "four"]

L'esempio seguente mostra la funzionalità 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'))]"
    }
  }
}

L'output dell'esempio precedente è:

Nome Type Valore
objectOutput Oggetto {"property":{"one":"a","two":"b","three":"c2","four":"d","five":"e"},"nestedArray":[3,4]}
arrayOutput Matrice [["one","two"],["three"],["four","two"]]

Se le matrici annidate sono state unite, il valore di objectOutput.nestedArray sarà [1, 2, 3, 4], e il valore di arrayOutput sarà [["one", "two", "three"], ["three", "four", "two"]].

Passaggi successivi