Esercitazione: Usare l'API REST per gestire un'applicazione Azure IoT Central

  • Articolo

Questa esercitazione illustra come usare l'API REST di Azure IoT Central per creare e interagire con un'applicazione IoT Central. Questa esercitazione usa l'API REST per completare molti dei passaggi completati usando l'interfaccia utente Web nelle guide introduttive. Questi passaggi includono l'uso di un'app sullo smartphone come dispositivo IoT che si connette a IoT Central.

In questa esercitazione apprenderai a:

  • Autorizzare l'API REST.
  • Creare un'applicazione IoT Central.
  • Aggiungere un dispositivo all'applicazione.
  • Eseguire query e controllare il dispositivo.
  • Configurare l'esportazione dei dati.
  • Elimina un'applicazione.

Prerequisiti

Per completare la procedura di questa esercitazione, è necessario quanto segue:

  • Una sottoscrizione di Azure attiva. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

  • Uno smartphone Android o iOS in cui è possibile installare un'app gratuita da uno degli app store ufficiali.

Interfaccia della riga di comando di Azure

Usare l'interfaccia della riga di comando di Azure per generare i token di connessione usati da alcune api REST per l'autorizzazione.

Postman

In questa esercitazione si usa Postman per effettuare chiamate API REST. Se si preferisce non scaricare e installare Postman, è possibile usare la versione online. È possibile completare tutti i passaggi dell'esercitazione usando la versione gratuita di Postman.

L'esercitazione usa una raccolta Postman predefinita che include alcuni script per completare i passaggi.

Importare la raccolta Postman

Per importare la raccolta, aprire Postman e selezionare Importa. Nella finestra di dialogo Importa selezionare Collega e incollare l'URL seguente, selezionare Continua.

L'area di lavoro contiene ora la raccolta di esercitazioni REST di IoT Central. Questa raccolta include tutte le API usate nell'esercitazione.

La raccolta usa variabili per parametrizzare le chiamate API REST. Per visualizzare le variabili, selezionare l'esercitazione ... accanto a IoT Central REST e selezionare Modifica. Selezionare quindi Variabili. Molte delle variabili vengono impostate automaticamente quando si effettuano chiamate API o si hanno valori predeterminati.

Autorizzare l'API REST

Prima di poter usare l'API REST, è necessario configurare l'autorizzazione. Le chiamate API REST in questa esercitazione usano uno dei tre tipi di autorizzazione:

  • Token di connessione che autorizza l'accesso a https://management.azure.com. Questo token di connessione viene usato durante la creazione e l'eliminazione e l'applicazione IoT Central. Un'applicazione IoT Central è una risorsa di Azure.
  • Token di connessione che autorizza l'accesso a https://apps.azureiotcentral.com. Questo token di connessione viene usato per creare i token API nell'applicazione IoT Central.
  • Amministrazione istrator e token API dell'operatore che autorizzano l'accesso alle funzionalità nell'applicazione IoT Central. Questi token vengono usati per la maggior parte delle chiamate API in questa esercitazione. Questi token autorizzano l'accesso solo a un'applicazione IoT Central specifica.

Assegnare valori alle variabili seguenti nell'insieme Postman:

  • bearerToken: eseguire i comandi dell'interfaccia della riga di comando di Azure seguenti per generare un token di connessione che autorizza l'accesso a https://management.azure.com:

    az login
az account get-access-token --resource https://management.azure.com

    Suggerimento

    Potrebbe essere necessario eseguire az login anche se si usa Cloud Shell.

    Copiare il accessToken valore nella colonna Valore corrente per bearerToken nelle variabili della raccolta.

  • bearerTokenApp: eseguire i comandi dell'interfaccia della riga di comando di Azure seguenti per generare un token di connessione che autorizza l'accesso a https://apps.azureiotcentral.com:

    az account get-access-token --resource https://apps.azureiotcentral.com

    Suggerimento

    Se è stata avviata una nuova istanza della shell, eseguire az login di nuovo.

    Copiare il accessToken valore nella colonna Valore corrente per bearerTokenApp nelle variabili della raccolta.

  • subscriptionId: l'ID sottoscrizione è stato incluso nell'output dei due comandi precedenti. Copiare il subscription valore nella colonna Valore corrente per subscriptionId nelle variabili della raccolta.

Screenshot that shows the variables set manually in the Postman collection.

Assicurarsi di salvare le modifiche apportate alla raccolta Postman.

Nota

I token di connessione scadono dopo un'ora.

Creare un'applicazione

Usare le richieste del piano di controllo per creare e gestire applicazioni IoT Central. Usare la richiesta PUT seguente per creare l'applicazione usata in questa esercitazione. La richiesta usa un token di connessione per autorizzare e generare un nome di applicazione casuale.

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Crea un'applicazione IoT central.
  2. Selezionare Invia.
  3. Controllare che la richiesta abbia esito positivo. In caso di errore, verificare di aver immesso i valori della variabile bearerToken e subscriptionId nella raccolta Postman.
  4. Selezionare Visualizza per visualizzare l'URL della nuova applicazione IoT Central. Prendere nota di questo URL, che sarà necessario più avanti in questa esercitazione.

Screenshot that shows the Visualize tab with the application URL in Postman.

Creare i token API

Usare le richieste del piano dati seguenti per creare i token API dell'applicazione nell'applicazione IoT Central. Alcune delle richieste descritte in questa esercitazione richiedono un token API con autorizzazioni di amministratore, ma la maggior parte può usare le autorizzazioni degli operatori:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta crea un token dell'operatore.
  2. Selezionare Invia.
  3. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Crea un token di amministratore.
  4. Selezionare Invia.

Per visualizzare questi token nell'applicazione IoT Central, aprire l'applicazione e passare a Token API autorizzazioni > di sicurezza>.

Nota

Uno script in Postman aggiunge automaticamente questi token API all'elenco di variabili di raccolta.

Registrazione di un dispositivo

È necessario registrare un dispositivo con IoT Central prima di potersi connettere. Usare le richieste seguenti per registrare il dispositivo nell'applicazione e recuperare le credenziali del dispositivo. La prima richiesta crea un dispositivo con phone-001 come ID dispositivo:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Aggiungi un dispositivo .
  2. Selezionare Invia. Nella risposta si noti che non è stato effettuato il provisioning del dispositivo.
  3. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Ottieni credenziali del dispositivo.
  4. Selezionare Invia.
  5. La scheda Visualizza mostra i valori di ambito ID e chiave primaria necessari per la connessione del dispositivo.

Effettuare il provisioning e connettere un dispositivo

Per evitare la necessità di immettere manualmente le credenziali del dispositivo sullo smartphone, è possibile usare un codice a matrice generato da IoT Central. Il codice a matrice codifica l'ID dispositivo, l'ambito ID, la chiave primaria. Per visualizzare il codice a matrice:

  1. Aprire l'applicazione IoT Central usando l'URL dell'applicazione annotato in precedenza.
  2. Nell'applicazione IoT Central passare a Dispositivi > App per telefono > Connessione > codice a matrice. Mantenere aperta questa pagina fino a quando il dispositivo non è connesso.

Screenshot that shows the QR code you use to connect the device.

Per semplificare la configurazione, questo articolo usa l'app per smartphone Plug and Play IoT come dispositivo IoT. L'app invia i dati di telemetria raccolti dai sensori dello smartphone, risponde ai comandi richiamati da IoT Central e segnala i valori delle proprietà a IoT Central.

Installa l'app sul tuo smartphone da uno degli App Store:

Get the app for your Android phone on Google Play.Download the app for your phone from the App Store.

Per connettere l'app Plug and Play IoT all'applicazione Iot Central:

  1. Apri l'app IoT PnP sul tuo smartphone.

  2. Nella pagina iniziale selezionare Analizza codice a matrice. Puntare la fotocamera dello smartphone al codice a matrice. Attendere quindi alcuni secondi mentre viene stabilita la connessione.

  3. Nella pagina di telemetria nell'app è possibile visualizzare i dati inviati dall'app a IoT Central. Nella pagina dei log è possibile visualizzare il dispositivo che si connette e diversi messaggi di inizializzazione.

Per verificare che il dispositivo sia ora sottoposto a provisioning, è possibile usare l'API REST:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Ottieni un dispositivo .
  2. Selezionare Invia. Nella risposta si noti che è stato eseguito il provisioning del dispositivo. IoT Central ha anche assegnato un modello di dispositivo al dispositivo in base all'ID modello inviato dal dispositivo.

È possibile usare l'API REST per gestire i modelli di dispositivo nell'applicazione. Ad esempio, per visualizzare i modelli di dispositivo nell'applicazione:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Elenca modelli di dispositivo .
  2. Selezionare Invia.

Eseguire query e controllare il dispositivo

È possibile usare l'API REST per eseguire query sui dati di telemetria dai dispositivi. La richiesta seguente restituisce i dati dell'accelerometro da tutti i dispositivi che condividono un ID modello di dispositivo specifico:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare esegui una richiesta di query .
  2. Selezionare Invia.

È possibile usare l'API REST per leggere e impostare le proprietà del dispositivo. La richiesta seguente restituisce tutti i valori delle proprietà del componente Informazioni sul dispositivo implementato dal dispositivo:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare le proprietà Get da una richiesta di componente .
  2. Selezionare Invia.

È possibile usare l'API REST per chiamare i comandi del dispositivo. La richiesta seguente chiama un comando che accende la luce dello smartphone due volte per tre secondi. Affinché il comando venga eseguito, lo schermo dello smartphone deve essere attivo con l'app Plug and Play IoT visibile:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta di comando Chiama.
  2. Selezionare Invia.

Esportare i dati di telemetria

È possibile usare l'API RESP per configurare e gestire l'applicazione IoT Central. I passaggi seguenti illustrano come configurare l'esportazione dei dati per inviare valori di telemetria a un webhook. Per semplificare la configurazione, questo articolo usa un webhook RequestBin come destinazione. RequestBin è un servizio di terze parti.

Per creare l'endpoint di test per la destinazione di esportazione dei dati:

  1. Passare a RequestBin.
  2. Selezionare Create a RequestBin (Crea un elemento RequestBin).
  3. Accedere con uno dei metodi disponibili.
  4. Copiare l'URL dell'endpoint RequestBin.
  5. In Postman aprire la raccolta di esercitazioni REST di IoT Central e passare alle variabili di raccolta.
  6. Incollare l'URL dell'endpoint RequestBin nella colonna Valore corrente per webHookURL nelle variabili di raccolta.
  7. Salvare le modifiche.

Per configurare la destinazione di esportazione nell'applicazione IoT Central usando l'API REST:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Crea una destinazione di esportazione webhook.
  2. Selezionare Invia.

Per configurare la definizione di esportazione nell'applicazione IoT Central usando l'API REST:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Creare una richiesta di definizione di esportazione dei dati di telemetria.
  2. Selezionare Invia. Si noti che lo stato non è avviato.

L'avvio dell'esportazione potrebbe richiedere alcuni minuti. Per controllare lo stato dell'esportazione usando l'API REST:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Recupera un'esportazione per ID .
  2. Selezionare Invia. Quando lo stato è integro, IoT Central invia dati di telemetria al webhook.

L'app sullo smartphone non invia dati di telemetria a meno che lo schermo non sia acceso e che l'app Plug and Play IoT sia visibile.

Quando l'app per smartphone invia dati di telemetria, passare a RequestBin per visualizzare i dati di telemetria esportati.

Pulire le risorse

Se l'applicazione IoT Central usata in questa esercitazione è stata completata, è possibile usare l'API REST per eliminarla:

  1. In Postman aprire la raccolta di esercitazioni REST di IoT Central e selezionare la richiesta Elimina un'applicazione IoT central.
  2. Selezionare Invia.

Suggerimento

Questa richiesta usa un token di connessione generato all'inizio dell'esercitazione. I token di connessione scadono dopo l'ora. Potrebbe essere necessario generare un nuovo token di connessione che autorizza l'accesso a https://apps.azureiotcentral.com.

Passaggi successivi

Se si preferisce continuare il set di esercitazioni di IoT Central e saperne di più sulla creazione di una soluzione di IoT Central, vedere:

Creare un modello di dispositivo gateway