Samouczek: aprowizuj urządzenia przy użyciu grup rejestracji kluczy symetrycznych

  • Artykuł

W tym samouczku pokazano, jak bezpiecznie aprowizować wiele symulowanych urządzeń kluczy symetrycznych do pojedynczej usługi IoT Hub przy użyciu grupy rejestracji.

Usługa Azure IoT Hub Device Provisioning obsługuje dwa typy rejestracji na potrzeby aprowizacji urządzeń:

  • Grupy rejestracji: służą do rejestrowania wielu pokrewnych urządzeń. W tym samouczku przedstawiono aprowizowanie przy użyciu grup rejestracji.
  • Rejestracje indywidualne: służy do rejestrowania pojedynczego urządzenia.

Usługa Azure IoT Hub Device Provisioning obsługuje trzy formy uwierzytelniania na potrzeby aprowizacji urządzeń:

  • Certyfikaty X.509
  • Moduł TPM (Trusted Platform Module)
  • Klucze symetryczne — w tym samouczku przedstawiono zaświadczanie klucza symetrycznego

Niektóre urządzenia mogą nie mieć certyfikatu, modułu TPM ani żadnej innej funkcji zabezpieczeń, która może służyć do bezpiecznego identyfikowania urządzenia. W przypadku takich urządzeń usługa Azure IoT Hub Device Provisioning Service (DPS) obejmuje zaświadczanie klucza symetrycznego. Zaświadczanie klucza symetrycznego może służyć do identyfikowania urządzenia na podstawie unikatowych informacji, takich jak adres MAC lub numer seryjny.

W tym samouczku wykonasz następujące cele:

  • Zdefiniuj unikatowy identyfikator rejestracji dla każdego urządzenia.
  • Utwórz grupę rejestracji korzystającą z zaświadczania klucza symetrycznego.
  • Utwórz klucz urządzenia dla każdego urządzenia przy użyciu jego unikatowego identyfikatora rejestracji i klucza grupy rejestracji udostępnionej.
  • Aprowizuj urządzenia przy użyciu klucza urządzenia i przykładowego kodu w zestawach SDK urządzeń azure IoT.

Ten samouczek jest zorientowany na stację roboczą opartą na systemie Windows. Jednak opisane procedury można wykonać także w systemie Linux. Aby zapoznać się z przykładem systemu Linux, zobacz Samouczek: aprowizowanie opóźnienia geograficznego.

Uwaga

Jeśli wcześniej ukończono przewodnik Szybki start: aprowizuj symulowane urządzenie klucza symetrycznego i nadal masz skonfigurowane zasoby platformy Azure i środowisko programistyczne, możesz przejść do sekcji Tworzenie grupy rejestracji klucza symetrycznego w tym samouczku.

Wymagania wstępne

  • Jeśli używasz środowiska deweloperskiego systemu Windows, zainstaluj program Visual Studio 2022 z włączonym obciążeniem "Programowanie aplikacji klasycznych z językiem C++". Obsługiwane są również programy Visual Studio 2019, Visual Studio 2017 i Visual Studio 2015. W przypadku systemu Linux lub macOS zapoznaj się z odpowiednią sekcją w temacie Przygotowywanie środowiska projektowego w dokumentacji zestawu SDK.

  • Zainstaluj najnowszy system kompilacji narzędzia CMake. Upewnij się, że zaznaczono opcję, która dodaje plik wykonywalny narzędzia CMake do ścieżki.

    Ważne

    Przed rozpoczęciem CMake instalacji upewnij się, że na maszynie są zainstalowane wymagania wstępne programu Visual Studio (Program Visual Studio i pakiet roboczy Programowanie aplikacji klasycznych z językiem C++). Gdy wymagania wstępne zostaną spełnione, a pobrane pliki zweryfikowane, zainstaluj system kompilacji CMake. Należy również pamiętać, że starsze wersje systemu kompilacji CMake nie mogą wygenerować pliku rozwiązania używanego w tym artykule. Upewnij się, że używasz najnowszej wersji narzędzia CMake.

  • Zainstaluj zestaw .NET SDK 6.0 lub nowszy na maszynie z systemem Windows. Aby sprawdzić wersję, możesz użyć następującego polecenia.

    dotnet --info
  • Zainstaluj środowisko Python w wersji 3.7 lub nowszej zainstalowanej na komputerze z systemem Windows. Możesz sprawdzić swoją wersję języka Python, uruchamiając polecenie python --version.

przygotowywanie środowiska programistycznego

W tej sekcji przygotujesz środowisko programistyczne do skompilowania zestawu SDK urządzeń usługi Azure IoT dla języka C. Przykładowy kod aprowizuje urządzenie podczas sekwencji rozruchu urządzenia.

  1. W przeglądarce internetowej przejdź do strony Wydanie zestawu AZURE IoT C SDK.

  2. Skopiuj nazwę tagu dla najnowszej wersji zestawu AZURE IoT C SDK, na przykład: lts_03_2024.

  3. Otwórz wiersz polecenia systemu Windows i uruchom następujące polecenia, aby sklonować najnowszą wersję zestawu AZURE IoT Device SDK for C GitHub. Zastąp <release-tag> element tagiem skopiowanymi w poprzednim kroku.

    git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

    Wykonanie tej operacji może potrwać kilka minut.

  4. Po zakończeniu operacji uruchom następujące polecenia z azure-iot-sdk-c katalogu:

    mkdir cmake
cd cmake

  5. Przykładowy kod używa klucza symetrycznego do zapewnienia zaświadczania. Uruchom następujące polecenie, aby skompilować wersję zestawu SDK specyficzną dla platformy klienta programowania, która obejmuje klienta aprowizacji urządzeń:

    cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..

    Napiwek

    Jeśli cmake nie znajdziesz kompilatora języka C++, podczas uruchamiania powyższego polecenia mogą wystąpić błędy kompilacji. W takim przypadku spróbuj uruchomić polecenie w wierszu polecenia programu Visual Studio.

  6. Po pomyślnym zakończeniu kompilacji ostatnie kilka wierszy wyjściowych będzie wyglądać podobnie do następujących danych wyjściowych:

    $ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
-- Building for: Visual Studio 16 2019
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.22621.
-- The C compiler identification is MSVC 19.29.30146.0
-- The CXX compiler identification is MSVC 19.29.30146.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: C:/azure-iot-sdk-c/cmake

  1. Otwórz wiersz polecenia lub terminal powłoki Git Bash.

  2. Sklonuj repozytorium GitHub zestawu AZURE IoT SDK dla języka C# przy użyciu następującego polecenia:

    git clone https://github.com/Azure/azure-iot-sdk-csharp.git

  1. Otwórz wiersz polecenia lub terminal powłoki Git Bash.

  2. Sklonuj zestaw SDK usługi Azure IoT dla repozytorium Node.js GitHub przy użyciu następującego polecenia:

    git clone https://github.com/Azure/azure-iot-sdk-node.git --recursive

  1. Otwórz wiersz polecenia lub terminal powłoki Git Bash.

  2. Sklonuj repozytorium GitHub zestawu SDK urządzeń usługi Azure IoT dla języka Python przy użyciu następującego polecenia:

    git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive

    Uwaga

    Przykłady używane w tym samouczku znajdują się w gałęzi w wersji 2 repozytorium azure-iot-sdk-python. Wersja 3 zestawu SDK języka Python jest dostępna do użycia w wersji beta. Aby uzyskać informacje na temat aktualizowania przykładów kodu w wersji 2 w celu korzystania z wersji 3 zestawu SDK języka Python, zobacz Przewodnik migracji zestawu SDK urządzeń usługi Azure IoT dla języka Python.

  1. Otwórz wiersz polecenia lub terminal powłoki Git Bash.

  2. Sklonuj repozytorium GitHub zestawu SDK usługi Azure IoT dla języka Java przy użyciu następującego polecenia:

    git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive

  3. Przejdź do katalogu głównego azure-iot-sdk-java i skompiluj projekt, aby pobrać wszystkie potrzebne pakiety. Wykonanie tego kroku może potrwać kilka minut.

    cd azure-iot-sdk-java
mvn install -DskipTests=true

Tworzenie grupy rejestracji klucza symetrycznego

  1. Zaloguj się do witryny Azure Portal i przejdź do wystąpienia usługi Device Provisioning Service.

  2. Wybierz pozycję Zarządzaj rejestracjami w sekcji Ustawienia menu nawigacji.

  3. Wybierz pozycję Dodaj grupę rejestracji.

  4. Na karcie Rejestracja i aprowizacja na stronie Dodawanie grupy rejestracji podaj następujące informacje, aby skonfigurować szczegóły grupy rejestracji:

    Pole opis
    Zaświadczanie Wybierz pozycję Klucz symetryczny jako mechanizm zaświadczania.
    Ustawienia klucza symetrycznego Zaznacz pole Automatycznie Generuj klucze symetryczne, jeśli chcesz użyć losowo wygenerowanych kluczy. Usuń zaznaczenie tego pola, jeśli chcesz podać własne klucze.
    Nazwa grupy Podaj nazwę grupy urządzeń. Nazwa grupy rejestracji jest ciągiem bez uwzględniania wielkości liter (do 128 znaków) znaków alfanumerycznych oraz znakami specjalnymi: '-', , '.''_', ':'. Ostatni znak musi być alfanumeryczny lub kreskowy ('-').
    Stan aprowizacji Zaznacz pole Włącz tę rejestrację, jeśli ta grupa rejestracji ma być dostępna do aprowizowania urządzeń. Usuń zaznaczenie tego pola, jeśli chcesz, aby grupa została wyłączona. To ustawienie można zmienić później.
    Zasady ponownej aprowizacji Wybierz zasady ponownej aprowizacji, które odzwierciedlają sposób obsługi urządzeń, które żądają ponownej aprowizacji przez usługę DPS. Aby uzyskać więcej informacji, zobacz Zasady ponownej aprowizacji

    Screenshot that shows adding an enrollment group for symmetric key attestation.

  5. Wybierz pozycję Dalej: centra IoT.

  6. Na karcie Centra IoT na stronie Dodawanie grupy rejestracji podaj następujące informacje, aby określić, które centra IoT mogą aprowizować urządzenia do:

    Pole opis
    Docelowe centra IoT Wybierz co najmniej jedno połączone centra IoT lub dodaj nowy link do centrum IoT. Aby dowiedzieć się więcej na temat łączenia centrów IoT z wystąpieniem usługi DPS, zobacz Jak połączyć centra IoT i zarządzać nimi.
    Zasady alokacji Jeśli wybrano więcej niż jedno połączone centrum IoT, wybierz sposób przypisywania urządzeń do różnych centrów. Aby dowiedzieć się więcej na temat zasad alokacji, zobacz Jak używać zasad alokacji.

    Jeśli wybrano tylko jedno połączone centrum IoT, zalecamy użycie zasad dystrybucji równomiernie ważonej.

    Screenshot that shows connecting IoT hubs to the new enrollment group.

  7. Wybierz pozycję Dalej: Ustawienia urządzenia

  8. Na karcie Ustawienia urządzenia na stronie Dodawanie grupy rejestracji podaj następujące informacje, aby zdefiniować sposób konfigurowania nowo aprowizowania urządzeń:

    Pole opis
    IoT Edge Sprawdź włączanie usługi IoT Edge na aprowidowanych urządzeniach, jeśli wszystkie urządzenia aprowidowane za pośrednictwem tej grupy będą uruchamiać usługę Azure IoT Edge. Usuń zaznaczenie tego pola, jeśli ta grupa dotyczy tylko urządzeń z obsługą usługi IoT Edge. Wszystkie urządzenia w grupie będą włączone w usłudze IoT Edge lub żadna z nich nie może być.
    Tagi urządzeń Użyj tego pola tekstowego, aby podać wszystkie tagi, które mają być stosowane do bliźniaczych reprezentacji urządzeń aprowizowania.
    Żądane właściwości Użyj tego pola tekstowego, aby podać żądane właściwości, które mają zostać zastosowane do bliźniaczych reprezentacji urządzeń aprowizowania.

    Aby uzyskać więcej informacji, zobacz Opis bliźniaczej reprezentacji urządzenia w usłudze IoT Hub oraz sposoby jej używania.

  9. Wybierz pozycję Dalej: Przeglądanie i tworzenie.

  10. Na karcie Przeglądanie i tworzenie sprawdź wszystkie wartości, a następnie wybierz pozycję Utwórz.

Podczas tworzenia grupy rejestracji usługa DPS generuje klucz podstawowy i klucz pomocniczy, a następnie dodaje je do wpisu rejestracji. Grupa rejestracji klucza symetrycznego jest wyświetlana w kolumnie Nazwa grupy na karcie Grupy rejestracji.

Otwórz rejestrację i skopiuj wartość klucza podstawowego. Ten klucz jest kluczem grupy.

Wybieranie unikatowego identyfikatora rejestracji dla urządzenia

Aby zidentyfikować każde urządzenie, należy zdefiniować unikatowy identyfikator rejestracji. Możesz użyć adresu MAC, numeru seryjnego lub wszelkich unikatowych informacji z urządzenia.

W tym przykładzie używamy kombinacji adresu MAC i numeru seryjnego tworzącego następujący ciąg dla identyfikatora rejestracji.

sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6

Utwórz unikatowe identyfikatory rejestracji dla każdego urządzenia. Identyfikator rejestracji jest ciągiem bez uwzględniania wielkości liter (do 128 znaków) znaków alfanumerycznych oraz następującymi znakami specjalnymi: - . _ :. Ostatni znak musi być alfanumeryczny lub kreskowy (-).

Uzyskiwanie klucza urządzenia

Aby wygenerować klucze urządzeń, użyj klucza podstawowego grupy rejestracji, aby obliczyć skrót HMAC-SHA256 identyfikatora rejestracji dla każdego urządzenia. Wynik jest następnie konwertowany na format Base 64 dla każdego urządzenia.

Ostrzeżenie

Kod urządzenia dla każdego urządzenia powinien zawierać tylko pochodny klucz urządzenia dla tego urządzenia. Nie dołączaj klucza podstawowego grupy do kodu urządzenia. Naruszony klucz grupy może naruszyć bezpieczeństwo wszystkich urządzeń uwierzytelnionych w ramach tego klucza.

Rozszerzenie IoT dla interfejsu wiersza polecenia platformy Azure udostępnia polecenie az iot dps enrollment-group compute-device-key do generowania pochodnych kluczy urządzeń. To polecenie może być używane zarówno z systemów Windows, jak i Linux.

Zastąp wartość --key parametru kluczem podstawowym z grupy rejestracji.

Zastąp wartość parametru --registration-id identyfikatorem rejestracji.

az iot dps enrollment-group compute-device-key --key <group_primary_key> --registration-id <device_registration_id>

Przykładowy wynik:

"Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc="

Każde urządzenie używa jego pochodnego klucza urządzenia i unikatowego identyfikatora rejestracji do przeprowadzania zaświadczania klucza symetrycznego z grupą rejestracji podczas aprowizacji.

Przygotowywanie i uruchamianie kodu aprowizacji urządzenia

W tej sekcji zaktualizujesz przykładowy kod urządzenia, aby wysłać sekwencję rozruchową urządzenia do wystąpienia usługi Device Provisioning Service. Ta sekwencja rozruchowa powoduje, że urządzenie zostanie rozpoznane, uwierzytelnione i przypisane do centrum IoT Połączone z wystąpieniem usługi Device Provisioning Service.

Przykładowy kod aprowizacji wykonuje następujące zadania w następującej kolejności:

  1. Uwierzytelnia urządzenie przy użyciu zasobu Device Provisioning przy użyciu następujących trzech parametrów:

    • Zakres identyfikatora usługi Device Provisioning Service
    • Identyfikator rejestracji urządzenia.
    • Klucz pochodnego urządzenia dla urządzenia.

  2. Przypisuje urządzenie do centrum IoT Hub, które jest już połączone z wystąpieniem usługi Device Provisioning Service.

Aby zaktualizować i uruchomić przykład aprowizacji przy użyciu informacji o urządzeniu:

  1. W menu głównym usługi Device Provisioning Wybierz pozycję Przegląd.

  2. Skopiuj wartość Zakres identyfikatora.

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. W programie Visual Studio otwórz plik rozwiązania azure_iot_sdks.sln, który został wygenerowany przez uruchomienie narzędzia CMake. Plik rozwiązania powinien znajdować się w następującej lokalizacji:

    
\azure-iot-sdk-c\cmake\azure_iot_sdks.sln

    Napiwek

    Jeśli plik nie został wygenerowany w katalogu cmake, upewnij się, że użyto najnowszej wersji systemu kompilacji narzędzia CMake.

  4. W oknie Eksplorator rozwiązań programu Visual Studio przejdź do folderu Provision_Samples. Rozwiń przykładowy projekt o nazwie prov_dev_client_sample. Rozwiń węzeł Pliki źródłowe i otwórz plik prov_dev_client_sample.c.

  5. Znajdź stałą id_scope i zastąp wartość wartością Zakres identyfikatora skopiowaną z witryny Azure Portal.

    static const char* id_scope = "0ne00002193";

  6. Znajdź definicję funkcji main() w tym samym pliku. Upewnij się, że zmienna hsm_type jest ustawiona na SECURE_DEVICE_TYPE_SYMMETRIC_KEY, jak pokazano poniżej:

    SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
//hsm_type = SECURE_DEVICE_TYPE_X509;
hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;

  7. Znajdź wywołanie metody prov_dev_set_symmetric_key_info() w pliku prov_dev_client_sample.c , które zostało skomentowane.

    // Set the symmetric key if using they auth type
//prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");

    Usuń komentarz z wywołania funkcji i zastąp wartości symboli zastępczych (w tym nawiasy kątowe) identyfikatorem rejestracji wybranym w obszarze Wybierz unikatowy identyfikator rejestracji dla urządzenia i klucz urządzenia pochodnego wygenerowany w sekcji Tworzenie klucza urządzenia.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6", "Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=");

    Uwaga

    Należy pamiętać, że ten krok pozostawia klucz pochodnego urządzenia dołączony jako część obrazu dla każdego urządzenia, co nie jest zalecanym najlepszym rozwiązaniem w zakresie zabezpieczeń. Jest to jeden z powodów, dla których bezpieczeństwo i łatwość użytkowania są często kompromisami. Należy w pełni przejrzeć zabezpieczenia urządzeń zgodnie z własnymi wymaganiami.

  8. Zapisz plik.

  9. Kliknij prawym przyciskiem myszy projekt prov_dev_client_sample i wybierz polecenie Ustaw jako projekt startowy.

  10. Z menu programu Visual Studio wybierz pozycję Debuguj>Uruchom bez debugowania, aby uruchomić rozwiązanie. W wierszu polecenia ponownego kompilowania projektu wybierz pozycję Tak , aby ponownie skompilować projekt przed uruchomieniem.

    Następujące dane wyjściowe to przykład pomyślnego nawiązania połączenia urządzenia z wystąpieniem usługi aprowizacji, które ma zostać przypisane do centrum IoT:

    Provisioning API Version: 1.9.1

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-hub-2.azure-devices.net, deviceId: sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6
Press enter key to exit:

Przykładowy kod aprowizacji wykonuje następujące zadania:

  1. Uwierzytelnia urządzenie przy użyciu zasobu Device Provisioning przy użyciu następujących trzech parametrów:

    • Zakres identyfikatora usługi Device Provisioning Service
    • Identyfikator rejestracji urządzenia.
    • Klucz pochodnego urządzenia dla urządzenia.

  2. Przypisuje urządzenie do centrum IoT Hub, które jest już połączone z wystąpieniem usługi Device Provisioning Service.

  3. Wysyła komunikat telemetrii testowej do centrum IoT.

Aby zaktualizować i uruchomić przykład aprowizacji przy użyciu informacji o urządzeniu:

  1. W menu głównym usługi Device Provisioning Wybierz pozycję Przegląd.

  2. Skopiuj wartość Zakres identyfikatora.

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. Otwórz wiersz polecenia i przejdź do pliku SymmetricKeySample w sklonowanym repozytorium zestawu SDK:

    cd .\azure-iot-sdk-csharp\provisioning\device\samples\how to guides\SymmetricKeySample

  4. W folderze SymmetricKeySample otwórz Parameters.cs w edytorze tekstów. Ten plik zawiera parametry, do których odwołuje się przykład. Podczas uruchamiania przykładu używane są tylko pierwsze trzy wymagane parametry. Przejrzyj kod w tym pliku. Nie są potrzebne żadne zmiany.

    Parametr Wymagania opis
    --i lub --IdScope Prawda Zakres identyfikatora wystąpienia usługi DPS
    --r lub --RegistrationId Prawda Identyfikator rejestracji urządzenia. Identyfikator rejestracji jest ciągiem bez uwzględniania wielkości liter (do 128 znaków) znaków alfanumerycznych oraz znakami specjalnymi: '-', , '.''_', ':'. Ostatni znak musi być alfanumeryczny lub kreskowy ('-').
    --p lub --PrimaryKey Prawda Klucz podstawowy rejestracji indywidualnej lub pochodnego klucza urządzenia rejestracji grupy.
    --g lub --GlobalDeviceEndpoint Fałsz Globalny punkt końcowy dla urządzeń do nawiązania połączenia. Wartości domyślne global.azure-devices-provisioning.net
    --t lub --TransportType Fałsz Transport używany do komunikowania się z wystąpieniem aprowizacji urządzeń. Wartość domyślna to Mqtt. Możliwe wartości obejmują Mqtt, , Mqtt_WebSocket_Only, AmqpAmqp_Tcp_onlyMqtt_Tcp_OnlyAmqp_WebSocket_Only, i .Http1

  5. W folderze SymmetricKeySample otwórz ProvisioningDeviceClientSample.cs w edytorze tekstów. Ten plik pokazuje, jak klasa SecurityProviderSymmetricKey jest używana wraz z klasą ProvisioningDeviceClient w celu aprowizacji symulowanego urządzenia klucza symetrycznego. Przejrzyj kod w tym pliku. Nie są potrzebne żadne zmiany.

  6. Skompiluj i uruchom przykładowy kod przy użyciu następującego polecenia:

    dotnet run --i <id-scope> --r <registration-id> --p <primarykey>

  7. Powinny zostać wyświetlone dane wyjściowe podobne do poniższych. Ciąg "TestMessage" jest wysyłany do centrum jako komunikat testowy.

    D:\azure-iot-sdk-csharp\provisioning\device\samples\how to guides\SymmetricKeySample>dotnet run --i 0ne00000A0A --r sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6 --p sbDDeEzRuEuGKag+kQKV+T1QGakRtHpsERLP0yPjwR93TrpEgEh/Y07CXstfha6dhIPWvdD1nRxK5T0KGKA+nQ==

Initializing the device provisioning client...
Initialized for registration Id sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6.
Registering with the device provisioning service...
Registration status: Assigned.
Device sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6 registered to contoso-hub-2.azure-devices.net.
Creating symmetric key authentication for IoT Hub...
Testing the provisioned device with IoT Hub...
Sending a telemetry message...
Finished.

Przykładowy kod aprowizacji wykonuje następujące zadania w następującej kolejności:

  1. Uwierzytelnia urządzenie przy użyciu zasobu Device Provisioning przy użyciu następujących czterech parametrów:

    • PROVISIONING_HOST
    • PROVISIONING_IDSCOPE
    • PROVISIONING_REGISTRATION_ID
    • PROVISIONING_SYMMETRIC_KEY

  2. Przypisuje urządzenie do centrum IoT Hub, które jest już połączone z wystąpieniem usługi Device Provisioning Service.

  3. Wysyła komunikat telemetrii testowej do centrum IoT.

Aby zaktualizować i uruchomić przykład aprowizacji przy użyciu informacji o urządzeniu:

  1. W menu głównym usługi Device Provisioning Wybierz pozycję Przegląd.

  2. Skopiuj wartość Zakres identyfikatora.

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. Otwórz wiersz polecenia do wykonywania Node.js poleceń i przejdź do następującego katalogu:

    cd azure-iot-sdk-node\provisioning\device\samples

  4. W folderze provisioning/device/samples otwórz register_symkey.js i przejrzyj kod.

    Przykładowa wartość domyślna to MQTT jako protokół transportowy. Jeśli chcesz użyć innego protokołu, oznacz następujący wiersz jako komentarz i usuń komentarz z wiersza dla odpowiedniego protokołu.

    var ProvisioningTransport = require('azure-iot-provisioning-device-mqtt').Mqtt;

    Zwróć również uwagę, że przykładowy kod ustawia niestandardowy ładunek:

    provisioningClient.setProvisioningPayload({a: 'b'});

    Możesz oznaczyć ten kod jako niewymagany w tym samouczku. Niestandardowy ładunek może być używany podczas przypisywania urządzenia do usługi IoT Hub przy użyciu niestandardowego elementu webhook alokacji. Aby uzyskać więcej informacji, zobacz Samouczek: używanie niestandardowych zasad alokacji.

    Metoda provisioningClient.register() próbuje rejestracji urządzenia.

  5. W wierszu polecenia uruchom następujące polecenia, aby ustawić zmienne środowiskowe używane przez przykład:

    • Pierwsze polecenie ustawia zmienną PROVISIONING_HOST środowiskową na globalny punkt końcowy urządzenia. Ten punkt końcowy jest taki sam dla wszystkich wystąpień usługi DPS.
    • Zastąp <id-scope> wartość zakresem identyfikatora skopiowaną z witryny Azure Portal.
    • Zastąp <registration-id> element identyfikatorem rejestracji wybranym w obszarze Wybierz unikatowy identyfikator rejestracji dla urządzenia.
    • Zastąp <defived-device-key> ciąg kluczem pochodnym urządzenia wygenerowanym w sekcji Tworzenie klucza urządzenia.
    set PROVISIONING_HOST=global.azure-devices-provisioning.net

    set PROVISIONING_IDSCOPE=<id-scope>

    set PROVISIONING_REGISTRATION_ID=<registration-id>

    set PROVISIONING_SYMMETRIC_KEY=<derived-device-key>

  6. Skompiluj i uruchom przykładowy kod przy użyciu następujących poleceń:

     npm install

    node register_symkey.js

  7. Powinny zostać wyświetlone dane wyjściowe podobne do poniższych. Ciąg "Hello World" jest wysyłany do centrum jako komunikat testowy.

    registration succeeded
assigned hub=contoso-hub-2.azure-devices.net
deviceId=sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6
payload=undefined
Client connected
send status: MessageEnqueued

Przykładowy kod aprowizacji wykonuje następujące zadania w następującej kolejności:

  1. Uwierzytelnia urządzenie przy użyciu zasobu Device Provisioning przy użyciu następujących czterech parametrów:

    • PROVISIONING_HOST
    • PROVISIONING_IDSCOPE
    • PROVISIONING_REGISTRATION_ID
    • PROVISIONING_SYMMETRIC_KEY

  2. Przypisuje urządzenie do centrum IoT Hub, które jest już połączone z wystąpieniem usługi Device Provisioning Service.

  3. Wysyła komunikat telemetrii testowej do centrum IoT.

Aby zaktualizować i uruchomić przykład aprowizacji przy użyciu informacji o urządzeniu:

  1. W menu głównym usługi Device Provisioning Wybierz pozycję Przegląd.

  2. Skopiuj wartość Zakres identyfikatora.

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. Otwórz wiersz polecenia i przejdź do katalogu, w którym znajduje się przykładowy plik provision_symmetric_key.py.

    cd azure-iot-sdk-python\samples\async-hub-scenarios

  4. W wierszu polecenia uruchom następujące polecenia, aby ustawić zmienne środowiskowe używane przez przykład:

    • Pierwsze polecenie ustawia zmienną PROVISIONING_HOST środowiskową na globalny punkt końcowy urządzenia. Ten punkt końcowy jest taki sam dla wszystkich wystąpień usługi DPS.
    • Zastąp <id-scope> wartość zakresem identyfikatora skopiowaną z witryny Azure Portal.
    • Zastąp <registration-id> element identyfikatorem rejestracji wybranym w obszarze Wybierz unikatowy identyfikator rejestracji dla urządzenia.
    • Zastąp <defived-device-key> ciąg kluczem pochodnym urządzenia wygenerowanym w sekcji Tworzenie klucza urządzenia.
    set PROVISIONING_HOST=global.azure-devices-provisioning.net

    set PROVISIONING_IDSCOPE=<id-scope>

    set PROVISIONING_REGISTRATION_ID=<registration-id>

    set PROVISIONING_SYMMETRIC_KEY=<derived-device-key>

  5. Zainstaluj bibliotekę azure-iot-device , uruchamiając następujące polecenie.

    pip install azure-iot-device

  6. Uruchom przykładowy kod języka Python w provision_symmetric_key.py.

    python provision_symmetric_key.py

  7. Powinny zostać wyświetlone dane wyjściowe podobne do poniższych. Niektóre przykładowe komunikaty telemetryczne prędkości wiatru są również wysyłane do koncentratora jako test.

    D:\azure-iot-sdk-python\samples\async-hub-scenarios>python provision_symmetric_key.py
The complete registration result is
sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6
contoso-hub-2.azure-devices.net
initialAssignment
null
Will send telemetry from the provisioned device
sending message #1
sending message #2
sending message #3
sending message #4
sending message #5
sending message #6
sending message #7
sending message #8
sending message #9
sending message #10
done sending message #1
done sending message #2
done sending message #3
done sending message #4
done sending message #5
done sending message #6
done sending message #7
done sending message #8
done sending message #9
done sending message #10

Przykładowy kod aprowizacji wykonuje następujące zadania w następującej kolejności:

  1. Uwierzytelnia urządzenie przy użyciu zasobu Device Provisioning przy użyciu następujących czterech parametrów:

    • GLOBAL_ENDPOINT
    • SCOPE_ID
    • REGISTRATION_ID
    • SYMMETRIC_KEY

  2. Przypisuje urządzenie do centrum IoT Hub, które jest już połączone z wystąpieniem usługi Device Provisioning Service.

  3. Wysyła komunikat telemetrii testowej do centrum IoT.

Aby zaktualizować i uruchomić przykład aprowizacji przy użyciu informacji o urządzeniu:

  1. W menu głównym usługi Device Provisioning Wybierz pozycję Przegląd.

  2. Skopiuj wartość Zakres identyfikatora.

    Screenshot that shows copying the ID scope from the DPS overview pane.

  3. Otwórz przykładowy kod urządzenia Java do edycji. Pełna ścieżka do przykładowego kodu urządzenia to:

    azure-iot-sdk-java/provisioning/provisioning-samples/provisioning-symmetrickey-individual-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningSymmetricKeyIndividualEnrollmentSample.java

  4. Ustaw wartość następujących zmiennych dla usługi DPS i rejestracji urządzeń:

    • Zastąp [Your scope ID here] wartość zakresem identyfikatora skopiowaną z witryny Azure Portal.
    • Zastąp element [Your Provisioning Service Global Endpoint here] globalnym punktem końcowym urządzenia: global.azure-devices-provisioning.net. Ten punkt końcowy jest taki sam dla wszystkich wystąpień usługi DPS.
    • Zastąp [Enter your Symmetric Key here] ciąg kluczem pochodnym urządzenia wygenerowanym w sekcji Tworzenie klucza urządzenia.
    • Zastąp [Enter your Registration ID here] element identyfikatorem rejestracji wybranym w obszarze Wybierz unikatowy identyfikator rejestracji dla urządzenia.
    private static final String SCOPE_ID = "[Your scope ID here]";
private static final String GLOBAL_ENDPOINT = "[Your Provisioning Service Global Endpoint here]";
private static final String SYMMETRIC_KEY = "[Enter your Symmetric Key here]";
private static final String REGISTRATION_ID = "[Enter your Registration ID here]";

    Uwaga

    Należy pamiętać, że ten krok pozostawia klucz pochodnego urządzenia dołączony jako część obrazu dla każdego urządzenia, co nie jest zalecanym najlepszym rozwiązaniem w zakresie zabezpieczeń. Jest to jeden z powodów, dla których bezpieczeństwo i łatwość użytkowania są często kompromisami. Należy w pełni przejrzeć zabezpieczenia urządzeń zgodnie z własnymi wymaganiami.

  5. Otwórz wiersz polecenia do kompilowania. Przejdź do folderu przykładowego projektu aprowizacji w repozytorium zestawu JAVA SDK.

    cd azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-symmetrickey-individual-sample

  6. Skompiluj przykład.

    mvn clean install

  7. Przejdź do target folderu i wykonaj utworzony .jar plik. W poleceniu java zastąp {version} symbol zastępczy wersją w .jar nazwie pliku na maszynie.

    cd target
java -jar ./provisioning-symmetrickey-individual-sample-{version}-with-deps.jar

  8. Powinny zostać wyświetlone dane wyjściowe podobne do poniższych.

    Starting...
Beginning setup.
WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.
2022-10-07 18:14:48,388 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Initialized a ProvisioningDeviceClient instance using SDK version 2.0.2
2022-10-07 18:14:48,390 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Starting provisioning thread...
Waiting for Provisioning Service to register
2022-10-07 18:14:48,392 INFO (global.azure-devices-provisioning.net-002edcf5-CxnPendingConnectionId-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Opening the connection to device provisioning service...
2022-10-07 18:14:48,518 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Connection to device provisioning service opened successfully, sending initial device registration message
2022-10-07 18:14:48,521 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-RegisterTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.RegisterTask] - Authenticating with device provisioning service using symmetric key
2022-10-07 18:14:49,252 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Waiting for device provisioning service to provision this device...
2022-10-07 18:14:49,253 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Current provisioning status: ASSIGNING
2022-10-07 18:14:52,459 INFO (global.azure-devices-provisioning.net-002edcf5-Cxn002edcf5-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Device provisioning service assigned the device successfully
IotHUb Uri : contoso-hub-2.azure-devices.net
Device ID : sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6
2022-10-07 18:14:58,424 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-10-07 18:14:58,436 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-10-07 18:14:58,440 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.1.1
2022-10-07 18:14:58,450 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2022-10-07 18:14:58,471 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2022-10-07 18:14:59,314 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2022-10-07 18:14:59,315 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6/messages/devicebound/#
2022-10-07 18:14:59,378 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6/messages/devicebound/# was acknowledged
2022-10-07 18:14:59,379 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2022-10-07 18:14:59,381 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2022-10-07 18:14:59,383 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2022-10-07 18:14:59,389 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2022-10-07 18:14:59,392 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details
2022-10-07 18:14:59,395 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2022-10-07 18:14:59,404 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Sending message from device to IoT Hub...
2022-10-07 18:14:59,408 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Message was queued to be sent later ( Message details: Correlation Id [32cf12c4-4db1-4562-9d8c-267c0506636f] Message Id [2e1717be-cfcf-41a7-b1c0-59edeb8ea865] )
Press any key to exit...
2022-10-07 18:14:59,409 DEBUG (contoso-hub-2.azure-devices.net-sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6-c32c76d0-Cxn0e70bbf7-8476-441d-8626-c17250585ee6-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Sending message ( Message details: Correlation Id [32cf12c4-4db1-4562-9d8c-267c0506636f] Message Id [2e1717be-cfcf-41a7-b1c0-59edeb8ea865] )
2022-10-07 18:14:59,777 DEBUG (MQTT Call: sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - IotHub message was acknowledged. Checking if there is record of sending this message ( Message details: Correlation Id [32cf12c4-4db1-4562-9d8c-267c0506636f] Message Id [2e1717be-cfcf-41a7-b1c0-59edeb8ea865] )
2022-10-07 18:14:59,779 DEBUG (contoso-hub-2.azure-devices.net-sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6-c32c76d0-Cxn0e70bbf7-8476-441d-8626-c17250585ee6-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking the callback function for sent message, IoT Hub responded to message ( Message details: Correlation Id [32cf12c4-4db1-4562-9d8c-267c0506636f] Message Id [2e1717be-cfcf-41a7-b1c0-59edeb8ea865] ) with status OK
Message received! Response status: OK

Potwierdzanie rejestracji aprowizacji urządzeń

W tym samouczku użyto zasad alokacji konfiguracji statycznej do przypisania urządzeń rejestrujących się za pośrednictwem grupy rejestracji do tego samego centrum IoT. Jednak w przypadku alokacji, w których można aprowizować urządzenie w jednym z kilku centrów IoT, możesz sprawdzić rekordy rejestracji grupy rejestracji, aby sprawdzić, w którym centrum IoT Hub zostało aprowidowane:

  1. W witrynie Azure Portal przejdź do wystąpienia usługi DPS.

  2. W menu Ustawienia wybierz pozycję Zarządzaj rejestracjami.

  3. Wybierz pozycję Grupy rejestracji.

  4. Wybierz grupę rejestracji utworzoną na potrzeby tego samouczka.

  5. Na stronie Szczegóły grupy rejestracji wybierz pozycję Stan rejestracji.

  6. Znajdź identyfikator urządzenia dla kolumny Identyfikator urządzenia i zanotuj centrum IoT Hub w kolumnie Przypisane centrum IoT.

    Możesz wybrać rekord urządzenia, aby wyświetlić więcej szczegółów, takich jak początkowa reprezentacja bliźniacze przypisana do urządzenia.

Aby sprawdzić urządzenie w centrum IoT:

  1. W witrynie Azure Portal przejdź do centrum IoT Hub, do którego przypisano Urządzenie.

  2. W menu Zarządzanie urządzeniami wybierz pozycję Urządzenia.

  3. Jeśli urządzenie zostało pomyślnie aprowizowane, jego identyfikator urządzenia powinien pojawić się na liście z ustawionym stanem ustawionym jako włączone. Jeśli urządzenie nie jest widoczne, wybierz pozycję Odśwież.

    Device is registered with the IoT hub

Uwaga

Jeśli stan początkowej reprezentacji bliźniaczej urządzenia został zmieniony z wartości domyślnej w grupie rejestracji, urządzenie może ściągnąć żądany stan bliźniaczej reprezentacji z centrum i odpowiednio działać. Aby uzyskać więcej informacji, zobacz Opis bliźniaczej reprezentacji urządzenia w usłudze IoT Hub oraz sposoby jej używania.

Aprowizuj więcej urządzeń

Aby aprowizować więcej urządzeń za pośrednictwem grupy rejestracji, wykonaj kroki opisane w poprzednich sekcjach, aby:

  1. Wybierz unikatowy identyfikator rejestracji dla urządzenia.

  2. Uzyskiwanie klucza urządzenia. Tak jak wcześniej, użyj klucza podstawowego dla grupy rejestracji jako klucza grupy.

  3. Uruchom kod aprowizacji urządzenia. Zastąp niezbędne artefakty nowym pochodnym kluczem urządzenia i identyfikatorem rejestracji.

Czyszczenie zasobów

Jeśli planujesz kontynuować pracę i eksplorujesz przykład klienta urządzenia, nie usuwaj zasobów utworzonych w tym samouczku. Jeśli nie planujesz kontynuować, wykonaj następujące kroki, aby usunąć wszystkie zasoby utworzone w tym samouczku.

Usuwanie grupy rejestracji

Usunięcie grupy rejestracji nie powoduje usunięcia skojarzonych z nią rekordów rejestracji. Te oddzielone rekordy są liczone względem limitu przydziału rejestracji dla wystąpienia usługi DPS. Z tego powodu najlepszym rozwiązaniem jest usunięcie wszystkich rekordów rejestracji skojarzonych z grupą rejestracji przed usunięciem samej grupy rejestracji.

  1. W witrynie Azure Portal przejdź do wystąpienia usługi DPS.

  2. W menu Ustawienia wybierz pozycję Zarządzaj rejestracjami.

  3. Wybierz kartę Grupy rejestracji.

  4. Wybierz nazwę grupy rejestracji użytej w tym samouczku, aby otworzyć jej stronę szczegółów.

  5. Na stronie Szczegóły rejestracji wybierz pozycję Stan rejestracji. Następnie zaznacz pole wyboru obok nagłówka kolumny Identyfikator urządzenia, aby wybrać wszystkie rekordy rejestracji dla grupy rejestracji. Wybierz pozycję Usuń w górnej części strony, aby usunąć rekordy rejestracji.

  6. Wróć do strony Zarządzanie rejestracjami .

  7. Zaznacz pole wyboru obok nazwy grupy rejestracji użytej na potrzeby tego samouczka.

  8. W górnej części strony wybierz pozycję Usuń.

Usuwanie rejestracji urządzeń z usługi IoT Hub

  1. W witrynie Azure Portal przejdź do centrum IoT Hub, do którego przypisano Urządzenie.

  2. Wybierz pozycję Urządzenia w sekcji Zarządzanie urządzeniami w menu nawigacji.

  3. Zaznacz pole wyboru obok identyfikatora urządzenia urządzeń zarejestrowanych w tym samouczku.

  4. W górnej części strony wybierz pozycję Usuń.

Następne kroki

W tym samouczku zainicjowano obsługę wielu urządzeń w jednym centrum IoT przy użyciu grupy rejestracji. Następnie dowiedz się, jak aprowizować urządzenia IoT w wielu centrach.

Samouczek: zarządzanie przypisaniem centrum IoT przy użyciu niestandardowych zasad alokacji