Importación de actualizaciones a Device Update para IoT Hub: esquema y otra información

Artículo
03/22/2023

Si quiere importar una actualización a Device Update para IoT Hub, asegúrese de revisar primero los conceptos y la guía paso a paso. Si está interesado en los detalles del esquema del manifiesto de importación propiamente dicho, continúe leyendo.

El esquema JSON del manifiesto de importación se hospeda en SchemaStore.org.

Schema

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 de todos los tamaños de archivo 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`	El manifiesto de importación de fecha y hora se creó en formato ISO 8601. Ejemplo: `"2020-10-02T22:18:04.9446744Z"`	Sí

No se permiten propiedades adicionales.

Objeto updateId

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. 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. 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 descartarán los ceros iniciales. Patrón: `^\d+(?:\.\d+)+$` Ejemplos: `"1.0"`, `"2021.11.8"`	Sí

No se permiten propiedades adicionales.

Por ejemplo:

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

Objeto compatibility

El objeto compatibility describe las propiedades de un dispositivo con el que esta actualización es compatible.

Tipo: object
Propiedades mínimas: 1
Propiedades máximas: 5

Cada propiedad es un par nombre-valor de tipo cadena.

Longitud mínima del nombre de propiedad: 1
Longitud máxima del nombre de propiedad: 32
Longitud mínima del valor de propiedad: 1
Longitud máxima del valor de propiedad: 64

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 instructions

El objeto instructions proporciona las instrucciones de instalación de la actualización. El objeto instructions contiene una lista de los pasos que se van a realizar. Los pasos pueden ser código para ejecutar o un puntero a otra actualización.

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

No se permiten propiedades adicionales.

Por ejemplo:

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

Objeto inlineStep

Un objeto de paso inline 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: 5 caracteres Longitud máxima: 32 caracteres Ejemplos: `microsoft/script:1`, `microsoft/swupdate:1`, `microsoft/apt:1`	Sí
files	`string` `[1-10]`	Nombres de archivos de actualización definidos como objetos file que el agente pasará al controlador. Cada elemento de la matriz debe tener una longitud entre 1 y 255 caracteres.	Sí
handlerProperties	`inlineStepHandlerProperties`	Objeto JSON que el agente pasará al controlador como argumentos.	No

No se permiten propiedades adicionales.

Por ejemplo:

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

Objeto referenceStep

Un objeto de paso reference es un paso de instrucción de instalación que instala 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 permiten propiedades adicionales.

Por ejemplo:

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

Objeto file

Un objeto file es un archivo de carga de actualización, por ejemplo, binario, firmware, script, etc. Cada objeto file 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 puede especificar un algoritmo adicional si es compatible con el agente. Consulte a continuación los detalles sobre cómo calcular el hash.	Sí
relatedFiles	`relatedFile[0-4]`	Colección de archivos relacionados con uno o varios de los archivos de carga principales.	No
downloadHandler	`downloadHandler`	Especifica cómo procesar los archivos relacionados.	Sí, si solo si usa relatedFiles.

No se permiten propiedades adicionales.

Por ejemplo:

{
  "files": [
    {
      "filename": "configure.sh",
      "sizeInBytes": 7558,
      "hashes": {...}
    }
  ]
}

Objeto 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 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 propiedades adicionales.

Por ejemplo:

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

relatedFiles (objeto)

Colección de archivos relacionados con uno o varios de los archivos de carga principales.

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. Se debe especificar al menos el algoritmo SHA-256 y se puede especificar un algoritmo adicional si es compatible con el agente. Consulte a continuación los detalles sobre cómo calcular el hash.	Sí
properties	`relatedFilesProperties` `[0-5]`	Límite de 5 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 propiedades adicionales.

Por ejemplo:

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

Para más información, consulte Uso de la característica de archivos relacionados para hacer referencia a varios archivos de actualización.

downloadHandler (objeto)

Especifica cómo procesar los archivos relacionados.

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

No se permiten propiedades adicionales.

Por ejemplo:

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

Pasos siguientes

Obtenga más Información sobre los conceptos de la importación.

Cuando está listo, pruebe la guía de procedimientos de importación, que le guiará a través del proceso de importación paso a paso.

Compartir a través de

Importación de actualizaciones a Device Update para IoT Hub: esquema y otra información

Schema

Objeto updateId

Objeto compatibility

Objeto instructions

Objeto inlineStep

Objeto referenceStep

Objeto file

Objeto fileHashes

relatedFiles (objeto)

downloadHandler (objeto)

Pasos siguientes

Comentarios

Recursos adicionales