Introdução a dispositivos gêmeos

Use o SDK do dispositivo e o SDK do serviço do Hub IoT do Azure para desenvolver aplicativos que lidam com as tarefas comuns do dispositivo gêmeo. 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.

Você pode usar dispositivos gêmeos para:

• Armazenar os metadados do dispositivo de back-end da sua solução
• Relatar informações de estado atual, como recursos e condições disponíveis, por exemplo, o método de conectividade usado, do seu aplicativo de dispositivo
• Sincronizar o estado de fluxos de trabalho de execução longa, como atualizações de firmware e configuração, entre um aplicativo de dispositivo e um aplicativo de back-end
• Consultar os metadados, a configuração ou o estado do dispositivo

Para obter mais informações sobre os dispositivos gêmeos, incluindo quando usá-los, confira Entender e usar dispositivos gêmeos no Hub IoT.

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.

Esse artigo mostra como desenvolver dois tipos de aplicativos:

• Os aplicativos de dispositivo podem lidar com solicitações para atualizar as propriedades desejadas e responder com alterações nas propriedades relatadas.
• Os aplicativos de serviço podem atualizar as tags do dispositivo gêmeo, definir as novas propriedades desejadas e consultar os dispositivos com base nos valores do dispositivo gêmeo.

Observação

Esse artigo tem como objetivo complementar os exemplos de SDKs da Internet das Coisas do Azure referenciados nesse artigo. Você pode usar as ferramentas do SDK para criar aplicativos de dispositivo e de back-end.

Pré-requisitos

• Um hub IoT. Algumas chamadas do SDK exigem a cadeia de conexão primária do Hub IoT; portanto, anote a cadeia de conexão.

• Um dispositivo registrado. Algumas chamadas do SDK exigem a cadeia de conexão primária do dispositivo; portanto, anote a cadeia de conexão.

• Se o seu aplicativo usar o protocolo MQTT, certifique-se de que a porta 8883 está aberta no firewall. O protocolo MQTT 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).

• Requisitos do SDK de linguagem:

  • SDK do .NET – Requer o Visual Studio.
  • O SDK do Python - Python versão 3.7 ou posterior é recomendado. Certifique-se de usar a instalação de 32 bits ou 64 bits conforme exigido pelo seu programa de instalação. Quando solicitado durante a instalação, certifique-se de adicionar Python à variável de ambiente específica da plataforma.
  • Java – Requer o Java SE Development Kit 8. Certifique-se de selecionar Java 8 em Suporte de longo prazo para navegar até os downloads do JDK 8.
  • Node.js – Requer Node.js versão 10.0.x ou posterior.

Visão geral

Esse artigo descreve como usar o SDK da Internet das Coisas do Azure para .NET para criar código de aplicativo de serviço de back-end e dispositivo para dispositivos gêmeos.

Criar um aplicativo de dispositivo

Os aplicativos de dispositivo podem ler e gravar as propriedades relatadas pelos gêmeos e ser notificados sobre as alterações desejadas das propriedades do gêmeo definidas por um aplicativo de back-end ou pelo Hub IoT.

Esta seção descreve como usar o código do aplicativo de dispositivo para:

• Recuperar um dispositivo gêmeo e examinar as propriedades relatadas
• Atualizar as propriedades relatadas do dispositivo gêmeo
• Criar um manipulador de retorno de chamada de atualização de propriedade desejada

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 teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

Adicionar o pacote NuGet do dispositivo

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

Conecte a um dispositivo

A classe DeviceClient expõe todos os métodos necessários para interagir com os dispositivos gêmeos do dispositivo.

Conecte-se ao dispositivo usando o método CreateFromConnectionString junto com a cadeia de conexão do dispositivo e o protocolo de transporte da conexão.

O parâmetro de protocolo de transporte CreateFromConnectionString TransportType dá suporte aos seguintes protocolos de transporte:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only

Não há suporte para o protocolo Http1 para as atualizações do dispositivo gêmeo.

Esse exemplo se conecta a um dispositivo usando o protocolo de transporte Mqtt.

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

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Recuperar um dispositivo gêmeo e examinar as propriedades

Chame GetTwinAsync para recuperar as propriedades atuais do dispositivo gêmeo. Há muitas propriedades de objeto Twin que você pode usar para acessar áreas específicas dos dados JSON Twin, incluindo Properties, Status, Tags e Version.

Esse exemplo recupera as propriedades do dispositivo gêmeo e imprime os valores do gêmeo no formato JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Atualizar as propriedades relatadas do dispositivo gêmeo

Para atualizar uma propriedade relatada do gêmeo:

1. Crie um objeto TwinCollection para a atualização da propriedade relatada
2. Atualize uma ou mais propriedades relatadas dentro do objeto TwinCollection
3. Use UpdateReportedPropertiesAsync para efetuar push das alterações da propriedade relatada para o serviço do hub IoT

Por exemplo:

try
{
Console.WriteLine("Sending sample start time as reported property");
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
await _deviceClient.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 desejada

Crie um manipulador de retorno de chamada de atualização de propriedade desejado que é executado quando uma propriedade desejada é alterada no dispositivo gêmeo passando o nome do método do manipulador de retorno de chamada para SetDesiredPropertyUpdateCallbackAsync.

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

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

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

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

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 _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Exemplo de dispositivo SDK

O SDK da Internet das Coisas do Azure para .NET fornece um exemplo funcional de um aplicativo de dispositivo que lida com as tarefas do dispositivo gêmeo. Para obter mais informações, confira TwinSample.

Criar um aplicativo de back-end

Um aplicativo de back-end se conecta a um dispositivo por meio do Hub IoT e pode ler as propriedades relatadas e desejadas do dispositivo, gravar as propriedades desejadas do dispositivo e executar as consultas do dispositivo.

Esta seção descreve como criar o código de aplicativo de back-end para:

• Ler e atualizar os campos do dispositivo gêmeo
• Criar uma consulta de dispositivo gêmeo

A classe RegistryManager expõe todos os métodos necessários para criar um aplicativo de back-end para interagir com os dispositivos gêmeos do serviço.

Adicionar um pacote NuGet do serviço

Os aplicativos de serviço de back-end exigem o pacote NuGet Microsoft.Azure.Devices.

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 compartilhado
• 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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Conectar-se usando a política de acesso compartilhado

Conecte um aplicativo de back-end a um dispositivo usando CreateFromConnectionString. O seu aplicativo 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á uma política de acesso compartilhado padrão que contenha apenas essas duas permissões, então você precisa criar uma caso ainda não exista. Forneça essa cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as assinaturas de acesso compartilhado.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{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 ser autenticado com sucesso e obter 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, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

Configurar o aplicativo Microsoft Entra

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

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos do 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 a módulos gêmeos. Para obter mais informações, confira 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 do Microsoft Entra, confira 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 TokenCredential específico ou ChainedTokenCredential reduzido. Para simplificar, esta seção descreve a autenticação usando DefaultAzureCredential e um segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira as Diretrizes de uso para 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 credencial em uma ordem até encontrar uma credencial em funcionamento.

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

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

Neste exemplo, o segredo do cliente de registro do aplicativo do 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 pelo 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 então ser passado para um método de conexão com o Hub IoT para um cliente do SDK que aceite as credenciais do Microsoft Entra:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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, TokenCredential é passado para RegistryManager.Create para 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 da autenticação de serviço do Microsoft Entra, confira o Exemplo de autenticação baseada em função.

Ler e atualizar os campos do dispositivo gêmeo

Você pode recuperar os campos do dispositivo gêmeo atual em um objeto Twin chamando GetTwinAsync.

A classe Twin inclui propriedades que correspondem a cada seção de um dispositivo gêmeo. Use as propriedades da classe Twin para exibir e atualizar os campos do dispositivo gêmeo. Você pode usar as propriedades do objeto Twin para atualizar vários campos gêmeos antes de gravar as atualizações no dispositivo usando UpdateTwinAsync.

Depois de fazer atualizações do campo gêmeo, chame UpdateTwinAsync para gravar as atualizações do campo do objeto Twin novamente em um dispositivo. Use a lógica try e catch acoplada a um manipulador de erros para capturar erros de patch formatados incorretamente de UpdateTwinAsync.

Ler e atualizar os tags do dispositivo gêmeo

Use a propriedade Tags do dispositivo gêmeo para ler e gravar informações da tag do dispositivo.

Atualizar tags usando um objeto gêmeo

Esse exemplo cria um patch da tag location, atribua-o ao objeto Twin usando a propriedade Tags e aplique o patch usando UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Atualizar tags usando uma cadeia de caracteres JSON

Você pode criar e aplicar um patch de atualização de informações do dispositivo gêmeo no formato JSON. O Hub IoT analisa e aplica o patch se ele estiver formatado corretamente.

Esse exemplo chama GetTwinAsync para recuperar os campos do dispositivo gêmeo atual em um objeto Twin, cria um patch tag no formato JSON com as informações da localização da região e planta e, em seguida, chama UpdateTwinAsync para aplicar o patch para atualizar o dispositivo gêmeo. Uma mensagem de erro será exibida se UpdateTwinAsync falhar.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Exibir e atualizar as propriedades desejadas do gêmeo

Use a propriedade TwinProperties.Desired do dispositivo gêmeo para ler e gravar informações da propriedade desejada do dispositivo. Atualize as propriedades Desired do gêmeo usando um patch no formato JSON.

Esse exemplo chama GetTwinAsync para recuperar os campos do dispositivo gêmeo atual em um objeto Twin, atualiza a propriedade desejada speed do gêmeo e, em seguida, chama UpdateTwinAsync para aplicar o objeto Twin para atualizar o dispositivo gêmeo.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Outros métodos de atualização de gêmeos

Você também pode aplicar as atualizações de gêmeos usando estes métodos do SDK:

• Chame ReplaceTwinAsync para substituir todo o dispositivo gêmeo.
• Chame UpdateTwins2Async para atualizar uma lista de gêmeos criados anteriormente no sistema.

Criar uma consulta de dispositivo gêmeo

Esta seção demonstra duas consultas de dispositivo gêmeo. As consultas de dispositivo gêmeo são consultas semelhantes a SQL que retornam um conjunto de resultados de dispositivos gêmeos.

Para criar uma consulta de dispositivo gêmeo, chame CreateQuery para enviar uma consulta SQL de gêmeos e obter uma Interface IQuery. Opcionalmente, você pode chamar CreateQuery com um segundo parâmetro para especificar um número máximo de itens por página.

Em seguida, chame GetNextAsTwinAsync ou o método GetNextAsJsonAsync quantas vezes forem necessárias para recuperar todos os resultados do gêmeo.

• GetNextAsTwinAsync para recuperar o resultado da próxima página como os objetos Twin.
• GetNextAsJsonAsync para recuperar o resultado da próxima página como as cadeias de caracteres JSON.

A interface IQuery inclui uma propriedade booliana HasMoreResults que você pode usar para verificar se há mais resultados do gêmeo a serem buscados.

Essa consulta de exemplo seleciona apenas os dispositivos gêmeos de dispositivos localizados na planta Redmond43.

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

Essa consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados por meio de uma rede celular.

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

Exemplo de serviço do SDK

O SDK da Internet das Coisas do Azure para .NET fornece um exemplo funcional de um aplicativo de serviço que lida com as tarefas do dispositivo gêmeo. Para obter mais informações, confira Exemplo do Gerenciador de Registro.

Visão geral

Esse artigo descreve como usar o SDK da Internet das Coisas do Azure para Java para criar código de aplicativo de serviço de backend e dispositivo para dispositivos gêmeos.

Criar um aplicativo de dispositivo

Os aplicativos de dispositivo podem ler e gravar as propriedades relatadas pelos gêmeos e ser notificados sobre as alterações desejadas das propriedades do gêmeo definidas por um aplicativo de back-end ou pelo Hub IoT.

Esta seção descreve como criar o código do aplicativo de dispositivo para:

• Recuperar e exibir um dispositivo gêmeo
• Atualizar as propriedades relatadas do dispositivo gêmeo
• Inscreva-se para receber as alterações de propriedades desejadas

A classe DeviceClient expõe todos os métodos que você precisa para interagir com os dispositivos gêmeos do dispositivo.

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 teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

Instruções de importação do dispositivo

Use as seguintes instruções de importação de dispositivo para acessar o SDK da Internet das Coisas do Azure para Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

Conectar-se ao dispositivo

Para se conectar a um dispositivo:

1. Use IotHubClientProtocol para escolher um protocolo de transporte. Por exemplo:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. Use o construtor DeviceClient para adicionar o protocolo e a cadeia de conexão primária do dispositivo.

   String connString = "{IoT hub device connection string}";
   DeviceClient client = new DeviceClient(connString, protocol);
   

3. Use open para conectar o dispositivo ao hub IoT. Se o cliente já estiver aberto, o método não fará nada.

   client.open(true);
   

Recuperar e exibir um dispositivo gêmeo

Depois de abrir a conexão do cliente, chame getTwin para recuperar as propriedades do gêmeo atual em um objeto Twin.

Por exemplo:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Atualizar as propriedades relatadas do dispositivo gêmeo

Depois de recuperar o gêmeo atual, você poderá começar a fazer atualizações de propriedades relatadas. Você também poderá fazer atualizações de propriedade relatadas sem obter o gêmeo atual, desde que tenha a versão correta das propriedades relatadas. Se você enviar propriedades relatadas e receber um erro de "falha na pré-condição", a versão das propriedades relatadas estará desatualizada. Nesse caso, obtenha a versão mais recente chamando getTwin novamente.

Para atualizar as propriedades relatadas:

1. Chame getReportedProperties para buscar as propriedades relatadas do gêmeo em um objeto TwinCollection.

2. Use put para atualizar uma propriedade relatada dentro do objeto TwinCollection. Chame put para cada atualização de propriedade relatada.

3. Use updateReportedProperties para aplicar o grupo de propriedades relatadas que foram atualizadas usando o método put.

Por exemplo:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Inscreva-se para receber as alterações de propriedades desejadas

Chame subscribeToDesiredProperties para assinar as alterações de propriedades desejadas. Esse cliente recebe um retorno de chamada com um objeto Twin sempre que uma propriedade desejada é atualizada. Esse retorno de chamada contém o conjunto completo de propriedades desejadas ou apenas a propriedade desejada atualizada, dependendo de como a propriedade desejada foi alterada.

Esse exemplo assina as alterações de propriedades desejadas. Todas as alterações de propriedades desejadas são passadas para um manipulador chamado DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

Nesse exemplo, o manipulador de retorno de chamada de alteração de propriedade desejada DesiredPropertiesUpdatedHandler chama getDesiredProperties para recuperar as alterações de propriedade e imprime as propriedades de gêmeo atualizadas.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Exemplo de dispositivo SDK

O SDK da Internet das Coisas do Azure para Java inclui um exemplo de trabalho para testar os conceitos do aplicativo de dispositivo descritos nesse artigo. Para obter mais informações, confira Exemplo de dispositivo gêmeo.

Criar um aplicativo de back-end

Esta seção descreve como criar um aplicativo de back-end que:

• Atualiza as tags do dispositivo gêmeo
• Consulta dispositivos usando filtros nas tags e propriedades

A classe ServiceClient DeviceTwin contém métodos que os serviços podem usar para acessar dispositivos gêmeos.

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

Use as seguintes instruções de importação de serviço para acessar o SDK da Internet das Coisas do Azure para Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Conecte-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 compartilhado
• 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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Conectar-se usando a política de acesso compartilhado

Use um construtor DeviceTwin para criar a conexão com o hub IoT. O objeto DeviceTwin lida com a comunicação com seu hub IoT.

O seu aplicativo 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á uma política de acesso compartilhado padrão que contenha apenas essas duas permissões, então você precisa criar uma caso ainda não exista. Forneça essa cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as assinaturas de acesso compartilhado.

O objeto DeviceTwinDevice representa o dispositivo gêmeo com suas propriedades e tags.

Por exemplo:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Conectar-se usando o Microsoft Entra

Um aplicativo de back-end que usa o Microsoft Entra deve ser autenticado com sucesso e obter 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, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

Para obter uma visão geral da autenticação do SDK do Java, confira a autenticação do Azure com o Java e a Identidade do Azure.

Para simplificar, esta seção se concentra em descrever a autenticação usando o segredo do cliente.

Configurar o aplicativo Microsoft Entra

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

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos do 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 a módulos gêmeos. Para obter mais informações, confira 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 do Microsoft Entra, confira 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 TokenCredential específico ou ChainedTokenCredential reduzido. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira Cadeias de credenciais na biblioteca de clientes da Identidade do Azure para Java.

O 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 credencial em uma ordem até encontrar uma credencial em funcionamento.

Você pode autenticar as credenciais do aplicativo do Microsoft Entra usando DefaultAzureCredentialBuilder. Salve os parâmetros de conexão, como o tenantID do segredo do cliente, clientID e valores do segredo do cliente como variáveis ambientais. Depois que o TokenCredential for criado, passe-o para ServiceClient ou outro construtor como o parâmetro '''credential''.

Neste exemplo, DefaultAzureCredentialBuilder tenta autenticar uma conexão da lista descrita em DefaultAzureCredential. O resultado de uma autenticação bem-sucedida do Microsoft Entra é uma credencial de token de segurança que é passada para um construtor, como ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Autenticar usando o ClientSecretCredentialBuilder

Você pode usar ClientSecretCredentialBuilder para criar uma credencial usando informações do segredo do cliente. Se bem-sucedido, esse método retorna um TokenCredential que pode ser passado para ServiceClient ou outro construtor como o parâmetro ''credential''.

Neste exemplo, o segredo do cliente de registro do aplicativo do Microsoft Entra, a ID do cliente e os valores da ID do locatário foram adicionados a variáveis de ambiente. Essas variáveis de ambiente são usadas pelo ClientSecretCredentialBuilder para criar a credencial.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Outras classes de autenticação

O SDK do Java também inclui estas classes que autenticam um aplicativo de back-end com o Microsoft Entra:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

Exemplos de código

Para obter exemplos práticos da autenticação de serviço do Microsoft Entra, confira o Exemplo de autenticação baseada em função.

Atualizar os campos do dispositivo gêmeo

Para atualizar os campos do dispositivo gêmeo:

1. Use getTwin para recuperar os campos do dispositivo gêmeo atual

   Esse exemplo recupera e imprime os campos do dispositivo gêmeo:

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. Use um objeto HashSet para add um grupo de pares de tags do gêmeo

3. Use setTags para adicionar um grupo de pares de tags de um objeto tags a um objeto DeviceTwinDevice

4. Use updateTwin para atualizar o gêmeo no hub IoT

   Esse exemplo atualiza as tags do dispositivo gêmeo de planta e região para um dispositivo gêmeo:

   // Update device twin tags if they are different
   // from the existing values
   String currentTags = device.tagsToString();
   if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
   
   // Create the tags and attach them to the DeviceTwinDevice object
   Set<Pair> tags = new HashSet<Pair>();
   tags.add(new Pair("region", region));
   tags.add(new Pair("plant", plant));
   device.setTags(tags);
   
   // Update the device twin in IoT Hub
   System.out.println("Updating device twin");
   twinClient.updateTwin(device);
   }
   
   // Retrieve and display the device twin with the tag values from IoT Hub
   System.out.println("Device twin after update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

Criar uma consulta de dispositivo gêmeo

Esta seção demonstra duas consultas de dispositivo gêmeo. As consultas de dispositivo gêmeo são consultas semelhantes a SQL que retornam um conjunto de resultados de dispositivos gêmeos.

A classe Query contém métodos que podem ser usados para criar consultas no estilo SQL no Hub IoT para gêmeos, trabalhos, trabalhos de dispositivo ou dados brutos.

Para criar uma consulta de dispositivo:

1. Use createSqlQuery para criar a consulta SQL dos gêmeos

2. Use queryTwin para executar a consulta

3. Use hasNextDeviceTwin para verificar se há outro dispositivo gêmeo no conjunto de resultados

4. Use getNextDeviceTwin para recuperar o próximo dispositivo gêmeo do conjunto de resultados

As consultas de exemplo a seguir retornam no máximo 100 dispositivos.

Essa consulta de exemplo seleciona apenas os dispositivos gêmeos de dispositivos localizados na planta Redmond43.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Essa consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados por meio de uma rede celular.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Exemplo de serviço do SDK

O SDK da Internet das Coisas do Azure para Java fornece um exemplo funcional de um aplicativo de serviço que lida com as tarefas do dispositivo gêmeo. Para obter mais informações, confira Exemplo de dispositivo gêmeo.

Visão geral

Esse artigo descreve como usar o SDK da Internet das Coisas do Azure para Python para criar código de aplicativo de serviço de backend e dispositivo para dispositivos gêmeos.

Criar um aplicativo de dispositivo

Os aplicativos de dispositivo podem ler e gravar as propriedades relatadas pelos gêmeos e ser notificados sobre as alterações desejadas das propriedades do gêmeo definidas por um aplicativo de back-end ou pelo Hub IoT.

A classe IoTHubDeviceClient contém métodos que podem ser usados para trabalhar com os dispositivos gêmeos.

Esta seção descreve como criar o código do aplicativo de dispositivo que:

• Recupera um dispositivo gêmeo e examina as propriedades relatadas
• Aplicar patch de propriedades relatadas do dispositivo gêmeo

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 teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

Conecte a um dispositivo

Essa seção mostra como conectar um aplicativo a um dispositivo usando uma chave primária do dispositivo que inclui uma chave de acesso compartilhada.

Para conectar um aplicativo a um dispositivo:

1. Chame create_from_connection_string para adicionar a cadeia de conexão do dispositivo
2. Chame connect 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 = "{IOT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

Recuperar um dispositivo gêmeo e examinar as propriedades relatadas

Você pode recuperar e examinar as informações do dispositivo gêmeo, incluindo as tags e propriedades. As informações do dispositivo gêmeo recuperadas correspondem aos dados no formato JSON do dispositivo gêmeo que você pode exibir para um dispositivo no portal do Azure.

Chame get_twin para obter o dispositivo gêmeo do serviço do Hub IoT do Azure. As informações do gêmeo são colocadas em uma variável que pode ser impressa ou examinada.

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

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

Aplicar patch de propriedades relatadas do dispositivo gêmeo

Você pode aplicar um patch para atualizar as propriedades relatadas pelo dispositivo no formato JSON.

Para aplicar um patch para atualizar as propriedades relatadas:

1. Atribua um patch JSON da propriedade relatada a uma variável.
2. Chame patch_twin_reported_properties para aplicar o patch JSON às propriedades relatadas. Essa é uma chamada síncrona, o que significa que essa função não retorna até que o patch seja enviado para o serviço e seja reconhecido.

Se patch_twin_reported_properties retornar um erro, essa função gerará o erro correspondente.

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

Você também pode chamar esses métodos para atualizar dispositivos gêmeos:

• Chame replace_twin para substituir as propriedades desejadas e as tags do dispositivo gêmeo.
• Chame update_twin para atualizar as propriedades desejadas e as tags do dispositivo gêmeo.

Manipulador de patch de propriedades desejadas de entrada

Chame on_twin_desired_properties_patch_received para criar uma função de manipulador ou corrotina que é chamada quando um patch de propriedades desejadas do gêmeo é recebido. O manipulador usa um argumento, que é o patch gêmeo na forma de um objeto de dicionário JSON.

Esse 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 propriedades desejadas em JSON.

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

Exemplos de dispositivo do SDK

O SDK da Internet das Coisas do Azure para Python inclui os seguintes exemplos:

• get_twin – Conectar-se a um dispositivo e recuperar as informações do gêmeo.
• update_twin_reported_properties – Atualizar as propriedades relatadas do gêmeo.
• receive_twin_desired_properties – Receber e atualizar as propriedades desejadas.

Criar um aplicativo de back-end

Um aplicativo de back-end se conecta a um dispositivo por meio do Hub IoT e pode ler as propriedades relatadas e desejadas do dispositivo, gravar as propriedades desejadas do dispositivo e executar as consultas do dispositivo.

Esta seção descreve como criar um aplicativo de back-end para:

• Atualizar as propriedades desejadas e as tags do gêmeo
• Consulta dispositivos usando filtros nas tags e propriedades

A classe IoTHubRegistryManager expõe todos os métodos necessários para criar um aplicativo de back-end para interagir com os dispositivos gêmeos do serviço.

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 compartilhado
• 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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Conectar-se usando a política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string. O seu aplicativo 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á uma política de acesso compartilhado padrão que contenha apenas essas duas permissões, então você precisa criar uma caso ainda não exista. Forneça essa cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as assinaturas de acesso compartilhado.

Por exemplo:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Conectar-se usando o Microsoft Entra

Um aplicativo de back-end que usa o Microsoft Entra deve ser autenticado com sucesso e obter 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, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

Para obter uma visão geral da autenticação do SDK do Python, confira Autenticar aplicativos Python nos serviços do Azure usando o SDK do Azure para Python

Configurar o aplicativo Microsoft Entra

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

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos do 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 a módulos gêmeos. Para obter mais informações, confira 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 do Microsoft Entra, confira 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 TokenCredential específico ou ChainedTokenCredential reduzido. Para simplificar, esta seção descreve a autenticação usando DefaultAzureCredential e um segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira Cadeias de credenciais na biblioteca de clientes da Identidade do Azure para Python.

O 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 credencial em uma ordem até encontrar uma credencial em funcionamento.

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

pip install azure-identity

from azure.identity import DefaultAzureCredential

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

• IoTHubRegistryManager para criar uma conexão de serviço com o Hub IoT usando uma credencial de token do Entra.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential requer dois parâmetros:

• O URL do serviço do Azure – O URL do serviço do Azure deve estar no formato {Your Entra domain URL}.azure-devices.net sem um prefixo https://. Por exemplo, MyAzureDomain.azure-devices.net.
• O token de credencial do Azure

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

Exemplos de código

Para obter exemplos de trabalho da autenticação de serviço do Microsoft Entra, confira a MSAL (Biblioteca de Autenticação da Microsoft) para Python.

Atualizar as propriedades desejadas e as tags do gêmeo

Você pode atualizar as propriedades desejadas e as tags do gêmeo de um aplicativo de back-end ao mesmo tempo usando update_twin.

1. Chame get_twin para obter a versão atual do dispositivo gêmeo
2. Use a classe Twin para adicionar tags e propriedades no formato JSON.
3. Chame update_twin para aplicar o patch ao dispositivo gêmeo. Você também pode usar replace_twin para substituir as propriedades desejadas e as tags para um dispositivo gêmeo.

Esse exemplo atualiza as informações da tag region e plant e define uma propriedade desejada power_level como 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Criar uma consulta de dispositivo gêmeo

Você pode consultar as informações do dispositivo gêmeo usando as consultas do dispositivo gêmeo. As consultas de dispositivo gêmeo são consultas semelhantes a SQL que retornam um conjunto de resultados de dispositivos gêmeos.

Para usar uma consulta do dispositivo gêmeo:

1. Use um objeto QuerySpecification para definir uma solicitação de consulta semelhante a SQL.

2. Use query_iot_hub para consultar um Hub IoT e recuperar as informações do dispositivo gêmeo usando a especificação da consulta semelhante ao SQL.

Esse exemplo executa duas consultas. A primeira seleciona somente os dispositivos gêmeos de dispositivos localizados na planta Redmond43, enquanto a segunda refina a consulta para selecionar somente os dispositivos que também estão conectados por meio de uma rede de celular. Os resultados são impressos após cada consulta.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

Exemplo de serviço do SDK

O SDK da Internet das Coisas do Azure para Python fornece um exemplo funcional de um aplicativo de serviço que lida com as tarefas do dispositivo gêmeo. Para obter mais informações, confira Exemplo de Consulta do Gerenciador de Registro.

Visão geral

Esse artigo descreve como usar o SDK da Internet das Coisas do Azure para Node.js para criar código de aplicativo de serviço de backend e dispositivo para dispositivos gêmeos.

Criar um aplicativo de dispositivo

Os aplicativos de dispositivo podem ler e gravar as propriedades relatadas pelos gêmeos e ser notificados sobre as alterações desejadas das propriedades do gêmeo definidas por um aplicativo de back-end ou pelo Hub IoT.

Esta seção descreve como usar o pacote azure-iot-device no SDK da Internet das Coisas do Azure para Node.js para criar um aplicativo de dispositivo para:

• Recuperar um dispositivo gêmeo e examinar as propriedades relatadas
• Atualizar as propriedades relatadas do dispositivo gêmeo
• Receber aviso de alterações de propriedades desejadas

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 teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Melhores práticas de segurança> em Conexão de segurança.

Instalar pacotes do SDK

Execute esse comando para instalar o SDK do dispositivo azure-iot-device em seu computador de desenvolvimento:

npm install azure-iot-device --save

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

Escolher um protocolo de transporte

O objeto Client dá suporte a esses protocolos:

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

Instale os protocolos de transporte necessários em seu computador de desenvolvimento.

Por exemplo, esse comando instala o protocolo Mqtt:

npm install azure-iot-device-mqtt --save

Para obter mais informações sobre as diferenças entre a compatibilidade a MQTT, AMQP e HTTPS, consulte Diretrizes de comunicação da nuvem para dispositivo e Escolher um protocolo de comunicação.

Criar um módulo cliente

Crie um módulo Client usando o pacote instalado.

Por exemplo:

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

Criar um módulo de protocolo

Crie um módulo Protocol usando um pacote de transporte instalado.

Esse exemplo atribui o protocolo MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

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 – Uma cadeia de conexão que encapsula as permissões de "conexão de dispositivo" para um hub IoT. A cadeia de conexão contém o nome do host, a identidade do dispositivo e a chave de acesso compartilhada neste formato: "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>".
• transportCtor – protocolo de transporte.

Esse exemplo usa o protocolo de transporte Mqtt:

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

Abrir 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. Use .catch(err) para capturar um erro e executar o código do manipulador.

Por exemplo:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Recuperar um dispositivo gêmeo e examinar as propriedades relatadas

Chame getTwin para recuperar as informações atuais do dispositivo gêmeo em um objeto Twin.

Por exemplo:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Atualizar as propriedades relatadas do dispositivo gêmeo

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

Nesse exemplo, um patch de dispositivo gêmeo no formato JSON é armazenado na variável patch. O patch contém um valor de atualização connectivity do dispositivo gêmeo de cellular. O patch e o manipulador de erros são passados para o método update. Se houver um erro, uma mensagem de erro do console será exibida.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
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 propriedades desejadas

Crie um ouvinte de eventos de atualização da propriedade desejada que é executado quando uma propriedade desejada é alterada no dispositivo passando o nome do método do manipulador de retorno de chamada para twin.on.

O ouvinte de eventos da propriedade desejada pode usar um dos seguintes formatos:

• Receber 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

Receber todos os patches com um único manipulador de eventos

Você pode criar um ouvinte para receber as alterações da propriedade desejada.

Esse código de exemplo gera 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 for alterado.

Por exemplo:

1. As propriedades minTemperature e maxTemperature estão localizadas em um agrupamento de propriedades chamado properties.desired.climate changes.

2. Um aplicativo de serviço de back-end aplica esse patch para atualizar as propriedades desejadas minTemperature e maxTemperature:

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

3. Esse código configura um ouvinte de evento de alteração de propriedades desejadas que dispara com as alterações no agrupamento de propriedades properties.desired.climate. Se houver uma alteração de propriedade desejada nesse grupo, as mensagens de alteração de temperatura mínima e máxima que sã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. Nesse exemplo, o código para esse evento será executado somente se o valor booliano fanOn fizer parte do patch. O código gera o novo estado fanOn desejado sempre que o serviço o atualiza.

1. Um aplicativo de back-end aplica esse patch de propriedade desejada:

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

2. O ouvinte dispara somente quando a propriedade fanOn é alterada:

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

Exemplos do SDK do dispositivo

O SDK da Internet das Coisas do Azure para Node.js contém dois exemplos de dispositivo gêmeo:

• Exemplo simples de dispositivo gêmeo

• Exemplo simples de dispositivo gêmeo com SAS

Criar um aplicativo de back-end

Um aplicativo de back-end se conecta a um dispositivo por meio do Hub IoT e pode ler as propriedades relatadas e desejadas do dispositivo, gravar as propriedades desejadas do dispositivo e executar as consultas do dispositivo.

Esta seção descreve como criar um aplicativo de back-end que:

• Recupera e atualiza um dispositivo gêmeo
• Cria uma consulta de dispositivo gêmeo

Instalar pacotes do SDK do serviço

Execute esse comando para instalar azure-iothub em seu computador de desenvolvimento:

npm install azure-iothub --save

A classe Registry expõe todos os métodos necessários para interagir com os dispositivos gêmeos de um aplicativo de back-end.

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 compartilhado
• 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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Conectar-se usando a política de acesso compartilhado

Use fromConnectionString para se conectar ao hub IoT. O seu aplicativo 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á uma política de acesso compartilhado padrão que contenha apenas essas duas permissões, então você precisa criar uma caso ainda não exista. Forneça essa cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre as políticas de acesso compartilhado, confira Controlar o acesso ao Hub IoT com as assinaturas de acesso compartilhado.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Conectar-se usando o Microsoft Entra

Um aplicativo de back-end que usa o Microsoft Entra deve ser autenticado com sucesso e obter 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, confira Controlar o acesso ao Hub IoT usando o Microsoft Entra ID.

Para obter uma visão geral da autenticação do SDK do Node.js, confira:

• Comece a usar a autenticação do usuário no Azure
• Biblioteca de clientes da Identidade do Azure para JavaScript

Configurar o aplicativo Microsoft Entra

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

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos do 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 a módulos gêmeos. Para obter mais informações, confira 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 do Microsoft Entra, confira 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 TokenCredential específico ou ChainedTokenCredential reduzido. Para simplificar, esta seção descreve a autenticação usando DefaultAzureCredential e um segredo do cliente. Para obter mais informações sobre os prós e contras do uso de DefaultAzureCredential, confira Cadeias de credenciais na biblioteca de clientes da Identidade do Azure para JavaScript

O 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 credencial em uma ordem até encontrar uma credencial em funcionamento.

O Microsoft Entra requer este pacote:

npm install --save @azure/identity

Neste exemplo, o segredo do cliente de registro do aplicativo do Microsoft Entra, a ID do cliente e a ID do locatário foram adicionados a variáveis de ambiente. Essas variáveis de ambiente são usadas pelo 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.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

O token de credencial resultante pode então ser passado para fromTokenCredential para se conectar ao Hub IoT para um cliente do SDK que aceite as credenciais do Microsoft Entra:

• Registro
• Cliente
• JobClient

fromTokenCredential requer dois parâmetros:

• O URL do serviço do Azure – O URL do serviço do Azure deve estar no formato {Your Entra domain URL}.azure-devices.net sem um prefixo https://. Por exemplo, MyAzureDomain.azure-devices.net.
• O token de credencial do Azure

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

Exemplos de código

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

Recuperar e atualizar um dispositivo gêmeo

Você pode criar um patch que contém tags e atualizações de propriedades desejadas para um dispositivo gêmeo.

Para atualizar um dispositivo gêmeo:

1. Chame getTwin para recuperar o objeto gêmeo do dispositivo.

• Formate um patch que contenha a atualização do dispositivo gêmeo. O patch estpá no formato JSON, conforme descrito na classe Twin. Um patch de serviço de back-end pode conter tags e atualizações de propriedades desejadas. Para obter mais informações sobre o formato de patch, confira Tags e formato de propriedades.

1. Chame update para atualizar o dispositivo gêmeo com o patch.

Nesse exemplo, o dispositivo gêmeo é recuperado para myDeviceId, em seguida, um patch é aplicado aos gêmeos que contém a atualização da tag location de region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Criar uma consulta de dispositivo gêmeo

Você pode criar consultas de dispositivo semelhantes a SQL para coletar informações de dispositivos gêmeos.

Use createQuery para criar uma consulta que pode ser executada em uma instância do hub IoT para encontrar informações sobre dispositivos ou trabalhos.

createQuery inclui dois parâmetros:

• sqlQuery – A consulta escrita como uma cadeia de caracteres SQL.
• pageSize – O número desejado de resultados por página (opcional. padrão: 1000, máximo: 10000).

Se o parâmetro pageSize for especificado, o objeto de consulta conterá uma propriedade booliana hasMoreResults que você pode verificar e usar o método nextAsTwin para obter a próxima página de resultados do gêmeo quantas vezes forem necessárias para recuperar todos os resultados. Um método chamado next está disponível para resultados que não são dispositivos gêmeos, por exemplo, os resultados de consultas de agregação.

Essa consulta de exemplo seleciona apenas os dispositivos gêmeos de dispositivos localizados na planta Redmond43.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Essa consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados por meio da rede celular.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Exemplo de SDK de serviço

O SDK da Internet das Coisas do Azure para Node.js fornece um exemplo funcional de um aplicativo de serviço que lida com as tarefas do dispositivo gêmeo. Para obter mais informações, confira Serviço de Back-end do Dispositivo Gêmeo – Esse projeto é usado para enviar atualizações de patch do dispositivo gêmeo para um dispositivo específico.