implement review comments

v-thepet · v-thepet · commit 72dc63d89158 · 2025-01-08T14:41:10.000-08:00
diff --git a/articles/iot-hub-device-update/import-concepts.md b/articles/iot-hub-device-update/import-concepts.md
@@ -1,22 +1,21 @@
 ---
-title: Azure Device Update for IoT Hub import manifest concepts
-description: Understand the important concepts and sections in the Azure Device Update for IoT Hub import manifest.
+title: Azure Device Update for IoT Hub import concepts
+description: Understand key concepts for importing a new update into Azure Device Update for IoT Hub.
 author: andrewbrownmsft
 ms.author: andbrown
-ms.date: 01/03/2025
+ms.date: 01/08/2025
 ms.topic: concept-article
 ms.service: azure-iot-hub
 ms.subservice: device-update
 ---
 
-# Azure Device Update for IoT Hub import manifest concepts
+# Azure Device Update for IoT Hub import concepts
 
-To deploy an update to devices using Azure Device Update for IoT Hub, you first import the update into the Device Update service, which stores the imported update and deploys it to devices. Along with the update payload, you submit a JSON import manifest file that defines important information about the update. This article describes the important concepts and sections in the import manifest JSON file.
+To deploy an update to devices using Azure Device Update for IoT Hub, you first import the update into the Device Update service, which stores the imported update and deploys it to devices. This article provides an overview of some important concepts to understand when it comes to importing updates.
 
-<a name="import-manifest"></a>
-## Import manifest file
+## Import manifest
 
-You submit an import manifest JSON file along with the associated update files, such as a firmware update package, as part of the import process. The metadata defined in the import manifest is used both to ingest the update and at deployment time for functions like validating whether the update installed correctly.
+An import manifest is a JSON file that defines important information about the update you're importing. You submit both your import manifest and associated update file or files, such as a firmware update package, as part of the import process. The metadata defined in the import manifest is used to ingest the update. Some of the metadata is also used at deployment time, for example to validate if an update installed correctly.
 
 The following JSON code shows an example import manifest file:
 
@@ -65,11 +64,11 @@ The sections of the import manifest file represent important Device Update conce
 
 ### Update identity
 
-The *update identity* or `updateId` provides the unique identifier for an update in Device Update, and contains the following properties:
+The *update identity* or `updateId` is the unique identifier for an update in Device Update, and contains the following properties:
 
-- `provider` is the entity that creates or is responsible for the update, often a company name.
-- `name` identifies an update class, often a device class or model name.
-- `version` is a number that distinguishes this update from others with the same provider and name.
+- **Provider** is the entity that creates or is responsible for the update, often a company name.
+- **Name** is the identifier for an update class. **Name** is often a device class or model name.
+- **Version** is a number that distinguishes this update from others with the same provider and name.
 
 For example:
 
@@ -88,7 +87,7 @@ For example:
 
 ### Compatibility
 
-The `compatibility` section uses one or more arbitrary key-value pairs to define the devices that can install an update. Only devices that report properties matching the `compatibility` values are eligible to deploy the update. You can make an update compatible with multiple device classes by including more than one set of device compatibility properties.
+The **Compatibility** section uses one or more arbitrary key-value pairs to define the devices that can install an update. Only devices that report properties matching the compatibility values are eligible to deploy the update. You can make an update compatible with multiple device classes by including more than one set of device compatibility properties.
 
 The following example shows an update that can only be deployed to devices that report *Contoso* and *Toaster* as their device manufacturer and model.
 
@@ -105,7 +104,7 @@ The following example shows an update that can only be deployed to devices that
 
 ### Instructions
 
-The `instructions` section contains the necessary information or `steps` for the device agent to install the update. The simplest update contains a single inline step that executes the update payload file using a `handler` registered with the device agent. The following example shows a single-step `instructions` section.
+The **Instructions** section contains the necessary information or steps for the device agent to install the update. The simplest update contains a single inline step that executes the update payload file using a handler registered with the device agent. The following example shows a single-step instructions section.
 
 ```json
 {
@@ -125,7 +124,7 @@ The `instructions` section contains the necessary information or `steps` for the
 > [!NOTE]
 > The `handler` property is equivalent to the `updateType` property in import manifest version 3.0 or older.
 
-An update and an import manifest `steps` section can contain more than one step, as in the following example:
+An update can contain more than one step, as in the following example:
 
 ```json
 {
@@ -153,7 +152,9 @@ An update and an import manifest `steps` section can contain more than one step,
 }
 ```
 
-A `steps` section can also contain `reference` steps that instruct the device agent to install a different update and corresponding import manifest, establishing a parent and child update relationship. The following example update for a toaster contains two child update steps. An update can contain any combination of inline and reference steps.
+An update may contain *reference* steps that instruct the device agent to install another update with its own import manifest, establishing a parent and child update relationship. An update can contain any combination of inline and reference steps.
+
+For example, an update for a toaster may contain two child updates:
 
 ```json
 {
@@ -183,24 +184,24 @@ A `steps` section can also contain `reference` steps that instruct the device ag
 
 ### Files
 
-The `files` section of the import manifest contains update payload file metadata like `name`, `size`, and `hash`. Device Update uses this metadata for integrity validation during the import process, and forwards the same information to the device agent for integrity validation before installation.
+The **Files** section of the import manifest contains update payload file metadata like `name`, `size`, and `hash`. Device Update uses this metadata for integrity validation during the import process, and forwards the same information to the device agent for integrity validation before installation.
 
 > [!NOTE]
 > A parent update that contains only reference steps doesn't define any update payload files.
 
 ## Create an import manifest
 
-Once you understand the structure of an import manifest, create an import manifest file to describe your update. You can author a JSON import manifest file manually using a text editor, but the Azure CLI [az iot du init v5](/cli/azure/iot/du/update/init#az-iot-du-update-init-v5) command simplifies the process. For more information and instructions, see [Prepare an update to import into Device Update](create-update.md).
+While it's possible to author an import manifest JSON manually using a text editor, the Azure CLI simplifies the process greatly. When you're ready to try out the creation of an import manifest, you can use the [How-to guide](create-update.md#create-a-basic-device-update-import-manifest).
 
 > [!IMPORTANT]
-> To import into the Azure portal, an import manifest JSON filename must end with *.importmanifest.json*.
+> To import into the Device Update service via the Azure portal, an import manifest JSON filename must end with *.importmanifest.json*.
 
 > [!TIP]
 > You can use [Visual Studio Code](https://code.visualstudio.com) to enable autocomplete and JSON schema validation when you create an import manifest.
 
 ## Update import limits
 
-Certain limits are enforced for Device Update instances, including import limits. For more information, see [Device Update limits](./device-update-limits.md).
+Certain limits are enforced for each Device Update for IoT Hub instance. If you haven't already reviewed them, see [Device Update limits](./device-update-limits.md).
 
 ## Related content
 
diff --git a/articles/iot-hub-device-update/import-schema.md b/articles/iot-hub-device-update/import-schema.md
@@ -3,7 +3,7 @@ title: Import manifest schema for Azure Device Update for IoT Hub
 description: Understand the schema used to create the required import manifest for importing updates into Azure Device Update for IoT Hub.
 author: andrewbrownmsft
 ms.author: andbrown
-ms.date: 01/03/2025
+ms.date: 01/08/2025
 ms.topic: concept-article
 ms.service: azure-iot-hub
 ms.subservice: device-update
@@ -37,8 +37,8 @@ The `updateID` object is a unique identifier for each update.
 
 |Property|Type|Description|Required|
 |---|---|---|---|
-|**provider**|`string`|Entity who is creating or directly responsible for the update, such as a company name.<br>Pattern: `^[a-zA-Z0-9.-]+$`<br>Maximum length: 64 characters|Yes|
-|**name**|`string`|Identifier for a class of update, such as a device class or model name.<br>Pattern: `^[a-zA-Z0-9.-]+$`<br>Maximum length: 64 characters|Yes|
+|**provider**|`string`|Entity who is creating or directly responsible for the update. The **provider** can be a company name.<br>Pattern: `^[a-zA-Z0-9.-]+$`<br>Maximum length: 64 characters|Yes|
+|**name**|`string`|Identifier for a class of update. The **name** can be a device class or model name.<br>Pattern: `^[a-zA-Z0-9.-]+$`<br>Maximum length: 64 characters|Yes|
 |**version**|`string`|Two- to four-part dot-separated numerical version numbers. Each part must be a number between 0 and 2147483647, and leading zeroes are dropped.<br>Pattern: `^\d+(?:\.\d+)+$`<br>Examples: `"1.0"`, `"2021.11.8"`|Yes|
 
 No other properties are allowed.
@@ -107,7 +107,7 @@ An `inline` step object is an installation instruction step that performs code e
 
 |Property|Type|Description|Required|
 |---|---|---|---|
-|**type**|`string`|Instruction step type that performs code execution. Must be `inline`.|No|
+|**type**|`string`|Instruction step type that performs code execution. Must be `inline`. Defaults to `inline` if no value is provided.|No|
 |**description**|`string`|Optional instruction step description. Maximum length: 64 characters.|No|
 |**handler**|`string`|Identity of the handler on the device that can execute this step.<br>Pattern: `^\S+/\S+:\d{1,5}$`<br>Minimum length: Five characters<br>Maximum length: 32 characters<br>Examples: `microsoft/script:1`, `microsoft/swupdate:1`, `microsoft/apt:1` |Yes|
 |**files**|`string` `[1-10]`| Names of update files defined as [file objects](#files-object) that the agent passes to the handler. Each element length must be 1-255 characters. |Yes|
@@ -165,15 +165,15 @@ For example:
 
 ### Files object
 
-Each *file* object is an update payload file, such as a binary, firmware, or script file, that must be unique within an update.
+Each `files` object is an update payload file, such as a binary, firmware, or script file, that must be unique within an update.
 
 |Property|Type|Description|Required|
 |---|---|---|---|
-|**filename**|`string`|Update payload file name. Maximum length: 255 characters.|Yes|
-|**sizeInBytes**|`number`|File size in number of bytes. Maximum size: 2147483648 bytes.|Yes|
-|**hashes**|`fileHashes`|Base64-encoded file hashes with the algorithm name as key. For more information, see [fileHashes object](#filehashes-object). |Yes|
-|**relatedFiles**|`relatedFile[0-4]`|Collection of files related to one or more primary payload files. |No|
-|**downloadHandler**|`downloadHandler`|Specifies how to process any related files. |Yes if using `relatedFiles`|
+|**filename**|`string`|Update payload file name. Maximum length: 255 characters|Yes|
+|**sizeInBytes**|`number`|File size in number of bytes. Maximum size: 2147483648 bytes|Yes|
+|**hashes**|`fileHashes`|Base64-encoded file hashes with algorithm name as key. At least SHA-256 algorithm must be specified, and additional algorithms may be specified if supported by agent. See [Hashes object](#hashes-object} for details on how to calculate the hash.|Yes|
+|**relatedFiles**|`relatedFile[0-4]`|Collection of files related to one or more primary payload files. For more information, see [relatedFiles object](#relatedfiles-object).|No|
+|**downloadHandler**|`downloadHandler`|Specifies how to process any related files. |Yes, if using `relatedFiles`. For more information, see [downloadHandler object](#downloadhandler-object).|
 
 No other properties are allowed.
 
@@ -182,16 +182,29 @@ For example:
 ```json
 {
   "files": [
-    {
-      "filename": "configure.sh",
-      "sizeInBytes": 7558,
-      "hashes": {...}
+    {  
+      "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"
+        }
     }
   ]
 }
 ```
 
-#### fileHashes object
+#### Hashes object
 
 The `hashes` object contains base64-encoded file hashes with the algorithm names as keys. At least the SHA-256 algorithm must be specified, and other algorithms may be specified if supported by the agent. For an example of how to calculate the hash correctly, see the `Get-AduFileHashes` function in the [AduUpdate.psm1 script](https://github.com/Azure/iot-hub-device-update/blob/main/tools/AduCmdlets/AduUpdate.psm1).
 
@@ -220,7 +233,7 @@ The `relatedFiles` object contains a collection of files that are related to one
 |---|---|---|---|
 |**filename**|`string`|List of related files associated with a primary payload file.|Yes|
 |**sizeInBytes**|`number`|File size in number of bytes. Maximum size: 2147483648 bytes.|Yes|
-|**hashes**|`fileHashes`|Base64-encoded file hashes with algorithm name as key. For more information, see [fileHashes object](#filehashes-object). |Yes|
+|**hashes**|`fileHashes`|Base64-encoded file hashes with algorithm name as key. For more information, see [Hashes object](#filehashes-object). |Yes|
 |**properties**|`relatedFilesProperties` `[0-5]`|Up to five key-value pairs, where the key is limited to 64 ASCII characters and the value is a JObject with up to 256 ASCII characters. |No|
 
 Other properties are allowed.
diff --git a/articles/iot-hub-device-update/import-update.md b/articles/iot-hub-device-update/import-update.md
@@ -3,7 +3,7 @@ title: Import an update to Azure Device Update for IoT Hub
 description: Learn how to import update files into Azure Device Update for IoT Hub by using the Azure portal, Azure CLI, or programmatically.
 author: andrewbrownmsft
 ms.author: andbrown
-ms.date: 01/03/2025
+ms.date: 01/08/2025
 ms.topic: how-to
 ms.service: azure-iot-hub
 ms.subservice: device-update
@@ -23,6 +23,29 @@ To deploy an update to devices using Azure Device Update for IoT Hub, you first
   > [!IMPORTANT]
   > Make sure the storage account you use or create doesn't have private endpoints enabled. To see if private endpoints are enabled, you can check for your Azure Storage account name under **Private endpoints** in the [Private Link Center](https://portal.azure.com/#blade/Microsoft_Azure_Network/PrivateLinkCenterBlade/overview).
 
+# [Azure portal](#tab/portal)
+
+- Supported browsers Microsoft Edge or Google Chrome.
+
+# [Azure CLI](#tab/cli)
+
+- A Bash environment.
+
+  You can use the Bash environment in [Azure Cloud Shell](/azure/cloud-shell/quickstart) to run the commands in this article. Select **Launch Cloud Shell** to open Cloud Shell, or select the Cloud Shell icon in the top toolbar of the Azure portal.
+
+  :::image type="icon" source="~/reusable-content/ce-skilling/azure/media/cloud-shell/launch-cloud-shell-button.png" alt-text="Button to launch the Azure Cloud Shell." border="false" link="https://shell.azure.com":::
+
+  Or, if you prefer, you can run the Azure CLI commands locally:
+
+  1. [Install Azure CLI](/cli/azure/install-azure-cli). Run [az version](/cli/azure/reference-index#az-version) to see the installed Azure CLI version and dependent libraries, and run [az upgrade](/cli/azure/reference-index#az-upgrade) to install the latest version.
+  1. Sign in to Azure by running [az login](/cli/azure/reference-index#az-login).
+  1. Install the `azure-iot` extension when prompted on first use. To make sure you're using the latest version of the extension, run `az extension update --name azure-iot`.
+
+>[!TIP]
+>The Azure CLI commands in this article use the backslash \\ character for line continuation so that the command arguments are easier to read. This syntax works in Bash environments. If you run these commands in PowerShell, replace each backslash with a backtick \`, or remove them entirely.
+
+---
+
 ## Import an update
 
 This section shows how to import an update using either the Azure portal or the Azure CLI. You can also [import an update by using the Device Update APIs](#import-using-the-device-update-apis) instead.
@@ -31,7 +54,7 @@ To import an update, you first upload the update and import manifest files into
 
 # [Azure portal](#tab/portal)
 
-1. On the [Azure portal](https://portal.azure.com) IoT hub page for your Device Update instance, select **Device management** > **Updates** from the left navigation.
+1. In the [Azure portal](https://portal.azure.com), on the IoT hub page for your Device Update instance, select **Device management** > **Updates** from the left navigation.
 
    :::image type="content" source="media/import-update/import-updates-3-ppr.png" alt-text="Screenshot that shows Import updates." lightbox="media/import-update/import-updates-3-ppr.png":::
 
@@ -76,19 +99,6 @@ The import process begins, and the screen switches to the **Updates** screen. Af
 
 # [Azure CLI](#tab/cli)
 
-You can use the Bash environment in [Azure Cloud Shell](/azure/cloud-shell/quickstart) to run the following commands. Select **Launch Cloud Shell** to open Cloud Shell, or select the Cloud Shell icon in the top toolbar of the Azure portal.
-
-:::image type="icon" source="~/reusable-content/ce-skilling/azure/media/cloud-shell/launch-cloud-shell-button.png" alt-text="Button to launch the Azure Cloud Shell." border="false" link="https://shell.azure.com":::
-
-Or, if you prefer, you can run the Azure CLI commands locally:
-
-1. [Install Azure CLI](/cli/azure/install-azure-cli). Run [az version](/cli/azure/reference-index#az-version) to see the installed Azure CLI version and dependent libraries, and run [az upgrade](/cli/azure/reference-index#az-upgrade) to install the latest version.
-1. Sign in to Azure by running [az login](/cli/azure/reference-index#az-login).
-1. Install the `azure-iot` extension when prompted on first use. To make sure you're using the latest version of the extension, run `az extension update --name azure-iot`.
-
->[!TIP]
->The following Azure CLI commands use the backslash \\ character for line continuation so that the command arguments are easier to read. This syntax works in Bash environments. If you run these commands in PowerShell, replace each backslash with a backtick \`, or remove them entirely.
-
 The [az iot du update stage](/cli/azure/iot/du/update#az-iot-du-update-stage) command handles the prerequisite steps of importing an update, including uploading the update files into a target storage container. An optional flag also lets this command automatically import the files after preparing them. Otherwise, the [az iot du update import](/cli/azure/iot/du/update#az-iot-du-update-import) command completes the process.
 
 The `stage` command takes the following arguments:
diff --git a/articles/iot-hub-device-update/update-manifest.md b/articles/iot-hub-device-update/update-manifest.md
@@ -3,7 +3,7 @@ title: Azure Device Update for IoT Hub update manifest
 description: Learn about the update manifest that the Azure Device Update for IoT Hub service uses to send properties to devices during updates.
 author: andrewbrownmsft
 ms.author: andbrown
-ms.date: 01/03/2025
+ms.date: 01/08/2025
 ms.topic: concept-article
 ms.service: azure-iot-hub
 ms.subservice: device-update
