Definizioni dei tipi nei modelli di Resource Manager

Articolo
09/26/2024

Questo articolo descrive come creare e usare le definizioni in un modello di Azure Resource Manager (modello di ARM). Definendo i propri tipi, è possibile riutilizzarli. Le definizioni dei tipi possono essere usate solo con languageVersion 2.0.

Nota

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 Bicep perché offre le stesse funzionalità dei modelli di ARM e la sintassi è più semplice 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 una matrice. La distribuzione non riesce durante la convalida se viene passato un valore per la definizione del tipo che non rientra tra i 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 nella matrice.

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 Integer

È 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 del nome della proprietà => 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 obbligatorie, 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
      }
    }
  }
}

additionalProperties

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
  }
}

discriminator

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

prefixItems

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"
  }
}

articoli

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"
  }
}

Usare 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 modelli di Resource Manager.

Condividi tramite