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

Artigo
03/21/2023

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

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.

No fim deste artigo, você terá dois aplicativos de console .NET:

CreateIdentities: cria uma identidade de dispositivo, uma identidade de módulo e uma chave de segurança associada para conectar seus clientes de dispositivo e módulo.
UpdateModuleTwinReportedProperties: envia propriedades relatadas atualizadas de módulo gêmeo ao hub IoT.

Observação

Consulte os SDKs da IoT do Azure para obter mais informações sobre as ferramentas do SDK disponíveis para compilar aplicativos de dispositivo e back-end.

Pré-requisitos

Visual Studio.
Um hub IoT. Crie um com a CLI ou o portal do Azure.

Autenticação do módulo

Você pode utilizar chaves simétricas ou certificados X.509 para autenticar as identidades dos módulos. Para autenticação de certificado X.509, o certificado do módulo deve ter seu CN (nome comum) 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 conexão do hub IoT

Neste artigo, você criará um serviço de back-end que adiciona um dispositivo no registro de identidade e, em seguida, adiciona um módulo a esse dispositivo. Seu serviço requer a permissão de gravação do registro. Por padrão, todo hub IoT é criado com uma política de acesso compartilhado chamada registryReadWrite que concede essa permissão.

Para obter a cadeia de conexão do Hub IoT para a política registryReadWrite, siga estas etapas:

No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel do lado esquerdo do hub, selecione Políticas de acesso compartilhado.
Na lista de políticas, selecione a política registryReadWrite.
Copie a Cadeia de conexão primária e salve o valor.

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Criar uma identidade de módulo

Nesta seção, você criará um aplicativo de console .NET que cria uma identidade do dispositivo e uma identidade do módulo no registro de identidade em seu hub. Um dispositivo ou módulo não pode se conectar ao hub, a menos que ele tenha uma entrada no registro de identidade. Para obter mais informações, consulte a seção Registro de identidade do Guia do desenvolvedor do Hub IoT.

Quando você executa esse aplicativo de console, ele gera ID e chave exclusivas para o dispositivo e o módulo. O dispositivo e o módulo usam esses valores para se identificar ao enviar mensagens de dispositivo para nuvem para o Hub IoT. As IDs diferenciam minúsculas e maiúsculas.

Abra o Visual Studio e selecione Criar um projeto.
Em Criar um projeto, selecione Aplicativo de Console (.NET Framework) .
Selecione Avançar para exibir a tela Configurar seu novo projeto. Nomeie o projeto CreateIdentities e selecione Avançar.
Mantenha a opção padrão do .NET Framework e selecione Criar para criar seu projeto.
No Visual Studio, abra Ferramentas>Gerenciador de Pacotes NuGet>Gerenciar Pacotes NuGet para a Solução. Selecione a guia Procurar.
Procure o Microsoft.Azure.Devices. Selecione-o e, em seguida, selecione Instalar.

Adicione as instruções using abaixo na parte superior do arquivo Program.cs :

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;

Adicione os seguintes campos à classe Program . Substitua o valor do espaço reservado pela cadeia de conexão do Hub IoT criado na seção anterior.

const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";

Adicione o seguinte código para a classe Principal.

static void Main(string[] args)
{
    AddDeviceAsync().Wait();
    AddModuleAsync().Wait();
}

Adicione os seguintes métodos à classe Programa:

private static async Task AddDeviceAsync()
{
   RegistryManager registryManager = 
     RegistryManager.CreateFromConnectionString(connectionString);
   Device device;

   try
   {
       device = await registryManager.AddDeviceAsync(new Device(deviceID));
   }
   catch (DeviceAlreadyExistsException)
    {
        device = await registryManager.GetDeviceAsync(deviceID);
    }

    Console.WriteLine("Generated device key: {0}", 
      device.Authentication.SymmetricKey.PrimaryKey);
}

private static async Task AddModuleAsync()
{
    RegistryManager registryManager = 
      RegistryManager.CreateFromConnectionString(connectionString);
    Module module;

    try
    {
        module = 
          await registryManager.AddModuleAsync(new Module(deviceID, moduleID));
    }
    catch (ModuleAlreadyExistsException)
    {
        module = await registryManager.GetModuleAsync(deviceID, moduleID);
    }

    Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKey.PrimaryKey);
}

Esse método AddDeviceAsync cria uma identidade do dispositivo com a ID myFirstDevice. Se essa ID do dispositivo já existir no registro de identidade, o código simplesmente irá recuperar as informações do dispositivo existentes. Em seguida, o aplicativo exibe a chave primária dessa identidade. Você usa essa chave no aplicativo de dispositivo simulado para se conectar ao hub.

O método AddModuleAsync cria uma identidade de módulo com a ID myFirstModule no dispositivo myFirstDevice. Se essa ID de módulo já existir no registro de identidade, o código simplesmente irá recuperar as informações do módulo existentes. Em seguida, o aplicativo exibe a chave primária dessa identidade. Você usa essa chave no aplicativo de módulo simulado para se conectar ao hub.

Importante

A ID do dispositivo pode estar visível nos logs coletados para o atendimento ao cliente e à solução de problemas. Portanto, evite informações confidenciais ao nomear.

Execute este aplicativo e anote a chave do dispositivo e a chave do módulo.

Observação

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

Atualizar o módulo gêmeo usando o SDK do dispositivo .NET

Agora vamos nos comunicar com a nuvem pelo dispositivo simulado. Depois de criar uma identidade de módulo, um módulo gêmeo é implicitamente criado no Hub IoT. Nesta seção, você criará um aplicativo de console .NET em seu dispositivo simulado que atualiza as propriedades relatadas do módulo gêmeo.

Para recuperar a cadeia de conexão do módulo, navegue até o hub IoT e selecione Dispositivos. Selecione myFirstDevice para abri-lo e, em seguida, selecione myFirstModule para abri-lo. Em Detalhes de Identidade do Módulo, copie a Cadeia de conexão (chave primária) e salve-a para o aplicativo de console.

No Visual Studio, adicione um novo projeto à sua solução selecionando Arquivo>Novo>Projeto. Em Criar um projeto, selecione Aplicativo de Console (.NET Framework) e, em seguida, selecione Avançar.
Em Configurar novo projeto, nomeie o projeto como UpdateModuleTwinReportedProperties e selecione Avançar.
Mantenha a opção padrão do .NET Framework e selecione Criar para criar seu projeto.
No Visual Studio, abra Ferramentas>Gerenciador de Pacotes NuGet>Gerenciar Pacotes NuGet para a Solução. Selecione a guia Procurar.
Pesquise e selecione Microsoft.Azure.Devices.Client e, em seguida, selecione Instalar.

Adicione as instruções using abaixo na parte superior do arquivo Program.cs :

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using System.Threading.Tasks;
using Newtonsoft.Json;

Adicione os seguintes campos à classe Program . Substitua o valor de espaço reservado pela cadeia de conexão do módulo.

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;
static void ConnectionStatusChangeHandler(ConnectionStatus status, 
  ConnectionStatusChangeReason reason)
{
    Console.WriteLine("Connection Status Changed to {0}; the reason is {1}", 
      status, reason);
}

Adicione o seguinte método OnDesiredPropertyChanged à classe de Programa:

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

Adicione as seguintes linhas ao método Main:

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = 
      Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = 
          ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin.Properties)); 

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadLine();
    Client.CloseAsync().Wait();
}

Agora você já sabe como recuperar o módulo gêmeo e atualizar as propriedades relatadas com o protocolo AMQP.

Opcionalmente, você pode adicionar estas instruções ao método Main para enviar um evento ao Hub IoT do seu módulo. Coloque essas linhas abaixo do bloco try catch.

Byte[] bytes = new Byte[2];
bytes[0] = 0;
bytes[1] = 1;
var sendEventsTask = Client.SendEventAsync(new Message(bytes));
sendEventsTask.Wait();
Console.WriteLine("Event sent to IoT Hub.");

Executar os aplicativos

Agora você pode executar os aplicativos novamente.

No Visual Studio, no Gerenciador de Soluções, clique com o botão direito do mouse na solução e selecione Definir Projetos de Inicialização.
Em Propriedades Comuns, selecione Projeto de Inicialização.
Selecione Vários projetos de inicialização e, em seguida, selecione Iniciar como a ação para os aplicativos e OK para aceitar as alterações.
Pressione F5 para iniciar os aplicativos.

Próximas etapas

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

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

Pré-requisitos

Autenticação do módulo

Obter a cadeia de conexão do hub IoT

Criar uma identidade de módulo

Atualizar o módulo gêmeo usando o SDK do dispositivo .NET

Executar os aplicativos

Próximas etapas

Recursos adicionais