Introdução aos gêmeos de dispositivo (Java)

Artigo
01/29/2024

os dispositivos duplos são documentos JSON que armazenam informações de estado dos dispositivos, incluindo metadados, configurações e condições. O Hub IoT persiste um gêmeo de dispositivo para cada dispositivo que se conecta a ele.

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.

Use gêmeos de dispositivo para:

Armazene metadados do dispositivo a partir do back-end da solução.
Relate informações de estado atual, como recursos e condições disponíveis, por exemplo, o método de conectividade usado, do aplicativo do dispositivo.
Sincronize 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.
Consulte os metadados, a configuração ou o estado do dispositivo.

Os gêmeos de dispositivo são projetados para sincronização e para consultar configurações e condições do dispositivo. Para obter mais informações sobre gêmeos de dispositivo, incluindo quando usar gêmeos de dispositivo, consulte Compreender gêmeos de dispositivo.

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

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

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

A ilustração a seguir mostra a organização de gêmeos do dispositivo:

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

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

Este artigo mostra-lhe como:

Use um aplicativo de dispositivo simulado para relatar seu canal de conectividade como uma propriedade relatada no gêmeo do dispositivo.
Consulte dispositivos a partir do seu aplicativo back-end usando filtros nas tags e propriedades criadas anteriormente.

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

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

Nota

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

Pré-requisitos

Um hub IoT. Crie um com a CLI ou o portal do Azure.
Um dispositivo registrado em seu hub IoT. Se você não tiver um dispositivo em seu hub IoT, siga as etapas em Registrar um dispositivo.
Kit de Desenvolvimento Java SE 8. Certifique-se de selecionar Java 8 em Suporte de longo prazo para obter downloads para JDK 8.
Maven 3
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo neste artigo usa o protocolo MQTT, que 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).

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço 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 propriedades relatadas que foram atualizadas adequadamente. Seu serviço precisa da permissão de conexão de serviço para modificar as propriedades desejadas de um gêmeo de dispositivo e precisa da 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.

Para criar uma política de acesso compartilhado que conceda permissões de conexão de serviço e de leitura do Registro e obtenha 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 onde o hub está localizado e, em seguida, selecione o hub na lista de recursos.
No painel esquerdo do hub, selecione Políticas de acesso compartilhado.
No menu superior acima da lista de políticas, selecione Adicionar política de acesso à política compartilhada.
No painel Adicionar política de acesso compartilhado à direita, insira um nome descritivo para sua política, como serviceAndRegistryRead. Em Permissões, selecione Leitura do Registro e Conexão de Serviço e, em seguida, selecione Adicionar.
Selecione sua nova política na lista de políticas.
Selecione o ícone de cópia para a cadeia de conexão principal e salve o valor.

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

Criar um aplicativo de dispositivo que atualize as propriedades relatadas

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

Na pasta iot-java-twin-getstarted, crie um projeto Maven chamado simulated-device usando o seguinte comando 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 de dispositivo simulado.
Usando um editor de texto, abra o arquivo pom.xml na pasta simulated-device e adicione as seguintes dependências ao nó dependencies . Essa dependência permite que você use o pacote iot-device-client em seu aplicativo para se comunicar com seu hub IoT.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Nota

Pode verificar a versão mais recente do iot-device-client utilizando a pesquisa Maven.
Adicione a seguinte dependência ao nó dependências . Essa dependência configura um NOP para a fachada de log Apache SLF4J , que é usada pelo SDK do cliente de dispositivo para implementar o registro. Essa configuração é opcional, mas, se você omiti-la, poderá ver um aviso no console quando executar o aplicativo. Para obter mais informações sobre como registrar no SDK do cliente de dispositivo, consulte Registrando os exemplos para o arquivo Leiame 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ó de compilação após o nó de dependências . Essa configuração instrui o Maven a usar o Java 1.8 para construir 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>

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

Adicione as seguintes declarações de importação ao ficheiro:

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 de nível de classe à classe Aplicação. 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";
```
Esta aplicação de exemplo utiliza a variável de protocolo para instanciar 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 principal com o seguinte código para:

Crie um cliente de dispositivo para se comunicar com o Hub IoT.
Crie um objeto Device para armazenar as propriedades gêmeas do dispositivo.

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 ao método principal para criar uma propriedade relatada connectivityType e enviá-la para o 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 . Esperar pela chave Enter dá tempo para o Hub IoT relatar o status das operações gêmeas do dispositivo.
```
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 principal para incluir as exceções da seguinte forma:
```
public static void main(String[] args) throws URISyntaxException, IOException
```
Salve e feche o arquivo simulated-device\src\main\java\com\mycompany\app\App.java .
Crie o aplicativo de dispositivo simulado e corrija quaisquer 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 atualize as propriedades desejadas e consulte gêmeos

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

Em sua máquina 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 seguinte dependência ao nó dependencies . 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>
```
Nota

Pode verificar a versão mais recente do iot-service-client utilizando a pesquisa Maven.

Adicione o seguinte nó de compilação após o nó de dependências . Essa configuração instrui o Maven a usar Java 1.8 para construir 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>

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

Adicione as seguintes declarações de importação ao ficheiro:

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 de nível de classe à classe Aplicação. Substitua {youriothubconnectionstring} pela cadeia de conexão do hub IoT copiada 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 throws cláusula:
```
public static void main( String[] args ) throws IOException
```
Substitua o código no método principal com o 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 gêmeo de dispositivo com suas propriedades e tags:
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

Adicione o seguinte try/catch bloco 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 tags gêmeas de região e dispositivo de planta em seu dispositivo gêmeo, adicione o seguinte código no try bloco :

// 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 gêmeos de dispositivo no hub IoT, adicione o seguinte código ao try bloco após o código adicionado na etapa anterior. O código executa duas consultas. Cada consulta retorna um 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 quaisquer erros. No prompt de comando, navegue até a pasta add-tags-query e execute o seguinte comando:
```
mvn clean package -DskipTests
```

Executar as aplicações

Agora você está pronto para executar os aplicativos do 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 tags de planta e região adicionadas ao gêmeo do dispositivo. 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 connectivityType reported ao gêmeo do dispositivo:
```
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 seu dispositivo enviou a propriedade connectivityType para o Hub IoT, a segunda consulta retorna seu dispositivo.

Neste artigo, irá:

Metadados de dispositivo adicionados como tags de um aplicativo back-end
Informações de conectividade do dispositivo relatadas no gêmeo do dispositivo
Consultado as informações do gêmeo do dispositivo, usando a linguagem de consulta do Hub IoT semelhante ao SQL

Próximos passos

Para saber como:

Enviar telemetria de dispositivos, consulte Guia de 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 gêmeo de dispositivo, consulte Tutorial: Configurar seus dispositivos a partir de um serviço back-end
Controle dispositivos interativamente, como ligar um ventilador de um aplicativo controlado pelo usuário, consulte Guia de início rápido: controlar um dispositivo conectado a um hub IoT

Partilhar via