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

Articolo
11/09/2024

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.
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 effettuare chiamate all'API REST e generare i token di connessione usati da alcune api REST per l'autorizzazione.

Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.
Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
- Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.
- Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.
- Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

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 due tipi di autorizzazione seguenti:

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.
Token API di amministratore e 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.

Eseguire i comandi seguenti dell'interfaccia della riga di comando di Azure 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 di nuovo az login.

Prendere nota del accessToken valore, che verrà usato più avanti nell'esercitazione.

Nota

I token di connessione scadono dopo un'ora. Se scadono, eseguire gli stessi comandi per generare nuovi token di connessione.

Creare un gruppo di risorse

Usare l'interfaccia della riga di comando di Azure per creare un gruppo di risorse contenente l'applicazione IoT Central creata in questa esercitazione:

az group create --name iot-central-rest-tutorial --location eastus

Creazione di un'applicazione IoT Central

Usare il comando seguente per generare un'applicazione IoT Central con un nome casuale da usare in questa esercitazione:

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

Prendere nota del nome dell'applicazione, che verrà usato più avanti in questa esercitazione.

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:

Per creare un token di operatore chiamato operator-token tramite l'interfaccia della riga di comando di Azure, eseguire il comando seguente. Il GUID del ruolo è l'ID del ruolo operatore in tutte le applicazioni IoT Central:

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

Prendere nota del token dell'operatore restituito dal comando, che verrà usato più avanti nell'esercitazione. Il token è simile a SharedAccessSignature sr=2....

Per creare un token di amministratore chiamato admin-token usando l'interfaccia della riga di comando di Azure, eseguire il comando seguente. Il GUID del ruolo è l'ID del ruolo di amministratore in tutte le applicazioni IoT Central:

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

Prendere nota del token di amministratore restituito dal comando, che verrà usato più avanti nell'esercitazione. Il token è simile a SharedAccessSignature sr=2....

Per visualizzare questi token nell'applicazione IoT Central, aprire l'applicazione e passare a Sicurezza > Autorizzazioni > Token API.

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Prendere nota dei idScope valori e primaryKey restituiti dal comando, che verranno usati più avanti nell'esercitazione.

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:

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

Screenshot che mostra il codice a matrice usato per connettere il dispositivo.

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 invocati da IoT Central e segnala i valori delle proprietà a IoT Central.

Installare l'app sullo smartphone da uno degli App Store:

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

Aprire l'app IoT PnP sullo smartphone.
Nella pagina iniziale, selezionare Analizza codice a matrice. Puntare la fotocamera dello smartphone verso il codice a matrice. Attendere quindi alcuni secondi mentre viene stabilita la connessione.
Nella pagina dei dati di telemetria dell'app, è possibile visualizzare i dati che l'app sta inviando a IoT Central. Nella pagina dei log, è possibile visualizzare la connessione del dispositivo e diversi messaggi di inizializzazione.

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Prendere nota del valore restituito dal template comando, che verrà usato più avanti nell'esercitazione.

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

È 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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

Pulire le risorse

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

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial

Condividi tramite