Esquema de manifiesto de importación de Azure Device Update for IoT Hub

Artículo
01/13/2025

Al importar una actualización en Azure Device Update for Iot Hub, también envía un archivo de manifiesto de importación JSON asociado que define información importante sobre la actualización. En este artículo se describe el esquema usado para crear el archivo de manifiesto de importación JSON.

Para más información sobre los conceptos del manifiesto de importación y la estructura de archivos, consulte Manifiesto de importación de Azure Device Update for IoT Hub. Para obtener información sobre cómo crear el archivo, consulte Preparación de una actualización para la importación en Device Update for IoT Hub.

Esquema

El esquema JSON del manifiesto de importación se hospeda en SchemaStore.org y consta de las siguientes propiedades. No se permite ninguna otra propiedad.

Propiedad	Tipo	Descripción	Requerido
$schema	`string`	Referencia de esquema de JSON.	No
updateId	`updateId`	Identificador de actualización único.	Sí
description	`string`	Descripción de actualización opcional. Longitud máxima: 512 caracteres.	No
compatibility	`compatibility`	Lista de conjuntos de propiedades de dispositivo con los que es compatible esta actualización.	Sí
instructions	`instructions`	Instrucciones de instalación de la actualización.	Sí
files	`file` `[0-10]`	Lista de archivos de carga de actualización. La suma los tamaños de todos los archivos no puede superar los 2 GB. Puede estar vacío o ser null si todos los pasos de instrucción son pasos de referencia.	No
manifestVersion	`string`	Versión del esquema de manifiesto de importación. Debe ser 5.0.	Sí
createdDateTime	`string`	Importe la fecha y hora de creación del manifiesto en formato ISO 8601, por ejemplo `"2020-10-02T22:18:04.9446744Z"`.	Sí

Actualizar objeto

El objeto updateID es un identificador único para cada actualización.

Propiedad	Tipo	Descripción	Requerido
proveedor	`string`	Entidad que está creando la actualización o que es directamente responsable de ella. El proveedor puede ser un nombre de empresa. Patrón: `^[a-zA-Z0-9.-]+$` Longitud máxima: 64 caracteres	Sí
name	`string`	Identificador de una clase de actualización. El nombre puede ser una clase de dispositivo o un nombre de modelo. Patrón: `^[a-zA-Z0-9.-]+$` Longitud máxima: 64 caracteres	Sí
version	`string`	Números de versión numérica separados por puntos, de dos a cuatro partes. Cada parte debe ser un número entre 0 y 2147483647 y se descartan los ceros iniciales. Patrón: `^\d+(?:\.\d+)+$` Ejemplos: `"1.0"`, `"2021.11.8"`	Sí

No se permite ninguna otra propiedad.

Por ejemplo:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

Objeto de compatibilidad

El objetocompatibility describe entre 1 y 5 propiedades de un dispositivo con el que esta actualización es compatible. Cada propiedad es un par de nombre-valor de tipostring. El nombre debe tener entre 1 y 32 caracteres y el valor debe tener entre 1 y 64 caracteres. No se puede usar el mismo conjunto exacto de propiedades de compatibilidad con más de una combinación de proveedor de actualización y nombre.

Por ejemplo:

{
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ]
}

Objeto de instrucciones

El objeto instructions proporciona las instrucciones de instalación de la actualización. El objeto de instrucciones contiene una lista de steps que se va a realizar. No se permite ninguna otra propiedad.

Los pasos pueden ser código para ejecutar o punteros a otras actualizaciones. Un objeto paso tiene como valor predeterminado inline si no se proporciona ningún valor type.

Propiedad	Tipo	Descripción	Requerido
steps	`array[1-10]`	Cada elemento de la matriz `steps` debe ser un objeto de paso insertado o un objeto de paso de referencia.	Sí

Por ejemplo:

{
  "instructions": {
    "steps": [
      {
        "type": "inline",
        ...
      },
      {
        "type": "reference",
        ...
      }
    ]
  }
}

Objeto de paso insertado

Un objeto de pasoinline es un paso de instrucción de instalación que realiza la ejecución de código.

Propiedad	Tipo	Descripción	Obligatorio
type	`string`	Tipo de paso de instrucción que realiza la ejecución de código. Debe ser `inline`. El valor predeterminado es `inline` si no se proporciona ningún valor.	No
description	`string`	Descripción del paso de instrucción opcional. Longitud máxima: 64 caracteres.	No
handler	`string`	Identidad del controlador en el dispositivo que puede ejecutar este paso. Patrón: `^\S+/\S+:\d{1,5}$` Longitud mínima: cinco caracteres Longitud máxima: 32 caracteres Ejemplos: `microsoft/script:1`, `microsoft/swupdate:2`, `microsoft/apt:1`	Sí
files	`string` `[1-10]`	Nombres de archivos de actualización definidos como objetos de archivo que el agente pasará al controlador. Cada longitud de elemento debe tener entre 1 y 255 caracteres.	Sí
handlerProperties	`inlineStepHandlerProperties`	Objetos JSON que el agente pasa al controlador como argumentos.	No

No se permite ninguna otra propiedad.

Por ejemplo:

{
  "steps": [
    {
      "description": "pre-install script",
      "handler": "microsoft/script:1",
      "handlerProperties": {
        "arguments": "--pre-install"
      },
      "files": [
        "configure.sh"
      ]
    }
  ]
}

Objeto de paso de referencia

Un objeto de paso reference es un paso de instrucción de instalación para instalar otra actualización.

Propiedad	Tipo	Descripción	Obligatorio
type	`referenceStepType`	Tipo de paso de instrucción que instala otra actualización. Debe ser `reference`.	Sí
description	`stepDescription`	Descripción del paso de instrucción opcional. Longitud máxima: 64 caracteres.	No
updateId	`updateId`	Identificador de actualización único.	Sí

No se permite ninguna otra propiedad.

Por ejemplo:

{
  "steps": [
    {
      "type": "reference",
      "updateId": {
        "provider": "Contoso",
        "name": "Toaster.HeatingElement",
        "version": "1.0"
      }
    }
  ]
}

Objeto de archivos

Cada objetofiles es un archivo de carga de actualización, como un archivo binario, firmware o script, que debe ser único dentro de una actualización.

Propiedad	Tipo	Descripción	Requerido
filename	`string`	Nombre de archivo de carga de Update. Longitud máxima: 255 caracteres	Sí
sizeInBytes	`number`	Tamaño de archivo en número de bytes. Tamaño máximo: 2147483648 bytes	Sí
hashes	`fileHashes`	Hashes de archivo codificados en Base64 con el nombre del algoritmo como clave. Se debe especificar al menos el algoritmo SHA-256 y se pueden especificar algoritmos adicionales si es admitido por el agente. Consulte Objeto Hashes para obtener más información sobre cómo calcular el hash.	Sí
relatedFiles	`relatedFile[0-4]`	Colección de archivos relacionados con uno o varios archivos de carga principal. Para obtener más información, vea objeto relatedFiles.	No
downloadHandler	`downloadHandler`	Especifica cómo procesar los archivos relacionados.	Sí, si usa `relatedFiles`. Para obtener más información, vea objeto downloadHandler.

No se permite ninguna otra propiedad.

Por ejemplo:

{
  "files": [
    {  
      "fileName": "full-image-file-name",
      "sizeInBytes": 12345,
      "hashes": {...},
      "relatedFiles": [
        {
          "fileName": "delta-from-v1-file-name",
          "sizeInBytes": 1234,
          "hashes": {
            "SHA256": "delta-from-v1-file-hash"
          },
          "properties": {...}
        }  
      ],
      "downloadHandler": {
        "id": "microsoft/delta:1"
        }
    }
  ]
}

Objeto Hashes

El objetohashes contiene hashes de archivo codificados en base64 con los nombres de algoritmo como claves. Se debe especificar al menos el algoritmo SHA-256 y se puede especificar otro algoritmo si es compatible con el agente. Para obtener un ejemplo de cómo calcular el hash correctamente, consulte la función Get-AduFileHashes en el script AduUpdate.psm1.

Propiedad	Tipo	Descripción	Requerido
sha256	`string`	Valor hash de archivo codificado en Base64 mediante el algoritmo SHA-256.	Sí

Se permiten otras propiedades.

Por ejemplo:

{
  "hashes": {
    "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
  }
}

relatedFiles (objeto)

El objeto relatedFiles contiene una colección de archivos relacionados con uno o varios archivos de carga principal. Para más información, consulte Uso de la característica de archivos relacionados para hacer referencia a varios archivos de actualización.

Propiedad	Tipo	Descripción	Requerido
filename	`string`	Lista de archivos relacionados asociados a un archivo de carga principal.	Sí
sizeInBytes	`number`	Tamaño de archivo en número de bytes. Tamaño máximo: 2147483648 bytes.	Sí
hashes	`fileHashes`	Hashes de archivo codificados en Base64 con el nombre del algoritmo como clave. Para obtener más información, vea Objeto Hashes.	Sí
properties	`relatedFilesProperties` `[0-5]`	Límite de cinco pares clave-valor, donde la clave está limitada a 64 caracteres ASCII y el valor es JObject con hasta 256 caracteres ASCII.	No

Se permiten otras propiedades.

Por ejemplo:

"relatedFiles": [
  {
    "filename": "in1_in2_deltaupdate.dat",
    "sizeInBytes": 102910752,
    "hashes": {
      "sha256": "2MIldV8LkdKenjJasgTHuYi+apgtNQ9FeL2xsV3ikHY="
    },
    "properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "YmFYwnEUddq2nZsBAn5v7gCRKdHx+TUntMz5tLwU+24="
    }
  }
],

downloadHandler (objeto)

El objeto downloadHandler especifica cómo procesar los archivos relacionados.

Propiedad	Tipo	Descripción	Requerido
id	`string`	Identificador de `downloadHandler`. Límite de 64 caracteres ASCII.	Sí, si usa `relatedFiles`

No se permite ninguna otra propiedad.

Por ejemplo:

"downloadHandler": {
  "id": "microsoft/delta:1"
}

Compartir a través de

Esquema de manifiesto de importación de Azure Device Update for IoT Hub

Esquema

Actualizar objeto

Objeto de compatibilidad

Objeto de instrucciones

Objeto de paso insertado

Objeto de paso de referencia

Objeto de archivos

Objeto Hashes

relatedFiles (objeto)

downloadHandler (objeto)

Comentarios

Recursos adicionales

Compartir a través de

Esquema de manifiesto de importación de Azure Device Update for IoT Hub

Esquema

Actualizar objeto

Objeto de compatibilidad

Objeto de instrucciones

Objeto de paso insertado

Objeto de paso de referencia

Objeto de archivos

Objeto Hashes

relatedFiles (objeto)

downloadHandler (objeto)

Contenido relacionado

Comentarios

Recursos adicionales