Condividi tramite

Parametri nei modelli di Resource Manager

  • Articolo

Questo articolo descrive come definire e usare i parametri nel modello di Azure Resource Manager (modello 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 il parametro venga usato 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 di aggregazione da usare nelle definizioni, nei parametri e nelle definizionidi output. Questi vincoli includono:

Nota

La versione corrente dell'estensione Azure Resource Manager Tools per Visual Studio Code non riconosce i miglioramenti apportati in languageVersion 2.0.

Suggerimento

È consigliabile Usare Bicep perché offre le stesse funzionalità dei modelli di Resource Manager e la sintassi è più semplice da usare. Per altre informazioni, vedere parametri.

Sono limitati a 256 parametri in un modello. Per altre informazioni, vedere Limiti dei modelli.

Per le procedure consigliate per i parametri, vedere Parametri.

Dichiarazione minima

Almeno, ogni parametro richiede un nome e un tipo.

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

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

Parametri sicuri

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

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

Valori consentiti

È possibile definire valori consentiti per un parametro. Specificare i valori consentiti in una matrice. La distribuzione ha esito negativo durante la convalida se un valore viene passato per il parametro che non è uno dei 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 un valore non viene fornito durante la distribuzione.

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

Per specificare un valore predefinito insieme ad altre proprietà per il parametro, usare 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 delle funzioni di elenco nella sezione parametri. Queste funzioni ottengono lo stato di runtime di una risorsa e non possono essere eseguite prima della distribuzione quando vengono risolti i parametri.

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 del piano host dal nome del sito.

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

Vincoli di lunghezza

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

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

Vincoli integer

È possibile impostare valori minimi e massimi per i parametri integer. È possibile impostare uno o entrambi i vincoli.

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

Vincoli di oggetto

I vincoli dell'oggetto sono consentiti solo sugli oggetti e possono essere usati solo con languageVersion 2.0.

Proprietà

Il valore di è una mappa del nome della properties proprietà =>definizione del tipo.

L'esempio seguente accetta {"foo": "string", "bar": 1}, ma rifiuta {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}o qualsiasi oggetto senza una foo proprietà o bar .

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

Tutte le proprietà sono necessarie a meno che la definizione del tipo della proprietà non abbia il vincolo "nullable": true . Per rendere entrambe le proprietà nell'esempio precedente facoltativo, sarà simile al seguente:

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

proprietà aggiuntive

Il valore di è una definizione di additionalProperties tipo o un valore booleano. Se non additionalProperties viene definito alcun vincolo, il valore predefinito è true.

Se il valore è una definizione di tipo, il valore descrive lo schema applicato a tutte le proprietà non indicate nel properties vincolo. 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 specificare proprietà oltre quelle definite nel properties vincolo. 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 properties vincolo accetta alcun 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à discriminatoria. L'esempio seguente accetta o {"type": "ints", "foo": 1, "bar": 2}{"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 della matrice sono consentiti solo nelle matrici e 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 allo stesso indice. L'esempio seguente accetta [1, true] ma rifiuta [1, "string"] o [1]:

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

items

Il valore di è una definizione di items tipo o un booleano. Se non items viene definito alcun vincolo, il valore predefinito è true.

Se il valore è una definizione di tipo, il valore descrive lo schema applicato a tutti gli elementi della matrice il cui indice è maggiore dell'indice più grande del prefixItems vincolo. L'esempio seguente accetta [1, true, 1] o [1, true, 1, 1] rifiuta [1, true, "foo"]:

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

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

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

Se il valore è false, la matrice convalidata deve essere la stessa lunghezza del prefixItems vincolo. 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 prefixItems vincolo accettano qualsiasi valore. Gli esempi seguenti accettano [1, true]e [1, true, 1][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 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 parameters . 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 parameter 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