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

  • Artigo

Este artigo demonstra como carregar arquivos do Hub IoT para carregar um arquivo no armazenamento de blob do Azure, usando um dispositivo do Azure IoT .NET e SDKs de serviço.

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 artigo Configurar Roteamento de Mensagens com 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 carregar 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 aplicativos de console .NET:

  • FileUploadSample. Este aplicativo de dispositivo carrega um arquivo para o armazenamento usando um URI SAS fornecido pelo seu hub IoT. Este exemplo é do repositório do Azure IoT C# SDK que você baixa nos pré-requisitos.

  • ReadFileUploadNotification. Este aplicativo de serviço recebe notificações de carregamento de arquivos do seu hub IoT. Você cria este aplicativo.

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.

  • Os aplicativos de exemplo que você executa neste artigo são escritos usando C# com .NET Core.

    Baixe o SDK do .NET Core para várias plataformas do .NET.

    Verifique a versão atual do SDK do .NET Core em sua máquina de desenvolvimento usando o seguinte comando:

    dotnet --version

  • Baixe o SDK do Azure IoT C# do Exemplo de download e extraia o arquivo ZIP.

  • A porta 8883 deve estar aberta no firewall. O exemplo 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 ficheiro a partir de uma aplicação de dispositivo

Neste artigo, você usa um exemplo do repositório do Azure IoT C# SDK baixado anteriormente como o aplicativo de dispositivo. Você pode abrir os arquivos abaixo usando o Visual Studio, Visual Studio Code ou um editor de texto de sua escolha.

O exemplo está localizado em azure-iot-sdk-csharp/iothub/device/samples/getting started/FileUploadSample na pasta onde você extraiu o Azure IoT C# SDK.

Examine o código em FileUpLoadSample.cs. Este arquivo contém a lógica de exemplo principal. Depois de criar um cliente de dispositivo do Hub IoT, ele segue o procedimento padrão de três partes para carregar arquivos de um dispositivo:

  1. O código chama o método GetFileUploadSasUriAsync no cliente do dispositivo para obter um URI SAS do hub IoT:

    var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

// Lines removed for clarity

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
Uri uploadUri = sasUri.GetBlobUri();

  2. O código usa o URI SAS para carregar o arquivo no armazenamento do Azure. Neste exemplo, ele usa o URI SAS para criar um cliente de blob de bloco de armazenamento do Azure e carrega o arquivo:

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

  3. O código notifica o hub IoT de que concluiu o carregamento. Isso informa ao hub IoT que ele pode liberar recursos associados ao carregamento (o URI SAS). Se as notificações de carregamento de arquivo estiverem habilitadas, o hub IoT enviará uma mensagem de notificação para os serviços de back-end.

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

Se você examinar o arquivo parameter.cs , verá que:

  • O exemplo requer que você passe um parâmetro, p, que usa uma cadeia de conexão de dispositivo.

  • Por padrão, o exemplo de dispositivo usa o protocolo MQTT para se comunicar com o Hub IoT. Você pode usar o parâmetro t para alterar esse protocolo de transporte. Independentemente dessa seleção, o cliente de blob do Azure sempre usa HTTPS como o protocolo para carregar o arquivo de armazenamento do Azure.

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 seu hub IoT. 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 C# que recebe mensagens de notificação de carregamento de arquivo do seu hub IoT.

  1. Abra uma janela de comando e vá para a pasta onde você deseja criar o projeto. Crie uma pasta chamada ReadFileUploadNotifications e altere os diretórios para essa pasta.

    mkdir ReadFileUploadNotification
cd ReadFileUploadNotification

  2. Execute o seguinte comando para criar um projeto de console C#. Depois de executar o comando, a pasta conterá um arquivo Program.cs e um arquivo ReadFileUploadNotification.csproj .

    dotnet new console --language c#

  3. Execute o seguinte comando para adicionar o pacote Microsoft.Azure.Devices ao arquivo de projeto. Este pacote é o SDK do serviço Azure IoT .NET.

    dotnet add package Microsoft.Azure.Devices

  4. Abra o arquivo Program.cs e adicione a seguinte instrução na parte superior do arquivo:

    using Microsoft.Azure.Devices;

  5. Adicione os seguintes campos à classe Programa. Substitua o valor do espaço reservado {iot hub connection string} pela cadeia de conexão do hub IoT que você copiou anteriormente em Obter a cadeia de conexão do hub IoT:

    static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";

  6. Adicione o seguinte método à classe Programa:

    private async static void ReceiveFileUploadNotificationAsync()
{
    var notificationReceiver = serviceClient.GetFileNotificationReceiver();
    Console.WriteLine("\nReceiving file upload notification from service");
    while (true)
    {
        var fileUploadNotification = await notificationReceiver.ReceiveAsync();
        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);
    }
}

    Observe que esse padrão de recebimento é o mesmo usado para receber mensagens da nuvem para o dispositivo do aplicativo do dispositivo.

  7. Finalmente, substitua as linhas no método Main pelo seguinte:

    Console.WriteLine("Receive file upload notifications\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
ReceiveFileUploadNotificationAsync();
Console.WriteLine("Press Enter to exit\n");
Console.ReadLine();

Executar as aplicações

Agora você está pronto para executar os aplicativos.

  1. Primeiro, execute o aplicativo de serviço para receber notificações de carregamento de arquivos do hub IoT. No prompt de comando na pasta ReadFileUploadNotification , execute os seguintes comandos:

    dotnet restore
dotnet run

    O aplicativo é iniciado e aguarda uma notificação de upload de arquivo do seu hub IoT:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

  2. Em seguida, execute o aplicativo de dispositivo para carregar o arquivo no armazenamento do Azure. Abra um novo prompt de comando e altere as pastas para azure-iot-sdk-csharp \iothub\device\samples\getting started\FileUploadSample na pasta onde você expandiu o SDK do Azure IoT C#. Execute os seguintes comandos. Substitua o valor do {Your device connection string} espaço reservado no segundo comando pela cadeia de conexão do dispositivo que você viu quando registrou um dispositivo no hub IoT.

    dotnet restore
dotnet run --p "{Your device connection string}"

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

      Uploading file TestPayload.txt
  Getting SAS URI from IoT Hub to use when uploading the file...
  Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub
  Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication
  Successfully uploaded the file to Azure Storage
  Notified IoT Hub that the file upload succeeded and that the SAS URI can be freed.
  Time to upload file: 00:00:01.5077954.
  Done.

  3. Observe que o aplicativo de serviço mostra que recebeu a notificação de carregamento de arquivo:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

Received file upload notification: myDeviceId/TestPayload.txt

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 chamado TestPayload.txt.

    Captura de ecrã a mostrar a seleçã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: