Parametry w szablonach usługi ARM

W tym artykule opisano sposób definiowania i używania parametrów w szablonie usługi Azure Resource Manager (szablon usługi ARM). Podając różne wartości parametrów, można ponownie użyć szablonu dla różnych środowisk.

Usługa Resource Manager rozwiązuje wartości parametrów przed rozpoczęciem operacji wdrażania. Wszędzie tam, gdzie parametr jest używany w szablonie, usługa Resource Manager zastępuje go rozpoznaną wartością.

Każdy parametr musi być ustawiony na jeden z typów danych.

Oprócz parametrów minValue, maxValue, minLength, maxLength i allowedValues, languageVersion 2.0 wprowadza pewne ograniczenia walidacji typów agregowanych, które mają być używane w definicjach definicjach, parametrów i danych wyjściowych. Te ograniczenia obejmują:

Napiwek

Zalecamy Bicep , ponieważ oferuje te same możliwości co szablony usługi ARM, a składnia jest łatwiejsza w użyciu. Aby dowiedzieć się więcej, zobacz parametry.

W szablonie można umieścić maksymalnie 256 parametrów. Aby uzyskać więcej informacji, zobacz Limity szablonów.

Aby poznać najlepsze praktyki dotyczące parametrów, zobacz Parametry.

Minimalna deklaracja

Co najmniej każdy parametr wymaga nazwy i typu.

Podczas wdrażania szablonu za pośrednictwem witryny Azure Portal nazwy parametrów w notacji camelCase są zamieniane na nazwy rozdzielane spacjami. Na przykład demoString w poniższym przykładzie jest wyświetlany jako Ciąg demonstracyjny. Aby uzyskać więcej informacji, zobacz Używanie przycisku wdrażania do wdrażania szablonów z repozytorium GitHub i Wdrażanie zasobów przy użyciu szablonów usługi ARM i witryny Azure Portal.

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

Zabezpieczone parametry

Parametry ciągu lub obiektu można oznaczyć jako poufne. Wartość bezpiecznego parametru nie jest zapisywana w historii wdrażania i nie jest rejestrowana.

Maskowanie dotyczy samej bezpiecznej wartości. Nie jest gwarantowane, że dotyczy wartości, którą szablon przekształca lub uzyskuje z wartości zabezpieczonej, takiej jak odwrócony ciąg znaków, podciąg, wartość ponownie zakodowana lub wartość łączona. Unikaj umieszczania sekretów w wyrażeniach, które je przekształcają, gdy wynik może pojawić się w komunikatie o błędzie.

Bezpieczne parametry zmniejszają ryzyko ujawnienia sekretów, ale nie sprawiają, że każda wartość wyciągnięta z sekretu jest bezpieczna do ujawnienia. Nie włączaj sekretów do nazw zasobów, ciągów konfiguracyjnych podatnych na błędy, wyjść, tagów ani innych wartości, które mogą zostać zwrócone przez dostawcę zasobów. Gdy rozwiązujesz problem z nieudanym wdrożeniem, traktuj komunikaty o błędach jako potencjalnie wrażliwe i przejrzyj je przed udostępnieniem.

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

Dozwolone wartości

Dozwolone wartości parametru można zdefiniować. Podajesz dozwolone wartości w tablicy. Wdrożenie kończy się niepowodzeniem podczas walidacji, jeśli wartość jest przekazywana dla parametru, który nie jest jedną z dozwolonych wartości.

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

Domyślna wartość

Możesz określić wartość domyślną parametru. Wartość domyślna jest używana, gdy wartość nie jest podana podczas wdrażania.

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

Aby określić wartość domyślną wraz z innymi właściwościami parametru, użyj następującej składni.

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

Możesz używać wyrażeń wraz z wartością domyślną. Nie można użyć funkcji reference ani żadnej z funkcji list w sekcji parametrów. Te funkcje pobierają stan zasobu w czasie wykonywania i nie można ich wykonać przed wdrożeniem, gdy parametry są rozwiązywane.

Wyrażenia nie są dozwolone z innymi właściwościami parametrów.

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

Możesz użyć innej wartości parametru, aby utworzyć wartość domyślną. Poniższy szablon tworzy nazwę planu hosta z nazwy witryny.

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

Nie można jednak odwołać się do zmiennej jako wartości domyślnej.

Ograniczenia długości

Można określić minimalną i maksymalną długość dla parametrów typu ciąg znaków i tablica. Można ustawić jedno lub oba ograniczenia. W przypadku ciągów długość wskazuje liczbę znaków. W przypadku tablic długość wskazuje liczbę elementów w tablicy.

Poniższy przykład deklaruje dwa parametry. Jednym z parametrów jest nazwa konta magazynu danych, która musi mieć od 3 do 24 znaków. Drugi parametr jest tablicą, która musi zawierać od 1 do 5 elementów.

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

Ograniczenia liczb całkowitych

Można ustawić wartości minimalne i maksymalne dla parametrów całkowitoliczbowych. Można ustawić jedno lub oba ograniczenia.

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

Ograniczenia obiektu

Ograniczenia dotyczące obiektów są dozwolone tylko dla obiektów i mogą być używane tylko z languageVersion 2.0.

Właściwości

Wartość properties to mapa >nazwa właściwości = definicja typu.

Poniższy przykład zaakceptowałby {"foo": "string", "bar": 1}element, ale odrzuciłby {"foo": "string", "bar": -1}element, {"foo": "", "bar": 1} lub dowolny obiekt bez foo lub bar właściwości.

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

Wszystkie właściwości są wymagane, chyba że definicja typu właściwości ma ograniczenie "nullable": true. Aby ustawić obie właściwości w poprzednim przykładzie jako opcjonalne, wyglądałoby to następująco:

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

dodatkowe właściwości

Wartość additionalProperties jest definicją typu lub wartością logiczną. Jeśli nie additionalProperties zdefiniowano żadnego ograniczenia, wartość domyślna to true.

Jeśli wartość jest definicją typu, wartość opisuje schemat, który jest stosowany do wszystkich właściwości, które nie zostały wymienione w ograniczeniu properties . Poniższy przykład akceptuje {"fizz": "buzz", "foo": "bar"}, ale odrzuca {"property": 1}.

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

Jeśli wartość to false, nie można podać żadnych właściwości poza tymi zdefiniowanymi w ograniczeniu properties . Poniższy przykład zaakceptowałby {"foo": "string", "bar": 1}, ale odrzuciłby {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Jeśli wartość to true, każda właściwość nie zdefiniowana w ograniczeniu properties akceptuje dowolną wartość. Poniższy przykład będzie akceptował {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Dyskryminator

Wartość discriminator określa, który schemat zastosować na podstawie właściwości dyskryminującej. W poniższym przykładzie zostanie zaakceptowana wartość {"type": "ints", "foo": 1, "bar": 2} lub {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, ale wartość {"type": "ints", "fizz": "buzz"} zostanie odrzucona.

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

Ograniczenia macierzy

Ograniczenia tablic są dozwolone tylko dla tablic i mogą być używane tylko z languageVersion 2.0.

prefixItems

Wartość prefixItems to tablica definicji typu. Każda definicja typu w wartości jest schematem używanym do sprawdzania poprawności elementu tablicy na tej samej pozycji. Poniższy przykład akceptuje [1, true] , ale odrzuca [1, "string"] lub [1]:

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

elementy

Wartość items jest definicją typu lub wartością logiczną. Jeśli nie zdefiniowano żadnego ograniczenia items, wartość domyślna to true.

Jeśli wartość jest definicją typu, wartość opisuje schemat stosowany do wszystkich elementów tablicy, których indeks jest większy niż największy indeks ograniczenia prefixItems. Poniższy przykład zaakceptuje [1, true, 1] lub [1, true, 1, 1], ale odrzuci [1, true, "foo"]:

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

Można użyć items bez użycia polecenia prefixItems. W poniższym przykładzie zostaną zaakceptowane [1, 2] lub [1], ale ["foo"] zostanie odrzucone.

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

Jeśli wartość to false, zweryfikowana tablica musi mieć dokładnie tę samą długość co ograniczenie prefixItems. W poniższym przykładzie zostanie zaakceptowane [1, true], ale odrzucone [1, true, 1] i [1, true, false, "foo", "bar"].

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

Jeśli wartość ma wartość true, elementy tablicy, których indeks jest większy niż największy indeks ograniczenia prefixItems, akceptują dowolną wartość. Poniższe przykłady akceptują [1, true], [1, true, 1] i [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
}

ograniczenie nullowalności

Ograniczenie nullable może być używane tylko z languageVersion 2.0. Wskazuje, że wartość może wynosić null lub zostać pominięta. Zobacz Właściwości , aby zapoznać się z przykładem.

Opis

Możesz dodać opis do parametru, aby ułatwić użytkownikom szablonu zrozumienie wartości, którą należy podać. Podczas wdrażania szablonu za pośrednictwem portalu tekst, który podajesz w opisie, jest automatycznie używany jako porada dla tego parametru. Dodaj opis tylko wtedy, gdy tekst zawiera więcej informacji niż można wywnioskować z nazwy parametru.

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

Użyj parametru

Aby odwołać się do wartości parametru, użyj funkcji parameters. W poniższym przykładzie użyto wartości parametru dla nazwy usługi Key Vault.

{
  "$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": "2025-05-01",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

Obiekty jako parametry

Powiązane wartości można organizować, przekazując je jako obiekt. Takie podejście zmniejsza również liczbę parametrów w szablonie.

W poniższym przykładzie przedstawiono parametr, który jest obiektem. Wartość domyślna zawiera oczekiwane właściwości obiektu. Te właściwości są używane podczas definiowania zasobu do wdrożenia.

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

Przykładowe szablony

W poniższych przykładach przedstawiono scenariusze używania parametrów.

Szablon Opis
parametry z funkcjami jako wartościami domyślnymi Pokazuje, jak używać funkcji szablonu podczas definiowania wartości domyślnych parametrów. Szablon nie wdraża żadnych zasobów. Tworzy wartości parametrów i zwraca te wartości.
obiekt parametru Pokazuje użycie obiektu jako parametru. Szablon nie wdraża żadnych zasobów. Tworzy wartości parametrów i zwraca te wartości.

Następne kroki

  • Ostatnia aktualizacja o