REST hub IoT

  • Articolo

Le API REST per hub IoT offrono l'accesso a livello di codice al dispositivo, alla messaggistica e ai servizi di processo, nonché al provider di risorse, in hub IoT. È possibile accedere ai servizi di messaggistica da un servizio IoT in esecuzione in Azure oppure direttamente su Internet da qualsiasi applicazione che può inviare una richiesta HTTPS e ricevere una risposta HTTPS.

Servizio

  • Usare questa API per gestire hub IoT dispositivi gemelli. È possibile recuperare e aggiornare le proprietà del dispositivo gemello e richiamare metodi diretti nei dispositivi.
  • Usare queste API per gestire le identità dei dispositivi nel Registro identità di un hub IoT.
  • Usare queste API per gestire i processi in hub IoT. È possibile pianificare, annullare o ottenere un processo.

Tutte le operazioni attività sono conformi alla specifica del protocollo HTTP/1.1 e ogni operazione restituisce un'intestazione x-ms-request-id che può essere usata per ottenere informazioni sulla richiesta. È necessario assicurarsi che le richieste effettuate per tali risorse siano sicure. Per altre informazioni, vedere guida per sviluppatori hub IoT - Sicurezza per le specifiche su come creare token di sicurezza.

Messaggistica del dispositivo

Usare queste API da un dispositivo per inviare messaggi da dispositivo a cloud a un hub IoT e ricevere messaggi da cloud a dispositivo da un hub IoT. Tutte le operazioni delle attività sono conformi alla specifica del protocollo HTTP/1.1. È necessario assicurarsi che le richieste effettuate per tali risorse siano sicure. Per altre informazioni, vedere hub IoT Guida per sviluppatori - Sicurezza per informazioni specifiche su come creare token di sicurezza.

Provider di risorse

Usare queste API per gestire la distribuzione delle risorse di hub IoT. Per informazioni su come proteggere queste richieste, vedere Informazioni di riferimento sull'API REST di Azure.

Parametri e intestazioni comuni

Le informazioni seguenti sono comuni a tutte le attività correlate alla hub IoT:

  • Sostituire {api-version} con "2018-06-30" nell'URI.

  • Sostituire {subscription-id} con l'identificatore della sottoscrizione nell'URI.

  • Sostituire {resourceGroupName} con il nome del gruppo di risorse contenente (o conterrà) l'hub IoT.

  • Sostituire {IoTHubName} con il nome dell'hub IoT.

  • Impostare l'intestazione Content-Type su application/json.

  • Impostare l'intestazione Di autorizzazione su un token di firma di accesso condiviso creato come specificato nella sezione Token di sicurezzadi Using hub IoT security tokens.

  • L'intestazione Etag viene restituita in tutte le richieste con ambito a una singola identità del dispositivo, in base a RFC7232.

  • Tutte le operazioni PUT/PATCH richiedono che siano specificate le intestazioni seguenti: If-Match = [*|<etag from get>]

  • Le operazioni DELETE possono includere l'intestazione seguente: If-Match = [*|<etag from get>]

Il comportamento per ETags può essere illustrato di seguito:

PUT La risorsa non esiste La risorsa esiste
If-Match = "" / assente 201 Creato 200 - OK
If-Match = "*" 412 - Condizione preliminare non riuscita 200 - OK
If-Match = "xyz" 412 - Condizione preliminare non riuscita 200 OK/ 412 Precondizione non riuscita
If-None-Match = "*" 201 Creato 412 - Condizione preliminare non riuscita
DELETE La risorsa non esiste La risorsa esiste
If-Match = "" / assente 204 No Content (Nessun contenuto) 200 - OK
If-Match = "*" 204 No Content (Nessun contenuto) 200 - OK
If-Match = "xyz" 204 No Content (Nessun contenuto) 200 OK/ 412 Precondizione non riuscita

Per le chiamate asincrone:

  • PUT risponde con 201 Create con Azure-AsyncOperation intestazione per tutte le operazioni asincrone. Tutte le operazioni sincrone (aggiornamenti) restituiscono 200 OK.

  • DELETE restituisce 202 accettata con posizione e intestazioni di Retry-After e Azure-AsyncOperation intestazione per le risorse esistenti.

  • L'intestazione percorso contiene l'URL per il risultato dell'operazione

  • Retry-After'intestazione contiene l'intervallo di tentativi appropriato in secondi

  • Azure-AsyncOperation intestazione contiene l'URL per lo stato del risultato dell'operazione asincrona

  • Al termine, l'URL GET al risultato dell'operazione genera esattamente lo stesso risultato di se l'operazione originale fosse stata completata in modo sincrono