Udostępnij za pośrednictwem

Definicje typów w szablonach usługi ARM

  • Artykuł

W tym artykule opisano sposób tworzenia i używania definicji w szablonie usługi Azure Resource Manager (szablon usługi ARM). Definiując własne typy, można ponownie użyć tych typów. Definicje typów mogą być używane tylko z languageVersion 2.0.

Uwaga

Bieżąca wersja rozszerzenia Azure Resource Manager Tools dla Visual Studio Code nie rozpoznaje ulepszeń w wersji languageVersion 2.0.

Porada

Zalecamy użycie aplikacji Bicep , ponieważ oferuje te same możliwości co szablony usługi ARM, a składnia jest łatwiejsza. Aby dowiedzieć się więcej, zobacz Typy danych zdefiniowane przez użytkownika w aplikacji Bicep.

Minimalna deklaracja

Co najmniej każda definicja typu wymaga nazwy i lub type$ref.

"definitions": {
  "demoStringType": {
    "type": "string"
  },
  "demoIntType": {
    "type": "int"
  },
  "demoBoolType": {
    "type": "bool"
  },
  "demoObjectType": {
    "type": "object"
  },
  "demoArrayType": {
    "type": "array"
  }
}

Dozwolone wartości

Dozwolone wartości można zdefiniować dla definicji typu. Dozwolone wartości są podane w tablicy. Wdrożenie kończy się niepowodzeniem podczas walidacji, jeśli wartość jest przekazywana dla definicji typu, która nie jest jedną z dozwolonych wartości.

"definitions": {
  "demoEnumType": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

Ograniczenia długości

Można określić minimalną i maksymalną długość definicji typu ciągu i tablicy. Można ustawić jedno lub oba ograniczenia. W przypadku ciągów długość wskazuje liczbę znaków. W przypadku tablic długość wskazuje liczbę elementów w tablicy.

W poniższym przykładzie zadeklarowane są dwie definicje typów. Jedną z definicji typów jest nazwa konta magazynu, która musi zawierać od 3 do 24 znaków. Druga definicja typu to tablica, która musi zawierać od 1 do 5 elementów.

"definitions": {
  "storageAccountNameType": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNameType": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

Ograniczenia liczb całkowitych

Możesz ustawić wartości minimalne i maksymalne dla definicji typów liczb całkowitych. Można ustawić jedno lub oba ograniczenia.

"definitions": {
  "monthType": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

Ograniczenia obiektu

Właściwości

Wartość properties to mapa nazwy właściwości => definicja typu.

W poniższym przykładzie akceptowana {"foo": "string", "bar": 1}jest wartość , ale odrzuca {"foo": "string", "bar": -1}obiekt , {"foo": "", "bar": 1}lub dowolny obiekt bez foo właściwości lub bar .

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
},
"parameters": {
  "objectParameter": {
    "$ref": "#/definitions/objectDefinition",
  }
}

Wszystkie właściwości są wymagane, chyba że definicja typu właściwości ma wartość "nullable": ograniczenie true . Aby ustawić obie właściwości w poprzednim przykładzie jako opcjonalne, wyglądałoby to następująco:

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

Wartość additionalProperties jest definicją typu lub wartością logiczną. Jeśli nie additionalProperties zdefiniowano żadnego ograniczenia, wartość domyślna to true.

Jeśli wartość jest definicją typu, wartość opisuje schemat, który jest stosowany do wszystkich właściwości, które nie zostały wymienione w ograniczeniu properties . W poniższym przykładzie zostanie zaakceptowana{"fizz": "buzz", "foo": "bar"}, ale odrzucona .{"property": 1}

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

Jeśli wartość to false, nie można podać żadnych właściwości poza tymi zdefiniowanymi w ograniczeniu properties . W poniższym przykładzie zostanie zaakceptowana {"foo": "string", "bar": 1}wartość , ale zostanie odrzucona {"foo": "string", "bar": 1, "fizz": "buzz"}wartość .

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

Jeśli wartość to true, każda właściwość, która nie została zdefiniowana w ograniczeniu properties , akceptuje dowolną wartość. W poniższym przykładzie zostanie zaakceptowana opcja {"foo": "string", "bar": 1, "fizz": "buzz"}.

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

Rozróżniacza

Wartość discriminator określa schemat do zastosowania na podstawie właściwości dyskryminującej. W poniższym przykładzie zostanie zaakceptowana wartość {"type": "ints", "foo": 1, "bar": 2} lub {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, ale zostanie odrzucona {"type": "ints", "fizz": "buzz"}wartość .

"definitions": {
  "taggedUnionDefinition": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

Ograniczenia tablicy

prefixItems

Wartość prefixItems to tablica definicji typów. Każda definicja typu w wartości jest schematem używanym do sprawdzania poprawności elementu tablicy w tym samym indeksie. Poniższy przykład akceptuje, ale odrzuca [1, true][1, "string"] lub [1]:

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ]
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

elementy

Wartość items jest definicją typu lub wartością logiczną. Jeśli nie items zdefiniowano żadnego ograniczenia, wartość domyślna to true.

Jeśli wartość jest definicją typu, wartość opisuje schemat, który jest stosowany do wszystkich elementów tablicy, których indeks jest większy niż największy indeks prefixItems ograniczenia. W poniższym przykładzie zostanie zaakceptowana [1, true, 1] lub [1, true, 1, 1] odrzucona:[1, true, "foo"]

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" }
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

Możesz użyć polecenia items bez użycia polecenia prefixItems. W poniższym przykładzie zostanie zaakceptowana [1, 2] lub [1] odrzucona:["foo"]

"definitions": {
  "intArrayDefinition": {
    "type": "array",
    "items": { "type": "int" }
  }
},
"parameters": {
  "intArrayParameter": {
    "$ref": "#/definitions/intArrayDefinition"
  }
}

Jeśli wartość to false, zweryfikowana tablica musi mieć dokładnie taką samą długość, jak prefixItems ograniczenie. Poniższy przykład będzie akceptował [1, true]element , ale odrzucał [1, true, 1]elementy i [1, true, false, "foo", "bar"].

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": false
}

Jeśli wartość jest prawdziwa, elementy tablicy, których indeks jest większy niż największy indeks prefixItems ograniczenia akceptują dowolną wartość. Poniższe przykłady akceptują elementy [1, true]i [1, true, 1][1, true, false, "foo", "bar"].

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

ograniczenie dopuszczane do wartości null

Ograniczenie dopuszczające wartość null wskazuje, że wartość może być null lub pominięta. Zobacz właściwości , aby zapoznać się z przykładem.

Opis

Możesz dodać opis do definicji typu, aby ułatwić użytkownikom szablonu zrozumienie wartości, którą należy podać.

"definitions": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

Użyj definicji

Aby odwołać się do definicji typu, użyj następującej składni:

"$ref": "#/definitions/<definition-name>"

W poniższym przykładzie pokazano, jak odwołać się do definicji typu z parametrów i danych wyjściowych:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "languageVersion": "2.0",

  "definitions": {
    "naturalNumber": {
      "type": "int",
      "minValue": 1
    }
  },
  "parameters": {
    "numberParam": {
      "$ref": "#/definitions/naturalNumber",
      "defaultValue": 0
    }
  },
  "resources": {},
  "outputs": {
    "output1": {
      "$ref": "#/definitions/naturalNumber",
      "value": "[parameters('numberParam')]"
    }
  }
}

Następne kroki