Introdução à identidade do módulo e ao módulo gêmeo do Hub IoT (Python)

Artigo
03/02/2023

As identidades do módulo e os módulos gêmeos são semelhantes às identidades do dispositivo e aos dispositivos gêmeos do Hub IoT do Azure, mas fornecem melhor granularidade. Enquanto que as identidades do dispositivo e os dispositivos gêmeos do Hub IoT do Azure permitem que o aplicativo de back-end configure um dispositivo e forneça visibilidade às condições do dispositivo, as identidades do módulo e os módulos gêmeos fornecem essas funcionalidades para componentes individuais de um dispositivo. Em dispositivos habilitados com vários componentes, como dispositivos de sistema operacional ou dispositivos de firmware, eles permitem condições e configuração isolada para cada componente.

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 sua solução.

No fim deste artigo, você tem três aplicativos Python:

CreateModule: que cria uma identidade de dispositivo, uma identidade de módulo e chaves de segurança associadas para conectar seus clientes de dispositivo e módulo.
UpdateModuleTwinDesiredProperties: envia propriedades desejadas atualizadas de módulo gêmeo ao Hub IoT.
ReceiveModuleTwinDesiredPropertiesPatch: recebe o patch das propriedades desejadas do módulo gêmeo em seu dispositivo.

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

Obter a cadeia de conexão do hub IoT

Neste artigo, você criará um serviço de back-end que adiciona um dispositivo no registro de identidade e, em seguida, adiciona um módulo a esse dispositivo. Esse serviço requer a permissão de gravação do registro (que também inclui a leitura do registro). Você também cria um serviço que adiciona as propriedades desejadas ao módulo gêmeo para o módulo recém-criado. Este serviço precisa da permissão de conexão de serviço. Embora existam políticas de acesso compartilhado padrão que concedam essas permissões individualmente, nesta seção, você cria uma política de acesso compartilhado personalizada que contém essas duas permissões.

Para criar uma política de acesso compartilhado que conceda permissões de conexão de serviço e gravação de registro e para obter uma cadeia de conexão para esta política, 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, selecione Políticas de acesso compartilhado.
No menu acima da lista de políticas, selecione Adicionar política de acesso compartilhado.
Em Adicionar política de acesso compartilhado, insira um nome descritivo para a política, como serviceAndRegistryReadWrite. Em Permissões, selecione Gravação de registro e Conexão de serviço e selecione Adicionar. (A permissão de Leitura de registro é incluída automaticamente quando você seleciona a Gravação de registro.)
Selecione a sua nova política na lista de políticas.
Em Chaves de acesso compartilhado, selecione o ícone de cópia da 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 uma identidade do dispositivo e uma identidade do módulo no Hub IoT

Nesta seção, você criará um aplicativo de serviço Python que cria uma identidade do dispositivo e uma identidade do módulo no registro de identidade no Hub IoT. Um dispositivo ou módulo não pode se conectar ao Hub IoT, a menos que ele tenha uma entrada no Registro de identidade. Para obter mais informações, consulte Entender o registro de identidade no Hub IoT. Quando você executa esse aplicativo de console, ele gera ID e chave exclusivas para o dispositivo e o módulo. A ID e a chave diferenciam maiúsculas de minúsculas. O dispositivo e o módulo usam esses valores para se identificar ao enviar mensagens de dispositivo para nuvem para o Hub IoT.

No prompt de comando, execute o seguinte comando para instalar o pacote azure-iot-hub:
```
pip install azure-iot-hub
```
No prompt de comando, execute o seguinte comando para instalar o pacote msrest. Você precisa desse pacote para capturar exceções HTTPOperationError.
```
pip install msrest
```
Usando um editor de texto, crie um arquivo chamado CreateModule.py em seu diretório de trabalho.

Adicione o código a seguir ao arquivo do Python. Substitua YourIoTHubConnectionString pela cadeia de conexão que você copiou em Obter a cadeia de conexão do hub IoT.

import sys
from msrest.exceptions import HttpOperationError
from azure.iot.hub import IoTHubRegistryManager

CONNECTION_STRING = "YourIotHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    try:
        # CreateDevice - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        device_state = "enabled"
        new_device = iothub_registry_manager.create_device_with_sas(
            DEVICE_ID, primary_key, secondary_key, device_state
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the device already exists.
            new_device = iothub_registry_manager.get_device(DEVICE_ID)
        else:
            raise

    print("device <" + DEVICE_ID +
          "> has primary key = " + new_device.authentication.symmetric_key.primary_key)

    try:
        # CreateModule - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        managed_by = ""
        new_module = iothub_registry_manager.create_module_with_sas(
            DEVICE_ID, MODULE_ID, managed_by, primary_key, secondary_key
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the module already exists.
            new_module = iothub_registry_manager.get_module(DEVICE_ID, MODULE_ID)
        else:
            raise

    print("device/module <" + DEVICE_ID + "/" + MODULE_ID +
          "> has primary key = " + new_module.authentication.symmetric_key.primary_key)

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

No prompt de comando, execute o comando a seguir:
```
python CreateModule.py
```

Esse aplicativo cria uma identidade do dispositivo com a ID myFirstDevice e uma identidade do módulo com a ID myFirstModule no dispositivo myFirstDevice. (Quando esse dispositivo ou essa identidade do módulo já existe no registro de identidade, o código simplesmente recupera as informações do dispositivo ou módulo existente.) O aplicativo exibe a identidade e a chave primária de cada identidade.

Observação

O Registro de identidade do Hub IoT armazena apenas as identidades de dispositivo e módulo para habilitar o acesso seguro ao Hub IoT. O registro de identidade armazena IDs de dispositivo e chaves para usar como credenciais de segurança. O registro de identidade também armazena um sinalizador de habilitado/desabilitado para cada dispositivo que você pode usar para desabilitar o acesso ao dispositivo. Se seu aplicativo precisar armazenar outros metadados específicos do dispositivo, ele deverá usar um repositório específico do aplicativo. Não há nenhum sinalizador habilitado/desabilitado para as identidades do módulo. Para obter mais informações, consulte Entender o registro de identidade no Hub IoT.

Atualizar o módulo gêmeo usando o SDK do serviço Python

Nesta seção, você cria um aplicativo de serviço do Python que atualiza as propriedades desejadas do módulo gêmeo.

No prompt de comando, execute o seguinte comando para instalar o pacote azure-iot-hub. Você poderá ignorar esta etapa se tiver instalado o pacote azure-iot-hub na seção anterior.
```
pip install azure-iot-hub
```
Usando um editor de texto, crie um arquivo chamado UpdateModuleTwinDesiredProperties.py em seu diretório de trabalho.

Adicione o código a seguir ao arquivo do Python. Substitua YourIoTHubConnectionString pela cadeia de conexão que você copiou em Obter a cadeia de conexão do hub IoT.

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties

CONNECTION_STRING = "YourIoTHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module twin properties before update    :" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

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

Obter atualizações no lado do dispositivo

Nesta seção, você criará um aplicativo Python para obter a atualização das propriedades desejadas do módulo gêmeo em seu dispositivo.

Obtenha a cadeia de conexão do módulo. No portal do Azure, navegue até o Hub IoT e selecione Dispositivos no painel esquerdo. Selecione myFirstDevice na lista de dispositivos e abra-o. Em Identidades do módulo selecione myFirstModule. Selecione o ícone de cópia para a cadeia de conexão (chave primária). Você precisa dessa cadeia de conexão em uma etapa posterior.
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 ReceiveModuleTwinDesiredPropertiesPatch.py em seu diretório de trabalho.

Adicione o código a seguir ao arquivo do Python. Substitua YourModuleConnectionString pela cadeia de conexão do módulo que você copiou na etapa 1.

import time
from azure.iot.device import IoTHubModuleClient

CONNECTION_STRING = "YourModuleConnectionString"


def twin_patch_handler(twin_patch):
    print("")
    print("Twin desired properties patch received:")
    print(twin_patch)


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

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Attach the handler to the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler

        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubModuleClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Executar os aplicativos

Nesta seção, você executará o aplicativo de dispositivo ReceiveModuleTwinDesiredPropertiesPatch e executará o aplicativo de serviço UpdateModuleTwinDesiredProperties para atualizar as propriedades desejadas do seu módulo.

Abra o prompt de comando e execute o aplicativo do dispositivo:
```
python ReceiveModuleTwinDesiredPropertiesPatch.py
```
Abra um prompt de comando separado e execute o aplicativo de serviço:
```
python UpdateModuleTwinDesiredProperties.py
```
Observe que a propriedade desejada TelemetryInterval aparece no módulo gêmeo atualizado na saída do aplicativo de serviço:

A mesma propriedade aparece no patch de propriedades desejadas recebido na saída do aplicativo do dispositivo:

Próximas etapas

Para continuar a introdução ao Hub IoT e explorar outros cenários de IoT, confira:

Compartilhar via

Introdução à identidade do módulo e ao módulo gêmeo do Hub IoT (Python)

Pré-requisitos

Obter a cadeia de conexão do hub IoT

Criar uma identidade do dispositivo e uma identidade do módulo no Hub IoT

Atualizar o módulo gêmeo usando o SDK do serviço Python

Obter atualizações no lado do dispositivo

Executar os aplicativos

Próximas etapas

Recursos adicionais