Import an update to Azure Device Update for IoT Hub

To deploy an update to devices using Azure Device Update for IoT Hub, you first import the update files into the Device Update service, which stores the imported update for deployment to devices. In this article, you learn how to import an update into the Device Update service by using the Azure portal, Azure CLI, or Device Update APIs.

Prerequisites

• A Device Update account and instance configured with an IoT hub.

• An IoT device or simulator provisioned for Device Update within the IoT hub.

• Update files for your device, and an associated import manifest file created by following the instructions in Prepare an update to import into Device Update.

• An Azure Storage account and container to hold the imported files. Or, you can create a new storage account and container as part of the Azure portal based import process.

  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.

Azure portal

• Supported browsers Microsoft Edge or Google Chrome.

Azure CLI

• A Bash environment.

  You can use the Bash environment in Azure Cloud Shell 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.

  

  Or, if you prefer, you can run the Azure CLI commands locally:

  1. Install Azure CLI. Run az version to see the installed Azure CLI version and dependent libraries, and run az upgrade to install the latest version.
  2. Sign in to Azure by running az login.
  3. 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 instead.

To import an update, you first upload the update and import manifest files into an Azure Storage container. Then, you import the update from Azure Storage into Device Update for IoT Hub, which stores it for deployment to devices.

Azure portal

1. In the Azure portal, on the IoT hub page for your Device Update instance, select Device management > Updates from the left navigation.

   

2. On the Updates page, select Import a new update.

   

3. On the Import update page, select Select from storage container.

4. On the Storage accounts page, select an existing storage account or create a new account by selecting Storage account. You use the storage account for a container to stage the update files.

5. On the Containers page, select an existing container or create a new container by selecting Container. You use the container to stage the update files for import.

   

   Tip

   Using a new container each time you import an update helps prevent accidentally importing files from previous updates. If you don't use a new container, be sure to delete any previous files from the existing container.

6. On the container page, select Upload.

   

7. On the Upload blob screen, select the folder icon next to the Files. Use the file picker to navigate to the location of your update and import manifest files, select the files, and then select Open. You can use the Shift key to multiselect files.

   

8. After you select all the files, select Upload.

   

9. After they upload, the files appear on the container page. On the container page, review and select the files to import, and then select Select.

   

10. On the Import update screen, select Import update.

    

The import process begins, and the screen switches to the Updates screen. After the import succeeds, it appears on the Updates tab. To resolve any errors, see Proxy update troubleshooting.

Azure CLI

The 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 command completes the process.

The stage command takes the following arguments:

• --account: The Device Update account name.
• --instance: The Device Update instance name.
• --manifest-path: The file path to the import manifest to stage.
• --storage-account: The name of the storage account to stage the update to.
• --storage-container: The name of the container within the selected storage account to stage the update to.
• --overwrite: Optional flag that indicates whether to overwrite existing blobs in the storage container if there's a conflict.
• --then-import: Optional flag that indicates whether to import the update to Device Update after staging it.

az iot du update stage \
    --account <Replace with your Device Update account name> \
    --instance <Replace with your Device Update instance name> \
    --manifest-path <Replace with the full path to your import manifest> \
    --storage-account <Replace with your Storage account name> \
    --storage-container <Replace with your container name> \
    --overwrite --then-import

For example:

az iot du update stage \
    --account deviceUpdate001 \
    --instance myInstance \
    --manifest-path /my/apt/manifest/file.importmanifest.json \
    --storage-account deviceUpdateStorage \
    --storage-container deviceUpdateDemo \
    --overwrite --then-import

You can include multiple import manifests in a single command. For example:

az iot du update stage \
    --account deviceUpdate001 \
    --instance myInstance \
    --manifest-path /my/apt/manifest/parent.importmanifest.json \
    --manifest-path /my/apt/manifest/child1.importmanifest.json \
    --manifest-path /my/apt/manifest/child2.importmanifest.json \
    --storage-account deviceUpdateStorage \
    --storage-container deviceUpdateDemo \
    --overwrite --then-import

If you don't use the --then-import flag, the output of the stage command includes a prompt to run az iot du update import with prepopulated arguments.

Use az iot du update list to verify that your updates successfully import.

az iot du update list \
    --account <Replace with your Device Update account name> \
    --instance <Replace with your Device Update instance name> \
    -o table

Import using the Device Update APIs

You can also import an update programmatically by using any of the following methods:

• The Device Update APIs in the Azure SDKs for .NET, Java, JavaScript, or Python
• The Device Update Import Update REST API
• Sample PowerShell modules (requires PowerShell 5 or later for Linux, macOS, or Windows)

Note

See Device Update user roles and access for required API permission.

The update files and import manifest must be uploaded to an Azure Storage Blob container for staging. To import the staged files, provide the blob URL, or shared access signature (SAS) for private blobs, to the Device Update API. If using a SAS, be sure to provide an expiration window of three hours or more.

Tip

To upload large update files to an Azure Storage Blob container, you can use one of the following methods for better performance:

• AzCopy
• Azure Storage Explorer

Related content

• Device groups
• Device Update import manifest