Compartir vía

Uso de la característica de archivos relacionados para hacer referencia a varios archivos de actualización

  • Artículo

Usa la característica de archivos relacionados cuando necesites expresar relaciones entre diferentes archivos de actualización en una sola actualización.

Al importar una actualización a Device Update for IoT Hub, se requiere un manifiesto de importación que contenga metadatos sobre la carga de actualización. Los metadatos de nivel de archivo del manifiesto de importación pueden ser una lista plana de archivos de carga de actualización en el caso más sencillo. En escenarios más avanzados, la característica de archivos relacionados ofrece una manera de especificar las relaciones entre varios archivos de actualización.

Al crear un manifiesto de importación mediante la característica de archivos relacionados, puedes agregar una colección de archivos relacionados a uno o varios de los archivos de carga principal. Un ejemplo de este concepto es la característica de actualización diferencial de Device Update, que usa archivos relacionados para especificar una actualización diferencial asociada a un archivo de imagen completo. En el escenario delta, la característica de archivos relacionados permite importar la imagen completa y la actualización diferencial como una única acción de actualización y, a continuación, se puede implementar en un dispositivo. Sin embargo, la característica de archivos relacionados no se limita a las actualizaciones diferenciales, ya que está diseñada para ser extensible para nuestros clientes en función de sus propios escenarios únicos.

La característica de archivos relacionados está disponible para los manifiestos de importación con la versión 5 o posterior.

Al agregar archivos relacionados a un manifiesto de importación, incluya la información siguiente:

  • File details

    Proporcione el nombre de archivo, el tamaño y el hash para definir los archivos relacionados.

  • Controlador de descarga

    Especifique cómo se procesan estos archivos relacionados para producir el archivo de destino. Para especificar el enfoque de procesamiento, incluye una propiedad downloadHandler en el manifiesto de importación. Es necesario incluir downloadHandler si especificas una colección no vacía de relatedFiles en un elemento file. Puedes especificar un downloadHandler mediante una propiedad id simple. El controlador de descarga id tiene un límite de 64 caracteres ASCII.

  • Propiedades de archivos relacionados

    Puede proporcionar metadatos adicionales para el controlador de actualizaciones en el dispositivo, con el fin de saber cómo interpretar y usar correctamente los archivos que ha especificado como archivos relacionados. Estos metadatos se agregan como parte de un contenedor de propiedades properties a los objetos file y relatedFile.

Para obtener más información sobre el esquema de importación de archivos relacionados, consulte Objeto relatedFiles.

El siguiente manifiesto de importación de ejemplo muestra cómo se usa la característica de archivos relacionados para importar una actualización diferencial. En este ejemplo, puedes ver que en la sección files hay una imagen completa especificada (full-image-file-name) con un elemento properties. A su vez, el elemento properties tiene un elemento asociado relatedFiles debajo. Dentro de la sección relatedFiles, puedes ver otra sección properties para el archivo de actualización diferencial (delta-from-v1-file-name) y también un elemento downloadHandler con la lista id adecuada (microsoft/delta:1).

Nota

En este ejemplo se usan actualizaciones diferenciales para mostrar cómo hacer referencia a archivos relacionados. Si quiere usar las actualizaciones diferenciales como una característica, consulte más información en la documentación sobre actualizaciones diferenciales.

    {
      "updateId": {
        // provider, name, version
      },
      "compatibility": [
        {
          // manufacturer, model, etc.
        }
      ],
      "instructions": {
        "steps": [
          // Inline steps...
        ]
      },
      "files": [
        {  
          // standard file properties
          "fileName": "full-image-file-name",
          "sizeInBytes": 12345,
          "hashes": {
            "SHA256": "full-image-file-hash"
          },
          "mimeType": "application/octet-stream",
          // new properties
          "properties  ": {},
          "relatedFiles": [
            {
              // delta from version 1.0.0.0
              // standard file properties
              "fileName": "delta-from-v1-file-name",
              "sizeInBytes": 1234,
              "hashes": {
                "SHA256": "delta-from-v1-file-hash"
              },
              "mimeType": "application/octet-stream",
              // new properties
              "properties": {
                "microsoft.sourceFileHash": "delta-source-file-hash",
                "microsoft.sourceFileHashAlgorithm": "sha256"
              }
            }  
          ],
          // handler to download/process our related files
      "downloadHandler": {
        "id": "microsoft/delta:1"
      }
    }
  ],
  "createdDateTime": "2021-12-01T01:12:21Z",
  "manifestVersion": "5.0"
    }

El comando az iot du init v5 para crear un manifiesto de importación admite un parámetro --related-file opcional.

El parámetro --related-file toma una clave path y properties:

--related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}'

Por ejemplo:

az iot du update init v5 \
--update-provider Microsoft --update-name myBundled --update-version 2.0 \
--compat manufacturer=Contoso model=SpaceStation \
--step handler=microsoft/script:1 properties='{"arguments": "--pre"}' description="Pre-install script" \
--file path=/my/update/scripts/preinstall.sh downloadHandler=microsoft/delta:1 \
--related-file path=/my/update/scripts/related_preinstall.json properties='{"microsoft.sourceFileHashAlgorithm": "sha256"}' \
--step updateId.provider=Microsoft updateId.name=SwUpdate updateId.version=1.1 \
--step handler=microsoft/script:1 properties='{"arguments": "--post"}' description="Post-install script" \
--file path=/my/update/scripts/postinstall.sh

Pasos siguientes