Caricare file con l'hub IoT

  • Articolo

Esistono molti scenari in cui non è possibile eseguire facilmente il mapping dei dati del dispositivo nei messaggi da dispositivo a cloud relativamente piccoli accettati hub IoT. Ad esempio, l'invio di file multimediali di grandi dimensioni come video; oppure, inviando batch di telemetria di grandi dimensioni, caricati da dispositivi connessi in modo intermittente o aggregati e compressi per risparmiare larghezza di banda.

Quando è necessario caricare file di grandi dimensioni da un dispositivo, è comunque possibile usare la sicurezza e l'affidabilità di hub IoT. Invece di negoziare i messaggi tramite se stesso, hub IoT funge da dispatcher a un account di archiviazione di Azure associato. hub IoT può anche fornire notifiche ai servizi back-end quando un dispositivo completa un caricamento di file.

Se è necessario assistenza per decidere quando usare le proprietà segnalate, i messaggi da dispositivo a cloud o i caricamenti di file, vedere Indicazioni sulle comunicazioni da dispositivo a cloud.

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.

Panoramica del caricamento di file

Un hub IoT facilita i caricamenti di file dai dispositivi connessi fornendo loro URI di firma di accesso condiviso (SAS) in base al caricamento per un contenitore BLOB e un account di archiviazione di Azure preconfigurati con l'hub. Esistono tre parti per l'uso dei caricamenti di file con hub IoT: preconfigurazione di un account di archiviazione di Azure e di un contenitore BLOB nell'hub IoT, caricamento di file dai dispositivi e, facoltativamente, notifica ai servizi back-end dei caricamenti di file completati.

Prima di poter usare la funzionalità di caricamento file, è necessario associare un account di archiviazione di Azure e un contenitore BLOB all'hub IoT. È anche possibile configurare le impostazioni che controllano la modalità di autenticazione hub IoT con l'archiviazione di Azure, la durata (TTL) degli URI di firma di accesso condiviso che l'hub IoT distribuisce ai dispositivi e le notifiche di caricamento dei file nei servizi back-end. Per altre informazioni, vedere Associare un account di archiviazione di Azure a hub IoT.

I dispositivi seguono un processo in tre passaggi per caricare un file nel contenitore BLOB associato:

  1. Il dispositivo avvia il caricamento del file con l'hub IoT. Passa il nome di un BLOB nella richiesta e ottiene un URI di firma di accesso condiviso e un ID di correlazione restituito. L'URI di firma di accesso condiviso contiene un token di firma di accesso condiviso per l'archiviazione di Azure che concede all'utente l'autorizzazione di lettura/scrittura del dispositivo per il BLOB richiesto nel contenitore BLOB. Per altre informazioni, vedere Device: Initialize a file upload .For more information, see Device: Initialize a file upload.

  2. Il dispositivo usa l'URI di firma di accesso condiviso per chiamare in modo sicuro le API di archiviazione BLOB di Azure per caricare il file nel contenitore BLOB. Per altre informazioni, vedere Dispositivo: Caricare file usando le API di archiviazione di Azure.

  3. Al termine del caricamento del file, il dispositivo invia una notifica all'hub IoT dello stato di completamento usando l'ID di correlazione ricevuto da hub IoT all'avvio del caricamento. Per altre informazioni, vedere Device: Notify hub IoT of a completed file upload .For more information, see Device: Notify hub IoT of a completed file upload.

I servizi back-end possono sottoscrivere notifiche di caricamento file nell'endpoint di notifica di caricamento file dell'hub IoT. Se queste notifiche sono state abilitate nell'hub IoT, vengono recapitate in questo endpoint ogni volta che un dispositivo notifica all'hub che ha completato un caricamento di file. I servizi possono usare queste notifiche per attivare un'ulteriore elaborazione dei dati BLOB. Per altre informazioni, vedere Servizio: Notifiche di caricamento file.

Il caricamento di file è completamente supportato dagli SDK per dispositivi e servizi IoT di Azure. Per altre informazioni, vedere Caricamento di file con un SDK.

Quote e limiti per il caricamento di file

hub IoT impone limiti di limitazione al numero di caricamenti di file che può essere avviato in un determinato periodo. La soglia si basa sullo SKU e sul numero di unità dell'hub IoT. Inoltre, ogni dispositivo è limitato a 10 caricamenti simultanei di file attivi alla volta. Per altre informazioni, vedere hub IoT quote e limitazioni.

Associare un account di archiviazione di Azure a hub IoT

Per usare le funzionalità di caricamento file, è necessario associare un account di archiviazione di Azure e un contenitore BLOB all'hub IoT. Tutti i caricamenti di file dai dispositivi registrati nell'hub IoT verranno caricati in questo contenitore. Per configurare un account di archiviazione e un contenitore BLOB nell'hub IoT, vedere Configurare i caricamenti di file hub IoT usando il portale di Azure, Configurare i caricamenti di file hub IoT tramite l'interfaccia della riga di comando di Azure o Configurare i caricamenti di file hub IoT tramite PowerShell. È anche possibile usare le API di gestione hub IoT per configurare i caricamenti di file a livello di codice.

Se si usa il portale, è possibile creare un account di archiviazione e un contenitore durante la configurazione. In caso contrario, per creare un account di archiviazione, vedere Creare un account di archiviazione nella documentazione di Archiviazione di Azure. Dopo aver creato un account di archiviazione, è possibile vedere come creare un contenitore BLOB nelle guide introduttive di Archiviazione BLOB di Azure. Per impostazione predefinita, hub IoT di Azure usa l'autenticazione basata su chiave per connettersi e autorizzare con Archiviazione di Azure. È anche possibile configurare identità gestite assegnate dall'utente o assegnate dal sistema per autenticare hub IoT di Azure con Archiviazione di Azure. Le identità gestite forniscono ai servizi di Azure un'identità gestita automaticamente in Microsoft Entra ID in modo sicuro. Per informazioni su come configurare le identità gestite, vedere la sezione Configurare il caricamento di file con identità gestite di hub IoT supporto per le identità gestite.

Il caricamento di file è soggetto alle impostazioni del firewall di Archiviazione di Azure. In base alla configurazione di autenticazione, è necessario assicurarsi che i dispositivi possano comunicare con Archiviazione di Azure.

Esistono diverse altre impostazioni che controllano il comportamento dei caricamenti di file e delle notifiche di caricamento dei file. Le sezioni seguenti elencano tutte le impostazioni disponibili. A seconda che si usino le portale di Azure, l'interfaccia della riga di comando di Azure, PowerShell o le API di gestione per configurare i caricamenti di file, alcune di queste impostazioni potrebbero non essere disponibili. Assicurarsi di impostare l'impostazione enableFileUploadNotifications se si desidera inviare notifiche ai servizi back-end al termine del caricamento di un file.

Impostazioni di archiviazione e autenticazione dell'hub Iot

Le impostazioni seguenti associano un account di archiviazione e un contenitore all'hub IoT e controllano la modalità di autenticazione dell'hub con Archiviazione di Azure. Queste impostazioni non influiscono sul modo in cui i dispositivi eseguono l'autenticazione con Archiviazione di Azure. I dispositivi eseguono sempre l'autenticazione con il token di firma di accesso condiviso presentato nell'URI di firma di accesso condiviso recuperato da hub IoT.

Proprietà Descrizione Intervallo e valore predefinito
storageEndpoints.$default.authenticationType Controlla come l'hub IoT esegue l'autenticazione con Archiviazione di Azure. I valori possibili sono keyBased e identityBased. Impostazione predefinita: keyBased.
storageEndpoints.$default.connectionString Il stringa di connessione all'account di archiviazione di Azure da usare per i caricamenti di file. Impostazione predefinita: stringa vuota.
storageEndpoints.$default.containerName Nome del contenitore in cui caricare i file. Impostazione predefinita: stringa vuota.
storageEndpoints.$default.identity Identità gestita da usare per l'autenticazione basata su identità. I valori possibili sono [system] relativi all'identità gestita assegnata dal sistema o a un ID risorsa per un'identità gestita assegnata dall'utente. Il valore non viene usato per l'autenticazione basata su chiave. Impostazione predefinita: null.

Impostazioni di caricamento file

Le impostazioni seguenti controllano i caricamenti dei file dal dispositivo.

Proprietà Descrizione Intervallo e valore predefinito
storageEndpoints.$default.ttlAsIso8601 TTL predefinito per gli URI di firma di accesso condiviso generati da hub IoT. ISO_8601 intervallo fino a 48 ore (minimo un minuto). Impostazione predefinita: un'ora.

Impostazioni di notifica per il caricamento di file

Le impostazioni seguenti controllano le notifiche di caricamento dei file nei servizi back-end.

Proprietà Descrizione Intervallo e valore predefinito
enableFileUploadNotifications Controlla se verranno scritte notifiche di caricamento file nell'endpoint per le notifiche relative ai file. Bool. Valore predefinito: False.
fileNotifications.ttlAsIso8601 Durata (TTL) predefinita per le notifiche di caricamento file. ISO_8601 intervallo fino a 48 ore (minimo un minuto). Impostazione predefinita: un'ora.
fileNotifications.lockDuration Durata del blocco per la coda delle notifiche di caricamento file. Da 5 a 300 secondi Predefinito: 60 secondi.
fileNotifications.maxDeliveryCount Numero massimo di recapiti per la coda delle notifiche di caricamento file. Da 1 a 100. Predefinito: 10.

Caricamento di file con un SDK

Le guide pratiche seguenti forniscono istruzioni dettagliate complete per caricare i file usando gli SDK per dispositivi e servizi azure IoT. Le guide illustrano come usare il portale di Azure per associare un account di archiviazione a un hub IoT. Le guide contengono anche frammenti di codice o fanno riferimento a esempi che consentono di eseguire un caricamento.

Guida pratica Esempio di SDK per dispositivi Esempio di Service SDK
.NET Sì Sì
Java Sì Sì
Node.JS Sì Sì
Python Sì No (non supportato)

Nota

L'SDK per dispositivi C usa una singola chiamata sul client del dispositivo per eseguire caricamenti di file. Per altre informazioni, vedere IoTHubDeviceClient_UploadToBlobAsync() e IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Queste funzioni eseguono tutti gli aspetti del caricamento del file in una singola chiamata: avvio del caricamento, caricamento del file nell'archiviazione di Azure e notifica hub IoT al termine. Questa interazione significa che, oltre a qualsiasi protocollo usato dal dispositivo per comunicare con hub IoT, il dispositivo deve anche essere in grado di comunicare tramite HTTPS con Archiviazione di Azure perché queste funzioni effettuano chiamate alle API di archiviazione di Azure.

Dispositivo: inizializzare un caricamento di file

Il dispositivo chiama l'API REST Create File Upload SAS URI o l'API equivalente in uno degli SDK del dispositivo per avviare un caricamento di file.

Protocolli supportati: HTTPS
Endpoint: {iot hub}.azure-devices.net/devices/{deviceId}/files
Metodo: POST

{
    "blobName":"myfile.txt"
}
Proprietà Descrizione
blobName Nome del BLOB per cui generare l'URI di firma di accesso condiviso.

hub IoT risponde con un ID di correlazione e gli elementi di un URI di firma di accesso condiviso che il dispositivo può usare per l'autenticazione con Archiviazione di Azure. Questa risposta è soggetta ai limiti di limitazione e ai limiti di caricamento per dispositivo dell'hub IoT di destinazione.

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}
Proprietà Descrizione
correlationId Identificatore da usare per il dispositivo durante l'invio della notifica di caricamento del file a hub IoT.
hostName Nome host dell'account di archiviazione di Azure per l'account di archiviazione configurato nell'hub IoT
containerName Nome del contenitore BLOB configurato nell'hub IoT.
blobName Percorso in cui verrà archiviato il BLOB nel contenitore. Il nome è nel formato seguente: {device ID of the device making the request}/{blobName in the request}
sasToken Token di firma di accesso condiviso che concede l'accesso in lettura/scrittura nel BLOB con Archiviazione di Azure. Il token viene generato e firmato da hub IoT.

Quando riceve la risposta, il dispositivo:

  • Salva l'ID di correlazione da includere nella notifica completa di caricamento del file nell'hub IoT al termine del caricamento.

  • Usa le altre proprietà per costruire un URI di firma di accesso condiviso per il BLOB usato per l'autenticazione con Archiviazione di Azure. L'URI di firma di accesso condiviso contiene l'URI della risorsa per il BLOB richiesto e il token di firma di accesso condiviso. Assume il formato seguente: https://{hostName}/{containerName}/{blobName}{sasToken} (la sasToken proprietà nella risposta contiene un carattere iniziale '?'). Le parentesi graffe non sono incluse.

    Ad esempio, per i valori restituiti nell'esempio precedente, l'URI di firma di accesso condiviso è, https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw

    Per altre informazioni sull'URI di firma di accesso condiviso e sul token di firma di accesso condiviso, vedere Creare una firma di accesso condiviso del servizio nella documentazione di Archiviazione di Azure.

Dispositivo: caricare file usando le API di archiviazione di Azure

Il dispositivo usa le API REST Archiviazione BLOB di Azure o le API equivalenti di Azure Storage SDK per caricare il file nel BLOB nell'archiviazione di Azure.

Protocolli supportati: HTTPS

L'esempio seguente mostra una richiesta Put BLOB per creare o aggiornare un BLOB in blocchi di piccole dimensioni. Si noti che l'URI usato per questa richiesta è l'URI di firma di accesso condiviso restituito da hub IoT nella sezione precedente. L'intestazione x-ms-blob-type indica che questa richiesta è per un BLOB in blocchi. Se la richiesta ha esito positivo, Archiviazione di Azure restituisce .201 Created

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

L'uso delle API di archiviazione di Azure esula dall'ambito di questo articolo. Oltre alle API REST di Archiviazione BLOB di Azure collegate in precedenza in questa sezione, è possibile esplorare la documentazione seguente per iniziare:

  • Per altre informazioni sull'uso dei BLOB nell'archiviazione di Azure, vedere la documentazione di Archiviazione BLOB di Azure.

  • Per informazioni sull'uso degli SDK client di archiviazione di Azure per caricare i BLOB, vedere informazioni di riferimento sulle API di Archiviazione BLOB di Azure.

Dispositivo: notifica hub IoT di un caricamento di file completato

Il dispositivo chiama l'API REST Aggiorna stato caricamento file o l'API equivalente in uno degli SDK del dispositivo al termine del caricamento del file. Il dispositivo deve aggiornare lo stato di caricamento del file con hub IoT indipendentemente dal fatto che il caricamento abbia esito positivo o negativo.

Protocolli supportati: HTTPS
Endpoint: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Metodo: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
Proprietà Descrizione
correlationId ID di correlazione ricevuto nella richiesta URI di firma di accesso condiviso iniziale.
isSuccess Valore booleano che indica se il caricamento del file è riuscito.
statusCode Intero che rappresenta il codice di stato del caricamento del file. In genere tre cifre; ad esempio 200 o 201.
statusDescription Descrizione dello stato di caricamento del file.

Quando riceve una notifica di caricamento del file completata dal dispositivo, hub IoT:

  • Attiva una notifica di caricamento di file nei servizi back-end se sono configurate le notifiche di caricamento dei file.

  • Rilascia le risorse associate al caricamento del file. Se hub IoT non riceve una notifica, manterrà le risorse fino alla scadenza del TTL (SAS URI time-to-live) associato al caricamento.

Servizio: notifiche di caricamento file

Se le notifiche di caricamento dei file sono abilitate nell'hub IoT, l'hub genera un messaggio di notifica per i servizi back-end quando riceve una notifica da un dispositivo per il completamento del caricamento di file. hub IoT recapita queste notifiche di caricamento file tramite un endpoint rivolto al servizio. La semantica di ricezione per le notifiche di caricamento dei file è identica a quella dei messaggi da cloud a dispositivo e ha lo stesso ciclo di vita dei messaggi. Gli SDK del servizio espongono le API per gestire le notifiche di caricamento dei file.

Protocolli supportati AMQP, AMQP-WS
Endpoint: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Metodo GET

Ogni messaggio recuperato dall'endpoint di notifica di caricamento file è un record JSON:

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}
Proprietà Descrizione
enqueuedTimeUtc Timestamp che indica quando è stata creata la notifica.
deviceId ID dispositivo del dispositivo che ha caricato il file.
BLOBUri URI del file caricato.
blobName Nome del file caricato. Il nome è nel formato seguente: {device ID of the device}/{name of the blob}
lastUpdatedTime Timestamp che indica quando è stato eseguito l'ultimo aggiornamento del file.
blobSizeInBytes Intero che rappresenta le dimensioni del file caricato in byte.

I servizi possono usare le notifiche per gestire i caricamenti. Ad esempio, possono attivare la propria elaborazione dei dati BLOB, attivare l'elaborazione dei dati BLOB usando altri servizi di Azure o registrare la notifica di caricamento dei file per una revisione successiva.

Passaggi successivi