Compartilhar via

Parâmetros de modelos do ARM

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:

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 parâmetros de cadeia de caracteres ou objeto como seguros. O valor de um parâmetro seguro não será salvo no histórico de implantação nem registrado em log.

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

Valores permitidos

É possível definir valores permitidos em um parâmetro. Forneça os valores permitidos em matriz. Caso um valor não permitido seja aprovado para o parâmetro, haverá falha na implantação durante a validação.

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

Valor padrão

É possível especificar o valor padrão de um parâmetro. O valor padrão é usado quando um valor não é fornecido durante a implantação.

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

Use a sintaxe a seguir para especificar o valor padrão, juntamente com outras propriedades do parâmetro.

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

É possível usar 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 criará o nome do plano de host 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 fazer referência a uma variável como o valor padrão.

Restrições de comprimento

É possível especificar comprimentos mínimos e máximos para parâmetros de cadeia de caracteres e matriz. É possível definir uma restrição ou as duas. Nas cadeias de caracteres, o comprimento indica o número de caracteres. Nas matrizes, o comprimento indica o número de itens da matriz.

O exemplo a seguir vai declarar dois parâmetros. Um parâmetro é usado para obter o nome da conta de armazenamento, que deverá ter de 3 a 24 caracteres. O outro parâmetro é a matriz, que deverá ter de 1 a 5 itens.

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

Restrições do inteiro

É possível definir valores mínimos e máximos para parâmetros do inteiro. É possível definir uma restrição ou as duas.

"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 mostrará um parâmetro como objeto. O valor padrão mostrará as propriedades esperadas do objeto. Essas propriedades são usadas ao definir qual recurso implantar.

{
  "$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 demonstrarão em que cenário usar os 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

  • Last updated on