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

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

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

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

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

Примечание

Текущий выпуск расширения Azure Resource Manager Tools для 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"
    ]
  }
}

Значение по умолчанию

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

"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": "string", "bar": -1}, {"foo": "", "bar": 1}или любой foo объект без свойства или bar .

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

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

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

additionalProperties

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

Если value является определением типа, значение описывает схему, которая применяется ко всем свойствам, не упомянутым в ограничении 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

Значение 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.

prefixItems

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

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

items

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

Если value является определением типа, значение описывает схему, применяемую ко всем элементам массива, индекс которого больше самого большого 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 или опущено. Пример см. в разделе Свойства .

Описание

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

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

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

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

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

Дальнейшие действия