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 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.
Postman
W tym samouczku użyjesz narzędzia Postman do wykonania wywołań interfejsu API REST. Jeśli nie chcesz pobierać i instalować narzędzia Postman, możesz użyć wersji online. Wszystkie kroki opisane w samouczku można wykonać przy użyciu bezpłatnej wersji narzędzia Postman.
W samouczku użyto wstępnie zdefiniowanej kolekcji Postman, która zawiera niektóre skrypty ułatwiające wykonanie tych kroków.
Importuj kolekcję Postman
Aby zaimportować kolekcję, otwórz narzędzie Postman i wybierz pozycję Importuj. W oknie dialogowym Importowanie wybierz pozycję Połącz i wklej następujący adres URL, a następnie wybierz pozycję Kontynuuj.
Obszar roboczy zawiera teraz kolekcję samouczków REST usługi IoT Central. Ta kolekcja zawiera wszystkie interfejsy API używane w samouczku.
Kolekcja używa zmiennych do parametryzacji wywołań interfejsu API REST. Aby wyświetlić zmienne, wybierz ...
obok samouczka REST usługi IoT Central i wybierz pozycję Edytuj. Następnie wybierz pozycję Zmienne. Wiele zmiennych jest ustawianych automatycznie podczas tworzenia wywołań interfejsu API lub mają wartości wstępne.
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 trzech typów autoryzacji:
- Token elementu nośnego, który autoryzuje dostęp do
https://management.azure.com
elementu . Ten token elementu nośnego jest używany podczas tworzenia i usuwania aplikacji usługi IoT Central. Aplikacja usługi IoT Central jest zasobem platformy Azure. - Token elementu nośnego, który autoryzuje dostęp do
https://apps.azureiotcentral.com
elementu . 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.
Przypisz wartości do następujących zmiennych w kolekcji Postman:
bearerToken: uruchom następujące polecenia interfejsu wiersza polecenia platformy Azure, aby wygenerować token elementu nośnego, który autoryzuje dostęp do
https://management.azure.com
elementu :az login az account get-access-token --resource https://management.azure.com
Napiwek
Może być konieczne uruchomienie
az login
, nawet jeśli używasz usługi Cloud Shell.Skopiuj wartość do kolumny Bieżąca
accessToken
wartość elementu bearerToken w zmiennych kolekcji.bearerTokenApp: 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.com
elementu :az account get-access-token --resource https://apps.azureiotcentral.com
Napiwek
Jeśli uruchomiono nowe wystąpienie powłoki, uruchom
az login
je ponownie.accessToken
Skopiuj wartość do kolumny Current value dla elementu bearerTokenApp w zmiennych kolekcji.subscriptionId: Identyfikator subskrypcji został uwzględniony w danych wyjściowych z dwóch poprzednich poleceń.
subscription
Skopiuj wartość do kolumny Current value for subscriptionId w zmiennych kolekcji.
Pamiętaj, aby zapisać zmiany w kolekcji Postman.
Uwaga
Tokeny elementu nośnego wygasają po godzinie.
Tworzenie aplikacji
Użyj żądań płaszczyzny sterowania, aby utworzyć aplikacje usługi IoT Central i zarządzać nimi. Użyj następującego żądania PUT , aby utworzyć aplikację używaną w tym samouczku. Żądanie używa tokenu elementu nośnego do autoryzowania i generowania losowej nazwy aplikacji.
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie utwórz aplikację usługi IoT Central.
- Wybierz Wyślij.
- Sprawdź, czy żądanie zakończy się powodzeniem. Jeśli nie powiedzie się, sprawdź, czy wprowadzono wartości zmiennych bearerToken i subscriptionId w kolekcji Postman.
- Wybierz pozycję Visualize (Wizualizacja), aby wyświetlić adres URL nowej aplikacji usługi IoT Central. Zanotuj ten adres URL. Będzie on potrzebny 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:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie tworzenia tokenu operatora.
- Wybierz Wyślij.
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie tworzenia tokenu administratora.
- Wybierz Wyślij.
Jeśli chcesz zobaczyć te tokeny w aplikacji usługi IoT Central, otwórz aplikację i przejdź do pozycji Tokeny interfejsu API uprawnień > zabezpieczeń>.
Uwaga
Skrypt w narzędziu Postman automatycznie dodaje te tokeny interfejsu API do listy zmiennych kolekcji.
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:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie Dodaj urządzenie.
- Wybierz Wyślij. W odpowiedzi zwróć uwagę, że urządzenie nie jest aprowidowane.
- W narzędziu Postman otwórz kolekcję samouczków rest usługi IoT Central i wybierz żądanie Pobierz poświadczenia urządzenia.
- Wybierz Wyślij.
- Na karcie Wizualizacja są wyświetlane wartości Zakres identyfikatorów i Klucz podstawowy, których urządzenie potrzebuje do nawiązania połączenia.
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:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie Pobierz urządzenie.
- Wybierz Wyślij. W odpowiedzi zwróć uwagę, że urządzenie jest teraz aprowidowane. Usługa IoT Central przypisał również szablon urządzenia do urządzenia na podstawie identyfikatora modelu wysyłanego przez urządzenie.
Interfejs API REST umożliwia zarządzanie szablonami urządzeń w aplikacji. Aby na przykład wyświetlić szablony urządzeń w aplikacji:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie Wyświetl szablony urządzeń.
- Wybierz Wyślij.
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:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz pozycję Uruchom żądanie zapytania.
- Wybierz Wyślij.
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:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz pozycję Pobierz właściwości z żądania składnika.
- Wybierz Wyślij.
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 :
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie polecenia Wywołaj.
- Wybierz Wyślij.
Eksportowanie telemetrii
Za pomocą interfejsu API REST można skonfigurować aplikację usługi IoT Central i zarządzać nią. W poniższych krokach pokazano, jak skonfigurować eksport danych w celu wysyłania wartości telemetrycznych do elementu webhook. Aby uprościć konfigurację, w tym artykule jako miejsce docelowe jest używane element webhook RequestBin . RequestBin to usługa firmy innej niż Microsoft.
Aby utworzyć testowy punkt końcowy dla miejsca docelowego eksportu danych:
- Przejdź do pozycji RequestBin.
- Wybierz pozycję Utwórz element RequestBin.
- Zaloguj się przy użyciu jednej z dostępnych metod.
- Skopiuj adres URL punktu końcowego RequestBin.
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i przejdź do zmiennych kolekcji.
- Wklej adres URL punktu końcowego RequestBin do kolumny Current value for webHookURL w zmiennych kolekcji.
- Zapisz zmiany.
Aby skonfigurować miejsce docelowe eksportu w aplikacji usługi IoT Central przy użyciu interfejsu API REST:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie utwórz docelowy eksport elementu webhook.
- Wybierz Wyślij.
Aby skonfigurować definicję eksportu w aplikacji usługi IoT Central przy użyciu interfejsu API REST:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie tworzenia definicji eksportu telemetrii.
- Wybierz Wyślij. Zwróć uwagę, że stan to Nie uruchomiono.
Rozpoczęcie eksportu może potrwać kilka minut. Aby sprawdzić stan eksportu przy użyciu interfejsu API REST:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie Pobierz eksport według identyfikatora.
- Wybierz Wyślij. Gdy stan jest w dobrej kondycji, usługa IoT Central wysyła dane telemetryczne do elementu webhook.
Aplikacja na smartfonie nie wysyła danych telemetrycznych, chyba że ekran jest włączony, a aplikacja IoT Plug and Play jest widoczna.
Gdy aplikacja na smartfony wysyła dane telemetryczne, przejdź do elementu RequestBin, aby wyświetlić wyeksportowane dane telemetryczne.
Czyszczenie zasobów
Jeśli skończysz z aplikacją usługi IoT Central używaną w tym samouczku, możesz usunąć ją przy użyciu interfejsu API REST:
- W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie usuń aplikację usługi IoT Central.
- Wybierz Wyślij.
Napiwek
To żądanie używa tokenu elementu nośnego wygenerowanego na początku samouczka. Tokeny elementu nośnego wygasają po godzinie. Może być konieczne wygenerowanie nowego tokenu elementu nośnego, który autoryzuje dostęp do https://apps.azureiotcentral.com
elementu .
Następne kroki
Jeśli wolisz kontynuować korzystanie z zestawu samouczków usługi IoT Central i dowiedzieć się więcej o tworzeniu rozwiązania usługi IoT Central, zobacz: