Importación de actualizaciones en Device Update para IoT Hub

Para implementar una actualización en dispositivos desde Device Update para IoT Hub, primero debe importar esa actualización en el servicio Device Update. En este artículo se proporciona información general sobre algunos conceptos importantes que se deben conocer en relación con la importación de actualizaciones.

Manifiesto de importación

Un manifiesto de importación es un archivo JSON que define información importante sobre la actualización que va a importar. Envíe el manifiesto de importación y el archivo o los archivos de actualización asociados (como un paquete de actualización de firmware) como parte del proceso de importación. Los metadatos definidos en el manifiesto de importación se usan para ingerir la actualización. Algunos de los metadatos también se usan en el momento de la implementación; por ejemplo, para validar si una actualización se instaló correctamente.

Por ejemplo:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "firmware.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "firmware.swu",
      "sizeInBytes": 7558,
      "hashes": {
        "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
      }
    }
  ],
  "createdDateTime": "2022-01-19T06:23:52.6996916Z",
  "manifestVersion": "4.0"
}

El manifiesto de importación contiene varios elementos que representan conceptos importantes de Device Update para IoT Hub. Estos elementos se describen en esta sección. Para obtener información sobre el esquema de importación completo, consulte Esquema JSON del manifiesto de importación.

Actualizar identidad

La identidad de actualización o updateId es el identificador único de una actualización en Device Update para IoT Hub. Consta de tres partes:

• Proveedor: entidad que está creando o responsable directamente de la actualización. A menudo será un nombre de empresa.
• Nombre: identificador de una clase de actualizaciones. A menudo será un nombre de modelo o clase de dispositivo.
• Versión: un número de versión que distingue esta actualización de otros que tienen el mismo proveedor y nombre.

Por ejemplo:

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

Compatibilidad

La compatibilidad define los criterios de un dispositivo que puede instalar la actualización. Contiene propiedades de dispositivo que son un conjunto de pares de valores de clave arbitrarios que se notifican desde un dispositivo. Solo los dispositivos con propiedades coincidentes serán aptos para la implementación. Una actualización puede ser compatible con varias clases de dispositivo al tener más de un conjunto de propiedades de dispositivo.

Este es un ejemplo de una actualización que solo se puede implementar en un dispositivo que informa a Contoso y Toaster como su fabricante y modelo de dispositivo.

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

Instrucciones

La parte Instrucciones contiene la información o los pasos necesarios para que el agente de dispositivo instale la actualización. La actualización más sencilla contiene un solo paso en línea. Ese paso ejecuta el archivo de carga incluido mediante un controlador registrado con el agente de dispositivo:

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Una actualización puede contener más de un paso:

{
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "description": "firmware package",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Una actualización puede contener pasos de referencia que indican al agente de dispositivo que instale otra actualización con su propio manifiesto de importación por completo, estableciendo una relación de actualización primaria y secundaria. Por ejemplo, una actualización para una tostadora puede contener dos actualizaciones secundarias.

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

Archivos

La parte Files contiene los metadatos de los archivos de carga de actualización, como sus nombres, tamaños y hash. Device Update para IoT Hub usa estos metadatos para la validación de integridad durante el proceso de importación. A continuación, se reenvía la misma información al agente de dispositivo para repetir la validación de integridad antes de la instalación.

Creación de un manifiesto de importación

Puede usar cualquier editor de texto para crear el archivo JSON del manifiesto de importación. También hay scripts de ejemplo para crear manifiestos de importación mediante programación en Azure/iot-hub-device-update en GitHub.

Límites de importación de actualizaciones

En todas las instancias de Device Update for IoT Hub, se aplican los determinados límites. Si aún no los ha revisado, consulte Límites de actualización de dispositivos.

Pasos siguientes

• Para obtener más información sobre el proceso de importación, consulte Preparación de una actualización para la importación.
• Consulte el esquema de manifiesto de importación.