Introdução aos gêmeos de dispositivo (Python)

Artigo
04/07/2024

os dispositivos duplos são documentos JSON que armazenam informações de estado dos dispositivos, incluindo metadados, configurações e condições. O Hub IoT persiste um gêmeo de dispositivo para cada dispositivo que se conecta a ele.

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 gêmeos de dispositivo para:

Armazene metadados do dispositivo a partir do back-end da solução.
Relate informações de estado atual, como recursos e condições disponíveis, por exemplo, o método de conectividade usado, do aplicativo do dispositivo.
Sincronize o estado de fluxos de trabalho de longa execução, como atualizações de firmware e configuração, entre um aplicativo de dispositivo e um aplicativo back-end.
Consulte os metadados, a configuração ou o estado do dispositivo.

Os gêmeos de dispositivo são projetados para sincronização e para consultar configurações e condições do dispositivo. Para obter mais informações sobre gêmeos de dispositivo, incluindo quando usar gêmeos de dispositivo, consulte Compreender gêmeos de dispositivo.

Os hubs IoT armazenam gêmeos de dispositivo, que contêm os seguintes elementos:

Etiquetas. Metadados do dispositivo acessíveis apenas pelo back-end da solução.
Propriedades desejadas. Objetos JSON modificáveis pelo back-end da solução e observáveis pelo aplicativo do dispositivo.
Propriedades relatadas. Objetos JSON modificáveis pelo aplicativo de dispositivo e legíveis pelo back-end da solução.

Tags e propriedades não podem conter matrizes, mas podem conter objetos aninhados.

A ilustração a seguir mostra a organização de gêmeos do dispositivo:

Captura de tela de um diagrama de conceito de gêmeo de dispositivo.

Além disso, o back-end da solução pode consultar gêmeos de dispositivo com base em todos os dados acima. Para obter mais informações sobre gêmeos de dispositivo, consulte Compreender gêmeos de dispositivo. Para obter mais informações sobre consultas, consulte Linguagem de consulta do Hub IoT.

Este artigo mostra-lhe como:

Use um aplicativo de dispositivo simulado para relatar seu canal de conectividade como uma propriedade relatada no gêmeo do dispositivo.
Consulte dispositivos a partir do seu aplicativo back-end usando filtros nas tags e propriedades criadas anteriormente.

Neste artigo, você cria dois aplicativos de console Python:

AddTagsAndQuery.py: um aplicativo back-end que adiciona tags e consulta gêmeos de dispositivos.
ReportConnectivity.py: um aplicativo de dispositivo simulado que se conecta ao seu hub IoT e relata sua condição de conectividade.

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. Crie um com a CLI ou o portal do Azure.
Um dispositivo registado. Registre um no portal do Azure.
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).

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço back-end que adiciona as propriedades desejadas a um dispositivo gêmeo e, em seguida, consulta o registro de identidade para localizar todos os dispositivos com propriedades relatadas que foram atualizadas adequadamente. Seu serviço precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo de dispositivo e precisa da permissão de leitura do registro para consultar o registro de identidade. Não há nenhuma política de acesso compartilhado padrão que contenha apenas essas duas permissões, portanto, você precisa criar uma.

Para criar uma política de acesso compartilhado que conceda permissões de conexão de serviço e de leitura do Registro e obtenha uma cadeia de conexão para essa política, 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, selecione Políticas de acesso compartilhado.
No menu superior acima da lista de políticas, selecione Adicionar política de acesso à política compartilhada.
No painel Adicionar política de acesso compartilhado à direita, insira um nome descritivo para sua política, como serviceAndRegistryRead. Em Permissões, selecione Leitura do Registro e Conexão de Serviço e, em seguida, selecione Adicionar.
Selecione sua nova política na lista de políticas.
Selecione o ícone de cópia para a cadeia de conexão principal 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 que atualize as propriedades desejadas e consulte gêmeos

Nesta seção, você cria um aplicativo de console Python que adiciona metadados de localização ao gêmeo de dispositivo associado ao seu {Device ID}. O aplicativo consulta o hub IoT para dispositivos localizados nos EUA e, em seguida, consulta dispositivos que relatam uma conexão de rede celular.

No diretório de trabalho, abra um prompt de comando e instale o SDK do Serviço de Hub IoT do Azure para Python.
```
pip install azure-iot-hub
```
Usando um editor de texto, crie um novo arquivo AddTagsAndQuery.py .

Adicione o código seguinte para importar os módulos necessários do SDK do serviço:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

Adicione o seguinte código. Substitua [IoTHub Connection String] pela cadeia de conexão do hub IoT copiada em Obter a cadeia de conexão do hub IoT. Substitua [Device Id] pelo ID do dispositivo (o nome) do seu dispositivo registrado no hub IoT.
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

Adicione o seguinte código ao arquivo AddTagsAndQuery.py :

def iothub_service_sample_run():
    try:
        iothub_registry_manager = IoTHubRegistryManager(IOTHUB_CONNECTION_STRING)

        new_tags = {
                'location' : {
                    'region' : 'US',
                    'plant' : 'Redmond43'
                }
            }

        twin = iothub_registry_manager.get_twin(DEVICE_ID)
        twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
        twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

        # Add a delay to account for any latency before executing the query
        sleep(1)

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

        print()

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

    except Exception as ex:
        print("Unexpected error {0}".format(ex))
        return
    except KeyboardInterrupt:
        print("IoT Hub Device Twin service sample stopped")

O objeto IoTHubRegistryManager expõe todos os métodos necessários para interagir com gêmeos de dispositivo do serviço. O código primeiro inicializa o objeto IoTHubRegistryManager , em seguida, atualiza o dispositivo gêmeo para DEVICE_ID e, finalmente, executa duas consultas. O primeiro seleciona apenas os gêmeos de dispositivos localizados na planta Redmond43 , e o segundo refina a consulta para selecionar apenas os dispositivos que também estão conectados através de uma rede celular.

Adicione o seguinte código no final do AddTagsAndQuery.py para implementar a função iothub_service_sample_run :

if __name__ == '__main__':
    print("Starting the Python IoT Hub Device Twin service sample...")
    print()

    iothub_service_sample_run()

Execute o aplicativo com:
```
python AddTagsAndQuery.py
```
Você deve ver um dispositivo nos resultados da consulta solicitando todos os dispositivos localizados em Redmond43 e nenhum para a consulta que restringe os resultados a dispositivos que usam uma rede celular. Na próxima seção, você criará um aplicativo de dispositivo que usará uma rede celular e executará novamente essa consulta para ver como ela muda.

Criar um aplicativo de dispositivo que atualize as propriedades relatadas

Nesta seção, você cria um aplicativo de console Python que se conecta ao seu hub como seu {Device ID} e, em seguida, atualiza as propriedades relatadas do gêmeo de dispositivo para confirmar que ele está conectado usando uma rede celular.

Em um prompt de comando em seu diretório de trabalho, instale o SDK de Dispositivo do Hub IoT do Azure para Python:
```
pip install azure-iot-device
```
Usando um editor de texto, crie um novo arquivo ReportConnectivity.py .
Adicione o seguinte código para importar os módulos necessários do SDK do dispositivo:
```
import time
from azure.iot.device import IoTHubModuleClient
```
Adicione o seguinte código. Substitua o valor do [IoTHub Device Connection String] espaço reservado pela cadeia de conexão do dispositivo que você viu quando registrou um dispositivo no Hub IoT:
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

Adicione o seguinte código ao arquivo ReportConnectivity.py para instanciar um cliente e implementar a funcionalidade de gêmeos de dispositivo:

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

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

    try:
        # Set handlers on the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler
    except:
        # Clean up in the event of failure
        client.shutdown()

    return client

Adicione o seguinte código no final do ReportConnectivity.py para executar o aplicativo:

def main():
    print ( "Starting the Python IoT Hub Device Twin device sample..." )
    client = create_client()
    print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )

    try:
        # Update reported properties with cellular information
        print ( "Sending data as reported property..." )
        reported_patch = {"connectivity": "cellular"}
        client.patch_twin_reported_properties(reported_patch)
        print ( "Reported properties updated" )

        # Wait for program exit
        while True:
            time.sleep(1000000)
    except KeyboardInterrupt:
        print ("IoT Hub Device Twin device sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Execute o aplicativo do dispositivo:
```
python ReportConnectivity.py
```
Você verá a confirmação de que as propriedades relatadas pelo gêmeo do dispositivo foram atualizadas.
Agora que o dispositivo relatou suas informações de conectividade, ele deve aparecer em ambas as consultas. Volte e execute as consultas novamente:
```
python AddTagsAndQuery.py
```
Desta vez, o { ID do dispositivo} deve aparecer em ambos os resultados da consulta.

No aplicativo do dispositivo, você verá a confirmação de que o patch gêmeo de propriedades desejado enviado pelo aplicativo de serviço foi recebido.

Neste artigo, irá:

Metadados de dispositivo adicionados como tags de um aplicativo back-end
Informações de conectividade do dispositivo relatadas no gêmeo do dispositivo
Consultado as informações do gêmeo do dispositivo usando a linguagem de consulta do Hub IoT

Próximos passos

Para saber como:

Enviar telemetria de dispositivos, consulte Guia de início rápido: enviar telemetria de um dispositivo IoT Plug and Play para o Hub IoT do Azure.
Configure dispositivos usando as propriedades desejadas do gêmeo de dispositivo, consulte Tutorial: Configurar seus dispositivos a partir de um serviço back-end.
Controle dispositivos interativamente, como ligar um ventilador de um aplicativo controlado pelo usuário, consulte Guia de início rápido: controlar um dispositivo conectado a um hub IoT.

Share via