Параметры в шаблонах ARM

Статья
09/26/2024

В этой статье описано, как определять и использовать параметры в шаблоне Azure Resource Manager (шаблон ARM). Предоставляя различные значения параметров, можно повторно использовать шаблон в разных средах.

Resource Manager разрешает значения параметров перед началом операций развертывания. Когда в шаблоне используется параметр, Resource Manager заменяет его разрешенным значением.

Для каждого параметра необходимо задать один из типов данных.

Помимо minValue, maxValue, minLength, maxLength и allowedValues, languageVersion 2.0 содержит некоторые ограничения проверки агрегатного типа, используемые в определениях, параметрах и определениях выходных данных. К этим ограничениям относятся следующие:

additionalProperties
дискриминатор
items
nullable
префиксItems
properties

Примечание.

Текущий выпуск расширения средств Azure Resource Manager для Visual Studio Code не распознает улучшения, внесенные в languageVersion 2.0.

Совет

Мы рекомендуем использовать Bicep, так как он предоставляет те же возможности, что и шаблоны ARM, и имеет более простой синтаксис. Дополнительные сведения см. в разделе Параметры.

В шаблоне может быть не более 256 параметров. Дополнительные сведения см. в разделе Ограничения шаблона.

Рекомендации по настройке параметров см. в разделе Параметры.

Минимальное объявление

Для каждого параметра требуется как минимум указать имя и тип.

При развертывании шаблона с помощью портала Azure имена параметров в "верблюжьем" регистре преобразуются в имена, разделенные пробелами. Например, строка demoString в следующем примере показана как Demo String. Дополнительные сведения см. в статьях Использование кнопки развертывания для развертывания шаблонов из репозитория GitHub и Развертывание ресурсов с помощью шаблонов ARM и портала Azure.

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

Защищенные параметры

Можно пометить параметры типа "строка" или "объект" как защищенные. Значение защищенного параметра не сохраняется в журнале развертывания и не заносится в журнал.

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

Допустимые значения

Вы можете определить допустимые значения параметра. Допустимые значения задаются в массиве. Развертывание завершается ошибкой во время проверки, если значение передается в качестве параметра, который не является одним из допустимых значений.

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

Default value

Можно указать значение параметра по умолчанию. Оно используется, если во время развертывания не указано значение.

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

Чтобы задать значение по умолчанию вместе с другими свойствами для параметра, используйте приведенный ниже синтаксис.

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

Выражения можно использовать со значением по умолчанию. Нельзя использовать функцию reference или любую из функций list в разделе parameters. Эти функции получают состояние среды выполнения ресурса и не могут быть выполнены перед развертыванием при разрешении параметров.

Выражения с другими свойствами параметров не допускаются.

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

Также для создания значения по умолчанию можно использовать значение другого параметра. Следующий шаблон конструирует имя плана узла из имени сайта.

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

Однако нельзя ссылаться на переменную в качестве значения по умолчанию.

Ограничения длины

Для параметров типов “строка” и “массив” можно указать минимальную и максимальную длину. Вы можете установить один или оба этих предела. Для строк длина указывает количество символов. Для массивов она указывает количество элементов.

В приведенном ниже примере объявляются два параметра. Один из них — имя учетной записи хранения, которое должно содержать 3–24 символа. Другой параметр — это массив, который должен содержать от 1 до 5 элементов.

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

Ограничения для целочисленных параметров

Для целочисленных параметров можно задать минимальное и максимальное значения. Вы можете установить один или оба этих предела.

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

Ограничения объектов

Ограничения объектов разрешены только для объектов и могут использоваться только с languageVersion 2.0.

Свойства

Значением properties является карта имени свойства =>определение типа.

В следующем примере будет принято, {"foo": "string", "bar": 1}но отклонить {"foo": "", "bar": 1}{"foo": "string", "bar": -1}или любой объект без foo свойства.bar

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

Все свойства требуются, если определение типа свойства не имеет значения NULL: значение true. Чтобы сделать оба свойства в предыдущем примере необязательным, будет выглядеть следующим образом:

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

additionalProperties

Значением additionalProperties является определение типа или логическое значение. Если ограничение не additionalProperties определено, значение по умолчанию равно true.

Если значение является определением типа, значение описывает схему, которая применяется ко всем свойствам, не упомянутым в ограничении properties . В следующем примере будет принято {"fizz": "buzz", "foo": "bar"} , но отклонено {"property": 1}.

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

Если значение равно false, свойства, не превышающие указанные в ограничении properties , могут быть предоставлены. В следующем примере будет принято {"foo": "string", "bar": 1}, но отклонить {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Если значение равно true, любое свойство, не определенное в ограничении properties , принимает любое значение. В следующем примере будет принято {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

дискриминатор

Значение discriminator определяет, какая схема применяется на основе дискриминационных свойств. В следующем примере будет принято либо {"type": "ints", "foo": 1, "bar": 2} или {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}отклонено {"type": "ints", "fizz": "buzz"}.

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

Ограничения массива

Ограничения массива разрешены только для массивов и могут использоваться только с languageVersion 2.0.

префиксItems

Значением prefixItems является массив определений типов. Каждое определение типа в значении — это схема, используемая для проверки элемента массива по одному индексу. В следующем примере будет принято [1, true] , но отклонено [1, "string"] или [1]:

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

items

Значением items является определение типа или логическое значение. Если ограничение не items определено, значение по умолчанию равно true.

Если значение является определением типа, то значение описывает схему, которая применяется ко всем элементам массива, индекс которого больше наибольшего prefixItems индекса ограничения. В следующем примере будет принято [1, true, 1] или [1, true, 1, 1] отклонено [1, true, "foo"]:

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

Вы можете использовать items без использования prefixItems. В следующем примере будет принято [1, 2] или [1] отклонено ["foo"]:

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

Если значение равно false, проверенный массив должен иметь ту же длину, что prefixItems и ограничение. В следующем примере будет принято [1, true], но отклонить [1, true, 1]и [1, true, false, "foo", "bar"].

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

Если значение равно true, элементы массива, индекс которого больше, чем самый большой индекс prefixItems ограничения, принимает любое значение. В следующих примерах будет принято [1, true][1, true, 1] и [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
}

Ограничение, допускаемое значение NULL

Ограничение, допускаемое значение NULL, можно использовать только с languageVersion 2.0. Он указывает, что значение может быть null или опущено. Пример см. в разделе "Свойства ".

Description

Вы можете добавить описание параметра, чтобы помочь пользователям шаблона понять, какое значение следует указать. При развертывании шаблона через портал текст, который вы указываете в описании, автоматически используется в качестве подсказки для этого параметра. Добавлять описание следует только в том случае, если текст содержит больше информации, чем можно понять из имени параметра.

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

Использование параметра

Чтобы сослаться на значение параметра, используйте функцию parameters. В следующем примере используется значение параметра для имени хранилища ключей.

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

Объекты в качестве параметров

Чтобы структурировать связанные друг с другом значения, их можно передать в виде объекта. Что не менее важно, этот подход сокращает число параметров в шаблоне.

В приведенном ниже примере показан параметр, который является объектом. Значение по умолчанию отражает ожидаемые свойства объекта. Эти свойства используются при определении развертываемого ресурса.

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

Образцы шаблонов

В приведенных ниже примерах демонстрируются сценарии использования параметров.

Template	Description
Использование параметров с функциями для определения значений по умолчанию	Демонстрирует, как можно применить функции шаблонов при определении значений по умолчанию для параметров. Шаблон не развертывает ресурсы. Он только создает значения параметров и возвращает их.
Объект параметров	Демонстрирует использование объекта в качестве параметра. Шаблон не развертывает ресурсы. Он только создает значения параметров и возвращает их.

Следующие шаги

Дополнительные сведения о доступных свойствах для параметров см. в статье Общие сведения о структуре и синтаксисе шаблонов ARM.
Дополнительные сведения о передаче значений параметров в виде файла см. в статье Создание файла параметров Resource Manager.
Рекомендации по созданию параметров см. в разделе Рекомендации — параметры.

Поделиться через