Introdução ao dispositivos gêmeos (Java)

Artigo
03/19/2023

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

Observação

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

Use os dispositivos gêmeos para:

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

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

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

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

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

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

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

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

Este artigo mostra como:

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

Neste artigo, você cria dois aplicativos de console Java:

add-tags-query: um aplicativo de back-end que adiciona marcas e consulta dispositivos gêmeos.
simulated-device: um aplicativo de dispositivo simulado que se conecta ao hub IoT e relata sua condição de conectividade.

Observação

Consulte os SDKs da IoT do Azure para obter mais informações sobre as ferramentas do SDK disponíveis para compilar aplicativos de dispositivo e back-end.

Pré-requisitos

Um hub IoT. Crie um com a CLI ou o portal do Azure.
Um dispositivo registrado. Registre um no portal do Azure.
Java SE Development Kit 8. Certifique-se de selecionar Java 8 em Suporte de longo prazo para obter downloads do JDK 8.
Maven 3
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

Obter a cadeia de conexão do hub IoT

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

Para criar uma política de acesso compartilhado que conceda as permissões conexão de serviço e leitura de registro e obter uma cadeia de conexão para essa política, siga estas etapas:

No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel do lado esquerdo do hub, selecione Políticas de acesso compartilhado.
No menu superior acima da lista de políticas, selecione Adicionar política de acesso compartilhado.
No painel Adicionar política de acesso compartilhado à direita, insira um nome descritivo para a política, como serviceAndRegistryRead. Em Permissões, selecione Leitura de Registro e Conexão de Serviço e selecione Adicionar.
Selecione a sua nova política na lista de políticas.
Selecione o ícone de cópia da Cadeia de conexão primária e salve o valor.

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Criar um aplicativo de dispositivo que atualiza as propriedades relatadas

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

Na pasta iot-java-twin-getstarted, crie um projeto Maven denominado simulated-device usando o comando a seguir no prompt de comando:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=simulated-device -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

No prompt de comando, navegue até a pasta simulated-device.
Usando um editor de texto, abra o arquivo pom.xml na pasta simulated-device e adicione as seguintes dependências ao nó dependências. Essa dependência permite que você use o pacote iot-device-client em seu aplicativo para se comunicar com o hub IoT.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Observação

Você pode verificar a versão mais recente do iot-device-client usando a pesquisa do Maven.
Adicione a dependência a seguir ao nó dependências. Essa dependência configura um NOP para a fachada de log do Apache SLF4J, que é usada pelo SDK do cliente do dispositivo para implementar o registro em log. Essa configuração é opcional, mas, se você omiti-la, poderá ver um aviso no console ao executar o aplicativo. Para obter mais informações sobre o registro em log no SDK de cliente do dispositivo, consulte Registro em log no arquivo Leiame Exemplos do SDK do dispositivo IoT do Azure para Java.
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Adicione o seguinte nó buid após o nó dependencies. Esta configuração instrui o Maven a usar Java 1.8 para compilar o aplicativo:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.3</version>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
      </configuration>
    </plugin>
  </plugins>
</build>

Salve e feche o arquivo pom.xml.
Usando um editor de texto, abra o arquivo simulated-device\src\main\java\com\mycompany\app\App.java.

Adicione as seguintes instruções import ao arquivo:

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

import java.io.IOException;
import java.net.URISyntaxException;
import java.util.Scanner;

Adicione as seguintes variáveis no nível da classe à classe App . Substitua {yourdeviceconnectionstring} pela cadeia de conexão de dispositivo que você viu quando registrou um dispositivo no Hub IoT:
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
Este aplicativo de exemplo usa a variável protocol quando cria uma instância de um objeto DeviceClient.

Adicione o seguinte método à classe App para imprimir informações sobre atualizações gêmeas:

protected static class DeviceTwinStatusCallBack implements IotHubEventCallback {
    @Override
    public void execute(IotHubStatusCode status, Object context) {
      System.out.println("IoT Hub responded to device twin operation with status " + status.name());
    }
  }

Substitua o código no método main pelo seguinte código para:

Criar um cliente de dispositivo para se comunicar com o Hub IoT.
Criar um objeto Dispositivo para armazenar as propriedades do dispositivo gêmeo.

DeviceClient client = new DeviceClient(connString, protocol);

// Create a Device object to store the device twin properties
Device dataCollector = new Device() {
  // Print details when a property value changes
  @Override
  public void PropertyCall(String propertyKey, Object propertyValue, Object context) {
    System.out.println(propertyKey + " changed to " + propertyValue);
  }
};

Adicione o seguinte código para ao método principal para criar uma propriedade relatada connectivityType e enviá-la ao Hub IoT:

try {
  // Open the DeviceClient and start the device twin services.
  client.open();
  client.startDeviceTwin(new DeviceTwinStatusCallBack(), null, dataCollector, null);

  // Create a reported property and send it to your IoT hub.
  dataCollector.setReportedProp(new Property("connectivityType", "cellular"));
  client.sendReportedProperties(dataCollector.getReportedProp());
}
catch (Exception e) {
  System.out.println("On exception, shutting down \n" + " Cause: " + e.getCause() + " \n" + e.getMessage());
  dataCollector.clean();
  client.closeNow();
  System.out.println("Shutting down...");
}

Adicione o seguinte código ao final do método principal. Aguardar a tecla Enter dá tempo para o Hub IoT relatar o status das operações do dispositivo gêmeo.
```
System.out.println("Press any key to exit...");

Scanner scanner = new Scanner(System.in);
scanner.nextLine();

dataCollector.clean();
client.close();
```

Modifique a assinatura do método main para incluir as exceções abaixo:

public static void main(String[] args) throws URISyntaxException, IOException

Salve e feche o arquivo simulated-device\src\main\java\com\mycompany\app\App.java.
Compile o aplicativo simulated-device e corrija os erros. No prompt de comando, navegue até a pasta simulated-device e execute o seguinte comando:
```
mvn clean package -DskipTests
```

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

Nesta seção, você cria um aplicativo Java que adiciona metadados de local associado como uma marca ao dispositivo gêmeo no Hub IoT associado a myDeviceId. O aplicativo consulta o hub IoT para dispositivos localizados nos EUA e, em seguida, consulta dispositivos que reportam a uma conexão de rede de celular.

Em seu computador de desenvolvimento, crie uma pasta vazia chamada iot-java-twin-getstarted.

Na pasta iot-java-twin-getstarted, crie um projeto Maven chamado add-tags-query usando o seguinte comando no prompt de comando:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=add-tags-query -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

No prompt de comando, navegue até a pasta add-tags-query.
Usando um editor de texto, abra o arquivo pom.xml na pasta add-tags-query e adicione a dependência a seguir ao nó dependências. Essa dependência permite que você use o pacote iot-service-client em seu aplicativo para se comunicar com seu hub IoT:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Observação

Você pode verificar a versão mais recente do iot-service-client usando a pesquisa do Maven.

Adicione o seguinte nó buid após o nó dependencies. Esta configuração instrui o Maven a usar o Java 1.8 para compilar o aplicativo.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.3</version>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
      </configuration>
    </plugin>
  </plugins>
</build>

Salve e feche o arquivo pom.xml.
Usando um editor de texto, abra o arquivo add-tags-query\src\main\java\com\mycompany\app\App.java.

Adicione as seguintes instruções import ao arquivo:

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

import java.io.IOException;
import java.util.HashSet;
import java.util.Set;

Adicione as seguintes variáveis no nível da classe à classe App . Substitua {youriothubconnectionstring} pela cadeia de conexão do hub IoT que você copiou em Obter a cadeia de conexão do hub IoT.

public static final String iotHubConnectionString = "{youriothubconnectionstring}";
public static final String deviceId = "myDeviceId";

public static final String region = "US";
public static final String plant = "Redmond43";

Atualize a assinatura do método principal para incluir a seguinte cláusula throws:
```
public static void main( String[] args ) throws IOException
```
Substitua o código no método main pelo código a seguir para criar os objetos DeviceTwin e DeviceTwinDevice. O objeto DeviceTwin lida com a comunicação com seu hub IoT. O objeto DeviceTwinDevice representa o dispositivo gêmeo com suas propriedades e marcas:
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

Adicione o seguinte bloco try/catch ao método principal:

try {
  // Code goes here
} catch (IotHubException e) {
  System.out.println(e.getMessage());
} catch (IOException e) {
  System.out.println(e.getMessage());
}

Para atualizar as marcas do dispositivo gêmeo região e planta no seu dispositivo gêmeo, adicione o seguinte código ao bloco try:

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

// 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 the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

Para consultar os dispositivos gêmeos no hub IoT, adicione o seguinte código ao bloco try após o código adicionado na etapa anterior. O código executa duas consultas. Cada consulta retorna o máximo de 100 dispositivos.

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

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

Salve e feche o arquivo add-tags-query\src\main\java\com\mycompany\app\App.java
Crie o aplicativo add-tags-query e corrija os erros. No prompt de comando, navegue até a pasta add-tags-query e execute o seguinte comando:
```
mvn clean package -DskipTests
```

Executar os aplicativos

Agora você está pronto para executar os aplicativos de console.

Em um prompt de comando na pasta add-tags-query, execute o seguinte comando para executar o aplicativo de serviço add-tags-query:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Você pode ver as marcas planta e região adicionadas ao dispositivo gêmeo. A primeira consulta retorna seu dispositivo, mas a segunda, não.
Em um prompt de comando na pasta simulated-device, execute o seguinte comando para adicionar a propriedade relatada connectivityType para o dispositivo gêmeo:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Em um prompt de comando na pasta add-tags-query, execute o seguinte comando para executar o aplicativo de serviço add-tags-query uma segunda vez:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Agora que o dispositivo enviou a propriedade connectivityType ao Hub IoT, a segunda consulta retornará seu dispositivo.

Neste artigo você:

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

Próximas etapas

Para saber como:

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

Share via