Introdução ao gerenciamento de dispositivos (Python)

Artigo
10/01/2024

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

Nota

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

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

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

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

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 última hora de reinicialização. Os métodos diretos são invocados a partir 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.

Nota

Para obter mais informações sobre as ferramentas SDK disponíveis para criar aplicativos de dispositivo e back-end, consulte Azure IoT SDKs.

Pré-requisitos

Uma conta ativa do Azure. (Se não tiver uma conta, pode criar uma conta gratuita em apenas alguns minutos.)
Um hub IoT em sua assinatura do Azure. Se você ainda não tiver um hub, siga as etapas em Criar um hub IoT.
Um dispositivo registrado em seu hub IoT. Se você não tiver um dispositivo em seu hub IoT, siga as etapas em Registrar um dispositivo.
Python versão 3.7 ou posterior é recomendado. Certifique-se de que utiliza a instalação de 32 ou 64 bits, conforme exigido pela sua configuração. Quando lhe for pedido durante a instalação, confirme que adiciona Python à variável de ambiente específica da sua plataforma.
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo 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).

Registrar um novo dispositivo no hub IoT

Nesta seção, você usa a CLI do Azure para criar uma identidade de dispositivo para este artigo. Os IDs dos dispositivos são sensíveis a maiúsculas e minúsculas.

Abra o Azure Cloud Shell.
No Azure Cloud Shell, execute o seguinte comando para instalar a Extensão IoT do Microsoft Azure para CLI do Azure:
```
az extension add --name azure-iot
```
Crie uma nova identidade de 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

O ID do dispositivo poderá estar visível nos registos recolhidos para suporte técnico ao cliente e resolução de problemas, pelo que deve evitar incluir informações confidenciais quando lhe der um nome.

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

Criar um aplicativo de dispositivo com um método direto

Nesta secção, pode:

Crie um aplicativo de console Python que responda a um método direto chamado pela nuvem.
Simule uma reinicialização do dispositivo.
Use as propriedades relatadas para habilitar consultas gêmeas de dispositivo para identificar dispositivos e quando eles foram reinicializados pela última vez.

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 testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança de conexão.

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

No 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_device.py em seu diretório de trabalho.

Adicione as seguintes import instruções 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 do 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 seguinte função 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 .

Nota

Para facilitar, este tutorial não implementa nenhuma política de repetição. No código de produção, você deve implementar políticas de repetição (como um backoff 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, 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:

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.
No painel 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 políticas e permissões 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ê cria um aplicativo de console Python que inicia uma reinicialização remota em um dispositivo usando um método direto. O aplicativo usa consultas gêmeas de dispositivo para descobrir o último tempo 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 autenticar em um serviço com ID do Microsoft Entra ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança na 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 chamado dmpatterns_getstarted_service.py em seu diretório de trabalho.

Adicione as seguintes import instruções 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 seguintes declarações de variáveis. Substitua o valor do {IoTHubConnectionString} espaço reservado pela cadeia de conexão do hub IoT copiada anteriormente em Obter a cadeia de conexão do hub IoT. Substitua o valor do {deviceId} espaço reservado pelo ID do dispositivo registrado 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 seguinte função para invocar o método de dispositivo para reiniciar o dispositivo de destino, em seguida, consultar os gêmeos de dispositivo e obter a última hora de reinicialização.

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 as aplicações

Agora você está pronto para executar o código do dispositivo e o código de serviço que inicia uma reinicialização do dispositivo.

No prompt de comando onde você criou o dispositivo, execute o seguinte comando para começar a ouvir o método direto de reinicialização.
```
python dmpatterns_getstarted_device.py
```
No prompt de comando onde você cria o serviço, execute o seguinte comando para acionar a reinicialização remota e consultar o gêmeo do dispositivo para encontrar a última hora de reinicialização.
```
python dmpatterns_getstarted_service.py
```
Você vê a resposta do dispositivo ao método direto no console.

A seguir mostra a resposta do dispositivo ao método direto de reinicialização:

A seguir mostra o serviço chamando o método direto de reinicialização e sondando o gêmeo do dispositivo para o status:

Personalizar e estender as ações de gerenciamento de dispositivos

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

Janelas de manutenção de dispositivos

Normalmente, você configura dispositivos para executar ações em um momento que minimiza interrupções e tempo de inatividade. As janelas de manutenção de dispositivos são um padrão comumente usado para definir o momento em que um dispositivo deve atualizar sua configuração. Suas soluções de back-end podem usar as propriedades desejadas do gêmeo de dispositivo para definir e ativar uma política em seu dispositivo que permita uma janela de manutenção. Quando um dispositivo recebe a política da janela de manutenção, ele pode usar a propriedade relatada do gêmeo do dispositivo para relatar o status da política. O aplicativo back-end pode usar consultas gêmeas de dispositivo para atestar a conformidade dos dispositivos e de cada política.

Próximos passos

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 última hora de reinicialização do dispositivo e consultou o gêmeo do dispositivo para descobrir a última hora de reinicialização do dispositivo a partir da nuvem.

Para continuar a introdução ao Hub IoT e aos padrões de gerenciamento de dispositivos, como a atualização completa baseada em imagem no artigo 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 sua solução de IoT e agendar chamadas de método em vários dispositivos, consulte Agendar e transmitir trabalhos.

Partilhar 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 as aplicações

Personalizar e estender as ações de gerenciamento de dispositivos

Janelas de manutenção de dispositivos

Próximos passos

Comentários

Recursos adicionais