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

Artigo
12/04/2024

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

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.

Este artigo mostra como desenvolver dois tipos de aplicativos:

Aplicativos de dispositivo que visualizam e atualizam a identidade do módulo geminam as propriedades relatadas e lidam com solicitações para atualizar as propriedades desejadas.
Aplicativos de serviço que podem ler e definir as propriedades desejadas da identidade do módulo.

Nota

Este artigo destina-se a complementar exemplos de SDKs do Azure IoT referenciados neste artigo. Você pode usar ferramentas SDK para criar aplicativos de dispositivo e back-end.

Pré-requisitos

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

Requer o Visual Studio

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para .NET 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 código do aplicativo de dispositivo para:

Recuperar um gêmeo de identidade de módulo e examinar as propriedades relatadas
Atualizar propriedades gêmeas de identidade do módulo relatado
Criar um manipulador de retorno de chamada de atualização de propriedade desejado do 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 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.

Pacote NuGet do dispositivo necessário

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

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

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

Ligar a um dispositivo

A classe ModuleClient expõe todos os métodos necessários para interagir com gêmeos de identidade de 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 de módulo e examinar propriedades

Chame GetTwinAsync para recuperar as propriedades gêmeas da identidade do módulo atual em um objeto Twin .

Este exemplo recupera e exibe propriedades gêmeas 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 de gêmeos de identidade do módulo

Para atualizar uma propriedade dupla relatada:

Criar um objeto TwinCollection para a atualização de propriedade relatada
Atualizar uma ou mais propriedades relatadas dentro do TwinCollection objeto
Use UpdateReportedPropertiesAsync para enviar por push as alterações de propriedade relatadas para o serviço de 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 desejado

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 desejado que é executado quando uma propriedade desejada é alterada no gêmeo de identidade do módulo.

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

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

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

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

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 SDK

O SDK do Azure IoT para .NET fornece exemplos funcionais de aplicativos de dispositivo que lidam com tarefas gêmeas de identidade de módulo. Para obter mais informações, consulte:

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 gêmeos de identidade de 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 using instruções para usar a biblioteca de serviços.

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

Ligar a um Hub IoT

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

Política de acesso partilhado
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 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.

Conectar-se usando uma política de acesso compartilhado

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

O UpdateModuleAsync método usado nesta seção requer a permissão da política de acesso compartilhado do Service Connect para adicionar as propriedades desejadas a um módulo. Como parâmetro para CreateFromConnectionStringo , forneça uma cadeia de conexão de política de acesso compartilhado que inclua a permissão Service Connect . Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com 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 autenticar e obter com êxito 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, consulte Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.

Configurar o aplicativo Microsoft Entra

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

Segredo do cliente
Certificado
Credencial de identidade federada

Os aplicativos 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 gêmeos de módulo. Para obter mais informações, consulte 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 Microsoft Entra, consulte Guia de 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 específico TokenCredential ou ChainedTokenCredentialreduzido. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras do uso DefaultAzureCredentialdo , consulte Diretrizes de uso para DefaultAzureCredential.

DefaultAzureCredential suporta 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 credenciais em uma ordem até encontrar uma credencial de trabalho.

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

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

Neste exemplo, o segredo do cliente de registro do aplicativo 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 por 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 ser passado para um método de conexão ao Hub IoT para qualquer cliente SDK que aceite 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, o TokenCredential é passado para RegistryManager.Create 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 de autenticação de serviço do Microsoft Entra, consulte Exemplo de autenticação baseada em função.

Ler e atualizar campos de identidade do módulo

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

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

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

Este exemplo recupera um módulo em um Module objeto, atualiza a module LastActivityTime propriedade 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);
}

API de outro 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 SDK

O SDK do Azure IoT para .NET fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas de identidade de módulo. Para obter mais informações, consulte Testes E2E do Gerenciador do Registro.

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.

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para Python para criar código de aplicativo de serviço de dispositivo e back-end para gêmeos de identidade de 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 de módulo e examinar as propriedades relatadas
Atualizar propriedades de gêmeos de identidade do módulo
Criar um manipulador de retorno de chamada de atualização de propriedade desejada do gêmeo de identidade do módulo

Importante

Declarações de importação

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

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

Ligar 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
Ligar 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 de módulo e examinar propriedades

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

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

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

Atualizar propriedades de gêmeos de identidade do módulo

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

Para aplicar um patch para atualizar as propriedades relatadas:

Atribua um patch JSON de 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 de identidade do módulo

Chame on_twin_desired_properties_patch_received para criar uma função de manipulador ou co-rotina que é chamada quando um patch de propriedades desejadas do gêmeo 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.

Este 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 propriedade desejadas do JSON.

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

Exemplos de dispositivos SDK

O SDK do Azure IoT para Python fornece um exemplo funcional de aplicativos de dispositivo que lidam com tarefas gêmeas de identidade de módulo:

get_twin - Conecte-se a um dispositivo e recupere informações de gêmeos.
update_twin_reported_properties - Atualize as propriedades relatadas por gêmeos.
receive_twin_desired_properties - Receba e atualize as propriedades desejadas.

Criar um aplicativo de back-end

Esta seção descreve como criar um aplicativo 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 gêmeos de identidade de módulo do serviço.

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

Adicione esta import instrução 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 partilhado
Microsoft Entra

Importante

Conectar-se usando uma política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string.

O update_module_twin método usado nesta seção requer a permissão da política de acesso compartilhado do Service Connect para adicionar as propriedades desejadas a um módulo. Como parâmetro para from_connection_stringo , forneça uma cadeia de conexão de política de acesso compartilhado que inclua a permissão Service Connect . Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com 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, consulte 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 Microsoft Entra, consulte Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

Autenticar usando 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 credenciais em uma ordem até encontrar uma credencial de trabalho.

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

pip install azure-identity

from azure.identity import DefaultAzureCredential

Neste exemplo, o segredo do cliente de registro do aplicativo Microsoft Entra, a ID do cliente e a ID do locatário foram adicionados às variáveis de ambiente. Essas variáveis de ambiente são usadas por 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 ser passado para from_token_credential se conectar ao Hub IoT para qualquer cliente SDK que aceite credenciais do Microsoft Entra:

IoTHubRegistryManager para criar uma conexão de serviço com o Hub IoT usando uma credencial de token 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 https:// prefixo. Por exemplo, MyAzureDomain.azure-devices.net.
O token de credencial do Azure

Neste exemplo, a credencial do Azure é obtida usando DefaultAzureCredentialo . A URL e a credencial do serviço do Azure são fornecidas para IoTHubRegistryManager.from_token_credential 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)

Amostras de código

Para obter exemplos de trabalho da autenticação do serviço Microsoft Entra, consulte Microsoft Authentication Library (MSAL) for 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:

Ligue para 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.
Ligue update_module_twin para aplicar o patch no dispositivo gêmeo. Você também pode usar replace_module_twin para substituir propriedades e tags desejadas para um gêmeo de identidade de módulo.

Este exemplo atualiza a telemetryInterval propriedade 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 SDK

O SDK do Azure IoT para Python fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas do módulo de identidade do dispositivo. Para obter mais informações, consulte Test IoTHub Registry Manager.

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

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para Node.js para criar código de aplicativo de serviço de dispositivo e back-end 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 do Azure IoT para Node.js criar um aplicativo de dispositivo para:

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

Importante

Instalar pacotes SDK

Execute este comando para instalar o SDK do dispositivo azure-iot-device em sua máquina de desenvolvimento:

npm install azure-iot-device --save

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

Escolha um protocolo de transporte

O Client objeto suporta estes protocolos:

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

Instale os protocolos de transporte necessários em sua máquina de desenvolvimento.

Por exemplo, este comando instala o Amqp protocolo:

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

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

Criar um objeto cliente

Crie um Client objeto usando o pacote instalado.

Por exemplo:

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

Criar um objeto de protocolo

Crie um Protocol objeto 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 - O protocolo de transporte.

Este exemplo usa o Amqp protocolo de transporte:

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

Abra 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 de módulo e examinar as propriedades relatadas

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

O código do dispositivo pode então acessar as propriedades do gêmeo de 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 de gêmeos de identidade do módulo

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

Neste exemplo, um patch gêmeo de identidade de módulo formatado patch em JSON é armazenado na variável. O patch contém um valor de atualização gêmea connectivity de identidade do módulo de cellular. O patch e o manipulador de erros são passados para o update método. 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 de propriedade desejadas do gêmeo de identidade do módulo

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

O ouvinte de eventos de propriedade desejado pode assumir as seguintes formas:

Receba 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

Receba todos os patches com um único manipulador de eventos

Você pode criar um ouvinte para receber qualquer alteração de propriedade desejada.

Este código de exemplo gera a saída de 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 mudar.

Por exemplo:

As minTemperature propriedades e maxTemperature estão localizadas sob um agrupamento de propriedades chamado properties.desired.climate changes.
Um aplicativo de serviço de back-end aplica esse patch à atualização minTemperature e maxTemperature às propriedades desejadas:
```
const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };
```
Esse código configura um ouvinte de eventos de alteração de propriedade desejado que é acionado para quaisquer alterações dentro do agrupamento de properties.desired.climate propriedades. Se houver uma alteração de propriedade desejada dentro desse 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. Neste exemplo, o código para esse evento é executado somente se o fanOn valor booleano fizer parte do patch. O código produz o novo estado desejado fanOn sempre que o serviço o atualiza.

Um aplicativo de back-end aplica este patch de propriedade desejado:

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

O ouvinte aciona somente quando a fanOn propriedade muda:

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

Exemplo completo

Este exemplo encapsula os princípios desta seção, incluindo aninhamento de função de retorno de chamada de 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 de SDK de dispositivo

O SDK do Azure IoT para Node.js fornece exemplos funcionais de aplicativos de dispositivo que lidam com tarefas gêmeas de identidade de módulo. Para obter mais informações, consulte:

Criar um aplicativo de back-end

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

Instalar pacote SDK de serviço

Execute este comando para instalar o azure-iothub em sua máquina 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 gêmeos de identidade de módulo de um aplicativo 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 partilhado
Microsoft Entra

Importante

Conectar-se usando uma política de acesso compartilhado

Use fromConnectionString para se conectar ao hub IoT.

O update método usado nesta seção requer a permissão da política de acesso compartilhado do Service Connect para adicionar as propriedades desejadas a um módulo. Como parâmetro para fromConnectionStringo , forneça uma cadeia de conexão de política de acesso compartilhado que inclua a permissão Service Connect . Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com 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 Node.js SDK, consulte:

Configurar o aplicativo Microsoft Entra

Segredo do cliente
Certificado
Credencial de identidade federada

Para obter mais informações sobre como configurar um aplicativo Microsoft Entra, consulte Guia de 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 ser passado para fromTokenCredential para se conectar ao Hub IoT para qualquer cliente SDK que aceite 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 https:// prefixo. Por exemplo, MyAzureDomain.azure-devices.net.
O token de credencial do Azure

Neste exemplo, a credencial do Azure é obtida usando DefaultAzureCredentialo . A URL e a credencial do domínio do Azure são fornecidas para Registry.fromTokenCredential 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);

Amostras de código

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

Recuperar um gêmeo de identidade de 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 de módulo.

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

Chame getModuleTwin para recuperar o objeto Twin do dispositivo.
Formate um patch que contenha a atualização do gêmeo de identidade do módulo. O patch é formatado em 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 do patch, consulte Tags e formato de propriedades.
Ligue 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 adesivo é aplicado aos gêmeos que contém climate informações.

// 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 de serviço

O SDK do Azure IoT para Node.js fornece exemplos funcionais de aplicativos de serviço que lidam com tarefas gêmeas de identidade de módulo. Para obter mais informações, consulte:

Partilhar via

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

Pré-requisitos

Descrição geral

Criar um aplicativo de dispositivo

Pacote NuGet do dispositivo necessário

Ligar a um dispositivo

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

Atualizar propriedades de gêmeos de identidade do módulo

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

Exemplo de módulo SDK

Criar um aplicativo de back-end

Pacote NuGet de serviço necessário

Ligar a um Hub IoT

Conectar-se usando uma 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

API de outro módulo

Exemplo de serviço SDK

Descrição geral

Instalar pacotes

Criar um aplicativo de dispositivo

Declarações de importação

Ligar a um dispositivo

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

Atualizar propriedades de gêmeos de identidade do módulo

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

Exemplos de dispositivos SDK

Criar um aplicativo de back-end

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

Conectar-se ao hub IoT

Conectar-se usando uma política de acesso compartilhado

Conectar-se usando o Microsoft Entra

Configurar o aplicativo Microsoft Entra

Autenticar usando DefaultAzureCredential

Amostras de código

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

Exemplo de serviço SDK

Descrição geral

Criar um aplicativo de dispositivo

Instalar pacotes SDK

Escolha 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

Abra a conexão com o Hub IoT

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

Atualizar propriedades de gêmeos de identidade do módulo

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

Receba 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 de SDK de dispositivo

Criar um aplicativo de back-end

Instalar pacote SDK de serviço

Criar um objeto Registry

Conectar-se ao hub IoT

Conectar-se usando uma política de acesso compartilhado

Conectar-se usando o Microsoft Entra

Configurar o aplicativo Microsoft Entra

Autenticar usando DefaultAzureCredential

Amostras de código

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

Exemplos de SDK de serviço

Comentários

Recursos adicionais