Typdefinitioner i ARM-mallar

Artikel
09/03/2023

Den här artikeln beskriver hur du skapar och använder definitioner i din Azure Resource Manager-mall (ARM-mall). Genom att definiera dina egna typer kan du återanvända dessa typer. Typdefinitioner kan bara användas med languageVersion 2.0.

Anteckning

Den aktuella versionen av Azure Resource Manager Tools-tillägget för Visual Studio Code känner inte igen förbättringarna i languageVersion 2.0.

Tips

Vi rekommenderar Bicep eftersom det har samma funktioner som ARM-mallar och syntaxen är enklare att använda. Mer information finns i Användardefinierade datatyper i Bicep.

Minimal deklaration

Som minst behöver varje typdefinition ett namn och antingen ett type eller .$ref

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

Tillåtna värden

Du kan definiera tillåtna värden för en typdefinition. Du anger tillåtna värden i en matris. Distributionen misslyckas under valideringen om ett värde skickas in för typdefinitionen som inte är ett av de tillåtna värdena.

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

Längdbegränsningar

Du kan ange minsta och högsta längder för definitioner av sträng- och matristyper. Du kan ange en eller båda begränsningarna. För strängar anger längden antalet tecken. För matriser anger längden antalet objekt i matrisen.

I följande exempel deklareras två typdefinitioner. En typdefinition är för ett lagringskontonamn som måste innehålla 3–24 tecken. Den andra typdefinitionen är en matris som måste ha mellan 1 och 5 objekt.

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

Heltalsbegränsningar

Du kan ange lägsta och högsta värden för heltalstypdefinitioner. Du kan ange en eller båda begränsningarna.

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

Objektbegränsningar

Egenskaper

Värdet för properties är en mappning av egenskapsnamnet => typdefinitionen.

I följande exempel skulle acceptera {"foo": "string", "bar": 1}, men avvisa {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}eller något objekt utan en foo eller bar -egenskap.

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

Alla egenskaper krävs om inte egenskapens typdefinition har villkoret "nullable": true . Om du vill göra båda egenskaperna i föregående exempel valfria skulle det se ut så här:

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

additionalProperties

Värdet additionalProperties för är en typdefinition eller ett booleskt värde. Om ingen additionalProperties begränsning har definierats är truestandardvärdet .

Om värdet är en typdefinition beskriver värdet schemat som tillämpas på alla egenskaper som inte nämns i villkoret properties . I följande exempel skulle acceptera {"fizz": "buzz", "foo": "bar"} men avvisa {"property": 1}.

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

Om värdet är falsekan inga egenskaper utöver de som definierats i villkoret properties anges. I följande exempel skulle acceptera {"foo": "string", "bar": 1}, men avvisa {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Om värdet är trueaccepterar alla egenskaper som inte definierats i villkoret properties något värde. I följande exempel skulle acceptera {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

diskriminator

Värdet discriminator definierar vilket schema som ska tillämpas baserat på en diskriminerande egenskap. I följande exempel skulle acceptera antingen {"type": "ints", "foo": 1, "bar": 2} eller {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, men avvisa {"type": "ints", "fizz": "buzz"}.

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

Matrisbegränsningar

prefixItems

Värdet för prefixItems är en matris med typdefinitioner. Varje typdefinition i värdet är det schema som ska användas för att verifiera elementet i en matris vid samma index. Följande exempel skulle acceptera [1, true] men avvisa [1, "string"] eller [1]:

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

objekt

Värdet för items är en typdefinition eller ett booleskt värde. Om ingen items begränsning har definierats är truestandardvärdet .

Om värdet är en typdefinition beskriver värdet schemat som tillämpas på alla element i matrisen vars index är större än begränsningens prefixItems största index. I följande exempel skulle acceptera [1, true, 1] eller [1, true, 1, 1] men avvisa [1, true, "foo"]:

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

Du kan använda items utan att använda prefixItems. I följande exempel skulle acceptera [1, 2] eller [1] men avvisa ["foo"]:

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

Om värdet är falsemåste den verifierade matrisen ha exakt samma längd som villkoret prefixItems . I följande exempel skulle acceptera [1, true], men avvisa [1, true, 1], och [1, true, false, "foo", "bar"].

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

Om värdet är sant accepterar element i matrisen vars index är större än det största indexet för villkoret prefixItems något värde. I följande exempel skulle acceptera [1, true], [1, true, 1] och [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
}

villkor som kan ha värdet null

Villkoret som kan ha värdet null anger att värdet kan utelämnas null eller utelämnas. Ett exempel finns i Egenskaper .

Description

Du kan lägga till en beskrivning i en typdefinition som hjälper användare av mallen att förstå värdet som ska anges.

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

Använd definition

Om du vill referera till en typdefinition använder du följande syntax:

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

I följande exempel visas hur du refererar till en typdefinition från parametrar och utdata:

{
  "$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ästa steg

Mer information om tillgängliga egenskaper för typdefinitioner finns i Förstå strukturen och syntaxen för ARM-mallar.