Oktatóanyag: Azure IoT Central-alkalmazás kezelése a REST API használatával

Ez az oktatóanyag bemutatja, hogyan hozhat létre és használhat IoT Central-alkalmazásokat az Azure IoT Central REST API használatával. Ez az oktatóanyag a REST API használatával hajtja végre a webes felhasználói felülettel végrehajtott lépések nagy részét a rövid útmutatókban. Ezek a lépések magukban foglalják az okostelefonon lévő alkalmazás IoT-eszközként való használatát, amely az IoT Centralhoz csatlakozik.

Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:

Előfeltételek

Az oktatóanyag lépéseinek elvégzéséhez a következőkre van szüksége:

• Aktív Azure-előfizetés. Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.

• Egy Android vagy iOS rendszerű okostelefon, amelyen egy ingyenes alkalmazást telepíthet az egyik hivatalos alkalmazásboltból.

Azure CLI

Az Azure CLI-vel kezdeményezheti a REST API-hívásokat, és létrehozhatja azokat a tulajdonosi jogkivonatokat, amelyeket a REST API-k némelyike az engedélyezéshez használ.

• Használja a Bash-környezetet az Azure Cloud Shellben. További információ: A Bash rövid útmutatója az Azure Cloud Shellben.

  

• Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszert használ, fontolja meg az Azure CLI Docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.

  • Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával. A hitelesítési folyamat befejezéséhez kövesse a terminálon megjelenő lépéseket. További bejelentkezési lehetőségekért lásd : Bejelentkezés az Azure CLI-vel.

  • Amikor a rendszer kéri, először telepítse az Azure CLI-bővítményt. További információ a bővítményekről: Bővítmények használata az Azure CLI-vel.

  • Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.

A REST API engedélyezése

A REST API használatához konfigurálnia kell az engedélyezést. Az oktatóanyagban szereplő REST API-hívások két engedélyezési típus egyikét használják:

• Tulajdonosi jogkivonat, amely engedélyezi a hozzáférést.https://apps.azureiotcentral.com Ezzel a tulajdonosi jogkivonattal hozza létre az API-jogkivonatokat az IoT Central-alkalmazásban.
• Rendszergazdai és operátori API-jogkivonatok, amelyek engedélyezik az IoT Central-alkalmazás képességeihez való hozzáférést. Ezeket a jogkivonatokat az oktatóanyagban szereplő legtöbb API-híváshoz használhatja. Ezek a jogkivonatok csak egy adott IoT Central-alkalmazáshoz engedélyezik a hozzáférést.

Futtassa a következő Azure CLI-parancsokat egy tulajdonosi jogkivonat létrehozásához, amely engedélyezi a hozzáférést:https://apps.azureiotcentral.com

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

Jegyezze fel az accessToken értéket, amelyet az oktatóanyag későbbi részében fog használni.

Erőforráscsoport létrehozása

Az Azure cli használatával hozzon létre egy erőforráscsoportot, amely az oktatóanyagban létrehozott IoT Central-alkalmazást tartalmazza:

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

IoT Central-alkalmazás létrehozása

Az alábbi paranccsal hozzon létre egy véletlenszerű névvel rendelkező IoT Central-alkalmazást az oktatóanyagban:

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

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

Jegyezze fel az alkalmazás nevét, amelyet az oktatóanyag későbbi részében fog használni.

AZ API-jogkivonatok létrehozása

Az alábbi adatsík-kérésekkel hozza létre az alkalmazás API-jogkivonatait az IoT Central-alkalmazásban. Az oktatóanyag egyes kérései rendszergazdai engedélyekkel rendelkező API-jogkivonatot igényelnek, de a többség használhat operátori engedélyeket:

Az Azure CLI használatával hívott operator-token operátori jogkivonat létrehozásához futtassa az alábbi parancsot. A szerepkör GUID azonosítója az operátori szerepkör azonosítója minden IoT Central-alkalmazásban:

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"}]}'

Jegyezze fel a parancs által visszaadott operátori jogkivonatot, amelyet az oktatóanyag későbbi részében fog használni. A jogkivonat a következőképpen SharedAccessSignature sr=2...néz ki.

Ha az Azure CLI használatával szeretne admin-token létrehozni egy rendszergazdai jogkivonatot, futtassa a következő parancsot. A szerepkör GUID azonosítója a rendszergazdai szerepkör azonosítója minden IoT Central-alkalmazásban:

$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"}]}'

Jegyezze fel a parancs által visszaadott rendszergazdai jogkivonatot, amelyet az oktatóanyag későbbi részében fog használni. A jogkivonat a következőképpen SharedAccessSignature sr=2...néz ki.

Ha meg szeretné tekinteni ezeket a jogkivonatokat az IoT-központi alkalmazásban, nyissa meg az alkalmazást, és keresse meg a Biztonsági > engedélyek > API-jogkivonatokat.

Eszköz regisztrálása

A csatlakozás előtt regisztrálnia kell egy eszközt az IoT Centralon. Az alábbi kérésekkel regisztrálhatja az eszközt az alkalmazásban, és lekérheti az eszköz hitelesítő adatait. Az első kérés egy 001-as telefonnal rendelkező eszközt hoz létre eszközazonosítóként:

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"

Jegyezze fel a idScope parancs által visszaadott értékeket primaryKey , és használja őket az oktatóanyag későbbi részében.

Eszköz kiépítése és csatlakoztatása

Annak érdekében, hogy ne kelljen manuálisan megadnia az eszköz hitelesítő adatait az okostelefonján, használhatja az IoT Central által létrehozott QR-kódot. A QR-kód kódolja az eszközazonosítót, az azonosító hatókörét és az elsődleges kulcsot. A QR-kód megjelenítése:

1. Nyissa meg az IoT centralalkalmazást a korábban jegyzett alkalmazás URL-címével.
2. Az IoT Central-alkalmazásban navigáljon a Devices > My phone app > Connect > QR-kódra. Tartsa nyitva ezt a lapot, amíg az eszköz csatlakoztatva nem lesz.

A beállítás egyszerűsítése érdekében ez a cikk az IoT Plug and Play okostelefon-alkalmazást használja IoT-eszközként. Az alkalmazás telemetriát küld az okostelefon érzékelőiről, válaszol az IoT Centraltól meghívott parancsokra, és a tulajdonságértékeket jelenti az IoT Centralnak.

Telepítse az alkalmazást okostelefonjára az egyik alkalmazásboltból:

Az IoT Plug and Play alkalmazás csatlakoztatása az Iot Central-alkalmazáshoz:

1. Nyissa meg az IoT PnP alkalmazást okostelefonján.

2. Az üdvözlőlapon válassza a QR-kód beolvasása lehetőséget. Mutasson az okostelefon kamerájára a QR-kódra. Ezután várjon néhány másodpercig, amíg a kapcsolat létrejött.

3. Az alkalmazás telemetriai oldalán láthatja azokat az adatokat, amelyet az alkalmazás az IoT Centralnak küld. A naplók lapon láthatja az eszköz csatlakoztatását és számos inicializálási üzenetet.

Az eszköz üzembe helyezésének ellenőrzéséhez használhatja a REST API-t:

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"

Jegyezze fel a template parancs által visszaadott értéket, amelyet az oktatóanyag későbbi részében fog használni.

A REST API-val kezelheti az eszközsablonokat az alkalmazásban. Például az eszközsablonok megtekintése az alkalmazásban:

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"

Az eszköz lekérdezése és vezérlése

A REST API-val telemetria kérdezhető le az eszközeiről. A következő kérés visszaadja a gyorsulásmérő adatait az összes olyan eszközről, amely egy adott eszközsablon-azonosítóval rendelkezik:

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"

Az eszköztulajdonságok olvasásához és beállításához használhatja a REST API-t. A következő kérés az eszköz által implementálható Eszközinformáció összetevő összes tulajdonságértékét adja vissza:

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"

A REST API-val meghívhatja az eszközparancsokat. A következő kérés meghív egy parancsot, amely három másodpercen keresztül kétszer bekapcsolja az okostelefonját. A parancs futtatásához az okostelefon képernyőjének be kell kapcsolnia az IoT Plug and Play alkalmazást:

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}'

Az erőforrások eltávolítása

Ha befejezte az oktatóanyagban használt IoT Central-alkalmazást, törölheti azt:

appName=<the app name generated previously>

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