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 the 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 è utile per gli scenari in cui la linea di condotta immediata è diversa a seconda che il dispositivo sia in grado di rispondere o meno,This approach is useful for scenarios where the course of immediate action is different depending on whether the device was able to respond.

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT.The features described in this article are only available in the standard tier of IoT hub. Per altre informazioni sui livelli Basic e Standard dell'hub IoT, vedere come scegliere il livello corretto dell'hub IoT.For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

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,Direct methods follow a request-response pattern and are meant for communications that require immediate confirmation of their result. ad esempio il controllo interattivo del dispositivo, come l'accensione di un ventilatore.For example, interactive control of the device, such as turning 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/). Un dispositivo riceve metodi diretti tramite un argomento MQTT specifico del dispositivo ($iothub/methods/POST/{method name}/) o tramite collegamenti AMQP (proprietà IoThub-methodname e IoThub-status dell'applicazione).A device receives direct methods through a device-specific MQTT topic ($iothub/methods/POST/{method name}/) or through AMQP links (IoThub-methodname and IoThub-status application properties).

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,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. ad esempio nel caso dell'accensione di una luce da un telefono.For example, 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 128 KB.The payload for method requests and responses is a JSON document up to 128 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.

RispostaResponse

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.

Chiamata al metodo per i moduli di IoT EdgeMethod invocation for IoT Edge modules

La chiamata a metodi diretti tramite un ID modulo è supportata nella versione di anteprima dell'SDK per C# (disponibile qui).Invoking direct methods using a module ID is supported in the C# preview SDK (available here).

A tale scopo, usare il metodo ServiceClient.InvokeDeviceMethodAsync() e passare deviceId e moduleId come parametri.For this purpose, use the ServiceClient.InvokeDeviceMethodAsync() method and pass in the deviceId and moduleId as parameters.

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

MQTTMQTT

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.

RispostaResponse

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.

AMQPAMQP

Chiamata al metodoMethod invocation

Il dispositivo riceve richieste di metodi diretti tramite la creazione di un collegamento di ricezione sull'indirizzo amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBoundThe device receives direct method requests by creating a receive link on address amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound

Il messaggio AMQP arriva sul collegamento di ricezione che rappresenta la richiesta del metodo.The AMQP message arrives on the receive link that represents the method request. Tale messaggio contiene quanto segue:It contains the following:

  • La proprietà ID di correlazione, contenente un ID richiesta che deve essere passato con la relativa risposta del metodoThe correlation ID property, which contains a request ID that should be passed back with the corresponding method response
  • Una proprietà dell'applicazione denominata IoThub-methodname, contenente il nome del metodo richiamatoAn application property named IoThub-methodname, which contains the name of the method being invoked
  • Il corpo del messaggio AMQP, contenente il payload del metodo in formato JSONThe AMQP message body containing the method payload as JSON

RispostaResponse

Il dispositivo crea un collegamento di invio per restituire la risposta del metodo all'indirizzo amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBoundThe device creates a sending link to return the method response on address amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound

La risposta del metodo viene restituita sul collegamento di invio e contiene gli elementi seguenti:The method’s response is returned on the sending link and is structured as follows:

  • La proprietà ID di correlazione, contenente l'ID richiesta passato nel messaggio di richiesta del metodoThe correlation ID property, which contains the request ID passed in the method’s request message
  • Una proprietà dell'applicazione denominata IoThub-status, contenente lo stato del metodo fornito dall'utenteAn application property named IoThub-status, which contains the user supplied method status
  • Il corpo del messaggio AMQP, contenente la risposta del metodo in formato JSONThe AMQP message body containing the method response as JSON

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: