Comprendere e richiamare metodi diretti dall'hub IoT

  • Articolo

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 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,

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT di base e standard/gratuiti, vedere Scegliere il livello di hub IoT appropriato per la soluzione.

Ogni metodo del dispositivo è destinato a un unico dispositivo. In Pianificare processi in più dispositivi viene descritto come fornire un modo per richiamare i metodi diretti in più dispositivi e di pianificare la chiamata al metodo per i dispositivi disconnessi.

Chiunque disponga delle autorizzazioni di connessione al servizio per hub IoT può richiamare un metodo in un dispositivo.

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, ad esempio il controllo interattivo del dispositivo, come 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/). 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).

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 hanno esito positivo o negativo dopo il periodo di timeout (valore predefinito: 30 secondi, impostabile tra 5 e 300 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 sono HTTPS solo dal lato cloud e MQTT, AMQP, MQTT su WebSockets o AMQP su WebSocket dal lato dispositivo.

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

Richiamare un metodo diretto da un'app back-end

Per richiamare un metodo diretto da un'app back-end, usare l'API REST del metodo di dispositivo Invoke o il relativo equivalente in uno degli SDK del servizio hub IoT.

Chiamata al metodo

Le chiamate a metodi diretti in un dispositivo sono chiamate HTTPS composte dagli elementi seguenti:

  • URI della richiesta specifico del dispositivo insieme alla versione dell'API:

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • Metodo POST

  • Intestazioni che contengono l'autorizzazione, il tipo di contenuto e la codifica del contenuto.

  • Corpo JSON trasparente nel formato seguente:

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

Il valore fornito come responseTimeoutInSeconds nella richiesta è la quantità di tempo che hub IoT servizio deve attendere il completamento di un'esecuzione diretta del metodo in un dispositivo. Impostare questo timeout in modo che sia pari almeno al tempo di esecuzione previsto di un metodo diretto da parte di un dispositivo. Se il timeout non viene fornito, viene usato il valore predefinito di 30 secondi. I valori minimi e massimi per responseTimeoutInSeconds sono rispettivamente 5 e 300 secondi.

Il valore fornito come connectTimeoutInSeconds nella richiesta è la quantità di tempo alla chiamata di un metodo diretto che hub IoT servizio deve attendere che un dispositivo disconnesso venga online. Il valore predefinito è 0, ovvero i dispositivi devono essere già online alla chiamata di un metodo diretto. Il valore massimo per connectTimeoutInSeconds è 300 secondi.

Esempio

Questo esempio consente di avviare in modo sicuro una richiesta per richiamare un metodo diretto in un dispositivo IoT registrato in un hub IoT di Azure.

Per iniziare, usare l'estensione IoT di Microsoft Azure per l'interfaccia della riga di comando di Azure per creare un oggetto SharedAccessSignature.

az iot hub generate-sas-token -n <iothubName> --du <duration>

Sostituire quindi l'intestazione Di autorizzazione con l'intestazione SharedAccessSignature appena generata, quindi modificare i iothubNameparametri , deviceIdmethodName e payload in modo che corrispondano all'implementazione nel comando di esempio curl seguente.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

Eseguire il comando modificato per richiamare il metodo diretto specificato. Le richieste riuscite restituiranno un codice di stato HTTP 200.

Nota

Nell'esempio precedente viene illustrato come richiamare un metodo diretto in un dispositivo. Se si vuole richiamare un metodo diretto in un modulo IoT Edge, è necessario modificare la richiesta url come illustrato di seguito:

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

Risposta

L'app back-end riceve una risposta composta dagli elementi seguenti:

  • Codice di stato HTTP:

    • 200 indica l'esecuzione corretta del metodo diretto;
    • 404 indica che l'ID dispositivo non è valido o che il dispositivo non è online quando si chiama un metodo diretto e per connectTimeoutInSeconds successivamente (usare un messaggio di errore accompagnato per comprendere la causa radice);
    • 504 indica il timeout del gateway causato dal dispositivo che non risponde a una chiamata diretta al metodo all'interno responseTimeoutInSecondsdi .

  • Intestazioni che contengono l'ID richiesta, il tipo di contenuto e la codifica del contenuto.

  • Corpo JSON nel formato seguente:

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

    Entrambi status e payload vengono forniti dal dispositivo e usati per rispondere con il proprio codice di stato del dispositivo e la risposta al metodo.

Chiamata al metodo per i moduli di IoT Edge

Richiamare metodi diretti in un modulo è supportato dall'API REST del metodo Invoke o dal relativo equivalente in uno degli SDK del servizio hub IoT.

L'oggetto moduleId viene passato insieme all'URI deviceId della richiesta quando si usa l'API REST o come parametro quando si usa un SDK del servizio. Ad esempio, https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. Il corpo della richiesta e la risposta sono simili a quello dei metodi diretti richiamati nel dispositivo.

Gestire un metodo diretto in un dispositivo

In un dispositivo IoT i metodi diretti possono essere ricevuti tramite MQTT, AMQP o uno di questi protocolli su WebSocket. Gli SDK del dispositivo hub IoT consentono di ricevere e rispondere ai metodi diretti nei dispositivi senza dover preoccuparsi dei dettagli del protocollo sottostanti.

MQTT

La sezione seguente è per il protocollo MQTT. Per altre informazioni sull'uso del protocollo MQTT direttamente con hub IoT, vedere Supporto del protocollo MQTT.

Chiamata al metodo

I dispositivi ricevono richieste di metodi diretti nell'argomento MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. Tuttavia, l'oggetto request id viene generato da hub IoT e non può essere noto in anticipo, quindi sottoscrivere e quindi filtrare i messaggi recapitati in base ai $iothub/methods/POST/# nomi dei metodi supportati dal dispositivo. Verrà usato request id per rispondere.

Il corpo ricevuto dal dispositivo è nel formato seguente:

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

Le richieste di metodo sono QoS 0.

Risposta

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. L'ID richiesta è un valore formattato esadecimale.

Il corpo è impostato dal dispositivo e accetta qualsiasi stato.

AMQP

La sezione seguente è per il protocollo AMQP. Per altre informazioni sull'uso del protocollo AMQP direttamente con hub IoT, vedere Supporto del protocollo AMQP.

Chiamata al metodo

Il dispositivo riceve richieste di metodi diretti tramite la creazione di un collegamento di ricezione sull'indirizzo amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Il messaggio AMQP arriva sul collegamento di ricezione che rappresenta la richiesta del metodo. Contiene le sezioni seguenti:

  • La proprietà ID di correlazione, contenente un ID richiesta che deve essere passato con la relativa risposta del metodo.

  • Una proprietà dell'applicazione denominata IoThub-methodname, contenente il nome del metodo richiamato.

  • Il corpo del messaggio AMQP, contenente il payload del metodo in formato JSON.

Risposta

Il dispositivo crea un collegamento di invio per restituire la risposta del metodo all'indirizzo amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

La risposta del metodo viene restituita nel collegamento di invio ed è strutturata come segue:

  • Proprietà ID correlazione che contiene l'ID richiesta passato nel messaggio di richiesta del metodo.

  • Una proprietà dell'applicazione denominata IoThub-status, contenente lo stato del metodo fornito dall'utente.

  • Il corpo del messaggio AMQP, contenente la risposta del metodo in formato JSON.

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 articolo di interesse della Guida per sviluppatori dell'hub IoT:

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