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

Questa esercitazione illustra come usare la funzionalità di caricamento file dell'hub IoT con Azure IoT SDK per dispositivi e servizi .NET.

L’argomento di avvio rapido Inviare dati di telemetria da un dispositivo a un hub IoT e l’esercitazione Inviare messaggi da cloud a dispositivo con l'hub IoT illustrano le funzionalità di messaggistica di base da dispositivo a cloud e da cloud a dispositivo dell'hub IoT. L'esercitazione Configurare il routing dei messaggi con l'hub IoT descrive un modo per archiviare in modo affidabile i messaggi da dispositivo a cloud nell'Microsoft Azure BLOB. Tuttavia in alcuni scenari non è possibile mappare facilmente i dati che i dispositivi inviano in messaggi relativamente ridotti da dispositivo a cloud, che l'hub IoT accetta. Ad esempio:

  • File di grandi dimensioni che contengono immagini

  • Video

  • Dati di vibrazione campionati ad alta frequenza

  • Qualche tipo di dati pre-elaborati

Questi dati in genere vengono elaborati in batch nel cloud con strumenti come Azure Data Factory o lo stack Hadoop. Quando è necessario caricare file da un dispositivo, tuttavia, è comunque possibile usare la sicurezza e l'affidabilità dell'hub IoT. Questa esercitazione illustra come.

Al termine di questa esercitazione vengono eseguite 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 esempi C# scaricato nei prerequisiti.

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

Nota

L'hub IoT supporta molte piattaforme e linguaggi per dispositivi, tra cui C, Java, Python e JavaScript, Azure IoT SDK per dispositivi. Vedere il Centro per sviluppatori di IoT di Azure per istruzioni dettagliate su come connettere il dispositivo all'Hub IoT di Azure.

Importante

La funzionalità di caricamento file nei dispositivi che usano l'autenticazione dell'autorità di certificazione (CA) X.509 è in anteprima pubblica e la modalità di anteprima deve essere abilitata. È disponibile a livello generale nei dispositivi che usano l'autenticazione dell'identificazione personale X.509. Per altre informazioni sull'autenticazione X.509 con l'hub IoT, vedere Certificati X.509 supportati.

Prerequisiti

  • Un account Azure attivo. Se non si ha un account, è possibile creare un account gratuito in pochi minuti.

  • Le applicazioni di esempio eseguite in questo articolo vengono scritte usando C#. Per gli Azure IoT C#, è consigliabile avere il .NET Core SDK 3.1 o versione successiva nel computer di sviluppo.

    È possibile scaricare .NET Core SDK per più piattaforme da .NET.

    È possibile verificare la versione corrente del .NET Core SDK nel computer di sviluppo usando il comando seguente:

    dotnet --version
    
  • Scaricare gli esempi di C# per Azure IoT da https://github.com/Azure-Samples/azure-iot-samples-csharp/archive/main.zip ed estrarre l'archivio ZIP.

  • Assicurarsi che la porta 8883 sia 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).

Creare un hub IoT

Questa sezione illustra come creare un hub IoT usando il portale di Azure.

  1. Accedere al portale di Azure.

  2. Nella home page di Azure selezionare il pulsante + Crea una risorsa e quindi immettere Hub IoT nel campo Cerca nel Marketplace.

  3. Nei risultati della ricerca selezionare Hub IoT e quindi fare clic su Crea.

  4. Nella scheda Informazioni di base completare i campi come indicato di seguito:

    • Sottoscrizione Selezionare la sottoscrizione da usare per l'hub.

    • Gruppo di risorse: selezionare un gruppo di risorse o crearne uno nuovo. Per crearne uno nuovo, fare clic su Crea nuovo e specificare il nome da usare. Per usare un gruppo di risorse esistente, selezionarlo. Per altre informazioni, vedere l'articolo su come gestire gruppi di risorse di Azure Resource Manager.

    • Area: selezionare l'area in cui si vuole collocare l'hub. Selezionare la località più vicina. Alcune funzionalità, ad esempio i flussi dei dispositivi dell'hub IoT, sono disponibili solo in aree specifiche. Per queste funzionalità limitate, è necessario selezionare una delle aree supportate.

    • Nome hub IoT: immettere un nome per l'hub. Questo nome deve essere univoco a livello globale, con una lunghezza compresa tra 3 e 50 caratteri alfanumerici. Il nome può includere anche il trattino ( '-' ).

    Importante

    Dato che l'hub IoT sarà individuabile pubblicamente come endpoint DNS, evitare di includere nel nome informazioni personali o sensibili.

    Create a hub in the Azure portal.

  5. Selezionare Avanti: Rete per continuare a creare l'hub.

    Scegliere gli endpoint che i dispositivi possono usare per connettersi all'hub IoT. È possibile selezionare l'impostazione predefinita Endpoint pubblico (tutte le reti) oppure scegliere Endpoint pubblico (intervalli IP selezionati) o Endpoint privato. Accettare l'impostazione predefinita per questo esempio.

    Choose the endpoints that can connect.

  6. Selezionare Avanti: Gestione per continuare a creare l'hub.

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

    In questa schermata è possibile accettare le impostazioni predefinite. Se si preferisce, è possibile modificare uno dei campi seguenti:

    • Piano tariffario e livello di scalabilità: il piano e il livello selezionati. È possibile scegliere tra livelli diversi a seconda del numero di funzionalità che si desidera e della quantità di messaggi che si inviano al giorno tramite la soluzione. Il livello gratuito è utilizzabile a scopo di test e valutazione. Consente la connessione di 500 dispositivi all'hub e un massimo di 8.000 messaggi al giorno. Per ogni sottoscrizione di Azure è possibile creare un solo hub IoT nel livello gratuito.

      Se si sta eseguendo un Avvio rapido per flussi dei dispositivi dell'hub IoT, selezionare il livello gratuito.

    • Unità di hub IoT: Il numero di messaggi consentiti per unità al giorno dipende dal piano tariffario dell'hub. Se ad esempio si vuole che l'hub supporti 700.000 messaggi in ingresso, selezionare due unità del piano S1. Per informazioni dettagliate sulle altre opzioni relative al livello, vedere Scegliere il livello più adatto di hub IoT.

    • Microsoft Defender per IoT:attivare questa opzione per aggiungere un ulteriore livello di protezione dalle minacce a IoT e ai dispositivi. Questa opzione non è disponibile per gli hub del livello gratuito. Altre informazioni sulle raccomandazioni di sicurezza per l'hub IoT in Defender per IoT.

    • Advanced Impostazionipartizioni da dispositivo a cloud: questa proprietà mette in relazione i messaggi da dispositivo a cloud al numero di lettori simultanei dei messaggi. La maggior parte degli hub richiede solo quattro partizioni.

  7. Selezionare Avanti: Tag per passare alla schermata successiva.

    I tag sono coppie nome/valore. È possibile assegnare lo stesso tag a più risorse e gruppi di risorse per classificare le risorse e consolidare la fatturazione. In questo documento non verranno aggiunti tag. Per altre informazioni, vedere Usare tag per organizzare le risorse di Azure.

    Assign tags for the hub using the Azure portal.

  8. Selezionare Avanti: Rivedi e crea per rivedere le scelte effettuate. Viene visualizzata una schermata simile a questa, ma con i valori selezionati durante la creazione dell'hub.

    Review information for creating the new hub.

  9. Selezionare Crea per avviare la distribuzione del nuovo hub. La distribuzione sarà in corso alcuni minuti durante la creazione dell'hub. Al termine della distribuzione, selezionare Vai alla risorsa per aprire il nuovo hub.

Registrare un nuovo dispositivo nell'hub IoT

In questa sezione si creerà un'identità del dispositivo nel registro delle identità dell'hub IoT. Un dispositivo non può connettersi all'hub a meno che non abbia una voce nel registro di identità. Per altre informazioni, vedere la Guida per gli sviluppatori dell'hub IoT.

  1. Nel menu di spostamento dell'hub IoT aprire Dispositivie quindi selezionare Aggiungi dispositivo per aggiungere un dispositivo nell'hub IoT.

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

  2. In Crea un dispositivo, specificare un nome per il nuovo dispositivo, ad esempio myDeviceId, quindi selezionare Salva. In questo modo viene creata un’identità del dispositivo per l'hub IoT. Lasciare selezionata l'opzione Auto-generate keys (Genera automaticamente chiavi) in modo che le chiavi primaria e secondaria siano generate automaticamente.

    Screen capture that shows how to add a new device

    Importante

    L'ID dispositivo può essere visibile nei log raccolti per il supporto tecnico e la risoluzione dei problemi, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.

  3. Dopo aver creato il dispositivo, aprirlo dall'elenco nel riquadro Dispositivi. Copiare la stringa di connessione primaria. Questa stringa di connessione viene usata dal codice del dispositivo per comunicare con l'hub.

    Per impostazione predefinita, le chiavi e le stringhe di connessione vengono mascherate perché sono informazioni riservate. Se si fa clic sull'icona a forma di occhio, vengono rivelati. Non è necessario rivelarli per copiarli con il pulsante copia.

    Screen capture that shows the device connection string

Nota

Il registro di identità dell'hub IoT archivia solo le identità del dispositivo per abilitare l'accesso sicuro all'hub. Archivia gli ID dispositivo e le chiavi da usare come credenziali di sicurezza e un flag di attivazione/disattivazione che consente di disabilitare l'accesso per un singolo dispositivo. Se l'applicazione deve archiviare altri metadati specifici del dispositivo, dovrà usare un archivio specifico dell'applicazione. Per altre informazioni, vedere la Guida per gli sviluppatori dell'hub IoT.

Associare un account di archiviazione di Azure all'hub IoT

Per caricare file da un dispositivo, è necessario avere un account Archiviazione di Azure e un contenitore blob Archiviazione Azure 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 che usa 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 hubselezionare Caricamento file nel riquadro sinistro dell'hub IoT.

    Screen capture showing select file upload settings from the portal.

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

    • Se si ha già un account di archiviazione da usare, selezionarlo dall'elenco.

    • Per creare un nuovo account di archiviazione, selezionare +Archiviazione account. Specificare un nome per l'account di archiviazione e assicurarsi che La 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 dall'elenco.

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

  3. Nel riquadro Contenitori selezionare il contenitore BLOB.

    • Se si ha già un contenitore BLOB da 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 i valori predefiniti per tutti gli altri campi. Selezionare Crea. Al termine della distribuzione, selezionare il contenitore dall'elenco e fare clic su Seleziona.

  4. Nel riquadro Caricamento file assicurarsi che le notifiche dei file siano impostate su Sì. È possibile lasciare le impostazioni predefinite per tutte le altre impostazioni. Selezionare Salva e attendere il completamento delle impostazioni prima di passare alla sezione successiva.

    Screen capture showing confirm file upload settings in the portal.

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 usandoil portale di Azure .

Upload file da un'app per dispositivo

In questo articolo si userà un esempio del repository di esempi Azure IoT C# scaricato in precedenza come app per dispositivo. È 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-samples-csharp-main\iot-hub\Samples\device\FileUploadSample nella cartella in cui sono stati estratti gli esempi Azure IoT C#.

Esaminare il codice in FileUpLoadSample.cs. Questo file contiene la logica di esempio principale. Dopo aver creato un client dispositivo dell'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 in 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 il caricamento è stato completato. Ciò indica all'hub IoT che può rilasciare le risorse associate al caricamento (URI di firma di accesso condiviso). Se le notifiche di caricamento 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 può vedere 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 l'hub IoT. È possibile utilizzare 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 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. In Chiavi di accesso condivisoselezionare l'icona di copia per Stringa di connessione primaria e salvare il valore.

Screenshot that shows how to retrieve the connection string

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 alla 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 è il 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 con la stringa di connessione dell'hub IoT copiata in precedenza {iot hub connection string} in Ottenere la stringa di connessione {iot hub connection string}

    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. Infine, sostituire 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 punto è 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 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 azure-iot-samples-csharp-main\iot-hub\Samples\device\FileUploadSample nella cartella in cui sono stati espansi gli esempi Azure IoT C#. Eseguire i comandi seguenti. Sostituire il valore segnaposto nel secondo comando con la stringa di connessione del dispositivo copiata in precedenza {Your device connection string} in {Your device connection string}

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

    L'output seguente viene restituito dall'app per dispositivo al termine 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 di 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 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 of selecting the uploaded file in the Azure portal.

  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 questa esercitazione si è appreso come usare la funzionalità di caricamento file dell'hub IoT per semplificare i caricamenti di file dai dispositivi. È possibile continuare a esplorare questa funzionalità con gli articoli seguenti: