Definizioni dei tipi nei modelli ARM

2025-04-30

Questo articolo descrive come creare e usare le definizioni nel modello di Azure Resource Manager .This article describe how to create and use definitions in your Azure Resource Manager template (ARM template). Definendo i propri tipi, è possibile riutilizzare questi tipi. Le definizioni dei tipi possono essere usate solo con languageVersion 2.0.

Annotazioni

La versione corrente dell'estensione Strumenti di Azure Resource Manager per Visual Studio Code non riconosce i miglioramenti apportati in languageVersion 2.0.

Suggerimento

È consigliabile usare Bicep perché offre le stesse funzionalità dei modelli arm e la sintassi è più facile da usare. Per altre informazioni, vedere Tipi di dati definiti dall'utente in Bicep.

Dichiarazione minima

Come minimo, ogni definizione di tipo richiede un nome e un type o un $ref.

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

Valori consentiti

È possibile definire i valori consentiti per una definizione di tipo. È possibile specificare i valori consentiti in un array. La distribuzione non riesce durante la convalida se viene passato un valore per la definizione del tipo che non è uno dei valori consentiti.

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

Vincoli di lunghezza

È possibile specificare lunghezze minime e massime per le definizioni di tipo stringa e matrice. È possibile impostare uno o entrambi i vincoli. Per le stringhe, la lunghezza indica il numero di caratteri. Per le matrici, la lunghezza indica il numero di elementi nell'array.

Nell'esempio seguente vengono dichiarate due definizioni di tipo. Una definizione di tipo è per un nome di account di archiviazione che deve avere 3-24 caratteri. L'altra definizione di tipo è una matrice che deve avere da 1 a 5 elementi.

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

Vincoli sui numeri interi

È possibile impostare valori minimi e massimi per le definizioni dei tipi integer. È possibile impostare uno o entrambi i vincoli.

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

Vincoli oggetto

Proprietà

Il valore di properties è una mappa in cui il nome della proprietà è associato alla definizione del tipo >.

Nell'esempio seguente viene accettato {"foo": "string", "bar": 1}, ma viene rifiutato {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}o qualsiasi oggetto senza una proprietà foo o bar.

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

Tutte le proprietà sono necessarie a meno che la definizione del tipo della proprietà non abbia il vincolo "nullable": true . Per rendere facoltative entrambe le proprietà nell'esempio precedente, l'aspetto sarà simile al seguente:

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

proprietà aggiuntive

Il valore di additionalProperties è una definizione di tipo o un valore booleano. Se non viene definito alcun vincolo additionalProperties, il valore predefinito è true.

Se il valore è una definizione di tipo, descrive lo schema applicato a tutte le proprietà non indicate nel vincolo properties. L'esempio seguente accetta {"fizz": "buzz", "foo": "bar"} ma rifiuta {"property": 1}.

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

Se il valore è false, non è possibile fornire alcuna proprietà oltre a quelle definite nel vincolo properties. L'esempio seguente accetta {"foo": "string", "bar": 1} ma rifiuta {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Se il valore è true, qualsiasi proprietà non definita nel vincolo properties accetta qualsiasi valore. L'esempio seguente accetta {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

discriminatore

Il valore discriminator definisce lo schema da applicare in base a una proprietà di discriminator. L'esempio seguente accetta {"type": "ints", "foo": 1, "bar": 2} o {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, ma rifiuta {"type": "ints", "fizz": "buzz"}.

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

Vincoli di matrice

elementi prefissi

Il valore di prefixItems è una matrice di definizioni di tipo. Ogni definizione di tipo nel valore è lo schema da usare per convalidare l'elemento di una matrice nello stesso indice. L'esempio seguente accetta [1, true] ma rifiuta [1, "string"] o [1]:

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

Elementi

Il valore di items è una definizione di tipo o un valore booleano. Se non viene definito alcun vincolo items, il valore predefinito è true.

Se il valore è una definizione di tipo, descrive lo schema applicato a tutti gli elementi della matrice il cui indice è maggiore dell'indice più grande del vincolo prefixItems. L'esempio seguente accetta [1, true, 1] o [1, true, 1, 1] ma rifiuta [1, true, "foo"]:

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

È possibile usare items senza usare prefixItems. L'esempio seguente accetta [1, 2] o [1] ma rifiuta ["foo"]:

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

Se il valore è false, la matrice convalidata deve avere la stessa lunghezza del vincolo prefixItems. L'esempio seguente accetta [1, true], ma rifiuta [1, true, 1] e [1, true, false, "foo", "bar"].

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

Se il valore è true, gli elementi della matrice il cui indice è maggiore dell'indice più grande del vincolo prefixItems accettano qualsiasi valore. Gli esempi seguenti accettano [1, true], [1, true, 1] e [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
}

Vincolo nullable

Il vincolo nullable indica che il valore può essere null o omesso. Per un esempio, vedere Proprietà.

Descrizione

È possibile aggiungere una descrizione a una definizione di tipo per aiutare gli utenti del modello a comprendere il valore da fornire.

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

Usa la definizione

Per fare riferimento a una definizione di tipo, usare la sintassi seguente:

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

Nell'esempio seguente viene illustrato come fare riferimento a una definizione di tipo da parametri e output:

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

Passaggi successivi

Per informazioni sulle proprietà disponibili per le definizioni dei tipi, vedere Comprendere la struttura e la sintassi dei template ARM di Azure Resource Manager.