Parametry v šablonách ARM

  • Článek

Tento článek popisuje, jak definovat a používat parametry v šabloně Azure Resource Manager (šablona ARM). Zadáním různých hodnot parametrů můžete šablonu znovu použít pro různá prostředí.

Resource Manager před spuštěním operací nasazení přeloží hodnoty parametrů. Bez ohledu na to, kde se v šabloně použije parametr, Resource Manager ho nahradí přeloženou hodnotou.

Každý parametr musí být nastavený na jeden z datových typů.

Kromě minValue, maxValue, minLength, maxLength a allowedValues zavádí languageVersion 2.0 některá omezení ověřování agregovaného typu, která se mají použít v definicích, parametrech a definicích výstupů. Mezi tato omezení patří:

Poznámka

Aktuální verze rozšíření Azure Resource Manager Tools pro Visual Studio Code nerozpoznává vylepšení vytvořená v languageVersion 2.0.

Tip

Doporučujeme Bicep , protože nabízí stejné funkce jako šablony ARM a syntaxe se snadněji používá. Další informace najdete v tématu parametry.

V šabloně jste omezeni na 256 parametrů. Další informace najdete v tématu Limity šablon.

Osvědčené postupy pro parametry najdete v tématu Parametry.

Minimální deklarace

Minimálně každý parametr potřebuje název a typ.

Když nasadíte šablonu prostřednictvím Azure Portal, názvy parametrů s velbloudy a písmeny se změní na názvy oddělené mezerami. Například demoString v následujícím příkladu je zobrazen jako Ukázkový řetězec. Další informace najdete v tématech Použití tlačítka nasazení k nasazení šablon z úložiště GitHub a Nasazení prostředků pomocí šablon ARM a Azure Portal.

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

Zabezpečené parametry

Parametry řetězce nebo objektu můžete označit jako zabezpečené. Hodnota zabezpečeného parametru se neuloží do historie nasazení a nezaprotokoluje se.

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

Povolené hodnoty

Pro parametr můžete definovat povolené hodnoty. V poli zadáte povolené hodnoty. Nasazení se během ověřování nezdaří, pokud je předána hodnota parametru, který není jednou z povolených hodnot.

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

Výchozí hodnota

Pro parametr můžete zadat výchozí hodnotu. Výchozí hodnota se použije, když se během nasazení nezadá hodnota.

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

Pokud chcete zadat výchozí hodnotu spolu s dalšími vlastnostmi parametru, použijte následující syntaxi.

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

Můžete použít výrazy s výchozí hodnotou. V oddílu parametrů nemůžete použít referenční funkci ani žádnou ze seznamu funkcí. Tyto funkce získají stav modulu runtime prostředku a nelze je spustit před nasazením, když se parametry přeloží.

Výrazy nejsou povoleny s jinými vlastnostmi parametrů.

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

K vytvoření výchozí hodnoty můžete použít jinou hodnotu parametru. Následující šablona vytvoří název plánu hostitele z názvu webu.

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

Omezení délky

Pro parametry řetězce a pole můžete zadat minimální a maximální délku. Můžete nastavit jedno nebo obě omezení. U řetězců délka označuje počet znaků. U polí určuje délka počet položek v poli.

Následující příklad deklaruje dva parametry. Jeden parametr je pro název účtu úložiště, který musí mít 3 až 24 znaků. Druhý parametr je pole, které musí obsahovat 1 až 5 položek.

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

Omezení celého čísla

Můžete nastavit minimální a maximální hodnoty pro celočíselné parametry. Můžete nastavit jedno nebo obě omezení.

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

Omezení objektu

Omezení objektu jsou povolena pouze u objektů a lze je použít pouze s languageVersion 2.0.

Vlastnosti

Hodnota properties je mapa názvu vlastnosti =>definice typu.

Následující příklad by přijal {"foo": "string", "bar": 1}, ale odmítl {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}nebo jakýkoli objekt bez foo vlastnosti nebo bar .

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

Všechny vlastnosti jsou povinné, pokud definice typu vlastnosti nemá hodnotu nullable: true constraint. Aby byly obě vlastnosti v předchozím příkladu volitelné, vypadaly by takto:

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

další Vlastnosti

Hodnota additionalProperties je definice typu nebo logická hodnota. Pokud není definováno žádné additionalProperties omezení, výchozí hodnota je true.

Pokud je hodnota definicí typu, tato hodnota popisuje schéma, které se použije u všech vlastností, které nejsou uvedené v properties omezení. Následující příklad by přijal, {"fizz": "buzz", "foo": "bar"} ale odmítl {"property": 1}.

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

Pokud je falsehodnota , nesmí být zadány žádné vlastnosti nad rámec těch, které jsou definovány properties v omezení. Následující příklad by přijal {"foo": "string", "bar": 1}, ale odmítl {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Pokud je truehodnota , jakákoli vlastnost, která není definována properties v omezení, přijímá jakoukoli hodnotu. Následující příklad by přijal {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Diskriminátor

Hodnota discriminator definuje, jaké schéma se má použít na základě diskriminující vlastnosti. Následující příklad by přijal buď {"type": "ints", "foo": 1, "bar": 2} nebo , {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}ale odmítl {"type": "ints", "fizz": "buzz"}.

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

Omezení pole

Omezení pole jsou povolena pouze u polí a lze je použít pouze s languageVersion 2.0.

prefixItems

Hodnota je prefixItems pole definic typů. Každá definice typu v hodnotě je schéma, které se má použít k ověření prvku pole ve stejném indexu. Následující příklad by přijal, [1, true] ale odmítl [1, "string"] nebo [1]:

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

položky

Hodnota items je definice typu nebo logická hodnota. Pokud není definováno žádné items omezení, výchozí hodnota je true.

Pokud je hodnota definice typu, tato hodnota popisuje schéma, které se použije na všechny prvky pole, jejichž index je větší než největší index prefixItems omezení. Následující příklad by přijal [1, true, 1] nebo [1, true, 1, 1] odmítl [1, true, "foo"]:

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

Můžete použít items bez použití prefixItems. Následující příklad by přijal [1, 2] nebo [1] odmítl ["foo"]:

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

Pokud je falsehodnota , musí být ověřená matice přesně stejná jako prefixItems omezení. Následující příklad by přijal [1, true], ale odmítl [1, true, 1]a [1, true, false, "foo", "bar"].

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

Pokud je hodnota true, prvky pole, jejichž index je větší než největší index omezení, přijímají libovolnou prefixItems hodnotu. Následující příklady by akceptovaly [1, true], [1, true, 1] a [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
}

Omezení s možnou hodnotou null

Omezení s možnou hodnotou null lze použít pouze s languageVersion 2.0. Označuje, že hodnota může být null nebo vynechána. Příklad najdete v tématu Vlastnosti .

Description

K parametru můžete přidat popis, který uživatelům šablony pomůže pochopit hodnotu, kterou mají poskytnout. Při nasazování šablony prostřednictvím portálu se text, který zadáte v popisu, automaticky použije jako tip pro daný parametr. Popis přidejte pouze v případech, kdy text obsahuje více informací, než je možné odvodit z názvu parametru.

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

Použití parametru

Pokud chcete odkazovat na hodnotu parametru, použijte funkci parameters . Následující příklad používá hodnotu parametru pro název trezoru klíčů.

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

Objekty jako parametry

Související hodnoty můžete uspořádat tak, že je předáte jako objekt. Tento přístup také snižuje počet parametrů v šabloně.

Následující příklad ukazuje parametr, který je objektem. Výchozí hodnota zobrazuje očekávané vlastnosti objektu. Tyto vlastnosti se používají při definování prostředku, který se má nasadit.

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

Ukázkové šablony

Následující příklady ukazují scénáře použití parametrů.

Template (Šablona) Description
parametry s funkcemi pro výchozí hodnoty Ukazuje, jak používat funkce šablony při definování výchozích hodnot pro parametry. Šablona nenasadí žádné prostředky. Vytvoří hodnoty parametrů a vrátí tyto hodnoty.
parameter – objekt Ukazuje použití objektu pro parametr. Šablona nenasadí žádné prostředky. Vytvoří hodnoty parametrů a vrátí tyto hodnoty.

Další kroky