Merge pull request #224804 from kgremban/jan23-durelatedfiles

Review related-files

Author: Stacyrch140

articles/iot-hub-device-update/create-update.md

@@ -83,7 +83,7 @@ For handler properties, you may need to escape certain characters in your JSON.
 
 The `init` command supports advanced scenarios, including the [related files feature](related-files.md) that allows you to define the relationship between different update files. For more examples and a complete list of optional parameters, see [az iot du init v5](/cli/azure/iot/du/update/init#az-iot-du-update-init-v5).
 
-Once you've created your import manifest and saved it as a JSON file, if you're ready to [import your update](import-update.md).
+Once you've created your import manifest and saved it as a JSON file, you're ready to [import your update](import-update.md).
 
 ## Create an advanced Device Update import manifest for a proxy update
 

articles/iot-hub-device-update/delta-updates.md

@@ -149,44 +149,43 @@ sudo ./DiffGenTool
 
 ## Import the generated delta update
 
-### Generate import manifest
-
 The basic process of importing an update to the Device Update service is unchanged  for delta updates, so if you haven't already, be sure to review this page: [How to prepare an update to be imported into Azure Device Update for IoT Hub](create-update.md)
 
+### Generate import manifest
+
 The first step to import an update into the Device Update service is always to create an import manifest if you don't already have one. For more information about import manifests, see [Importing updates into Device Update](import-concepts.md#import-manifest). For delta updates, your import manifest will need to reference two files:
+
 - The _recompressed_ target SWU image created when you ran the DiffGen tool.
 - The delta file created when you ran the DiffGen tool.
 
-The delta update feature uses a new capability called [Related Files](related-files.md), which requires an import manifest that is version 5 or later.
+The delta update feature uses a capability called [related files](related-files.md), which requires an import manifest that is version 5 or later.
 
-To create an import manifest for your delta update using the Related Files feature, you'll need to add [relatedFiles](import-schema.md#relatedfiles-object) and [downloadHandler](import-schema.md#downloadhandler-object) elements to your import manifest.
+To create an import manifest for your delta update using the related files feature, you'll need to add [relatedFiles](import-schema.md#relatedfiles-object) and [downloadHandler](import-schema.md#downloadhandler-object) objects to your import manifest.
 
-The `relatedFiles` element is used to specify information about the delta update file, including the file name, file size and sha256 hash (examples available at the link above). Importantly, you also need to specify two properties which are unique to the delta update feature:
+Use the `relatedFiles` object to specify information about the delta update file, including the file name, file size and sha256 hash. Importantly, you also need to specify two properties which are unique to the delta update feature:
 
 ```json
 "properties": {
       "microsoft.sourceFileHashAlgorithm": "sha256",
       "microsoft.sourceFileHash": "[insert the source SWU image file hash]"
 }
 ```
+
 Both of the properties above are specific to your _source SWU image file_ that you used as an input to the DiffGen tool when creating your delta update. The information about the source SWU image is needed in your import manifest even though you will not actually be importing the source image. The delta components on the device use this metadata about the source image to locate the image on the device once the delta has been downloaded.
 
-The `downloadHandler` element is used to specify how the Device Update agent will orchestrate the delta update, using the Related Files feature. Unless you are customizing your own version of the Device Update agent for delta functionality, you should only use this downloadHandler:
+Use the `downloadHandler` object to specify how the Device Update agent will orchestrate the delta update, using the related files feature. Unless you are customizing your own version of the Device Update agent for delta functionality, you should only use this downloadHandler:
 
 ```json
 "downloadHandler": {
   "id": "microsoft/delta:1"
 }
 ```
-You can use the Azure Command Line Interface (CLI) to generate an import manifest for your delta update. If you haven't used the Azure CLI to create an import manifest before, refer to [these instructions](create-update.md#create-a-basic-device-update-import-manifest).
+
+You can use the Azure Command Line Interface (CLI) to generate an import manifest for your delta update. If you haven't used the Azure CLI to create an import manifest before, see [Create a basic import manifest](create-update.md#create-a-basic-device-update-import-manifest).
 
 ```azurecli
-    az iot du update init v5
---update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version>
---compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report>
---step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'>
---file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1
---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>"}' 
+az iot du update init v5
+--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --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>"}' 
 ```
 
 Save your generated import manifest JSON to a file with the extension `.importmanifest.json`

articles/iot-hub-device-update/import-schema.md

@@ -221,6 +221,7 @@ For example:
   }
 }
 ```
+
 ## relatedFiles object
 
 Collection of related files to one or more of your primary payload files.
@@ -251,6 +252,9 @@ For example:
   }
 ],
 ```
+
+For more information, see [Use the related files feature to reference multiple update files](related-files.md).
+
 ## downloadHandler object
 
 Specifies how to process any related files.

articles/iot-hub-device-update/related-files.md

@@ -1,26 +1,47 @@
 ---
-title: Related files for Device Update for Azure IoT Hub | Microsoft Docs
-description: Understand the Device Update for IoT Hub related files feature.
+title: Related files for Device Update for Azure IoT Hub
+description: Create import manifests that reference multiple update files using the Device Update for IoT Hub related files feature.
 author: andrewbrownmsft
 ms.author: andbrown
-ms.date: 08/23/2022
+ms.date: 01/24/2023
 ms.topic: how-to
 ms.service: iot-hub-device-update
 ---
 
-# Use the related files feature in Device Update for IoT Hub
+# Use the related files feature to reference multiple update files
 
 Use the related files feature when you need to express relationships between different update files in a single update.
 
-## What is the related files feature?
-
-When importing an update to Device Update for IoT Hub, an import manifest containing metadata about the update payload is required. The file-level metadata in the import manifest can be a flat list of update payload files in the simplest case. However, for more advanced scenarios, you can instead use the related files feature, which provides a way for files to have a relationship specified between them.
+When importing an update to Device Update for IoT Hub, an import manifest containing metadata about the update payload is required. The file-level metadata in the import manifest can be a flat list of update payload files in the simplest case. However, for more advanced scenarios, the related files feature provides a way for you to specify relationships between multiple update files.
 
 When creating an import manifest using the related files feature, you can add a collection of _related_ files to one or more of your _primary_ payload files. An example of this concept is the Device Update [delta update](delta-updates.md) feature, which uses related files to specify a delta update that is associated with a full image file. In the delta scenario, the related files feature allows the full image and delta update to both be imported as a single update action, and then either one can be deployed to a device. However, the related files feature isn't limited to delta updates, since it's designed to be extensible by our customers depending on their own unique scenarios.
 
-### Example import manifest using related files
+## How to define related files
+
+The related files feature is available for import manifests that are version 5 or later.
+
+When you add related files to an import manifest, include the following information:
+
+* File details
+
+  Define the related files by providing the filename, size, and hash.
+
+* A download handler
+
+  Specify how to process these related files to produce the target file. You specify the processing approach by including a `downloadHandler` property in your import manifest. Including `downloadHandler` is required if you specify a non-empty collection of `relatedFiles` in a `file` element. You can specify a `downloadHandler` using a simple `id` property. The Download handler `id` has a limit of 64 ASCII characters.
+
+* Related files properties
+
+  You can provide extra metadata for the update handler on your device to know how to interpret and properly use the files that you've specified as related files. This metadata is added as part of a `properties` property bag to the `file` and `relatedFile` objects.
 
-Below is an example of an import manifest that uses the related files feature to import a delta update. In this example, you can see that in the `files` section, there's a full image specified (`full-image-file-name`) with a `properties` item. The `properties` item in turn has an associated `relatedFiles` item below it. Within the `relatedFiles` section, you can see another `properties` section for the delta update file (`delta-from-v1-file-name`), and also a `downloadHandler` item with the appropriate `id` listed (`microsoft/delta:1`).
+For more information about the import schema for related files, see [relatedFiles object](import-schema.md#relatedfiles-object).
+
+## Example import manifest using related files
+
+The following sample import manifest demonstrates how the related files feature is used to import a delta update. In this example, you can see that in the `files` section, there's a full image specified (`full-image-file-name`) with a `properties` item. The `properties` item in turn has an associated `relatedFiles` item below it. Within the `relatedFiles` section, you can see another `properties` section for the delta update file (`delta-from-v1-file-name`), and also a `downloadHandler` item with the appropriate `id` listed (`microsoft/delta:1`).
+
+>[!NOTE]
+>This example uses delta updates to demonstrate how to reference related files. If you want to use delta updates as a feature, learn more in the [delta update documentation](delta-updates.md).
 
 ```json
     {
@@ -76,20 +97,31 @@ Below is an example of an import manifest that uses the related files feature to
     }
 ```
 
-## How to use related files
+## Example init command using related files
 
->[!NOTE]
->The documentation on this page uses delta updates as an example of how to use related files. If you want to use delta updates as a _feature_, follow the [delta update documentation](delta-updates.md).
-
-### Related files properties
+The [az iot du init v5](/cli/azure/iot/du/update/init#az-iot-du-update-init-v5) command for creating an import manifest supports an optional `--related-file` parameter.
 
-In certain scenarios, you may want to provide extra metadata for the update handler on your device to know how to interpret and properly use the files that you've specified as related files. This metadata is added as part of a `properties` property bag to the `file` and `relatedFile` objects.
+The `--related-file` parameter takes a `path` and `properties` key:
 
-### Specify a download handler
+```azurecli
+--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>"}' 
+```
 
-When you use the related files feature, you need to specify how to process these related files to produce the target file. You specify the processing approach by including a `downloadHandler` property in your import manifest. Including `downloadHandler` is required if you specify a non-empty collection of `relatedFiles` in a `file` element. You can specify a `downloadHandler` using a simple `id` property. The Download handler `id` has a limit of 64 ASCII characters.
+For example:
+
+```azurecli
+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
+```
 
 ## Next steps
 
-- Learn about [import manifest schema](import-schema.md)
-- Learn about [delta updates](delta-updates.md)
+* Learn about [import manifest schema](import-schema.md)
+* Learn about [delta updates](delta-updates.md)