Parametry v šablonách ARM

Tento článek popisuje, jak definovat a používat parametry v šabloně Azure Resource Manageru (š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 zahájením operací nasazení přeloží hodnoty parametrů. Pokud se parametr v šabloně používá, 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, languageVersion 2.0 zavádí některá omezení ověření agregovaného typu, která se mají použít v definicích, parametrech a výstupních definicích. Mezi tato omezení patří:

• additionalProperties
• diskriminátor
• položky
• Nullable
• prefixItems
• vlastnosti

V šabloně můžete zadat jen 256 parametrů. Další informace najdete v tématu Omezení š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 webu Azure Portal, názvy parametrů s malých písmeny se změní na názvy oddělené mezerami. Například demoString v následujícím příkladu je zobrazen jako Demo String. Další informace najdete v tématu Použití tlačítka nasazení k nasazení šablon z úložiště GitHub a nasazení prostředků pomocí šablon ARM a webu 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 bezpečné. 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. Do pole zadáte povolené hodnoty. Nasazení selže během ověřování, pokud je hodnota předána pro parametr, který není jednou z povolených hodnot.

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

Default value

Můžete zadat výchozí hodnotu parametru. Výchozí hodnota se použije, když není během nasazení zadaná 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"
    ]
  }
}

Výrazy můžete použít s výchozí hodnotou. V oddílu parametrů nemůžete použít referenční funkci ani žádnou funkci seznamu . Tyto funkce získají stav modulu runtime prostředku a nelze je spustit před nasazením při vyřešení parametrů.

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

Na proměnnou ale nemůžete odkazovat jako na výchozí hodnotu.

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 matici.

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

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

Celočíselná omezení

Pro celočíselné parametry můžete nastavit minimální a maximální hodnoty. 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 ji 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ítnout {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}nebo jakýkoli objekt bez foo nebo bar vlastnost.

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

Všechny vlastnosti jsou vyžadovány, pokud definice typu vlastnosti nemá hodnotu nullable: true constraint. Pokud chcete, aby obě vlastnosti v předchozím příkladu byly volitelné, vypadaly by takto:

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

additionalProperties

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

Pokud je hodnota definice typu, hodnota popisuje schéma, které je použito na všechny vlastnosti, které nejsou uvedeny 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ítnout {"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á libovolnou 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ě nediskriminační 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ítnout {"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 jazykemVersion 2.0.

prefixItems

Hodnota prefixItems je 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, hodnota popisuje schéma použité pro 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 se jedná falseo hodnotu, musí být ověřená matice přesně stejná jako prefixItems omezení. Následující příklad by přijal [1, true], ale odmítnout [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 prefixItems omezení, přijímají libovolnou hodnotu. Následující příklady by přijímaly [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 části Vlastnosti .

Popis

K parametru můžete přidat popis, který uživatelům šablony pomůže pochopit hodnotu, kterou chcete poskytnout. Při nasazování šablony prostřednictvím portálu se text, který zadáte v popisu, automaticky použije jako tip pro tento parametr. Přidejte popis pouze v případech, kdy text poskytuje více informací, než lze 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 parametrů . 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 objekt. 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ů.

Další kroky

• Informace o dostupných vlastnostech parametrů najdete v tématu Vysvětlení struktury a syntaxe šablon ARM.
• Další informace o předávání hodnot parametrů jako souboru najdete v tématu Vytvoření souboru parametrů Resource Manageru.
• Doporučení týkající se vytváření parametrů najdete v tématu Osvědčené postupy – parametry.