Funkcje obiektów dla szablonów usługi ARM

Usługa Resource Manager udostępnia kilka funkcji do pracy z obiektami w szablonie usługi Azure Resource Manager (szablon usługi ARM):

• zawiera
• createObject
• pusty
• skrzyżowanie
• Elementy
• JSON
• długości
• zero
• unia

zawiera

contains(container, itemToFind)

Sprawdza, czy tablica zawiera wartość, obiekt zawiera klucz lub ciąg zawiera podciąg. Porównanie ciągów uwzględnia wielkość liter. Jednak podczas testowania, czy obiekt zawiera klucz, porównanie jest bez uwzględniania wielkości liter.

W Bicep użyj contains funkcji .

Parametry

Wartość zwracana

Wartość True , jeśli element zostanie znaleziony; w przeciwnym razie wartość False.

Przykład

W poniższym przykładzie pokazano, jak używać z contains różnymi typami:

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

Dane wyjściowe wartości domyślnych z poprzedniego przykładu to:

createObject

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

Tworzy obiekt na podstawie kluczy i wartości.

Funkcja nie jest obsługiwana createObject przez Bicep. Skonstruuj obiekt przy użyciu polecenia {}. Zobacz Obiekty.

Parametry

Funkcja akceptuje tylko parzystą liczbę parametrów. Każdy klucz musi mieć zgodną wartość.

Wartość zwracana

Obiekt z każdą parą klucz i wartość.

Przykład

Poniższy przykład tworzy obiekt z różnych typów wartości:

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

Dane wyjściowe z poprzedniego przykładu z wartościami domyślnymi to obiekt o nazwie newObject o następującej wartości:

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

pusty

empty(itemToTest)

Określa, czy tablica, obiekt lub ciąg jest pusta.

W Bicep użyj empty funkcji .

Parametry

Wartość zwracana

Zwraca wartość True , jeśli wartość jest pusta; w przeciwnym razie wartość False.

Przykład

Poniższy przykład sprawdza, czy tablica, obiekt i ciąg są puste:

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

Dane wyjściowe wartości domyślnych z poprzedniego przykładu to:

skrzyżowanie

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

Zwraca pojedynczą tablicę lub obiekt z typowymi elementami z parametrów.

W Bicep użyj intersection funkcji .

Parametry

Wartość zwracana

Tablica lub obiekt ze wspólnymi elementami.

Przykład

W poniższym przykładzie pokazano, jak używać z intersection tablicami i obiektami:

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

Dane wyjściowe wartości domyślnych z poprzedniego przykładu to:

przedmioty

items(object)

Konwertuje obiekt słownika na tablicę. Zobacz obiekt toObject dotyczący konwertowania tablicy na obiekt.

W Bicep użyj items funkcji .

Parametry

Wartość zwracana

Tablica obiektów dla przekonwertowanego słownika. Każdy obiekt w tablicy ma właściwość zawierającą key wartość klucza słownika. Każdy obiekt ma również właściwość zawierającą value właściwości obiektu.

Przykład

Poniższy przykład konwertuje obiekt słownika na tablicę, tworząc nowy obiekt z zmodyfikowanymi wartościami dla każdego obiektu w tablicy:

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

Powyższy przykład zwraca następujące dane:

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

W poniższym przykładzie pokazano tablicę zwracaną przez items funkcję:

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

Przykład zwraca następujące dane:

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

W formacie JSON obiekt jest nieurządkowaną kolekcją par klucz/wartość zero lub więcej. Kolejność może być różna w zależności od implementacji. Na przykład funkcja Bicep items() sortuje obiekty w kolejności alfabetycznej. W innych miejscach można zachować oryginalną kolejność. Ze względu na ten niedeterminizm należy unikać wprowadzania wszelkich założeń dotyczących porządkowania kluczy obiektów podczas pisania kodu, który wchodzi w interakcje z parametrami i danymi wyjściowymi wdrożeń.

JSON

json(arg1)

Konwertuje prawidłowy ciąg JSON na typ danych JSON.

W Bicep użyj json funkcji .

Parametry

Wartość zwracana

Typ danych JSON z określonego ciągu lub wartość pusta w przypadku określenia wartości null .

Uwagi

Jeśli musisz uwzględnić wartość parametru lub zmienną w obiekcie JSON, użyj format funkcji , aby utworzyć ciąg przekazywany do funkcji.

Możesz również użyć null() polecenia , aby uzyskać wartość null.

Przykład

W poniższym przykładzie pokazano, jak używać json funkcji. Zwróć uwagę, że można przekazać null element dla pustego obiektu:

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

Dane wyjściowe wartości domyślnych z poprzedniego przykładu to:

długość

length(arg1)

Zwraca liczbę elementów w tablicy, znaki w ciągu lub właściwości na poziomie głównym w obiekcie.

W Bicep użyj length funkcji .

Parametry

Wartość zwracana

Int.

Przykład

W poniższym przykładzie pokazano, jak używać z length tablicą i ciągiem:

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

Dane wyjściowe wartości domyślnych z poprzedniego przykładu to:

null

null()

Zwraca wartość null.

Funkcja null nie jest dostępna w Bicep. Zamiast tego użyj słowa kluczowego null .

Parametry

Funkcja null nie akceptuje żadnych parametrów.

Wartość zwracana

Wartość, która zawsze ma wartość null.

Przykład

W poniższym przykładzie użyto null funkcji :

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

Dane wyjściowe z poprzedniego przykładu to:

objectKeys

objectKeys(object)

Zwraca klucze z obiektu, w którym obiekt jest kolekcją par klucz-wartość.

W Bicep użyj objectKeys funkcji .

Parametry

Wartość zwracana

Tablicy.

Przykład

W poniższym przykładzie pokazano, jak używać z objectKeys obiektem:

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

Dane wyjściowe z poprzedniego przykładu to:

W formacie JSON obiekt jest nieurządkowaną kolekcją par klucz/wartość zero lub więcej. Kolejność może być różna w zależności od implementacji. Na przykład funkcja Bicep items() sortuje obiekty w kolejności alfabetycznej. W innych miejscach można zachować oryginalną kolejność. Ze względu na ten niedeterminizm należy unikać wprowadzania wszelkich założeń dotyczących porządkowania kluczy obiektów podczas pisania kodu, który wchodzi w interakcje z parametrami i danymi wyjściowymi wdrożeń.

płytkieMerge

shallowMerge(inputArray)

Łączy tablicę obiektów, w których scalane są tylko obiekty najwyższego poziomu. Oznacza to, że jeśli scalane obiekty zawierają zagnieżdżone obiekty, te zagnieżdżone obiekty nie są głęboko scalane; zamiast tego są one całkowicie zastępowane przez odpowiednią właściwość z scalanego obiektu.

W Bicep użyj shallowMerge funkcji .

Parametry

Wartość zwracana

Obiekt .

Przykład

W poniższym przykładzie pokazano, jak używać 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'))]"
    }
  }
}

Dane wyjściowe wartości domyślnych z poprzedniego przykładu to:

firstOutput pokazuje właściwości z scalanych obiektów są łączone w nowy obiekt. Jeśli występują właściwości powodujące konflikt (tj. właściwości o tej samej nazwie), właściwość z ostatniego obiektu, który jest scalany, zwykle ma pierwszeństwo.

secondOutput pokazuje płytkie scalanie nie rekursywnie scala tych zagnieżdżonych obiektów. Zamiast tego cały zagnieżdżony obiekt jest zastępowany przez odpowiednią właściwość z scalanego obiektu.

tryGet

tryGet(itemToTest, keyOrIndex)

tryGet Pomaga uniknąć niepowodzeń wdrażania podczas próby uzyskania dostępu do nieistniejących właściwości lub indeksów w obiekcie lub tablicy. Jeśli określony klucz lub indeks nie istnieje, tryGet zwraca wartość null zamiast zgłaszać błąd.

W Bicep użyj operatora safe-dereference .

Parametry

Wartość zwracana

Zwraca wartość w kluczu/indeksie, jeśli istnieje. Zwraca wartość null, jeśli brakuje klucza/indeksu lub poza granicami.

Przykład

Poniższy przykład sprawdza, czy tablica, obiekt i ciąg są puste:

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

Dane wyjściowe z poprzedniego przykładu to:

związek

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

Zwraca pojedynczą tablicę lub obiekt ze wszystkimi elementami z parametrów. W przypadku tablic są uwzględniane zduplikowane wartości raz. W przypadku obiektów zduplikowane nazwy właściwości są uwzględniane tylko raz.

W Bicep użyj union funkcji .

Parametry

Wartość zwracana

Tablica lub obiekt.

Uwagi

Funkcja union używa sekwencji parametrów, aby określić kolejność i wartości wyniku.

W przypadku tablic funkcja iteruje każdy element w pierwszym parametrze i dodaje go do wyniku, jeśli nie jest jeszcze obecny. Następnie powtarza proces dla drugiego parametru i innych parametrów. Jeśli wartość jest już obecna, jej wcześniejsze umieszczenie w tablicy jest zachowywane.

W przypadku obiektów nazwy właściwości i wartości z pierwszego parametru są dodawane do wyniku. W przypadku późniejszych parametrów wszystkie nowe nazwy są dodawane do wyniku. Jeśli późniejszy parametr ma właściwość o tej samej nazwie, ta wartość zastępuje istniejącą wartość. Kolejność właściwości nie jest gwarantowana.

Funkcja union nie tylko scala elementy najwyższego poziomu, ale także rekursywnie scala wszystkie zagnieżdżone tablice i obiekty w nich. Zobacz drugi przykład w poniższej sekcji.

Przykład

W poniższym przykładzie pokazano, jak używać z union tablicami i obiektami:

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

Dane wyjściowe wartości domyślnych z poprzedniego przykładu to:

W poniższym przykładzie przedstawiono możliwość głębokiego scalania:

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

Dane wyjściowe z poprzedniego przykładu to:

Jeśli zagnieżdżone tablice zostały scalone, wartość objectOutput.nestedArray będzie wynosić [1, 2, 3, 4], a wartość arrayOutput będzie wynosić [["jeden", "dwa", "trzy"], ["trzy", "cztery", "dwa"]].

Dalsze kroki

Aby zapoznać się z opisem sekcji w szablonie usługi ARM, zobacz Omówienie struktury i składni szablonów usługi ARM.