Comprendere la struttura e la sintassi dei modelli di Resource Manager

Questo articolo descrive la struttura di un modello di Azure Resource Manager (modello 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 Resource Manager. Fornisce informazioni dettagliate sulla struttura del modello. Per un'esercitazione dettagliata che illustra il processo di creazione di un modello, vedere Esercitazione: Creare e distribuire il primo modello di Resource Manager. Per informazioni sui modelli di Resource Manager tramite un set guidato di moduli Learn, vedere Distribuire e gestire le risorse in Azure usando i modelli di Resource Manager.

Suggerimento

Bicep è un nuovo linguaggio che offre le stesse funzionalità dei modelli arm, ma con una sintassi più semplice da usare. Se si considera l'infrastruttura come opzioni di codice, è consigliabile esaminare Bicep.

Per informazioni sugli elementi di un file Bicep, vedere Comprendere la struttura e la sintassi dei file Bicep.

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#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}

Nome dell'elemento	Obbligatoria	Descrizione
$schema	Sì	Percorso del file dello schema JSON (JavaScript Object Notation) che descrive la versione del linguaggio del modello. Il numero di versione usato dipende dall'ambito della distribuzione e dall'editor JSON. Se si usa Visual Studio Code con l'estensione azure Resource Manager tools, usare la versione più recente per le distribuzioni di gruppi di risorse: https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json# Altri editor (incluso Visual Studio) potrebbero non essere in grado di elaborare questo schema. Per tali editor, usare: https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json# Per le distribuzioni della sottoscrizione, usare: https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json# Per le distribuzioni di gruppi di gestione, usare: https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json# Per le distribuzioni tenant, usare: https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#
contentVersion	Sì	Versione del modello (ad esempio 1.0.0.0). Questo elemento accetta tutti i valori. Usare questo valore per documentare le modifiche significative al modello. Quando si distribuiscono risorse tramite il modello, è possibile usare questo valore per assicurarsi che venga usato il modello corretto.
apiProfile	No	Una versione dell'API che funge da raccolta di versioni delle API per i tipi di risorse. Usare questo valore per evitare di dover specificare le versioni delle API per ogni risorsa nel modello. Quando si specifica una versione del profilo API e non si specifica una versione dell'API per il tipo di risorsa, Resource Manager usa la versione dell'API per il tipo di risorsa definito nel profilo. La proprietà del profilo API è particolarmente utile quando si distribuisce un modello in ambienti diversi, ad esempio Azure Stack e Azure globale. Usare la versione del profilo API per assicurarsi che il modello usi automaticamente le versioni supportate in entrambi gli ambienti. Per un elenco delle versioni correnti del profilo API e delle versioni delle API delle risorse definite nel profilo, vedere Profilo API. Per altre informazioni, vedere Tenere traccia delle versioni usando i profili API.
parameters	No	Valori forniti durante la distribuzione per personalizzare la distribuzione di risorse.
variables	No	Valori usati come frammenti JSON nel modello per semplificare le espressioni di linguaggio del modello.
functions	No	Funzioni definite dall'utente disponibili nel modello.
resources	Sì	Tipi di risorse che vengono distribuite o aggiornate in un gruppo di risorse o sottoscrizione.
outputs	No	Valori restituiti dopo la distribuzione.

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

Parametri

parameters Nella sezione del modello specificare i valori che è possibile immettere durante la distribuzione delle risorse. Sono limitati a 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-parameters>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}

Nome dell'elemento	Obbligatoria	Descrizione
parameter-name	Sì	Nome del parametro. Deve essere un identificatore JavaScript valido.
tipo	Sì	Tipo di valore del parametro. I tipi e i valori consentiti sono string, securestring, int, bool, object, secureObject e array. Vedere Tipi di dati nei modelli di Resource Manager.
defaultValue	No	Valore predefinito per il parametro, se non viene fornito alcun valore per il parametro.
allowedValues	No	Matrice di valori consentiti per il parametro per assicurare che venga fornito il valore corretto.
minValue	No	Il valore minimo per i parametri di tipo int, questo valore è inclusivo.
maxValue	No	Il valore massimo per i parametri di tipo int, questo valore è inclusivo.
minLength	No	Lunghezza minima per i parametri di tipo string, secureString e array. Questo valore è inclusivo.
maxLength	No	Lunghezza massima per i parametri di tipo string, secureString e array. Questo valore è inclusivo.
description	No	Descrizione del parametro visualizzato agli utenti nel portale. Per altre informazioni, consultare la sezione Comments in templates (Commenti nel modello).

Per esempi di come usare i parametri, vedere Parametri nei modelli di Resource Manager.

In Bicep vedere i parametri.

Variabili

variables Nella sezione si costruiscono valori che possono essere usati 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. Sono limitate a 256 variabili in un modello.

L'esempio seguente mostra le opzioni disponibili per la definizione di 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 copy di per creare diversi valori per una variabile, vedere Iterazione variabile.

Per esempi di come usare le variabili, vedere Variabili nel modello di Resource Manager.

In Bicep vedere le variabili.

Funzioni

Nel modello è possibile creare funzioni personalizzate. Tali funzioni sono disponibili per usare il modello. In genere, si definiscono espressioni complesse che non si desidera 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 parameters all'interno di una funzione definita dall'utente, si è limitati ai parametri per tale 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>"
        }
      }
    }
  }
],

Nome dell'elemento	Obbligatoria	Descrizione
namespace	Sì	Spazio dei nomi per le funzioni personalizzate. Usare per evitare conflitti di denominazione con le funzioni del modello.
function-name	Sì	Nome della funzione personalizzata. Quando si chiama la funzione, combinare il nome della funzione con lo spazio dei nomi . Ad esempio, per chiamare una funzione denominata uniqueName nello spazio dei nomi contoso, usare "[contoso.uniqueName()]".
parameter-name	No	Nome del parametro da usare all'interno della funzione personalizzata.
parameter-value	No	Tipo di valore del parametro. I tipi e i valori consentiti sono string, securestring, int, bool, object, secureObject e array.
tipo di output	Sì	Tipo del valore di output. I valori di output supportano gli stessi tipi dei parametri di input della funzione.
output-value	Sì	Espressione del linguaggio del modello valutata e restituita dalla funzione .

Per esempi di come usare funzioni personalizzate, vedere Funzioni definite dall'utente nel modello di Resource Manager.

In Bicep le funzioni definite dall'utente non sono supportate. Bicep supporta un'ampia gamma di funzioni e operatori.

Risorse

resources Nella sezione vengono definite le risorse distribuite o aggiornate. Sono limitate a 800 risorse in un 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>"
      ]
  }
]

Nome dell'elemento	Obbligatoria	Descrizione
condizione	No	Valore booleano che indica se verrà eseguito il provisioning della risorsa durante questa distribuzione. Se true, la risorsa viene creata durante la distribuzione. Se false, la risorsa viene ignorata per questa distribuzione. Vedere condizione.
tipo	Sì	Tipo di risorsa. Questo valore è una combinazione dello spazio dei nomi del provider di risorse e del tipo di risorsa ,ad esempio Microsoft.Storage/storageAccounts. Per determinare i valori disponibili, vedere informazioni di riferimento sul modello. Per una risorsa figlio, il formato del tipo dipende dal fatto che sia annidato all'interno della risorsa padre o definito all'esterno della risorsa padre. Vedere Impostare il nome e il tipo per le risorse figlio.
apiVersion	Sì	Versione dell'API REST da utilizzare per la creazione della risorsa. Quando si crea un nuovo modello, impostare questo valore sulla versione più recente della risorsa che si sta distribuendo. Se il modello funziona in base alle esigenze, continuare a usare la stessa versione dell'API. Continuando a usare la stessa versione dell'API, si riduce al minimo il rischio di una nuova versione dell'API che modifica il funzionamento del modello. È consigliabile aggiornare la versione dell'API solo quando si vuole usare una nuova funzionalità introdotta in una versione successiva. Per determinare i valori disponibili, vedere informazioni di riferimento sul modello.
name	Sì	Nome della risorsa. Il nome deve rispettare le restrizioni dei componenti URI definite dallo standard RFC3986. I servizi di Azure che espongono il nome della risorsa a parti esterne convalidano il nome per assicurarsi che non si tratti di un tentativo di spoofing di un'altra identità. Per una risorsa figlio, il formato del nome dipende dal fatto che sia annidato all'interno della risorsa padre o definito all'esterno della risorsa padre. Vedere Impostare il nome e il tipo per le risorse figlio.
comments	No	Le note per documentare le risorse nel modello. Per altre informazioni, consultare la sezione Comments in templates (Commenti nel modello).
posizione	Varia	Aree geografiche supportate della risorsa specificata. È possibile selezionare qualsiasi località disponibile, ma è in genere opportuno sceglierne una vicina agli utenti. Di solito è anche opportuno inserire le risorse che interagiscono tra loro nella stessa area. La maggior parte dei tipi di risorsa richiede una posizione, ma alcuni tipi (ad esempio un'assegnazione di ruolo) non la richiedono. Vedere Impostare la posizione delle risorse.
dependsOn	No	Risorse da distribuire prima della distribuzione di questa risorsa. Resource Manager valuta le dipendenze tra le risorse e le distribuisce nell'ordine corretto. Quando le risorse non sono interdipendenti, vengono distribuite in parallelo. Il valore può essere un elenco delimitato da virgole di nomi o identificatori univoci di risorse. Elencare solo le risorse distribuite in questo modello. Le risorse non definite in questo modello devono essere già esistenti. Evitare di aggiungere dipendenze non necessarie perché possono rallentare la distribuzione e creare dipendenze circolari. Per indicazioni sull'impostazione delle dipendenze, vedere Definire l'ordine di distribuzione delle risorse nei modelli di Resource Manager.
tags	No	Tag associati alla risorsa. Applicare i tag per organizzare in modo logico le risorse nella sottoscrizione.
identity	No	Alcune risorse supportano le identità gestite per le risorse di Azure. Tali risorse hanno un oggetto Identity a livello radice della dichiarazione di risorsa. È possibile impostare se l'identità è assegnata dall'utente o assegnata dal sistema. Per le identità assegnate dall'utente, specificare un elenco di ID risorsa per le identità. Impostare la chiave sull'ID risorsa e sul valore su un oggetto vuoto. Per altre informazioni, vedere Configurare le identità gestite per le risorse di Azure in una macchina virtuale di Azure usando i modelli.
sku	No	Alcune risorse consentono valori che definiscono lo SKU da distribuire. Ad esempio, è possibile specificare il tipo di ridondanza per un account di archiviazione.
kind	No	Alcune risorse consentono un valore che definisce il tipo di risorsa distribuito. Ad esempio, è possibile specificare il tipo di Cosmos DB da creare.
ambito	No	La proprietà scope è disponibile solo per i tipi di risorse di estensione. Usarlo quando si specifica un ambito diverso dall'ambito di distribuzione. Vedere Impostazione dell'ambito per le risorse di estensione nei modelli di Resource Manager.
copy	No	Numero di risorse da creare, se sono necessarie più istanze. La modalità predefinita è parallela. Specificare la modalità seriale quando si desidera che non tutte le risorse vengano distribuite contemporaneamente. Per altre informazioni, vedere Creare più istanze di risorse in Azure Resource Manager.
piano	No	Alcune risorse consentono valori che definiscono il piano da distribuire. Ad esempio, è possibile specificare l'immagine del marketplace per una macchina virtuale.
properties	No	Impostazioni di configurazione specifiche delle risorse. I valori per l'elemento properties corrispondono esattamente a quelli specificati nel corpo della richiesta per l'operazione API REST (metodo PUT) per creare la risorsa. È inoltre possibile specificare una matrice di copia per creare diverse istanze di una proprietà. Per determinare i valori disponibili, vedere informazioni di riferimento sul modello.
resources	No	Risorse figlio che dipendono dalla risorsa in via di definizione. Specificare solo tipi di risorsa consentiti dallo schema della risorsa padre. La dipendenza dalla risorsa padre non è implicita. È necessario definirla in modo esplicito. Vedere Impostare il nome e il tipo per le risorse figlio.

In Bicep vedere le risorse.

Output

outputs Nella sezione specificare i valori restituiti dalla distribuzione. In genere, si restituiscono valori dalle risorse distribuite. L'output di un modello è limitato a 64 .

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

Nome dell'elemento	Obbligatoria	Descrizione
output-name	Sì	Nome del valore di output. Deve essere un identificatore JavaScript valido.
condizione	No	Valore booleano che indica se questo valore di output viene restituito. Quando è true, il valore è incluso nell'output per la distribuzione. Quando è false, il valore dell'output viene ignorato per questa distribuzione. Quando non è specificato, il valore predefinito è true.
tipo	Sì	Tipo del valore di output. I valori di output supportano gli stessi tipi dei parametri di input del modello. Se si specifica securestring per il tipo di output, il valore non viene visualizzato nella cronologia di distribuzione e non può essere recuperato da un altro modello. Per usare un valore segreto in più modelli, archiviare il segreto in un Key Vault e fare riferimento al segreto nel file dei parametri. Per altre informazioni, vedere Usare Azure Key Vault per passare valori di parametro protetti durante la distribuzione.
Valore	No	Espressione del linguaggio di modello valutata e restituita come valore di output. Specificare il valore o la copia.
copy	No	Usato per restituire più di un valore per un output. Specificare il valore o la copia. Per altre informazioni, vedere Iterazione di output nei modelli di Resource Manager.

Per esempi di come usare gli output, vedere Output nel modello di Resource Manager.

In Bicep vedere output.

Commenti e metadati

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

Commenti

Per i commenti inline, è possibile usare // o /* ... */. In Visual Studio Code salvare i file di parametri con commenti come tipo di file JSON con commenti (JSONC ), altrimenti verrà visualizzato un messaggio di errore che indica che i commenti non sono consentiti in JSON.

Nota

Quando si usa l'interfaccia della riga di comando di Azure per distribuire modelli con commenti, usare la versione 2.3.0 o successiva e specificare l'opzione --handle-extended-json-format .

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-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 Azure Resource Manager Tools può rilevare automaticamente un modello di Resource Manager e modificare la modalità del linguaggio. Se viene visualizzato il modello di Azure Resource Manager nell'angolo inferiore destro di Visual Studio Code, è possibile usare i commenti inline. In questo modo i commenti inline non verranno più contrassegnati come non validi.

In Bicep vedere commenti.

Metadati

È 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, aggiungere un metadata oggetto con una description proprietà.

"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, aggiungere un elemento o un metadatacomments oggetto. Nell'esempio seguente viene illustrato sia un elemento che un commentsmetadata oggetto.

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2018-07-01",
    "name": "[concat('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, aggiungere un metadata oggetto al valore di output.

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

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

Stringhe a più righe

È possibile suddividere una stringa in più righe. Ad esempio, vedere la location proprietà e uno dei commenti nell'esempio JSON seguente.

Nota

Per distribuire modelli con stringhe a più righe, usare Azure PowerShell o l'interfaccia della riga di comando di Azure. Per l'interfaccia della riga di comando, usare la versione 2.3.0 o successiva e specificare l'opzione --handle-extended-json-format .

Le stringhe a più righe non sono supportate quando si distribuisce il modello tramite la portale di Azure, una pipeline DevOps o l'API REST.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-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 vedere stringhe a più righe.

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 dall'interno di un modello, vedere Funzioni modello arm.
• Per combinare diversi modelli durante la distribuzione, vedere Uso di modelli collegati e annidati durante la distribuzione delle risorse di Azure.
• Per suggerimenti sulla creazione di modelli, vedere Procedure consigliate per i modelli di Resource Manager.
• Per le risposte alle domande comuni, vedere Domande frequenti sui modelli di Resource Manager.