Comprendere la struttura e la sintassi dei modelli di Azure Resource ManagerUnderstand the structure and syntax of Azure Resource Manager Templates

Questo articolo descrive la struttura di un modello di Azure Resource Manager.This article describes the structure of an Azure Resource Manager template. Presenta le diverse sezioni di un modello e le proprietà disponibili in queste sezioni.It presents the different sections of a template and the properties that are available in those sections. Il modello è composto da JSON ed espressioni che è possibile usare per creare valori per la distribuzione.The template consists of JSON and expressions that you can use to construct values for your deployment. Per un'esercitazione dettagliata sulla creazione di un modello, vedere Creare il primo modello di Azure Resource Manager.For a step-by-step tutorial on creating a template, see Create your first Azure Resource Manager template.

Formato del modelloTemplate format

La struttura più semplice di un modello è costituita dagli elementi seguenti:In its simplest structure, a template has the following elements:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "",
    "parameters": {  },
    "variables": {  },
    "functions": {  },
    "resources": [  ],
    "outputs": {  }
}
Nome dell'elementoElement name ObbligatoriaRequired DESCRIZIONEDescription
$schema$schema Yes Percorso del file di schema JSON che descrive la versione del linguaggio del modello.Location of the JSON schema file that describes the version of the template language. Usare l'URL riportato nell'esempio precedente.Use the URL shown in the preceding example.
contentVersioncontentVersion Yes Versione del modello (ad esempio 1.0.0.0).Version of the template (such as 1.0.0.0). Questo elemento accetta tutti i valori.You can provide any value for this element. Usare questo valore per documentare le modifiche significative al modello.Use this value to document significant changes in your template. Quando si distribuiscono risorse tramite il modello, è possibile usare questo valore per assicurarsi che venga usato il modello corretto.When deploying resources using the template, this value can be used to make sure that the right template is being used.
Parametriparameters No No Valori forniti durante la distribuzione per personalizzare la distribuzione di risorse.Values that are provided when deployment is executed to customize resource deployment.
variablesvariables No No Valori usati come frammenti JSON nel modello per semplificare le espressioni di linguaggio del modello.Values that are used as JSON fragments in the template to simplify template language expressions.
functionsfunctions No No Funzioni definite dall'utente disponibili nel modello.User-defined functions that are available within the template.
resourcesresources Yes Tipi di risorse che vengono distribuite o aggiornate in un gruppo di risorse.Resource types that are deployed or updated in a resource group.
outputsoutputs No No Valori restituiti dopo la distribuzione.Values that are returned after deployment.

Ogni elemento ha proprietà che è possibile impostare.Each element has properties you can set. L'esempio seguente illustra la sintassi completa per un modello:The following example shows the full syntax for a template:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "",
    "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>" 
            }
        }
    },
    "variables": {
        "<variable-name>": "<variable-value>",
        "<variable-object-name>": {
            <variable-complex-type-value>
        },
        "<variable-object-name>": {
            "copy": [
                {
                    "name": "<name-of-array-property>",
                    "count": <number-of-iterations>,
                    "input": {
                        <properties-to-repeat>
                    }
                }
            ]
        },
        "copy": [
            {
                "name": "<variable-array-name>",
                "count": <number-of-iterations>,
                "input": {
                    <properties-to-repeat>
                }
            }
        ]
    },
    "functions": [
      {
        "namespace": "<namespace-for-your-function>",
        "members": {
          "<function-name>": {
            "parameters": [
              {
                "name": "<parameter-name>",
                "type": "<type-of-parameter-value>"
              }
            ],
            "output": {
              "type": "<type-of-output-value>",
              "value": "<function-expression>"
            }
          }
        }
      }
    ],
    "resources": [
      {
          "condition": "<boolean-value-whether-to-deploy>",
          "apiVersion": "<api-version-of-resource>",
          "type": "<resource-provider-namespace/resource-type-name>",
          "name": "<name-of-the-resource>",
          "location": "<location-of-resource>",
          "tags": {
              "<tag-name1>": "<tag-value1>",
              "<tag-name2>": "<tag-value2>"
          },
          "comments": "<your-reference-notes>",
          "copy": {
              "name": "<name-of-copy-loop>",
              "count": "<number-of-iterations>",
              "mode": "<serial-or-parallel>",
              "batchSize": "<number-to-deploy-serially>"
          },
          "dependsOn": [
              "<array-of-related-resource-names>"
          ],
          "properties": {
              "<settings-for-the-resource>",
              "copy": [
                  {
                      "name": ,
                      "count": ,
                      "input": {}
                  }
              ]
          },
          "resources": [
              "<array-of-child-resources>"
          ]
      }
    ],
    "outputs": {
        "<outputName>" : {
            "type" : "<type-of-output-value>",
            "value": "<output-value-expression>"
        }
    }
}

In questo articolo le sezioni del modello vengono esaminate in modo dettagliato.This article describes the sections of the template in greater detail.

SintassiSyntax

La sintassi di base del modello è JSON.The basic syntax of the template is JSON. Le espressioni e le funzioni estendono ad ogni modo i valori JSON disponibili all'interno del modello.However, expressions and functions extend the JSON values available within the template. Le espressioni vengono scritte all'interno di valori letterali stringa JSON il cui primo e ultimo carattere sono le parentesi quadre: rispettivamente[ e ].Expressions are written within JSON string literals whose first and last characters are the brackets: [ and ], respectively. Il valore dell'espressione viene valutato quando viene distribuito il modello.The value of the expression is evaluated when the template is deployed. Sebbene sia scritto come valore letterale stringa, il risultato della valutazione dell'espressione può essere di un tipo JSON diverso, ad esempio una matrice o un numero intero, a seconda dell'espressione effettiva.While written as a string literal, the result of evaluating the expression can be of a different JSON type, such as an array or integer, depending on the actual expression. Per avere una stringa letterale che inizi con una parentesi quadra [, ma che non venga interpretata come espressione, è necessario aggiungere un'altra parentesi in modo che la stringa inizi con [[.To have a literal string start with a bracket [, but not have it interpreted as an expression, add an extra bracket to start the string with [[.

Solitamente, si usano espressioni con funzioni per eseguire operazioni per la configurazione della distribuzione.Typically, you use expressions with functions to perform operations for configuring the deployment. Proprio come in JavaScript, le chiamate di funzione sono formattate come functionName(arg1,arg2,arg3).Just like in JavaScript, function calls are formatted as functionName(arg1,arg2,arg3). Per i riferimenti alle proprietà si usano il punto e gli operatori [index].You reference properties by using the dot and [index] operators.

L'esempio seguente illustra come usare diverse funzioni al momento di costruire un valore:The following example shows how to use several functions when constructing a value:

"variables": {
    "storageName": "[concat(toLower(parameters('storageNamePrefix')), uniqueString(resourceGroup().id))]"
}

Per l’elenco completo delle funzioni del modello, vedere Funzioni del modello di Gestione risorse di Azure.For the full list of template functions, see Azure Resource Manager template functions.

ParametriParameters

Nella sezione parameters del modello si possono specificare i valori che è possibile immettere durante la distribuzione delle risorse.In the parameters section of the template, you specify which values you can input when deploying the resources. I valori dei parametri consentono di personalizzare la distribuzione fornendo valori specifici per un determinato ambiente, ad esempio sviluppo, test e produzione.These parameter values enable you to customize the deployment by providing values that are tailored for a particular environment (such as dev, test, and production). Non è obbligatorio specificare parametri nel modello, ma senza di essi il modello distribuisce sempre le stesse risorse con lo stesso nome, la stessa posizione e le stesse proprietà.You don't have to provide parameters in your template, but without parameters your template would always deploy the same resources with the same names, locations, and properties.

L'esempio seguente illustra la definizione di un parametro semplice:The following example shows a simple parameter definition:

"parameters": {
  "siteNamePrefix": {
    "type": "string",
    "metadata": {
      "description": "The name prefix of the web app that you wish to create."
    }
  },
},

Per informazioni sulla definizione di parametri, vedere Sezione parameters dei modelli di Azure Resource Manager.For information about defining parameters, see Parameters section of Azure Resource Manager templates.

variablesVariables

Nella sezione variables è possibile costruire valori da usare in tutto il modello.In the variables section, you construct values that can be used throughout your template. Non è obbligatorio definire le variabili. Queste tuttavia consentono spesso di semplificare il modello, riducendo le espressioni complesse.You don't need to define variables, but they often simplify your template by reducing complex expressions.

L'esempio seguente illustra la definizione di una variabile semplice:The following example shows a simple variable definition:

"variables": {
  "webSiteName": "[concat(parameters('siteNamePrefix'), uniqueString(resourceGroup().id))]",
},

Per informazioni sulla definizione di variabili, vedere Sezione variables dei modelli di Azure Resource Manager.For information about defining variables, see Variables section of Azure Resource Manager templates.

FunzioniFunctions

Nel modello è possibile creare funzioni personalizzate.Within your template, you can create your own functions. Tali funzioni sono disponibili per usare il modello.These functions are available for use in your template. Si definiscono in genere espressioni complesse che non si vogliono ripetere in tutto il modello.Typically, you define complicated expression that you don't want to repeat throughout your template. Le funzioni definite dall'utente vengono create da espressioni e funzioni supportate nei modelli.You create the user-defined functions from expressions and functions that are supported in templates.

Quando si crea una funzione definita dall'utente, è necessario tenere presente alcune restrizioni:When defining a user function, there are some restrictions:

  • La funzione non può accedere alle variabili.The function can't access variables.
  • La funzione non può usare la funzione di riferimento.The function can't use the reference function.
  • I parametri della funzione non possono avere valori predefiniti.Parameters for the function can't have default values.

Le funzioni richiedono che sia definito un valore dello spazio dei nomi per evitare conflitti di denominazione con le funzioni del modello.Your functions require a namespace value to avoid naming conflicts with template functions. L'esempio illustrata una funzione che restituisce un nome di account di archiviazione:The following example shows a function that returns a storage account name:

"functions": [
  {
    "namespace": "contoso",
    "members": {
      "uniqueName": {
        "parameters": [
          {
            "name": "namePrefix",
            "type": "string"
          }
        ],
        "output": {
          "type": "string",
          "value": "[concat(toLower(parameters('namePrefix')), uniqueString(resourceGroup().id))]"
        }
      }
    }
  }
],

La funzione viene chiamata con:You call the function with:

"resources": [
  {
    "name": "[contoso.uniqueName(parameters('storageNamePrefix'))]",
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2016-01-01",
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "location": "South Central US",
    "tags": {},
    "properties": {}
  }
]

RisorseResources

Nella sezione risorse è possibile definire le risorse da distribuire o aggiornare.In the resources section, you define the resources that are deployed or updated. Questa sezione può risultare complicata perché per specificare i valori corretti è necessario comprendere i tipi da distribuire.This section can get complicated because you must understand the types you're deploying to provide the right values.

"resources": [
  {
    "apiVersion": "2016-08-01",
    "name": "[variables('webSiteName')]",
    "type": "Microsoft.Web/sites",
    "location": "[resourceGroup().location]",
    "properties": {
      "serverFarmId": "/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.Web/serverFarms/<plan-name>"
    }
  }
],

Per altre informazioni, vedere Sezione relativa alle risorse dei modelli di Azure Resource Manager.For more information, see Resources section of Azure Resource Manager templates.

OutputOutputs

Nella sezione dell'output è possibile specificare i valori restituiti dalla distribuzione.In the Outputs section, you specify values that are returned from deployment. Ad esempio, è possibile restituire l'URI per accedere a una risorsa distribuita.For example, you could return the URI to access a deployed resource.

"outputs": {
  "newHostName": {
    "type": "string",
    "value": "[reference(variables('webSiteName')).defaultHostName]"
  }
}

Per altre informazioni, vedere Sezione outputs nei modelli di Azure Resource Manager.For more information, see Outputs section of Azure Resource Manager templates.

Limiti del modelloTemplate limits

Limitare le dimensioni del modello a 1 MB e ogni file di parametri a 64 KB.Limit the size of your template to 1 MB, and each parameter file to 64 KB. Il limite di 1 MB si applica allo stato finale del modello dopo che è stato espanso con le definizioni delle risorse iterative e i valori di variabili e parametri.The 1-MB limit applies to the final state of the template after it has been expanded with iterative resource definitions, and values for variables and parameters.

Esistono anche i limiti seguenti:You're also limited to:

  • 256 parametri256 parameters
  • 256 variabili256 variables
  • 800 risorse (incluso il conteggio copie)800 resources (including copy count)
  • 64 valori di output64 output values
  • 24.576 caratteri in un'espressione di modello24,576 characters in a template expression

È possibile superare alcuni limiti del modello usando un modello annidato.You can exceed some template limits by using a nested template. Per altre informazioni, vedere Uso di modelli collegati nella distribuzione di risorse di Azure.For more information, see Using linked templates when deploying Azure resources. Per ridurre il numero di parametri, variabili o output, è possibile combinare più valori in un oggetto.To reduce the number of parameters, variables, or outputs, you can combine several values into an object. Per altre informazioni, vedere Oggetti come parametri.For more information, see Objects as parameters.

Passaggi successiviNext steps