Condividi tramite

Comprendere e richiamare metodi diretti dall'hub IoT

I metodi diretti dell'hub IoT consentono di richiamare in remoto le chiamate nei dispositivi dal cloud. I metodi diretti seguono un modello di richiesta-risposta e sono destinati alle comunicazioni che richiedono 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.

Annotazioni

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 e le dimensioni dell'hub IoT corretti per la soluzione.

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

Chiunque disponga delle autorizzazioni di connessione del servizio nell'hub IoT può richiamare un metodo in un dispositivo.

Fare riferimento alle linee guida per le comunicazioni da cloud a dispositivo in caso di dubbi tra l'uso di proprietà desiderate, metodi diretti o messaggi da cloud a dispositivo.

Ciclo di vita del metodo

I metodi diretti vengono implementati nel dispositivo e potrebbero richiedere zero o più input nel payload del metodo per creare correttamente un'istanza. Richiami un metodo diretto tramite un URI rivolto al 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 (le proprietà dell'applicazione IoThub-methodname e IoThub-status ).

Annotazioni

Quando si richiama un metodo diretto su un dispositivo, i nomi delle proprietà e i valori possono contenere solo caratteri alfanumerici stampabili US-ASCII, tranne quelli nel seguente set: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

I metodi diretti sono sincroni e hanno esito positivo o negativo dopo il periodo di timeout (predefinito 30 secondi; impostabile tra 5 e 300 secondi). I metodi diretti sono utili negli scenari interattivi in cui si vuole che un dispositivo agisca se e solo se il dispositivo è online e riceve comandi. Ad esempio, accendere una luce da un telefono. In questi scenari si vuole visualizzare un esito positivo o negativo immediato in modo che il servizio cloud possa agire sul risultato il prima possibile. Il dispositivo potrebbe restituire un corpo del messaggio come risultato del metodo , ma non è obbligatorio. Non esiste alcuna garanzia sull'ordinamento o sulle semantiche di concorrenza sulle chiamate al metodo.

I metodi diretti sono solo HTTPS dal lato cloud e MQTT, AMQP, MQTT su WebSockets o AMQP su WebSockets dal lato dispositivo.

Il payload per le richieste di metodo e le risposte è un documento JSON fino a 128 KB.

Richiamare un metodo diretto da un'applicazione back-end

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

Invocazione del metodo

Le chiamate al metodo diretto in un dispositivo sono chiamate HTTPS costituite 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 il servizio hub IoT deve attendere per il completamento di un'esecuzione diretta del metodo in un dispositivo. Impostare questo timeout almeno quanto il tempo di esecuzione previsto di un metodo diretto eseguito da un dispositivo. Se non viene specificato un valore di 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 il servizio hub IoT 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, usa l'estensione Microsoft Azure IoT per Azure CLI per creare un 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.

Annotazioni

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 da includere /modules/<moduleName> come illustrato nell'esempio seguente:

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

risposta

L'app back-end riceve una risposta costituita 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 principale);
    • 504 indica il timeout del gateway causato dal dispositivo che non risponde a una chiamata al metodo diretto all'interno di responseTimeoutInSeconds.

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

  • Un body 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.

Invocazione del metodo per i moduli IoT Edge

Per richiamare un metodo diretto in un modulo, usare l'API REST Modules - Invoke Method o il relativo equivalente in uno degli SDK del servizio hub IoT.

moduleId è passato insieme a deviceId nella URI della richiesta quando si utilizza l'API REST o come parametro quando si utilizza 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 per dispositivi dell'hub IoT consentono di ricevere e rispondere ai metodi diretti nei dispositivi senza doversi preoccupare dei dettagli del protocollo sottostanti.

MQTT

La sezione seguente riguarda il protocollo MQTT. Per altre informazioni sull'uso del protocollo MQTT direttamente con l'hub IoT, vedere Comunicare con un hub IoT usando il protocollo MQTT.

Invocazione del metodo

I dispositivi ricevono richieste di metodo diretto nell'argomento MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. Tuttavia, request id non può essere noto in anticipo perché l'hub IoT lo genera. Pertanto, iscriviti a $iothub/methods/POST/# e poi filtra i messaggi recapitati in base ai nomi dei metodi supportati dal dispositivo. Usi il generato request id per rispondere.

La struttura ricevuta 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}, dove:

  • La status proprietà è lo stato fornito dal dispositivo dell'esecuzione del metodo.

  • La proprietà $rid è l'ID della richiesta dalla chiamata al metodo ricevuta dall'IoT Hub. L'ID richiesta è un valore formattato esadecimale.

Il dispositivo configura il corpo e può assumere qualsiasi stato.

AMQP

La sezione seguente riguarda il protocollo AMQP. Per altre informazioni sull'uso del protocollo AMQP direttamente con l'hub IoT, vedere Comunicare con l'hub IoT usando il protocollo AMQP.

Invocazione del metodo

Il dispositivo riceve richieste di metodo diretto creando un collegamento di ricezione all'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, che contiene un ID di richiesta che deve essere restituito assieme alla risposta del metodo corrispondente.

  • Proprietà dell'applicazione denominata IoThub-methodname, che contiene il nome del metodo richiamato.

  • Il corpo del messaggio AMQP che contiene 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 sul collegamento di invio ed è strutturata come segue:

  • La proprietà dell'ID di correlazione, che contiene l'ID della richiesta passato nel messaggio della richiesta del metodo.

  • Proprietà dell'applicazione denominata IoThub-status, che contiene lo stato del metodo fornito dall'utente.

  • Corpo del messaggio AMQP contenente la risposta del metodo come JSON.

Passaggi successivi

Ora che si è appreso come usare metodi diretti, è possibile che si sia interessati agli articoli della guida per sviluppatori dell'hub IoT seguenti:

  • Last updated on