Kurz: Použití rozhraní REST API ke správě aplikace Azure IoT Central

Článek
11/09/2024

V tomto kurzu se dozvíte, jak pomocí rozhraní AZURE IoT Central REST API vytvořit aplikaci IoT Central a pracovat s ní. Tento kurz používá rozhraní REST API k dokončení mnoha kroků, které jste dokončili pomocí webového uživatelského rozhraní v rychlých startech. Mezi tyto kroky patří použití aplikace na smartphonu jako zařízení IoT, které se připojuje k IoT Central.

V tomto kurzu se naučíte:

Autorizace rozhraní REST API
Vytvořte aplikaci IoT Central.
Přidejte do aplikace zařízení.
Zadejte dotaz a řízení zařízení.
Nastavení exportu dat
Odstraňte aplikaci.

Požadavky

K dokončení kroků v tomto kurzu potřebujete:

Aktivní předplatné Azure. Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.
Smartphone s Androidem nebo iOSem, na který si můžete nainstalovat bezplatnou aplikaci z některého z oficiálních obchodů s aplikacemi.

Azure CLI

Pomocí Azure CLI provedete volání rozhraní REST API a vygenerujete nosné tokeny, které některá rozhraní REST API používají k autorizaci.

Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.
Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.
- Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.
- Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.
- Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Autorizace rozhraní REST API

Před použitím rozhraní REST API musíte nakonfigurovat autorizaci. Volání rozhraní REST API v tomto kurzu používají jeden ze dvou typů autorizace:

Nosný token, který autorizuje přístup k https://apps.azureiotcentral.com. Tento nosný token použijete k vytvoření tokenů rozhraní API v aplikaci IoT Central.
Tokeny rozhraní API správce a operátora, které autorizuje přístup k funkcím ve vaší aplikaci IoT Central. Tyto tokeny použijete pro většinu volání rozhraní API v tomto kurzu. Tyto tokeny autorizuje přístup pouze k jedné konkrétní aplikaci IoT Central.

Spuštěním následujících příkazů Azure CLI vygenerujte nosný token, který autorizuje přístup k https://apps.azureiotcentral.com:

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

Tip

Pokud jste spustili novou instanci prostředí, spusťte az login to znovu.

Poznamenejte accessToken si hodnotu, kterou použijete později v kurzu.

Poznámka:

Platnost nosných tokenů vyprší po hodině. Pokud vyprší jejich platnost, spusťte stejné příkazy a vygenerujte nové nosné tokeny.

Vytvoření skupiny zdrojů

Pomocí Azure CLI vytvořte skupinu prostředků, která obsahuje aplikaci IoT Central, kterou vytvoříte v tomto kurzu:

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

Vytvoření aplikace IoT Central

Pomocí následujícího příkazu vygenerujte aplikaci IoT Central s náhodným názvem, který se použije v tomto kurzu:

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

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

Poznamenejte si název aplikace, který použijete později v tomto kurzu.

Vytvoření tokenů rozhraní API

Pomocí následujících požadavků na rovinu dat vytvořte tokeny rozhraní API aplikace ve vaší aplikaci IoT Central. Některé požadavky v tomto kurzu vyžadují token rozhraní API s oprávněními správce, ale většina může používat oprávnění operátora:

Pokud chcete vytvořit token operátoru volaný operator-token pomocí Azure CLI, spusťte následující příkaz. Identifikátor GUID role je ID role operátora ve všech aplikacích 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"}]}'

Poznamenejte si token operátoru, který příkaz vrátí, použijete ho později v kurzu. Token vypadá jako SharedAccessSignature sr=2....

Pokud chcete vytvořit token správce volaný admin-token pomocí Azure CLI, spusťte následující příkaz. Identifikátor GUID role je ID role správce ve všech aplikacích 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"}]}'

Poznamenejte si token správce, který příkaz vrátí, použijete ho později v kurzu. Token vypadá jako SharedAccessSignature sr=2....

Pokud chcete tyto tokeny zobrazit v aplikaci IoT Central, otevřete aplikaci a přejděte na tokeny rozhraní API pro oprávnění > zabezpečení>.

Registrace zařízení

Před připojením je nutné zaregistrovat zařízení ve službě IoT Central. Pomocí následujících požadavků zaregistrujte zařízení v aplikaci a načtěte přihlašovací údaje zařízení. První požadavek vytvoří zařízení s ID zařízení phone-001 :

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"

Poznamenejte idScope si hodnoty, primaryKey které příkaz vrátí, použijete je později v kurzu.

Zřízení a připojení zařízení

Abyste se vyhnuli nutnosti ručního zadávání přihlašovacích údajů zařízení na smartphonu, můžete použít kód QR vygenerovaný službou IoT Central. Kód QR kóduje ID zařízení, rozsah ID, primární klíč. Zobrazení kódu QR:

Otevřete aplikaci IoT Central pomocí adresy URL aplikace, kterou jste si poznamenali dříve.
V aplikaci IoT Central přejděte na Zařízení > Moje telefonní aplikace > Připojit > kód QR. Nechte tuto stránku otevřenou, dokud nebude zařízení připojené.

Snímek obrazovky znázorňující kód QR, který používáte k připojení zařízení

Pro zjednodušení nastavení tento článek používá aplikaci IoT technologie Plug and Play smartphone jako zařízení IoT. Aplikace odesílá telemetrická data shromážděná ze senzorů smartphonu, reaguje na příkazy vyvolané z IoT Central a hlásí hodnoty vlastností do IoT Central.

Nainstalujte si aplikaci na smartphone z některého z obchodů s aplikacemi:

Připojení aplikace IoT technologie Plug and Play k aplikaci Iot Central:

Na smartphonu otevřete aplikaci IoT PnP .
Na úvodní stránce vyberte Naskenovat kód QR. Nasměrujte fotoaparát smartphonu na kód QR. Pak počkejte několik sekund, než se naváže připojení.
Na stránce telemetrie v aplikaci uvidíte data, která aplikace odesílá do IoT Central. Na stránce protokolů se zobrazí připojení zařízení a několik inicializačních zpráv.

Pokud chcete ověřit, že je zařízení teď zřízené, můžete použít rozhraní REST API:

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"

Poznamenejte si hodnotu, kterou template příkaz vrátí, použijete ji později v kurzu.

Rozhraní REST API můžete použít ke správě šablon zařízení v aplikaci. Pokud chcete například zobrazit šablony zařízení v aplikaci:

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"

Dotazování a řízení zařízení

K dotazování telemetrie ze zařízení můžete použít rozhraní REST API. Následující požadavek vrátí data akcelerometru ze všech zařízení, která sdílejí konkrétní ID šablony zařízení:

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"

Rozhraní REST API můžete použít ke čtení a nastavení vlastností zařízení. Následující požadavek vrátí všechny hodnoty vlastností ze komponenty Informace o zařízení, kterou zařízení implementuje:

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"

K volání příkazů zařízení můžete použít rozhraní REST API. Následující požadavek volá příkaz, který dvakrát zapne světlo na smartphonu po dobu tří sekund. Aby se příkaz spustil, musí být obrazovka smartphonu zapnutá pomocí aplikace IoT technologie Plug and Play viditelné:

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

Vyčištění prostředků

Pokud jste dokončili aplikaci IoT Central, kterou jste použili v tomto kurzu, můžete ji odstranit:

appName=<the app name generated previously>

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

Sdílet prostřednictvím