Escrever definições em modelos do ARM

Artigo
09/26/2024

Este artigo descreve como criar e utilizar definições no modelo do Azure Resource Manager (modelo arm). Ao definir os seus próprios tipos, pode reutilizar estes tipos. As definições de tipo só podem ser utilizadas com languageVersion 2.0.

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

Declaração mínima

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

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

Valores permitidos

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

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

Restrições de comprimento

Pode especificar comprimentos mínimos e máximos para definições de tipo 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 duas definições de tipo. Uma definição de tipo é para um nome de conta de armazenamento que tem de ter entre 3 e 24 carateres. A outra definição de tipo é uma matriz que tem de ter entre 1 e 5 itens.

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

Restrições de números inteiros

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

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

Restrições de objetos

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 .

"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 do tipo da propriedade tenha a restrição "nulo": verdadeiro . Para tornar opcionais ambas as propriedades no exemplo anterior, teria o seguinte aspeto:

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

"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, 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"}.

"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 aceita qualquer valor. O exemplo seguinte aceitaria {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

"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 utilizado para validar o elemento de uma matriz no mesmo índice. O exemplo seguinte 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 é 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"]:

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

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

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

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

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

"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. Veja Propriedades para obter um exemplo.

Description

Pode adicionar uma descrição a uma definição de tipo para ajudar os utilizadores do seu modelo a compreender o valor a fornecer.

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

Utilizar a definição

Para referenciar uma definição de tipo, utilize a seguinte sintaxe:

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

O exemplo seguinte mostra como referenciar uma definição de tipo a partir de parâmetros 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')]"
    }
  }
}

Passos seguintes

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

Partilhar via