Parameters in ARM-sjablonen

Artikel
09/26/2024

In dit artikel wordt beschreven hoe u parameters in uw ARM-sjabloon (Azure Resource Manager) definieert en gebruikt. Door verschillende waarden voor parameters op te geven, kunt u een sjabloon opnieuw gebruiken voor verschillende omgevingen.

Resource Manager lost parameterwaarden op voordat de implementatiebewerkingen worden gestart. Waar de parameter ook in de sjabloon wordt gebruikt, vervangt Resource Manager deze door de opgeloste waarde.

Elke parameter moet worden ingesteld op een van de gegevenstypen.

Naast minValue, maxValue, minLength, maxLength en allowedValues introduceert languageVersion 2.0 enkele statistische typevalidatiebeperkingen die moeten worden gebruikt in definities, parameters en uitvoerdefinities . Deze beperkingen zijn onder andere:

additionalProperties
Discriminator
Items
nullable
voorvoegselitems
properties

Notitie

De huidige versie van de Azure Resource Manager Tools-extensie voor Visual Studio Code herkent de verbeteringen die zijn aangebracht in languageVersion 2.0 niet.

Tip

We raden Bicep aan omdat het dezelfde mogelijkheden biedt als ARM-sjablonen en de syntaxis gemakkelijker te gebruiken is. Zie parameters voor meer informatie.

U kunt maximaal 256 parameters opgeven in een sjabloon. Zie Sjabloonlimieten voor meer informatie.

Zie Parameters voor aanbevolen procedures voor parameters.

Minimale declaratie

Elke parameter heeft minimaal een naam en type nodig.

Wanneer u een sjabloon implementeert via De Azure-portal, worden namen van parameters met een kameel hoofdlettergebruik omgezet in door spaties gescheiden namen. DemoString in het volgende voorbeeld wordt bijvoorbeeld weergegeven als Demo-tekenreeks. Zie Een implementatieknop gebruiken om sjablonen te implementeren vanuit gitHub-opslagplaats en resources implementeren met ARM-sjablonen en Azure Portal voor meer informatie.

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

Beveiligde parameters

U kunt tekenreeks- of objectparameters als veilig markeren. De waarde van een beveiligde parameter wordt niet opgeslagen in de implementatiegeschiedenis en wordt niet geregistreerd.

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

Toegestane waarden

U kunt toegestane waarden definiëren voor een parameter. U geeft de toegestane waarden op in een matrix. De implementatie mislukt tijdens de validatie als een waarde wordt doorgegeven voor de parameter die geen van de toegestane waarden is.

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

Default value

U kunt een standaardwaarde voor een parameter opgeven. De standaardwaarde wordt gebruikt wanneer er tijdens de implementatie geen waarde wordt opgegeven.

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

Als u een standaardwaarde samen met andere eigenschappen voor de parameter wilt opgeven, gebruikt u de volgende syntaxis.

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

U kunt expressies gebruiken met de standaardwaarde. U kunt de verwijzingsfunctie of een van de lijstfuncties in de sectie parameters niet gebruiken. Deze functies krijgen de runtimestatus van een resource en kunnen niet worden uitgevoerd voordat de implementatie wordt uitgevoerd wanneer parameters worden opgelost.

Expressies zijn niet toegestaan met andere parametereigenschappen.

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

U kunt een andere parameterwaarde gebruiken om een standaardwaarde te maken. Met de volgende sjabloon wordt een hostplannaam samengesteld op basis van de sitenaam.

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

U kunt echter niet verwijzen naar een variabele als de standaardwaarde.

Lengtebeperkingen

U kunt minimum- en maximumlengten opgeven voor tekenreeks- en matrixparameters. U kunt een of beide beperkingen instellen. Voor tekenreeksen geeft de lengte het aantal tekens aan. Voor matrices geeft de lengte het aantal items in de matrix aan.

In het volgende voorbeeld worden twee parameters declareren. Een parameter is voor een opslagaccountnaam die 3-24 tekens moet bevatten. De andere parameter is een matrix die uit 1-5 items moet bestaan.

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

Beperkingen voor gehele getallen

U kunt minimum- en maximumwaarden instellen voor parameters voor gehele getallen. U kunt een of beide beperkingen instellen.

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

Objectbeperkingen

De objectbeperkingen zijn alleen toegestaan voor objecten en kunnen alleen worden gebruikt met languageVersion 2.0.

Eigenschappen

De waarde is properties een toewijzing van de eigenschapsnaam =>typedefinitie.

In het volgende voorbeeld wordt geaccepteerd {"foo": "string", "bar": 1}, maar geweigerd {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}of een object zonder een foo of bar eigenschap.

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

Alle eigenschappen zijn vereist, tenzij de typedefinitie van de eigenschap de 'nullable' heeft: true constraint. Als u beide eigenschappen in het voorgaande voorbeeld optioneel wilt maken, ziet dit er als volgt uit:

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

additionalProperties

De waarde van additionalProperties is een typedefinitie of een Booleaanse waarde. Als er geen additionalProperties beperking is gedefinieerd, is truede standaardwaarde .

Als waarde een typedefinitie is, beschrijft de waarde het schema dat wordt toegepast op alle eigenschappen die niet in de properties beperking worden vermeld. In het volgende voorbeeld wordt geaccepteerd {"fizz": "buzz", "foo": "bar"} maar geweigerd {"property": 1}.

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

Als de waarde is false, kunnen er geen eigenschappen worden opgegeven buiten de eigenschappen die in de properties beperking zijn gedefinieerd. In het volgende voorbeeld wordt geaccepteerd {"foo": "string", "bar": 1}, maar geweigerd {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Als de waarde is true, accepteert een eigenschap die niet is gedefinieerd in de properties beperking een waarde. In het volgende voorbeeld wordt geaccepteerd {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Discriminator

De waarde discriminator definieert welk schema moet worden toegepast op basis van een discriminator-eigenschap. In het volgende voorbeeld wordt geaccepteerd {"type": "ints", "foo": 1, "bar": 2} of {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, maar geweigerd {"type": "ints", "fizz": "buzz"}.

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

Matrixbeperkingen

De matrixbeperkingen zijn alleen toegestaan voor matrices en kunnen alleen worden gebruikt met languageVersion 2.0.

voorvoegselitems

De waarde is prefixItems een matrix van typedefinities. Elke typedefinitie in de waarde is het schema dat moet worden gebruikt om het element van een matrix in dezelfde index te valideren. In het volgende voorbeeld wordt geaccepteerd [1, true] , maar geweigerd [1, "string"] of [1]:

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

items

De waarde van items is een typedefinitie of een Booleaanse waarde. Als er geen items beperking is gedefinieerd, is truede standaardwaarde .

Als waarde een typedefinitie is, beschrijft de waarde het schema dat wordt toegepast op alle elementen van de matrix waarvan de index groter is dan de grootste index van de prefixItems beperking. In het volgende voorbeeld wordt geaccepteerd [1, true, 1] of [1, true, 1, 1] geweigerd [1, true, "foo"]:

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

U kunt dit gebruiken items zonder gebruik te maken prefixItemsvan . In het volgende voorbeeld wordt geaccepteerd [1, 2] of [1] geweigerd ["foo"]:

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

Als de waarde is false, moet de gevalideerde matrix exact dezelfde lengte hebben als de prefixItems beperking. In het volgende voorbeeld zou worden geaccepteerd [1, true], maar geweigerd [1, true, 1]en [1, true, false, "foo", "bar"].

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

Als de waarde waar is, accepteren elementen van de matrix waarvan de index groter is dan de grootste index van de prefixItems beperking een willekeurige waarde. De volgende voorbeelden accepteren [1, true], [1, true, 1] en [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
}

nullable constraint

De null-beperking kan alleen worden gebruikt met languageVersion 2.0. Hiermee wordt aangegeven dat de waarde mogelijk wordt null of weggelaten. Zie Eigenschappen voor een voorbeeld.

Beschrijving

U kunt een beschrijving toevoegen aan een parameter om gebruikers van uw sjabloon inzicht te geven in de waarde die u moet opgeven. Bij het implementeren van de sjabloon via de portal wordt de tekst die u in de beschrijving opgeeft, automatisch gebruikt als tip voor die parameter. Voeg alleen een beschrijving toe wanneer de tekst meer informatie biedt dan kan worden afgeleid van de parameternaam.

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

Parameter gebruiken

Als u naar de waarde van een parameter wilt verwijzen, gebruikt u de parameterfunctie . In het volgende voorbeeld wordt een parameterwaarde gebruikt voor de naam van een sleutelkluis.

{
  "$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')]",
      ...
    }
  ]
}

Objecten als parameters

U kunt gerelateerde waarden ordenen door ze door te geven als een object. Deze benadering vermindert ook het aantal parameters in de sjabloon.

In het volgende voorbeeld ziet u een parameter die een object is. De standaardwaarde toont de verwachte eigenschappen voor het object. Deze eigenschappen worden gebruikt bij het definiëren van de resource die moet worden geïmplementeerd.

{
  "$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]"
            }
          }
        ]
      }
    }
  ]
}

Voorbeeldsjablonen

In de volgende voorbeelden ziet u scenario's voor het gebruik van parameters.

Sjabloon	Beschrijving
parameters met functies voor standaardwaarden	Demonstreert hoe u sjabloonfuncties gebruikt bij het definiëren van standaardwaarden voor parameters. Met de sjabloon worden geen resources geïmplementeerd. Hiermee worden parameterwaarden samengesteld en worden deze waarden geretourneerd.
parameterobject	Demonstreert het gebruik van een object voor een parameter. Met de sjabloon worden geen resources geïmplementeerd. Hiermee worden parameterwaarden samengesteld en worden deze waarden geretourneerd.

Volgende stappen

Zie De structuur en syntaxis van ARM-sjablonen voor meer informatie over de beschikbare eigenschappen voor parameters.
Zie Het parameterbestand Resource Manager maken voor meer informatie over het doorgeven van parameterwaarden als een bestand.
Zie Best practices - parameters voor aanbevelingen over het maken van parameters.

Delen via