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.comelementu . 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.comelementu . Ten token elementu nośnego służy do tworzenia tokenów interfejsu API w aplikacji usługi IoT Central.
• Administracja istrator i tokeny interfejsu API 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.comelementu :

  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.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.

  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.

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie utwórz aplikację usługi IoT Central.
2. Wybierz Wyślij.
3. Sprawdź, czy żądanie zakończy się powodzeniem. Jeśli nie powiedzie się, sprawdź, czy wprowadzono wartości zmiennych bearerToken i subscriptionId w kolekcji Postman.
4. 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:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie tworzenia tokenuoperatora.
2. Wybierz Wyślij.
3. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie tworzenia tokenuadministratora.
4. 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:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie Dodaj urządzenie.
2. Wybierz Wyślij. W odpowiedzi zwróć uwagę, że urządzenie nie jest aprowidowane.
3. W narzędziu Postman otwórz kolekcję samouczków rest usługi IoT Central i wybierz żądanie Pobierz poświadczenia urządzenia.
4. Wybierz Wyślij.
5. 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:

1. Otwórz aplikację usługi IoT Central przy użyciu adresu URL aplikacji zanotowany wcześniej.
2. W aplikacji usługi IoT Central przejdź do pozycji Urządzenia > Moja aplikacja > na telefon Połączenie > 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:

1. Otwórz aplikację IoT PnP na smartfonie.

2. Na stronie powitalnej wybierz pozycję Skanuj kod QR. Wskaż aparat smartfona w kodzie QR. Następnie zaczekaj kilka sekund na nawiązanie połączenia.

3. 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:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie Pobierz urządzenie.
2. 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:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie Wyświetl szablony urządzeń.
2. 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:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz pozycję Uruchom żądanie zapytania.
2. 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:

1. 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.
2. 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 :

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie polecenia Wywołaj.
2. 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:

1. Przejdź do pozycji RequestBin.
2. Wybierz pozycję Utwórz element RequestBin.
3. Zaloguj się przy użyciu jednej z dostępnych metod.
4. Skopiuj adres URL punktu końcowego RequestBin.
5. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i przejdź do zmiennych kolekcji.
6. Wklej adres URL punktu końcowego RequestBin do kolumny Current value for webHookURL w zmiennych kolekcji.
7. Zapisz zmiany.

Aby skonfigurować miejsce docelowe eksportu w aplikacji usługi IoT Central przy użyciu interfejsu API REST:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie utwórz docelowy eksport elementu webhook.
2. Wybierz Wyślij.

Aby skonfigurować definicję eksportu w aplikacji usługi IoT Central przy użyciu interfejsu API REST:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie tworzenia definicji eksportu telemetrii.
2. 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:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie Pobierz eksport według identyfikatora.
2. 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:

1. W narzędziu Postman otwórz kolekcję samouczków REST usługi IoT Central i wybierz żądanie usuń aplikację usługi IoT Central.
2. 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.comelementu .

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:

Tworzenie szablonu urządzenia bramy