Condividi tramite

Caricare file con l'hub IoT

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

Per caricare file di grandi dimensioni da un dispositivo, è comunque possibile usare la sicurezza e l'affidabilità dell'hub IoT. Invece di negoziare i messaggi tramite se stesso, l'hub IoT funge da dispatcher per un account di archiviazione di Azure associato. L'hub IoT può anche inviare notifiche ai servizi back-end appena un dispositivo termina un caricamento dei file.

Se è necessaria 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) per ogni caricamento per un contenitore BLOB e un account di archiviazione di Azure configurati per il caricamento di file dall'hub. L'uso dei caricamenti di file con l'hub IoT prevede tre operazioni:

  • Configurazione di un account di archiviazione di Azure e di un contenitore BLOB nell'hub IoT.
  • Caricamento di file dai dispositivi.
  • Facoltativamente, è possibile notificare i caricamenti di file completati ai servizi back-end.

Prima di poter usare la funzionalità di caricamento di 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 dell'hub IoT con Archiviazione di Azure, la durata (TTL) degli URI SAS 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 all'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 SAS e un ID di correlazione nella risposta. L'URI SAS contiene un token SAS per Archiviazione di Azure che concede all'utente l'autorizzazione in lettura/scrittura del dispositivo per il BLOB richiesto nel contenitore BLOB. Per altre informazioni, vedere Dispositivo: Inizializzare un caricamento di file.

  2. Il dispositivo usa l'URI SAS 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 un file usando le API di Archiviazione di Azure.

  3. Al termine del caricamento del file, il dispositivo notifica lo stato di completamento all'hub IoT usando l'ID di correlazione ricevuto dall'hub IoT al momento dell'avvio del caricamento. Per altre informazioni, vedere Dispositivo: Notificare il completamento del caricamento di un file all'hub IoT.

I servizi back-end possono sottoscrivere notifiche di caricamento di file nell'endpoint di notifica del caricamento file per il servizio dell'hub IoT. Se queste notifiche sono state abilitate nell'hub IoT, vengono recapitate all'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 dei file.

Gli SDK per i dispositivi e servizi di Azure IoT supportano completamente il caricamento dei file. Per altre informazioni, vedere Caricamento di file con un SDK.

Quote e limiti per il caricamento di file

L'hub IoT impone limiti per la limitazione del 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, il limite per ogni dispositivo è di 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 all'hub IoT

Per usare le funzionalità di caricamento di 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 in questo contenitore. Per configurare un account di archiviazione e un contenitore BLOB nell'hub IoT, vedere Configurare i caricamenti di file dell'hub IoT. È anche possibile usare le API di gestione dell'hub IoT per configurare i caricamenti di file a livello di codice.

Per impostazione predefinita, l'hub IoT di Azure usa l'autenticazione basata su chiave per connettersi ad Archiviazione di Azure e configurare l'autorizzazione. È 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 in modo sicuro un'identità gestita automaticamente in Microsoft Entra ID.

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 relative notifiche. Le sezioni seguenti elencano tutte le impostazioni disponibili. Alcune di queste impostazioni potrebbero non essere disponibili a seconda del fatto che si usi il portale di Azure, l'interfaccia della riga di comando di Azure, PowerShell o le API di gestione per configurare i caricamenti di file. Assicurarsi di configurare l'impostazione enableFileUploadNotifications se si vuole 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. 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 SAS. 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.

Proprietà Descrizione Intervallo e valore predefinito
storageEndpoints.$default.authenticationType Controlla in che modo l'hub IoT esegue l'autenticazione con Archiviazione di Azure. I valori possibili sono keyBased e identityBased. Impostazione predefinita: keyBased.
storageEndpoints.$default.connectionString 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] per l'identità gestita assegnata dal sistema o 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 del caricamento di 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 SAS generati dall'hub IoT. Intervallo ISO_8601 fino a 48 ore (minimo un minuto). Impostazione predefinita: un'ora.

Impostazioni delle notifiche di 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. Valore booleano. Valore predefinito: False.
fileNotifications.ttlAsIso8601 Durata (TTL) predefinita per le notifiche di caricamento file. Intervallo ISO_8601 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 di Azure IoT. Le guide spiegano 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 SDK per servizi
.NET Sì Sì
Java Sì Sì
Node.js Sì Sì
Python Sì No (non supportato)

Note

L'SDK per dispositivi C usa una singola chiamata sul client del dispositivo per eseguire i caricamenti di file. Per altre informazioni, vedere IoTHubDeviceClient_UploadToBlobAsync() e IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Queste funzioni eseguono tutti gli aspetti del caricamento di file in una singola chiamata: avvio del caricamento, caricamento del file in Archiviazione di Azure e invio di una notifica all'hub IoT al termine dell'operazione. Questa interazione significa che, oltre a qualsiasi protocollo usato dal dispositivo per comunicare con l'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 di creazione dell'URI SAS per il caricamento di file o l'API equivalente in uno degli SDK per dispositivi 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 SAS.

L'hub IoT risponde con un ID di correlazione e gli elementi di un URI SAS 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 di file all'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 SAS che concede l'accesso in lettura/scrittura al BLOB con Archiviazione di Azure. Il token viene generato e firmato dall'hub IoT.

Quando riceve la risposta, il dispositivo:

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

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

    Ad esempio, per i valori restituiti nell'esempio precedente, l'URI SAS è, 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 SAS e sul token SA, 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 di Archiviazione BLOB di Azure o le API equivalenti di Azure Storage SDK per caricare il file nel BLOB in 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 SAS restituito dall'hub IoT nella sezione precedente. L'intestazione x-ms-blob-type indica che questa richiesta si riferisce a 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 indicate nei collegamenti precedenti in questa sezione, è possibile esplorare la documentazione seguente per iniziare:

Dispositivo: Notificare il completamento di un caricamento di file all'hub IoT

Il dispositivo chiama l'API REST di aggiornamento dello stato del caricamento di file o l'API equivalente in uno degli SDK per dispositivi al termine del caricamento del file. Il dispositivo deve aggiornare lo stato del caricamento del file con l'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 SAS iniziale.
isSuccess Valore booleano che indica se il caricamento del file è riuscito.
statusCode Numero intero che rappresenta il codice di stato del caricamento dei file. In genere è costituito da tre cifre; ad esempio 200 o 201.
statusDescription Descrizione dello stato di caricamento dei file.

Quando riceve una notifica del completamento del caricamento di file dal dispositivo, l'hub IoT:

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

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

Servizio: Notifiche di caricamento dei file

Se le notifiche di caricamento di file sono abilitate nell'hub IoT, l'hub genera un messaggio di notifica per i servizi back-end quando riceve una notifica di completamento dei file da un dispositivo. L'hub IoT recapita queste notifiche di caricamento di file tramite un endpoint rivolto al servizio. La semantica di ricezione per le notifiche di caricamento di 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 di file.

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

Ogni messaggio recuperato dall'endpoint di notifica del caricamento di 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 Numero 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 di file per una revisione. successiva.

Passaggi successivi

  • Last updated on