Introdução a dispositivos gêmeos (.NET)

Artigo
03/18/2023

Dispositivos gêmeos são documentos JSON que armazenam informações do estado do dispositivo, incluindo metadados, configurações e condições. O Hub IoT persiste um dispositivo gêmeo para cada dispositivo que você conecta a ele.

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.

Use os dispositivos gêmeos para:

Armazene os metadados de dispositivo de seu back-end da solução.
Relate informações de estado atual, como funcionalidades disponíveis e condições (por exemplo, o método conectividade usado) do aplicativo do dispositivo.
Sincronize o estado dos fluxos de trabalho de longa duração (como atualizações de firmware e de configuração) entre um aplicativo de dispositivo e um aplicativo de back-end.
Consultar os metadados, a configuração ou o estado do seu dispositivo.

Dispositivos gêmeos são projetados para sincronização e para consultar condições e configurações de dispositivos. Para obter mais informações sobre dispositivos gêmeos e quando usá-los, confira Noções básicas sobre dispositivos gêmeos.

Os hubs IoT armazenam dispositivos gêmeos, que contêm os seguintes elementos:

Marcas. Metadados do dispositivo acessíveis apenas por meio do back-end da solução.
Propriedades desejadas. Objetos JSON modificáveis pelo back-end da solução e observáveis pelo aplicativo de dispositivo.
Propriedades reportadas. Objetos JSON modificáveis pelo aplicativo de dispositivo e legíveis pelo back-end da solução.

Marcas e propriedades não podem conter matrizes, mas podem conter objetos aninhados.

A ilustração a seguir mostra a organização de um dispositivo gêmeo:

Captura de tela de um diagrama de conceito de dispositivo gêmeo.

Além disso, o back-end da solução pode consultar dispositivos gêmeos com base em todos os dados acima. Para obter mais informações sobre dispositivos gêmeos, consulte Noções básicas de dispositivos gêmeos. Para obter mais informações sobre a consulta, consulte Linguagem de consulta do Hub IoT.

Este artigo mostra como:

Use um aplicativo de dispositivo simulado para relatar seu canal de conectividade como uma propriedade relatada no dispositivo gêmeo.
Consulte dispositivos por meio do aplicativo de back-end usando filtros nas marcações e propriedades criadas anteriormente.

Neste artigo, você cria dois aplicativos de console do .NET:

AddTagsAndQuery: um aplicativo de back-end que adiciona marcas e consultas aos dispositivos gêmeos.
ReportConnectivity: um aplicativo de dispositivo simulado que se conecta ao hub IoT e relata sua condição de conectividade.

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.
Um dispositivo registrado. Registre um no portal do Azure.
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, que 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).

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço de back-end que adiciona as propriedades desejadas a um dispositivo gêmeo e, em seguida, consulta o registro de identidade para localizar todos os dispositivos com as propriedades relatadas que foram atualizadas de acordo. O seu serviço precisa da permissão conexão de serviço para modificar as propriedades desejadas de um dispositivo gêmeo e precisa da permissão leitura do registro para consultar o registro de identidade. Não há nenhuma política de acesso compartilhado padrão que contenha apenas essas duas permissões, portanto, você precisa criar uma.

Para criar uma política de acesso compartilhado que conceda as permissões conexão de serviço e leitura de registro e obter uma cadeia de conexão para essa política, 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.
No menu superior acima da lista de políticas, selecione Adicionar política de acesso compartilhado.
No painel Adicionar política de acesso compartilhado à direita, insira um nome descritivo para a política, como serviceAndRegistryRead. Em Permissões, selecione Leitura de Registro e Conexão de Serviço e selecione Adicionar.
Selecione a sua nova política na lista de políticas.
Selecione o ícone de cópia da 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 um aplicativo de dispositivo que atualiza as propriedades relatadas

Nesta seção, você cria um aplicativo de console do .NET que se conecta ao seu hub como myDeviceId e depois atualiza suas propriedades reportadas para confirmar que ele está conectado usando uma rede celular.

Abra o Visual Studio e selecione Criar novo projeto.
Selecione Aplicativo de Console (.NET Framework) e Avançar.
Em Configurar seu novo projeto, nomeie o projeto como ReportConnectivity e selecione Avançar.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto ReportConnectivity e selecione Gerenciar Pacotes NuGet.
Mantenha o padrão do .NET Framework e selecione Criar para criar o projeto.
Selecione Procurar para pesquisar e escolha Microsoft.Azure.Devices.Client. Selecione Instalar.

Esta etapa baixa, instala e adiciona uma referência ao pacote NuGet do SDK do dispositivo IoT do Azure e as dependências dele.

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

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

Adicione os seguintes campos à classe Program . Substitua {device connection string} pela cadeia de conexão de dispositivo que você viu quando registrou um dispositivo no Hub IoT:

static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

Adicione o seguinte método à classe Programa :

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

O objeto Client expõe todos os métodos necessários para você interagir com dispositivos gêmeos a partir do dispositivo. O código mostrado acima inicializa o objeto Cliente e recupera o dispositivo gêmeo para myDeviceId.

Adicione o seguinte método à classe Programa :

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

O código acima atualiza a propriedade relatada de myDeviceId com as informações de conectividade.

Por fim, adicione as seguintes linhas ao método Principal :

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

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>Projeto de Inicialização, selecione Vários projetos de inicialização. Para ReportConnectivity, selecione Iniciar como a Ação. Selecione OK para salvar suas alterações.
Execute esse aplicativo clicando com o botão direito do mouse no projeto ReportConnectivity, selecione Depurar e, em seguida, Iniciar nova instância. Você verá o aplicativo obter as informações do gêmeo e enviar a conectividade como uma propriedade relatada.

Depois que o dispositivo relatou as informações de conectividade, ele deve aparecer em ambas as consultas.
Clique com o botão direito do mouse no projeto AddTagsAndQuery e selecione Depurar>Iniciar nova instância para executar as consultas novamente. Desta vez, myDeviceId deve aparecer em ambos os resultados da consulta.

Criar um aplicativo de serviço que atualiza as propriedades desejadas e consulta gêmeos

Nesta seção, você cria um aplicativo de console do .NET usando o C#, que adiciona metadados de local ao dispositivo gêmeo associado com myDeviceId. O aplicativo consulta o hub IoT para dispositivos localizados nos EUA e, em seguida, consulta dispositivos que reportam a uma conexão de rede de celular.

No Visual Studio, selecione Arquivo > Novo > Projeto. Em Criar um projeto, selecione Aplicativo de Console (.NET Framework) e, em seguida, selecione Próximo.
Em Configurar seu novo projeto, nomeie o projeto como AddTagsAndQuery e depois selecione Avançar.
Aceite a versão padrão do .NET Framework e selecione Criar, para criar o projeto.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto AddTagsAndQuery e, em seguida, selecione Gerenciar Pacotes NuGet.
Selecione Procurar para pesquisar e selecionar Microsoft.Azure.Devices. Selecione Instalar.

Esta etapa baixa, instala e adiciona uma referência ao pacote NuGet do SDK do serviço IoT do Azure e suas dependências.
Adicione as instruções using abaixo na parte superior do arquivo Program.cs :
```
using Microsoft.Azure.Devices;
```
Adicione os seguintes campos à classe Program . Substitua {iot hub connection string} pela cadeia de conexão do Hub IoT que você copiou em Obter a cadeia de conexão do hub IoT.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```
Adicione o seguinte método à classe Programa :
```
public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

    var query = registryManager.CreateQuery(
      "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
    var twinsInRedmond43 = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43: {0}", 
      string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

    query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
    var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
      string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}
```
A classe RegistryManager expõe todos os métodos necessários para interagir com gêmeos de dispositivo do serviço. O código anterior inicializa primeiro o objeto registryManager, depois recupera o dispositivo gêmeo para myDeviceId e, finalmente, atualiza as marcações com as informações do local desejado.

Após a atualização, ele executa duas consultas: a primeira seleciona somente os dispositivos gêmeos de dispositivos localizados na fábrica de Redmond43, enquanto o segundo aperfeiçoa a consulta para selecionar somente os dispositivos que também estão conectados por meio de rede celular.

O código anterior, quando ele cria o objeto query, especifica um número máximo de documentos retornados. O objeto query contém uma propriedade booliana HasMoreResults que você pode usar para invocar os métodos GetNextAsTwinAsync várias vezes para recuperar todos os resultados. Um método chamado GetNextAsJson está disponível para os resultados que não são de dispositivos gêmeos, por exemplo, resultados de consultas de agregação.

Por fim, adicione as seguintes linhas ao método Principal :

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Execute esse aplicativo clicando com o botão direito do mouse no projeto AddTagsAndQuery e selecionando Depurar, seguido de Iniciar nova instância. Você deve ver um dispositivo nos resultados da consulta que pergunta sobre todos os dispositivos localizados em Redmond43, e nenhum para a consulta que restringe os resultados para dispositivos que usam uma rede de celular.

Neste artigo você:

Adicionou metadados do dispositivo como marcas de um aplicativo de back-end
Relatou informações de conectividade do dispositivo no dispositivo gêmeo
Consultou as informações do dispositivo gêmeo usando a linguagem de consulta do Hub IoT semelhante a SQL

Próximas etapas

Para saber como:

Enviar telemetria de dispositivos, consulte Início Rápido: enviar telemetria de um dispositivo IoT Plug and Play para o Hub IoT do Azure.
Configurar dispositivos usando as propriedades desejadas do dispositivo gêmeo, consulte Tutorial: Configurar seus dispositivos de um serviço de back-end.
Controlar dispositivos interativamente, como ativar um ventilador de um aplicativo controlado pelo usuário, consulte Início Rápido: controlar um dispositivo conectado a um hub IoT.