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

Artigo
08/25/2023

As identidades dos módulos e os módulos duplos são semelhantes aos Hub IoT do Azure identidades de dispositivos e dispositivos duplos, mas fornecem uma granularidade mais fina. Enquanto Hub IoT do Azure identidades de dispositivos e dispositivos duplos permitem que uma aplicação de back-end configure um dispositivo e forneça visibilidade sobre as condições do dispositivo, as identidades dos módulos e os módulos duplos fornecem estas capacidades para componentes individuais de um dispositivo. Em dispositivos compatíveis com vários componentes, como dispositivos de sistema operativo ou dispositivos de firmware, permitem configuração e condições isoladas para cada componente.

Nota

As funcionalidades descritas neste artigo só estão disponíveis no escalão padrão do Hub IoT. Para obter mais informações sobre os escalões de Hub IoT básico e standard/gratuito, consulte Escolher o escalão de Hub IoT certo para a sua solução.

No final deste artigo, tem três aplicações Python:

CreateModule: cria uma identidade de dispositivo, uma identidade de módulo e chaves de segurança associadas para ligar os clientes do dispositivo e do módulo.
UpdateModuleTwinDesiredProperties: envia o módulo duplo atualizado, as propriedades pretendidas para o seu Hub IoT.
ReceiveModuleTwinDesiredPropertiesPatch: recebe o patch de propriedades pretendidas do módulo duplo no seu dispositivo.

Nota

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

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 uma com a CLI ou a portal do Azure.
Recomenda-se a versão 3.7 ou posterior do Python . 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.

Autenticação de módulos

Pode utilizar chaves simétricas ou certificados X.509 para autenticar identidades de módulos. Para a autenticação de certificado X.509, o certificado do módulo tem de ter o respetivo nome comum (CN) formatado como CN=<deviceid>/<moduleid>. Por exemplo:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Obter a cadeia de ligação do hub IoT

Neste artigo, vai criar um serviço de back-end que adiciona um dispositivo no registo de identidade e, em seguida, adiciona um módulo a esse dispositivo. Este serviço requer a permissão de escrita do registo (que também inclui a leitura do registo). Também vai criar um serviço que adiciona as propriedades pretendidas ao módulo duplo para o módulo criado recentemente. Este serviço precisa da permissão de ligação do serviço . Embora existam políticas de acesso partilhado predefinidas que concedem estas permissões individualmente, nesta secção, vai criar uma política de acesso partilhado personalizada que contém ambas as permissões.

Para criar uma política de acesso partilhado que conceda permissões de ligação ao serviço e de escrita do registo e para obter uma cadeia de ligação para esta política, siga estes passos:

Na 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 partilhado.
No menu acima da lista de políticas, selecione Adicionar política de acesso partilhado.
Em Adicionar política de acesso partilhado, introduza um nome descritivo para a sua política, como serviceAndRegistryReadWrite. Em Permissões, selecione Escrita no Registo e Ligação do Serviço e, em seguida, selecione Adicionar. (A permissão de Leitura do Registo é incluída automaticamente quando seleciona Escrita do Registo.)
Selecione a nova política na lista de políticas.
Em Chaves de acesso partilhadas, selecione o ícone de cópia da cadeia de ligação Primária e guarde o valor.

Para obter mais informações sobre Hub IoT permissões e políticas de acesso partilhado, veja Controlo de acesso e permissões.

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

Nesta secção, vai criar uma aplicação do serviço Python que cria uma identidade de dispositivo e uma identidade de módulo no registo de identidades no seu hub IoT. Um dispositivo ou módulo não consegue ligar-se ao hub IoT, a menos que tenha uma entrada no registo de identidade. Para obter mais informações, veja Compreender o registo de identidades no seu hub IoT. Ao executar esta aplicação de consola, será gerado um ID e uma chave exclusivos para o dispositivo e o módulo. O ID e a chave são sensíveis às maiúsculas e minúsculas. O dispositivo e o módulo utilizam estes valores para se identificarem quando enviam mensagens do dispositivo para cloud para o Hub IoT.

Na linha de comandos, execute o seguinte comando para instalar o pacote azure-iot-hub :
```
pip install azure-iot-hub
```
Na linha de comandos, execute o seguinte comando para instalar o pacote msrest . Precisa deste pacote para detetar exceções HTTPOperationError .
```
pip install msrest
```
Com um editor de texto, crie um ficheiro com o nome CreateModule.py no seu diretório de trabalho.

Adicione o seguinte código ao ficheiro Python. Substitua YourIoTHubConnectionString pela cadeia de ligação que copiou em Obter a cadeia de ligaçã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")

Na linha de comandos, execute o seguinte comando:
```
python CreateModule.py
```

Esta aplicação cria uma identidade de dispositivo com o ID myFirstDevice e uma identidade de módulo com o ID myFirstModule no dispositivo myFirstDevice. (Se o ID do dispositivo ou módulo já existir no registo de identidade, o código obtém simplesmente as informações do dispositivo ou módulo existentes.) A aplicação apresenta o ID e a chave primária para cada identidade.

Nota

O registo de identidade do Hub IoT apenas armazena identidades de dispositivos e módulos para permitir um acesso seguro ao hub IoT. O registo de identidades armazena os IDs de dispositivo e as chaves para utilizar como credenciais de segurança. O registo de identidades também armazena um sinalizador ativado/desativado para cada dispositivo que pode utilizar para desativar o acesso a esse dispositivo. Se a sua aplicação tiver de armazenar outros metadados específicos do dispositivo, deverá utilizar um armazenamento específico da aplicação. Não existe nenhum sinalizador ativado/desativado para identidades de módulo. Para obter mais informações, veja Compreender o registo de identidades no seu hub IoT.

Atualizar o módulo duplo com o SDK do serviço Python

Nesta secção, vai criar uma aplicação do serviço Python que atualiza as propriedades pretendidas do módulo duplo.

Na linha de comandos, execute o seguinte comando para instalar o pacote azure-iot-hub . Pode ignorar este passo se tiver instalado o pacote azure-iot-hub na secção anterior.
```
pip install azure-iot-hub
```
Com um editor de texto, crie um ficheiro com o nome UpdateModuleTwinDesiredProperties.py no seu diretório de trabalho.

Adicione o seguinte código ao ficheiro Python. Substitua YourIoTHubConnectionString pela cadeia de ligação que copiou em Obter a cadeia de ligaçã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 do lado do dispositivo

Nesta secção, vai criar uma aplicação Python para obter a atualização das propriedades pretendidas do módulo duplo no seu dispositivo.

Obtenha a cadeia de ligação do módulo. No portal do Azure, navegue até à sua 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 copiar para Cadeia de ligação (chave primária). Precisa desta cadeia de ligação num passo seguinte.
Na linha de comandos, execute o seguinte comando para instalar o pacote azure-iot-device :
```
pip install azure-iot-device
```
Com um editor de texto, crie um ficheiro com o nome ReceiveModuleTwinDesiredPropertiesPatch.py no seu diretório de trabalho.

Adicione o seguinte código ao ficheiro Python. Substitua YourModuleConnectionString pela cadeia de ligação do módulo que copiou no passo 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 as aplicações

Nesta secção, vai executar a aplicação de dispositivo ReceiveModuleTwinDesiredPropertiesPatch e, em seguida, executar a aplicação do serviço UpdateModuleTwinDesiredProperties para atualizar as propriedades pretendidas do módulo.

Abra uma linha de comandos e execute a aplicação do dispositivo:
```
python ReceiveModuleTwinDesiredPropertiesPatch.py
```
Abra uma linha de comandos separada e execute a aplicação de serviço:
```
python UpdateModuleTwinDesiredProperties.py
```
Repare que a propriedade pretendida TelemetryInterval aparece no módulo duplo atualizado na saída da aplicação de serviço:

A mesma propriedade aparece no patch de propriedades pretendidas recebido na saída da aplicação do dispositivo:

Passos seguintes

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

Partilhar via

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

Pré-requisitos

Autenticação de módulos

Obter a cadeia de ligação do hub IoT

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

Atualizar o módulo duplo com o SDK do serviço Python

Obter atualizações do lado do dispositivo

Executar as aplicações

Passos seguintes

Recursos adicionais