Fazer upload de arquivos do seu dispositivo na nuvem com o Hub IoT do Azure (.NET)

  • Artigo

Esse artigo demonstra como usar as funcionalidades de upload de arquivos do Hub IoT para carregar um arquivo para o armazenamento de blobs do Azure usando um dispositivo .NET de Internet das Coisas do Azure e SDKs de serviço.

O início rápido de Enviar telemetria de um dispositivo para um hub IoT e o artigo Enviar mensagens da nuvem para dispositivo com o Hub IoT mostram a funcionalidade básica do sistema de mensagens do dispositivo para nuvem e da nuvem para dispositivo do Hub IoT. O artigo Configurar o Roteamento de Mensagens com o Hub IoT descreve uma forma de armazenar mensagens do dispositivo para nuvem de maneira confiável no armazenamento de blobs do Microsoft Azure. No entanto, em alguns cenários, não é possível mapear com facilidade os dados que seus dispositivos enviam em mensagens relativamente pequenas de dispositivo para nuvem e que o Hub IoT aceita. 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.

No final deste artigo, você executará dois aplicativos de console .NET:

  • FileUploadSample. Esse dispositivo carrega um arquivo no armazenamento usando um URI SAS fornecido pelo seu Hub IoT. Esse exemplo é do repositório de SDK do C# da Internet das Coisas do Azure baixado nos pré-requisitos.

  • ReadFileUploadNotification. Esse aplicativo de serviço recebe notificações de upload de arquivo do hub IoT. Você cria este aplicativo.

Observação

O Hub IoT é compatível com muitas plataformas de dispositivo e linguagens (incluindo C, Java, Python e JavaScript) por meio dos SDKs do dispositivo IoT do Azure. Confira a Central do Desenvolvedor de IoT do Azure para saber como conectar seu dispositivo ao Hub IoT do Azure.

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. Crie um com a CLI ou o portal do Azure.

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

  • Os aplicativos de exemplo executados neste artigo são escritos usando o C# com o .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 C# da Internet das Coisas do Azure de Baixar amostra e extraia o arquivo zip.

  • A porta 8883 deve estar aberta no firewall. O exemplo deste artigo usa o protocolo MQTT (Message Queue Telemetry Transport), que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

Associar uma conta do 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 Blobs do Azure associados ao Hub IoT. Depois de associar a conta de armazenamento e o contêiner ao Hub IoT, ele poderá fornecer os elementos de um URI de SAS quando solicitado por um dispositivo. Em seguida, o dispositivo pode usar esses elementos para criar o URI de SAS a ser usado na autenticação no Armazenamento do Azure e no upload de arquivos para o contêiner de blobs.

Para associar uma conta de Armazenamento do Azure ao Hub IoT:

  1. Em Configurações do hub, selecione Upload de arquivos no painel esquerdo do Hub IoT.

    Captura de tela que mostra as configurações de upload de arquivos selecionadas no portal.

  2. No painel Upload de arquivo, selecione Contêiner de Armazenamento do Azure. Para este artigo, é recomendado que a conta de armazenamento e o Hub IoT estejam 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. Dê um nome à conta de armazenamento, verifique se o Local está definido para a mesma região do Hub IoT e selecione OK. A nova conta é criada no mesmo grupo de recursos do 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 blobs.

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

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

  4. Volte ao painel Upload de arquivo e verifique se as notificações de arquivo estão definidas como Ativado. Deixe todas as outras configurações com os valores padrão. Selecione Salvar e aguarde a conclusão da configuração antes de ir para a próxima seção.

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

Para obter instruções mais detalhadas sobre a criação de contas de armazenamento do Azure, veja Criar uma conta de armazenamento. Para obter instruções mais detalhadas sobre a associação de uma conta de armazenamento e um contêiner de blobs a um Hub IoT, veja Configurar uploads de arquivo com o portal do Azure.

Carregar um arquivo de um aplicativo de dispositivo

Neste artigo, você usará um exemplo do repositório de SDK do C# da Internet das Coisas do Azure que você baixou anteriormente como o aplicativo de dispositivo. Você pode abrir os arquivos abaixo usando o Visual Studio, o Visual Studio Code ou um editor de texto preferido.

A amostra está localizada em azure-iot-sdk-csharp/iothub/device/samples/getting started/FileUploadSample na pasta em que você extraiu o SDK do C# da Internet das Coisas do Azure.

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

  1. O código chama o método GetFileUploadSasUriAsync no cliente do dispositivo para obter um URI de 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 de SAS para carregar o arquivo no Armazenamento do Azure. Neste exemplo, ele usa o URI de 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 o upload foi concluído. Isso informa ao Hub IoT que ele pode liberar recursos associados ao upload (o URI de SAS). Se as notificações de upload de arquivo estiverem habilitadas, o hub IoT enviará uma mensagem de notificação aos 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:

  • A amostra requer que você transmita 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 escolha, o cliente de blob do Azure sempre usa HTTPS como protocolo para carregar armazenamento do Azure do arquivo.

Obter a cadeia de conexão do hub IoT

Neste artigo, você criará um serviço de back-end para receber mensagens de notificação de upload do seu hub IoT. Para receber mensagens de notificação de upload de arquivo, seu serviço precisa da permissão conexão de serviço. Por padrão, todo 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 em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.

  2. No painel do lado 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 permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Receber uma notificação de upload de arquivo

Nesta seção, você criará um aplicativo de console em C# que recebe mensagens de notificação de upload de arquivo do seu hub IoT.

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

    mkdir ReadFileUploadNotification
cd ReadFileUploadNotification

  2. Execute o comando a seguir para criar um projeto de console em 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 comando a seguir para adicionar o pacote Microsoft.Azure.Devices ao arquivo de projeto. Esse pacote é o SDK do serviço .NET da Internet das Coisas do Azure.

    dotnet add package Microsoft.Azure.Devices

  4. Abra o arquivo Program.cs e adicione as seguintes instruções à parte superior do arquivo:

    using Microsoft.Azure.Devices;

  5. Adicione os seguintes campos à classe Program . 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);
    }
}

    É importante lembrar que o padrão de recebimento é o mesmo usado para receber mensagens da nuvem para o dispositivo do aplicativo do dispositivo.

  7. Por fim, substitua o método Main pelo código abaixo:

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

Executar os aplicativos

Agora você está pronto para executar os aplicativos.

  1. Primeiro, execute o aplicativo de serviço para receber notificações de upload de arquivo 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 em que você expandiu o SDK do C# da Internet das Coisas do Azure. Execute os seguintes comandos. Substitua o valor do espaço reservado {Your device connection string} no segundo comando pela cadeia de conexão de dispositivo que você viu quando registrou um dispositivo no hub IoT.

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

    Veja se a seguinte saída veio do aplicativo de dispositivo após a conclusão do upload:

      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 upload de arquivo:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

Received file upload notification: myDeviceId/TestPayload.txt

Verifique o carregamento do arquivo

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

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

  2. No painel esquerdo dela, selecione Contêineres.

  3. Selecione o contêiner em que você carregou o arquivo.

  4. Selecione a pasta com o nome do dispositivo.

  5. Selecione o blob em que você carregou o arquivo. Neste artigo, é o blob chamado TestPayload.txt.

    Captura de tela da seleção do arquivo carregado no portal do Azure.

  6. Veja as propriedades do blob na página que é aberta. Você pode selecionar Baixar para baixar o arquivo e exibir o conteúdo dele localmente.

Próximas etapas

Neste artigo, você aprendeu a usar o recurso de carregamento de arquivos do Hub IoT para simplificar os carregamentos de arquivos de dispositivos. Você pode continuar a explorar esse recurso nos seguintes artigos: