Caricare file con l'hub IoT

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.

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 configurati per il caricamento di file dall'hub. Esistono tre parti per l'uso dei caricamenti di file con hub IoT:

• Configurazione di un account di archiviazione di Azure e di un contenitore BLOB nell'hub IoT.
• Caricamento di file da dispositivi.
• Facoltativamente, notificare ai servizi back-end i 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, queste 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.

Gli SDK per dispositivi e servizi IoT di Azure supportano completamente il caricamento dei file. 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 Quote e limitazioni dell'hub IoT.

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 passano a 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.

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 l'hub IoT di Azure con Archiviazione di Azure. Le identità gestite offrono ai servizi di Azure un'identità gestita automaticamente in Microsoft Entra ID in modo sicuro.

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

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.

hub IoT impostazioni di archiviazione e autenticazione

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. È comunque necessario connettere i dispositivi all'archiviazione usando l'URI di firma di accesso condiviso. Oggi l'URI di firma di accesso condiviso viene generato usando la stringa di connessione.

Per informazioni sulla configurazione del caricamento di file per l'uso dell'autenticazione basata su identità, vedere Configurare il caricamento di file con identità gestite.

Impostazioni di caricamento file

Le impostazioni seguenti controllano i caricamenti dei file dal dispositivo.

Impostazioni di notifica per il caricamento di file

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

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.

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"
}

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"
}

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"
}

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, mantiene 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"
}

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

• Come configurare i caricamenti di file in hub IoT

• Come configurare le identità gestite in hub IoT