Parâmetros nos modelos do ARM

  • Artigo

Este artigo descreve como definir e utilizar parâmetros no modelo do Azure Resource Manager (modelo arm). Ao fornecer valores diferentes para parâmetros, pode reutilizar um modelo para diferentes ambientes.

Resource Manager resolve os valores dos parâmetros antes de iniciar as operações de implementação. Onde quer que o parâmetro seja utilizado no modelo, Resource Manager substitui-o pelo valor resolvido.

Cada parâmetro tem de 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 a serem utilizadas em definições, parâmetros e definições de saídas . Estas restrições incluem:

Nota

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

Dica

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

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

Para obter as melhores práticas de parâmetros, veja Parâmetros.

Declaração mínima

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

Quando implementa um modelo através do portal do Azure, os nomes dos parâmetros em maiúsculas e minúsculas de camelo são transformados em nomes separados pelo espaço. Por exemplo, demoString no exemplo seguinte é mostrado como Cadeia de Demonstração. Para obter mais informações, veja Utilizar um botão de implementação para implementar modelos a partir do repositório do GitHub e Implementar 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

Pode marcar parâmetros de cadeia ou objeto como seguros. O valor de um parâmetro seguro não é guardado no histórico de implementações e não é registado.

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

Valores permitidos

Pode definir valores permitidos para um parâmetro. Fornece os valores permitidos numa matriz. A implementação falha durante a validação se for transmitido um valor para o parâmetro que não é um dos valores permitidos.

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

Valor predefinido

Pode especificar um valor predefinido para um parâmetro. O valor predefinido é utilizado quando um valor não é fornecido durante a implementação.

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

Para especificar um valor predefinido juntamente com outras propriedades para o parâmetro, utilize a seguinte sintaxe.

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

Pode utilizar expressões com o valor predefinido. Não pode utilizar a função de referência ou nenhuma das funções de lista na secção parâmetros. Estas funções obtêm o estado de runtime de um recurso e não podem ser executadas antes da implementação quando os parâmetros são resolvidos.

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

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

Pode utilizar outro valor de parâmetro para criar um valor predefinido. O modelo seguinte constrói um nome de plano de anfitrião 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

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

O exemplo seguinte declara dois parâmetros. Um parâmetro destina-se a um nome de conta de armazenamento que tem de ter entre 3 e 24 carateres. O outro parâmetro é uma matriz que tem de ter entre 1 e 5 itens.

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

Restrições de números inteiros

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

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

Restrições de objetos

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

Propriedades

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

O exemplo seguinte aceitaria {"foo": "string", "bar": 1}, mas rejeitaria {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}ou qualquer objeto sem uma foo propriedade 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 do tipo da propriedade tenha a restrição "nulo": verdadeiro . Para tornar opcionais ambas as propriedades no exemplo anterior, teria o seguinte aspeto:

"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 não for definida nenhuma additionalProperties restrição, o valor predefinido é true.

Se valor for uma definição de tipo, o valor descreve o esquema aplicado a todas as propriedades não mencionadas na properties restrição. O exemplo seguinte 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, não poderão ser fornecidas propriedades para além das definidas na properties restrição. O exemplo seguinte 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 aceita qualquer valor. O exemplo seguinte aceitaria {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

discriminatório

O valor discriminator define o esquema a aplicar com base numa propriedade discriminatória. O exemplo seguinte 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 utilizadas 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 utilizado para validar o elemento de uma matriz no mesmo índice. O exemplo seguinte 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 não for definida nenhuma items restrição, o valor predefinido é true.

Se valor for uma definição de tipo, o valor descreve o esquema que é aplicado a todos os elementos da matriz cujo índice é maior do que o maior índice da prefixItems restrição. O exemplo seguinte 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"]
  }
}

Pode utilizar items sem utilizar prefixItems. O exemplo seguinte aceitaria [1, 2] ou [1] rejeitaria ["foo"]:

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

Se o valor for false, a matriz validada tem de ter exatamente o mesmo comprimento que a prefixItems restrição. O exemplo seguinte 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 verdadeiro, os elementos da matriz cujo índice é maior do que o maior índice da prefixItems restrição aceitam qualquer valor. Os exemplos seguintes aceitariam [1, true]e [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
}

Restrição anulável

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

Description

Pode adicionar uma descrição a um parâmetro para ajudar os utilizadores do seu modelo a compreender o valor a fornecer. Ao implementar o modelo através do portal, o texto que fornecer na descrição é automaticamente utilizado como uma sugestão para esse parâmetro. Adicione apenas uma descrição quando o texto fornecer mais informações do que as que podem ser inferidas 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"
  }
}

Utilizar parâmetro

Para referenciar o valor de um parâmetro, utilize a função parameters . O exemplo seguinte utiliza 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

Pode organizar valores relacionados ao transmiti-los como um objeto. Esta abordagem também reduz o número de parâmetros no modelo.

O exemplo seguinte mostra um parâmetro que é um objeto. O valor predefinido mostra as propriedades esperadas para o objeto. Essas propriedades são utilizadas ao definir o recurso a implementar.

{
  "$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 seguintes demonstram cenários de utilização de parâmetros.

Modelo Description
parâmetros com funções para valores predefinidos Demonstra como utilizar funções de modelo ao definir valores predefinidos para parâmetros. O modelo não implementa recursos. Constrói valores de parâmetros e devolve esses valores.
objeto de parâmetro Demonstra a utilização de um objeto para um parâmetro. O modelo não implementa recursos. Constrói valores de parâmetros e devolve esses valores.

Passos seguintes