Usare i metodi diretti sul dispositivo IoT con Node. jsUse direct methods on your IoT device with Node.js

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.

Al termine di questa esercitazione si avranno due app console Node.js:At the end of this tutorial, you have two Node.js console apps:

  • CallMethodOnDevice.js, che chiama un metodo nell'app per dispositivo simulato e visualizza la risposta.CallMethodOnDevice.js, which calls a method in the simulated device app and displays the response.
  • SimulatedDevice.js, che si connette all'hub IoT con l'identità del dispositivo creata in precedenza e risponde al metodo chiamato dal cloud.SimulatedDevice.js, which connects to your IoT hub with the device identity created earlier, and responds to the method called by the cloud.

Nota

L'articolo Azure IoT SDK offre informazioni sui vari Azure IoT SDK che è possibile usare per compilare applicazioni da eseguire nei dispositivi e il backend della soluzione.The article Azure IoT SDKs provides information about the Azure IoT SDKs that you can use to build both applications to run on devices and your solution back end.

Per completare l'esercitazione, sono necessari gli elementi seguenti:To complete this tutorial, you need the following:

  • Node.js 4.0.x o versione successiva.Node.js version 4.0.x or later.
  • Un account Azure attivo.An active Azure account. Se non si ha un account, è possibile creare un account gratuito in pochi minuti.(If you don't have an account, you can create a free account in just a couple of minutes.)

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'applicazione console Node.js che risponde a un metodo chiamato dal cloud.In this section, you create a Node.js console app that responds to a method called by the cloud.

  1. Creare una nuova cartella vuota denominata simulateddevice.Create a new empty folder called simulateddevice. Nella cartella simulateddevice creare un file package.json eseguendo questo comando al prompt dei comandi.In the simulateddevice folder, create a package.json file using the following command at your command prompt. Accettare tutte le impostazioni predefinite:Accept all the defaults:

    npm init
    
  2. Eseguire questo comando al prompt dei comandi nella cartella simulateddevice per installare il pacchetto SDK per dispositivi azure-iot-device e il pacchetto azure-iot-device-mqtt:At your command prompt in the simulateddevice folder, run the following command to install the azure-iot-device Device SDK package and azure-iot-device-mqtt package:

    npm install azure-iot-device azure-iot-device-mqtt --save
    
  3. Con un editor di testo creare un nuovo file SimulatedDevice.js nella cartella simulateddevice.Using a text editor, create a new SimulatedDevice.js file in the simulateddevice folder.
  4. Aggiungere le istruzioni require seguenti all'inizio del file SimulatedDevice.js :Add the following require statements at the start of the SimulatedDevice.js file:

    'use strict';
    
    var Mqtt = require('azure-iot-device-mqtt').Mqtt;
    var DeviceClient = require('azure-iot-device').Client;
    
  5. Aggiungere una variabile connectionString e usarla per creare un'istanza di DeviceClient.Add a connectionString variable and use it to create a DeviceClient instance. Sostituire {device connection string} con la stringa di connessione del dispositivo generata nella sezione Creare un'identità del dispositivo:Replace {device connection string} with the device connection string you generated in the Create a device identity section:

    var connectionString = '{device connection string}';
    var client = DeviceClient.fromConnectionString(connectionString, Mqtt);
    
  6. Aggiungere la funzione seguente per implementare il metodo nel dispositivo:Add the following function to implement the method on the device:

    function onWriteLine(request, response) {
        console.log(request.payload);
    
        response.send(200, 'Input was written to log.', function(err) {
            if(err) {
                console.error('An error ocurred when sending a method response:\n' + err.toString());
            } else {
                console.log('Response to method \'' + request.methodName + '\' sent successfully.' );
            }
        });
    }
    
  7. Aprire la connessione all'hub IoT e inizializzare il listener del metodo:Open the connection to your IoT hub and start initialize the method listener:

    client.open(function(err) {
        if (err) {
            console.error('could not open IotHub client');
        }  else {
            console.log('client opened');
            client.onDeviceMethod('writeLine', onWriteLine);
        }
    });
    
  8. Salvare e chiudere il file SimulatedDevice.js .Save and close the SimulatedDevice.js file.

Nota

Per semplicità, in questa esercitazione non si implementa alcun criterio di ripetizione dei tentativi.To keep things simple, this tutorial does not implement any retry policy. Nel codice di produzione è consigliabile implementare criteri di ripetizione dei tentativi, ad esempio i tentativi di connessione, come indicato nell'articolo di MSDN Transient Fault Handling (Gestione degli errori temporanei).In production code, you should implement retry policies (such as connection retry), as suggested in the MSDN article Transient Fault Handling.

Chiamare un metodo su un dispositivoCall a method on a device

In questa sezione viene creata un'app console Node.js che chiama un metodo nell'app per dispositivo simulato e quindi visualizza la risposta.In this section, you create a Node.js console app that calls a method in the simulated device app and then displays the response.

  1. Creare una nuova cartella vuota denominata callmethodondevice.Create a new empty folder called callmethodondevice. Nella cartella callmethodondevice creare un file package.json eseguendo questo comando al prompt dei comandi.In the callmethodondevice folder, create a package.json file using the following command at your command prompt. Accettare tutte le impostazioni predefinite:Accept all the defaults:

    npm init
    
  2. Eseguire questo comando al prompt dei comandi nella cartella callmethodondevice per installare il pacchetto azure-iothub:At your command prompt in the callmethodondevice folder, run the following command to install the azure-iothub package:

    npm install azure-iothub --save
    
  3. Usando un editor di testo creare un file CallMethodOnDevice.js nella cartella callmethodondevice.Using a text editor, create a CallMethodOnDevice.js file in the callmethodondevice folder.
  4. Aggiungere le istruzioni require seguenti all'inizio del file CallMethodOnDevice.js:Add the following require statements at the start of the CallMethodOnDevice.js file:

    'use strict';
    
    var Client = require('azure-iothub').Client;
    
  5. Aggiungere la dichiarazione di variabile seguente e sostituire il valore del segnaposto con la stringa di connessione per l'hub IoT:Add the following variable declaration and replace the placeholder value with the IoT Hub connection string for your hub:

    var connectionString = '{iothub connection string}';
    var methodName = 'writeLine';
    var deviceId = 'myDeviceId';
    
  6. Creare il client per aprire la connessione all'hub IoT.Create the client to open the connection to your IoT hub.

    var client = Client.fromConnectionString(connectionString);
    
  7. Aggiungere la funzione seguente per richiamare il metodo del dispositivo e stampare la risposta del dispositivo nella console:Add the following function to invoke the device method and print the device response to the console:

    var methodParams = {
        methodName: methodName,
        payload: 'hello world',
        timeoutInSeconds: 30
    };
    
    client.invokeDeviceMethod(deviceId, methodParams, function (err, result) {
        if (err) {
            console.error('Failed to invoke method \'' + methodName + '\': ' + err.message);
        } else {
            console.log(methodName + ' on ' + deviceId + ':');
            console.log(JSON.stringify(result, null, 2));
        }
    });
    
  8. Salvare e chiudere il file CallMethodOnDevice.js.Save and close the CallMethodOnDevice.js file.

Eseguire le appRun the apps

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

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

    node SimulatedDevice.js
    

  2. Al prompt dei comandi nella cartella callmethodondevice eseguire questo comando per iniziare a monitorare l'hub IoT:At a command prompt in the callmethodondevice folder, run the following command to begin monitoring your IoT hub:

    node CallMethodOnDevice.js 
    

  3. Il dispositivo reagirà al metodo stampando il messaggio e l'applicazione che ha chiamato il metodo visualizzerà la risposta dal dispositivo:You will see the device react to the method by printing out the message and the application which called the method display the response from the device:

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 altre informazioni sulle attività iniziali con l'hub IoT e per esplorare altri scenari IoT, vedere:To continue getting started with IoT Hub and to explore other IoT scenarios, see:

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.