Parametrar i ARM-mallar

  • Artikel

Den här artikeln beskriver hur du definierar och använder parametrar i din Azure Resource Manager-mall (ARM-mall). Genom att ange olika värden för parametrar kan du återanvända en mall för olika miljöer.

Resource Manager löser parametervärden innan du startar distributionsåtgärderna. Oavsett var parametern används i mallen ersätter Resource Manager den med det matchade värdet.

Varje parameter måste anges till en av datatyperna.

Förutom minValue, maxValue, minLength, maxLength och allowedValues introducerar languageVersion 2.0 vissa verifieringsbegränsningar av mängdtyp som ska användas i definitioner, parametrar och utdatadefinitioner . Dessa begränsningar omfattar:

Anteckning

Den aktuella versionen av Azure Resource Manager Tools-tillägget för Visual Studio Code känner inte igen förbättringarna i languageVersion 2.0.

Tips

Vi rekommenderar Bicep eftersom det har samma funktioner som ARM-mallar och syntaxen är enklare att använda. Mer information finns i parametrar.

Du är begränsad till 256 parametrar i en mall. Mer information finns i Mallgränser.

Metodtips för parametrar finns i Parametrar.

Minimal deklaration

Varje parameter behöver minst ett namn och en typ.

När du distribuerar en mall via Azure Portal omvandlas kamelkadlade parameternamn till blankstegsavgränsade namn. DemoString i följande exempel visas till exempel som demosträng. Mer information finns i Använda en distributionsknapp för att distribuera mallar från GitHub-lagringsplatsen och Distribuera resurser med ARM-mallar och Azure Portal.

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

Säkra parametrar

Du kan markera sträng- eller objektparametrar som säkra. Värdet för en säker parameter sparas inte i distributionshistoriken och loggas inte.

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

Tillåtna värden

Du kan definiera tillåtna värden för en parameter. Du anger tillåtna värden i en matris. Distributionen misslyckas under valideringen om ett värde skickas för parametern som inte är ett av de tillåtna värdena.

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

Standardvärde

Du kan ange ett standardvärde för en parameter. Standardvärdet används när ett värde inte anges under distributionen.

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

Om du vill ange ett standardvärde tillsammans med andra egenskaper för parametern använder du följande syntax.

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

Du kan använda uttryck med standardvärdet. Du kan inte använda referensfunktionen eller någon av listfunktionerna i avsnittet parametrar. Dessa funktioner hämtar körningstillståndet för en resurs och kan inte köras före distributionen när parametrarna matchas.

Uttryck tillåts inte med andra parameteregenskaper.

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

Du kan använda ett annat parametervärde för att skapa ett standardvärde. Följande mall skapar ett värdplansnamn från platsnamnet.

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

Längdbegränsningar

Du kan ange minsta och högsta längd för sträng- och matrisparametrar. Du kan ange en eller båda begränsningarna. För strängar anger längden antalet tecken. För matriser anger längden antalet objekt i matrisen.

I följande exempel deklareras två parametrar. En parameter är för ett lagringskontonamn som måste innehålla 3–24 tecken. Den andra parametern är en matris som måste ha mellan 1 och 5 objekt.

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

Heltalsbegränsningar

Du kan ange lägsta och högsta värden för heltalsparametrar. Du kan ange en eller båda begränsningarna.

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

Objektbegränsningar

Objektbegränsningarna är endast tillåtna för objekt och kan endast användas med languageVersion 2.0.

Egenskaper

Värdet för properties är en mappning av egenskapsnamnet =>typdefinition.

I följande exempel skulle acceptera {"foo": "string", "bar": 1}, men avvisa {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}eller något objekt utan en foo eller bar -egenskap.

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

Alla egenskaper krävs om inte egenskapens typdefinition har villkoret "nullable": true . Om du vill göra båda egenskaperna i föregående exempel valfria skulle det se ut så här:

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

additionalProperties

Värdet additionalProperties för är en typdefinition eller ett booleskt värde. Om ingen additionalProperties begränsning har definierats är truestandardvärdet .

Om värdet är en typdefinition beskriver värdet schemat som tillämpas på alla egenskaper som inte nämns i villkoret properties . I följande exempel skulle acceptera {"fizz": "buzz", "foo": "bar"} men avvisa {"property": 1}.

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

Om värdet är falsekan inga egenskaper utöver de som definierats i villkoret properties anges. I följande exempel skulle acceptera {"foo": "string", "bar": 1}, men avvisa {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Om värdet är trueaccepterar alla egenskaper som inte definierats i villkoret properties något värde. I följande exempel skulle acceptera {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

diskriminator

Värdet discriminator definierar vilket schema som ska tillämpas baserat på en diskriminerande egenskap. I följande exempel skulle acceptera antingen {"type": "ints", "foo": 1, "bar": 2} eller {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, men avvisa {"type": "ints", "fizz": "buzz"}.

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

Matrisbegränsningar

Matrisbegränsningarna tillåts endast i matriser och kan endast användas med languageVersion 2.0.

prefixItems

Värdet för prefixItems är en matris med typdefinitioner. Varje typdefinition i värdet är det schema som ska användas för att verifiera elementet i en matris vid samma index. Följande exempel skulle acceptera [1, true] men avvisa [1, "string"] eller [1]:

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

objekt

Värdet för items är en typdefinition eller ett booleskt värde. Om ingen items begränsning har definierats är truestandardvärdet .

Om värdet är en typdefinition beskriver värdet schemat som tillämpas på alla element i matrisen vars index är större än begränsningens prefixItems största index. I följande exempel skulle acceptera [1, true, 1] eller [1, true, 1, 1] men avvisa [1, true, "foo"]:

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

Du kan använda items utan att använda prefixItems. I följande exempel skulle acceptera [1, 2] eller [1] men avvisa ["foo"]:

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

Om värdet är falsemåste den verifierade matrisen ha exakt samma längd som villkoret prefixItems . I följande exempel skulle acceptera [1, true], men avvisa [1, true, 1], och [1, true, false, "foo", "bar"].

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

Om värdet är sant accepterar element i matrisen vars index är större än det största indexet för villkoret prefixItems något värde. I följande exempel skulle acceptera [1, true], [1, true, 1] och [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
}

villkor som kan ha värdet null

Den nullbara begränsningen kan endast användas med languageVersion 2.0. Det anger att värdet kan vara null eller utelämnas. Ett exempel finns i Egenskaper .

Description

Du kan lägga till en beskrivning i en parameter för att hjälpa användare av mallen att förstå värdet som ska anges. När du distribuerar mallen via portalen används den text som du anger i beskrivningen automatiskt som ett tips för den parametern. Lägg bara till en beskrivning när texten innehåller mer information än vad som kan härledas från parameternamnet.

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

Använda parameter

Om du vill referera till en parameters värde använder du parameterfunktionen . I följande exempel används ett parametervärde för ett nyckelvalvnamn.

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

Objekt som parametrar

Du kan ordna relaterade värden genom att skicka in dem som ett objekt. Den här metoden minskar också antalet parametrar i mallen.

I följande exempel visas en parameter som är ett objekt. Standardvärdet visar de förväntade egenskaperna för objektet. Dessa egenskaper används när du definierar resursen som ska distribueras.

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

Exempelmallar

I följande exempel visas scenarier för att använda parametrar.

Mall Description
parametrar med funktioner för standardvärden Visar hur du använder mallfunktioner när du definierar standardvärden för parametrar. Mallen distribuerar inga resurser. Den konstruerar parametervärden och returnerar dessa värden.
parameterobjekt Visar hur du använder ett objekt för en parameter. Mallen distribuerar inga resurser. Den konstruerar parametervärden och returnerar dessa värden.

Nästa steg