Caricare file da un dispositivo al cloud con l'hub IoT (.NET)

Questo articolo illustra come caricare funzionalità di caricamento di file di hub IoT caricare un file nell'archiviazione BLOB di Azure usando un dispositivo e gli SDK del servizio .NET di Azure IoT.

L'articolo Invia dati di telemetria da un dispositivo a un hub IoT guida introduttiva e Invia messaggi da cloud a dispositivo con hub IoT mostra la funzionalità di messaggistica da dispositivo a cloud e da cloud a dispositivo di hub IoT. L'articolo Configura routing messaggi con hub IoT mostra un modo per archiviare in modo affidabile i messaggi da dispositivo a cloud nell'archiviazione BLOB di Microsoft Azure. Tuttavia, in alcuni scenari, non è possibile eseguire facilmente il mapping dei dati inviati ai dispositivi nei messaggi da dispositivo a cloud relativamente piccoli che hub IoT accetta. Ad esempio:

  • Video
  • File di grandi dimensioni che contengono immagini
  • Dati di vibrazione campionati ad alta frequenza
  • Qualche tipo di dati pre-elaborati

Questi file vengono in genere elaborati in batch nel cloud usando strumenti come Azure Data Factory o lo stack Hadoop. Quando è necessario caricare i file da un dispositivo, è comunque possibile usare la sicurezza e affidabilità dell'hub IoT. Questo articolo illustra i passaggi da eseguire.

Alla fine di questo articolo si eseguono due app console .NET:

  • FileUploadSample. Questa app per dispositivi carica un file nell'archiviazione usando un URI di firma di accesso condiviso fornito dall'hub IoT. Questa app verrà eseguita dal repository AZURE IoT C# SDK scaricato nei prerequisiti.

  • ReadFileUploadNotification. Questa app del servizio riceve notifiche di caricamento file dall'hub IoT. Si creerà questa app.

Nota

hub IoT supporta molte piattaforme e linguaggi di dispositivo (tra cui C, Java, Python e JavaScript) tramite SDK del dispositivo IoT di Azure. Fare riferimento al Centro per sviluppatori IoT di Azure per informazioni su come connettere il dispositivo a hub IoT di Azure.

Importante

Le funzionalità di caricamento dei file nei dispositivi che usano l'autenticazione dell'autorità di certificazione X.509 sono in anteprima pubblica e la modalità di anteprima deve essere abilitata. È disponibile a livello generale nei dispositivi che usano l'autenticazione di identificazione personale X.509 o l'attestazione del certificato X.509 con il servizio Provisioning dispositivi di Azure. Per altre informazioni sull'autenticazione X.509 con hub IoT, vedere Certificati X.509 supportati.

Prerequisiti

  • Un hub IoT. Crearne uno con l'interfaccia della riga di comando o il portale di Azure.

  • Dispositivo registrato. Registrare una nella portale di Azure.

  • Le applicazioni di esempio eseguite in questo articolo vengono scritte usando C# con .NET Core.

    Scaricare .NET Core SDK per più piattaforme da .NET.

    Verificare la versione corrente di .NET Core SDK nel computer di sviluppo usando il comando seguente:

    dotnet --version
    
  • Scaricare Azure IoT C# SDK da Scaricare l'esempio ed estrarre l'archivio ZIP.

  • La porta 8883 deve essere aperta nel firewall. L'esempio in questo articolo usa il protocollo MQTT, che comunica sulla porta 8883. Questa porta potrebbe essere bloccata in alcuni ambienti di rete aziendali e didattici. Per altre informazioni e soluzioni alternative per questo problema, vedere Connettersi all'hub IoT (MQTT).

Associare un account di archiviazione di Azure all'hub IoT

Per caricare file da un dispositivo, è necessario avere un account di archiviazione di Azure e Archiviazione BLOB di Azure contenitore associato all'hub IoT. Dopo aver associato l'account di archiviazione e il contenitore all'hub IoT, l'hub IoT può fornire gli elementi di un URI di firma di accesso condiviso quando richiesto da un dispositivo. Il dispositivo può quindi usare questi elementi per costruire l'URI di firma di accesso condiviso usato per eseguire l'autenticazione con Archiviazione di Azure e caricare file nel contenitore BLOB.

Per associare un account di Archiviazione di Azure all'hub IoT:

  1. In Impostazioni hub selezionare Caricamento file nel riquadro sinistro dell'hub IoT.

    Acquisizione schermata che mostra le impostazioni di caricamento dei file dal portale.

  2. Nel riquadro Caricamento file selezionare Azure Storage Container. Per questo articolo, è consigliabile che l'account di archiviazione e hub IoT si trovi nella stessa area.

    • Se si dispone già di un account di archiviazione che si vuole usare, selezionarlo dall'elenco.

    • Per creare un nuovo account di archiviazione, selezionare +Account di archiviazione. Specificare un nome per l'account di archiviazione e assicurarsi che la posizione sia impostata sulla stessa area dell'hub IoT e quindi selezionare OK. Il nuovo account viene creato nello stesso gruppo di risorse dell'hub IoT. Al termine della distribuzione, selezionare l'account di archiviazione dall'elenco.

    Dopo aver selezionato l'account di archiviazione, verrà aperto il riquadro Contenitori .

  3. Nel riquadro Contenitori selezionare il contenitore BLOB.

    • Se si dispone già di un contenitore BLOB che si vuole usare, selezionarlo dall'elenco e fare clic su Seleziona.

    • Per creare un nuovo contenitore BLOB, selezionare + Contenitore. Specificare un nome per il nuovo contenitore. Ai fini di questo articolo, è possibile lasciare tutti gli altri campi per impostazione predefinita. Selezionare Crea. Al termine della distribuzione, selezionare il contenitore dall'elenco e fare clic su Seleziona.

  4. Tornare al riquadro Caricamento file , assicurarsi che le notifiche dei file siano impostate su Attiva. È possibile lasciare tutte le altre impostazioni alle impostazioni predefinite. Selezionare Salva e attendere il completamento delle impostazioni prima di passare alla sezione successiva.

    Acquisizione schermata che mostra le impostazioni di caricamento del file nel portale.

Per istruzioni più dettagliate su come creare un account di archiviazione di Azure, vedere Creare un account di archiviazione. Per istruzioni più dettagliate su come associare un account di archiviazione e un contenitore BLOB a un hub IoT, vedere Configurare i caricamenti di file usando la portale di Azure.

Caricare file da un'app per dispositivi

In questo articolo viene usato un esempio dal repository AZURE IoT C# SDK scaricato in precedenza come app per dispositivi. È possibile aprire i file seguenti usando Visual Studio, Visual Studio Code o un editor di testo a scelta.

L'esempio si trova in azure-iot-sdk-csharp/iothub/device/samples/started/FileUploadSample nella cartella in cui è stato estratto Azure IoT C# SDK.

Esaminare il codice in FileUpLoadSample.cs. Questo file contiene la logica di esempio principale. Dopo aver creato un client del dispositivo hub IoT, segue la procedura standard di tre parti per il caricamento di file da un dispositivo:

  1. Il codice chiama il metodo GetFileUploadSasUriAsync nel client del dispositivo per ottenere un URI di firma di accesso condiviso dall'hub IoT:

    var fileUploadSasUriRequest = new FileUploadSasUriRequest
    {
        BlobName = fileName
    };
    
    // Lines removed for clarity
    
    FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
    Uri uploadUri = sasUri.GetBlobUri();
    
  2. Il codice usa l'URI di firma di accesso condiviso per caricare il file nell'archiviazione di Azure. In questo esempio usa l'URI di firma di accesso condiviso per creare un client BLOB a blocchi di archiviazione di Azure e carica il file:

    var blockBlobClient = new BlockBlobClient(uploadUri);
    await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());
    
  3. Il codice notifica all'hub IoT che ha completato il caricamento. Questo indica all'hub IoT che può rilasciare risorse associate al caricamento (l'URI di firma di accesso condiviso). Se le notifiche di caricamento dei file sono abilitate, l'hub IoT invierà un messaggio di notifica ai servizi back-end.

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

Se si esamina il file parameter.cs , si noterà che:

  • L'esempio richiede di passare un parametro, p, che accetta una stringa di connessione del dispositivo.

  • Per impostazione predefinita, l'esempio di dispositivo usa il protocollo MQTT per comunicare con hub IoT. È possibile usare il parametro t per modificare questo protocollo di trasporto. Tenere presente che, indipendentemente da questa selezione, il client BLOB di Azure usa sempre HTTPS come protocollo per caricare il file di Archiviazione di Azure.

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end per ricevere messaggi di notifica di caricamento file dall'hub IoT. Per ricevere messaggi di notifica del caricamento di file, è necessario che il servizio disponga dell'autorizzazione di connessione al servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.

Per ottenere la stringa di connessione dell'hub IoT per i criteri del servizio, seguire questa procedura:

  1. Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.

  2. Nel riquadro sinistro dell'hub IoT selezionare Criteri di accesso condiviso.

  3. Dall'elenco dei criteri selezionare i criteri del servizio.

  4. Copiare la stringa di connessione primaria e salvare il valore.

Screenshot che mostra come recuperare la stringa di connessione dal hub IoT nel portale di Azure.

Per altre informazioni sui criteri di accesso condiviso e sulle autorizzazioni dell'hub IoT, vedere Controllo dell'accesso e autorizzazioni.

Ricevere la notifica di caricamento di un file

In questa sezione viene creata un'app console C# che riceve messaggi di notifica di caricamento file dall'hub IoT.

  1. Aprire una finestra di comando e passare alla cartella in cui si vuole creare il progetto. Creare una cartella denominata ReadFileUploadNotifications e passare a tale cartella.

    mkdir ReadFileUploadNotification
    cd ReadFileUploadNotification
    
  2. Eseguire il comando seguente per creare un progetto console C#. Dopo aver eseguito il comando, la cartella conterrà un file Program.cs e un file ReadFileUploadNotification.csproj .

    dotnet new console --language c#
    
  3. Eseguire il comando seguente per aggiungere il pacchetto Microsoft.Azure.Devices al file di progetto. Questo pacchetto è l'SDK del servizio .NET di Azure IoT.

    dotnet add package Microsoft.Azure.Devices
    
  4. Aprire il file Program.cs e aggiungere l'istruzione seguente all'inizio del file:

    using Microsoft.Azure.Devices;
    
  5. Aggiungere i campi seguenti alla classe Program . Sostituire il valore segnaposto {iot hub connection string} con la stringa di connessione dell'hub IoT copiata in precedenza in Ottenere la stringa di connessione dell’hub IoT:

    static ServiceClient serviceClient;
    static string connectionString = "{iot hub connection string}";
    
  6. Aggiungere il metodo seguente alla classe Program :

    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 == null) continue;
            Console.ForegroundColor = ConsoleColor.Yellow;
            Console.WriteLine("Received file upload notification: {0}", 
              string.Join(", ", fileUploadNotification.BlobName));
            Console.ResetColor();
            await notificationReceiver.CompleteAsync(fileUploadNotification);
        }
    }
    

    Si noti che il modello di ricezione è identico a quello usato per ricevere messaggi da cloud a dispositivo dall'app per dispositivo.

  7. Sostituire infine le righe nel metodo Main con quanto segue:

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

Eseguire le applicazioni

A questo momento si è pronti per eseguire le applicazioni.

  1. Eseguire prima di tutto l'app del servizio per ricevere notifiche di caricamento file dall'hub IoT. Al prompt dei comandi nella cartella ReadFileUploadNotification eseguire i comandi seguenti:

    dotnet restore
    dotnet run
    

    L'app avvia e attende una notifica di caricamento di file dall'hub IoT:

    Receive file upload notifications
    
    
    Receiving file upload notification from service
    Press Enter to exit
    
  2. Eseguire quindi l'app per dispositivo per caricare il file in Archiviazione di Azure. Aprire un nuovo prompt dei comandi e passare a azure-iot-sdk-csharp\iothub\device\samples\getting started\FileUploadSample nella cartella in cui è stato espanso Azure IoT C# SDK. Eseguire i comandi seguenti. Sostituire il {Your device connection string} valore segnaposto nel secondo comando con la stringa di connessione del dispositivo visualizzata quando è stato registrato un dispositivo nel hub IoT.

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

    L'output seguente proviene dall'app per dispositivi dopo il completamento del caricamento:

      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.net/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 be freed.
      Time to upload file: 00:00:01.5077954.
      Done.
    
  3. Si noti che l'app del servizio mostra che ha ricevuto la notifica di caricamento file:

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

Verificare il caricamento del file

Per visualizzare il file caricato nel contenitore di archiviazione configurato, è possibile usare il portale:

  1. Passare all'account di archiviazione in portale di Azure.

  2. Nel riquadro sinistro dell'account di archiviazione selezionare Contenitori.

  3. Selezionare il contenitore in cui è stato caricato il file.

  4. Selezionare la cartella denominata dopo il dispositivo.

  5. Selezionare il BLOB in cui è stato caricato il file. In questo articolo si tratta del BLOB denominato TestPayload.txt.

    Screenshot della selezione del file caricato nel portale di Azure.

  6. Visualizzare le proprietà del BLOB nella pagina visualizzata. È possibile selezionare Scarica per scaricare il file e visualizzarne il contenuto in locale.

Passaggi successivi

In questo articolo si è appreso come usare la funzionalità di caricamento di file di hub IoT per semplificare i caricamenti di file dai dispositivi. È possibile continuare a esplorare questa funzionalità con gli articoli seguenti: