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

Artigo
03/19/2023

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

O início rápido Enviar telemetria de um dispositivo para um hub IoT e o artigo Enviar mensagens de nuvem para dispositivo com o Hub IoT mostram a funcionalidade básica do sistema de mensagens de dispositivo para nuvem e de nuvem para dispositivo do Hub IoT. O tutorial Configurar o roteamento de mensagens com o Hub IoT descreve uma forma de armazenar mensagens de dispositivo para nuvem com confiança 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ê executa o aplicativo de console Python FileUpload.py, que carrega um arquivo no armazenamento usando o SDK do dispositivo Python.

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

Uma conta ativa do Azure. (Se você não tiver uma conta, poderá criar uma conta gratuita em apenas alguns minutos.)
Um hub IoT. Crie um com a CLI ou o portal do Azure.
Um dispositivo registrado. Registre um no portal do Azure.
O Python versão 3.7 ou posterior é recomendado. Certifique-se de usar a instalação de 32 bits ou 64 bits conforme exigido pelo seu programa de instalação. Quando solicitado durante a instalação, certifique-se de adicionar Python à variável de ambiente específica da plataforma.
A porta 8883 deve estar aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, 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:

Em Configurações do hub, selecione Upload de arquivos no painel esquerdo do Hub IoT.
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.
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.
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.

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

Nesta seção, você criará o aplicativo de dispositivo para carregar um arquivo no hub IoT.

No prompt de comando, execute o seguinte comando para instalar o pacote azure-iot-device. Use esse pacote para coordenar o upload do arquivo com o hub IoT.
```
pip install azure-iot-device
```
No prompt de comando, execute o seguinte comando para instalar o pacote azure.storage.blob. Você usa esse pacote para carregar o arquivo.
```
pip install azure.storage.blob
```
Crie um arquivo de teste que você carregará no armazenamento de blobs.
Usando um editor de texto, crie um arquivo FileUpload.py em sua pasta de trabalho.

Adicione as instruções import e variáveis a seguir ao início do arquivo FileUpload.py.

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

CONNECTION_STRING = "[Device Connection String]"
PATH_TO_FILE = r"[Full path to local file]"

Substitua [Device Connection String] pela cadeia de conexão do dispositivo do Hub IoT no seu arquivo. Substitua [Full path to local file] pelo caminho para o arquivo de teste que você criou, ou qualquer arquivo no dispositivo que você deseja carregar.

Crie uma função para carregar o arquivo no armazenamento de blobs:

def store_blob(blob_info, file_name):
    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)

Essa função analisa a estrutura de blob_info passada para ela para criar uma URL que ela usa para inicializar um azure.storage.blob.BlobClient. Em seguida, ela carrega o arquivo no armazenamento de blobs do Azure usando esse cliente.

Adicione o código a seguir para conectar ao cliente e carregar o arquivo:

def run_sample(device_client):
    # Connect the client
    device_client.connect()

    # Get the storage info for the blob
    blob_name = os.path.basename(PATH_TO_FILE)
    storage_info = device_client.get_storage_info_for_blob(blob_name)

    # Upload to blob
    success, result = store_blob(storage_info, PATH_TO_FILE)

    if success == True:
        print("Upload succeeded. Result is: \n") 
        print(result)
        print()

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

    else :
        # If the upload was not successful, the result is the exception object
        print("Upload failed. Exception is: \n") 
        print(result)
        print()

        device_client.notify_blob_upload_status(
            storage_info["correlationId"], False, result.status_code, str(result)
        )

def main():
    device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

    try:
        print ("IoT Hub file upload sample, press Ctrl-C to exit")
        run_sample(device_client)
    except KeyboardInterrupt:
        print ("IoTHubDeviceClient sample stopped")
    finally:
        # Graceful exit
        device_client.shutdown()


if __name__ == "__main__":
    main()

Esse código cria um IoTHubDeviceClient e usa as seguintes APIs para gerenciar o upload de arquivos com o hub IoT:

get_storage_info_for_blob obtém informações de seu hub IoT sobre a conta de armazenamento vinculada que você criou anteriormente. Essas informações incluem nome do host, nome do contêiner, nome do blob e um token SAS. As informações de armazenamento são passadas para a função store_blob (criada na etapa anterior), para que o BlobClient nessa função possa ser autenticado com o armazenamento do Azure. O método get_storage_info_for_blob também retorna uma correlation_id, que é usado no método notify_blob_upload_status. A correlation_id é a maneira do Hub IoT marcar em qual blob você está trabalhando.
notify_blob_upload_status notifica o Hub IoT do status da operação de armazenamento de blobs. Você passa a correlation_id obtida pelo método get_storage_info_for_blob. Ela é usada pelo Hub IoT para notificar qualquer serviço que possa estar ouvindo uma notificação sobre o status da tarefa de upload de arquivo.

Salve e feche o arquivo FileUpload.py.

Executar o aplicativo

Agora você está pronto para executar o aplicativo.

Em um prompt de comando na pasta de trabalho, execute o seguinte comando:
```
python FileUpload.py
```
A captura de tela a seguir mostra a saída do aplicativo FileUpload:
Você pode usar o portal para exibir o arquivo carregado no contêiner de armazenamento configurado:

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:

Saiba mais sobre o Armazenamento de Blobs do Azure com os seguintes links: