Upload files from your device to the deject with IoT Hub (.Internet)

  • Article
  • 14 minutes to read
  • .Internet
  • Java
  • Node.js
  • Python

This tutorial shows yous how to use the file upload feature of IoT Hub with the Azure IoT .NET device and service SDKs.

The Send telemetry from a device to an IoT hub quickstart and Send cloud-to-device messages with IoT Hub tutorial bear witness the basic device-to-cloud and cloud-to-device messaging functionality of IoT Hub. The Configure Message Routing with IoT Hub tutorial describes a fashion to reliably store device-to-cloud messages in Microsoft Azure hulk storage. However, in some scenarios you can't easily map the data your devices send into the relatively modest device-to-deject messages that IoT Hub accepts. For example:

  • Large files that contain images

  • Videos

  • Vibration information sampled at high frequency

  • Some class of preprocessed information

These files are typically batch processed in the cloud using tools such as Azure Data Factory or the Hadoop stack. When y'all need to upload files from a device, nevertheless, you tin can withal utilise the security and reliability of IoT Hub. This tutorial shows yous how.

At the end of this tutorial y'all run two .Net console apps:

  • FileUploadSample. This device app uploads a file to storage using a SAS URI provided by your IoT hub. Y'all'll run this app from the Azure IoT C# samples repository that you download in the prerequisites.

  • ReadFileUploadNotification. This service app receives file upload notifications from your IoT hub. You'll create this app.

Note

IoT Hub supports many device platforms and languages, including C, Java, Python, and JavaScript, through Azure IoT device SDKs. Refer to the Azure IoT Developer Center for step-by-stride instructions on how to connect your device to Azure IoT Hub.

Prerequisites

  • An active Azure account. If y'all don't accept an business relationship, you tin can create a free account in just a couple of minutes.

  • The sample applications y'all run in this commodity are written using C#. For the Azure IoT C# samples, we recommend you lot have the .Internet Core SDK three.1 or greater on your development machine.

    You can download the .Net Cadre SDK for multiple platforms from .NET.

    You can verify the current version of the .NET Core SDK on your development automobile using the following command:

                      dotnet --version

  • Download the Azure IoT C# samples from https://github.com/Azure-Samples/azure-iot-samples-csharp/archive/master.zip and extract the ZIP annal.

  • Brand sure that port 8883 is open in your firewall. The sample in this article uses MQTT protocol, which communicates over port 8883. This port may exist blocked in some corporate and educational network environments. For more information and ways to piece of work around this event, see Connecting to IoT Hub (MQTT).

Create an IoT hub

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

  1. Sign in to the Azure portal.

  2. On the Azure homepage, select the + Create a resource button.

  3. From the Categories menu, select Internet of Things so IoT Hub.

  4. On the Basics tab, consummate the fields as follows:

    • Subscription: Select the subscription to use for your hub.

    • Resource group: Select a resources grouping or create a new ane. To create a new one, select Create new and fill in the name you desire to utilise. To apply an existing resource group, select that resource group. For more information, run across Manage Azure Resource Manager resource groups.

    • Region: Select the region in which you desire your hub to be located. Select the location closest to y'all. Some features, such equally IoT Hub device streams, are only bachelor in specific regions. For these limited features, y'all must select one of the supported regions.

    • IoT hub name: Enter a proper noun for your hub. This name must exist globally unique, with a length between 3 and 50 alphanumeric characters. The proper name can also include the dash ('-') grapheme.

    Important

    Considering the IoT hub will be publicly discoverable every bit a DNS endpoint, exist certain to avoid entering whatever sensitive or personally identifiable information when you name information technology.

    Create a hub in the Azure portal.

  5. Select Adjacent: Networking to proceed creating your hub.

    Cull the endpoints that devices tin use to connect to your IoT hub. You tin can select the default setting, Public access, or choose Individual access. Take the default setting for this case.

    Choose the endpoints that can connect.

  6. Select Adjacent: Management to go on creating your hub.

    Set the size and scale for a new hub using the Azure portal.

    You tin accept the default settings here. If desired, you tin modify whatever of the following fields:

    • Pricing and scale tier: Your selected tier. You can choose from several tiers, depending on how many features y'all desire and how many letters you send through your solution per twenty-four hours. The free tier is intended for testing and evaluation. It allows 500 devices to be continued to the hub and up to 8,000 messages per day. Each Azure subscription can create ane IoT hub in the free tier.

      If you are working through a quickstart, select the complimentary tier.

    • IoT Hub units: The number of letters allowed per unit of measurement per day depends on your hub's pricing tier. For example, if you want the hub to support ingress of 700,000 messages, you lot cull two S1 tier units. For details about the other tier options, encounter Choosing the right IoT Hub tier.

    • Microsoft Defender for IoT: Turn this on to add an extra layer of threat protection to IoT and your devices. This option is not available for hubs in the gratuitous tier. Learn more almost security recommendations for IoT Hub in Defender for IoT.

    • Role-based access control: Cull how access to the IoT hub is managed, whether shared access policies are immune or merely role-based access control is supported. For more information, see Control access to IoT Hub by using Azure Agile Directory.

    • Device-to-deject partitions: This property relates the device-to-cloud messages to the number of simultaneous readers of the letters. Most hubs demand only four partitions.

  7. Select Next: Tags to proceed to the next screen.

    Tags are name/value pairs. Yous can assign the same tag to multiple resource and resources groups to categorize resources and consolidate billing. In this document, you won't be adding any tags. For more data, encounter Use tags to organize your Azure resources.

    Assign tags for the hub using the Azure portal.

  8. Select Adjacent: Review + create to review your choices. You encounter something similar to this screen, but with the values y'all selected when creating the hub.

    Review information for creating the new hub.

  9. Select Create to start the deployment of your new hub. Your deployment will exist in progress a few minutes while the hub is being created. Once the deployment is complete, select Become to resource to open the new hub.

Register a new device in the IoT hub

In this section, you create a device identity in the identity registry in your IoT hub. A device cannot connect to a hub unless it has an entry in the identity registry. For more data, see the IoT Hub developer guide.

  1. In your IoT hub navigation carte du jour, open Devices, then select Add Device to add together a device in your IoT hub.

    Screen capture that shows how to create a device identity in the portal

  2. In Create a device, provide a proper noun for your new device, such as myDeviceId, and select Save. This action creates a device identity for your IoT hub. Leave Auto-generate keys checked and so that the primary and secondary keys volition be generated automatically.

    Screen capture that shows how to add a new device

    Important

    The device ID may exist visible in the logs collected for client support and troubleshooting, so brand certain to avoid whatsoever sensitive information while naming it.

  3. Subsequently the device is created, open the device from the listing in the Devices pane. Copy the Principal Connexion String. This connection string is used by device code to communicate with the hub.

    By default, the keys and connectedness strings are masked as they are sensitive information. If y'all click the eye icon, they are revealed. Information technology is non necessary to reveal them to copy them with the copy button.

    Screen capture that shows the device connection string

Note

The IoT Hub identity registry only stores device identities to enable secure access to the IoT hub. It stores device IDs and keys to use as security credentials, and an enabled/disabled flag that yous can use to disable access for an individual device. If your application needs to store other device-specific metadata, it should use an awarding-specific store. For more information, come across IoT Hub programmer guide.

Associate an Azure Storage account to IoT Hub

To upload files from a device, you lot must have an Azure Storage account and Azure Blob Storage container associated with your IoT hub. Once you associate the storage account and container with your IoT hub, your IoT hub can provide the elements of a SAS URI when requested by a device. The device tin can and so apply these elements to construct the SAS URI that it uses to cosign with Azure Storage and upload files to the hulk container.

To acquaintance an Azure Storage account with your IoT hub:

  1. Under Hub settings, select File upload on the left-pane of your IoT hub.

    Screen capture showing select file upload settings from the portal.

  2. On the File upload pane, select Azure Storage Container. For this article, it's recommended that your storage account and IoT Hub be located in the same region.

    • If y'all already take a storage account you want to utilise, select information technology from the list.

    • To create a new storage account, select +Storage account. Provide a name for the storage business relationship and make certain the Location is set to the same region every bit your IoT hub, and so select OK. The new account is created in the same resource group every bit your IoT hub. When the deployment completes, select the storage account from the list.

    After you select the storage business relationship, the Containers pane opens.

  3. On the Containers pane, select the hulk container.

    • If you already accept a blob container you want to employ, select it from the listing and click Select.

    • To create a new blob container, select + Container. Provide a proper noun for the new container. For the purposes of this article, you can leave all other fields at their default. Select Create. When the deployment completes, select the container from the list and click Select.

  4. Dorsum on the File upload pane, make sure that file notifications are prepare to On. You can leave all other settings at their defaults. Select Save and await for the settings to complete before moving on to the next section.

    Screen capture showing confirm file upload settings in the portal.

For more detailed instructions on how to create an Azure Storage account, come across Create a storage account. For more detailed instructions on how to associate a storage account and blob container with an IoT hub, see Configure file uploads using the Azure portal.

Upload file from a device app

In this commodity, y'all'll use a sample from the Azure IoT C# samples repository yous downloaded earlier every bit the device app. You can open the files below using Visual Studio, Visual Studio Code, or a text editor of your choice.

The sample is located in the azure-iot-samples-csharp-principal\iot-hub\Samples\device\FileUploadSample nether the binder where you extracted the Azure IoT C# samples.

Examine the lawmaking in FileUpLoadSample.cs. This file contains the main sample logic. Afterward creating an IoT Hub device client, information technology follows the standard iii-role procedure for uploading files from a device:

  1. The lawmaking calls the GetFileUploadSasUriAsync method on the device customer to get a SAS URI from the IoT hub:

                      var fileUploadSasUriRequest = new FileUploadSasUriRequest {     BlobName = fileName };  // Lines removed for clarity  FileUploadSasUriResponse sasUri = expect _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest); Uri uploadUri = sasUri.GetBlobUri();

  2. The code uses the SAS URI to upload the file to Azure storage. In this sample, it uses the SAS URI to create an Azure storage block hulk customer and uploads the file:

                      var blockBlobClient = new BlockBlobClient(uploadUri); await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());

  3. The code notifies the IoT hub that it has completed the upload. This tells the IoT hub that it can release resource associated with the upload (the SAS URI). If file upload notifications are enabled, the IoT hub will transport a notification message to backend services.

                      var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification {     // Mandatory. Must exist the same value as the correlation id returned in the sas uri response     CorrelationId = sasUri.CorrelationId,      // Mandatory. Volition exist present when service client receives this file upload notification     IsSuccess = true,      // Optional, user defined status code. Will exist nowadays when service client receives this file upload notification     StatusCode = 200,      // Optional, user-defined condition description. Will be present when service client receives this file upload notification     StatusDescription = "Success" };  await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

If y'all examine the parameter.cs file, you'll see that:

  • The sample requires yous to pass a parameter, p, which takes a device connectedness string.

  • Past default, the device sample uses the MQTT protocol to communicate with IoT Hub. Yous can utilize the parameter t to alter this send protocol. Exist aware that, regardless of this choice, the Azure blob client always uses HTTPS every bit the protocol to upload the file Azure storage.

Go the IoT hub connection string

In this article, yous create a backend service to receive file upload notification messages from your IoT hub. To receive file upload notification letters, your service needs the service connect permission. By default, every IoT Hub is created with a shared access policy named service that grants this permission.

To become the IoT Hub connectedness string for the service policy, follow these steps:

  1. In the Azure portal, select Resource groups. Select the resource group where your hub is located, and and then select your hub from the list of resources.

  2. On the left-side pane of your IoT hub, select Shared access policies.

  3. From the list of policies, select the service policy.

  4. Under Shared admission keys, select the copy icon for the Main connection string and salve the value.

Screenshot that shows how to retrieve the connection string

For more than information about IoT Hub shared access policies and permissions, see Access control and permissions.

Receive a file upload notification

In this section, you create a C# console app that receives file upload notification messages from your IoT hub.

  1. Open a command window and go to the folder where yous desire to create the projection. Create a folder named ReadFileUploadNotifications and change directories to that binder.

                      mkdir ReadFileUploadNotification cd ReadFileUploadNotification

  2. Run the following command to create a C# console project. After running the command, the folder will comprise a Programme.cs file and a ReadFileUploadNotification.csproj file.

                      dotnet new console --linguistic communication c#

  3. Run the following command to add the Microsoft.Azure.Devices parcel to the projection file. This parcel is the Azure IoT .NET service SDK.

                      dotnet add together package Microsoft.Azure.Devices

  4. Open the Program.cs file and add the following statement at the top of the file:

                      using Microsoft.Azure.Devices;

  5. Add together the following fields to the Programme class. Replace the {iot hub connection string} placeholder value with the IoT hub connection cord that yous copied previously in Go the IoT hub connectedness string:

                      static ServiceClient serviceClient; static string connectionString = "{iot hub connection cord}";

  6. Add the following method to the Program class:

                      private async static void ReceiveFileUploadNotificationAsync() {     var notificationReceiver = serviceClient.GetFileNotificationReceiver();     Console.WriteLine("\nReceiving file upload notification from service");     while (true)     {         var fileUploadNotification = await notificationReceiver.ReceiveAsync();         if (fileUploadNotification == zero) continue;         Console.ForegroundColor = ConsoleColor.Yellowish;         Panel.WriteLine("Received file upload notification: {0}",            string.Join(", ", fileUploadNotification.BlobName));         Console.ResetColor();         await notificationReceiver.CompleteAsync(fileUploadNotification);     } }

    Notation this receive pattern is the same one used to receive cloud-to-device messages from the device app.

  7. Finally, supercede the lines in the Principal method with the following:

                      Console.WriteLine("Receive file upload notifications\due north"); serviceClient = ServiceClient.CreateFromConnectionString(connectionString); ReceiveFileUploadNotificationAsync(); Console.WriteLine("Press Enter to exit\n"); Console.ReadLine();

Run the applications

Now you lot're ready to run the applications.

  1. First, run the service app to receive file upload notifications from the IoT hub. At your command prompt in the ReadFileUploadNotification binder, run the following commands:

                      dotnet restore dotnet run

    The app starts and waits for a file upload notification from your IoT hub:

                      Receive file upload notifications   Receiving file upload notification from service Press Enter to exit

  2. Next, run the device app to upload the file to Azure storage. Open a new control prompt and modify folders to the azure-iot-samples-csharp-principal\iot-hub\Samples\device\FileUploadSample under the folder where you expanded the Azure IoT C# samples. Run the following commands. Replace the {Your device connexion string} placeholder value in the second command with the device connection cord you copied previously in Register a new device in the IoT hub.

                      dotnet restore dotnet run --p "{Your device connection string}"

    The following output is from the device app after the upload has completed:

                                          Uploading file TestPayload.txt   Getting SAS URI from IoT Hub to use when uploading the file...   Successfully got SAS URI (https://contosostorage.blob.core.windows.internet/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub   Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication   Successfully uploaded the file to Azure Storage   Notified IoT Hub that the file upload succeeded and that the SAS URI can exist freed.   Time to upload file: 00:00:01.5077954.   Done.

  3. Notice that the service app shows that it has received the file upload notification:

                      Receive file upload notifications   Receiving file upload notification from service Press Enter to exit  Received file upload notification: myDeviceId/TestPayload.txt

Verify the file upload

You can use the portal to view the uploaded file in the storage container you configured:

  1. Navigate to your storage account in Azure portal.

  2. On the left pane of your storage account, select Containers.

  3. Select the container you uploaded the file to.

  4. Select the binder named afterwards your device.

  5. Select the blob that you uploaded your file to. In this article, it's the hulk named TestPayload.txt.

    Screenshot of selecting the uploaded file in the Azure portal.

  6. View the hulk properties on the folio that opens. You tin select Download to download the file and view its contents locally.

Adjacent steps

In this tutorial, yous learned how to use the file upload feature of IoT Hub to simplify file uploads from devices. You lot can continue to explore this characteristic with the following manufactures:

  • Overview of file uploads with IoT Hub

  • Configure IoT Hub file uploads

  • Azure blob storage documentation

  • Azure hulk storage API reference

  • Azure IoT SDKs