How to manage devices using device twin tags in Azure IoT Hub

This article demonstrates how to use tags to manage IoT devices using device twin tags

Device twin tags can be used as a powerful tool to help you organize your devices. This is especially important when you have multiple kinds of devices within your IoT solutions, you can use tags to set types, locations etc. For example:

    "deviceId": "mydevice1",
    "status": "enabled",
    "connectionState": "Connected",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "tags": {
        "deploymentLocation": {
            "building": "43",
            "floor": "1"
    "properties": {


Add and view device twin tags using the Azure portal

This section describes how to create an IoT hub using the Azure portal.

  1. Sign in to the Azure portal and go to your IoT Hub.

  2. Select the Device tab in the left navigation.

  3. Select the desired devices, select Assign Tags.

    Screenshot of selecting devices to assign tags.

  4. In the opened view, you can see the tags the devices already have. To add a new basic tag, provide a name and value for the tag. The format for the name and value pair is found in Tags and properties format. Select Save to save the tag.

    Screenshot of assigning tags to devices screen.

  5. After saving, you can view the tags that were added by selecting Assign Tags again.

    Screenshot of viewing tags added to devices.

Add and view nested tags

  1. Following the example above, you can add a nested tag by selecting the advanced tab in the Assign Tags and add a nested json object with two values.
        "deploymentLocation": {
            "building": "43",
            "floor": "1"
  2. Select Save Screenshot of adding nested tags to devices.
  3. Select the devices again and select Assign Tags to view the newly added tags Screenshot of viewing nested tags to devices.

Filtering devices with device twin tags

Device twin tags is a great way to group devices by type, location etc., and you can manage your devices by filtering through device tags.

  1. Select + Add filter, and select Device Tag as the filter type
  2. Enter the desired tag name and value, select Apply to retrieve the list of devices that matches the criteria Screenshot of filtering devices with tags.

Update and delete device twin tags from multiple devices using the Azure portal

  1. Select the two or more devices, select Assign Tags.
  2. In the opened panel, you can update existing tags by typing the target tag name in the Name field, and the new string in the Value field.
  3. To delete a tag from multiple devices, type the target tag name in the Name field, and the select the Delete Tags button. Screenshot of marking tag for deletion.
  4. Select Save to delete the tag from the devices that contains the matching tag name.

Managing device twin tags using the Azure CLI

The following section walk-through several examples of tagging using the Azure CLI. For full references to the device twin CLI

  1. At the command prompt, run the login command:

    az login

    Follow the instructions to authenticate using the code and sign in to your Azure account through a web browser.

  2. If you have multiple Azure subscriptions, signing in to Azure grants you access to all the Azure accounts associated with your credentials. Use the az account list to view the full list of accounts:

    az account list

    Use the following command to select the subscription that you want to use to run the commands to create your IoT hub. You can use either the subscription name or ID from the output of the previous command:

    az account set --subscription {your subscription name or id}
  3. The following command enables file notifications and sets the file notification properties to their default values. (The file upload notification time to live is set to one hour and the lock duration is set to 60 seconds.)

    az iot hub device-twin update -n {iothub_name} \
        -d {device_id} --tags '{"country": "USA"}'
  4. You can add complex nested tags by importing a json file or adding json directly to the input:

    az iot hub device-twin update --name {your iot hub name} \
        -d {device_id} --tags /path/to/file
    az iot hub device-twin update --name {your iot hub name} \
        -d {device_id} --tags '{"country":{"county":"king"}}'
  5. Use the command on an existing tag to update the value:

    az iot hub device-twin update --name {your iot hub name} \
        -d {device_id} --tags '{"country": "Germany"}'
  6. The following command removes the tag that was added by setting the value to null.

    az iot hub device-twin update --name {your iot hub name} \
        -d {device_id} --tags '{"country": null}'


If you are using Powershell or CloudShell>Powershell mode, you need to add a forward slash '\' to escape all the double quotes. Example: --tags '{\"country\":\"US\"}'

Create jobs to set tags using Azure CLI

For full references to the IoT Hub Jobs CLI

Next steps

Now you have learned about device twins, you may be interested in the following IoT Hub developer guide topics:

To try out some of the concepts described in this article, see the following IoT Hub tutorials: