Carregue ficheiros do seu dispositivo para a nuvem com o Hub IoT do Azure (Node.js)

  • Artigo

Este artigo demonstra como carregar arquivos do Hub IoT para carregar um arquivo no armazenamento de blob do Azure, usando Node.js.

Os artigos Enviar telemetria de um dispositivo para um início rápido do hub IoT e Enviar mensagens da nuvem para o dispositivo com o Hub IoT mostram a funcionalidade básica de mensagens de dispositivo para nuvem e de nuvem para dispositivo do Hub IoT. O tutorial Configurar Roteamento de Mensagens com o Hub IoT mostra uma maneira confiável de armazenar mensagens do dispositivo para a nuvem no armazenamento de blobs do Microsoft Azure. No entanto, em alguns cenários, você não pode mapear facilmente os dados que seus dispositivos enviam para as mensagens relativamente pequenas de dispositivo para nuvem que o Hub IoT aceita. Por exemplo:

  • Vídeos
  • Arquivos grandes que contêm imagens
  • Dados de vibração amostrados em alta frequência
  • Alguma forma de dados pré-processados.

Esses arquivos geralmente são processados em lote na nuvem, usando ferramentas como o Azure Data Factory ou a pilha Hadoop . Quando você precisa atualizar arquivos de um dispositivo, ainda pode usar a segurança e a confiabilidade do Hub IoT. Este artigo mostra-lhe como.

No final deste artigo, você executa dois Node.js aplicativos de console:

  • FileUpload.js, que carrega um arquivo para o armazenamento usando um URI SAS fornecido pelo seu hub IoT.

  • FileUploadNotification.js, que recebe notificações de carregamento de arquivos do seu hub IoT.

Nota

O Hub IoT dá suporte a muitas plataformas e linguagens de dispositivo (incluindo C, Java, Python e JavaScript) por meio de SDKs de dispositivo IoT do Azure. Consulte o Azure IoT Developer Center para saber como conectar seu dispositivo ao Hub IoT do Azure.

Importante

A funcionalidade de carregamento de ficheiros em dispositivos que utilizam a autenticação da autoridade de certificação (CA) X.509 está em pré-visualização pública e o modo de pré-visualização tem de estar ativado. Está geralmente disponível em dispositivos que utilizam a autenticação de impressão digital X.509 ou o atestado de certificado X.509 com o Serviço de Aprovisionamento de Dispositivos do Azure. Para saber mais sobre a autenticação X.509 com o Hub IoT, consulte Certificados X.509 suportados.

Pré-requisitos

  • Um hub IoT. Crie um com a CLI ou o portal do Azure.

  • Um dispositivo registado. Registre um no portal do Azure.

  • Node.js versão 10.0.x ou posterior. A versão LTS é recomendada. Você pode baixar Node.js do nodejs.org.

  • A porta 8883 deve estar aberta no firewall. O exemplo de dispositivo neste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).

Associar uma conta de Armazenamento do Azure ao Hub IoT

Para carregar arquivos de um dispositivo, você deve ter uma conta de Armazenamento do Azure e um contêiner de Armazenamento de Blob do Azure associados ao seu hub IoT. Depois de associar a conta de armazenamento e o contêiner ao hub IoT, o hub IoT pode fornecer os elementos de um URI SAS quando solicitado por um dispositivo. O dispositivo pode usar esses elementos para construir o URI SAS que ele usa para autenticar com o Armazenamento do Azure e carregar arquivos no contêiner de blob.

Para associar uma conta de Armazenamento do Azure ao seu hub IoT:

  1. Em Configurações do Hub, selecione Carregamento de arquivo no painel esquerdo do seu hub IoT.

    Captura de tela mostrando as configurações de upload de arquivos selecionados do portal.

  2. No painel Carregamento de arquivo, selecione Contêiner de Armazenamento do Azure. Para este artigo, é recomendável que sua conta de armazenamento e o Hub IoT estejam localizados na mesma região.

    • Se você já tiver uma conta de armazenamento que deseja usar, selecione-a na lista.

    • Para criar uma nova conta de armazenamento, selecione +Conta de armazenamento. Forneça um nome para a conta de armazenamento e verifique se o Local está definido para a mesma região do seu hub IoT e, em seguida, selecione OK. A nova conta é criada no mesmo grupo de recursos do seu hub IoT. Quando a implantação for concluída, selecione a conta de armazenamento na lista.

    Depois de selecionar a conta de armazenamento, o painel Contêineres é aberto.

  3. No painel Contêineres, selecione o contêiner de blob.

    • Se você já tiver um contêiner de blob que deseja usar, selecione-o na lista e clique em Selecionar.

    • Para criar um novo contêiner de blob, selecione + Contêiner. Forneça um nome para o novo contêiner. Para os fins deste artigo, você pode deixar todos os outros campos em seu padrão. Selecione Criar. Quando a implantação for concluída, selecione o contêiner na lista e clique em Selecionar.

  4. De volta ao painel Carregamento de ficheiros, certifique-se de que as notificações de ficheiros estão definidas como Ativado. Você pode deixar todas as outras configurações em seus padrões. Selecione Salvar e aguarde a conclusão das configurações antes de passar para a próxima seção.

    Captura de tela mostrando as configurações de confirmação de upload de arquivos no portal.

Para obter instruções mais detalhadas sobre como criar uma conta de Armazenamento do Azure, consulte Criar uma conta de armazenamento. Para obter instruções mais detalhadas sobre como associar uma conta de armazenamento e um contêiner de blob a um hub IoT, consulte Configurar carregamentos de arquivos usando o portal do Azure.

Carregar um ficheiro a partir de uma aplicação de dispositivo

Nesta seção, você cria um aplicativo de dispositivo para carregar um arquivo no hub IoT. O código é baseado no código disponível no exemplo de upload_to_blob_advanced.js nos exemplos de dispositivo do SDK do Azure IoT Node.js.

  1. Crie uma pasta vazia com o nome fileupload. Na pasta fileupload, crie um ficheiro package.json com o comando seguinte na sua linha de comandos. Aceite todas as predefinições:

    npm init

  2. No prompt de comando na fileupload pasta, execute o seguinte comando para instalar o SDK de dispositivo azure-iot-device , o azure-iot-device-mqtt e os pacotes @azure/storage-blob :

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

  3. Usando um editor de texto, crie um arquivo FileUpload.js na fileupload pasta e copie o código a seguir para ele.

    '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. Salve e feche o arquivo FileUpload.js .

  5. Copie um arquivo de imagem para a fileupload pasta e dê a ele um nome como myimage.png.

  6. Adicione variáveis de ambiente para a cadeia de conexão do dispositivo e o caminho para o arquivo que você deseja carregar. Você obteve a cadeia de conexão do dispositivo quando registrou um dispositivo no hub IoT.

    • Para Windows:

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

    • Para Linux/Bash:

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

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço de back-end para receber mensagens de notificação de carregamento de arquivos do hub IoT criado. Para receber mensagens de notificação de carregamento de arquivos, seu serviço precisa da permissão de conexão de serviço. Por padrão, cada Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Para obter a cadeia de conexão do Hub IoT para a política de serviço , siga estas etapas:

  1. No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos onde o hub está localizado e, em seguida, selecione o hub na lista de recursos.

  2. No painel esquerdo do hub IoT, selecione Políticas de acesso compartilhado.

  3. Na lista de políticas, selecione a política de serviço .

  4. Copie a cadeia de conexão primária e salve o valor.

Captura de tela que mostra como recuperar a cadeia de conexão do seu Hub IoT no portal do Azure.

Para obter mais informações sobre políticas e permissões de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Receber uma notificação de carregamento de ficheiros

Nesta seção, você cria um aplicativo de console Node.js que recebe mensagens de notificação de carregamento de arquivos do Hub IoT.

  1. Crie uma pasta vazia com o nome fileuploadnotification. Na pasta fileuploadnotification, crie um ficheiro package.json com o comando seguinte na sua linha de comandos. Aceite todas as predefinições:

    npm init

  2. No prompt de comando na fileuploadnotification pasta, execute o seguinte comando para instalar o pacote azure-iothub SDK:

    npm install azure-iothub --save

  3. Usando um editor de texto, crie um arquivo FileUploadNotification.js na fileuploadnotification pasta.

  4. Adicione as seguintes require instruções no início do arquivo FileUploadNotification.js :

    'use strict';

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

  5. Leia a cadeia de conexão para seu hub IoT a partir do ambiente:

    const connectionString = process.env.IOT_HUB_CONNECTION_STRING;

  6. Adicione o seguinte código para criar um cliente de serviço a partir da cadeia de conexão:

    const serviceClient = Client.fromConnectionString(connectionString);

  7. Abra o cliente e use a função getFileNotificationReceiver para receber atualizações de status.

    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 você quiser receber notificações de desconexão enquanto estiver ouvindo notificações de upload de arquivo, precisará se registrar 'error' usando receiver.on. Para continuar a receber notificações de carregamento de arquivos, você precisa se reconectar ao Hub IoT usando o serviceClient.open método.

  8. Salve e feche o arquivo FileUploadNotification.js .

  9. Adicione uma variável de ambiente para sua cadeia de conexão do Hub IoT. Você copiou essa cadeia de caracteres anteriormente em Obter a cadeia de conexão do hub IoT.

    • Para Windows:

      set IOT_HUB_CONNECTION_STRING={your iot hub connection string}

    • Para Linux/Bash:

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

Executar as aplicações

Agora você está pronto para executar os aplicativos.

Em um prompt de fileuploadnotification comando na pasta, execute o seguinte comando:

node FileUploadNotification.js

Em um prompt de fileupload comando na pasta, execute o seguinte comando:

node FileUpload.js

A saída a seguir é do aplicativo FileUpload após a conclusão do carregamento:

uploadStreamToBlockBlob success
notifyBlobUploadStatus success

A saída de exemplo a seguir é do aplicativo FileUploadNotification após a conclusão do carregamento:

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

Verificar o upload do arquivo

Você pode usar o portal para exibir o arquivo carregado no contêiner de armazenamento que você configurou:

  1. Navegue até sua conta de armazenamento no portal do Azure.

  2. No painel esquerdo da sua conta de armazenamento, selecione Contêineres.

  3. Selecione o contêiner para o qual você carregou o arquivo.

  4. Selecione a pasta com o nome do seu dispositivo.

  5. Selecione o blob para o qual você carregou seu arquivo. Neste artigo, é o blob com o mesmo nome do seu arquivo.

    Captura de ecrã a mostrar a visualização do ficheiro carregado no portal do Azure.

  6. Exiba as propriedades do blob na página que é aberta. Você pode selecionar Download para baixar o arquivo e visualizar seu conteúdo localmente.

Próximos passos

Neste artigo, você aprendeu como usar o recurso de carregamento de arquivos do Hub IoT para simplificar o carregamento de arquivos de dispositivos. Pode continuar a explorar esta funcionalidade com os seguintes artigos: