Samouczek: używanie niestandardowych zasad alokacji z usługą Device Provisioning Service (DPS)

  • Artykuł

Niestandardowe zasady alokacji zapewniają większą kontrolę nad tym, jak urządzenia są przypisywane do centrów IoT. Za pomocą niestandardowych zasad alokacji można zdefiniować własne zasady alokacji, gdy zasady udostępniane przez usługę Azure IoT Hub Device Provisioning Service (DPS) nie spełniają wymagań danego scenariusza. Niestandardowe zasady alokacji są implementowane w elemecie webhook hostowanym w usłudze Azure Functions i konfigurowane w co najmniej jednej indywidualnej rejestracji i/lub grupach rejestracji. Gdy urządzenie rejestruje się w usłudze DPS przy użyciu skonfigurowanego wpisu rejestracji, usługa DPS wywołuje element webhook, aby dowiedzieć się, do którego centrum IoT powinno być zarejestrowane urządzenie, i, opcjonalnie, jego stan początkowy. Aby dowiedzieć się więcej, zobacz Omówienie niestandardowych zasad alokacji.

W tym samouczku przedstawiono niestandardowe zasady alokacji przy użyciu funkcji platformy Azure napisanej w języku C#. Urządzenia są przypisywane do jednego z dwóch centrów IoT reprezentujących dział Contoso Tosters Division i Dział pomp cieplnych Contoso. Urządzenia żądające aprowizacji muszą mieć identyfikator rejestracji z jednym z następujących sufiksów, które mają zostać zaakceptowane do aprowizacji:

  • -contoso-tstrsd-007 dla Działu Tosterów Contoso
  • -contoso-hpsd-088 dla działu pomp cieplnych Contoso

Urządzenia są symulowane przy użyciu przykładu aprowizacji zawartego w zestawie SDK języka C usługi Azure IoT.

W tym samouczku wykonasz następujące czynności:

  • Użyj interfejsu wiersza polecenia platformy Azure, aby utworzyć wystąpienie usługi DPS i utworzyć i połączyć z nim dwa centra IoT działu Contoso Division (Contoso Tosters Division i Contoso Heat Pump Division).
  • Utwórz funkcję platformy Azure, która implementuje niestandardowe zasady alokacji.
  • Utwórz nową grupę rejestracji przy użyciu funkcji platformy Azure dla niestandardowych zasad alokacji.
  • Utwórz klucze symetryczne urządzenia dla dwóch symulowanych urządzeń.
  • Skonfiguruj środowisko programistyczne dla zestawu SDK języka C usługi Azure IoT.
  • Zasymuluj urządzenia i sprawdź, czy są one aprowidowane zgodnie z przykładowym kodem w niestandardowych zasadach alokacji.

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto platformy Azure.

Wymagania wstępne

Poniższe wymagania wstępne dotyczą środowiska deweloperskiego systemu Windows. W przypadku systemu Linux lub macOS zapoznaj się z odpowiednią sekcją w temacie Przygotowywanie środowiska projektowego w dokumentacji zestawu SDK.

Tworzenie usługi aprowizacji i dwóch centrów IoT

W tej sekcji użyjesz usługi Azure Cloud Shell do utworzenia usługi aprowizacji i dwóch centrów IoT reprezentujących dział Contoso Tosters Division i dział Contoso Heat Pump.

  1. Najpierw ustaw zmienne środowiskowe w obszarze roboczym, aby uprościć polecenia w tym samouczku.

    Nazwy usług DPS i IoT Hub muszą być globalnie unikatowe. Zastąp SUFFIX symbol zastępczy własną wartością.

    Ponadto kod funkcji platformy Azure utworzony w dalszej części tego samouczka szuka centrów IoT, które mają -toasters- nazwy lub -heatpumps- ich nazwy. Jeśli zmienisz sugerowane wartości, upewnij się, że używasz nazw zawierających wymagane podciągy.

    #!/bin/bash
export RESOURCE_GROUP="contoso-us-resource-group"
export LOCATION="westus"
export DPS="contoso-provisioning-service-SUFFIX"
export TOASTER_HUB="contoso-toasters-hub-SUFFIX"
export HEATPUMP_HUB="contoso-heatpumps-hub-SUFFIX"

    # PowerShell
$env:RESOURCE_GROUP = "contoso-us-resource-group"
$env:LOCATION = "westus"
$env:DPS = "contoso-provisioning-service-SUFFIX"
$env:TOASTER_HUB = "contoso-toasters-hub-SUFFIX"
$env:HEATPUMP_HUB = "contoso-heatpumps-hub-SUFFIX"

    Napiwek

    Polecenia używane w tym samouczku domyślnie tworzą zasoby w lokalizacji Zachodnie stany USA. Zalecamy utworzenie zasobów w najbliższym regionie obsługującym usługę Device Provisioning Service. Listę dostępnych lokalizacji można wyświetlić, przechodząc do strony Stan platformy Azure i wyszukując frazę "Device Provisioning Service". W poleceniach lokalizacje można określić w jednym formacie wyrazu lub w wielu wyrazach; na przykład: westus, Zachodnie stany USA, Zachodnie stany USA itp. Wartość nie uwzględnia wielkości liter.

  2. Użyj polecenia az group create, aby utworzyć grupę zasobów platformy Azure. Grupa zasobów platformy Azure to logiczny kontener przeznaczony do wdrażania zasobów platformy Azure i zarządzania nimi.

    Poniższy przykład tworzy grupę zasobów. Zalecamy użycie jednej grupy dla wszystkich zasobów utworzonych w tym samouczku. Takie podejście ułatwi czyszczenie po zakończeniu pracy.

    az group create --name $RESOURCE_GROUP --location $LOCATION

  3. Użyj polecenia az iot dps create, aby utworzyć wystąpienie usługi Device Provisioning Service (DPS). Usługa aprowizacji jest dodawana do grupy contoso-us-resource-group.

    az iot dps create --name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION

    Wykonanie tego polecenia może potrwać kilka minut.

  4. Użyj polecenia az iot hub create, aby utworzyć centrum IoT Division Contoso JoT Division. Centrum IoT jest dodawane do grupy contoso-us-resource-group.

    az iot hub create --name $TOASTER_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1

    Wykonanie tego polecenia może potrwać kilka minut.

  5. Użyj polecenia az iot hub create, aby utworzyć centrum IoT Dział pomp cieplnych Contoso. To centrum IoT jest również dodawane do grupy contoso-us-resource-group.

    az iot hub create --name $HEATPUMP_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1

    Wykonanie tego polecenia może potrwać kilka minut.

  6. Uruchom następujące dwa polecenia, aby uzyskać parametry połączenia dla utworzonych centrów.

    az iot hub connection-string show --hub-name $TOASTER_HUB --key primary --query connectionString -o tsv
az iot hub connection-string show --hub-name $HEATPUMP_HUB --key primary --query connectionString -o tsv

  7. Uruchom następujące polecenia, aby połączyć koncentratory z zasobem usługi DPS. Zastąp symbole zastępcze parametry połączenia piasty z poprzedniego kroku.

    az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <toaster_hub_connection_string>
az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <heatpump_hub_connection_string>

Tworzenie niestandardowej funkcji alokacji

W tej sekcji utworzysz funkcję platformy Azure, która implementuje niestandardowe zasady alokacji. Ta funkcja decyduje, które działowe centrum IoT hub ma być zarejestrowane w celu ustalenia, czy jego identyfikator rejestracji zawiera ciąg -contoso-tstrsd-007 lub -contoso-hpsd-088. Ustawia również początkowy stan bliźniaczej reprezentacji urządzenia na podstawie tego, czy urządzenie jest przesterem, czy pompą cieplną.

  1. Zaloguj się w witrynie Azure Portal.

  2. W polu wyszukiwania wyszukaj i wybierz pozycję Aplikacja funkcji.

  3. Wybierz pozycję Utwórz lub utwórz aplikację funkcji.

  4. Na stronie Tworzenie aplikacji funkcji na karcie Podstawy wprowadź następujące ustawienia dla nowej aplikacji funkcji i wybierz pozycję Przejrzyj i utwórz:

    Parametr Wartość
    Subskrypcja Upewnij się, że wybrano subskrypcję, w której utworzono zasoby dla tego samouczka.
    Grupa zasobów Wybierz grupę zasobów utworzoną w poprzedniej sekcji. Wartość domyślna podana w poprzedniej sekcji to contoso-us-resource-group.
    Nazwa aplikacji funkcji Podaj nazwę aplikacji funkcji.
    Czy chcesz wdrożyć kod lub obraz kontenera? Kod
    Stos środowiska uruchomieniowego .NET
    Wersja Wybierz dowolną wersję modelu w procesie.
    Region Wybierz region w pobliżu.

    Uwaga

    Domyślnie Szczegółowe informacje aplikacji jest włączona. Szczegółowe informacje aplikacji nie jest konieczne w tym samouczku, ale może pomóc zrozumieć i zbadać wszelkie problemy występujące z alokacją niestandardową. Jeśli wolisz, możesz wyłączyć aplikację Szczegółowe informacje, wybierając kartę Monitorowanie, a następnie wybierając pozycję Nie w obszarze Włącz aplikację Szczegółowe informacje.

    Zrzut ekranu przedstawiający formularz Tworzenie aplikacji funkcji w witrynie Azure Portal.

  5. Na karcie Przeglądanie + tworzenie wybierz pozycję Utwórz, aby utworzyć aplikację funkcji.

  6. Wdrożenie może potrwać kilka minut. Po zakończeniu wybierz pozycję Przejdź do zasobu.

  7. W lewym okienku strony Przegląd aplikacji funkcji wybierz pozycję Utwórz funkcję.

    Zrzut ekranu przedstawiający wybieranie opcji tworzenia funkcji w witrynie Azure Portal.

  8. Na stronie Tworzenie funkcji wybierz szablon Wyzwalacz HTTP, a następnie wybierz pozycję Dalej.

  9. Na karcie Szczegóły szablonu wybierz pozycję Anonimowe jako poziom autoryzacji, a następnie wybierz pozycję Utwórz.

    Zrzut ekranu przedstawiający ustawianie poziomu autoryzacji jako anonimowego.

    Napiwek

    Jeśli zachowasz poziom autoryzacji jako funkcja, musisz skonfigurować rejestracje usługi DPS przy użyciu klucza interfejsu API funkcji. Aby uzyskać więcej informacji, zobacz Wyzwalacz HTTP usługi Azure Functions.

  10. Po otwarciu funkcji HttpTrigger1 wybierz pozycję Kod i testowanie w okienku po lewej stronie. Dzięki temu można edytować kod funkcji. Plik kodu run.csx powinien zostać otwarty do edycji.

  11. Wymagane pakiety NuGet odwołują się do odwołania. Aby utworzyć początkową reprezentację urządzenia, funkcja alokacji niestandardowej używa klas zdefiniowanych w dwóch pakietach NuGet, które muszą zostać załadowane do środowiska hostingu. W usłudze Azure Functions pakiety NuGet odwołują się do plików function.proj . W tym kroku zapiszesz i przekażesz plik function.proj dla wymaganych zestawów. Aby uzyskać więcej informacji, zobacz Using NuGet packages with Azure Functions (Używanie pakietów NuGet z usługą Azure Functions).

    1. Skopiuj następujące wiersze do ulubionego edytora i zapisz plik na komputerze jako function.proj.

      <Project Sdk="Microsoft.NET.Sdk">  
    <PropertyGroup>  
        <TargetFramework>netstandard2.0</TargetFramework>  
    </PropertyGroup>  
    <ItemGroup>  
        <PackageReference Include="Microsoft.Azure.Devices.Provisioning.Service" Version="1.18.1" />
        <PackageReference Include="Microsoft.Azure.Devices.Shared" Version="1.30.1" />
    </ItemGroup>  
</Project>

    2. Wybierz przycisk Przekaż znajdujący się nad edytorem kodu, aby przekazać plik function.proj. Po przekazaniu wybierz plik w edytorze kodu przy użyciu pola listy rozwijanej, aby zweryfikować zawartość.

    3. Wybierz plik function.proj w edytorze kodu i sprawdź jego zawartość. Jeśli plik function.proj jest pusty, skopiuj powyższe wiersze do pliku i zapisz go. (Czasami przekazywanie tworzy plik bez przekazywania zawartości).

  12. Upewnij się, że w edytorze kodu wybrano plik run.csx dla elementu HttpTrigger1 . Zastąp kod funkcji HttpTrigger1 następującym kodem i wybierz pozycję Zapisz:

    #r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

using Microsoft.Azure.Devices.Shared;               // For TwinCollection
using Microsoft.Azure.Devices.Provisioning.Service; // For TwinState

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    // Get request body
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);

    log.LogInformation("Request.Body:...");
    log.LogInformation(requestBody);

    // Get registration ID of the device
    string regId = data?.deviceRuntimeContext?.registrationId;

    string message = "Uncaught error";
    bool fail = false;
    ResponseObj obj = new ResponseObj();

    if (regId == null)
    {
        message = "Registration ID not provided for the device.";
        log.LogInformation("Registration ID : NULL");
        fail = true;
    }
    else
    {
        string[] hubs = data?.linkedHubs?.ToObject<string[]>();

        // Must have hubs selected on the enrollment
        if (hubs == null)
        {
            message = "No hub group defined for the enrollment.";
            log.LogInformation("linkedHubs : NULL");
            fail = true;
        }
        else
        {
            // This is a Contoso Toaster Model 007
            if (regId.Contains("-contoso-tstrsd-007"))
            {
                //Find the "-toasters-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-toasters-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No toasters hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "toaster";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "ready";
                    properties["darknessSetting"] = "medium";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // This is a Contoso Heat pump Model 008
            else if (regId.Contains("-contoso-hpsd-088"))
            {
                //Find the "-heatpumps-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-heatpumps-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No heat pumps hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "heatpump";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "on";
                    properties["temperatureSetting"] = "65";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // Unrecognized device.
            else
            {
                fail = true;
                message = "Unrecognized device registration.";
                log.LogInformation("Unknown device registration");
            }
        }
    }

    log.LogInformation("\nResponse");
    log.LogInformation((obj.iotHubHostName != null) ? JsonConvert.SerializeObject(obj) : message);

    return (fail)
        ? new BadRequestObjectResult(message) 
        : (ActionResult)new OkObjectResult(obj);
}

public class ResponseObj
{
    public string iotHubHostName {get; set;}
    public TwinState initialTwin {get; set;}
}

Tworzenie rejestracji

W tej sekcji utworzysz nową grupę rejestracji, która używa niestandardowych zasad alokacji. Dla uproszczenia w tym samouczku używane jest zaświadczanie klucza symetrycznego z rejestracją. Aby uzyskać bezpieczniejsze rozwiązanie, rozważ użycie zaświadczania certyfikatów X.509 z łańcuchem zaufania.

  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.
    Nazwa grupy Jako nazwę grupy wprowadź nazwę contoso-custom-allocated-devices .
    Stan aprowizacji Zaznacz pole Włącz tę rejestrację.

  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.
    Zasady alokacji Wybierz pozycję Niestandardowe (użyj funkcji platformy Azure). Wybierz pozycję Wybierz funkcję platformy Azure, a następnie postępuj zgodnie z monitami, aby wybrać funkcję utworzoną na potrzeby tego samouczka.

  7. Wybierz pozycję Przejrzyj i utwórz.

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

Po zapisaniu rejestracji otwórz ją ponownie i zanotuj klucz podstawowy. Najpierw musisz zapisać rejestrację, aby wygenerować klucze. Ten klucz służy do generowania unikatowych kluczy urządzeń dla symulowanych urządzeń w następnej sekcji.

Uzyskiwanie unikatowych kluczy urządzeń

Urządzenia nie korzystają bezpośrednio z podstawowego klucza symetrycznego grupy rejestracji. Zamiast tego należy użyć klucza podstawowego, aby uzyskać klucz urządzenia dla każdego urządzenia. W tej sekcji utworzysz dwa unikatowe klucze urządzenia. Jeden z kluczy jest używany do symulowanego urządzenia tostera. Drugi klucz jest używany do symulowanego urządzenia pompy cieplnej.

Aby uzyskać klucz urządzenia, należy użyć zanotowany wcześniej klucza podstawowego grupy rejestracji, aby obliczyć HMAC-SHA256 identyfikator rejestracji urządzenia dla każdego urządzenia i przekonwertować wynik na format Base 64. Aby uzyskać więcej informacji na temat tworzenia pochodnych kluczy urządzeń z grupami rejestracji, zobacz sekcję Rejestracje grup w temacie Zaświadczanie klucza symetrycznego.

W tym przykładzie w tym samouczku użyj następujących dwóch identyfikatorów rejestracji urządzeń i oblicz klucz urządzenia dla obu urządzeń. Oba identyfikatory rejestracji mają prawidłowy sufiks do pracy z przykładowym kodem dla niestandardowych zasad alokacji:

  • breakroom499-contoso-tstrsd-007
  • mainbuilding167-contoso-hpsd-088

Rozszerzenie IoT dla interfejsu wiersza polecenia platformy Azure udostępnia iot dps enrollment-group compute-device-key polecenie do generowania pochodnych kluczy urządzeń. To polecenie może być używane w systemach z systemem Windows lub Linux z poziomu programu PowerShell lub powłoki Bash.

Zastąp wartość --key argumentu kluczempodstawowym z grupy rejestracji.

az iot dps enrollment-group compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id breakroom499-contoso-tstrsd-007

az iot dps compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id mainbuilding167-contoso-hpsd-088

Uwaga

Można również podać identyfikator grupy rejestracji, a nie klucz symetryczny do iot dps enrollment-group compute-device-key polecenia . Na przykład:

az iot dps enrollment-group compute-device-key -g contoso-us-resource-group --dps-name contoso-provisioning-service-1098 --enrollment-id contoso-custom-allocated-devices --registration-id breakroom499-contoso-tstrsd-007

Symulowane urządzenia używają pochodnych kluczy urządzeń z każdym identyfikatorem rejestracji w celu wykonania zaświadczania klucza symetrycznego.

Przygotowywanie środowiska deweloperskiego dla zestawu SDK języka C usługi Azure IoT

W tej sekcji przygotujesz środowisko programistyczne używane do kompilowania zestawu SDK języka C usługi Azure IoT. Zestaw SDK zawiera przykładowy kod symulowanego urządzenia. To urządzenie symulowane podejmie próbę aprowizacji podczas sekwencji rozruchu urządzenia.

Ta sekcja jest zorientowana na stację roboczą opartą na systemie Windows. Aby zapoznać się z przykładem systemu Linux, zobacz konfigurowanie maszyn wirtualnych w artykule Samouczek: aprowizowanie opóźnienia geograficznego.

  1. Pobierz system kompilacji narzędzia CMake.

    Przed rozpoczęciem CMake instalacji należy zainstalować 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.

  2. Znajdź nazwę tagu dla najnowszej wersji zestawu SDK.

  3. Otwórz wiersz polecenia lub powłokę Git Bash. Uruchom następujące polecenia, aby sklonować najnowszą wersję zestawu AZURE IoT Device SDK for C GitHub. Użyj tagu znalezionego w poprzednim kroku jako wartości parametru -b , na przykład: lts_01_2023.

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

    Należy się spodziewać, że ukończenie operacji potrwa kilka minut.

  4. Utwórz podkatalog cmake w katalogu głównym repozytorium Git, a następnie przejdź do tego folderu. Uruchom następujące polecenia z azure-iot-sdk-c katalogu:

    mkdir cmake
cd cmake

  5. Uruchom następujące polecenie, które utworzy wersję zestawu SDK specyficzną dla platformy klienta deweloperskiego. Rozwiązanie programu Visual Studio dla symulowanego urządzenia zostanie wygenerowane w katalogu cmake.

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

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

    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 15 2017
-- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
-- The C compiler identification is MSVC 19.12.25835.0
-- The CXX compiler identification is MSVC 19.12.25835.0

...

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

Symulowanie urządzeń

W tej sekcji zaktualizujesz przykład aprowizacji o nazwie prov_dev_client_sample znajdujący się w skonfigurowanym wcześniej zestawie SDK języka C usługi Azure IoT.

Ten przykładowy kod symuluje sekwencję rozruchu urządzenia, która wysyła żądanie aprowizacji do wystąpienia usługi Device Provisioning Service. Sekwencja rozruchowa powoduje rozpoznawanie i przypisywanie urządzenia tostera do centrum IoT przy użyciu niestandardowych zasad alokacji.

  1. W witrynie Azure Portal wybierz kartę Przegląd dla usługi Device Provisioning Service i zanotuj wartość Zakres identyfikatora.

    Wyodrębnianie informacji o punkcie końcowym usługi Device Provisioning Service z bloku portalu

  2. W programie Visual Studio otwórz plik rozwiązania azure_iot_sdks.sln wygenerowany wcześniej 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.

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

  4. Znajdź stałą id_scope i zastąp jej wartość wcześniej skopiowaną wartością Zakres identyfikatorów.

    static const char* id_scope = "0ne00002193";

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

  6. main() W funkcji znajdź wywołanie metody Prov_Device_Register_Device(). Tuż przed tym wywołaniem dodaj następujące wiersze kodu, które są używane Prov_Device_Set_Provisioning_Payload() do przekazywania niestandardowego ładunku JSON podczas aprowizacji. Może to służyć do dostarczania dodatkowych informacji do niestandardowych funkcji alokacji. Można go również użyć do przekazania typu urządzenia zamiast sprawdzania identyfikatora rejestracji. Aby uzyskać więcej informacji na temat wysyłania i odbierania niestandardowych ładunków danych za pomocą usługi DPS, zobacz How to transfer payloads between devices and DPS (Jak przesyłać ładunki między urządzeniami i usługą DPS).

    // An example custom payload
const char* custom_json_payload = "{\"MyDeviceFirmwareVersion\":\"12.0.2.5\",\"MyDeviceProvisioningVersion\":\"1.0.0.0\"}";

prov_device_result = Prov_Device_Set_Provisioning_Payload(prov_device_handle, custom_json_payload);
if (prov_device_result != PROV_DEVICE_RESULT_OK)
{
    (void)printf("\r\nFailure setting provisioning payload: %s\r\n", MU_ENUM_TO_STRING(PROV_DEVICE_RESULT, prov_device_result));
}

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

Symulowanie urządzenia contoso toster

  1. Aby zasymulować urządzenie tostera, znajdź wywołanie 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 tostera i wygenerowany wcześniej kluczem urządzenia pochodnego. Wartość klucza JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs= pokazana poniżej jest podana tylko jako przykład.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("breakroom499-contoso-tstrsd-007", "JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs=");

    Zapisz plik.

  2. 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 rozruchu symulowanego urządzenia tosteringu i nawiązania połączenia z wystąpieniem usługi aprowizacji, które ma zostać przypisane do centrum IoT Hub przez niestandardowe zasady alokacji:

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-toasters-hub-1098.azure-devices.net, deviceId: breakroom499-contoso-tstrsd-007

Press enter key to exit:

    Poniżej przedstawiono przykładowe dane wyjściowe rejestrowania danych wyjściowych z niestandardowego kodu funkcji alokacji uruchomionego dla urządzenia toster. Zwróć uwagę, że koncentrator został pomyślnie wybrany dla urządzenia z tosterem. Zwróć również uwagę na payload właściwość zawierającą niestandardową zawartość JSON dodaną do kodu. Jest to dostępne dla kodu do użycia w obiekcie deviceRuntimeContext.

    To rejestrowanie jest dostępne, klikając pozycję Dzienniki w kodzie funkcji w portalu:

    2022-08-03T20:34:41.178 [Information] Executing 'Functions.HttpTrigger1' (Reason='This function was programmatically called via the host APIs.', Id=12950752-6d75-4f41-844b-c253a6653d4f)
2022-08-03T20:34:41.340 [Information] C# HTTP trigger function processed a request.
2022-08-03T20:34:41.341 [Information] Request.Body:...
2022-08-03T20:34:41.341 [Information] {"enrollmentGroup":{"enrollmentGroupId":"contoso-custom-allocated-devices","attestation":{"type":"symmetricKey"},"capabilities":{"iotEdge":false},"etag":"\"0000f176-0000-0700-0000-62eaad1e0000\"","provisioningStatus":"enabled","reprovisionPolicy":{"updateHubAssignment":true,"migrateDeviceData":true},"createdDateTimeUtc":"2022-08-03T17:15:10.8464255Z","lastUpdatedDateTimeUtc":"2022-08-03T17:15:10.8464255Z","allocationPolicy":"custom","iotHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"],"customAllocationDefinition":{"webhookUrl":"https://contoso-function-app-1098.azurewebsites.net/api/HttpTrigger1?****","apiVersion":"2021-10-01"}},"deviceRuntimeContext":{"registrationId":"breakroom499-contoso-tstrsd-007","currentIotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","currentDeviceId":"breakroom499-contoso-tstrsd-007","symmetricKey":{},"payload":{"MyDeviceFirmwareVersion":"12.0.2.5","MyDeviceProvisioningVersion":"1.0.0.0"}},"linkedHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"]}
2022-08-03T20:34:41.382 [Information] Response
2022-08-03T20:34:41.398 [Information] {"iotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","initialTwin":{"properties":{"desired":{"state":"ready","darknessSetting":"medium"}},"tags":{"deviceType":"toaster"}}}
2022-08-03T20:34:41.399 [Information] Executed 'Functions.HttpTrigger1' (Succeeded, Id=12950752-6d75-4f41-844b-c253a6653d4f, Duration=227ms)

Symulowanie urządzenia pompy cieplnej Contoso

  1. Aby zasymulować urządzenie pompy cieplnej, zaktualizuj wywołanie metody prov_dev_set_symmetric_key_info() w prov_dev_client_sample.c ponownie przy użyciu identyfikatora rejestracji pompy cieplnej i wygenerowanego wcześniej klucza urządzenia pochodnego. Wartość klucza 6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg= pokazana poniżej jest również podana tylko jako przykład.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("mainbuilding167-contoso-hpsd-088", "6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg=");

    Zapisz plik.

  2. 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 uruchomienia symulowanego urządzenia pompy cieplnej i nawiązania połączenia z wystąpieniem usługi aprowizacji, które ma zostać przypisane do centrum IoT Firmy Contoso przez zasady alokacji niestandardowej:

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-heatpumps-hub-1098.azure-devices.net, deviceId: mainbuilding167-contoso-hpsd-088

Press enter key to exit:

Rozwiązywanie problemów z niestandardowymi zasadami alokacji

W poniższej tabeli przedstawiono oczekiwane scenariusze i kody błędów wyników, które mogą zostać wyświetlone. Ta tabela ułatwia rozwiązywanie problemów z błędami niestandardowych zasad alokacji w usłudze Azure Functions.

Scenariusz Wynik rejestracji z usługi Provisioning Service Wyniki aprowizacji zestawu SDK
Element webhook zwraca wartość 200 OK z wartością "iotHubHostName" ustawioną na prawidłową nazwę hosta centrum IoT Stan wyniku: Przypisano Zestaw SDK zwraca PROV_DEVICE_RESULT_OK wraz z informacjami o centrum
Element webhook zwraca wartość 200 OK z wartością "iotHubHostName" w odpowiedzi, ale ustawiono pusty ciąg lub wartość null Stan wyniku: Niepowodzenie

Kod błędu: CustomAllocationIotHubNotSpecified (400208)		 Zestaw SDK zwraca PROV_DEVICE_RESULT_HUB_NOT_SPECIFIED
Element webhook zwraca błąd 401 Brak autoryzacji Stan wyniku: Niepowodzenie

Kod błędu: CustomAllocationUnauthorizedAccess (400209)		 Zestaw SDK zwraca PROV_DEVICE_RESULT_UNAUTHORIZED
Utworzono rejestrację indywidualną, aby wyłączyć urządzenie Stan wyniku: Wyłączone Zestaw SDK zwraca PROV_DEVICE_RESULT_DISABLED
Element webhook zwraca kod >błędu = 429 Orkiestracja usługi DPS będzie ponawiana kilka razy. Zasady ponawiania prób są obecnie następujące:

  - Liczba ponownych prób: 10
  - Interwał początkowy: 1 s
  - Przyrost: 9 s		 Zestaw SDK zignoruje błąd i prześle kolejny komunikat o stanie pobierania w określonym czasie
Element webhook zwraca dowolny inny kod stanu Stan wyniku: Niepowodzenie

Kod błędu: CustomAllocationFailed (400207)		 Zestaw SDK zwraca PROV_DEVICE_RESULT_DEV_AUTH_ERROR

Czyszczenie zasobów

Jeśli planujesz kontynuować pracę z zasobami utworzonymi w tym samouczku, możesz je pozostawić. Jeśli nie planujesz kontynuować korzystania z zasobów, wykonaj następujące kroki, aby usunąć wszystkie zasoby utworzone w tym samouczku, aby uniknąć niepotrzebnych opłat.

W poniższych krokach przyjęto założenie, że wszystkie zasoby utworzone w tym samouczku zostały utworzone zgodnie z instrukcjami w tej samej grupie zasobów o nazwie contoso-us-resource-group.

Ważne

Usunięcie grupy zasobów jest nieodwracalne. Grupa zasobów oraz wszystkie zawarte w niej zasoby zostaną trwale usunięte. Uważaj, aby nie usunąć przypadkowo niewłaściwych zasobów lub niewłaściwej grupy zasobów. Jeśli usługa IoT Hub została utworzona wewnątrz istniejącej grupy zasobów zawierającej zasoby, które chcesz zachować, zamiast usuwać całą grupę zasobów, usuń tylko zasób usługi IoT Hub.

Aby usunąć grupę zasobów według nazwy:

  1. Zaloguj się do witryny Azure Portal i wybierz pozycję Grupy zasobów.

  2. W polu tekstowym Filtruj według nazwy ... wpisz nazwę grupy zasobów zawierającej zasoby contoso-us-resource-group.

  3. Po prawej stronie grupy zasobów na liście wyników wybierz pozycję ... a następnie pozycję Usuń grupę zasobów.

  4. Zostanie wyświetlony monit o potwierdzenie usunięcia grupy zasobów. Ponownie wpisz nazwę grupy zasobów, aby potwierdzić, a następnie wybierz pozycję Usuń. Po krótkim czasie grupa zasobów i wszystkie zawarte w niej zasoby zostaną usunięte.

Następne kroki

Aby dowiedzieć się więcej o niestandardowych zasadach alokacji, zobacz

Omówienie niestandardowych zasad alokacji