Kom igång med enhetshantering (Java)

Artikel
10/01/2024

Serverdelsappar kan använda Azure IoT Hub-primitiver, till exempel enhetstvillingar och direktmetoder, för att fjärrstarta och övervaka enhetshanteringsåtgärder på enheter. Den här artikeln visar hur en serverdelsapp och en enhetsapp kan arbeta tillsammans för att initiera och övervaka en omstart av fjärrenheter med hjälp av IoT Hub.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Använd en direktmetod för att initiera åtgärder för enhetshantering (till exempel omstart, fabriksåterställning och uppdatering av inbyggd programvara) från en serverdelsapp i molnet. Enheten ansvarar för:

Hantera metodbegäran som skickas från IoT Hub.
Initiera motsvarande enhetsspecifika åtgärd på enheten.
Tillhandahålla statusuppdateringar via rapporterade egenskaper till IoT Hub.

Du kan använda en serverdelsapp i molnet för att köra frågor för enhetstvillingar för att rapportera om förloppet för dina enhetshanteringsåtgärder.

Den här artikeln visar hur du skapar:

simulated-device: en simulerad enhetsapp med en direktmetod som startar om enheten och rapporterar den senaste omstartstiden. Direktmetoder anropas från molnet.
trigger-reboot: en Java-app som anropar direktmetoden i den simulerade enhetsappen via din IoT-hubb. Den visar svaret och uppdaterade rapporterade egenskaper.

Kommentar

Information om de SDK:er som du kan använda för att skapa program för att köras på enheter och serverdelen för lösningen finns i Azure IoT SDK:er.

Förutsättningar

En IoT-hubb i din Azure-prenumeration. Om du inte har någon hubb ännu kan du följa stegen i Skapa en IoT-hubb.
En enhet som är registrerad i din IoT-hubb. Om du inte har en enhet i din IoT-hubb följer du stegen i Registrera en enhet.
Java SE Development Kit 8. Se till att du väljer Java 8 under Långsiktigt stöd för att komma till nedladdningar för JDK 8.
Maven 3
Kontrollera att port 8883 är öppen i brandväggen. Enhetsexemplet i den här artikeln använder MQTT-protokollet, som kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Ansluta till IoT Hub (MQTT).

Skapa en enhetsapp med en direktmetod

I det här avsnittet skapar du en Java-konsolapp som simulerar en enhet. Appen lyssnar efter anropet till direktmetoden för omstart från din IoT-hubb och svarar omedelbart på det samtalet. Appen viloläge ett tag för att simulera omstartsprocessen innan den använder en rapporterad egenskap för att meddela serverdelsappen trigger-reboot att omstarten är klar.

Viktigt!

Den här artikeln innehåller steg för att ansluta en enhet med en signatur för delad åtkomst, även kallad symmetrisk nyckelautentisering. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men att autentisera en enhet med X.509-certifikat är en säkrare metod. Mer information finns i Metodtips > för säkerhet Anslutningssäkerhet.

I mappen dm-get-started skapar du ett Maven-projekt med namnet simulated-device med följande kommando i kommandotolken:

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

Gå till mappen simulated-device i kommandotolken.
Med hjälp av en textredigerare öppnar du filen pom.xml i mappen simulated-device och lägger till följande beroenden i noden beroenden . Med det här beroendet kan du använda iot-service-client-paketet i din app för att kommunicera med din IoT-hubb:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
Kommentar

Du kan söka efter den senaste versionen av iot-device-client med Maven-sökning.
Lägg till följande beroende till noden beroenden. Det här beroendet konfigurerar en NOP för Apache SLF4J-loggningsfasaden , som används av enhetens klient-SDK för att implementera loggning. Den här konfigurationen är valfri, men om du utelämnar den kan du se en varning i konsolen när du kör appen. Mer information om loggning i enhetsklient-SDK finns i Loggning i exempel för Azure IoT-enhets-SDK för Java-readme-filen .
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

Lägg till följande byggnod efter noden beroenden. Den här konfigurationen instruerar Maven att använda Java 1.8 för att skapa appen:

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

Spara och stäng filen pom.xml.
Öppna filen simulated-device\src\main\java\com\mycompany\app\App.java med hjälp av en textredigerare.

Lägg till följande Import-instruktioner i filen:

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.time.LocalDateTime;
import java.util.Scanner;
import java.util.Set;
import java.util.HashSet;

Lägg till följande variabler på klassnivå till klassen App. Ersätt {yourdeviceconnectionstring} med enheten anslutningssträng du såg när du registrerade en enhet i IoT Hub:

private static final int METHOD_SUCCESS = 200;
private static final int METHOD_NOT_DEFINED = 404;

private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String connString = "{yourdeviceconnectionstring}";
private static DeviceClient client;

Om du vill implementera en motringningshanterare för statushändelser för direktmetod lägger du till följande kapslade klass i klassen App :

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

Om du vill implementera en motringningshanterare för statushändelser för enhetstvillingar lägger du till följande kapslade klass i klassen App :

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

Om du vill implementera en motringningshanterare för egenskapshändelser lägger du till följande kapslade klass i klassen App :

protected static class PropertyCallback implements PropertyCallBack<String, String>
{
  public void PropertyCall(String propertyKey, String propertyValue, Object context)
  {
    System.out.println("PropertyKey:     " + propertyKey);
    System.out.println("PropertyKvalue:  " + propertyKey);
  }
}

Om du vill implementera en tråd för att simulera omstarten av enheten lägger du till följande kapslade klass i klassen App . Tråden viloläge i fem sekunder och anger sedan egenskapen lastReboot reported:

protected static class RebootDeviceThread implements Runnable {
  public void run() {
    try {
      System.out.println("Rebooting...");
      Thread.sleep(5000);
      Property property = new Property("lastReboot", LocalDateTime.now());
      Set<Property> properties = new HashSet<Property>();
      properties.add(property);
      client.sendReportedProperties(properties);
      System.out.println("Rebooted");
    }
    catch (Exception ex) {
      System.out.println("Exception in reboot thread: " + ex.getMessage());
    }
  }
}

Om du vill implementera direktmetoden på enheten lägger du till följande kapslade klass i klassen App . När den simulerade appen tar emot ett anrop till direktmetoden för omstart returnerar den en bekräftelse till anroparen och startar sedan en tråd för att bearbeta omstarten:

protected static class DirectMethodCallback implements com.microsoft.azure.sdk.iot.device.DeviceTwin.DeviceMethodCallback
{
  @Override
  public DeviceMethodData call(String methodName, Object methodData, Object context)
  {
    DeviceMethodData deviceMethodData;
    switch (methodName)
    {
      case "reboot" :
      {
        int status = METHOD_SUCCESS;
        System.out.println("Received reboot request");
        deviceMethodData = new DeviceMethodData(status, "Started reboot");
        RebootDeviceThread rebootThread = new RebootDeviceThread();
        Thread t = new Thread(rebootThread);
        t.start();
        break;
      }
      default:
      {
        int status = METHOD_NOT_DEFINED;
        deviceMethodData = new DeviceMethodData(status, "Not defined direct method " + methodName);
      }
    }
    return deviceMethodData;
  }
}

Ändra signaturen för huvudmetoden för att utlösa följande undantag:

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

Om du vill instansiera en DeviceClient ersätter du koden i huvudmetoden med följande kod:

System.out.println("Starting device client sample...");
client = new DeviceClient(connString, protocol);

Om du vill börja lyssna efter direktmetodanrop lägger du till följande kod i huvudmetoden :

try
{
  client.open();
  client.subscribeToDeviceMethod(new DirectMethodCallback(), null, new DirectMethodStatusCallback(), null);
  client.startDeviceTwin(new DeviceTwinStatusCallback(), null, new PropertyCallback(), null);
  System.out.println("Subscribed to direct methods and polling for reported properties. Waiting...");
}
catch (Exception e)
{
  System.out.println("On exception, shutting down \n" + " Cause: " + e.getCause() + " \n" +  e.getMessage());
  client.close();
  System.out.println("Shutting down...");
}

Om du vill stänga av enhetssimulatorn lägger du till följande kod i huvudmetoden :

System.out.println("Press any key to exit...");
Scanner scanner = new Scanner(System.in);
scanner.nextLine();
scanner.close();
client.close();
System.out.println("Shutting down...");

Spara och stäng filen simulated-device\src\main\java\com\mycompany\app\App.java.
Skapa appen simulated-device och korrigera eventuella fel. I kommandotolken navigerar du till mappen simulated-device och kör följande kommando:
```
mvn clean package -DskipTests
```

Hämta IoT Hub-anslutningssträng

I den här artikeln skapar du en serverdelstjänst som anropar en direktmetod på en enhet. Om du vill anropa en direktmetod på en enhet via IoT Hub behöver din tjänst behörighet för tjänstanslutning . Som standard skapas varje IoT Hub med en princip för delad åtkomst med namnet service som ger den här behörigheten.

Följ dessa steg för att hämta IoT Hub-anslutningssträng för tjänstprincipen:

I Azure Portal väljer du Resursgrupper. Välj den resursgrupp där hubben finns och välj sedan din hubb i listan över resurser.
Välj Principer för delad åtkomst i den vänstra rutan i din IoT-hubb.
I listan över principer väljer du tjänstprincipen.
Kopiera den primära anslutningssträng och spara värdet.

Mer information om principer och behörigheter för delad åtkomst i IoT Hub finns i Åtkomstkontroll och behörigheter.

Skapa en tjänstapp för att utlösa en omstart

I det här avsnittet skapar du en Java-konsolapp som:

Anropar direktmetoden för omstart i den simulerade enhetsappen.
Visar svaret.
Avsöker de rapporterade egenskaperna som skickas från enheten för att avgöra när omstarten är klar.

Viktigt!

Den här artikeln innehåller steg för att ansluta till en tjänst med hjälp av en signatur för delad åtkomst. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men autentisering till en tjänst med Microsoft Entra-ID eller hanterade identiteter är en säkrare metod. Mer information finns i Metodtips för > säkerhet Molnsäkerhet.

Den här konsolappen ansluter till din IoT Hub för att anropa direktmetoden och läsa de rapporterade egenskaperna.

Skapa en tom mapp med namnet dm-get-started.

I mappen dm-get-started skapar du ett Maven-projekt med namnet trigger-reboot med hjälp av följande kommando i kommandotolken:

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

Gå till mappen trigger-reboot i kommandotolken.
Med hjälp av en textredigerare öppnar du filen pom.xml i mappen trigger-reboot och lägger till följande beroende till noden beroenden. Med det här beroendet kan du använda iot-service-client-paketet i din app för att kommunicera med din IoT-hubb:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
Kommentar

Du kan söka efter den senaste versionen av iot-service-client med Maven-sökning.

Lägg till följande byggnod efter noden beroenden. Den här konfigurationen instruerar Maven att använda Java 1.8 för att skapa appen:

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

Spara och stäng filen pom.xml.
Med hjälp av en textredigerare öppnar du källfilen trigger-reboot\src\main\java\com\mycompany\app\App.java .

Lägg till följande Import-instruktioner i filen:

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceMethod;
import com.microsoft.azure.sdk.iot.service.devicetwin.MethodResult;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;
import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwin;
import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;

import java.io.IOException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.Executors;
import java.util.concurrent.ExecutorService;

Lägg till följande variabler på klassnivå till klassen App. Ersätt {youriothubconnectionstring} med IoT Hub-anslutningssträng som du kopierade tidigare i Hämta IoT Hub-anslutningssträng:

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

private static final String methodName = "reboot";
private static final Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
private static final Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

Om du vill implementera en tråd som läser de rapporterade egenskaperna från enhetstvillingen var 10:e sekund lägger du till följande kapslade klass i klassen App :

private static class ShowReportedProperties implements Runnable {
  public void run() {
    try {
      DeviceTwin deviceTwins = DeviceTwin.createFromConnectionString(iotHubConnectionString);
      DeviceTwinDevice twinDevice = new DeviceTwinDevice(deviceId);
      while (true) {
        System.out.println("Get reported properties from device twin");
        deviceTwins.getTwin(twinDevice);
        System.out.println(twinDevice.reportedPropertiesToString());
        Thread.sleep(10000);
      }
    } catch (Exception ex) {
      System.out.println("Exception reading reported properties: " + ex.getMessage());
    }
  }
}

Ändra signaturen för huvudmetoden för att utlösa följande undantag:
```
public static void main(String[] args) throws IOException
```

Om du vill anropa omstartsdirigeringsmetoden på den simulerade enheten ersätter du koden i huvudmetoden med följande kod:

System.out.println("Starting sample...");
DeviceMethod methodClient = DeviceMethod.createFromConnectionString(iotHubConnectionString);

try
{
  System.out.println("Invoke reboot direct method");
  MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, null);

  if(result == null)
  {
    throw new IOException("Invoke direct method reboot returns null");
  }
  System.out.println("Invoked reboot on device");
  System.out.println("Status for device:   " + result.getStatus());
  System.out.println("Message from device: " + result.getPayload());
}
catch (IotHubException e)
{
    System.out.println(e.getMessage());
}

Om du vill starta tråden för att avsöka rapporterade egenskaper från den simulerade enheten lägger du till följande kod i huvudmetoden :

ShowReportedProperties showReportedProperties = new ShowReportedProperties();
ExecutorService executor = Executors.newFixedThreadPool(1);
executor.execute(showReportedProperties);

Du kan stoppa appen genom att lägga till följande kod i huvudmetoden :

System.out.println("Press ENTER to exit.");
System.in.read();
executor.shutdownNow();
System.out.println("Shutting down sample...");

Spara och stäng filen trigger-reboot\src\main\java\com\mycompany\app\App.java .
Skapa serverdelsappen trigger-reboot och korrigera eventuella fel. I kommandotolken navigerar du till mappen trigger-reboot och kör följande kommando:
```
mvn clean package -DskipTests
```

Köra apparna

Nu är du redo att köra apparna.

I en kommandotolk i mappen simulated-device kör du följande kommando för att börja lyssna efter omstartsmetodanrop från din IoT-hubb:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
I en kommandotolk i mappen trigger-reboot kör du följande kommando för att anropa omstartsmetoden på den simulerade enheten från din IoT-hubb:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
Den simulerade enheten svarar på anropet till direktmetoden för omstart:

Anpassa och utöka enhetshanteringsåtgärderna

Dina IoT-lösningar kan utöka den definierade uppsättningen med enhetshanteringsmönster eller aktivera anpassade mönster med hjälp av enhetstvillingen och primitiverna för moln-till-enhet-metoden. Andra exempel på åtgärder för enhetshantering är fabriksåterställning, uppdatering av inbyggd programvara, programuppdatering, energisparfunktioner, nätverks- och anslutningshantering samt datakryptering.

Fönster för enhetsunderhåll

Vanligtvis konfigurerar du enheter för att utföra åtgärder i taget som minimerar avbrott och stilleståndstid. Fönster för enhetsunderhåll är ett vanligt mönster för att definiera den tid då en enhet ska uppdatera sin konfiguration. Serverdelslösningarna kan använda önskade egenskaper för enhetstvillingen för att definiera och aktivera en princip på enheten som aktiverar ett underhållsperiod. När en enhet tar emot principen för underhållsperiod kan den använda den rapporterade egenskapen för enhetstvillingen för att rapportera status för principen. Serverdelsappen kan sedan använda enhetstvillingfrågor för att intyga efterlevnad av enheter och varje princip.

Nästa steg

I den här artikeln använde du en direktmetod för att utlösa en fjärromstart på en enhet. Du använde de rapporterade egenskaperna för att rapportera den senaste omstartstiden från enheten och frågade enhetstvillingen om att identifiera enhetens senaste omstartstid från molnet.

För att fortsätta komma igång med IoT Hub- och enhetshanteringsmönster, till exempel avbildningsbaserad uppdatering från slutpunkt till slutpunkt i artikeln Enhetsuppdatering för Azure IoT Hub med hjälp av raspberry Pi 3 B+-referensbilden.

Information om hur du utökar IoT-lösnings- och schemametodanrop på flera enheter finns i Schemalägga och sända jobb.

Dela via