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

Artigo
03/18/2023

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. Embora Hub IoT do Azure identidade do dispositivo e o dispositivo duplo ativem a aplicação de back-end para configurar um dispositivo e fornecer visibilidade sobre as condições do dispositivo, uma identidade do módulo e o módulo duplo fornecem estas capacidades para componentes individuais de um dispositivo. Em dispositivos compatíveis com vários componentes, tais como dispositivos de sistema operativo ou dispositivos de firmware, identidades de módulos e módulos duplos permitem uma configuração e condições isoladas para cada componente.

Nota

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

No final deste artigo, tem duas aplicações de consola .NET:

CreateIdentities: cria uma identidade de dispositivo, uma identidade de módulo e uma chave de segurança associada para ligar os clientes do dispositivo e do módulo.
UpdateModuleTwinReportedProperties: envia o módulo duplo atualizado, as propriedades comunicadas para o seu hub IoT.

Nota

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

Pré-requisitos

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

Autenticação de módulos

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

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

Obter a cadeia de ligação do hub IoT

Neste artigo, vai criar um serviço de back-end que adiciona um dispositivo no registo de identidade e, em seguida, adiciona um módulo a esse dispositivo. O seu serviço requer a permissão de escrita do registo . Por predefinição, cada hub IoT é criado com uma política de acesso partilhado denominada registryReadWrite que concede esta permissão.

Para obter a cadeia de ligação Hub IoT para a política registryReadWrite, siga estes passos:

Na portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos onde o hub está localizado e, em seguida, selecione o hub na lista de recursos.
No painel esquerdo do hub, selecione Políticas de acesso partilhado.
Na lista de políticas, selecione a política registryReadWrite .
Copie a cadeia de ligação Primária e guarde o valor.

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

Criar uma identidade de módulo

Nesta secção, vai criar uma aplicação de consola .NET que cria uma identidade de dispositivo e uma identidade de módulo no registo de identidades no seu hub. Um dispositivo ou módulo não consegue ligar ao hub, a menos que tenha uma entrada no registo de identidade. Para obter mais informações, veja a secção Identity Registry (Registo de Identidades) do Hub IoT developer guide (Guia do programador do Hub IoT).

Ao executar esta aplicação de consola, será gerado um ID e uma chave exclusivos para o dispositivo e o módulo. O seu dispositivo e módulo utilizam estes valores para se identificarem quando envia mensagens do dispositivo para a cloud para Hub IoT. Os IDs são sensíveis às maiúsculas e minúsculas.

Abra o Visual Studio e selecione Criar um novo projeto.
Em Criar um novo projeto, selecione Aplicação de Consola (.NET Framework).
Selecione Seguinte para abrir Configurar o novo projeto. Atribua o nome CreateIdentities ao projeto e, em seguida, selecione Seguinte.
Mantenha a opção de .NET Framework predefinida e selecione Criar para criar o seu projeto.
No Visual Studio, abra Ferramentas> Gestor > dePacotes NuGetGerir Pacotes NuGet para Solução. Selecione o separador Procurar.
Procure Microsoft.Azure.Devices. Selecione-o e, em seguida, selecione Instalar.

Adicione as seguintes using instruções na parte superior do ficheiro Program.cs :

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

Adicione os seguintes campos à classe Programa. Substitua o valor do marcador de posição pela cadeia de ligação do Hub IoT para o hub que criou na secção anterior.
```
const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";
```

Adicione o seguinte código à classe Main .

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);
}
```
O AddDeviceAsync método cria uma identidade de dispositivo com o ID myFirstDevice. Se esse ID do dispositivo já existir no registo de identidade, o código obtém simplesmente as informações do dispositivo existentes. De seguida, a aplicação irá apresentar a chave primária para essa identidade. Utilize esta chave na aplicação de dispositivo simulado para ligar ao seu hub.

O AddModuleAsync método cria uma identidade de módulo com o ID myFirstModule no dispositivo myFirstDevice. Se esse ID do módulo já existir no registo de identidade, o código obtém simplesmente as informações do módulo existente. De seguida, a aplicação irá apresentar a chave primária para essa identidade. Utilize esta chave na aplicação de módulo simulado para ligar ao hub.

Importante

O ID do dispositivo poderá estar visível no registos recolhidos para suporte técnico ao cliente e resolução de problemas, pelo que deve evitar incluir informações confidenciais quando lhe der um nome.
Execute esta aplicação e anote a chave do dispositivo e a chave do módulo.

Nota

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

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

Agora, vamos comunicar com a cloud 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.

Para obter a cadeia de ligação do módulo, navegue para o hub IoT e, em seguida, selecione Dispositivos. Localize e selecione myFirstDevice para o abrir e, em seguida, selecione myFirstModule para o abrir. Em Detalhes da Identidade do Módulo, copie a Cadeia de ligação (chave primária) e guarde-a na aplicação de consola.

No Visual Studio, adicione um novo projeto à sua solução ao selecionar Ficheiro>Novo>Projeto. Em Criar um novo projeto, selecione Aplicação de Consola (.NET Framework) e selecione Seguinte.
Em Configurar o novo projeto, atribua o nome UpdateModuleTwinReportedProperties ao projeto e, em seguida, selecione Seguinte.
Mantenha a opção de .NET Framework predefinida e selecione Criar para criar o seu projeto.
No Visual Studio, abra Ferramentas> Gestor > dePacotes NuGetGerir Pacotes NuGet para Solução. Selecione o separador Procurar.
Procure e selecione Microsoft.Azure.Devices.Client e, em seguida, selecione Instalar.

Adicione as seguintes using instruções na parte superior do ficheiro Program.cs :

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

Adicione os seguintes campos à classe Programa. Substitua o valor do marcador de posição pela cadeia de ligaçã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 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);
    }

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 já sabe como obter o módulo duplo e atualizar as propriedades comunicadas com o protocolo AMQP.

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

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 as aplicações

Agora pode executar as aplicações.

No Visual Studio, no Explorador de Soluções, clique com o botão direito do rato na sua solução e, em seguida, selecione Definir projetos startUp.
Em Propriedades Comuns, selecione Projeto de Arranque.
Selecione Vários projetos de arranque e, em seguida, selecione Iniciar como a ação para as aplicações e OK para aceitar as suas alterações.
Prima F5 para iniciar as aplicações.

Passos seguintes

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

Partilhar via

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

Pré-requisitos

Autenticação de módulos

Obter a cadeia de ligação do hub IoT

Criar uma identidade de módulo

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

Executar as aplicações

Passos seguintes

Comentários

Comentários

Recursos adicionais