Introdução à identidade do módulo do Hub IoT e ao módulo gêmeo usando o portal do Azure e um dispositivo .NET

Artigo
10/01/2024

As identidades de módulo e os módulos duplos assemelham-se à identidade do dispositivo e ao dispositivo duplo do Hub IoT do Azure, exceto no facto de oferecerem melhor granularidade. Enquanto a identidade do dispositivo do Hub IoT do Azure e o gêmeo 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 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 módulo permitem configuração e condições isoladas para cada componente.

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.

Neste artigo, você aprenderá a:

Crie uma identidade de módulo no portal.
Use um SDK de dispositivo .NET para atualizar o módulo gêmeo do seu dispositivo.

Nota

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

Pré-requisitos

Visual Studio.
Um hub IoT em sua assinatura do Azure. Se você ainda não tiver um hub, siga as etapas em Criar um hub IoT.
Um dispositivo registrado em seu hub IoT. Se você não tiver um dispositivo em seu hub IoT, siga as etapas em Registrar um dispositivo.

Autenticação do módulo

Você pode usar chaves simétricas ou certificados X.509 para autenticar identidades de módulo. Para autenticação de certificado X.509, o certificado do módulo deve ter seu nome comum (CN) formatado como CN=<deviceid>/<moduleid>. Por exemplo:

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

Criar uma identidade de módulo no portal

Numa identidade do dispositivo, pode criar até 20 identidades de módulo. Para adicionar uma identidade, siga estes passos:

No seu dispositivo existente no portal do Azure, escolha Adicionar Identidade de Módulo para criar sua primeira identidade de módulo.
Digite o nome myFirstModule. Salve a identidade do módulo.
A nova identidade do módulo aparece na parte inferior da tela. Selecione-o para ver os detalhes da identidade do módulo.
Salve a cadeia de conexão (chave primária). Use-o na próxima seção para configurar seu módulo no dispositivo em um aplicativo de console.

Atualizar o módulo duplo com o SDK de dispositivo .NET

Agora vamos comunicar com a nuvem a partir do seu dispositivo simulado. Quando uma identidade de módulo é criada, é criado implicitamente um módulo duplo no Hub IoT. Nesta secção, vai criar uma aplicação de consola .NET no seu dispositivo simulado que atualiza as propriedades reportadas do módulo duplo.

Criar um projeto do Visual Studio

Para criar um aplicativo que atualiza o módulo gêmeo, propriedades relatadas, siga estas etapas:

No Visual Studio, selecione Criar um novo projeto, escolha Aplicativo de Console (.NET Framework) e selecione Avançar.
Em Configurar seu novo projeto, insira UpdateModuleTwinReportedProperties como o nome do projeto. Selecione Seguinte para continuar.
Mantenha o .NET framework padrão e selecione Criar.

Instalar o SDK de dispositivo .NET mais recente do Hub IoT do Azure

A identidade do módulo e os recursos gêmeos do módulo só estão disponíveis nos SDKs de dispositivo de pré-lançamento do Hub IoT. Para instalá-lo, execute estas etapas:

No Visual Studio, abra Ferramentas>Gerenciador de Pacotes>NuGet Gerenciar Pacotes NuGet para Solução.
Selecione Procurar e, em seguida, selecione Incluir pré-lançamento. Procure Microsoft.Azure.Devices.Client. Selecione a versão mais recente e instale.

Agora, tem acesso a todas as funcionalidades de módulo.

Criar aplicativo de console UpdateModuleTwinReportedProperties

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.

Para criar seu aplicativo, siga estas etapas:

Adicione as seguinte declarações using na parte superior do ficheiro Program.cs:

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

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

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;

Adicione o seguinte método OnDesiredPropertyChanged à classe Program:

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);
    }

Finalmente, substitua o método Main pelo seguinte código:

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));

        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.ReadKey();
    Client.CloseAsync().Wait();
}

private static void ConnectionStatusChangeHandler(ConnectionStatus status, ConnectionStatusChangeReason reason)
{
    Console.WriteLine($"Status {status} changed: {reason}");
}

Você pode criar e executar este aplicativo usando F5.

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

Próximos passos

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

Partilhar via