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.

O limite de parâmetros em um modelo é 256. 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')]"
  }
}

No entanto, você não pode referenciar uma variável como o valor padrão.

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

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