Typdefinitionen in ARM-Vorlagen

  • Artikel

In diesem Artikel wird beschrieben, wie Sie Definitionen in Ihrer Azure Resource Manager-Vorlage (ARM-Vorlage) erstellen und verwenden. Indem Sie Ihre eigenen Typen definieren, können Sie diese Typen wiederverwenden. Typdefinitionen können nur mit languageVersion 2.0 verwendet werden.

Hinweis

In der aktuellen Version der Azure Resource Manager Tools-Erweiterung für Visual Studio Code werden die in languageVersion 2.0 vorgenommenen Verbesserungen nicht erkannt.

Tipp

Wir empfehlen Bicep, weil es dieselben Funktionen wie ARM-Vorlagen bietet und die Syntax einfacher zu verwenden ist. Weitere Informationen finden Sie unter Benutzerdefinierte Datentypen in Bicep.

Minimale Deklaration

Jede Typdefinition benötigt mindestens einen Namen und entweder einen type oder ein $ref.

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

Zulässige Werte

Sie können für eine Typdefinition zulässige Werte definieren. Diese werden in einem Array bereitgestellt. Wenn für die Typdefinition ein Wert übergeben wird, der nicht zu den zulässigen Werten gehört, schlägt die Bereitstellung während der Überprüfung fehl.

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

Längenbeschränkungen

Sie können die minimale und maximale Länge von Zeichenfolgen- und ArrayTypdefinitionen angeben. Sie können eine oder beide Einschränkungen festlegen. Bei Zeichenfolgen gibt die Länge die Anzahl der Zeichen an. Bei Arrays gibt die Länge die Anzahl der Elemente im Array an.

Im folgenden Beispiel werden zwei Typdefinitionen deklariert. Eine Typdefinition ist für den Namen eines Speicherkontos, der 3–24 Zeichen enthalten muss. Die andere Typdefinition ist ein Array, das 1–5 Elemente aufweisen muss.

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

Ganzzahlige Einschränkungen

Sie können die minimalen und maximalen Werte für ganzzahlige Typdefinitionen festlegen. Sie können eine oder beide Einschränkungen festlegen.

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

Objekteinschränkungen

Eigenschaften

Der Wert von properties ist eine Zuordnung von Eigenschaftsname = > Typdefinition.

Das folgende Beispiel würde {"foo": "string", "bar": 1} akzeptieren, aber {"foo": "string", "bar": -1}, {"foo": "", "bar": 1} oder ein beliebiges Objekt ohne eine foo- oder bar-Eigenschaft ablehnen.

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

Alle Eigenschaften sind erforderlich, es sei denn, die Typdefinition der Eigenschaft hat die Einschränkung "nullable": true. Wenn Sie beide Eigenschaften im vorangegangenen Beispiel optional machen, würde es so aussehen:

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

additionalProperties

Der Wert von additionalProperties ist eine Typdefinition oder ein boolescher Wert. Wenn keine additionalProperties-Einschränkung definiert ist, ist true der Standardwert.

Wenn der Wert eine Typdefinition ist, beschreibt der Wert das Schema, das auf alle Eigenschaften angewendet wird, die nicht in der properties-Einschränkung erwähnt werden. Das folgende Beispiel würde {"fizz": "buzz", "foo": "bar"} akzeptieren, {"property": 1} jedoch ablehnen.

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

Wenn der Wert false ist, können keine Eigenschaften angegeben werden, die über die in der properties-Einschränkung definierten hinausgehen. Das folgende Beispiel würde {"foo": "string", "bar": 1} akzeptieren, {"foo": "string", "bar": 1, "fizz": "buzz"} jedoch ablehnen.

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

Wenn der Wert true ist, akzeptiert jede Eigenschaft, die nicht in der properties-Einschränkung definiert ist, jeden Wert. Das folgende Beispiel würde {"foo": "string", "bar": 1, "fizz": "buzz"} akzeptieren.

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

discriminator

Der Wert discriminator definiert, welches Schema basierend auf einer Diskriminatoreigenschaft angewendet werden soll. Das folgende Beispiel würde entweder {"type": "ints", "foo": 1, "bar": 2} oder {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"} akzeptieren, {"type": "ints", "fizz": "buzz"} jedoch ablehnen.

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

Einschränkungen für Arrays

prefixItems

Der Wert von prefixItems ist ein Array von Typdefinitionen. Jede Typdefinition im Wert ist das Schema, das zum Überprüfen des Elements eines Arrays am selben Index verwendet werden soll. Das folgende Beispiel würde [1, true] akzeptieren, [1, "string"] oder [1] jedoch ablehnen:

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

items

Der Wert von items ist eine Typdefinition oder ein boolescher Wert. Wenn keine items-Einschränkung definiert ist, ist true der Standardwert.

Wenn der Wert eine Typdefinition ist, beschreibt der Wert das Schema, das auf alle Elemente des Arrays angewendet wird, deren Index größer als der größte Index der prefixItems-Einschränkung ist. Das folgende Beispiel würde [1, true, 1] oder [1, true, 1, 1] akzeptieren, [1, true, "foo"] jedoch ablehnen:

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

Sie können items verwenden, ohne prefixItems zu verwenden. Das folgende Beispiel würde [1, 2] oder [1] akzeptieren, ["foo"] jedoch ablehnen:

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

Wenn der Wert false ist, muss das überprüfte Array genau die gleiche Länge wie die prefixItems-Einschränkung aufweisen. Das folgende Beispiel würde [1, true] akzeptieren, [1, true, 1] und [1, true, false, "foo", "bar"] jedoch ablehnen.

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

Wenn der Wert true ist, akzeptieren Elemente des Arrays, dessen Index größer als der größte Index der prefixItems-Einschränkung ist, jeden Wert. Die folgenden Beispiele würden [1, true], [1, true, 1] und [1, true, false, "foo", "bar"] akzeptieren.

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

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

Nullable-Einschränkung

Die Nullable-Einschränkung gibt an, dass der Wert null sein oder ausgelassen werden kann. Ein Beispiel finden Sie unter Eigenschaften.

BESCHREIBUNG

Sie können einer Typdefinition eine Beschreibung hinzufügen, damit Benutzer Ihrer Vorlage leichter nachvollziehen können, welcher Wert bereitgestellt werden soll.

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

Verwenden der Definition

Verwenden Sie die folgende Syntax, um auf eine Typdefinition zu verweisen:

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

Im folgenden Beispiel wird gezeigt, wie aus Parametern und Ausgaben auf eine Typdefinition verwiesen wird:

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

Nächste Schritte