Condividi tramite

Comprendere e richiamare metodi diretti dall'hub IoT

  • Articolo

hub IoT metodi diretti consentono di richiamare in remoto le chiamate nei dispositivi dal cloud. 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 di un dispositivo, ad esempio l'accensione di una ventola. Questa funzionalità è utile per gli scenari in cui il corso dell'azione immediata è diverso a seconda che il dispositivo sia in grado di rispondere.

Nota

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

Ogni metodo del dispositivo è destinato a un unico dispositivo. Per richiamare metodi diretti su più dispositivi o pianificare i metodi per i dispositivi disconnessi, vedere Pianificare i processi in più dispositivi.

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

Fare riferimento alle linee guida per la comunicazione da cloud a dispositivo in caso di dubbi sull'uso di proprietà desiderate, metodi diretti o 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 (impostazione predefinita 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 è obbligatorio. Nelle chiamate ai metodi non esiste alcuna garanzia di ordinamento o semantica di concorrenza.

I metodi diretti sono solo HTTPS 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 del dispositivo Invoke o il relativo equivalente in uno degli SDK del servizio hub IoT.

Chiamata del 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 specificato come responseTimeoutInSeconds nella richiesta è la quantità di tempo che il servizio hub IoT deve attendere per il completamento dell'esecuzione di un metodo diretto 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 non si specifica il timeout, viene usato il valore predefinito di 30 secondi. I valori minimo e massimo per responseTimeoutInSeconds sono rispettivamente 5 e 300 secondi.

Il valore fornito come connectTimeoutInSeconds nella richiesta è la quantità di tempo durante la chiamata di un metodo diretto che hub IoT servizio deve attendere affinché 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 avvia una richiesta per richiamare un metodo diretto in un dispositivo IoT registrato in un hub IoT di Azure.

Per iniziare, usare l'estensione Microsoft Azure IoT 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 Authorization con l'oggetto SharedAccessSignature appena generato, 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 restituiscono un codice di stato HTTP 200.

Nota

L'esempio precedente illustra la chiamata di un metodo diretto in un dispositivo. Se si vuole richiamare un metodo diretto in un modulo IoT Edge, modificare la richiesta url in modo da includere /modules/<moduleName> come illustrato di seguito:

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

Response

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 era online al momento della chiamata di un metodo diretto e successivamente connectTimeoutInSeconds (usare il messaggio di errore accompagnato per comprendere la causa radice);
    • 504 indica il timeout del gateway causato dal dispositivo che non risponde a una chiamata al metodo diretto 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" : {...}
}

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

Chiamata al metodo per i moduli di IoT Edge

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

Il moduleId viene passato insieme al deviceId nell'URI 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 e la risposta della richiesta 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 doversi preoccupare dei dettagli del protocollo sottostanti.

MQTT

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

Chiamata del metodo

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

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. 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 diretto del protocollo AMQP con hub IoT, vedere Supporto del protocollo AMQP.

Chiamata del 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.

Response

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 sul collegamento di invio ed è strutturata come segue:

  • Proprietà ID di 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.

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: