Introdução aos dispositivos duplos

Use o SDK de dispositivo do Hub IoT do Azure e o SDK de serviço para desenvolver aplicativos que lidam com tarefas gêmeas de dispositivo comuns. Gêmeos de dispositivo são documentos JSON que armazenam informações de estado do dispositivo, incluindo metadados, configurações e condições. O Hub IoT persiste um gêmeo de dispositivo para cada dispositivo que se conecta a ele.

Você pode usar gêmeos de dispositivo para:

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

Para obter mais informações sobre gêmeos de dispositivo, incluindo quando usar gêmeos de dispositivo, consulte Compreender e usar gêmeos de dispositivo no Hub IoT.

Nota

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

Este 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 tags gêmeas de dispositivo, definir novas propriedades desejadas e consultar dispositivos com base em valores de gêmeos de dispositivo.

Nota

Este artigo destina-se a complementar exemplos de SDKs do Azure IoT referenciados neste artigo. Você pode usar ferramentas SDK para criar aplicativos de dispositivo e back-end.

Pré-requisitos

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

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

• Se o seu aplicativo usa o protocolo MQTT, certifique-se de que a porta 8883 esteja aberta no firewall. O protocolo MQTT se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).

• Requisitos do SDK de idioma:

  • .NET SDK - Requer Visual Studio.
  • Python SDK - Python versão 3.7 ou posterior é recomendado. Certifique-se de que utiliza a instalação de 32 ou 64 bits, conforme exigido pela sua configuração. Quando lhe for pedido durante a instalação, confirme que adiciona Python à variável de ambiente específica da sua plataforma.
  • Java - Requer Java SE Development Kit 8. Certifique-se de selecionar Java 8 em Suporte de longo prazo para navegar até downloads para JDK 8.
  • Node.js - Requer Node.js versão 10.0.x ou posterior.

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para .NET para criar código de aplicativo de serviço de dispositivo e back-end para gêmeos de dispositivo.

Criar um aplicativo de dispositivo

Os aplicativos de dispositivo podem ler e gravar propriedades de gêmeos relatados e ser notificados sobre as alterações de propriedades gêmeas desejadas definidas por um aplicativo de back-end ou 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 propriedades gêmeas do dispositivo relatadas
• Criar um manipulador de retorno de chamada de atualização de propriedade desejado

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança de conexão.

Adicionar pacote NuGet do dispositivo

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

Ligar a um dispositivo

A classe DeviceClient expõe todos os métodos necessários para interagir com gêmeos de dispositivo 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 de conexão.

O CreateFromConnectionString parâmetro de protocolo de transporte TransportType suporta os seguintes protocolos de transporte:

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

O Http1 protocolo não é suportado para atualizações gêmeas de dispositivo.

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

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 propriedades

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

Este exemplo recupera propriedades gêmeas de dispositivo e imprime os valores gêmeos no formato JSON.

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

Atualizar propriedades gêmeas do dispositivo relatadas

Para atualizar uma propriedade dupla relatada:

1. Criar um objeto TwinCollection para a atualização de propriedade relatada
2. Atualizar uma ou mais propriedades relatadas dentro do TwinCollection objeto
3. Use UpdateReportedPropertiesAsync para enviar por push as alterações de propriedade relatadas para o serviço de 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 desejado

Crie um manipulador de retorno de chamada de atualização de propriedade desejada que é executado quando uma propriedade desejada é alterada no gêmeo de dispositivo 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 chamadoOnDesiredPropertyChangedAsync sempre que uma propriedade desejada é alterada.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

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

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

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 do Azure IoT para .NET fornece uma amostra funcional de um aplicativo de dispositivo que lida com tarefas gêmeas de dispositivo. Para obter mais informações, consulte 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 desejadas e relatadas do dispositivo, gravar as propriedades desejadas do dispositivo e executar consultas de dispositivo.

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

• Ler e atualizar campos gêmeos do dispositivo
• Criar uma consulta dupla de dispositivo

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

Adicionar pacote NuGet de 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 partilhado
• 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 autenticar em um serviço com ID do Microsoft Entra ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

Conecte um aplicativo back-end a um dispositivo usando CreateFromConnectionString. Seu aplicativo precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo de dispositivo e precisa de permissão de 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 se uma ainda não existir. Forneça esta cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com 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 autenticar e obter com êxito 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, consulte Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.

Configurar o aplicativo Microsoft Entra

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

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos 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 gêmeos de módulo. Para obter mais informações, consulte 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 Microsoft Entra, consulte Guia de 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 específico TokenCredential ou ChainedTokenCredentialreduzido. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras do uso DefaultAzureCredentialdo , consulte Diretrizes de uso para DefaultAzureCredential.

DefaultAzureCredential suporta 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 credenciais em uma ordem até encontrar uma credencial de trabalho.

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

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

Neste exemplo, o segredo do cliente de registro do aplicativo 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 por 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 ser passado para um método de conexão ao Hub IoT para qualquer cliente SDK que aceite 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, o TokenCredential é passado para RegistryManager.Create 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 de autenticação de serviço do Microsoft Entra, consulte Exemplo de autenticação baseada em função.

Ler e atualizar campos gêmeos do dispositivo

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

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

Depois de fazer atualizações de campo duplo, chame UpdateTwinAsync para gravar Twin atualizações de campo de objeto em um dispositivo. Use try e catch lógica juntamente com um manipulador de erros para detetar erros de patch formatados incorretamente do UpdateTwinAsync.

Ler e atualizar tags gêmeas do dispositivo

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

Atualizar tags usando um objeto gêmeo

Este exemplo cria um patch de location marca, atribui-o Twin ao objeto usando a Tags propriedade e, em seguida, aplica 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 gêmeas de dispositivo formatado em JSON. O Hub IoT analisa e aplica o patch se ele estiver formatado corretamente.

Este exemplo chama GetTwinAsync para recuperar os campos gêmeos do dispositivo atual em um Twin objeto, cria um patch formatado em tag JSON com informações de região e localização da planta e, em seguida, chama UpdateTwinAsync para aplicar o patch para atualizar o gêmeo do dispositivo. 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);
}

Visualizar e atualizar propriedades desejadas gêmeas

Use a propriedade TwinProperties.Desired do dispositivo twin para ler e gravar as informações da propriedade desejada do dispositivo. Atualize as propriedades gêmeas Desired usando um patch formatado em JSON.

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

// 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 gêmeos

Você também pode aplicar atualizações gêmeas usando estes métodos SDK:

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

Criar uma consulta dupla de dispositivo

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

Para criar uma consulta gêmea de dispositivo, 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.

Próxima chamada GetNextAsTwinAsync ou GetNextAsJsonAsync método quantas vezes forem necessárias para recuperar todos os resultados gêmeos.

• GetNextAsTwinAsync para recuperar o próximo resultado paginado como objetos Twin .
• GetNextAsJsonAsync para recuperar o próximo resultado paginado como cadeias de caracteres JSON.

A IQuery interface inclui uma propriedade booleana HasMoreResults que você pode usar para verificar se há mais resultados gêmeos para buscar.

Esta consulta de exemplo seleciona apenas os 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)));

Esta consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados através 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 SDK

O SDK do Azure IoT para .NET fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas de dispositivo. Para obter mais informações, consulte Exemplo do Gerenciador do Registro.

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para Java para criar código de aplicativo de serviço de dispositivo e back-end para gêmeos de dispositivo.

Criar um aplicativo de dispositivo

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

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

• Recuperar e visualizar um dispositivo twin
• Atualizar propriedades gêmeas do dispositivo relatadas
• Subscrever as alterações de propriedade pretendidas

A classe DeviceClient expõe todos os métodos necessários para interagir com gêmeos de dispositivo 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 testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança de conexão.

Instruções de importação de dispositivo

Use as seguintes instruções de importação de dispositivo para acessar o SDK do Azure IoT para Java.

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

Ligar ao dispositivo

Para ligar a um dispositivo:

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

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

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

   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 visualizar um dispositivo twin

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

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 propriedades relatadas de gêmeos de dispositivo

Depois de recuperar o gêmeo atual, você pode começar a fazer atualizações de propriedade relatadas. Você também pode 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 ligando getTwin novamente.

Para atualizar as propriedades relatadas:

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

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

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

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

Subscrever as alterações de propriedade pretendidas

Chame subscribeToDesiredProperties para assinar as alterações de propriedade desejadas. Este cliente recebe um retorno de chamada com um Twin objeto cada vez 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.

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

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

Neste exemplo, o manipulador de retorno de chamada de alteração de DesiredPropertiesUpdatedHandler propriedade desejado chama getDesiredProperties para recuperar as alterações de propriedade e, em seguida, imprime as propriedades gêmeas 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 do Azure IoT para Java inclui um exemplo de trabalho para testar os conceitos de aplicativo de dispositivo descritos neste artigo. Para obter mais informações, consulte Exemplo de gêmeo de dispositivo.

Criar um aplicativo de back-end

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

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

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

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

Use as seguintes instruções de importação de serviço para acessar o SDK do Azure IoT para Java.

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

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 partilhado
• 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 autenticar em um serviço com ID do Microsoft Entra ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

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

Seu aplicativo precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo de dispositivo e precisa de permissão de 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 se uma ainda não existir. Forneça esta cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com assinaturas de acesso compartilhado.

O objeto DeviceTwinDevice representa o gêmeo de dispositivo 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 autenticar e obter com êxito 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, consulte Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.

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

Para simplificar, esta seção se concentra na descrição da autenticação usando o segredo do cliente.

Configurar o aplicativo Microsoft Entra

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

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos 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 gêmeos de módulo. Para obter mais informações, consulte 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 Microsoft Entra, consulte Guia de 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 específico TokenCredential ou ChainedTokenCredentialreduzido. Para obter mais informações sobre os prós e contras do uso DefaultAzureCredentialdo , consulte Cadeias de credenciais na biblioteca de cliente do Azure Identity para Java.

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 credenciais em uma ordem até encontrar uma credencial de trabalho.

Você pode autenticar as credenciais do aplicativo Microsoft Entra usando DefaultAzureCredentialBuilder. Salve parâmetros de conexão, como tenantID secreto do cliente, clientID e valores de segredo do cliente como variáveis ambientais. Uma vez criado, passe-o TokenCredential 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 ClientSecretCredentialBuilder

Você pode usar ClientSecretCredentialBuilder para criar uma credencial usando informações de 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, os valores de segredo do cliente de registro do aplicativo Microsoft Entra, ID do cliente e ID do locatário foram adicionados às variáveis de ambiente. Essas variáveis de ambiente são usadas para ClientSecretCredentialBuilder 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 Java SDK também inclui estas classes que autenticam um aplicativo de back-end com o Microsoft Entra:

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

Amostras de código

Para obter exemplos de funcionamento da autenticação de serviço do Microsoft Entra, consulte Exemplo de autenticação baseada em função.

Atualizar campos duplos do dispositivo

Para atualizar os campos gêmeos do dispositivo:

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

   Este exemplo recupera e imprime os campos gêmeos do dispositivo:

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

2. Usar um HashSet objeto para add um grupo de pares de tags gêmeas

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

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

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

   // 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 dupla de dispositivo

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

A classe Query contém métodos que podem ser usados para criar consultas no estilo SQL para o 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 de 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 um máximo de 100 dispositivos.

Esta consulta de exemplo seleciona apenas os 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());
}

Esta consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados através 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 SDK

O SDK do Azure IoT para Java fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas de dispositivo. Para obter mais informações, consulte Exemplo de gêmeo de dispositivo.

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para Python para criar código de aplicativo de serviço de back-end e dispositivo para gêmeos de dispositivo.

Criar um aplicativo de dispositivo

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

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

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

• Recupera um dispositivo gêmeo e examina as propriedades relatadas
• Propriedades gêmeas do dispositivo relatadas pelo patch

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança de conexão.

Ligar a um dispositivo

Esta 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. Ligar 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 informações de gêmeos do dispositivo, incluindo tags e propriedades. As informações de gêmeo de dispositivo recuperadas correspondem aos dados formatados em JSON de gêmeo de dispositivo que você pode exibir para um dispositivo no portal do Azure.

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

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

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

Propriedades gêmeas do dispositivo relatadas pelo patch

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

Para aplicar um patch para atualizar as propriedades relatadas:

1. Atribua um patch JSON de propriedade relatada a uma variável.
2. Chame patch_twin_reported_properties para aplicar o patch JSON às propriedades relatadas. Esta é uma chamada síncrona, o que significa que esta função não retorna até que o patch seja enviado para o serviço e 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 estes métodos para atualizar gêmeos de dispositivo:

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

Manipulador de patch de propriedades desejadas de entrada

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

Este 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 propriedade desejadas do JSON.

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

Exemplos de dispositivos SDK

O SDK do Azure IoT para Python inclui os seguintes exemplos:

• get_twin - Conecte-se a um dispositivo e recupere informações de gêmeos.
• update_twin_reported_properties - Atualize as propriedades relatadas por gêmeos.
• receive_twin_desired_properties - Receba e atualize 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 desejadas e relatadas do dispositivo, gravar as propriedades desejadas do dispositivo e executar consultas de dispositivo.

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

• Atualizar tags gêmeas e propriedades desejadas
• 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 gêmeos de dispositivo 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 partilhado
• 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 autenticar em um serviço com ID do Microsoft Entra ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

Conecte-se ao hub IoT usando from_connection_string. Seu aplicativo precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo de dispositivo e precisa de permissão de 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 se uma ainda não existir. Forneça esta cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com 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 autenticar e obter com êxito 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, consulte Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.

Para obter uma visão geral da autenticação do SDK do Python, consulte 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 Microsoft Entra configurado para sua credencial de autenticação preferida. O aplicativo contém parâmetros como segredo do cliente que são usados pelo aplicativo back-end para autenticar. As configurações de autenticação de aplicativo disponíveis são:

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos 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 gêmeos de módulo. Para obter mais informações, consulte 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 Microsoft Entra, consulte Guia de 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 específico TokenCredential ou ChainedTokenCredentialreduzido. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras do uso DefaultAzureCredentialdo , consulte Cadeias de credenciais na biblioteca de cliente do Azure Identity para Python.

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 credenciais em uma ordem até encontrar uma credencial de trabalho.

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

pip install azure-identity

from azure.identity import DefaultAzureCredential

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

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

from_token_credential requer dois parâmetros:

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

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

Amostras de código

Para obter exemplos de trabalho da autenticação do serviço Microsoft Entra, consulte Microsoft Authentication Library (MSAL) for Python.

Atualizar tags gêmeas e propriedades desejadas

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

1. Ligue para 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. Ligue update_twin para aplicar o patch no dispositivo gêmeo. Você também pode usar replace_twin para substituir as propriedades e tags desejadas para um dispositivo gêmeo.

Este exemplo atualiza region e marca informações e define uma power_level propriedade desejada como 1plant .

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 dupla de dispositivo

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

Para usar uma consulta gêmea de dispositivo:

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

2. Use query_iot_hub para consultar um IoTHub e recuperar informações de gêmeos de dispositivo usando a especificação de consulta semelhante a SQL.

Este exemplo executa duas consultas. O primeiro seleciona apenas os gêmeos de dispositivos localizados na Redmond43 planta, e o segundo refina a consulta para selecionar apenas os dispositivos que também estão conectados através de uma rede 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 SDK

O SDK do Azure IoT para Python fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas de dispositivo. Para obter mais informações, consulte Exemplo de consulta do Gerenciador do Registro.

Descrição geral

Este artigo descreve como usar o SDK do Azure IoT para Node.js para criar código de aplicativo de serviço de dispositivo e back-end para gêmeos de dispositivo.

Criar um aplicativo de dispositivo

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

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

• Recuperar um dispositivo gêmeo e examinar as propriedades relatadas
• Atualizar propriedades gêmeas do dispositivo relatadas
• Receber aviso de alterações de propriedade 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 testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança de conexão.

Instalar pacotes SDK

Execute este comando para instalar o SDK do dispositivo azure-iot-device em sua máquina de desenvolvimento:

npm install azure-iot-device --save

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

Escolha um protocolo de transporte

O Client objeto suporta estes protocolos:

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

Instale os protocolos de transporte necessários em sua máquina de desenvolvimento.

Por exemplo, este comando instala o Mqtt protocolo:

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

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

Criar um módulo cliente

Crie um Client módulo usando o pacote instalado.

Por exemplo:

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

Criar um módulo de protocolo

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

Este 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 permissões de "conexão de dispositivo" para um hub IoT. A cadeia de conexão contém nome do host, ID do dispositivo ou chave de acesso compartilhado neste formato: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
• transportCtor - O protocolo de transporte.

Este exemplo usa o Mqtt protocolo de transporte:

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

Abra 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 informações gêmeas do dispositivo atual em um objeto Twin .

Por exemplo:

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

Atualizar propriedades gêmeas do dispositivo relatadas

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

Neste exemplo, um patch gêmeo de dispositivo formatado patch em JSON é armazenado na variável. O patch contém um valor de atualização gêmea connectivity de dispositivo de cellular. O patch e o manipulador de erros são passados para o update método. 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 propriedade desejadas

Crie um ouvinte de eventos de atualização de 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 de propriedade desejado pode assumir uma das seguintes formas:

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

Receba todos os patches com um único manipulador de eventos

Você pode criar um ouvinte para receber qualquer alteração de propriedade desejada.

Este código de exemplo gera a saída de 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 mudar.

Por exemplo:

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

2. Um aplicativo de serviço de back-end aplica esse patch à atualização minTemperature e maxTemperature às propriedades desejadas:

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

3. Esse código configura um ouvinte de eventos de alteração de propriedades desejado que é acionado para quaisquer alterações dentro do properties.desired.climate agrupamento de propriedades. Se houver uma alteração de propriedade desejada dentro desse grupo, as mensagens de alteração de temperatura mínima e máxima 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. Neste exemplo, o código para esse evento é executado somente se o fanOn valor booleano fizer parte do patch. O código produz o novo estado desejado fanOn sempre que o serviço o atualiza.

1. Um aplicativo de back-end aplica este patch de propriedade desejado:

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

2. O ouvinte aciona somente quando a fanOn propriedade muda:

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

Exemplos de SDK de dispositivo

O SDK do Azure IoT para Node.js contém dois exemplos gêmeos de dispositivo:

• Dispositivo de amostra simples gêmeo

• Dispositivo de amostra simples twin 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 desejadas e relatadas do dispositivo, gravar as propriedades desejadas do dispositivo e executar consultas de dispositivo.

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

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

Instalar pacotes SDK de serviço

Execute este comando para instalar o azure-iothub em sua máquina de desenvolvimento:

npm install azure-iothub --save

A classe Registry expõe todos os métodos necessários para interagir com gêmeos de dispositivo 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 partilhado
• 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 autenticar em um serviço com ID do Microsoft Entra ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança na nuvem.

Conectar-se usando uma política de acesso compartilhado

Use fromConnectionString para se conectar ao hub IoT. Seu aplicativo precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo de dispositivo e precisa de permissão de 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 se uma ainda não existir. Forneça esta cadeia de conexão de política de acesso compartilhado como um parâmetro para fromConnectionString. Para obter mais informações sobre políticas de acesso compartilhado, consulte Controlar o acesso ao Hub IoT com 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 autenticar e obter com êxito 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, consulte Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.

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

• Introdução à autenticação de usuário no Azure
• Biblioteca de cliente do Azure Identity para JavaScript

Configurar o aplicativo Microsoft Entra

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

• Segredo do cliente
• Certificado
• Credencial de identidade federada

Os aplicativos 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 gêmeos de módulo. Para obter mais informações, consulte 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 Microsoft Entra, consulte Guia de 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 específico TokenCredential ou ChainedTokenCredentialreduzido. Para simplificar, esta seção descreve o uso da DefaultAzureCredential autenticação e o segredo do cliente. Para obter mais informações sobre os prós e contras do uso DefaultAzureCredentialdo , consulte Cadeias de credenciais na biblioteca de cliente do Azure Identity para JavaScript

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 credenciais em uma ordem até encontrar uma credencial de trabalho.

O Microsoft Entra requer este pacote:

npm install --save @azure/identity

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

• Registo
• Cliente
• JobClient

fromTokenCredential requer dois parâmetros:

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

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

Amostras de código

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

Recuperar e atualizar um dispositivo twin

Você pode criar um patch que contenha 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 gêmea do dispositivo. O patch é formatado em JSON conforme descrito na classe Twin. Um patch de serviço de back-end pode conter atualizações de tags e propriedades desejadas. Para obter mais informações sobre o formato do patch, consulte Tags e formato de propriedades.

1. Ligue para atualizar o dispositivo gêmeo com o patch.

Neste exemplo, o dispositivo gêmeo é recuperado para myDeviceId, em seguida, um patch é aplicado aos gêmeos que contém location a atualização de tag 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 dupla de dispositivo

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

Use createQuery para criar uma consulta que pode ser executada em uma instância do hub IoT para localizar 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, max: 10000).

Se o parâmetro pageSize for especificado, o objeto de consulta conterá uma hasMoreResults propriedade booleana que você pode verificar e usar o nextAsTwin método para obter a próxima página de resultados gêmeos 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 gêmeos de dispositivo, por exemplo, os resultados de consultas de agregação.

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

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(','));
    }
});

Esta consulta de exemplo refina a primeira consulta para selecionar apenas os dispositivos que também estão conectados através 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 do Azure IoT para Node.js fornece uma amostra funcional de um aplicativo de serviço que lida com tarefas gêmeas de dispositivo. Para obter mais informações, consulte Device Twin Backend Service - Este projeto é usado para enviar atualizações de patch duplo de dispositivo para um dispositivo específico.