Introdução a dispositivos gêmeos

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

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:

• Conecta-se a um dispositivo por meio do Hub IoT
• Pode ler as propriedades relatadas e desejadas do dispositivo, gravar as propriedades desejadas do dispositivo e executar as consultas do dispositivo

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.

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

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

Conecte um aplicativo de back-end a um dispositivo usando CreateFromConnectionString. Como parâmetro, forneça a cadeia de conexão de serviço do Hub IoT que você criou na seção de pré-requisitos.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{IoT hub service connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

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.

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;

Conectar-se ao cliente de serviço do hub IoT

Para se conectar ao Hub IoT para exibir e atualizar informações do dispositivo gêmeo:

1. Crie um objeto DeviceTwinClientOptions. Defina todas as opções necessárias para seu aplicativo. Essas opções são passadas para o objeto DeviceTwin.
2. 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. Como parâmetros, forneça a cadeia de conexão de serviço do Hub IoT que você criou na seção Pré-requisitos e no objeto DeviceTwinClientOptions.
3. O objeto DeviceTwinDevice representa o dispositivo gêmeo com suas propriedades e tags.

Por exemplo:

public static final String iotHubConnectionString = "{IoT hub service 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
DeviceTwinClientOptions twinOptions = new DeviceTwinClientOptions();
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString,twinOptions);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

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

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

Conecte-se ao hub IoT usando from_connection_string. Como parâmetro, forneça a cadeia de conexão de serviço do Hub IoT que você criou na seção de pré-requisitos.

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)

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

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

Use fromConnectionString para se conectar ao hub IoT. Como parâmetro, forneça a cadeia de conexão de serviço do hub IoT que você criou na seção de pré-requisitos.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Iot Hub service connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

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.