Parameters in ARM-sjablonen

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

Resource Manager parameterwaarden oplost voordat u de implementatiebewerkingen start. Waar de parameter ook wordt gebruikt in de sjabloon, Resource Manager deze vervangt door de opgeloste waarde.

Elke parameter moet worden ingesteld op een van de gegevenstypen.

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.

Minimale declaratie

Elke parameter heeft minimaal een naam en type nodig.

Wanneer u een sjabloon implementeert via de Azure Portal, worden kameel-cased parameternamen omgezet in door spaties gescheiden namen. DemoString in het volgende voorbeeld wordt bijvoorbeeld weergegeven als Demo String. 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 voor een parameter definiëren. 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"
    ]
  }
}

Standaardwaarde

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

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

Gebruik de volgende syntaxis om een standaardwaarde samen met andere eigenschappen voor de parameter op te geven.

"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')]"
  }
}

Lengtebeperkingen

U kunt de minimum- en maximumlengte voor tekenreeks- en matrixparameters opgeven. 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
  }
}

Description

U kunt een beschrijving toevoegen aan een parameter om gebruikers van uw sjabloon inzicht te geven in de waarde die moet worden opgegeven. 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 uit de parameternaam.

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

Parameter gebruiken

Gebruik de parameterfunctie om te verwijzen naar de waarde van een parameter. 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 aanpak 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.

Template Beschrijving
parameters met functies voor standaardwaarden Demonstreert hoe u sjabloonfuncties gebruikt bij het definiëren van standaardwaarden voor parameters. De sjabloon implementeert geen resources. Hiermee worden parameterwaarden samengesteld en worden deze waarden geretourneerd.
parameterobject Demonstreert het gebruik van een object voor een parameter. De sjabloon implementeert geen resources. Hiermee worden parameterwaarden samengesteld en worden deze waarden geretourneerd.

Volgende stappen