Comprendere e richiamare metodi diretti dall'hub IoT

Panoramica

L'hub IoT offre la possibilità di richiamare metodi diretti nei dispositivi dal 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. Questo 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.

Ogni metodo del dispositivo è destinato a un unico dispositivo. I processi permettono di richiamare i metodi diretti in più dispositivi e di pianificare la chiamata al metodo per i dispositivi disconnessi.

Chiunque abbia autorizzazioni di connessione servizio per l'hub IoT può richiamare un metodo in un dispositivo.

Quando usare le autorizzazioni

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.

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.

Ciclo di vita dei metodi

I metodi diretti vengono implementati nel dispositivo. Per creare correttamente un'istanza possono essere necessari zero o più input nel payload del metodo. Per richiamare un metodo diretto è possibile usare un URI per il servizio ({iot hub}/twins/{device id}/methods/). Il dispositivo riceve i metodi diretti tramite un argomento MQTT specifico del dispositivo ($iothub/methods/POST/{method name}/). In futuro potranno essere supportati metodi diretti su altri protocolli di rete sul lato dispositivo.

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}.

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. 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. 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. Il dispositivo può restituire un corpo del messaggio come risultato del metodo, ma non è necessario che il metodo esegua questa operazione. Nelle chiamate ai metodi non esiste alcuna garanzia di ordinamento o semantica di concorrenza.

I metodi diretti supportano solo HTTP lato cloud e solo MQTT o AMQP lato dispositivo.

Il payload per le richieste e le risposte del metodo è un documento JSON con dimensioni massime di 8 KB.

Argomenti di riferimento:

Gli argomenti di riferimento seguenti offrono altre informazioni sull'uso dei metodi diretti.

Richiamare un metodo diretto da un'app back-end

Chiamata al metodo

Le chiamate a metodi diretti in un dispositivo sono chiamate HTTP e includono:

  • URI specifico del dispositivo ({iot hub}/twins/{device id}/methods/)
  • Metodo POST
  • Intestazioni contenenti l'autorizzazione, l'ID richiesta, il tipo di contenuto e la codifica del contenuto
  • Corpo JSON trasparente nel formato seguente:
{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

Il timeout è espresso in secondi. Se il timeout non è impostato, il valore predefinito è 30 secondi.

Response

L'app back-end riceve una risposta che include:

  • Codice di stato HTTP, usato per errori provenienti dall'hub IoT, incluso un errore 404 per i dispositivi attualmente non connessi
  • Intestazioni contenenti l'ETag, l'ID richiesta, il tipo di contenuto e la codifica del contenuto
  • Corpo JSON nel formato seguente:
{
    "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.

Gestire un metodo diretto in un dispositivo

Chiamata al metodo

I dispositivi ricevono richieste di metodi diretti nell'argomento MQTT: $iothub/methods/POST/{method name}/?$rid={request id}

Il corpo ricevuto dal dispositivo è nel formato seguente:

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

Le richieste di metodo sono QoS 0.

Response

Il dispositivo invia risposte a $iothub/methods/res/{status}/?$rid={request id}, in cui:

  • La proprietà status è lo stato di esecuzione del metodo fornito dal dispositivo.
  • La proprietà $rid è l'ID richiesta della chiamata al metodo ricevuta dall'hub IoT.

Il corpo è impostato dal dispositivo e accetta qualsiasi stato.

Materiale di riferimento

Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:

Passaggi successivi

Ora che si è appreso come usare i metodi diretti, è possibile vedere un altro argomento di interesse reperibile nell'argomento seguente della Guida per gli sviluppatori dell'hub IoT:

Per provare alcuni dei concetti descritti in questo articolo, può essere utile l'esercitazione seguente sull'hub IoT: