Samouczek: zarządzanie aplikacją usługi Azure IoT Central przy użyciu interfejsu API REST
W tym samouczku pokazano, jak używać interfejsu API REST usługi Azure IoT Central do tworzenia aplikacji usługi IoT Central i interakcji z nią. W tym samouczku użyto interfejsu API REST, aby wykonać wiele kroków wykonanych przy użyciu internetowego interfejsu użytkownika w przewodnikach Szybki start. Te kroki obejmują używanie aplikacji na smartfonie jako urządzenia IoT, które łączy się z usługą IoT Central.
Z tego samouczka dowiesz się, jak wykonywać następujące czynności:
- Autoryzowanie interfejsu API REST.
- Utwórz aplikację usługi IoT Central.
- Dodaj urządzenie do aplikacji.
- Wykonywanie zapytań i kontrolowanie urządzenia.
- Konfigurowanie eksportu danych.
- Usuń aplikację.
Wymagania wstępne
Aby wykonać kroki opisane w tym samouczku, potrzebne są następujące elementy:
Aktywna subskrypcja platformy Azure. Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
Smartfon z systemem Android lub iOS, na którym można zainstalować bezpłatną aplikację z jednego z oficjalnych sklepów z aplikacjami.
Interfejs wiersza polecenia platformy Azure
Interfejs wiersza polecenia platformy Azure służy do tworzenia wywołań interfejsu API REST i generowania tokenów elementu nośnego używanych przez niektóre interfejsy API REST do autoryzacji.
Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.
Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.
Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.
Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.
Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.
Autoryzowanie interfejsu API REST
Przed rozpoczęciem korzystania z interfejsu API REST należy skonfigurować autoryzację. Wywołania interfejsu API REST w tym samouczku używają jednego z dwóch typów autoryzacji:
- Token elementu nośnego, który autoryzuje dostęp do
https://apps.azureiotcentral.comelementu . Ten token elementu nośnego służy do tworzenia tokenów interfejsu API w aplikacji usługi IoT Central. - Tokeny interfejsu API administratora i operatora, które autoryzować dostęp do funkcji w aplikacji usługi IoT Central. Te tokeny są używane dla większości wywołań interfejsu API w tym samouczku. Te tokeny autoryzować tylko dostęp do jednej konkretnej aplikacji usługi IoT Central.
Uruchom następujące polecenia interfejsu wiersza polecenia platformy Azure, aby wygenerować token elementu nośnego, który autoryzuje dostęp do https://apps.azureiotcentral.comelementu :
az account get-access-token --resource https://apps.azureiotcentral.com
Napiwek
Jeśli uruchomiono nowe wystąpienie powłoki, uruchom az login je ponownie.
Zanotuj accessToken wartość, której użyjesz w dalszej części samouczka.
Uwaga
Tokeny elementu nośnego wygasają po godzinie. Jeśli wygasną, uruchom te same polecenia, aby wygenerować nowe tokeny elementu nośnego.
Tworzenie grupy zasobów
Użyj interfejsu wiersza polecenia platformy Azure, aby utworzyć grupę zasobów zawierającą aplikację usługi IoT Central utworzoną w tym samouczku:
az group create --name iot-central-rest-tutorial --location eastus
Tworzenie aplikacji usługi IoT Central
Użyj następującego polecenia, aby wygenerować aplikację usługi IoT Central z losową nazwą do użycia w tym samouczku:
appName=app-rest-$(date +%s)
az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName
Zanotuj nazwę aplikacji, której użyjesz w dalszej części tego samouczka.
Tworzenie tokenów interfejsu API
Użyj następujących żądań płaszczyzny danych, aby utworzyć tokeny interfejsu API aplikacji w aplikacji usługi IoT Central. Niektóre żądania w tym samouczku wymagają tokenu interfejsu API z uprawnieniami administratora, ale większość może używać uprawnień operatora:
Aby utworzyć token operatora wywoływany operator-token przy użyciu interfejsu wiersza polecenia platformy Azure, uruchom następujące polecenie. Identyfikator GUID roli jest identyfikatorem roli operatora we wszystkich aplikacjach usługi 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"}]}'
Zanotuj token operatora zwracany przez polecenie. Użyj go w dalszej części samouczka. Token wygląda następująco: SharedAccessSignature sr=2....
Aby utworzyć token administratora wywoływany admin-token przy użyciu interfejsu wiersza polecenia platformy Azure, uruchom następujące polecenie. Identyfikator GUID roli jest identyfikatorem roli administratora we wszystkich aplikacjach usługi 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"}]}'
Zanotuj token administratora zwracany przez polecenie. Użyj go w dalszej części samouczka. Token wygląda następująco: SharedAccessSignature sr=2....
Jeśli chcesz zobaczyć te tokeny w aplikacji usługi IoT Central, otwórz aplikację i przejdź do pozycji Tokeny interfejsu API uprawnień > zabezpieczeń>.
Rejestrowanie urządzenia
Aby można było nawiązać połączenie, musisz zarejestrować urządzenie w usłudze IoT Central. Użyj następujących żądań, aby zarejestrować urządzenie w aplikacji i pobrać poświadczenia urządzenia. Pierwsze żądanie tworzy urządzenie z numerem phone-001 jako identyfikator urządzenia:
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"
Zanotuj idScope wartości i primaryKey zwracane przez polecenie , a następnie użyjesz ich w dalszej części samouczka.
Aprowizuj urządzenie i połącz je
Aby uniknąć konieczności ręcznego wprowadzania poświadczeń urządzenia na smartfonie, możesz użyć kodu QR wygenerowanego przez usługę IoT Central. Kod QR koduje identyfikator urządzenia, zakres identyfikatora, klucz podstawowy. Aby wyświetlić kod QR:
- Otwórz aplikację usługi IoT Central przy użyciu adresu URL aplikacji zanotowany wcześniej.
- W aplikacji usługi IoT Central przejdź do pozycji Urządzenia > Moja aplikacja > telefonu Połącz > kod QR. Pozostaw tę stronę otwartą do momentu połączenia urządzenia.
Aby uprościć konfigurację, w tym artykule użyto aplikacji smartfonu IoT Plug and Play jako urządzenia IoT. Aplikacja wysyła dane telemetryczne zebrane z czujników smartfona, reaguje na polecenia wywoływane z usługi IoT Central i zgłasza wartości właściwości do usługi IoT Central.
Zainstaluj aplikację na smartfonie z jednego ze sklepów z aplikacjami:
Aby połączyć aplikację IoT Plug and Play z aplikacją usługi IoT Central:
Otwórz aplikację IoT PnP na smartfonie.
Na stronie powitalnej wybierz pozycję Skanuj kod QR. Wskaż aparat smartfona w kodzie QR. Następnie zaczekaj kilka sekund na nawiązanie połączenia.
Na stronie telemetrii w aplikacji widać dane wysyłane przez aplikację do usługi IoT Central. Na stronie dzienników można zobaczyć połączenie urządzenia i kilka komunikatów inicjowania.
Aby sprawdzić, czy urządzenie jest teraz aprowidowane, możesz użyć interfejsu 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"
Zanotuj template wartość zwracaną przez polecenie. Użyj go w dalszej części samouczka.
Interfejs API REST umożliwia zarządzanie szablonami urządzeń w aplikacji. Aby na przykład wyświetlić szablony urządzeń w aplikacji:
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"
Wykonywanie zapytań i kontrolowanie urządzenia
Interfejs API REST umożliwia wykonywanie zapytań dotyczących danych telemetrycznych z urządzeń. Następujące żądanie zwraca dane akcelerometru ze wszystkich urządzeń, które współużytkują określony identyfikator szablonu urządzenia:
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"
Interfejs API REST umożliwia odczytywanie i ustawianie właściwości urządzenia. Następujące żądanie zwraca wszystkie wartości właściwości ze składnika Informacje o urządzeniu, który implementuje urządzenie:
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"
Interfejs API REST umożliwia wywoływanie poleceń urządzenia. Następujące żądanie wywołuje polecenie, które włącza światło na smartfonie dwa razy przez trzy sekundy. Aby można było uruchomić polecenie, ekran smartfona musi być włączony z widoczną aplikacją IoT Plug and Play :
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}'
Czyszczenie zasobów
Jeśli skończysz z aplikacją usługi IoT Central używaną w tym samouczku, możesz ją usunąć:
appName=<the app name generated previously>
az iot central app delete --name $appName --resource-group iot-central-rest-tutorial