Definições de tipo em modelos do ARM

Artigo
09/03/2023

Este artigo descreverá de que modo usar e criar definições de uso no seu modelo do ARM (modelo do Azure Resource Manager). Ao definir seus próprios tipos, você pode reutilizar esses tipos. As definições de tipo só podem ser usadas com languageVersion 2.0.

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 Tipos de dados definidos pelo usuário no Bicep.

Declaração mínima

No mínimo, cada definição de tipo precisa de um nome e de um type ou um $ref.

"definitions": {
  "demoStringType": {
    "type": "string"
  },
  "demoIntType": {
    "type": "int"
  },
  "demoBoolType": {
    "type": "bool"
  },
  "demoObjectType": {
    "type": "object"
  },
  "demoArrayType": {
    "type": "array"
  }
}

Valores permitidos

É possível definir valores permitidos em um definição de tipo. Você fornece os valores permitidos em uma matriz. Caso um valor não permitido seja aprovado para o definição de tipo, haverá falha na implantação durante a validação.

"definitions": {
  "demoEnumType": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

Restrições de comprimento

É possível especificar comprimentos mínimos e máximos para definições de tipo 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 vai declarar duas definições de tipo. Uma definição de tipo é usada para obter o nome da conta de armazenamento, que deverá ter de 3 a 24 caracteres. A outra definição de tipo é a matriz, que deverá ter de 1 a 5 itens.

"definitions": {
  "storageAccountNameType": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNameType": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

Restrições de inteiro

É possível definir valores mínimos e máximos para definições de tipo do inteiro. É possível definir uma ou ambas as restrições.

"definitions": {
  "monthType": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

Restrições do objeto

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.

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
},
"parameters": {
  "objectParameter": {
    "$ref": "#/definitions/objectDefinition",
  }
}

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:

"definitions": {
  "objectDefinition": {
    "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}.

"definitions": {
  "dictionaryDefinition": {
    "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"}.

"definitions": {
  "dictionaryDefinition": {
    "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"}.

"definitions": {
  "dictionaryDefinition": {
    "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"}.

"definitions": {
  "taggedUnionDefinition": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

Restrições de matriz

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]:

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ]
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

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"]:

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" }
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

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

"definitions": {
  "intArrayDefinition": {
    "type": "array",
    "items": { "type": "int" }
  }
},
"parameters": {
  "intArrayParameter": {
    "$ref": "#/definitions/intArrayDefinition"
  }
}

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"].

"definitions": {
  "tupleDefinition": {
    "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"].

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

restrição anulável

A restrição anulável 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 definição de tipo para ajudar os usuários do modelo a entender qual valor fornecer.

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

Usar definição

Para fazer referência a uma definição de tipo, use a seguinte sintaxe:

"$ref": "#/definitions/<definition-name>"

O exemplo a seguir mostra como referenciar uma definição de tipo e saídas:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "languageVersion": "2.0",

  "definitions": {
    "naturalNumber": {
      "type": "int",
      "minValue": 1
    }
  },
  "parameters": {
    "numberParam": {
      "$ref": "#/definitions/naturalNumber",
      "defaultValue": 0
    }
  },
  "resources": {},
  "outputs": {
    "output1": {
      "$ref": "#/definitions/naturalNumber",
      "value": "[parameters('numberParam')]"
    }
  }
}

Próximas etapas

Para saber mais sobre as propriedades disponíveis para definições de tipo, veja Entender a estrutura e a sintaxe de modelos do ARM.