Introdução às identidades de módulo do Hub IoT e aos gêmeos de identidade do módulo

Artigo
12/04/2024

As identidades de módulo e os gêmeos da identidade do módulo são semelhantes às identidades do dispositivo e aos gêmeos do dispositivo do Hub IoT do Azure, mas fornecem granularidade mais fina. Enquanto as identidades de dispositivo e os gêmeos de dispositivo do Hub IoT do Azure permitem que o aplicativo de back-end configure um dispositivo e forneça visibilidade sobre as condições do dispositivo, uma identidade do módulo e um gêmeo da identidade do módulo fornecem esses recursos para componentes individuais de um dispositivo. Em dispositivos com capacidade para vários componentes, como dispositivos de sistema operacional ou dispositivos de firmware, as identidades do módulo e os gêmeos da identidade do módulo permitem configuração e condições isoladas para cada componente. Para obter mais informações, confira Noções básicas sobre os gêmeos do módulo do Hub IoT do Azure.

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.

Esse artigo mostra como desenvolver dois tipos de aplicativos:

Aplicativos de dispositivos que exibem e atualizam propriedades relatadas do gêmeo da identidade do módulo e tratam de solicitações para atualizar as propriedades desejadas.
Aplicativos de serviço que podem ler e definir as propriedades desejadas da identidade do módulo.

Observação

Esse artigo tem como objetivo complementar os exemplos de SDKs da Internet das Coisas do Azure referenciados nesse artigo. Você pode usar as ferramentas do SDK para criar aplicativos de dispositivo e de back-end.

Pré-requisitos

Um hub IoT
Um dispositivo do hub IoT
Uma identidade do módulo de dispositivo do hub IoT
Se o seu aplicativo usar o protocolo MQTT, certifique-se de que a porta 8883 está aberta no firewall. O protocolo MQTT 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).

Requer o Visual Studio

Visão geral

Este artigo descreve como usar o SDK da Internet das Coisas do Azure para .NET para criar um dispositivo e um código de aplicativo de serviço de back-end para gêmeos de identidade do módulo.

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código do aplicativo de dispositivo para:

Recuperar um gêmeo de identidade do módulo e examinar as propriedades relatadas
Atualizar as propriedades de gêmeo de identidade do módulo relatadas
Criar um manipulador de retorno de chamada de atualização de propriedade desejada pelo módulo

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.

Pacote NuGet do dispositivo necessário

Os aplicativos cliente de dispositivo escritos em C# exigem o pacote NuGet Microsoft.Azure.Devices.Client.

Adicione essas instruções using para usar a biblioteca de dispositivos.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

Conecte a um dispositivo

A classe ModuleClient expõe todos os métodos necessários para interagir com os gêmeos de identidade do módulo do dispositivo.

Conecte-se ao dispositivo usando o método CreateFromConnectionString com a cadeia de conexão de identidade do módulo.

A chamada CreateFromConnectionString sem um parâmetro de transporte se conecta usando o transporte AMQP padrão.

Este exemplo se conecta ao dispositivo usando o transporte AMQP padrão.

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

Recuperar um gêmeo de identidade do módulo e examinar propriedades

Chame GetTwinAsync para recuperar as propriedades atuais do gêmeo de identidade do módulo em um objeto Gêmeo.

Este exemplo recupera e exibe as propriedades do gêmeo de identidade do módulo no formato JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

Atualizar propriedades relatadas do gêmeo de identidade do módulo

Para atualizar uma propriedade relatada do gêmeo:

Crie um objeto TwinCollection para a atualização da propriedade relatada
Atualize uma ou mais propriedades relatadas dentro do objeto TwinCollection
Use UpdateReportedPropertiesAsync para efetuar push das alterações da propriedade relatada para o serviço do hub IoT

Por exemplo:

try
{
  Console.WriteLine("Sending sample start time as reported property");
  TwinCollection reportedProperties = new TwinCollection();
  reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
  await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Criar um manipulador de retorno de chamada de atualização de propriedade desejada

Passe o nome do método do manipulador de retorno de chamada para SetDesiredPropertyUpdateCallbackAsync para criar um manipulador de retorno de chamada de atualização de propriedade desejada que é executado quando uma propriedade desejada é alterada no módulo identity twin.

Por exemplo, essa chamada configura o sistema para notificar um método chamado OnDesiredPropertyChangedAsync sempre que uma propriedade de módulo desejada for alterada.

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

As propriedades do gêmeo da identidade do módulo são passadas para o método de retorno de chamada como um TwinCollection e podem ser examinadas como estruturas KeyValuePair.

Esse exemplo recebe as atualizações de propriedade desejadas como um TwinCollection, em seguida, faz loop e imprime as atualizações da coleção KeyValuePair. Depois de fazer loop pela coleção KeyValuePair, o código chama UpdateReportedPropertiesAsync para atualizar a propriedade relatada DateTimeLastDesiredPropertyChangeReceived para manter atualizado o tempo da última atualização.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Exemplo de módulo do SDK

O SDK da Internet das Coisas do Azure para .NET fornece exemplos de trabalho de aplicativos de dispositivo que lidam com tarefas do módulo gêmeo de identidade. Para saber mais, veja:

Criar um aplicativo de back-end

Esta seção descreve como ler e atualizar campos de identidade do módulo.

A classe RegistryManager expõe todos os métodos necessários para criar um aplicativo de back-end para interagir com os gêmeos de identidade do módulo do serviço.

Pacote NuGet de serviço necessário

Os aplicativos de serviço de back-end exigem o pacote NuGet Microsoft.Azure.Devices.

Adicione essas instruções using para usar a biblioteca de serviços.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Conectar ao Hub IoT

Você pode conectar um serviço de back-end ao Hub IoT usando os seguintes métodos:

Política de acesso compartilhado
Microsoft Entra

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.

Conectar-se usando a política de acesso compartilhado

Conecte um aplicativo de back-end ao hub IoT usando CreateFromConnectionString.

O método UpdateModuleAsync usado nesta seção requer a permissão da política de acesso compartilhado da Conexão de Serviço para adicionar as propriedades desejadas a um módulo. Como parâmetro para CreateFromConnectionString, forneça uma cadeia de conexão de política de acesso compartilhado que inclua a permissão da Conexão de Serviço. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as assinaturas de acesso compartilhado.

Por exemplo:

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Conectar-se usando o Microsoft Entra

Um aplicativo de back-end que usa o Microsoft Entra deve ser autenticado com sucesso e obter uma credencial de token de segurança antes de se conectar ao Hub IoT. Esse token é passado para um método de conexão do Hub IoT. Para obter informações gerais sobre como configurar e usar o Microsoft Entra para Hub IoT, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

Configurar o aplicativo Microsoft Entra

Você deve configurar um aplicativo do Microsoft Entra configurado para sua credencial de autenticação preferencial. O aplicativo contém parâmetros como o segredo do cliente que são usados pelo aplicativo de back-end para autenticação. As configurações de autenticação do aplicativo disponíveis são:

Segredo do cliente
Certificado
Credencial de identidade federada

Os aplicativos do Microsoft Entra podem exigir permissões de função específicas, dependendo das operações que estão sendo executadas. Por exemplo, o Colaborador gêmeo do Hub IoT é necessário para habilitar o acesso de leitura e gravação a um dispositivo do Hub IoT e a módulos gêmeos. Para obter mais informações, confira Gerenciar o acesso ao Hub IoT usando a atribuição de função RBAC do Azure.

Para obter mais informações sobre como configurar um aplicativo do Microsoft Entra, confira Início Rápido: Registrar um aplicativo com a plataforma de identidade da Microsoft.

Autenticar usando DefaultAzureCredential

A maneira mais fácil de usar o Microsoft Entra para autenticar um aplicativo de back-end é usar DefaultAzureCredential, mas é recomendável usar um método diferente em um ambiente de produção, incluindo um TokenCredential específico ou ChainedTokenCredential reduzido. Para simplificar, esta seção descreve a autenticação usando DefaultAzureCredential e um segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira as Diretrizes de uso para DefaultAzureCredential.

DefaultAzureCredential dá suporte a diferentes mecanismos de autenticação e determina o tipo de credencial apropriado com base no ambiente em que está sendo executado. Ele tenta usar vários tipos de credencial em uma ordem até encontrar uma credencial em funcionamento.

O Microsoft Entra requer estes pacotes NuGet e as instruções using correspondentes:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

Neste exemplo, o segredo do cliente de registro do aplicativo do Microsoft Entra, a ID do cliente e a ID do locatário são adicionados às variáveis de ambiente. Essas variáveis de ambiente são usadas pelo DefaultAzureCredential para autenticar o aplicativo. O resultado de uma autenticação bem-sucedida do Microsoft Entra é uma credencial de token de segurança que é passada para um método de conexão do Hub IoT.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

O TokenCredential resultante pode então ser passado para um método de conexão com o Hub IoT para um cliente do SDK que aceite as credenciais do Microsoft Entra:

Neste exemplo, o TokenCredential é passado para ServiceClient.Create para criar um objeto de conexão ServiceClient.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Neste exemplo, TokenCredential é passado para RegistryManager.Create para criar um objeto RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Exemplo de código

Para obter um exemplo prático da autenticação de serviço do Microsoft Entra, confira o Exemplo de autenticação baseada em função.

Ler e atualizar campos de identidade do módulo

Chame GetModuleAsync para recuperar os campos de gêmeos de identidade do módulo atual em um objeto Module.

A classe Module inclui properties que corresponde às seções de um gêmeo de identidade do módulo. Use as propriedades da classe Module para visualizar e atualizar os campos de gêmeos de identidade do módulo. Você pode usar as propriedades do objeto Module para atualizar vários campos antes de gravar as atualizações no dispositivo usando UpdateModuleAsync.

Depois de fazer as atualizações do campo do gêmeo da identidade do módulo, chame UpdateModuleAsync para gravar as atualizações do campo do objeto Module de volta em um dispositivo. Use a lógica try e catch acoplada a um manipulador de erros para capturar erros de patch formatados incorretamente de UpdateModuleAsync.

Esse exemplo recupera um módulo em um objeto Module, atualiza a propriedade module LastActivityTime e, em seguida, atualiza o módulo no Hub IoT usando UpdateModuleAsync.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

Outra API de módulo

GetModulesOnDeviceAsync — recupera as identidades do módulo em um dispositivo
RemoveModuleAsync — exclui um módulo registrado anteriormente de um dispositivo

Exemplo de serviço do SDK

O SDK da Internet das Coisas do Azure para .NET fornece um exemplo funcional de um aplicativo de serviço que lida com as tarefas do dispositivo gêmeo. Para obter mais informações, confira Testes E2E do Gerenciador de Registro.

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.

Visão geral

Este artigo descreve como usar o SDK da Internet das Coisas do Azure para Python para criar um dispositivo e um código de aplicativo de serviço de back-end para gêmeos de identidade do módulo.

Instalar Pacotes

A biblioteca azure-iot-device deve ser instalada para criar aplicativos de dispositivo.

pip install azure-iot-device

A biblioteca azure-iot-hub deve ser instalada para criar aplicativos de serviço de back-end.

pip install azure-iot-hub

A biblioteca msrest é usada para capturar exceções HTTPOperationError.

pip install msrest

Criar um aplicativo de dispositivo

Esta seção descreve como usar o código do aplicativo de dispositivo para:

Recuperar um gêmeo de identidade do módulo e examinar as propriedades relatadas
Atualizar propriedades relatadas do gêmeo de identidade do módulo
Criar um manipulador de retorno de chamada de atualização de propriedade desejada do gêmeo da identidade do módulo

Importante

Importar instruções

Adicione esta instrução import para usar a biblioteca de dispositivos.

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

Conecte a um dispositivo

A classe IoTHubModuleClient contém métodos que podem ser usados para trabalhar com gêmeos de identidade de módulo.

Para conectar um aplicativo a um dispositivo:

Chame create_from_connection_string para adicionar a cadeia de conexão de identidade do módulo
Chame connect para conectar o cliente do dispositivo a um Hub IoT do Azure

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{Device module identity connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

Recuperar um gêmeo de identidade do módulo e examinar propriedades

Chame get_twin para recuperar o gêmeo de identidade do módulo do serviço do Hub IoT do Azure. As informações sobre os gêmeos são colocadas em uma variável que pode ser examinada.

Esse exemplo recupera o dispositivo gêmeo e usa o comando print para exibir o dispositivo gêmeo no formato JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Atualizar propriedades relatadas do gêmeo de identidade do módulo

Você pode aplicar um patch para atualizar as propriedades relatadas dos gêmeos de identidade do módulo no formato JSON.

Para aplicar um patch para atualizar as propriedades relatadas:

Atribua um patch JSON da propriedade relatada a uma variável.
Chame patch_twin_reported_properties para aplicar o patch JSON às propriedades relatadas.

Por exemplo:

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Criar um manipulador de retorno de chamada de atualização de propriedade desejada do gêmeo da identidade do módulo

Chame on_twin_desired_properties_patch_received para criar uma função de manipulador ou corrotina que é chamada quando um patch de propriedades desejadas de gêmeos de identidade de módulo é recebido. O manipulador usa um argumento, que é o patch gêmeo na forma de um objeto de dicionário JSON.

Esse exemplo configura um manipulador de patch de propriedades desejadas chamado twin_patch_handler.

Por exemplo:

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

O twin_patch_handler recebe e imprime as atualizações de propriedades desejadas em JSON.

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

Exemplos de dispositivo do SDK

O SDK da Internet das Coisas do Azure para Python fornece uma amostra funcional de aplicativos de dispositivos que lidam com tarefas de gêmeos de identidade de módulo:

get_twin – Conectar-se a um dispositivo e recuperar as informações do gêmeo.
update_twin_reported_properties – Atualizar as propriedades relatadas do gêmeo.
receive_twin_desired_properties – Receber e atualizar as propriedades desejadas.

Criar um aplicativo de back-end

Esta seção descreve como criar um aplicativo de back-end para recuperar e atualizar as propriedades desejadas do gêmeo de identidade do módulo.

A classe IoTHubRegistryManager expõe todos os métodos necessários para criar um aplicativo de back-end para interagir com os gêmeos de identidade do módulo do serviço.

Instruções de importação de serviço

Adicione esta instrução import para usar a biblioteca de serviços.

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

Conectar-se ao Hub IoT

Você pode conectar um serviço de back-end ao Hub IoT usando os seguintes métodos:

Política de acesso compartilhado
Microsoft Entra

Importante

Conectar-se usando a política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string.

O método update_module_twin usado nesta seção requer a permissão da política de acesso compartilhado da Conexão de Serviço para adicionar as propriedades desejadas a um módulo. Como parâmetro para from_connection_string, forneça uma cadeia de conexão de política de acesso compartilhado que inclua a permissão da Conexão de Serviço. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as assinaturas de acesso compartilhado.

Por exemplo:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub shared access policy connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Conectar-se usando o Microsoft Entra

Para obter uma visão geral da autenticação do SDK do Python, confira Autenticar aplicativos Python nos serviços do Azure usando o SDK do Azure para Python

Configurar o aplicativo Microsoft Entra

Segredo do cliente
Certificado
Credencial de identidade federada

Para obter mais informações sobre como configurar um aplicativo do Microsoft Entra, confira Início Rápido: Registrar um aplicativo com a plataforma de identidade da Microsoft.

Autenticar usando DefaultAzureCredential

O DefaultAzureCredential dá suporte a diferentes mecanismos de autenticação e determina o tipo de credencial apropriado com base no ambiente em que está sendo executado. Ele tenta usar vários tipos de credencial em uma ordem até encontrar uma credencial em funcionamento.

O Microsoft Entra requer esse pacote de importação e a instrução import correspondente:

pip install azure-identity

from azure.identity import DefaultAzureCredential

Nesse exemplo, o segredo do cliente de registro do aplicativo do Microsoft Entra, a ID do cliente e a ID do locatário foram adicionados a variáveis de ambiente. Essas variáveis de ambiente são usadas pelo DefaultAzureCredential para autenticar o aplicativo. O resultado de uma autenticação bem-sucedida do Microsoft Entra é uma credencial de token de segurança que é passada para um método de conexão do Hub IoT.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

O AccessToken resultante pode então ser passado para from_token_credential para se conectar com o Hub IoT para um cliente do SDK que aceite as credenciais do Microsoft Entra:

IoTHubRegistryManager para criar uma conexão de serviço com o Hub IoT usando uma credencial de token do Entra.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential requer dois parâmetros:

A URL do serviço do Azure — A URL do serviço do Azure deve estar no formato {Your Entra domain URL}.azure-devices.net sem um prefixo https://. Por exemplo, MyAzureDomain.azure-devices.net.
O token de credencial do Azure

Nesse exemplo, a credencial do Azure é obtida usando DefaultAzureCredential. A URL e a credencial do serviço do Azure são fornecidas para IoTHubRegistryManager.from_token_credential para criar a conexão com o Hub IoT.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

Exemplos de código

Para obter exemplos de trabalho da autenticação de serviço do Microsoft Entra, confira a MSAL (Biblioteca de Autenticação da Microsoft) para Python.

Recuperar e atualizar as propriedades desejadas do gêmeo de identidade do módulo

Você pode atualizar as propriedades desejadas de um aplicativo de back-end usando update_module_twin.

Para recuperar e atualizar as propriedades desejadas do gêmeo de identidade do módulo:

Chame get_module_twin para obter a versão atual do gêmeo de identidade do módulo.
Use a classe Twin para adicionar as propriedades desejadas no formato JSON.
Chame update_module_twin para aplicar o patch ao dispositivo gêmeo. Você também pode usar replace_module_twin para substituir as propriedades e marcas desejadas para um gêmeo da identidade do módulo.

Este exemplo atualiza a propriedade telemetryInterval desejada para 122.

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity 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 identity 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" )

Exemplo de serviço do SDK

O SDK da Internet das Coisas do Azure para Python fornece um exemplo funcional de um aplicativo de serviço que lida com tarefas de gêmeos de identidade de módulo do dispositivo. Para obter mais informações, confira Testar o Gerenciador de Registro do IoTHub.

Requer Node.js versão 10.0.x ou posterior

Visão geral

Este artigo descreve como usar o SDK da Internet das Coisas do Azure para Node.js para criar código de aplicativo de serviço de back-end e dispositivo para gêmeos de identidade de módulo.

Criar um aplicativo de dispositivo

Esta seção descreve como usar o pacote azure-iot-device no SDK da Internet das Coisas do Azure para Node.js para criar um aplicativo de dispositivo para:

Recuperar um gêmeo de identidade do módulo e examinar as propriedades relatadas
Atualizar as propriedades de gêmeo relatadas na identidade do módulo
Receber aviso de alterações desejadas na propriedade do gêmeo de identidade do módulo

Importante

Instalar pacotes do SDK

Execute esse comando para instalar o SDK do dispositivo azure-iot-device em seu computador de desenvolvimento:

npm install azure-iot-device --save

O pacote azure-iot-device contém objetos que fazem interface com os dispositivos IoT. A classe Twin inclui objetos específicos de gêmeos. Esta seção descreve o código de classe Client que é usado para ler e gravar dados de gêmeos de identidade do módulo do dispositivo.

Escolher um protocolo de transporte

O objeto Client dá suporte a esses protocolos:

Amqp
Http - ao usar Http, a instância Client verifica as mensagens do Hub IoT com pouca frequência (um mínimo a cada 25 minutos).
Mqtt
MqttWs
AmqpWs

Instale os protocolos de transporte necessários em seu computador de desenvolvimento.

Por exemplo, esse comando instala o protocolo Amqp:

npm install azure-iot-device-amqp --save

Para obter mais informações sobre as diferenças entre o suporte a MQTT, AMQP e HTTPS, confira Diretrizes de comunicações entre nuvem e dispositivo e Escolher um protocolo de comunicação de dispositivo.

Criar um objeto cliente

Crie um objeto Client usando o pacote instalado.

Por exemplo:

const Client = require('azure-iot-device').Client;

Criar um objeto de protocolo

Crie um objeto Protocol usando um pacote de transporte instalado.

Este exemplo atribui o protocolo AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;

Adicionar a cadeia de conexão do dispositivo e o protocolo de transporte

Chame fromConnectionString para fornecer parâmetros de conexão do dispositivo:

connStr — A cadeia de conexão do módulo de identidade do hub IoT.
transportCtor – protocolo de transporte.

Esse exemplo usa o protocolo de transporte Amqp:

const deviceConnectionString = "{IoT hub identity module connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Abrir a conexão com o Hub IoT

Use o método open para abrir uma conexão entre um dispositivo IoT e o Hub IoT.

Por exemplo:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Recuperar um gêmeo de identidade do módulo e examinar as propriedades relatadas

Chame getTwin para recuperar as informações de gêmeos de identidade do módulo atual em um objeto Twin.

O código do dispositivo poderá então acessar as propriedades do gêmeo da identidade do módulo.

Por exemplo:

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

Atualizar propriedades relatadas do gêmeo de identidade do módulo

Use update para atualizar as propriedades relatadas do dispositivo. Inclua um patch no formato JSON como o primeiro parâmetro e o método de retorno de chamada do status de execução da função como o segundo parâmetro do método.

Nesse exemplo, um patch gêmeo da identidade do módulo formatado em JSON é armazenado na variável patch. O patch contém um valor de atualização connectivity do gêmeo da identidade do módulo de cellular. O patch e o manipulador de erros são passados para o método update. Se houver um erro, uma mensagem de erro do console será exibida.

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Receber aviso de alterações desejadas na propriedade do gêmeo de identidade do módulo

Crie um ouvinte de eventos de atualização de propriedade desejada do gêmeo da identidade do módulo que seja executado quando uma propriedade desejada for alterada, passando o nome do método do manipulador de retorno de chamada para twin.on.

O ouvinte de eventos da propriedade desejada pode assumir as seguintes formas:

Receber todos os patches com um único manipulador de eventos
Receber um evento se algo mudar em um agrupamento de propriedades
Receber um evento para uma única alteração de propriedade

Receber todos os patches com um único manipulador de eventos

Você pode criar um ouvinte para receber as alterações da propriedade desejada.

Esse código de exemplo gera todas as propriedades recebidas do serviço.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Receber um evento se algo mudar em um agrupamento de propriedades

Você pode criar um ouvinte para receber um evento se algo em um agrupamento de propriedades for alterado.

Por exemplo:

As propriedades minTemperature e maxTemperature estão localizadas em um agrupamento de propriedades chamado properties.desired.climate changes.
Um aplicativo de serviço de back-end aplica esse patch para atualizar as propriedades desejadas minTemperature e maxTemperature:
```
const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };
```

Esse código configura um ouvinte de eventos de alteração da propriedade desejada que é disparado para qualquer alteração no agrupamento de propriedades properties.desired.climate. Se houver uma alteração de propriedade desejada nesse grupo, as mensagens de alteração de temperatura mínima e máxima serão exibidas no console:

twin.on('properties.desired.climate', function (delta) {
    if (delta.minTemperature || delta.maxTemperature) {
        console.log('updating desired temp:');
        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
    }
});

Receber um evento para uma única alteração de propriedade

Você pode configurar um ouvinte para uma única alteração de propriedade. Nesse exemplo, o código para esse evento será executado somente se o valor booliano fanOn fizer parte do patch. O código gera o novo estado fanOn desejado sempre que o serviço o atualiza.

Um aplicativo de back-end aplica esse patch de propriedade desejada:

 const twinPatch2 = {
  properties: {
    desired: {
      climate: {
        hvac: {
          systemControl: { fanOn: true, },
        },
      },
    },
  },
};

O ouvinte dispara somente quando a propriedade fanOn é alterada:

 twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
     console.log('setting fan state to ' + fanOn);
  });

Exemplo completo

Este exemplo encapsula os princípios dessa seção, incluindo o aninhamento de funções de retorno de chamada em vários níveis.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

Exemplos do SDK do dispositivo

O SDK da Internet das Coisas do Azure para Node.js fornece exemplos funcionais de aplicativos de dispositivos que lidam com tarefas de gêmeos de identidade de módulo. Para saber mais, veja:

Criar um aplicativo de back-end

Esta seção descreve como criar um aplicativo de back-end que recupera um gêmeo de identidade do módulo e atualiza as propriedades desejadas.

Instalar o pacote do SDK de serviço

Execute esse comando para instalar azure-iothub em seu computador de desenvolvimento:

npm install azure-iothub --save

Criar um objeto Registry

A classe Registry expõe todos os métodos necessários para interagir com os gêmeos de identidade de módulo a partir de um aplicativo de back-end.

let Registry = require('azure-iothub').Registry;

Conectar-se ao Hub IoT

Você pode conectar um serviço de back-end ao Hub IoT usando os seguintes métodos:

Política de acesso compartilhado
Microsoft Entra

Importante

Conectar-se usando a política de acesso compartilhado

Use fromConnectionString para se conectar ao hub IoT.

O método update usado nesta seção requer a permissão da política de acesso compartilhado da Conexão de Serviço para adicionar as propriedades desejadas a um módulo. Como parâmetro para fromConnectionString, forneça uma cadeia de conexão de política de acesso compartilhado que inclua a permissão da Conexão de Serviço. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as assinaturas de acesso compartilhado.

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

Conectar-se usando o Microsoft Entra

Para obter uma visão geral da autenticação do SDK Node.js, confira:

Configurar o aplicativo Microsoft Entra

Segredo do cliente
Certificado
Credencial de identidade federada

Para obter mais informações sobre como configurar um aplicativo do Microsoft Entra, confira Início Rápido: Registrar um aplicativo com a plataforma de identidade da Microsoft.

Autenticar usando DefaultAzureCredential

O Microsoft Entra requer este pacote:

npm install --save @azure/identity

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

O token de credencial resultante pode então ser passado para fromTokenCredential para se conectar ao Hub IoT para um cliente do SDK que aceite as credenciais do Microsoft Entra:

fromTokenCredential requer dois parâmetros:

A URL do serviço do Azure — A URL do serviço do Azure deve estar no formato {Your Entra domain URL}.azure-devices.net sem um prefixo https://. Por exemplo, MyAzureDomain.azure-devices.net.
O token de credencial do Azure

Nesse exemplo, a credencial do Azure é obtida usando DefaultAzureCredential. A URL de domínio e a credencial do Azure são fornecidas para Registry.fromTokenCredential para criar a conexão com o Hub IoT.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Exemplos de código

Para obter exemplos de trabalho da autenticação de serviço do Microsoft Entra, confira Exemplos de identidade do Azure.

Recuperar um gêmeo de identidade do módulo e atualizar as propriedades desejadas

Você pode criar um patch que contenha as atualizações de propriedade desejadas para um gêmeo de identidade do módulo.

Para atualizar um gêmeo de identidade do módulo:

Chame getModuleTwin para recuperar o objeto Twin do dispositivo.
Formate um patch que contenha a atualização dupla da identidade do módulo. O patch estpá no formato JSON, conforme descrito na classe Twin. Um patch de serviço de back-end contém atualizações de propriedade desejadas. Para obter mais informações sobre o formato de patch, confira Tags e formato de propriedades.
Chame update para atualizar o gêmeo de identidade do módulo com o patch.

Neste exemplo, o gêmeo de identidade do módulo é recuperado para myDeviceId e myModuleId. Em seguida, um patch é aplicado aos gêmeos que contêm informações de climate.

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

Exemplos de SDK do serviço

O SDK da Internet das Coisas do Azure para Node.js fornece exemplos funcionais de aplicativos de serviço que lidam com tarefas de gêmeos de identidade de módulo. Para saber mais, veja:

Compartilhar via

Introdução às identidades de módulo do Hub IoT e aos gêmeos de identidade do módulo

Pré-requisitos

Visão geral

Criar um aplicativo de dispositivo

Pacote NuGet do dispositivo necessário

Conecte a um dispositivo

Recuperar um gêmeo de identidade do módulo e examinar propriedades

Atualizar propriedades relatadas do gêmeo de identidade do módulo

Criar um manipulador de retorno de chamada de atualização de propriedade desejada

Exemplo de módulo do SDK

Criar um aplicativo de back-end

Pacote NuGet de serviço necessário

Conectar ao Hub IoT

Conectar-se usando a política de acesso compartilhado

Conectar-se usando o Microsoft Entra

Configurar o aplicativo Microsoft Entra

Autenticar usando DefaultAzureCredential

Exemplo de código

Ler e atualizar campos de identidade do módulo

Outra API de módulo

Exemplo de serviço do SDK

Visão geral

Instalar Pacotes

Criar um aplicativo de dispositivo

Importar instruções

Conecte a um dispositivo

Recuperar um gêmeo de identidade do módulo e examinar propriedades

Atualizar propriedades relatadas do gêmeo de identidade do módulo

Criar um manipulador de retorno de chamada de atualização de propriedade desejada do gêmeo da identidade do módulo

Exemplos de dispositivo do SDK

Criar um aplicativo de back-end

Instruções de importação de serviço

Conectar-se ao Hub IoT

Conectar-se usando a política de acesso compartilhado

Conectar-se usando o Microsoft Entra

Configurar o aplicativo Microsoft Entra

Autenticar usando DefaultAzureCredential

Exemplos de código

Recuperar e atualizar as propriedades desejadas do gêmeo de identidade do módulo

Exemplo de serviço do SDK

Visão geral

Criar um aplicativo de dispositivo

Instalar pacotes do SDK

Escolher um protocolo de transporte

Criar um objeto cliente

Criar um objeto de protocolo

Adicionar a cadeia de conexão do dispositivo e o protocolo de transporte

Abrir a conexão com o Hub IoT

Recuperar um gêmeo de identidade do módulo e examinar as propriedades relatadas

Atualizar propriedades relatadas do gêmeo de identidade do módulo

Receber aviso de alterações desejadas na propriedade do gêmeo de identidade do módulo

Receber todos os patches com um único manipulador de eventos

Receber um evento se algo mudar em um agrupamento de propriedades

Receber um evento para uma única alteração de propriedade

Exemplo completo

Exemplos do SDK do dispositivo

Criar um aplicativo de back-end

Instalar o pacote do SDK de serviço

Criar um objeto Registry

Conectar-se ao Hub IoT

Conectar-se usando a política de acesso compartilhado

Conectar-se usando o Microsoft Entra

Configurar o aplicativo Microsoft Entra

Autenticar usando DefaultAzureCredential

Exemplos de código

Recuperar um gêmeo de identidade do módulo e atualizar as propriedades desejadas

Exemplos de SDK do serviço

Comentários

Recursos adicionais