Comprendere e richiamare metodi diretti dall'hub IoTUnderstand and invoke direct methods from IoT Hub

L'hub IoT offre la possibilità di richiamare metodi diretti nei dispositivi dal cloud.IoT Hub gives you ability to invoke direct methods on devices from the cloud. I metodi diretti rappresentano un'interazione di tipo richiesta-risposta con un dispositivo simile a una chiamata HTTP, dato che dopo il timeout specificato dall'utente l'esito positivo o negativo viene comunicato immediatamente.Direct methods represent a request-reply interaction with a device similar to an HTTP call in that they succeed or fail immediately (after a user-specified timeout). Questo approccio risulta utile in scenari in cui l'azione immediata da intraprendere varia a seconda che il dispositivo sia riuscito o meno a rispondere. Un esempio è rappresentato dall'invio di un SMS di riattivazione a un dispositivo offline, in cui l'invio di un SMS ha un costo maggiore rispetto a una chiamata a un metodo.This approach is useful for scenarios where the course of immediate action is different depending on whether the device was able to respond, such as sending an SMS wake-up to a device if a device is offline (SMS being more expensive than a method call).

Ogni metodo del dispositivo è destinato a un unico dispositivo.Each device method targets a single device. I processi permettono di richiamare i metodi diretti in più dispositivi e di pianificare la chiamata al metodo per i dispositivi disconnessi.Jobs provide a way to invoke direct methods on multiple devices, and schedule method invocation for disconnected devices.

Chiunque abbia autorizzazioni di connessione servizio per l'hub IoT può richiamare un metodo in un dispositivo.Anyone with service connect permissions on IoT Hub may invoke a method on a device.

I metodi diretti si basano su un modello di tipo richiesta- risposta e sono destinati a comunicazioni che necessitano di una conferma immediata del risultato, in genere per il controllo interattivo del dispositivo, ad esempio l'accensione di un ventilatore.Direct methods follow a request-response pattern and are meant for communications that require immediate confirmation of their result, usually interactive control of the device, for example to turn on a fan.

Vedere Cloud-to-device communication guidance (Indicazioni sulla comunicazione da cloud a dispositivo) in caso di dubbi tra l'uso delle proprietà specifiche, dei metodi diretti o dei messaggi da cloud a dispositivo.Refer to Cloud-to-device communication guidance if in doubt between using desired properties, direct methods, or cloud-to-device messages.

Ciclo di vita dei metodiMethod lifecycle

I metodi diretti vengono implementati nel dispositivo. Per creare correttamente un'istanza possono essere necessari zero o più input nel payload del metodo.Direct methods are implemented on the device and may require zero or more inputs in the method payload to correctly instantiate. Per richiamare un metodo diretto è possibile usare un URI per il servizio ({iot hub}/twins/{device id}/methods/).You invoke a direct method through a service-facing URI ({iot hub}/twins/{device id}/methods/). Il dispositivo riceve i metodi diretti tramite un argomento MQTT specifico del dispositivo ($iothub/methods/POST/{method name}/).A device receives direct methods through a device-specific MQTT topic ($iothub/methods/POST/{method name}/). In futuro potranno essere supportati metodi diretti su altri protocolli di rete sul lato dispositivo.We may support direct methods on additional device-side networking protocols in the future.

Nota

Quando si richiama un metodo diretto in un dispositivo, i valori e i nomi di proprietà possono contenere solo caratteri alfanumerici stampabili US-ASCII, ad eccezione dei seguenti: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}.When you invoke a direct method on a device, property names and values can only contain US-ASCII printable alphanumeric, except any in the following set: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}.

I metodi diretti sono sincroni e possono solo avere esito positivo o negativo dopo il periodo di timeout. Il valore predefinito è 30 secondi, ma il valore massimo impostabile è 3600 secondi.Direct methods are synchronous and either succeed or fail after the timeout period (default: 30 seconds, settable up to 3600 seconds). Risultano utili negli scenari interattivi in cui si vuole che il dispositivo agisca esclusivamente se è online e riceve comandi, ad esempio nel caso dell'accensione di una luce da un telefono.Direct methods are useful in interactive scenarios where you want a device to act if and only if the device is online and receiving commands, such as turning on a light from a phone. In questi scenari l'esito positivo o negativo deve essere immediato, in modo che il servizio cloud possa agire in base al risultato il prima possibile.In these scenarios, you want to see an immediate success or failure so the cloud service can act on the result as soon as possible. Il dispositivo può restituire un corpo del messaggio come risultato del metodo, ma non è necessario che il metodo esegua questa operazione.The device may return some message body as a result of the method, but it isn't required for the method to do so. Nelle chiamate ai metodi non esiste alcuna garanzia di ordinamento o semantica di concorrenza.There is no guarantee on ordering or any concurrency semantics on method calls.

I metodi diretti supportano solo HTTPS lato cloud e solo MQTT o AMQP lato dispositivo.Direct methods are HTTPS-only from the cloud side, and MQTT or AMQP from the device side.

Il payload per le richieste e le risposte del metodo è un documento JSON con dimensioni massime di 8 KB.The payload for method requests and responses is a JSON document up to 8 KB.

Richiamare un metodo diretto da un'app back-endInvoke a direct method from a back-end app

Chiamata al metodoMethod invocation

Le chiamate a metodi diretti in un dispositivo sono chiamate HTTPS che includono:Direct method invocations on a device are HTTPS calls that comprise:

  • URI specifico del dispositivo ({iot hub}/twins/{device id}/methods/)The URI specific to the device ({iot hub}/twins/{device id}/methods/)
  • Metodo POSTThe POST method
  • Intestazioni contenenti l'autorizzazione, l'ID richiesta, il tipo di contenuto e la codifica del contenutoHeaders that contain the authorization, request ID, content type, and content encoding
  • Corpo JSON trasparente nel formato seguente:A transparent JSON body in the following format:

    {
        "methodName": "reboot",
        "responseTimeoutInSeconds": 200,
        "payload": {
            "input1": "someInput",
            "input2": "anotherInput"
        }
    }
    

Il timeout è espresso in secondi.Timeout is in seconds. Se il timeout non è impostato, il valore predefinito è 30 secondi.If timeout is not set, it defaults to 30 seconds.

ResponseResponse

L'app back-end riceve una risposta che include:The back-end app receives a response that comprises:

  • Codice di stato HTTP, usato per errori provenienti dall'hub IoT, incluso un errore 404 per i dispositivi attualmente non connessiHTTP status code, which is used for errors coming from the IoT Hub, including a 404 error for devices not currently connected
  • Intestazioni contenenti l'ETag, l'ID richiesta, il tipo di contenuto e la codifica del contenutoHeaders that contain the ETag, request ID, content type, and content encoding
  • Corpo JSON nel formato seguente:A JSON body in the following format:

    {
        "status" : 201,
        "payload" : {...}
    }
    

    Sia status che body vengono forniti dal dispositivo e usati per rispondere con la descrizione e/o il codice di stato del dispositivo.Both status and body are provided by the device and used to respond with the device's own status code and/or description.

Gestire un metodo diretto in un dispositivoHandle a direct method on a device

Chiamata al metodoMethod invocation

I dispositivi ricevono richieste di metodi diretti nell'argomento MQTT: $iothub/methods/POST/{method name}/?$rid={request id}Devices receive direct method requests on the MQTT topic: $iothub/methods/POST/{method name}/?$rid={request id}

Il corpo ricevuto dal dispositivo è nel formato seguente:The body that the device receives is in the following format:

{
    "input1": "someInput",
    "input2": "anotherInput"
}

Le richieste di metodo sono QoS 0.Method requests are QoS 0.

ResponseResponse

Il dispositivo invia risposte a $iothub/methods/res/{status}/?$rid={request id}, in cui:The device sends responses to $iothub/methods/res/{status}/?$rid={request id}, where:

  • La proprietà status è lo stato di esecuzione del metodo fornito dal dispositivo.The status property is the device-supplied status of method execution.
  • La proprietà $rid è l'ID richiesta della chiamata al metodo ricevuta dall'hub IoT.The $rid property is the request ID from the method invocation received from IoT Hub.

Il corpo è impostato dal dispositivo e accetta qualsiasi stato.The body is set by the device and can be any status.

Materiale di riferimentoAdditional reference material

Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:Other reference topics in the IoT Hub developer guide include:

Passaggi successiviNext steps

Ora che si è appreso come usare i metodi diretti, è possibile vedere un altro articolo di interesse della Guida per sviluppatori dell'hub IoT:Now you have learned how to use direct methods, you may be interested in the following IoT Hub developer guide article:

Per provare alcuni dei concetti descritti in questo articolo, può essere utile l'esercitazione seguente sull'hub IoT:If you would like to try out some of the concepts described in this article, you may be interested in the following IoT Hub tutorial: