Informazioni sulla struttura e sulla sintassi dei modelli di Resource Manager

Questo articolo descrive la struttura di un modello di Azure Resource Manager (modello di ARM). Presenta le diverse sezioni di un modello e le proprietà disponibili in queste sezioni.

Questo articolo è destinato agli utenti che hanno familiarità con i modelli di ARM. Fornisce informazioni dettagliate sulla struttura del modello. Per un'esercitazione dettagliata che illustra il processo di creazione di un modello, vedi Esercitazione: Creare e distribuire il primo modello di ARM. Per informazioni sui modelli di ARM tramite un set guidato di moduli in Microsoft Learn, vedi Distribuire e gestire le risorse in Azure usando i modelli di ARM.

Formato del modello

La struttura più semplice di un modello è costituita dagli elementi seguenti:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "",
  "contentVersion": "",
  "apiProfile": "",
  "definitions": { },
  "parameters": { },
  "variables": { },
  "functions": [ ],
  "resources": [ ], /* or "resources": { } with languageVersion 2.0 */
  "outputs": { }
}

Ogni elemento ha proprietà che è possibile impostare. In questo articolo le sezioni del modello vengono esaminate in modo dettagliato.

Definizioni

definitions Nella sezione del modello specifica gli schemi usati per convalidare i valori di matrice e oggetto. Definitions può essere usato solo con languageVersion 2.0.

"definitions": {
  "<definition-name": {
    "type": "<data-type-of-definition>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the-type-definition>"
    }
  }
}

Per esempi di come usare le definizioni dei tipi, vedi Definizioni dei tipi nei modelli di ARM.

In Bicep, vedi Tipi di dati definiti dall'utente.

Parametri

Nella sezione parameters del modello puoi specificare i valori che è possibile immettere durante la distribuzione delle risorse. È previsto un limite di 256 parametri in un modello. È possibile ridurre il numero dei parametri usando oggetti che contengono più proprietà.

Le proprietà disponibili per un parametro sono:

"parameters": {
  "<parameter-name>" : {
    "type" : "<type-of-parameter-value>",
    "defaultValue": "<default-value-of-parameter>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}

Per esempi di come usare i parametri, vedi Parametri nei modelli di ARM.

In Bicep vedi parametri.

Variabili

Nella sezione variables puoi costruire valori da usare in tutto il modello. Non è obbligatorio definire le variabili. Queste tuttavia consentono spesso di semplificare il modello, riducendo le espressioni complesse. Il formato di ogni variabile corrisponde a uno dei tipi di dati. È previsto un limite di 256 parametri in un modello.

L'esempio seguente mostra le opzioni disponibili per definire una variabile:

"variables": {
  "<variable-name>": "<variable-value>",
  "<variable-name>": {
    <variable-complex-type-value>
  },
  "<variable-object-name>": {
    "copy": [
      {
        "name": "<name-of-array-property>",
        "count": <number-of-iterations>,
        "input": <object-or-value-to-repeat>
      }
    ]
  },
  "copy": [
    {
      "name": "<variable-array-name>",
      "count": <number-of-iterations>,
      "input": <object-or-value-to-repeat>
    }
  ]
}

Per informazioni sull'uso di copy per creare diversi valori per una variabile, vedi Iterazione variabili.

Per esempi di come usare le variabili, vedi Variabili nel modello di ARM.

In Bicep vedi variabili.

Funzioni

Nel modello è possibile creare funzioni personalizzate. Tali funzioni sono disponibili per usare il modello. Si definiscono in genere espressioni complesse che non vuoi ripetere in tutto il modello. Le funzioni definite dall'utente vengono create da espressioni e funzioni supportate nei modelli.

Quando si crea una funzione definita dall'utente, è necessario tenere presente alcune restrizioni:

• La funzione non può accedere alle variabili.
• La funzione può usare solo i parametri definiti in essa. Quando si usa la funzione parametri in una funzione definita dall'utente, è possibile usare solo i parametri per quella funzione.
• La funzione non può chiamare altre funzioni definite dall'utente.
• La funzione non può usare la funzione di riferimento.
• I parametri della funzione non possono avere valori predefiniti.

"functions": [
  {
    "namespace": "<namespace-for-functions>",
    "members": {
      "<function-name>": {
        "parameters": [
          {
            "name": "<parameter-name>",
            "type": "<type-of-parameter-value>"
          }
        ],
        "output": {
          "type": "<type-of-output-value>",
          "value": "<function-return-value>"
        }
      }
    }
  }
],

Per esempi di come usare funzioni personalizzate, vedi Funzioni definite dall'utente nel modello di ARM.

In Bicep le funzioni definite dall'utente non sono supportate. Bicep supporta varie funzioni e operatori.

Risorse

Nella sezione resources puoi definire le risorse distribuite o aggiornate. È previsto un limite di 800 risorse per modello.

Le risorse vengono definite con la struttura seguente:

"resources": [
  {
    "condition": "<true-to-deploy-this-resource>",
    "type": "<resource-provider-namespace/resource-type-name>",
    "apiVersion": "<api-version-of-resource>",
    "name": "<name-of-the-resource>",
    "comments": "<your-reference-notes>",
    "location": "<location-of-resource>",
    "dependsOn": [
        "<array-of-related-resource-names>"
    ],
    "tags": {
        "<tag-name1>": "<tag-value1>",
        "<tag-name2>": "<tag-value2>"
    },
    "identity": {
      "type": "<system-assigned-or-user-assigned-identity>",
      "userAssignedIdentities": {
        "<resource-id-of-identity>": {}
      }
    },
    "sku": {
        "name": "<sku-name>",
        "tier": "<sku-tier>",
        "size": "<sku-size>",
        "family": "<sku-family>",
        "capacity": <sku-capacity>
    },
    "kind": "<type-of-resource>",
    "scope": "<target-scope-for-extension-resources>",
    "copy": {
        "name": "<name-of-copy-loop>",
        "count": <number-of-iterations>,
        "mode": "<serial-or-parallel>",
        "batchSize": <number-to-deploy-serially>
    },
    "plan": {
        "name": "<plan-name>",
        "promotionCode": "<plan-promotion-code>",
        "publisher": "<plan-publisher>",
        "product": "<plan-product>",
        "version": "<plan-version>"
    },
    "properties": {
        "<settings-for-the-resource>",
        "copy": [
            {
                "name": ,
                "count": ,
                "input": {}
            }
        ]
    },
    "resources": [
        "<array-of-child-resources>"
    ]
  }
]

Per supportare il nome simbolico Bicep nei modelli di ARM JSON, aggiungi languageVersion con la versione 2.0 o più recente e modifica la definizione delle risorse da una matrice a un oggetto.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Per altre informazioni, vedere Risorse.

In Bicep, vedi risorse.

Output

Nella sezione outputs , puoi specificare i valori restituiti dalla distribuzione. In genere, restituisci i valori dalle risorse che sono state distribuite. È previsto un limite di 64 output in un modello.

L'esempio seguente illustra la struttura di una definizione di output:

"outputs": {
  "<output-name>": {
    "condition": "<boolean-value-whether-to-output-value>",
    "type": "<type-of-output-value>",
    "value": "<output-value-expression>",
    "copy": {
      "count": <number-of-iterations>,
      "input": <values-for-the-variable>
    }
  }
}

Per esempi di come usare gli output, vedi Output nel modello di ARM.

In Bicep, vedi output.

Commenti e metadati

Sono disponibili diverse opzioni per aggiungere commenti e metadati al modello.

Commenti

Per i commenti inline, puoi usare // o /* ... */. In Visual Studio Code, salva i file di parametri con commenti come il JSON con commenti tipo di file (JSONC), in caso contrario viene visualizzato un messaggio di errore che indica che "Commenti non consentiti in JSON".

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

In Visual Studio Code, l'estensione Strumenti di Azure Resource Manager può rilevare automaticamente un modello di ARM e modificare la modalità del linguaggio. Se vedi Modello di Azure Resource Manager nell'angolo inferiore destro di Visual Studio Code, puoi usare i commenti inline. In questo modo i commenti inline non verranno più contrassegnati come non validi.

In Bicep, vedi commenti.

Metadati UFX

È possibile aggiungere un oggetto metadata praticamente ovunque nel modello. Resource Manager ignora l'oggetto, ma l'editor JSON potrebbe segnalare che la proprietà non è valida. Nell'oggetto definire le proprietà necessarie.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "comments": "This template was developed for demonstration purposes.",
    "author": "Example Name"
  },

Per parameters, aggiungi un oggetto metadata con una proprietà description .

"parameters": {
  "adminUsername": {
    "type": "string",
    "metadata": {
      "description": "User name for the Virtual Machine."
    }
  },

Durante la distribuzione del modello tramite il portale, il testo specificato nella descrizione viene usato automaticamente come suggerimento per tale parametro.

Per resources, aggiungi un elemento comments o un oggetto metadata . L'esempio seguente mostra sia un elemento comments che un oggetto metadata .

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2022-09-01",
    "name": "[format('{0}{1}', 'storage', uniqueString(resourceGroup().id))]",
    "comments": "Storage account used to store VM disks",
    "location": "[parameters('location')]",
    "metadata": {
      "comments": "These tags are needed for policy compliance."
    },
    "tags": {
      "Dept": "[parameters('deptName')]",
      "Environment": "[parameters('environment')]"
    },
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "properties": {}
  }
]

Per outputs, aggiungi un oggetto metadata al valore di output.

"outputs": {
  "hostname": {
    "type": "string",
    "value": "[reference(variables('publicIPAddressName')).dnsSettings.fqdn]",
    "metadata": {
      "comments": "Return the fully qualified domain name"
    }
  },

Non puoi aggiungere un oggetto metadata alle funzioni definite dall'utente.

Stringhe multilinea

Puoi suddividere una stringa in più linee. Ad esempio, vedi la proprietà location e uno dei commenti nell'esempio JSON seguente.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

In Bicep, vedi stringhe multilinea.

languageVersion 2.0

Per usare languageVersion 2.0, aggiungi "languageVersion": "2.0" al tuo modello:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Miglioramenti e modifiche introdotti in languageVersion 2.0:

• Usa il nome simbolico nel modello JSON di ARM. Per ulteriori informazioni, vedi Usare nome simbolico.
• Usa il nome simbolico nei cicli di copia delle risorse. Vedi Usare il nome simbolico.
• Usa il nome simbolico nelle matrici dependsOn . Vedi DependsOn e In base alle risorse di un ciclo.
• Usa il nome simbolico anziché il nome della risorsa nella funzione reference . Vedi le informazioni di riferimento.
• Una funzione riferimenti() che restituisce una matrice di oggetti che rappresentano gli stati di runtime di una raccolta di risorse. Vedi riferimenti.
• Usa la proprietà della risorsa "esistente" per dichiarare le risorse esistenti per ARM da leggere anziché distribuire una risorsa. Vedi Dichiarare le risorse esistenti.
• Crea tipi definiti dall'utente. Vedi Definizione del tipo.
• Vincoli di convalida dei tipi aggregati aggiuntivi da usare nei parametri e negli output.
• Il valore predefinito per la proprietàexpressionEvaluationOptions è inner. Il valore outer è bloccato. Vedi Ambito di valutazione delle espressioni nei modelli annidati.
• La funzione deployment restituisce un subset limitato di proprietà. Vedi Deployment (Distribuzione).
• Se la risorsa Distribuzioni viene usata in una distribuzione con nome simbolico, usa apiVersion 2020-09-01 o versione successiva.
• Nella definizione della risorsa non sono più necessari valori di doppio escape all'interno di un'espressione. Vedi Caratteri di escape.

L'uso di una delle funzionalità Bicep seguenti abilita automaticamente la generazione del codice della versione 2.0 del linguaggio:

• tipi definiti dall'utente
• funzioni definite dall'utente
• importazioni in fase di compilazione
• funzionalità sperimentali

Passaggi successivi

• Per visualizzare modelli completi per molti tipi diversi di soluzioni, vedere Modelli di avvio rapido di Azure.
• Per informazioni dettagliate sulle funzioni che è possibile usare in un modello, vedi Funzioni del modello di ARM.
• Per unire più modelli durante la distribuzione, vedi Uso di modelli collegati e annidati durante la distribuzione delle risorse di Azure.
• Per consigli sulla creazione di modelli, vedi Procedure consigliate per i modelli di ARM.
• Per le risposte alle domande frequenti, vedi Domande frequenti sui modelli di ARM.