Typedefinities in ARM-sjablonen

Artikel
09/03/2023

In dit artikel wordt beschreven hoe u definities maakt en gebruikt in uw Azure Resource Manager-sjabloon (ARM-sjabloon). Door uw eigen typen te definiëren, kunt u deze typen opnieuw gebruiken. Typedefinities kunnen alleen worden gebruikt met languageVersion 2.0.

Notitie

De huidige versie van de Azure Resource Manager Tools-extensie voor Visual Studio Code herkent de verbeteringen in languageVersion 2.0 niet.

Tip

We raden Bicep aan omdat het dezelfde mogelijkheden biedt als ARM-sjablonen en de syntaxis eenvoudiger te gebruiken is. Zie Door de gebruiker gedefinieerde gegevenstypen in Bicep voor meer informatie.

Minimale declaratie

Elke typedefinitie heeft minimaal een naam nodig en een type of een $ref.

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

Toegestane waarden

U kunt toegestane waarden voor een typedefinitie definiëren. U geeft de toegestane waarden op in een matrix. De implementatie mislukt tijdens de validatie als er een waarde wordt doorgegeven voor de typedefinitie die niet een van de toegestane waarden is.

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

Lengtebeperkingen

U kunt minimum- en maximumlengten opgeven voor tekenreeks- en matrixtypedefinities. U kunt een of beide beperkingen instellen. Voor tekenreeksen geeft de lengte het aantal tekens aan. Voor matrices geeft de lengte het aantal items in de matrix aan.

In het volgende voorbeeld worden twee typedefinities declareren. Eén typedefinitie is voor een opslagaccountnaam die 3-24 tekens moet bevatten. De andere typedefinitie is een matrix die uit 1-5 items moet bestaan.

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

Beperkingen voor gehele getallen

U kunt minimum- en maximumwaarden instellen voor definities van het type geheel getal. U kunt een of beide beperkingen instellen.

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

Objectbeperkingen

Eigenschappen

De waarde van properties is een toewijzing van eigenschapsnaam => typedefinitie.

In het volgende voorbeeld wordt geaccepteerd {"foo": "string", "bar": 1}, maar geweigerd {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}, of een object zonder de foo eigenschap of bar .

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

Alle eigenschappen zijn vereist, tenzij de typedefinitie van de eigenschap de 'nullable' heeft: true constraint. Als u beide eigenschappen in het voorgaande voorbeeld optioneel wilt maken, ziet dit er als volgt uit:

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

additionalProperties

De waarde van additionalProperties is een typedefinitie of een booleaanse waarde. Als er geen additionalProperties beperking is gedefinieerd, is truede standaardwaarde .

Als waarde een typedefinitie is, wordt met de waarde het schema beschreven dat wordt toegepast op alle eigenschappen die niet in de properties beperking worden vermeld. In het volgende voorbeeld wordt geaccepteerd {"fizz": "buzz", "foo": "bar"} , maar geweigerd {"property": 1}.

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

Als de waarde is false, kunnen er geen eigenschappen worden opgegeven die verder gaan dan de eigenschappen die zijn gedefinieerd in de properties beperking. In het volgende voorbeeld wordt geaccepteerd {"foo": "string", "bar": 1}, maar geweigerd {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Als de waarde is true, accepteert elke eigenschap die niet is gedefinieerd in de properties beperking elke waarde. In het volgende voorbeeld wordt geaccepteerd {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Discriminator

De waarde discriminator definieert welk schema moet worden toegepast op basis van een discriminator-eigenschap. In het volgende voorbeeld wordt of {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}geaccepteerd{"type": "ints", "foo": 1, "bar": 2}, maar wordt geweigerd{"type": "ints", "fizz": "buzz"}.

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

Matrixbeperkingen

prefixItems

De waarde van prefixItems is een matrix van typedefinities. Elke typedefinitie in de waarde is het schema dat moet worden gebruikt om het element van een matrix in dezelfde index te valideren. In het volgende voorbeeld wordt geaccepteerd [1, true] , maar geweigerd [1, "string"] of [1]:

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

items

De waarde van items is een typedefinitie of een booleaanse waarde. Als er geen items beperking is gedefinieerd, is truede standaardwaarde .

Als waarde een typedefinitie is, beschrijft de waarde het schema dat wordt toegepast op alle elementen van de matrix waarvan de index groter is dan de grootste index van de prefixItems beperking. In het volgende voorbeeld wordt geaccepteerd [1, true, 1] of [1, true, 1, 1] maar geweigerd [1, true, "foo"]:

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

U kunt gebruiken items zonder gebruik te maken van prefixItems. In het volgende voorbeeld wordt geaccepteerd [1, 2] of [1] maar geweigerd ["foo"]:

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

Als de waarde is false, moet de gevalideerde matrix exact dezelfde lengte hebben als de prefixItems beperking. In het volgende voorbeeld wordt geaccepteerd [1, true], maar geweigerd [1, true, 1], en [1, true, false, "foo", "bar"].

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

Als de waarde waar is, accepteren elementen van de matrix waarvan de index groter is dan de grootste index van de prefixItems beperking elke waarde. In de volgende voorbeelden worden , [1, true, 1] en [1, true, false, "foo", "bar"]geaccepteerd[1, true].

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

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

beperking met null-waarde

De beperking waarvoor null kan worden ingesteld, geeft aan dat de waarde kan zijn null of weggelaten. Zie Eigenschappen voor een voorbeeld.

Description

U kunt een beschrijving toevoegen aan een typedefinitie om gebruikers van uw sjabloon inzicht te geven in de waarde die moet worden opgegeven.

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

Definitie gebruiken

Gebruik de volgende syntaxis om te verwijzen naar een typedefinitie:

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

In het volgende voorbeeld ziet u hoe u naar een typedefinitie verwijst vanuit parameters en uitvoer:

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

Volgende stappen

Zie Inzicht in de structuur en syntaxis van ARM-sjablonen voor meer informatie over de beschikbare eigenschappen voor typedefinities.