Parâmetros de modelos do ARM

  • Artigo

Este artigo descreverá de que modo definir e usar parâmetros no modelo do ARM (modelo do Azure Resource Manager). Ao fornecer valores diferentes para os parâmetros, é possível reutilizar um modelo em ambientes diferentes.

O Resource Manager resolverá os valores do parâmetro antes de iniciar as operações de implantação. Sempre que o parâmetro for usado no modelo, o Resource Manager o substituirá pelo valor resolvido.

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

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

Observação

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

Dica

Recomendamos o Bicep porque ele oferece as mesmas funcionalidades que os modelos do ARM e a sintaxe é mais fácil de usar. Para saber mais, confira parâmetros.

Você está limitado a 256 parâmetros em um modelo. Para obter mais informações, confira Limites de modelo.

Para obter as práticas recomendadas sobre parâmetro, confira Parâmetros.

Declaração mínima

Cada parâmetro precisa ter no mínimo um nome e um tipo.

Ao implantar um modelo por meio do portal do Azure, os nomes dos parâmetros com maiúsculas e minúsculas são transformados em nomes separados por espaços. O demoString será mostrado no exemplo a seguir como Cadeia de Caracteres de Demonstração. Para obter mais informações, confira como Usar um botão de implantação para implantar modelos do repositório GitHub e Implantar recursos com modelos do ARM e o portal do Azure.

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

Parâmetros seguros

É possível marcar os parâmetros de cadeia de caracteres ou de objeto como seguros. O valor de um parâmetro seguro não é salvo no histórico de implantação nem registrado em log.

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

Valores permitidos

É possível definir os 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"
    ]
  }
}

Valor padrão

É possível 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 seguinte sintaxe.

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

É possível usar as expressões com o valor padrão. Não é possível usar a função de referência nem outras funções de lista na seção de parâmetros. Essas funções obtêm o estado de runtime de um recurso. Além disso, quando os parâmetros são resolvidos, elas não podem ser executadas antes da implantação.

Não é permitido usar expressões 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')]"
  }
}

Restrições de comprimento

É possível especificar os comprimentos mínimos e máximos para os parâmetros de cadeia de caracteres e matriz. É possível 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 inteiro

É possível definir os valores mínimos e máximos para parâmetros inteiros. É possível definir uma ou ambas as restrições.

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

As restrições do 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 properties é um mapa de nome da propriedade =>definição de tipo.

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

"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 "anulável": true. Tornar as duas propriedades no exemplo anterior opcionais, seria semelhante a:

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

additionalProperties

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

Se o valor for uma definição de tipo, o valor descreverá o esquema aplicado a todas as propriedades não mencionadas na restrição properties. 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 daquelas definidas na restrição properties poderá 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 restrição properties aceitará 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 discriminatória. O exemplo a seguir aceitaria {"type": "ints", "foo": 1, "bar": 2} ou {"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 objeto 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 items é uma definição de tipo ou um booliano. Se nenhuma restrição items for definida, o valor padrão será true.

Se o valor for uma definição de tipo, o valor descreverá o esquema aplicado a todos os elementos da matriz cujo índice é maior que o maior índice da restrição prefixItems. O exemplo a seguir aceitaria [1, true, 1] ou [1, true, 1, 1], mas 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 prefixItems. O exemplo a seguir aceitaria [1, 2] ou [1] mas rejeitaria ["foo"]:

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

Se o valor for false, a matriz validada deverá ter exatamente o mesmo comprimento que a restrição prefixItems. 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 que o maior índice da restrição prefixItems aceitam qualquer valor. Todos 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.

Descrição

É possível adicionar uma descrição a um parâmetro a fim de ajudar os usuários do modelo a entender qual valor fornecer. Ao implantar o modelo por meio do portal, o texto que você fornece na descrição é usado automaticamente como uma dica para esse parâmetro. Adicione uma descrição somente quando o texto fornecer mais informações do que podem ser deduzidas 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"
  }
}

Usar parâmetro

Para fazer referência ao valor de um parâmetro, use a função parâmetros. O exemplo a seguir usará o valor do parâmetro em um nome do 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

É possível organizar valores relacionados aprovando-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 os cenários para o uso de parâmetros.

Modelo Descrição
parâmetros com funções de valores padrão Demonstra como usar funções de modelo ao definir valores padrão para parâmetros. O modelo não implanta todos os recursos. Ele cria valores de parâmetro e retorna os valores.
objeto de parâmetro Demonstra como usar um objeto para um parâmetro. O modelo não implanta todos os recursos. Ele cria valores de parâmetro e retorna os valores.

Próximas etapas