Introdução ao gerenciamento de dispositivos (Python)

Artigo
10/01/2024

Os aplicativos de back-end podem usar primitivos do Hub IoT do Azure, como dispositivos gêmeos e métodos diretos, para iniciar e monitorar remotamente as ações de gerenciamento de dispositivo nos dispositivos. Este artigo mostra como um aplicativo de back-end e um dispositivo podem trabalhar juntos para permitir que você inicie e monitore uma reinicialização remota por meio do Hub IoT.

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.

Use um método direto para iniciar as ações de gerenciamento do dispositivo (como a reinicialização, redefinição de fábrica e atualização do firmware) a partir de um aplicativo de back-end na nuvem. O dispositivo é responsável por:

Lidar com a solicitação do método enviada a partir do Hub IoT.
Iniciar a ação específica do dispositivo correspondente no dispositivo.
Fornecimento de atualizações de status por meio das propriedades relatadas para o Hub IoT.

Você pode usar um aplicativo de back-end na nuvem para executar consultas do dispositivo gêmeo para relatar o progresso de suas ações de gerenciamento do dispositivo.

Este artigo mostra como criar:

dmpatterns_getstarted_device.py: um aplicativo de dispositivo simulado com um método direto que reinicializa o dispositivo e relata a hora da última reinicialização. Métodos diretos são invocados da nuvem.
dmpatterns_getstarted_service.py: um aplicativo de console Python que chama o método direto no aplicativo de dispositivo simulado por meio do Hub IoT. Ele exibe a resposta e as propriedades relatadas atualizadas.

Observação

Para obter mais informações sobre as ferramentas do SDK disponíveis para compilar os dispositivos e os aplicativos de back-end, consulte SDKs de Internet das Coisas do Azure.

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 na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.
Um dispositivo registrado em seu hub IoT. Se você não tiver um dispositivo no hub IoT, siga as etapas em Registrar um dispositivo.
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.
Verifique se a porta 8883 está 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).

Registrar um novo dispositivo no hub IoT

Nesta seção, você usa a CLI do Azure para criar uma identidade do dispositivo para este artigo. As IDs de Dispositivo diferenciam maiúsculas de minúsculas.

Abra o Azure Cloud Shell.
No Azure Cloud Shell, execute o seguinte comando para instalar a Extensão de IoT do Microsoft Azure para a CLI do Azure:
```
az extension add --name azure-iot
```
Crie uma identidade do dispositivo chamada myDeviceId e recupere a cadeia de conexão do dispositivo com estes comandos:
```
az iot hub device-identity create --device-id myDeviceId --hub-name {Your IoT Hub name} --resource-group {Resource group of the Hub}
az iot hub device-identity connection-string show --device-id myDeviceId --hub-name {Your IoT Hub name} --resource-group {Resource group of the Hub} -o table
```
Importante

A ID do dispositivo pode estar visível nos logs coletados para o atendimento ao cliente e à solução de problemas. Portanto, evite informações confidenciais ao nomear.

Anote a cadeia de conexão do dispositivo no resultado. Essa cadeia de conexão é usada pelo aplicativo do dispositivo para se conectar ao seu Hub IoT como um dispositivo.

Criar um aplicativo de dispositivo com um método direto

Nesta seção, você:

Crie um aplicativo de console Python que responda a uma chamada de método direto pela nuvem.
Simule um reinício do dispositivo.
Usar as propriedades relatadas para habilitar consultas de dispositivo gêmeo para identificar dispositivos e a última reinicialização.

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

No Azure Cloud Shell que você usou anteriormente ou em qualquer outro ambiente com Python, crie o código do dispositivo.

No seu prompt de comando, execute o seguinte comando para instalar o pacote azure-iot-device:
```
pip install azure-iot-device
```
Usando um editor de texto, crie um arquivo chamado dmpatterns_getstarted_service.py em seu diretório de trabalho.

Adicione as seguintes instruções import no início do arquivo dmpatterns_getstarted_device.py.

import time
import datetime
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Adicione a variável CONNECTION_STRING. Substitua o valor de espaço reservado {deviceConnectionString} pela cadeia de conexão do dispositivo. Você copiou essa cadeia de conexão anteriormente em Registrar um novo dispositivo no hub IoT.
```
CONNECTION_STRING = "{deviceConnectionString}"
```

Adicione a função a seguir para instanciar um cliente configurado para métodos diretos no dispositivo.

def create_client():
    # Instantiate the client
    client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

    # Define the handler for method requests
    def method_request_handler(method_request):
        if method_request.name == "rebootDevice":
            # Act on the method by rebooting the device
            print("Rebooting device")
            time.sleep(20)
            print("Device rebooted")

            # ...and patching the reported properties
            current_time = str(datetime.datetime.now())
            reported_props = {"rebootTime": current_time}
            client.patch_twin_reported_properties(reported_props)
            print( "Device twins updated with latest rebootTime")

            # Create a method response indicating the method request was resolved
            resp_status = 200
            resp_payload = {"Response": "This is the response from the device"}
            method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

        else:
            # Create a method response indicating the method request was for an unknown method
            resp_status = 404
            resp_payload = {"Response": "Unknown method"}
            method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

        # Send the method response
        client.send_method_response(method_response)

    try:
        # Attach the handler to the client
        client.on_method_request_received = method_request_handler
    except:
        # In the event of failure, clean up
        client.shutdown()

    return client

Inicie o exemplo de método direto e aguarde.

def main():
    print ("Starting the IoT Hub Python sample...")
    client = create_client()

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Wait for program exit
        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubDeviceClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Salve e feche o arquivo dmpatterns_getstarted_device.py.

Observação

Para simplificar, este tutorial não implementa nenhuma política de repetição. No código de produção, implemente políticas de repetição (como uma retirada exponencial), conforme sugerido no artigo Tratamento de falhas transitórias.

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço de back-end que invoca um método direto em um dispositivo. Para invocar um método direto em um dispositivo por meio do Hub IoT, o 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:

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.
No painel do lado esquerdo do hub IoT, selecione Políticas de acesso compartilhado.
Na lista de políticas, selecione a política de serviço.
Copie a Cadeia de conexão primária e salve o valor.

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Criar um aplicativo de serviço para disparar uma reinicialização

Nesta seção, você criará um aplicativo do console Python que inicia uma reinicialização remota em um dispositivo usando um método direto. O aplicativo usa consultas de dispositivo gêmeo para descobrir o último horário de reinicialização para esse dispositivo.

Importante

Este artigo inclui etapas para se conectar a um serviço usando uma assinatura de acesso compartilhado. Esse método de autenticação é conveniente para teste e avaliação, mas a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

No Azure Cloud Shell ou em qualquer outro ambiente com Python, crie o código do console.

No prompt de comando, execute o seguinte comando para instalar o pacote azure-iot-hub:
```
pip install azure-iot-hub
```
Usando um editor de texto, crie um arquivo dmpatterns_getstarted_service.py em seu diretório de trabalho.

Adicione as seguintes instruções import no início do arquivo dmpatterns_getstarted_service.py.

import sys, time

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult, Twin

Adicione as declarações de variável a seguir. Substitua o valor de espaço reservado {IoTHubConnectionString} pela cadeia de conexão do hub IoT que você copiou anteriormente em Obter a cadeia de conexão do hub IoT. Substitua o valor do espaço reservado {deviceId} pela ID do dispositivo que você registrou em Registrar um novo dispositivo no Hub IoT.
```
CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10
```

Adicione a função a seguir para invocar o método de dispositivo para reiniciar o dispositivo de destino e consultar os dispositivos gêmeos, além de obter a hora de reinicialização mais recente.

def iothub_devicemethod_sample_run():
    try:
        # Create IoTHubRegistryManager
        registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

        print ( "" )
        print ( "Invoking device to reboot..." )

        # Call the direct method.
        deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
        response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

        print ( "" )
        print ( "Successfully invoked the device to reboot." )

        print ( "" )
        print ( response.payload )

        while True:
            print ( "" )
            print ( "IoTHubClient waiting for commands, press Ctrl-C to exit" )

            status_counter = 0
            while status_counter <= WAIT_COUNT:
                twin_info = registry_manager.get_twin(DEVICE_ID)

                if twin_info.properties.reported.get("rebootTime") != None :
                    print ("Last reboot time: " + twin_info.properties.reported.get("rebootTime"))
                else:
                    print ("Waiting for device to report last reboot time...")

                time.sleep(5)
                status_counter += 1

    except Exception as ex:
        print ( "" )
        print ( "Unexpected error {0}".format(ex) )
        return
    except KeyboardInterrupt:
        print ( "" )
        print ( "IoTHubDeviceMethod sample stopped" )

if __name__ == '__main__':
    print ( "Starting the IoT Hub Service Client DeviceManagement Python sample..." )
    print ( "    Connection string = {0}".format(CONNECTION_STRING) )
    print ( "    Device ID         = {0}".format(DEVICE_ID) )

    iothub_devicemethod_sample_run()

Salve e feche o arquivo dmpatterns_getstarted_service.py.

Executar os aplicativos

Agora você está pronto para executar o código de dispositivo e o código de serviço que iniciará um reinício do dispositivo.

No prompt de comando em que você criou o dispositivo, execute o seguinte comando para começar a escutar o método direto de reinício.
```
python dmpatterns_getstarted_device.py
```
No prompt de comando em que você criou o serviço, execute o seguinte comando para disparar o reinício remoto e consulte o dispositivo gêmeo para localizar a hora do último reinício.
```
python dmpatterns_getstarted_service.py
```
Você verá a resposta do dispositivo para o método direto no console.

O seguinte item mostra a resposta do dispositivo para o método direto de reinicialização:

O seguinte item mostra o serviço chamando o método direto de reinicialização e sondando o status no dispositivo gêmeo:

Personalizar e estender as ações de gerenciamento do dispositivo

As soluções de IoT podem expandir o conjunto definido de padrões de gerenciamento do dispositivo ou habilitar padrões personalizados usando o dispositivo gêmeo e os primitivos do método da nuvem para o dispositivo. Outros exemplos de ações de gerenciamento do dispositivo incluem a redefinição de fábrica, atualização do firmware, atualização do software, gerenciamento de energia, gerenciamento da rede e da conectividade, e criptografia dos dados.

Janelas de manutenção do dispositivo

Normalmente, você pode configurar os dispositivos para executar ações em um horário que minimiza as interrupções e a inatividade. As janelas de manutenção do dispositivo são um padrão usado para definir a hora em que um dispositivo deve atualizar sua configuração. As soluções de back-end podem usar as propriedades desejadas do dispositivo gêmeo para definir e ativar uma política no dispositivo que permite uma janela de manutenção. Quando um dispositivo recebe a política da janela de manutenção, ele pode usar a propriedade relatada do dispositivo gêmeo para informar o status da política. O aplicativo de back-end pode usar as consultas do dispositivo gêmeo para atestar a conformidade dos dispositivos e cada política.

Próximas etapas

Neste artigo, você usou um método direto para disparar uma reinicialização remota em um dispositivo. Você usou as propriedades relatadas para relatar a hora da última reinicialização do dispositivo e consultou o dispositivo gêmeo para descobrir a hora da última reinicialização do dispositivo na nuvem.

Para continuar a usar o Hub IoT e os padrões de gerenciamento de dispositivos, como a atualização baseada em imagem de ponta a ponta no artigo de Atualização de dispositivo para o Hub IoT do Azure usando a imagem de referência do Raspberry Pi 3 B+.

Para saber como estender a sua solução de IoT e agendar chamadas de método em vários dispositivos, consulte Agendar e difundir trabalhos.

Compartilhar via

Introdução ao gerenciamento de dispositivos (Python)

Pré-requisitos

Registrar um novo dispositivo no hub IoT

Criar um aplicativo de dispositivo com um método direto

Obter a cadeia de conexão do hub IoT

Criar um aplicativo de serviço para disparar uma reinicialização

Executar os aplicativos

Personalizar e estender as ações de gerenciamento do dispositivo

Janelas de manutenção do dispositivo

Próximas etapas

Comentários

Recursos adicionais