Parametry w szablonach arm

W tym artykule opisano sposób definiowania i używania parametrów w szablonie 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.

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

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

Minimalna deklaracja

Co najmniej każdy parametr wymaga nazwy i typu.

Podczas wdrażania szablonu za pośrednictwem Azure Portal nazwy parametrów z camel-case są przekształcone w nazwy rozdzielone spacjami. Na przykład ciąg 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 za pomocą szablonów usługi ARMi Azure Portal .

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

Bezpieczne parametry

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

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

Dozwolone wartości

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

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

Wartość domyślna

Można określić wartość domyślną dla parametru. Wartość domyślna jest używana, gdy wartość nie zostanie podany 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żna używać wyrażeń z wartością domyślną. Nie można użyć funkcji odwołania ani żadnej z funkcji listy w sekcji parameters. Te funkcje mają stan środowiska uruchomieniowego zasobu i nie można ich wykonać przed wdrożeniem, gdy parametry są rozpoznawane.

Wyrażenia są niedozwolone w przypadku innych właściwości 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 na podstawie nazwy lokacji.

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

Ograniczenia długości

Można określić minimalną i maksymalną długość parametrów ciągu i tablicy. 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. Jeden parametr jest dla nazwy konta magazynu, która musi mieć od 3 do 24 znaków. Drugi parametr to tablica, 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 liczby całkowitej

Dla parametrów liczb całkowitych można ustawić wartości minimalne i maksymalne. Można ustawić jedno lub oba ograniczenia.

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

Opis

Możesz dodać opis do parametru, aby ułatwić użytkownikom szablonu zrozumienie wartości do podania. Podczas wdrażania szablonu za pośrednictwem portalu tekst 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 magazynu kluczy.

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

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 pokazano parametr, który jest obiektem. Wartość domyślna pokazuje 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": "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]"
            }
          }
        ]
      }
    }
  ]
}

Przykładowe szablony

W poniższych przykładach pokazano scenariusze użycia parametrów.

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

Następne kroki