Parameters in ARM-sjablonen

  • Artikel

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

Resource Manager parameterwaarden worden omgezet voordat de implementatiebewerkingen worden gestart. Overal waar de parameter wordt gebruikt in de sjabloon, 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 validatiebeperkingen voor aggregatietypen die kunnen worden gebruikt in definities, parameters en uitvoerdefinities . Deze beperkingen omvatten:

Notitie

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

Tip

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

U bent beperkt tot 256 parameters 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 parameternamen met kameelkasten 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 de 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 er een waarde wordt doorgegeven voor de parameter die niet een van de toegestane waarden is.

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

Standaardwaarde

U kunt een standaardwaarde opgeven voor een parameter. 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 vóór de implementatie wanneer parameters zijn omgezet.

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. De volgende sjabloon maakt de naam van een hostplan op basis van de naam van de site.

"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 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 van properties is een toewijzing van eigenschapsnaam =>typedefinitie.

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

"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' beperking heeft: true . 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 andere eigenschappen worden opgegeven dan die zijn gedefinieerd in de properties beperking. 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 elke eigenschap die niet is gedefinieerd in de properties beperking elke 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 of {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}geaccepteerd{"type": "ints", "foo": 1, "bar": 2}, maar wordt 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 van prefixItems is 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] , maar geweigerd [1, true, "foo"]:

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

U kunt gebruiken items zonder gebruik te maken van prefixItems. In het volgende voorbeeld wordt geaccepteerd [1, 2] of [1] , maar 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 wordt 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 true is, accepteren elementen van de matrix waarvan de index groter is dan de grootste index van de prefixItems beperking elke waarde. In de volgende voorbeelden worden , [1, true, 1] en [1, true, false, "foo", "bar"]geaccepteerd[1, true].

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

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

null-bare beperking

De null-beperking kan alleen worden gebruikt met languageVersion 2.0. Het geeft aan dat de waarde mogelijk is null of weggelaten. Zie Eigenschappen voor een voorbeeld.

Description

U kunt een beschrijving toevoegen aan een parameter om gebruikers van uw sjabloon te helpen begrijpen welke waarde moet worden opgegeven. Wanneer u de sjabloon implementeert via de portal, wordt de tekst die u in de beschrijving opgeeft, automatisch gebruikt als tip voor die parameter. Voeg alleen een beschrijving toe als de tekst meer informatie bevat 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

Als u wilt verwijzen naar de waarde van een parameter, gebruikt u de functie parameters . 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 geeft de verwachte eigenschappen voor het object weer. 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 Laat zien hoe u sjabloonfuncties gebruikt bij het definiëren van standaardwaarden voor parameters. Met de sjabloon worden geen resources geïmplementeerd. Het maakt parameterwaarden en retourneert deze waarden.
parameterobject Demonstreert het gebruik van een object voor een parameter. Met de sjabloon worden geen resources geïmplementeerd. Het maakt parameterwaarden en retourneert deze waarden.

Volgende stappen