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

Descrição geral

Este tutorial contém duas seções:

• Carregar um ficheiro a partir de uma aplicação de dispositivo
• Receber notificação de upload de arquivo em um aplicativo de back-end

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

Esta seção descreve como carregar um arquivo de um dispositivo para um hub IoT usando a classe DeviceClient no SDK do Azure IoT 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 ficheiro para o armazenamento do Azure
4. Notificar o hub IoT sobre o status de carregamento do arquivo

Ligar 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

Ligue para GetFileUploadSasUriAsync para obter detalhes de upload de arquivos. 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 ficheiro para o armazenamento do Azure

Para carregar um arquivo no armazenamento do Azure:

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

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

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

Neste exemplo, BlockBlobClient é passado o URI SAS para criar um cliente Blob de bloco de armazenamento do Azure e carrega o arquivo:

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

Notificar o hub IoT sobre o status de carregamento do arquivo

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

Se as notificações de carregamento de arquivo estiverem habilitadas, o hub IoT enviará uma mensagem de notificação de carregamento de arquivo para serviços de back-end configurados para notificação de carregamento 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 carregamento de arquivo 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 carregamento de arquivos do hub IoT.

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

Para receber a notificação de carregamento de ficheiros:

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 recetor de notificação.
4. Use um loop com ReceiveAsync para aguardar a notificação de upload de 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);
}

Descrição geral

Este tutorial contém duas seções:

• Carregar um ficheiro a partir de uma aplicação de dispositivo
• Receber notificação de upload de arquivo em um aplicativo de back-end

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

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

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

1. Ligar ao dispositivo
2. Obter um URI SAS do hub IoT
3. Carregar o ficheiro para o Armazenamento do Azure
4. Enviar notificação de status de carregamento de arquivo para o hub IoT

Protocolo de conexão

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

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

Ligar ao dispositivo

Instancie o DeviceClient para se conectar 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 de retorno. Os valores de retorno podem ser passados para métodos de upload de arquivo.

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 ficheiro para o Armazenamento do Azure

Passe o ponto de extremidade 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 Blob Storage.

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

Enviar notificação de status de carregamento de arquivo para o hub IoT

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

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

FileUploadCompletionNotification deve ser chamado mesmo quando o upload do arquivo falhar. O hub IoT tem um número fixo de URI SAS permitido para estar ativo a qualquer momento. Depois de concluir o upload do arquivo, você deve liberar seu URI SAS para que outro URI SAS possa ser gerado. Se um URI SAS não for liberado por meio dessa API, ele se liberará eventualmente com base em quanto tempo os URIs SAS estão configurados 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

Liberte os client recursos.

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 arquivos.

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 carregamento de arquivo.

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

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

Ligue 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 estado do carregamento de ficheiros

Para verificar o estado do carregamento de ficheiros:

1. Crie um objeto getFileUploadNotificationReceiver .
2. Use open para se conectar ao hub IoT.
3. Ligue para receber para verificar o status de upload do arquivo. Esse método retorna um objeto fileUploadNotification . Se um aviso de upload for recebido, você poderá visualizar os campos de status de carregamento usando os 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 arquivos SDK

Há dois exemplos de upload de arquivos 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 carregamento do arquivo.

pip install azure.storage.blob

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

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

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

1. Ligar ao dispositivo
2. Obter informações de armazenamento de Blob
3. Carregue o arquivo para o Armazenamento de Blobs
4. Notificar o hub IoT sobre o status de carregamento

Importar bibliotecas

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

Ligar ao dispositivo

Para ligar ao dispositivo:

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

2. Ligue 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 de armazenamento de Blob

Ligue para get_storage_info_for_blob para obter informações de um hub IoT sobre uma conta de Armazenamento do Azure vinculada. Essas informações incluem o nome do host, o nome do contêiner, o nome do blob e um token SAS. O get_storage_info_for_blob método também retorna um correlation_id, que é usado no notify_blob_upload_status método. A correlation_id é a maneira do Hub IoT de 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 ficheiro para o Armazenamento de Blobs

Para carregar um arquivo no Armazenamento de Blob:

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 blob_info estrutura para criar uma URL que ela usa para inicializar um BlobClient. Em seguida, ele chama upload_blob para carregar o arquivo no Armazenamento de Blob.

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 carregamento

Use notify_blob_upload_status para notificar o hub IoT sobre o status da operação de Armazenamento de Blob. Passar o correlation_id obtido pelo get_storage_info_for_blob método. 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 carregamento de arquivo.

Este exemplo notifica o hub IoT sobre um carregamento de arquivo bem-sucedido:

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

Desligue o cliente do dispositivo

Desligue o cliente. Uma vez que esse método é chamado, qualquer tentativa de chamadas de cliente adicionais resulta em um ClientError sendo gerado.

device_client.shutdown()

Exemplos de upload de arquivos SDK

O SDK inclui dois exemplos de upload de arquivos:

• Carregar para blob
• Carregar para blob usando um certificado X.509

Descrição geral

Este tutorial contém duas seções:

• Carregar um ficheiro a partir de uma aplicação de dispositivo
• Receber notificação de upload de arquivo em um aplicativo de back-end

Carregar um ficheiro a partir de uma aplicação 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 do Azure IoT para Node.js.

Instalar pacotes 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 sua máquina 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 dispositivos IoT.

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

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

Criar módulos

Crie módulos de 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 Blob.

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

Carregue o arquivo para o hub IoT

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

1. Criar um pipeline de fluxo
2. Construir o URL do blob
3. Criar um BlockBlobClient para upload de arquivos para o Armazenamento de Blobs
4. Chamada uploadFile para carregar o arquivo para o Armazenamento de Blob
5. Chame notifyBlobUploadStatus para notificar o hub IoT de que o carregamento 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 se há notificações de carregamento de arquivo de dispositivo no cliente de serviço do hub IoT.

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 carregamento 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 arquivos:

1. Chame getFileNotificationReceiver. Forneça o nome de um método de retorno de chamada de carregamento 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 recetor de retorno de receiveFileUploadNotification chamada de notificação. O recetor 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 carregamento de arquivo SDK

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