Parametri nei modelli di ARM

  • Articolo

Questo articolo descrive come definire e usare i parametri in un modello di Azure Resource Manager (modello di ARM). Fornendo valori diversi per i parametri, è possibile riutilizzare un modello per ambienti diversi.

Resource Manager risolve i valori dei parametri prima di avviare le operazioni di distribuzione. Ovunque venga usato il parametro nel modello, Resource Manager lo sostituisce con il valore risolto.

Ogni parametro deve essere impostato su uno dei tipi di dati.

Oltre a minValue, maxValue, minLength, maxLength e allowedValues, languageVersion 2.0 introduce alcuni vincoli di convalida dei tipi aggregati da usare nelle definizioni, definizioni parametri e output. Questi vincoli includono:

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. Per altre informazioni, vedere parametri.

È previsto un limite di 256 parametri in un modello. Per altre informazioni, vedere Limiti dei modelli.

Per le procedure consigliate per i parametri, vedere Parametri.

Dichiarazione minima

Come minimo, ogni parametro richiede un nome e un tipo.

Quando si distribuisce un modello tramite il portale di Azure, i nomi dei parametri con maiuscole e minuscole camel vengono trasformati in nomi separati da spazi. Ad esempio, demoString nell'esempio seguente viene illustrato come Demo String. Per altre informazioni, vedere Usare un pulsante di distribuzione per distribuire i modelli dal repository GitHub e Distribuire le risorse con i modelli di Resource Manager e il portale di Azure.

"parameters": {
  "demoString": {
    "type": "string"
  },
  "demoInt": {
    "type": "int"
  },
  "demoBool": {
    "type": "bool"
  },
  "demoObject": {
    "type": "object"
  },
  "demoArray": {
    "type": "array"
  }
}

Parametri protetti

È possibile contrassegnare i parametri stringa o oggetto come sicuri. Il valore di un parametro sicuro non viene salvato nella cronologia di distribuzione e non viene registrato.

"parameters": {
  "demoPassword": {
    "type": "secureString"
  },
  "demoSecretObject": {
    "type": "secureObject"
  }
}

Valori consentiti

È possibile definire i valori consentiti per un parametro. È possibile specificare i valori consentiti in un array. La distribuzione non riesce durante la convalida se viene passato un valore per il parametro che non rientra tra i valori consentiti.

"parameters": {
  "demoEnum": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

Valore predefinito

È possibile specificare un valore predefinito per un parametro. Il valore predefinito viene usato quando non viene specificato un valore durante la distribuzione.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso"
  }
}

Per specificare un valore predefinito insieme ad altre proprietà per il parametro, utilizzare la sintassi seguente.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso",
    "allowedValues": [
      "Contoso",
      "Fabrikam"
    ]
  }
}

È possibile usare espressioni con il valore predefinito. Non è possibile usare la funzione di riferimento o una qualsiasi delle funzioni elenco presenti nella sezione Parametri. Tali funzioni ottengono lo stato di runtime di una risorsa e non possono essere eseguite prima della distribuzione, quando i parametri vengono risolti.

Le espressioni non sono consentite con altre proprietà dei parametri.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

Si può usare il valore di un altro parametro per generare un valore predefinito. Il modello seguente costruisce un nome di piano host dal nome del sito.

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]"
  }
}

Tuttavia, non è possibile fare riferimento a una variabile come valore predefinito.

Vincoli di lunghezza

È possibile specificare lunghezze minime e massime per le definizioni dei parametri stringa e array. È 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 dichiarati due parametri. Un parametro è per un nome di account di archiviazione che deve avere 3-24 caratteri. L'altro parametro è un array che deve avere da 1 a 5 elementi.

"parameters": {
  "storageAccountName": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNames": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

Vincoli sui numeri interi

È possibile impostare valori minimi e massimi per i parametri sui numeri interi. È possibile impostare uno o entrambi i vincoli.

"parameters": {
  "month": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

Vincoli oggetto

I vincoli di oggetto sono consentiti solo per gli oggettie possono essere usati solo con languageVersion 2.0.

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.

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
}

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:

"parameters": {
  "objectParameter": {
    "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}.

"parameters": {
  "dictionaryParameter": {
    "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"}.

"parameters": {
  "dictionaryParameter": {
    "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"}.

"parameters": {
  "dictionaryParameter": {
    "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"}.

"parameters": {
  "taggedUnionParameter": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

Vincoli di matrice

I vincoli di matrice sono consentiti solo per le matricie possono essere usati solo con languageVersion 2.0.

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]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

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"]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" },
    "defaultValue": [1, true, "foo"]
  }
}

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

"parameters": {
  "intArrayParameter": {
    "type": "array",
    "items": {"type": "int"}
  }
}

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"].

"parameters": {
  "tupleParameter": {
    "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"].

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

Vincolo nullable

Il vincolo nullable può essere usato solo con languageVersion 2.0. Indica che il valore può essere null o omesso. Per un esempio, vedere Proprietà.

Descrizione

È possibile aggiungere una descrizione a un parametro per aiutare gli utenti del modello a comprendere il valore da fornire. Durante la distribuzione del modello tramite il portale, il testo specificato nella descrizione viene usato automaticamente come suggerimento per tale parametro. Aggiungere una descrizione solo quando il testo fornisce più informazioni di quanto possa essere dedotto dal nome del parametro.

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

Usare il parametro

Per fare riferimento al valore di un parametro, usare la funzione parametri. Nell'esempio seguente viene usato un valore di parametro per un nome dell'insieme di credenziali delle chiavi.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vaultName": {
      "type": "string",
      "defaultValue": "[format('keyVault{0}', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-06-01-preview",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

Oggetti come parametri

È possibile organizzare i valori correlati passandoli come oggetto. Questo approccio riduce anche il numero di parametri nel modello.

Nell'esempio seguente viene illustrato un parametro che è un oggetto. Il valore predefinito mostra le proprietà previste per l'oggetto. Queste proprietà vengono usate quando si definisce la risorsa da distribuire.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vNetSettings": {
      "type": "object",
      "defaultValue": {
        "name": "VNet1",
        "location": "eastus",
        "addressPrefixes": [
          {
            "name": "firstPrefix",
            "addressPrefix": "10.0.0.0/22"
          }
        ],
        "subnets": [
          {
            "name": "firstSubnet",
            "addressPrefix": "10.0.0.0/24"
          },
          {
            "name": "secondSubnet",
            "addressPrefix": "10.0.1.0/24"
          }
        ]
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2021-02-01",
      "name": "[parameters('vNetSettings').name]",
      "location": "[parameters('vNetSettings').location]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vNetSettings').addressPrefixes[0].addressPrefix]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('vNetSettings').subnets[0].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[0].addressPrefix]"
            }
          },
          {
            "name": "[parameters('vNetSettings').subnets[1].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[1].addressPrefix]"
            }
          }
        ]
      }
    }
  ]
}

Modelli di esempio

Gli esempi seguenti illustrano gli scenari per l'uso dei parametri.

Modello Descrizione
parametri con funzioni per i valori predefiniti Illustra come usare le funzioni di modello quando si definiscono valori predefiniti per i parametri. Il modello non distribuisce alcuna risorsa. Crea valori di parametro e restituisce questi valori.
oggetto parametro Illustra l'uso di un oggetto per un parametro. Il modello non distribuisce alcuna risorsa. Crea valori di parametro e restituisce questi valori.

Passaggi successivi