Caricare file con l'hub IoTUpload files with IoT Hub

Come descritto nell'articolo IoT Hub endpoints (Endpoint dell'hub IoT), un dispositivo può avviare il caricamento di un file inviando una notifica tramite un endpoint per il dispositivo (/devices/{deviceId}/files).As detailed in the IoT Hub endpoints article, a device can initiate a file upload by sending a notification through a device-facing endpoint (/devices/{deviceId}/files). Quando un dispositivo notifica all'hub IoT il completamento di un caricamento, l'hub IoT invia un messaggio di notifica per il caricamento del file tramite l'endpoint per il servizio (/messages/servicebound/filenotifications).When a device notifies IoT Hub that an upload is complete, IoT Hub sends a file upload notification message through the /messages/servicebound/filenotifications service-facing endpoint.

I messaggi non vengono negoziati tramite l'hub IoT, che funge invece da strumento di recapito per un account di archiviazione di Azure associato.Instead of brokering messages through IoT Hub itself, IoT Hub instead acts as a dispatcher to an associated Azure Storage account. Un dispositivo richiede dall'hub IoT un token di archiviazione specifico del file che intende caricare.A device requests a storage token from IoT Hub that is specific to the file the device wishes to upload. Il dispositivo usa l'URI di firma di accesso condiviso per caricare il file nella risorsa di archiviazione e al termine del caricamento invia una notifica di completamento all'hub IoT.The device uses the SAS URI to upload the file to storage, and when the upload is complete the device sends a notification of completion to IoT Hub. L'hub IoT verifica che il completamento del file sia stato completato e quindi aggiunge un messaggio di notifica di caricamento file all'endpoint per il servizio per le notifiche relative ai file.IoT Hub checks the file upload is complete and then adds a file upload notification message to the service-facing file notification endpoint.

Prima di caricare un file in un hub IoT da un dispositivo, è necessario configurare l'hub associando un account di archiviazione di Azure all'hub.Before you upload a file to IoT Hub from a device, you must configure your hub by associating an Azure Storage account to it.

Il dispositivo può quindi inizializzare un'operazione di caricamento e quindi Inviare una notifica all'hub IoT al termine del caricamento.Your device can then initialize an upload and then notify IoT hub when the upload completes. Facoltativamente, quando un dispositivo comunica all'hub IoT che il caricamento è completo, il servizio può generare un messaggio di notifica.Optionally, when a device notifies IoT Hub that the upload is complete, the service can generate a notification message.

Quando usare le autorizzazioniWhen to use

Usare il caricamento di file per inviare file multimediali e batch di telemetria di grandi dimensioni caricati da dispositivi con connessione intermittente o compressi per risparmiare la larghezza di banda.Use file upload to send media files and large telemetry batches uploaded by intermittently connected devices or compressed to save bandwidth.

Vedere Device-to-cloud communication guidance (Indicazioni sulla comunicazione da dispositivo a cloud) in caso di dubbi tra l'uso delle proprietà indicate, dei messaggi da dispositivo a cloud o del caricamento di file.Refer to Device-to-cloud communication guidance if in doubt between using reported properties, device-to-cloud messages, or file upload.

Associare un account di archiviazione di Azure all'hub IoTAssociate an Azure Storage account with IoT Hub

Per usare la funzionalità di caricamento file, è prima necessario collegare un account di archiviazione di Azure all'hub IoT.To use the file upload functionality, you must first link an Azure Storage account to the IoT Hub. Questa attività può essere completata nel portale di Azure oppure a livello di codice con le API REST del provider di risorse dell'hub IoT.You can complete this task either through the Azure portal, or programmatically through the IoT Hub resource provider REST APIs. Dopo l'associazione di un account di archiviazione di Azure all'hub IoT, quando un dispositivo avvia una richiesta di caricamento file il servizio restituisce al dispositivo un URI di firma di accesso condiviso.Once you have associated an Azure Storage account with your IoT Hub, the service returns a SAS URI to a device when the device initiates a file upload request.

Nota

Gli Azure IoT SDKs (SDK di IoT di Azure) gestiscono automaticamente il recupero dell'URI di firma di accesso condiviso, il caricamento del file e la notifica all'hub IoT del completamento del caricamento.The Azure IoT SDKs automatically handle retrieving the SAS URI, uploading the file, and notifying IoT Hub of a completed upload.

Inizializzazione del caricamento di un fileInitialize a file upload

L'hub IoT dispone di un endpoint dedicato in modo specifico ai dispositivi che consente di richiedere un URI di firma di accesso condiviso con cui l'archiviazione possa caricare un file.IoT Hub has an endpoint specifically for devices to request a SAS URI for storage to upload a file. Per avviare il processo di caricamento del file, il dispositivo invia una richiesta POST a {iot hub}.azure-devices.net/devices/{deviceId}/files con il corpo JSON seguente:To initiate the file upload process, the device sends a POST request to {iot hub}.azure-devices.net/devices/{deviceId}/files with the following JSON body:

{
    "blobName": "{name of the file for which a SAS URI will be generated}"
}

L'hub IoT restituisce i dati seguenti, usati dal dispositivo per caricare il file:IoT Hub returns the following data, which the device uses to upload the file:

{
    "correlationId": "somecorrelationid",
    "hostName": "contoso.azure-devices.net",
    "containerName": "testcontainer",
    "blobName": "test-device1/image.jpg",
    "sasToken": "1234asdfSAStoken"
}

Obsoleto: inizializzare un caricamento di file con un'operazione GETDeprecated: initialize a file upload with a GET

Nota

In questa sezione viene descritta la funzionalità obsoleta per indicazioni su come ricevere un URI di firma di accesso condiviso dall'hub IoT.This section describes deprecated functionality for how to receive a SAS URI from IoT Hub. Usare il metodo POST descritto in precedenza.Use the POST method described previously.

Per supportare il caricamento di file, l'hub IoT usa due endpoint REST: uno per ottenere l'URI di firma di accesso condiviso per l'archiviazione e uno per la notifica all'hub IoT del completamento del caricamento.IoT Hub has two REST endpoints to support file upload, one to get the SAS URI for storage and the other to notify the IoT hub of a completed upload. Il dispositivo avvia il processo di caricamento file inviato una richiesta GET all'hub IoT in {iot hub}.azure-devices.net/devices/{deviceId}/files/{filename}.The device initiates the file upload process by sending a GET to the IoT hub at {iot hub}.azure-devices.net/devices/{deviceId}/files/{filename}. L'hub IoT restituisce:The IoT hub returns:

  • Un URI SAS specifico per il file da caricare.A SAS URI specific to the file to be uploaded.
  • Un ID di correlazione da utilizzare dopo il completamento del caricamento.A correlation ID to be used once the upload is completed.

Notifica all'hub IoT del completamento del caricamento di un fileNotify IoT Hub of a completed file upload

Il dispositivo è responsabile del caricamento del file nella risorsa di archiviazione con Azure Storage SDK.The device is responsible for uploading the file to storage using the Azure Storage SDKs. Al termine del caricamento, il dispositivo invia una richiesta POST a {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications con il corpo JSON seguente:When the upload is complete, the device sends a POST request to {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications with the following JSON body:

{
    "correlationId": "{correlation ID received from the initial request}",
    "isSuccess": bool,
    "statusCode": XXX,
    "statusDescription": "Description of status"
}

Il valore di isSuccess è un valore booleano che indica se il file è stato caricato correttamente.The value of isSuccess is a Boolean representing whether the file was uploaded successfully. Il codice di stato per statusCode è lo stato per il caricamento del file nell'archiviazione e statusDescription corrisponde a statusCode.The status code for statusCode is the status for the upload of the file to storage, and the statusDescription corresponds to the statusCode.

Argomenti di riferimento:Reference topics:

Negli argomenti di riferimento seguenti vengono offerte altre informazioni sul caricamento dei file da un dispositivo.The following reference topics provide you with more information about uploading files from a device.

Notifiche di caricamento fileFile upload notifications

Facoltativamente, quando un dispositivo notifica all'hub IoT il completamento di un caricamento, il servizio può generare un messaggio di notifica contenente il nome e la posizione di archiviazione del file.Optionally, when a device notifies IoT Hub that an upload is complete, IoT Hub can generate a notification message that contains the name and storage location of the file.

Come illustrato nella sezione Endpoint, , l'hub IoT recapita le notifiche di caricamento file sotto forma di messaggi tramite un endpoint per servizio (/messages/servicebound/fileuploadnotifications).As explained in Endpoints, IoT Hub delivers file upload notifications through a service-facing endpoint (/messages/servicebound/fileuploadnotifications) as messages. La semantica di ricezione per le notifiche di caricamento file è uguale a quella dei messaggi da cloud a dispositivo e ha lo stesso ciclo di vita dei messaggi.The receive semantics for file upload notifications are the same as for cloud-to-device messages and have the same message lifecycle. Ogni messaggio recuperato dall'endpoint delle notifiche di caricamento file è un record JSON con le proprietà seguenti.Each message retrieved from the file upload notification endpoint is a JSON record with the following properties:

ProprietàProperty DescrizioneDescription
EnqueuedTimeUtcEnqueuedTimeUtc Timestamp che indica quando è stata creata la notifica.Timestamp indicating when the notification was created.
deviceIdDeviceId DeviceId del dispositivo che ha caricato il file.DeviceId of the device which uploaded the file.
BlobUriBlobUri URI del file caricato.URI of the uploaded file.
BlobNameBlobName Nome del file caricato.Name of the uploaded file.
LastUpdatedTimeLastUpdatedTime Timestamp che indica quando è stato eseguito l'ultimo aggiornamento del file.Timestamp indicating when the file was last updated.
BlobSizeInBytesBlobSizeInBytes Dimensioni del file caricato.Size of the uploaded file.

Esempio.Example. Questo esempio illustra il corpo di un messaggio di notifica di caricamento di un messaggio.This example shows the body of a file upload notification message.

{
    "deviceId":"mydevice",
    "blobUri":"https://{storage account}.blob.core.windows.net/{container name}/mydevice/myfile.jpg",
    "blobName":"mydevice/myfile.jpg",
    "lastUpdatedTime":"2016-06-01T21:22:41+00:00",
    "blobSizeInBytes":1234,
    "enqueuedTimeUtc":"2016-06-01T21:22:43.7996883Z"
}

Opzioni di configurazione per le notifiche di caricamento fileFile upload notification configuration options

Ogni hub IoT espone le opzioni di configurazione seguenti per le notifiche di caricamento file.Each IoT hub exposes the following configuration options for file upload notifications:

ProprietàProperty DescrizioneDescription Intervallo e valore predefinitoRange and default
enableFileUploadNotificationsenableFileUploadNotifications Controlla se verranno scritte notifiche di caricamento file nell'endpoint per le notifiche relative ai file.Controls whether file upload notifications are written to the file notifications endpoint. Valore booleano.Bool. Predefinito: True.Default: True.
fileNotifications.ttlAsIso8601fileNotifications.ttlAsIso8601 Durata (TTL) predefinita per le notifiche di caricamento file.Default TTL for file upload notifications. Intervallo ISO_8601 fino a 48 ore (minimo 1 minuto).ISO_8601 interval up to 48H (minimum 1 minute). Predefinito: 1 ora.Default: 1 hour.
fileNotifications.lockDurationfileNotifications.lockDuration Durata del blocco per la coda delle notifiche di caricamento file.Lock duration for the file upload notifications queue. Da 5 a 300 secondi (minimo 5 secondi).5 to 300 seconds (minimum 5 seconds). Predefinito: 60 secondi.Default: 60 seconds.
fileNotifications.maxDeliveryCountfileNotifications.maxDeliveryCount Numero massimo di recapiti per la coda delle notifiche di caricamento file.Maximum delivery count for the file upload notification queue. Da 1 a 100.1 to 100. Predefinito: 100.Default: 100.

Materiale di riferimentoAdditional reference material

Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:Other reference topics in the IoT Hub developer guide include:

  • Endpoint dell'hub IoT illustra i diversi endpoint esposti da ogni hub IoT per operazioni della fase di esecuzione e di gestione.IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and management operations.
  • Quote e limitazioni descrive le quote e i comportamenti di limitazione applicabili al servizio hub IoT.Throttling and quotas describes the quotas and throttling behaviors that apply to the IoT Hub service.
  • Azure IoT SDK per dispositivi e servizi elenca gli SDK nei diversi linguaggi che è possibile usare quando si sviluppano app per dispositivi e servizi che interagiscono con l'hub IoT.Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.
  • Linguaggio di query dell'hub IoT descrive il linguaggio di query che è possibile usare per recuperare informazioni dall'hub IoT sui dispositivi gemelli e sui processi.IoT Hub query language describes the query language you can use to retrieve information from IoT Hub about your device twins and jobs.
  • Supporto di MQTT nell'hub IoT offre altre informazioni sul supporto dell'hub IoT per il protocollo MQTT.IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Passaggi successiviNext steps

In questa esercitazione si è appreso come caricare i file dai dispositivi con l'hub IoT. Altri argomenti di interesse reperibili nella Guida per gli sviluppatori dell'hub IoT:Now you have learned how to upload files from devices using IoT Hub, you may be interested in the following IoT Hub developer guide topics:

Per provare alcuni dei concetti descritti in questo articolo, può essere utile l'esercitazione seguente sull'hub IoT:If you would like to try out some of the concepts described in this article, you may be interested in the following IoT Hub tutorial: