Compartilhar via


Carregar arquivos de um dispositivo para a nuvem com o Hub IoT do Azure

Este artigo demonstra como:

  • Use os recursos de upload de arquivo do Hub IoT para carregar um arquivo no Armazenamento de Blobs do Azure usando um dispositivo da Internet das Coisas do Azure e SDKs de serviço.
  • Notifique o Hub IoT de que o arquivo foi carregado com êxito e crie um serviço de back-end para receber notificações de upload de arquivo do Hub IoT usando os SDKs do serviço da Internet das Coisas do Azure.

Em alguns cenários, você não pode mapear facilmente os dados que seus dispositivos enviam para as mensagens relativamente pequenas do dispositivo para a nuvem aceitas pelo Hub IoT. Os recursos de upload de arquivo no Hub IoT permitem mover dados grandes ou complexos para a nuvem. Por exemplo:

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

Esses arquivos normalmente são processados em lote na nuvem usando ferramentas como o Azure Data Factory ou a pilha do Hadoop. Quando você precisar carregar arquivos de um dispositivo, ainda poderá usar a segurança e a confiabilidade do Hub IoT. Este artigo mostra como fazer isso.

Este artigo destina-se a complementar os exemplos de SDK executáveis referenciados nele.

Para saber mais, veja:

Importante

A funcionalidade de carregamento de arquivo em dispositivos que usam a autenticação da autoridade de certificação (AC) de certificados X.509 está em versão prévia. Além disso, é necessário habilitar o modo de versão prévia. Geralmente está disponível em dispositivos que usam a autenticação de impressão digital X. 509 ou o atestado de certificado X. 509 com o Serviço de Provisionamento de Dispositivos do Azure. Para saber mais sobre a autenticação X.509 com o Hub IoT, confira Certificados X.509 com suporte.

Pré-requisitos

  • Um hub IoT. Algumas chamadas do SDK exigem a cadeia de conexão primária do Hub IoT; portanto, anote a cadeia de conexão.

  • Um dispositivo registrado. Algumas chamadas do SDK exigem a cadeia de conexão primária do dispositivo; portanto, anote a cadeia de conexão.

  • Permissão do Service Connect do Hub IoT – Para receber mensagens de notificação de upload de arquivo, o seu serviço de back-end precisa da permissão do Service Connect. Por padrão, todo Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão. Para obter mais informações, confira Conectar-se a um hub IoT.

  • Configure o upload de arquivos no hub IoT vinculando uma conta de Armazenamento do Microsoft Azure e um contêiner do Armazenamento de Blobs do Azure. Você pode configurá-los usando o portal do Azure, a CLI do Azure ou o Azure PowerShell.

Visão geral

Estas instruções contêm duas seções:

  • Carregar um arquivo de um aplicativo de dispositivo
  • Receber notificação de upload de arquivo em um aplicativo de back-end

Carregar um arquivo de um aplicativo de dispositivo

Esta seção descreve como carregar um arquivo de um dispositivo para um hub IoT usando a classe DeviceClient no SDK da Internet das Coisas do Azure para .NET.

Siga este procedimento para carregar um arquivo de um dispositivo para o hub IoT:

  1. Conectar-se ao Hub IoT
  2. Obter um URI SAS do hub IoT
  3. Carregar o arquivo no armazenamento do Azure
  4. Notificar o hub IoT do status de upload de arquivo

Conectar-se ao dispositivo

Chame CreateFromConnectionString para se conectar ao dispositivo. Passe a cadeia de conexão primária do dispositivo.

AMQP é o protocolo de transporte padrão.

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

Obter um URI SAS do hub IoT

Chame GetFileUploadSasUriAsync para obter detalhes de upload de arquivo. O URI SAS é usado na próxima etapa para carregar um arquivo de um dispositivo para o Armazenamento de Blobs.

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

Carregar um arquivo no Armazenamento do Microsoft Azure

Para carregar um arquivo no Armazenamento do Microsoft Azure:

  1. Crie um objeto blockBlobClient, passando um URI de upload de arquivo.

  2. Use o método UploadAsync para carregar um arquivo no Armazenamento de Blobs, passando o URI SAS. Opcionalmente, você pode adicionar opções de upload de Blob e parâmetros de token de cancelamento.

O cliente blob do Azure sempre usa HTTPS como o protocolo para carregar o arquivo no Armazenamento do Microsoft Azure.

Neste exemplo, é passado o URI SAS para BlockBlobClient para criar um cliente blob do bloco de Armazenamento do Microsoft Azure e carregar o arquivo:

var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, null, null);

Notificar o hub IoT do status de upload de arquivo

Use CompleteFileUploadAsync para notificar o hub IoT de que o cliente do dispositivo concluiu o upload, passando um objeto FileUploadCompletionNotification. O sinalizador IsSuccess indica se o upload foi ou não bem-sucedido. Após ser notificado, o Hub IoT liberará recursos associados ao upload (o URI SAS).

Se as notificações de upload de arquivo estiverem habilitadas, o Hub IoT enviará uma mensagem de notificação de upload de arquivo para serviços de back-end configurados para notificação de upload de arquivo.

var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
{
    // Mandatory. Must be the same value as the correlation id returned in the sas uri response
    CorrelationId = sasUri.CorrelationId,

    // Mandatory. Will be present when service client receives this file upload notification
    IsSuccess = true,

    // Optional, user defined status code. Will be present when service client receives this file upload notification
    StatusCode = 200,

    // Optional, user-defined status description. Will be present when service client receives this file upload notification
    StatusDescription = "Success"
};

await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

Exemplo de upload de arquivo do SDK

O SDK inclui este exemplo de upload de arquivo.

Receber uma notificação de upload de arquivo em um aplicativo de back-end

Você pode criar um serviço de back-end para receber mensagens de notificação de upload de arquivo do Hub IoT.

A classe ServiceClient contém métodos que os serviços podem usar para receber notificações de upload de arquivo.

Para receber uma notificação de upload de arquivo:

  1. Chame CreateFromConnectionString para se conectar ao hub IoT. Passe a cadeia de conexão primária do hub IoT.
  2. Crie um CancellationToken.
  3. Chame GetFileNotificationReceiver para criar um receptor de notificação.
  4. Use um loop com ReceiveAsync para aguardar a notificação de upload do arquivo.

Por exemplo:

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{IoT hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    if (fileUploadNotification == null) continue;
    Console.ForegroundColor = ConsoleColor.Yellow;
    Console.WriteLine("Received file upload notification: {0}", 
        string.Join(", ", fileUploadNotification.BlobName));
    Console.ResetColor();
    await notificationReceiver.CompleteAsync(fileUploadNotification);
}

Visão geral

Estas instruções contêm duas seções:

  • Carregar um arquivo de um aplicativo de dispositivo
  • Receber notificação de upload de arquivo em um aplicativo de back-end

Carregar um arquivo de um aplicativo de dispositivo

Esta seção descreve como carregar um arquivo de um dispositivo para um hub IoT usando a classe DeviceClient do SDK da Internet das Coisas do Azure para Java.

Siga este procedimento para carregar um arquivo de um dispositivo para o hub IoT:

  1. Conectar-se ao dispositivo
  2. Obter um URI SAS do hub IoT
  3. Carregar o arquivo no Armazenamento do Microsoft Azure
  4. Enviar uma notificação de status de upload de arquivo para o hub IoT

Protocolo de conexão

As operações de upload de arquivo sempre usam HTTPS, mas DeviceClient pode definir o IotHubClientProtocol para outros serviços, como telemetria, método de dispositivo e dispositivo gêmeo.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

Conectar-se ao dispositivo

Instancie DeviceClient para conectar-se ao dispositivo usando a cadeia de conexão primária do dispositivo.

String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Obter um URI SAS do hub IoT

Chame getFileUploadSasUri para obter um objeto FileUploadSasUriResponse.

FileUploadSasUriResponse inclui esses métodos e valores retornados. Os valores retornados podem ser passados para métodos de upload de arquivo.

Método Valor retornado
getCorrelationId() ID de Correlação
getContainerName() Nome do contêiner
getBlobName() Nome de blob
getBlobUri() URI do blob

Por exemplo:

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

Carregar o arquivo no Armazenamento do Microsoft Azure

Passe o ponto de extremidade do URI do blob para BlobClientBuilder.buildclient para criar o objeto BlobClient.

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

Chame uploadFromFile para carregar o arquivo no Armazenamento de Blobs.

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

Enviar uma notificação de status de upload de arquivo para o hub IoT

Envie uma notificação de status de upload para o hub IoT após uma tentativa de upload de arquivo.

Crie um objeto FileUploadCompletionNotification. Passe os status de sucesso do upload do arquivo correlationId e isSuccess. Passe um valor isSuccess true quando o upload de arquivo tiver sido bem-sucedido, e false quando não tiver.

FileUploadCompletionNotification deve ser chamado mesmo quando o upload de arquivo falha. O Hub IoT tem um número fixo de URI SAS permitido para estar ativo a qualquer momento. Depois de terminar o upload de arquivo, você deverá liberar o URI SAS para que outro URI SAS possa ser gerado. Se um URI SAS não for liberado por meio dessa API, ele será liberado eventualmente com base em quanto tempo os URIs SAS estão configuradas para viver em um hub IoT.

Este exemplo passa um status bem-sucedido.

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

Fechar o cliente

Libere os recursos client.

client.closeNow();

Receber uma notificação de upload de arquivo em um aplicativo de back-end

Você pode criar um aplicativo de back-end para receber notificações de upload de arquivo.

Para criar um aplicativo de notificação de upload de arquivo:

  1. Conectar-se ao cliente de serviço do hub IoT
  2. Verificar se há uma notificação de upload de arquivo

A classe ServiceClient contém métodos que os serviços podem usar para receber notificações de upload de arquivo.

Conectar-se ao cliente de serviço do hub IoT

Crie um objeto IotHubServiceClientProtocol. A conexão usa o protocolo AMQPS.

Chame createFromConnectionString para se conectar ao hub IoT. Passe a cadeia de conexão primária do hub IoT.

private static final String connectionString = "{IoT hub primary connection string}";
private static final IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;
ServiceClient sc = ServiceClient.createFromConnectionString(connectionString, protocol);

Verificar o status de upload de arquivo

Para verificar o status de upload de arquivo:

  1. Crie um objeto getFileUploadNotificationReceiver.
  2. Use aberto para se conectar ao hub IoT.
  3. Chame o recebimento para verificar o status de upload do arquivo. Este método retorna um objeto fileUploadNotification. Se um aviso de upload for recebido, você poderá exibir campos de status de upload usando métodos fileUploadNotification.

Por exemplo:

FileUploadNotificationReceiver receiver = sc.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

Exemplos de upload de arquivo do SDK

Há dois exemplos de upload de arquivo Java.

Instalar Pacotes

A biblioteca azure-iot-device deve ser instalada antes de chamar qualquer código relacionado.

pip install azure-iot-device

O pacote azure.storage.blob é usado para executar o upload do arquivo.

pip install azure.storage.blob

Carregar arquivo de um aplicativo de dispositivo

Esta seção descreve como carregar um arquivo de um dispositivo para um hub IoT usando a classe IoTHubDeviceClient do SDK da Internet das Coisas do Azure para Python.

Siga este procedimento para carregar um arquivo de um dispositivo para o hub IoT:

  1. Conectar-se ao dispositivo
  2. Obter informações do Armazenamento de Blobs
  3. Carregar o arquivo no Armazenamento de Blobs
  4. Notificar o hub IoT sobre o status de upload

Importar bibliotecas

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

Conectar-se ao dispositivo

Para se conectar ao dispositivo:

  1. Chame create_from_connection_string para adicionar a cadeia de conexão primária do dispositivo.

  2. Chame a conexão para conectar o cliente do dispositivo.

Por exemplo:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Obter informações do Armazenamento de Blobs

Chame get_storage_info_for_blob para obter informações de um hub IoT sobre uma conta vinculada do Armazenamento do Microsoft Azure. Essas informações incluem nome do host, nome do contêiner, nome do blob e um token SAS. O método get_storage_info_for_blob também retorna um correlation_id, que é usado no método notify_blob_upload_status. correlation_id é a maneira do Hub IoT marcar em qual Blob você está trabalhando.

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

Carregar um arquivo no Armazenamento de Blobs

Para carregar um arquivo no Armazenamento de Blobs:

  1. Use from_blob_url para criar um objeto BlobClient a partir de uma URL de blob.
  2. Chame upload_blob para carregar o arquivo no Armazenamento de Blobs.

Este exemplo analisa a estrutura blob_info para criar uma URL que ela usa para inicializar um BlobClient. Em seguida, ele chama upload_blob para carregar o arquivo no Armazenamento de Blobs.

try:
    sas_url = "https://{}/{}/{}{}".format(
        blob_info["hostName"],
        blob_info["containerName"],
        blob_info["blobName"],
        blob_info["sasToken"]
    )

    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

    # Upload the specified file
    with BlobClient.from_blob_url(sas_url) as blob_client:
        with open(file_name, "rb") as f:
            result = blob_client.upload_blob(f, overwrite=True)
            return (True, result)

except FileNotFoundError as ex:
    # catch file not found and add an HTTP status code to return in notification to IoT hub
    ex.status_code = 404
    return (False, ex)

except AzureError as ex:
    # catch Azure errors that might result from the upload operation
    return (False, ex)

Notificar o hub IoT sobre o status de upload

Use notify_blob_upload_status para notificar o Hub IoT sobre o status da operação de Armazenamento de Blobs. Passe o método correlation_id obtido pelo método get_storage_info_for_blob. O correlation_id é usado pelo hub IoT para notificar qualquer serviço que possa estar escutando uma notificação sobre o status da tarefa de upload de arquivo.

Este exemplo notifica o Hub IoT sobre um upload de arquivo bem-sucedido:

device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)

Desligar o cliente do dispositivo

Desligue o cliente. Depois que este método é chamado, qualquer tentativa de chamadas de cliente adicionais resulta na geração de um ClientError.

device_client.shutdown()

Exemplos de upload de arquivo do SDK

O SDK inclui dois exemplos de upload de arquivo:

Visão geral

Estas instruções contêm duas seções:

  • Carregar um arquivo de um aplicativo de dispositivo
  • Receber notificação de upload de arquivo em um aplicativo de back-end

Carregar um arquivo de um aplicativo de dispositivo

Esta seção descreve como carregar um arquivo de um dispositivo para um hub IoT usando o pacote azure-iot-device no SDK da Internet das Coisas do Azure para Node.js.

Instalar pacotes do SDK

Execute este comando para instalar o SDK do dispositivo azure-iot-device, o azure-iot-device-mqtt e os pacotes @azure/storage-blob em seu computador de desenvolvimento:

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

O pacote azure-iot-device contém objetos que fazem interface com os dispositivos IoT.

Siga este procedimento para carregar um arquivo de um dispositivo para o Hub IoT:

  1. Obter assinaturas de acesso compartilhado do Blob
  2. Carregar o arquivo no Armazenamento do Microsoft Azure
  3. Enviar uma notificação de status de upload de arquivo para o hub IoT

Criar módulos

Crie módulos cliente, protocolo, erros e caminho usando os pacotes instalados.

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');

Obter um URI SAS do hub IoT

Use getBlobSharedAccessSignature para obter o token SAS da conta de armazenamento vinculada do hub IoT. Conforme descrito nos pré-requisitos, o hub IoT está vinculado ao Armazenamento de Blobs.

Por exemplo:

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

Carregar o arquivo no hub IoT

Para carregar um arquivo de um dispositivo para o hub IoT:

  1. Criar um pipeline de fluxo
  2. Construir a URL do blob
  3. Criar um BlockBlobClient para upload de arquivo no Armazenamento de Blobs
  4. Chamar uploadFile para carregar o arquivo no Armazenamento de Blobs
  5. Chame notifyBlobUploadStatus para notificar o hub IoT de que o upload foi bem-sucedido ou falhou

Por exemplo:

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

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

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

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

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

  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);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

Receber notificação de upload de arquivo em um aplicativo de back-end

Você pode criar um aplicativo de back-end para verificar o cliente de serviço do hub IoT em busca de notificações de upload de arquivo de dispositivo.

Para criar um aplicativo de notificação de upload de arquivo:

  1. Conectar-se ao cliente de serviço do hub IoT
  2. Verificar se há uma notificação de upload de arquivo

Conectar-se ao cliente de serviço do hub IoT

A classe ServiceClient contém métodos que os serviços podem usar para receber notificações de upload de arquivo.

Conecte-se ao hub IoT usando fromConnectionString. Passe a cadeia de conexão primária do hub IoT.

const Client = require('azure-iothub').Client;
const connectionString = "{IoT hub primary connection string}";
const serviceClient = Client.fromConnectionString(connectionString);

Abra a conexão com o Hub IoT.

//Open the connection to IoT hub
serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');

Verificar se há uma notificação de upload de arquivo

Para verificar se há notificações de upload de arquivo:

  1. Chame getFileNotificationReceiver. Forneça o nome de um método de retorno de chamada de upload de arquivo que é chamado quando as mensagens de notificação são recebidas.
  2. Processar notificações de upload de arquivo no método de retorno de chamada.

Este exemplo configura um receptor de retorno de chamada de notificação receiveFileUploadNotification. O receptor interpreta as informações de status de upload do arquivo e imprime uma mensagem de status no console.

//Set up the receiveFileUploadNotification notification message callback receiver
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');
      }
    });
  });
}

Exemplo de upload de arquivo do SDK

O SDK inclui um exemplo de upload para blob avançado.