Definiciones de tipos en plantillas de ARM

Artículo
09/04/2023

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. Se produce un error en la implementación 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 definiciones de tipos de cadenas y matrices. 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.

El siguiente ejemplo declara 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 entre 1 y 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 definiciones de tipos enteros. 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 de nombre de propiedad = > 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 obligatorias a menos que la definición del tipo de 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
      }
    }
  }
}

additionalProperties

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
  }
}

discriminator

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

prefixItems

El valor de es prefixItems una matriz de definiciones de tipos. 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"
  }
}

items

El valor de items es una definición de tipo o un 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 que acepta valores NULL indica que el valor puede ser null u 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 su plantilla a comprender el valor que deben proporcionar.

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

Usar 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 Comprender la estructura y la sintaxis de las plantillas ARM.