Usare metodi diretti (Java)

L'hub IoT di Azure è un servizio completamente gestito che consente comunicazioni bidirezionali affidabili e sicure tra milioni di dispositivi e un back-end della soluzione. Le esercitazioni precedenti, ad esempio Introduzione all'hub IoT e Inviare messaggi da cloud a dispositivo con l'hub IoT, illustrano le funzionalità di messaggistica di base da dispositivo a cloud e da cloud a dispositivo dell'hub IoT. L'hub IoT offre inoltre la possibilità di richiamare metodi non durevoli dal cloud ai dispositivi. I metodi diretti rappresentano un'interazione di tipo richiesta-risposta con un dispositivo simile a una chiamata HTTP, perché dopo il timeout specificato dall'utente l'esito positivo o negativo viene comunicato immediatamente per far conoscere all'utente lo stato della chiamata. Richiamare un metodo diretto in un dispositivo descrive in maniera dettagliata i metodi diretti e illustra quando usarli in alternativa ai messaggi da cloud a dispositivo o alle proprietà desiderate.

Questa esercitazione illustra come:

  • Creare un hub IoT nel portale di Azure e un'identità del dispositivo nell'hub IoT.
  • Creare un'app per dispositivo simulato che ha un metodo diretto che può essere chiamato dal cloud.
  • Creare un'app console che chiama un metodo diretto nell'app per dispositivo simulato tramite l'hub IoT.
Nota

Al momento i metodi diretti sono supportati solo sui dispositivi che si connettono all'hub IoT usando il protocollo MQTT. Per istruzioni su come convertire l'app per dispositivo esistente in modo che usi MQTT, vedere l'articolo Supporto di MQTT.

In questa esercitazione vengono create due app console Java:

  • invoke-direct-method, un'app back-end Java che chiama un metodo nell'app per dispositivo simulato e visualizza la risposta.
  • simulated-device, un'app Java che simula la connessione di un dispositivo all'hub IoT con l'identità del dispositivo creata. Questa app risponde al metodo diretto richiamato dal back-end.
Nota

Per informazioni sugli SDK che consentono di compilare le applicazioni da eseguire nei dispositivi e i back-end della soluzione, vedere Azure IoT SDK.

Per completare questa esercitazione, sono necessari:

Creare un hub IoT

Creare un hub IoT per connettere l'app per dispositivo simulato. La procedura seguente illustra come completare questa attività usando il portale di Azure.

  1. Accedere al portale di Azure.
  2. Nell'indice fare clic su Nuovo > Internet delle cose > Hub IoT.

    Indice del portale di Azure

  3. Nel pannello Hub IoT scegliere la configurazione per l'hub IoT.

    Pannello Hub IoT

    1. Nella casella Nome immettere un nome per l'hub IoT. Se il Nome è valido e disponibile, appare un segno di spunta verde nella casella Nome.

      Importante

      L'hub IoT sarà individuabile pubblicamente come endpoint DNS, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.

    2. Selezionare un piano tariffario e un livello di scalabilità. Per questa esercitazione non è necessario un livello specifico. Per questa esercitazione, usare il livello F1 gratuito.

    3. In Gruppo di risorse creare un gruppo di risorse o selezionarne uno esistente. Per altre informazioni, vedere Using resource groups to manage your Azure resources (Uso di Gruppi di risorse per gestire le risorse di Azure).
    4. In Percorsoselezionare il percorso per ospitare l'hub IoT. Per questa esercitazione, scegliere la località più vicina.
  4. Dopo aver scelto le opzioni di configurazione dell'hub IoT, fare clic su Crea. La creazione dell'hub IoT da parte di Azure può richiedere alcuni minuti. Per verificare lo stato, è possibile monitorare l'avanzamento nella Schermata iniziale o nel pannello Notifiche.

    Stato del nuovo hub IoT

  5. Dopo avere creato l'hub IoT, fare clic sul nuovo riquadro per l'hub IoT nel portale di Azure per aprire il pannello del nuovo hub IoT. Annotare il Nome host, quindi fare clic su Criteri di accesso condiviso.

    Pannello del nuovo hub IoT

  6. Nel pannello Criteri di accesso condivisi fare clic sul criterio iothubowner, quindi copiare e annotare la stringa di connessione dell'hub IoT nel pannello iothubowner. Per altre informazioni, vedere Controllo di accesso nella "Guida per gli sviluppatori dell'hub IoT".

    Pannello Criteri di accesso condivisi

Creare un'identità del dispositivo

In questa sezione si usa uno strumento di Node.js denominato iothub-explorer per creare un'identità del dispositivo per questa esercitazione. Gli ID dispositivo fanno distinzione tra maiuscole e minuscole.

  1. Eseguire il codice seguente nell'ambiente della riga di comando:

    npm install -g iothub-explorer@latest

  2. Eseguire quindi il comando indicato di seguito per accedere all'hub. Sostituire {iot hub connection string} con la stringa di connessione all'hub IoT copiata prima:

    iothub-explorer login "{iot hub connection string}"

  3. Creare infine una nuova identità del dispositivo denominata myDeviceId con il comando:

    iothub-explorer create myDeviceId --connection-string

    Importante

    L'ID dispositivo può essere visibile nei log raccolti per il supporto tecnico e la risoluzione dei problemi, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.

Annotare la stringa di connessione del dispositivo visualizzata nei risultati. Questa stringa di connessione del dispositivo viene usata dall'app del dispositivo per la connessione all'hub IoT come dispositivo.

Per creare identità del dispositivo a livello di codice, vedere Introduzione all'hub IoT.

Creare un'app di dispositivo simulato

In questa sezione viene creata un'app console Java che risponde a un metodo chiamato dal back-end della soluzione.

  1. Creare una cartella vuota denominata iot-java-direct-method.

  2. Nella cartella iot-java-direct-method creare un progetto Maven denominato simulated-device usando il comando seguente al prompt dei comandi. Il comando seguente è un lungo comando singolo:

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

  3. Al prompt dei comandi passare alla cartella simulated-device.

  4. In un editor di testo aprire il file pom.xml nella cartella simulated-device e aggiungere le dipendenze seguenti al nodo dependencies . Questa dipendenza consente di usare il pacchetto iot-device-client nell'app per comunicare con l'hub IoT:

    <dependency>
      <groupId>com.microsoft.azure.sdk.iot</groupId>
      <artifactId>iot-device-client</artifactId>
      <version>1.3.32</version>
    </dependency>
    
    Nota

    È possibile cercare la versione più recente di iot-device-client usando la ricerca di Maven.

  5. Aggiungere il nodo build seguente dopo il nodo dependencies. Questa configurazione indica a Maven di usare Java 1.8 per compilare l'app:

    <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>
    
  6. Salvare e chiudere il file pom.xml.

  7. Usando un editor di testo, aprire il file simulated-device\src\main\java\com\mycompany\app\App.java.

  8. Aggiungere al file le istruzioni import seguenti:

    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;
    
  9. Aggiungere le variabili a livello di classe seguenti alla classe App . Sostituzione di {youriothubname} con il nome dell'hub IoT e di {yourdevicekey} con il valore della chiave del dispositivo generato nella sezione Creare un'identità del dispositivo:

    private static String connString = "HostName={youriothubname}.azure-devices.net;DeviceId=myDeviceID;SharedAccessKey={yourdevicekey}";
    private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
    private static String deviceId = "myDeviceId";
    private static final int METHOD_SUCCESS = 200;
    private static final int METHOD_NOT_DEFINED = 404;
    

    Questa app di esempio usa la variabile protocol quando crea un'istanza di un oggetto DeviceClient. Attualmente per usare i metodi diretti è necessario usare il protocollo MQTT.

  10. Per restituire un codice di stato all'hub IoT, aggiungere la classe annidata seguente alla classe 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());
      }
    }
    
  11. Per gestire le chiamate al metodo diretto dal back-end della soluzione, aggiungere la classe annidata seguente alla classe App:

    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 "writeLine" :
          {
            int status = METHOD_SUCCESS;
            System.out.println(new String((byte[])methodData));
            deviceMethodData = new DeviceMethodData(status, "Executed direct method " + methodName);
            break;
          }
          default:
          {
            int status = METHOD_NOT_DEFINED;
            deviceMethodData = new DeviceMethodData(status, "Not defined direct method " + methodName);
          }
        }
        return deviceMethodData;
      }
    }
    
  12. Per creare un DeviceClient e rimanere in ascolto delle chiamate al metodo diretto, aggiungere un metodo main alla classe App:

    public static void main(String[] args)
      throws IOException, URISyntaxException
    {
      System.out.println("Starting device sample...");
    
      DeviceClient client = new DeviceClient(connString, protocol);
    
      try
      {
        client.open();
        client.subscribeToDeviceMethod(new DirectMethodCallback(), null, new DirectMethodStatusCallback(), null);
        System.out.println("Subscribed to direct methods. 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...");
      }
    
      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...");
    }
    
  13. Salvare e chiudere il file simulated-device\src\main\java\com\mycompany\app\App.java.

  14. Compilare l'app simulated-device e correggere eventuali errori. Al prompt dei comandi passare alla cartella simulated-device ed eseguire il comando seguente:

    mvn clean package -DskipTests

Chiamare un metodo diretto in un dispositivo

In questa sezione viene creata un'app console Java che richiama un metodo diretto e quindi visualizza la risposta. Quest'app console si connette all'hub IoT per richiamare il metodo diretto.

  1. Nella cartella iot-java-direct-method creare un progetto Maven denominato invoke-direct-method usando il comando seguente al prompt dei comandi. Il comando seguente è un lungo comando singolo:

    mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=invoke-direct-method -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

  2. Al prompt dei comandi passare alla cartella invoke-direct-method.

  3. In un editor di testo aprire il file pom.xml nella cartella invoke-direct-method e aggiungere la dipendenza seguente al nodo dependencies. Questa dipendenza consente di usare il pacchetto iot-service-client nell'app per comunicare con l'hub IoT:

    <dependency>
      <groupId>com.microsoft.azure.sdk.iot</groupId>
      <artifactId>iot-service-client</artifactId>
      <version>1.7.23</version>
      <type>jar</type>
    </dependency>
    
    Nota

    È possibile cercare la versione più recente di iot-service-client usando la ricerca di Maven.

  4. Aggiungere il nodo build seguente dopo il nodo dependencies. Questa configurazione indica a Maven di usare Java 1.8 per compilare l'app:

    <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>
    
  5. Salvare e chiudere il file pom.xml.

  6. In un editor di testo aprire il file invoke-direct-method\src\main\java\com\mycompany\app\App.java.

  7. Aggiungere al file le istruzioni import seguenti:

    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 java.io.IOException;
    import java.util.concurrent.TimeUnit;
    
  8. Aggiungere le variabili a livello di classe seguenti alla classe App . Sostituire {youriothubconnectionstring} con la stringa di connessione dell'hub IoT indicata nella sezione Creare un hub IoT:

    public static final String iotHubConnectionString = "{youriothubconnectionstring}";
    public static final String deviceId = "myDeviceId";
    
    public static final String methodName = "writeLine";
    public static final Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
    public static final Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);
    public static final String payload = "a line to be written";
    
  9. Per richiamare il metodo sul dispositivo simulato, aggiungere il codice seguente al metodo main:

    System.out.println("Starting sample...");
    DeviceMethod methodClient = DeviceMethod.createFromConnectionString(iotHubConnectionString);
    
    try
    {
        System.out.println("Invoke direct method");
        MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
    
        if(result == null)
        {
            throw new IOException("Direct method invoke returns null");
        }
        System.out.println("Status=" + result.getStatus());
        System.out.println("Payload=" + result.getPayload());
    }
    catch (IotHubException e)
    {
        System.out.println(e.getMessage());
    }
    
    System.out.println("Shutting down sample...");
    
  10. Salvare e chiudere il file invoke-direct-method\src\main\java\com\mycompany\app\App.java

  11. Compilare l'app invoke-direct-method e correggere eventuali errori. Al prompt dei comandi passare alla cartella invoke-direct-method ed eseguire il comando seguente:

    mvn clean package -DskipTests

Eseguire le app

A questo punto è possibile eseguire le app console.

  1. Eseguire questo comando al prompt dei comandi nella cartella simulated-device per iniziare ad ascoltare le chiamate ai metodi dell'hub IoT:

    mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

    App del dispositivo simulato dell'hub IoT per Java per ascoltare le chiamate al metodo diretto

  2. Eseguire questo comando al prompt dei comandi nella cartella invoke-direct-method per chiamare un metodo sul dispositivo simulato dell'hub IoT:

    mvn exec:java -Dexec.mainClass="com.mycompany.app.App"

    App del servizio hub IoT per Java per chiamare un metodo diretto

  3. Il dispositivo simulato risponde alla chiamata al metodo diretto:

    L'app del dispositivo simulato dell'hub IoT per Java risponde alla chiamata al metodo diretto

Passaggi successivi

In questa esercitazione è stato configurato un nuovo hub IoT nel Portale di Azure ed è stata quindi creata un'identità del dispositivo nel registro di identità dell'hub IoT. Questa identità del dispositivo è stata usata per consentire all'app del dispositivo simulato di reagire ai metodi richiamati dal cloud. È stata anche creata un'applicazione che richiama i metodi sul dispositivo e visualizza la risposta dal dispositivo.

Per esplorare altri scenari IoT, vedere Pianificare processi in più dispositivi.

Per informazioni su come estendere la soluzione IoT e pianificare le chiamate al metodo su più dispositivi, vedere l'esercitazione Pianificare e trasmettere processi.