Usare metodi diretti (Java)Use direct methods (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.Azure IoT Hub is a fully managed service that enables reliable and secure bi-directional communications between millions of devices and a solution back end. 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.Previous tutorials ([Get started with IoT Hub] and [Send Cloud-to-Device messages with IoT Hub]) illustrate the basic device-to-cloud and cloud-to-device messaging functionality of IoT Hub. L'hub IoT offre inoltre la possibilità di richiamare metodi non durevoli dal cloud ai dispositivi.IoT Hub also gives you the ability to invoke non-durable methods on devices from the cloud. I metodi diretti rappresentano un'interazione di tipo richiesta-risposta con un dispositivo simile a una chiamata HTTPS, perché dopo il timeout specificato dall'utente l'esito positivo o negativo viene comunicato immediatamente per far conoscere all'utente lo stato della chiamata.Direct methods represent a request-reply interaction with a device similar to an HTTPS call in that they succeed or fail immediately (after a user-specified timeout) to let the user know the status of the call. 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.Invoke a direct method on a device describes direct methods in more detail and offers guidance about when to use direct methods rather than cloud-to-device messages or desired properties.

Questa esercitazione illustra come:This tutorial shows you how to:

  • Creare un hub IoT nel portale di Azure e un'identità del dispositivo nell'hub IoT.Use the Azure portal to create an IoT hub and create a device identity in your IoT hub.
  • Creare un'app per dispositivo simulato che ha un metodo diretto che può essere chiamato dal cloud.Create a simulated device app that has a direct method which can be called by the cloud.
  • Creare un'app console che chiama un metodo diretto nell'app per dispositivo simulato tramite l'hub IoT.Create a console app that calls a direct method in the simulated device app through your IoT hub.

In questa esercitazione vengono create due app console Java:In this tutorial, you create two Java console apps:

  • invoke-direct-method, un'app back-end Java che chiama un metodo nell'app per dispositivo simulato e visualizza la risposta.invoke-direct-method, a Java back-end app that calls a method in the simulated device app and displays the response.
  • simulated-device, un'app Java che simula la connessione di un dispositivo all'hub IoT con l'identità del dispositivo creata.simulated-device, a Java app that simulates a device connecting to your IoT hub with the device identity you create. Questa app risponde al metodo diretto richiamato dal back-end.This app responds to the direct invoked from the 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.For information about the SDKs that you can use to build applications to run on devices and your solution back end, see Azure IoT SDKs.

Per completare questa esercitazione, sono necessari:To complete this tutorial, you need:

Creare un hub IoTCreate an IoT hub

Creare un hub IoT per connettere l'app per dispositivo simulato.Create an IoT hub for your simulated device app to connect to. La procedura seguente illustra come completare questa attività usando il portale di Azure.The following steps show you how to complete this task by using the Azure portal.

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Selezionare Nuovo > Internet delle cose > Hub IoT.Select New > Internet of Things > IoT Hub.

    Indice del portale di Azure

  3. Nel riquadro Hub IoT immettere le informazioni seguenti per l'hub IoT:In the IoT hub pane, enter the following information for your IoT hub:

    • Nome: creare un nome per l'hub IoT.Name: Create a name for your IoT hub. Se il nome immesso è valido, viene visualizzato un segno di spunta verde.If the name you enter is valid, a green check mark appears.

    Importante

    L'hub IoT sarà individuabile pubblicamente come endpoint DNS, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.The IoT hub will be publicly discoverable as a DNS endpoint, so make sure to avoid any sensitive information while naming it.

    • Piano tariffario e livello di scalabilità: per questa esercitazione selezionare il livello F1 gratuito.Pricing and scale tier: For this tutorial, select the F1 - Free tier. Per altre informazioni, vedere la pagina relativa a piano tariffario e livello di scalabilità.For more information, see the Pricing and scale tier.

    • Gruppo di risorse: creare un gruppo di risorse per ospitare l'hub IoT o usarne uno esistente.Resource group: Create a resource group to host the IoT hub or use an existing one. Per altre informazioni, vedere l'articolo su come usare i gruppi di risorse per gestire le risorse di Azure.For more information, see Use resource groups to manage your Azure resources

    • Località: selezionare la località più vicina.Location: Select the closest location to you.

    • Aggiungi al dashboard: selezionare questa opzione per semplificare l'accesso all'hub IoT dal dashboard.Pin to dashboard: Check this option for easy access to your IoT hub from the dashboard.

      Finestra Hub IoT

  4. Fare clic su Crea.Click Create. La creazione dell'hub IoT può richiedere alcuni minuti.Your IoT hub might take a few minutes to create. È possibile monitorare lo stato di avanzamento nel riquadro Notifiche.You can monitor the progress in the Notifications pane.

Ora che è stato creato un hub IoT, individuare le informazioni importanti che consentono di connettere dispositivi e applicazioni all'hub IoT.Now that you have created an IoT hub, locate the important information that you use to connect devices and applications to your IoT hub.

  1. Dopo avere creato l'hub IoT, fare clic sul nuovo riquadro dell'hub IoT nel portale di Azure per aprire la finestra delle proprietà.When the IoT hub has been created successfully, click the new tile for your IoT hub in the Azure portal to open the properties window for the new IoT hub. Annotare il Nome host, quindi fare clic su Criteri di accesso condiviso.Make a note of the Hostname, and then click Shared access policies.

    Finestra del nuovo hub IoT

  2. In Criteri di accesso condivisi fare clic sul criterio iothubowner, quindi copiare e annotare la stringa di connessione dell'hub IoT nella finestra iothubowner.In Shared access policies, click the iothubowner policy, and then copy and make note of the IoT Hub connection string in the iothubowner window. Per altre informazioni, vedere Controllo di accesso nella "Guida per gli sviluppatori dell'hub IoT".For more information, see Access control in the "IoT Hub developer guide."

    Criteri di accesso condivisi

Creare un'identità del dispositivoCreate a device identity

In questa sezione si usa uno strumento di Node.js denominato iothub-explorer per creare un'identità del dispositivo per questa esercitazione.In this section, you use a Node.js tool called iothub-explorer to create a device identity for this tutorial. Gli ID dispositivo fanno distinzione tra maiuscole e minuscole.Device IDs are case sensitive.

  1. Eseguire il codice seguente nell'ambiente della riga di comando:Run the following in your command-line environment:

    npm install -g iothub-explorer@latest

  2. Eseguire quindi il comando indicato di seguito per accedere all'hub.Then, run the following command to login to your hub. Sostituire {iot hub connection string} con la stringa di connessione all'hub IoT copiata prima:Substitute {iot hub connection string} with the IoT Hub connection string you previously copied:

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

  3. Creare infine una nuova identità del dispositivo denominata myDeviceId con il comando:Finally, create a new device identity called myDeviceId with the command:

    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.The device ID may be visible in the logs collected for customer support and troubleshooting, so make sure to avoid any sensitive information while naming it.

Annotare la stringa di connessione del dispositivo visualizzata nei risultati.Make a note of the device connection string from the result. Questa stringa di connessione del dispositivo viene usata dall'app del dispositivo per la connessione all'hub IoT come dispositivo.This device connection string is used by the device app to connect to your IoT Hub as a device.

Per creare identità del dispositivo a livello di codice, vedere Introduzione all'hub IoT.Refer to Getting started with IoT Hub to programmatically create device identities.

Creare un'app di dispositivo simulatoCreate a simulated device app

In questa sezione viene creata un'app console Java che risponde a un metodo chiamato dal back-end della soluzione.In this section, you create a Java console app that responds to a method called by the solution back end.

  1. Creare una cartella vuota denominata iot-java-direct-method.Create an empty folder called 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.In the iot-java-direct-method folder, create a Maven project called simulated-device using the following command at your command prompt. Il comando seguente è un lungo comando singolo:The following command is a single, long command:

    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.At your command prompt, navigate to the simulated-device folder.

  4. In un editor di testo aprire il file pom.xml nella cartella simulated-device e aggiungere le dipendenze seguenti al nodo dependencies .Using a text editor, open the pom.xml file in the simulated-device folder and add the following dependencies to the dependencies node. Questa dipendenza consente di usare il pacchetto iot-device-client nell'app per comunicare con l'hub IoT:This dependency enables you to use the iot-device-client package in your app to communicate with your IoT hub:

    <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.You can check for the latest version of iot-device-client using Maven search.

  5. Aggiungere il nodo build seguente dopo il nodo dependencies.Add the following build node after the dependencies node. Questa configurazione indica a Maven di usare Java 1.8 per compilare l'app:This configuration instructs Maven to use Java 1.8 to build the 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.Save and close the pom.xml file.

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

  8. Aggiungere al file le istruzioni import seguenti:Add the following import statements to the file:

    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 .Add the following class-level variables to the App class. 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:Replacing {youriothubname} with your IoT hub name, and {yourdevicekey} with the device key value you generated in the Create a device identity section:

    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.This sample app uses the protocol variable when it instantiates a DeviceClient object.

  10. Per restituire un codice di stato all'hub IoT, aggiungere la classe annidata seguente alla classe App:To return a status code to your IoT hub, add the following nested class to the App class:

    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:To handle the direct method invocations from the solution back end, add the following nested class to the App class:

    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:To create a DeviceClient and listen for direct method invocations, add a main method to the App class:

    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.Save and close the simulated-device\src\main\java\com\mycompany\app\App.java file

  14. Compilare l'app simulated-device e correggere eventuali errori.Build the simulated-device app and correct any errors. Al prompt dei comandi passare alla cartella simulated-device ed eseguire il comando seguente:At your command prompt, navigate to the simulated-device folder and run the following command:

    mvn clean package -DskipTests

Chiamare un metodo diretto in un dispositivoCall a direct method on a device

In questa sezione viene creata un'app console Java che richiama un metodo diretto e quindi visualizza la risposta.In this section, you create a Java console app that invokes a direct method and then displays the response. Quest'app console si connette all'hub IoT per richiamare il metodo diretto.This console app connects to your IoT Hub to invoke the direct method.

  1. Nella cartella iot-java-direct-method creare un progetto Maven denominato invoke-direct-method usando il comando seguente al prompt dei comandi.In the iot-java-direct-method folder, create a Maven project called invoke-direct-method using the following command at your command prompt. Il comando seguente è un lungo comando singolo:The following command is a single, long command:

    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.At your command prompt, navigate to the invoke-direct-method folder.

  3. In un editor di testo aprire il file pom.xml nella cartella invoke-direct-method e aggiungere la dipendenza seguente al nodo dependencies.Using a text editor, open the pom.xml file in the invoke-direct-method folder and add the following dependency to the dependencies node. Questa dipendenza consente di usare il pacchetto iot-service-client nell'app per comunicare con l'hub IoT:This dependency enables you to use the iot-service-client package in your app to communicate with your IoT hub:

    <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.You can check for the latest version of iot-service-client using Maven search.

  4. Aggiungere il nodo build seguente dopo il nodo dependencies.Add the following build node after the dependencies node. Questa configurazione indica a Maven di usare Java 1.8 per compilare l'app:This configuration instructs Maven to use Java 1.8 to build the 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.Save and close the pom.xml file.

  6. In un editor di testo aprire il file invoke-direct-method\src\main\java\com\mycompany\app\App.java.Using a text editor, open the invoke-direct-method\src\main\java\com\mycompany\app\App.java file.

  7. Aggiungere al file le istruzioni import seguenti:Add the following import statements to the file:

    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 .Add the following class-level variables to the App class. Sostituire {youriothubconnectionstring} con la stringa di connessione dell'hub IoT indicata nella sezione Creare un hub IoT:Replace {youriothubconnectionstring} with your IoT hub connection string you noted in the Create an IoT Hub section:

    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:To invoke the method on the simulated device, add the following code to the main method:

    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.javaSave and close the invoke-direct-method\src\main\java\com\mycompany\app\App.java file

  11. Compilare l'app invoke-direct-method e correggere eventuali errori.Build the invoke-direct-method app and correct any errors. Al prompt dei comandi passare alla cartella invoke-direct-method ed eseguire il comando seguente:At your command prompt, navigate to the invoke-direct-method folder and run the following command:

    mvn clean package -DskipTests

Eseguire le appRun the apps

A questo punto è possibile eseguire le app console.You are now ready to run the console apps.

  1. Eseguire questo comando al prompt dei comandi nella cartella simulated-device per iniziare ad ascoltare le chiamate ai metodi dell'hub IoT:At a command prompt in the simulated-device folder, run the following command to begin listening for method calls from your IoT hub:

    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:At a command prompt in the invoke-direct-method folder, run the following command to call a method on your simulated device from your IoT hub:

    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:The simulated device responds to the direct method call:

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

Passaggi successiviNext steps

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.In this tutorial, you configured a new IoT hub in the Azure portal, and then created a device identity in the IoT hub's identity registry. Questa identità del dispositivo è stata usata per consentire all'app del dispositivo simulato di reagire ai metodi richiamati dal cloud.You used this device identity to enable the simulated device app to react to methods invoked by the cloud. È stata anche creata un'applicazione che richiama i metodi sul dispositivo e visualizza la risposta dal dispositivo.You also created an app that invokes methods on the device and displays the response from the device.

Per esplorare altri scenari IoT, vedere Pianificare processi in più dispositivi.To explore other IoT scenarios, see Schedule jobs on multiple devices.

Per informazioni su come estendere la soluzione IoT e pianificare le chiamate al metodo su più dispositivi, vedere l'esercitazione Pianificare e trasmettere processi.To learn how to extend your IoT solution and schedule method calls on multiple devices, see the Schedule and broadcast jobs tutorial.