Definiciones de tipos en plantillas de ARM

2025-05-01

En este artículo se describe cómo crear y usar definiciones en la plantilla de Azure Resource Manager (plantilla de ARM). Al definir sus propios tipos, puede reutilizar estos tipos. Las definiciones de tipo solo se pueden usar con languageVersion 2.0.

Nota:

La versión actual de la extensión Herramientas de Azure Resource Manager para Visual Studio Code no reconoce las mejoras realizadas en languageVersion 2.0.

Sugerencia

Se recomienda Bicep porque ofrece las mismas funcionalidades que las plantillas de ARM y la sintaxis es más fácil de usar. Para más información, consulte Tipos de datos definidos por el usuario en Bicep.

Declaración mínima

Como mínimo, cada definición de tipo necesita un nombre y un type o .$ref

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

Valores permitidos

Puede definir valores permitidos para una definición de tipo. Los valores permitidos se proporcionan en una matriz. La implementación produce un error durante la validación si se pasa un valor para la definición de tipo que no es uno de los valores permitidos.

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

Restricciones de longitud

Puede especificar longitudes mínimas y máximas para las definiciones de tipo de cadena y matriz. Puede establecer una o las dos restricciones. Para las cadenas, la longitud indica el número de caracteres. Para las matrices, la longitud indica el número de elementos de la matriz.

En el ejemplo siguiente se declaran dos definiciones de tipo. Una definición de tipo es para un nombre de cuenta de almacenamiento que debe tener entre 3 y 24 caracteres. La otra definición de tipo es una matriz que debe tener de 1 a 5 elementos.

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

Restricciones de enteros

Puede establecer valores mínimos y máximos para las definiciones de tipo entero. Puede establecer una o las dos restricciones.

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

Restricciones de objeto

Propiedades

El valor de properties es un mapa donde el nombre de la propiedad está asociado a una definición de tipo >.

En el ejemplo siguiente se aceptaría {"foo": "string", "bar": 1}, pero rechazaría {"foo": "string", "bar": -1}, {"foo": "", "bar": 1} o cualquier objeto sin una propiedad foo o bar.

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

Todas las propiedades son necesarias a menos que la definición de tipo de la propiedad tenga la restricción "nullable": true . Para hacer que ambas propiedades del ejemplo anterior sean opcionales, quedaría así:

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

propiedades adicionales

El valor de additionalProperties es una definición de tipo o un valor booleano. Si no se define ninguna restricción additionalProperties, el valor predeterminado es true.

Si value es una definición de tipo, el valor describe el esquema que se aplica a todas las propiedades que no se mencionan en la restricción properties. En el ejemplo siguiente se aceptaría {"fizz": "buzz", "foo": "bar"} pero se rechazaría {"property": 1}.

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

Si el valor es false, no se pueden proporcionar propiedades más allá de las definidas en la restricción properties. En el ejemplo siguiente se aceptaría {"foo": "string", "bar": 1} pero se rechazaría {"foo": "string", "bar": 1, "fizz": "buzz"}.

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

Si el valor es true, cualquier propiedad no definida en la restricción properties no acepta ningún valor. En el ejemplo siguiente se aceptaría {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Discriminador

El valor discriminator define qué esquema se va a aplicar en función de una propiedad Discriminator. En el ejemplo siguiente se aceptaría {"type": "ints", "foo": 1, "bar": 2} o {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, pero se rechazaría {"type": "ints", "fizz": "buzz"}.

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

Restricciones de matriz

prefijoElementos

El valor de prefixItems es una matriz de definiciones de tipo. Cada definición de tipo en el valor es el esquema que se utilizará para validar el elemento de una matriz en el mismo índice. En el ejemplo siguiente se aceptaría [1, true] pero se rechazaría [1, "string"] o [1]:

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

Artículos

El valor de items es una definición de tipo o un valor booleano. Si no se define ninguna restricción items, el valor predeterminado es true.

Si el valor es una definición de tipo, el valor describe el esquema que se aplica a todos los elementos de la matriz cuyo índice es mayor que el índice más grande de la restricción prefixItems. En el ejemplo siguiente se aceptaría [1, true, 1] o [1, true, 1, 1] pero se rechazaría [1, true, "foo"]:

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

Puede usar items sin usar prefixItems. En el ejemplo siguiente se aceptaría [1, 2] o [1] pero se rechazaría ["foo"]:

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

Si el valor es false, la matriz validada debe tener exactamente la misma longitud que la restricción prefixItems. En el ejemplo siguiente se aceptaría [1, true] pero se rechazaría [1, true, 1] y [1, true, false, "foo", "bar"].

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

Si el valor es true, los elementos de la matriz cuyo índice es mayor que el índice más grande de la restricción prefixItems aceptan cualquier valor. Los ejemplos siguientes aceptarían [1, true], [1, true, 1] y [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
}

restricción que admite un valor NULL

La restricción de nulidad indica que el valor puede ser null o omitirse. Vea Propiedades para obtener un ejemplo.

Descripción

Puede agregar una descripción a una definición de tipo para ayudar a los usuarios de la plantilla a comprender el valor que se va a proporcionar.

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

Uso de la definición

Para hacer referencia a una definición de tipo, use la sintaxis siguiente:

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

En el ejemplo siguiente se muestra cómo hacer referencia a una definición de tipo a partir de parámetros y salidas:

{
  "$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')]"
    }
  }
}

Pasos siguientes

Para obtener información sobre las propiedades disponibles para las definiciones de tipos, consulte Descripción de la estructura y la sintaxis de las plantillas de ARM.