Caricare file dal dispositivo al cloud con hub IoT di Azure (.NET)

  • Articolo

Questo articolo illustra come eseguire il caricamento di file di hub IoT caricare un file nell'archivio BLOB di Azure, usando un sdk per dispositivi e servizi .NET di Azure IoT.

L'articolo Inviare dati di telemetria da un dispositivo a un hub IoT e Inviare messaggi da cloud a dispositivo con hub IoT articolo illustra la funzionalità di messaggistica da dispositivo a cloud e da cloud a dispositivo di base di hub IoT. L'articolo Configurare il routing dei messaggi con hub IoT illustra un modo per archiviare in modo affidabile i messaggi da dispositivo a cloud nell'archivio BLOB di Microsoft Azure. In alcuni scenari, tuttavia, non è possibile eseguire facilmente il mapping dei dati inviati dai dispositivi nei messaggi da dispositivo a cloud relativamente piccoli accettati hub IoT. 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. Questo esempio proviene dal repository azure IoT C# SDK scaricato nei prerequisiti.

  • ReadFileUploadNotification. Questa app del servizio riceve notifiche di caricamento file dall'hub IoT. Questa app viene creata.

Nota

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

Importante

La funzionalità di caricamento dei file nei dispositivi che usano l'autenticazione dell'autorità di certificazione X.509 è in anteprima pubblica e la modalità di anteprima deve essere abilitata. È disponibile a livello generale nei dispositivi che usano l'autenticazione con identificazione personale X.509 o l'attestazione del certificato X.509 con il servizio Device Provisioning 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.

  • Un dispositivo registrato. Registrarne uno nel 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 dall'esempio Download 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 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 i file nel contenitore BLOB.

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

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

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

  2. Nel riquadro Caricamentofile selezionare Archiviazione di Azure Contenitore. Per questo articolo, è consigliabile che l'account di archiviazione e hub IoT trovarsi nella stessa area.

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

    • Per creare un nuovo account di archiviazione, selezionare +Archiviazione account. Specificare un nome per l'account di archiviazione e assicurarsi che Località sia impostata sulla stessa area dell'hub IoT, 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 nell'elenco.

    Dopo aver selezionato l'account di archiviazione, viene visualizzato il riquadro Contenitori .

  3. Nel riquadro Contenitori selezionare il contenitore BLOB.

    • Se si ha già un contenitore BLOB che si vuole usare, selezionarlo nell'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 come predefiniti. Seleziona 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 Sì. È possibile lasciare tutte le altre impostazioni predefinite. Selezionare Salva e attendere il completamento delle impostazioni prima di passare alla sezione successiva.

    Acquisizione dello schermo che mostra la conferma delle impostazioni di caricamento dei file nel portale.

Per istruzioni più dettagliate su come creare un account 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 il portale di Azure.

Caricare un file da un'app per dispositivi

In questo articolo si usa un esempio del 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 di propria scelta.

L'esempio si trova in azure-iot-sdk-csharp/iothub/device/samples/getting 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 in 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 in 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 (URI di firma di accesso condiviso). Se le notifiche di caricamento dei file sono abilitate, l'hub IoT invia 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 un dispositivo stringa di connessione.

  • 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. 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 il stringa di connessione primario e salvare il valore.

Screenshot che mostra come recuperare il stringa di connessione dal hub IoT nella 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 i messaggi di notifica di caricamento dei 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 è Azure IoT .NET Service SDK.

    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 è possibile 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 viene avviata 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 alle cartelle in 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 il dispositivo stringa di connessione visualizzato quando è stato registrato un dispositivo nell'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 del 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 in base al 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 nella 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 dei file di hub IoT per semplificare i caricamenti di file dai dispositivi. È possibile continuare a esplorare questa funzionalità con gli articoli seguenti: