Caricare file dal dispositivo al cloud con hub IoT di Azure (Node.js)

  • Articolo

Questo articolo illustra come caricare file funzionalità di hub IoT caricare un file nell'archivio BLOB di Azure usando Node.js.

La guida introduttiva Inviare dati di telemetria da un dispositivo a un hub IoT e Inviare messaggi da cloud a dispositivo con hub IoT articoli illustrano le funzionalità di messaggistica da dispositivo a cloud e da cloud a dispositivo di hub IoT. L'esercitazione Configurare il routing dei messaggi con hub IoT illustra un modo per archiviare in modo affidabile i messaggi da dispositivo a cloud nell'archivio BLOB di Microsoft Azure. In alcuni scenari, tuttavia, non è possibile eseguire facilmente il mapping dei dati inviati dai dispositivi nei messaggi da dispositivo a cloud relativamente piccoli accettati hub IoT. Ad esempio:

  • Video
  • File di grandi dimensioni che contengono immagini
  • Dati di vibrazione campionati ad alta frequenza
  • Qualche tipo di dati pre-elaborati.

Questi file vengono in genere elaborati in batch nel cloud, usando strumenti come Azure Data Factory o lo stack Hadoop . Quando è necessario caricare file da un dispositivo, è comunque possibile usare la sicurezza e l'affidabilità dell'hub IoT. Questo articolo illustra i passaggi da eseguire.

Alla fine di questo articolo si eseguono due app console Node.js:

  • FileUpload.js, che carica un file nell'archiviazione usando un URI di firma di accesso condiviso fornito dall'hub IoT.

  • FileUploadNotification.js, che riceve le notifiche di caricamento dei file dall'hub IoT.

Nota

hub IoT supporta molte piattaforme e linguaggi per dispositivi (tra cui C, Java, Python e JavaScript) tramite Azure IoT SDK per dispositivi. Fare riferimento al Centro per sviluppatori Azure IoT per informazioni su come connettere il dispositivo a hub IoT di Azure.

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.

Prerequisiti

  • Un hub IoT. Crearne uno con l'interfaccia della riga di comando o il portale di Azure.

  • Un dispositivo registrato. Registrarne uno nel portale di Azure.

  • Node.js 10.0.x o versione successiva. È consigliabile usare la versione LTS. È possibile scaricare Node.js da nodejs.org.

  • La porta 8883 deve essere aperta nel firewall. L'esempio di dispositivo di questo articolo usa il protocollo MQTT, che comunica tramite la 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).

Associare un account di archiviazione di Azure all'hub IoT

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

    Acquisizione schermo che mostra le impostazioni di caricamento dei file dal portale.

  2. Nel riquadro Caricamentofile selezionare Archiviazione di Azure Contenitore. Per questo articolo, è consigliabile che l'account di archiviazione e hub IoT trovarsi nella stessa area.

    • Se si ha già un account di archiviazione che si vuole usare, selezionarlo nell'elenco.

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

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

  3. Nel riquadro Contenitori selezionare il contenitore BLOB.

    • Se si ha già un contenitore BLOB che si vuole usare, selezionarlo nell'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 tutti gli altri campi come predefiniti. Seleziona Crea. Al termine della distribuzione, selezionare il contenitore dall'elenco e fare clic su Seleziona.

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

    Acquisizione dello schermo che mostra la conferma delle impostazioni di caricamento dei file nel portale.

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

Caricare un file da un'app per dispositivi

In questa sezione viene creata un'app per dispositivi per caricare un file nell'hub IoT. Il codice è basato sul codice disponibile nell'esempio di upload_to_blob_advanced.js negli esempi di dispositivi azure IoT Node.js SDK .

  1. Creare una cartella vuota denominata fileupload. Nella cartella fileupload creare un file package.json eseguendo questo comando al prompt dei comandi. Accettare tutte le impostazioni predefinite:

    npm init

  2. Al prompt dei comandi nella fileupload cartella eseguire il comando seguente per installare azure-iot-device Device SDK, azure-iot-device-mqtt e i pacchetti @azure/storage-blob :

    npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

  3. Usando un editor di testo, creare un file FileUpload.js nella fileupload cartella e copiarne il codice seguente.

    'use strict';

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

const {
  AnonymousCredential,
  BlockBlobClient,
  newPipeline
} = require('@azure/storage-blob');

// make sure you set these environment variables prior to running the sample.
const deviceConnectionString = process.env.DEVICE_CONNECTION_STRING;
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);

async function uploadToBlob(localFilePath, client) {
  const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
  if (!blobInfo) {
    throw new errors.ArgumentError('Invalid upload parameters');
  }

  const pipeline = newPipeline(new AnonymousCredential(), {
    retryOptions: { maxTries: 4 },
    telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
    keepAliveOptions: { enable: false }
  });

  // Construct the blob URL to construct the blob client for file uploads
  const { hostName, containerName, blobName, sasToken } = blobInfo;
  const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

  // Create the BlockBlobClient for file upload to the Blob Storage Blob
  const blobClient = new BlockBlobClient(blobUrl, pipeline);

  // Setup blank status notification arguments to be filled in on success/failure
  let isSuccess;
  let statusCode;
  let statusDescription;

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT Hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

  await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);
}

// Create a client device from the connection string and upload the local file to blob storage.
const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

  4. Salvare e chiudere il file FileUpload.js .

  5. Copiare un file di immagine nella fileupload cartella e assegnare un nome, myimage.pngad esempio .

  6. Aggiungere variabili di ambiente per il dispositivo stringa di connessione e il percorso del file da caricare. Il dispositivo stringa di connessione quando è stato registrato un dispositivo nell'hub IoT.

    • Per Windows:

      set DEVICE_CONNECTION_STRING={your device connection string}
set PATH_TO_FILE={your image filepath}

    • Per Linux/Bash:

      export DEVICE_CONNECTION_STRING="{your device connection string}"
export PATH_TO_FILE="{your image filepath}"

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end per ricevere i messaggi di notifica di caricamento dei file dall'hub IoT creato. 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. Copiare il stringa di connessione primario e salvare il valore.

Screenshot che mostra come recuperare il stringa di connessione dal hub IoT nella portale di Azure.

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 Node.js che riceve messaggi di notifica di caricamento file dall'hub IoT.

  1. Creare una cartella vuota denominata fileuploadnotification. Nella cartella fileuploadnotification creare un file package.json eseguendo questo comando al prompt dei comandi. Accettare tutte le impostazioni predefinite:

    npm init

  2. Al prompt dei comandi nella cartella fileuploadnotification eseguire il comando seguente per installare il pacchetto SDK azure-iothub:

    npm install azure-iothub --save

  3. Usando un editor di testo creare un file FileUploadNotification.js nella cartella fileuploadnotification.

  4. Aggiungere le istruzioni require seguenti all'inizio del file FileUploadNotification.js:

    'use strict';

const Client = require('azure-iothub').Client;

  5. Leggere il stringa di connessione per l'hub IoT dall'ambiente:

    const connectionString = process.env.IOT_HUB_CONNECTION_STRING;

  6. Aggiungere il codice seguente per creare un client del servizio dal stringa di connessione:

    const serviceClient = Client.fromConnectionString(connectionString);

  7. Aprire il client e usare la funzione getFileNotificationReceiver per ricevere aggiornamenti sullo stato.

    serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
      if (err) {
        console.error('error getting the file notification receiver: ' + err.toString());
      } else {
        receiver.on('message', function (msg) {
          console.log('File upload from device:')
          console.log(msg.getData().toString('utf-8'));
          receiver.complete(msg, function (err) {
            if (err) {
              console.error('Could not finish the upload: ' + err.message);
            } else {
              console.log('Upload complete');
            }
          });
        });
      }
    });
  }
});

    Nota

    Se si desidera ricevere notifiche di disconnessione durante l'ascolto delle notifiche di caricamento dei file, è necessario eseguire la registrazione 'error' usando receiver.on. Per continuare a ricevere le notifiche di caricamento dei file, è necessario riconossi per hub IoT usando il serviceClient.open metodo .

  8. Salvare e chiudere il file FileUploadNotification.js.

  9. Aggiungere una variabile di ambiente per il hub IoT stringa di connessione. Questa stringa è stata copiata in precedenza in Ottenere l'hub IoT stringa di connessione.

    • Per Windows:

      set IOT_HUB_CONNECTION_STRING={your iot hub connection string}

    • Per Linux/Bash:

      export IOT_HUB_CONNECTION_STRING="{your iot hub connection string}"

Eseguire le applicazioni

A questo momento è possibile eseguire le applicazioni.

Al prompt dei comandi nella cartella fileuploadnotification eseguire il comando seguente:

node FileUploadNotification.js

Al prompt dei comandi nella cartella fileupload eseguire il comando seguente:

node FileUpload.js

L'output seguente proviene dall'app FileUpload al termine del caricamento:

uploadStreamToBlockBlob success
notifyBlobUploadStatus success

L'output di esempio seguente proviene dall'app FileUploadNotification dopo il completamento del caricamento:

Service client connected
File upload from device:
{"deviceId":"myDeviceId","blobUri":"https://{your storage account name}.blob.core.windows.net/device-upload-container/myDeviceId/image.png","blobName":"myDeviceId/image.png","lastUpdatedTime":"2021-07-23T23:27:06+00:00","blobSizeInBytes":26214,"enqueuedTimeUtc":"2021-07-23T23:27:07.2580791Z"}

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 con lo stesso nome del file.

    Screenshot della visualizzazione del file caricato nella portale di Azure.

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