Parâmetros em modelos ARM

  • Artigo

Este artigo descreve como definir e usar parâmetros em seu modelo do Azure Resource Manager (modelo ARM). Ao fornecer valores diferentes para parâmetros, você pode reutilizar um modelo para ambientes diferentes.

O Resource Manager resolve valores de parâmetros antes de iniciar as operações de implantação. Sempre que o parâmetro é usado no modelo, o Gerenciador de Recursos o substitui pelo valor resolvido.

Cada parâmetro deve ser definido como um dos tipos de dados.

Além de minValue, maxValue, minLength, maxLength e allowedValues, languageVersion 2.0 introduz algumas restrições de validação de tipo agregado para serem usadas em definições, parâmetros e definições de saída. Essas restrições incluem:

Nota

A versão atual da extensão Azure Resource Manager Tools para Visual Studio Code não reconhece os aprimoramentos feitos no languageVersion 2.0.

Gorjeta

Recomendamos o Bicep porque ele oferece os mesmos recursos que os modelos ARM e a sintaxe é mais fácil de usar. Para saber mais, consulte parâmetros.

Está limitado a 256 parâmetros num modelo. Para obter mais informações, consulte Limites de modelo.

Para obter as práticas recomendadas de parâmetros, consulte Parâmetros.

Declaração mínima

No mínimo, cada parâmetro precisa de um nome e tipo.

Quando você implanta um modelo por meio do portal do Azure, os nomes de parâmetros com caixa camelo são transformados em nomes separados por espaço. Por exemplo, demoString no exemplo a seguir é mostrado como Demo String. Para obter mais informações, consulte Usar um botão de implantação para implantar modelos do repositório GitHub e Implantar recursos com modelos ARM e portal do Azure.

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

Parâmetros seguros

Você pode marcar parâmetros de cadeia de caracteres ou objeto como seguros. O valor de um parâmetro seguro não é salvo no histórico de implantação e não é registrado.

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

Valores permitidos

Você pode definir valores permitidos para um parâmetro. Você fornece os valores permitidos em uma matriz. A implantação falhará durante a validação se um valor for passado para o parâmetro que não é um dos valores permitidos.

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

Default value

Você pode especificar um valor padrão para um parâmetro. O valor padrão é usado quando um valor não é fornecido durante a implantação.

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

Para especificar um valor padrão junto com outras propriedades para o parâmetro, use a sintaxe a seguir.

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

Você pode usar expressões com o valor padrão. Não é possível usar a função de referência ou qualquer uma das funções de lista na seção de parâmetros. Essas funções obtêm o estado de tempo de execução de um recurso e não podem ser executadas antes da implantação quando os parâmetros são resolvidos.

As expressões não são permitidas com outras propriedades de parâmetro.

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

Você pode usar outro valor de parâmetro para criar um valor padrão. O modelo a seguir constrói um nome de plano de host a partir do nome do site.

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

No entanto, não é possível fazer referência a uma variável como o valor padrão.

Restrições de comprimento

Você pode especificar comprimentos mínimos e máximos para parâmetros de cadeia de caracteres e matriz. Você pode definir uma ou ambas as restrições. Para cadeias de caracteres, o comprimento indica o número de caracteres. Para matrizes, o comprimento indica o número de itens na matriz.

O exemplo a seguir declara dois parâmetros. Um parâmetro é para um nome de conta de armazenamento que deve ter de 3 a 24 caracteres. O outro parâmetro é uma matriz que deve ter de 1 a 5 itens.

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

Restrições de números inteiros

Você pode definir valores mínimos e máximos para parâmetros inteiros. Você pode definir uma ou ambas as restrições.

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

Restrições de objeto

As restrições de objeto só são permitidas em objetos e só podem ser usadas com languageVersion 2.0.

Propriedades

O valor de é um mapa de nome de propriedade => definição de properties tipo.

O exemplo a seguir aceitaria {"foo": "string", "bar": 1}, mas rejeitaria {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}ou qualquer objeto sem uma foo ou bar propriedade.

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

Todas as propriedades são necessárias, a menos que a definição de tipo da propriedade tenha a restrição "nullable": true. Para tornar ambas as propriedades no exemplo anterior opcionais, seria assim:

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

additionalProperties

O valor de é uma definição de additionalProperties tipo ou um valor booleano. Se nenhuma additionalProperties restrição for definida, o valor padrão será true.

Se value for uma definição de tipo, o valor descreverá o esquema que é aplicado a todas as propriedades não mencionadas na properties restrição. O exemplo a seguir aceitaria {"fizz": "buzz", "foo": "bar"} , mas rejeitaria {"property": 1}.

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

Se o valor for false, nenhuma propriedade além das properties definidas na restrição pode ser fornecida. O exemplo a seguir aceitaria {"foo": "string", "bar": 1}, mas rejeitaria {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Se o valor for true, qualquer propriedade não definida na properties restrição aceita qualquer valor. O exemplo a seguir aceitaria {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

discriminador

O valor discriminator define qual esquema aplicar com base em uma propriedade discriminadora. O exemplo a seguir aceitaria ou {"type": "ints", "foo": 1, "bar": 2} {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, mas rejeitaria {"type": "ints", "fizz": "buzz"}.

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

Restrições de matriz

As restrições de matriz só são permitidas em matrizes e só podem ser usadas com languageVersion 2.0.

prefixItems

O valor de prefixItems é uma matriz de definições de tipo. Cada definição de tipo no valor é o esquema a ser usado para validar o elemento de uma matriz no mesmo índice. O exemplo a seguir aceitaria [1, true] , mas rejeitaria [1, "string"] ou [1]:

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

itens

O valor de é uma definição de items tipo ou um booleano. Se nenhuma items restrição for definida, o valor padrão será true.

Se value for uma definição de tipo, o valor descreverá o esquema que é aplicado a todos os elementos da matriz cujo índice é maior do que o maior índice da prefixItems restrição. O exemplo a seguir aceitaria [1, true, 1] ou [1, true, 1, 1] rejeitaria [1, true, "foo"]:

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

Você pode usar items sem usar prefixItemso . O exemplo a seguir aceitaria [1, 2] ou [1] rejeitaria ["foo"]:

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

Se o valor for false, a matriz validada deve ter exatamente o mesmo comprimento que a prefixItems restrição. O exemplo a seguir aceitaria [1, true], mas rejeitaria [1, true, 1], e [1, true, false, "foo", "bar"].

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

Se o valor for true, os elementos da matriz cujo índice é maior do que o maior índice da prefixItems restrição aceitam qualquer valor. Os exemplos a seguir aceitariam [1, true], [1, true, 1] e [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
}

Restrição anulável

A restrição anulável só pode ser usada com languageVersion 2.0. Indica que o valor pode ser null ou omitido. Consulte Propriedades para obter um exemplo.

Description

Você pode adicionar uma descrição a um parâmetro para ajudar os usuários do seu modelo a entender o valor a ser fornecido. Ao implantar o modelo através do portal, o texto fornecido na descrição é usado automaticamente como uma dica para esse parâmetro. Adicione apenas uma descrição quando o texto fornecer mais informações do que pode ser inferido a partir do nome do parâmetro.

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

Parâmetro de utilização

Para fazer referência ao valor de um parâmetro, use a função parameters . O exemplo a seguir usa um valor de parâmetro para um nome de cofre de chaves.

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

Objetos como parâmetros

Você pode organizar valores relacionados passando-os como um objeto. Essa abordagem também reduz o número de parâmetros no modelo.

O exemplo a seguir mostra um parâmetro que é um objeto. O valor padrão mostra as propriedades esperadas para o objeto. Essas propriedades são usadas ao definir o recurso a ser implantado.

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

Modelos de exemplo

Os exemplos a seguir demonstram cenários para o uso de parâmetros.

Modelo Description
parâmetros com funções para valores padrão Demonstra como usar funções de modelo ao definir valores padrão para parâmetros. O modelo não implanta nenhum recurso. Ele constrói valores de parâmetro e retorna esses valores.
objeto de parâmetro Demonstra o uso de um objeto para um parâmetro. O modelo não implanta nenhum recurso. Ele constrói valores de parâmetro e retorna esses valores.

Próximos passos