Zrozumienie niestandardowych zasad alokacji w usłudze Azure IoT Hub Device Provisioning Service

Niestandardowe zasady alokacji zapewniają większą kontrolę nad tym, jak urządzenia są przypisywane do centrów IoT. Korzystając z niestandardowych zasad alokacji, można zdefiniować własne zasady alokacji, gdy wbudowane zasady udostępniane przez usługę Device Provisioning Service (DPS) nie spełniają wymagań danego scenariusza.

Na przykład może chcesz sprawdzić certyfikat używany przez urządzenie podczas aprowizacji i przypisać urządzenie do centrum IoT Na podstawie właściwości certyfikatu. A może masz informacje przechowywane w bazie danych dla urządzeń i musisz wysłać zapytanie do bazy danych, aby określić, do którego centrum IoT hub ma zostać przypisane urządzenie, lub sposób ustawienia początkowej reprezentacji bliźniaczej urządzenia.

Implementujesz niestandardową politykę alokacji w elemencie webhook hostowanym w usłudze Azure Functions. Następnie można skonfigurować webhook w jednej lub więcej indywidualnych rejestracjach i grupach rejestracyjnych. Gdy urządzenie rejestruje się za pomocą skonfigurowanego wpisu rejestracji, usługa Device Provisioning Service (DPS) wywołuje webhook, który zwraca centrum IoT do zarejestrowania urządzenia oraz, opcjonalnie, początkowe ustawienia cyfrowego bliźniaka urządzenia oraz wszelkie informacje, które mają zostać przekazane bezpośrednio do urządzenia.

Omówienie

W poniższych krokach opisano sposób działania niestandardowych policji alokacji:

1. Deweloper niestandardowych alokacji opracowuje webhook, który implementuje zamierzoną politykę alokacji i wdraża ją jako funkcję HTTP Trigger w usłudze Azure Functions. Webhook pobiera informacje o wpisie rejestracji w usłudze DPS oraz urządzeniu i zwraca IoT hub, do którego należy zarejestrować urządzenie, oraz, opcjonalnie, informacje o stanie początkowym urządzenia.

2. Operator systemów IoT konfiguruje jedną lub więcej indywidualnych rejestracji i/lub grup rejestracji dla niestandardowej alokacji oraz dostarcza szczegóły dotyczące wywołania niestandardowego webhooka alokacji w Azure Functions.

3. Gdy urządzenie rejestruje się za pośrednictwem wpisu rejestracji skonfigurowanego dla niestandardowego webhooka alokacji, usługa DPS wysyła żądanie POST do webhooka z treścią żądania w postaci obiektu żądania AllocationRequest. Obiekt AllocationRequest zawiera informacje o urządzeniu, które próbuje aprowizować, oraz indywidualną rejestrację lub grupę rejestracji, za pośrednictwem której jest aprowizowana. Informacje o urządzeniu mogą zawierać dodatkowy niestandardowy ładunek wysyłany z urządzenia w żądaniu rejestracji. Aby uzyskać więcej informacji, zobacz Żądanie dotyczące zasad niestandardowej alokacji.

4. Funkcja platformy Azure wykonuje i zwraca obiekt AllocationResponse w przypadku powodzenia. Obiekt AllocationResponse zawiera centrum IoT, do którego należy aprowizować urządzenie, początkowy stan reprezentacji bliźniaczej oraz opcjonalny niestandardowy ładunek do zwrotu do urządzenia. Aby uzyskać więcej informacji, zobacz Niestandardowa odpowiedź na zasady alokacji.

5. Usługa DPS przypisuje urządzenie do centrum IoT hub wskazanego w odpowiedzi, a w przypadku zwrócenia początkowej reprezentacji bliźniaczej ustawia odpowiednio początkową reprezentację bliźniacze dla urządzenia. Jeśli niestandardowy ładunek jest zwracany przez element webhook, jest przekazywany do urządzenia wraz z przypisanym centrum IoT i szczegółami uwierzytelniania w odpowiedzi rejestracji z usługi DPS.

6. Urządzenie łączy się z przypisanym centrum IoT i pobiera swój początkowy stan cyfrowego bliźniaka. Jeśli niestandardowy ładunek zostanie zwrócony w odpowiedzi na rejestrację, urządzenie użyje go zgodnie ze swoją logiką klienta.

Poniższe sekcje zawierają więcej szczegółowych informacji na temat żądań i odpowiedzi dotyczących niestandardowej alokacji, ładunków specjalnych oraz wdrażania zasad. Aby uzyskać więcej informacji na temat kompletnego kompleksowego przykładu niestandardowych zasad alokacji, zobacz Samouczek: używanie niestandardowych zasad alokacji z usługą Device Provisioning Service (DPS).

Zarządzanie kluczami funkcji

Niestandardowe zasady alokacji używają kluczy funkcji do uwierzytelniania wywołań w usłudze Azure Functions, gdzie poziom autoryzacji jest ustawiony na Function. Zachowanie zarządzania kluczami różni się w zależności od tego, czy zasady alokacji niestandardowej są konfigurowane za pośrednictwem witryny Azure Portal, czy programowo.

Klucze funkcji w portalu

Podczas tworzenia rejestracji w portalu Azure i określania niestandardowej polityki alokacji portal automatycznie obsługuje pobieranie i osadzanie klucza funkcji.

Po wybraniu funkcji dla niestandardowej polityki alokacji, portal pobiera klucz funkcji. Ten krok nie jest widoczny dla użytkowników za pośrednictwem interfejsu portalu. Następnie klucz funkcji jest przechowywany jako część zaszyfrowanego adresu URL webhooka używanego przez usługę DPS do wywołania tej funkcji. Klucz nie jest wyświetlany w portalu.

Aby pobrać szczegóły rejestracji, możesz sprawdzić, czy klucz jest osadzony w adresie URL elementu webhook. W konfiguracji rejestracji klucz funkcji jest uwzględniony w polu webhookUrl .

Klawisze funkcyjne z interfejsami API

Podczas programowego tworzenia rejestracji przy użyciu interfejsu API usługi DPS należy ręcznie podać klucz podczas tworzenia rejestracji. Jeśli klucz nie zostanie podany, wywołanie usługi Azure Functions zakończy się niepowodzeniem uwierzytelniania.

Przed utworzeniem rejestracji indywidualnej lub grupowej pobierz klucz funkcji z funkcji. Aby uzyskać więcej informacji, zobacz Pobieranie kluczy dostępu funkcji. Następnie dołącz klucz funkcji w polu webhookUrl elementu CustomAllocationDefinition.

Aby uzyskać więcej informacji, zobacz Autoryzacja klucza dostępu.

Żądanie niestandardowej polityki alokacji

Usługa DPS wysyła żądanie POST do webhooka na następujący punkt końcowy: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

Treść żądania jest obiektem AllocationRequest :

Obiekt DeviceRuntimeContext ma następujące właściwości:

Poniższy kod JSON przedstawia obiekt AllocationRequest wysyłany przez usługę DPS dla urządzenia rejestrującego się za pośrednictwem grupy rejestracji opartej na kluczu symetrycznym.

{
   "enrollmentGroup":{
      "enrollmentGroupId":"contoso-custom-allocated-devices",
      "attestation":{
         "type":"symmetricKey"
      },
      "capabilities":{
         "iotEdge":false
      },
      "etag":"\"13003fea-0000-0300-0000-62d1d5e50000\"",
      "provisioningStatus":"enabled",
      "reprovisionPolicy":{
         "updateHubAssignment":true,
         "migrateDeviceData":true
      },
      "createdDateTimeUtc":"2022-07-05T21:27:16.8123235Z",
      "lastUpdatedDateTimeUtc":"2022-07-15T21:02:29.5922255Z",
      "allocationPolicy":"custom",
      "iotHubs":[
         "custom-allocation-toasters-hub.azure-devices.net",
         "custom-allocation-heatpumps-hub.azure-devices.net"
      ],
      "customAllocationDefinition":{
         "webhookUrl":"https://custom-allocation-function-app-3.azurewebsites.net/api/HttpTrigger1?****",
         "apiVersion":"2021-10-01"
      }
   },
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
   "linkedHubs":[
      "custom-allocation-toasters-hub.azure-devices.net",
      "custom-allocation-heatpumps-hub.azure-devices.net"
   ]
}

Ponieważ jest to początkowa rejestracja urządzenia, właściwość deviceRuntimeContext zawiera tylko identyfikator rejestracji i szczegóły uwierzytelniania urządzenia. Poniższy kod JSON przedstawia element deviceRuntimeContext dla kolejnego wywołania w celu zarejestrowania tego samego urządzenia. Zwróć uwagę, że bieżąca nazwa hosta centrum IoT i identyfikator urządzenia są uwzględnione w żądaniu.

{
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "currentIotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
      "currentDeviceId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
}

Odpowiedź na niestandardowe zasady alokacji

Pomyślne żądanie zwraca obiekt AllocationResponse .

Poniższy kod JSON przedstawia obiekt AllocationResponse zwrócony przez niestandardową funkcję alokacji do usługi DPS na potrzeby rejestracji w poprzednim przykładzie.

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   }
}

Używanie ładunków urządzeń w ramach alokacji niestandardowej

Urządzenia mogą wysyłać niestandardowy ładunek przekazywany przez usługę DPS do niestandardowego elementu webhook alokacji, który może następnie używać tych danych w logice. Element webhook może używać tych danych na wiele sposobów, być może w celu określenia, do którego centrum IoT ma zostać przypisane urządzenie, lub do wyszukania informacji w zewnętrznej bazie danych, która może służyć do ustawiania właściwości początkowej reprezentacji bliźniaczej. Z drugiej strony element webhook może zwracać dane z powrotem do urządzenia za pośrednictwem usługi DPS, która może być używana w logice po stronie klienta urządzenia.

Możesz na przykład przydzielić urządzenia na podstawie modelu urządzenia. W takim przypadku urządzenie można skonfigurować tak, aby zgłaszało informacje o modelu w ładunku żądania podczas rejestrowania się w usłudze DPS. Usługa DPS przekazuje ten ładunek do niestandardowego webhooka alokacyjnego, który określa, do którego huba IoT urządzenie jest przypisane na podstawie informacji o modelu urządzenia. W razie potrzeby webhook może zwracać dane z powrotem do usługi DPS jako obiekt JSON w swojej odpowiedzi, a następnie usługa DPS zwraca te dane do urządzenia w odpowiedzi na rejestrację.

Urządzenie wysyła ładunek danych do usługi DPS

Urządzenie wywołuje interfejs API rejestracji usługi DPS w celu zarejestrowania się w usłudze DPS. Żądanie można ulepszyć dzięki opcjonalnej właściwości payload. Ta właściwość może zawierać dowolny prawidłowy obiekt JSON. Dokładna zawartość zależy od wymagań rozwiązania.

W przypadku zaświadczania za pomocą modułu TPM treść żądania wygląda następująco:

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
} 

Usługa DPS wysyła payload danych do niestandardowego webhooku alokacji

Jeśli urządzenie zawiera ładunek w jego żądaniu rejestracji, usługa DPS przekazuje ładunek we właściwości AllocationRequest.deviceRuntimeContext.payload, gdy wywołuje niestandardowy webhook alokacji.

W przypadku żądania rejestracji modułu TPM w poprzedniej sekcji kontekst środowiska uruchomieniowego urządzenia wygląda następująco:

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
} 

Jeśli nie jest to początkowa rejestracja urządzenia, kontekst środowiska uruchomieniowego zawiera również currentIoTHubHostname i właściwości currentDeviceId .

Niestandardowy webhook alokacji zwraca dane do usługi DPS

Niestandardowy element webhook zasad alokacji może zwracać dane przeznaczone dla urządzenia do usługi DPS w obiekcie JSON przy użyciu właściwości AllocationResponse.payload w odpowiedzi elementu webhook.

Poniższy kod JSON przedstawia odpowiedź elementu webhook zawierającą ładunek:

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   },
   "payload": { "property1": "value1" } 
}

Usługa DPS wysyła ładunek danych do urządzenia

Jeśli usługa DPS odbiera ładunek w odpowiedzi webhooka, przekazuje te dane z powrotem do urządzenia w właściwości RegistrationOperationStatus.registrationState.payload w przypadku pomyślnej rejestracji. Właściwość registrationState jest typu DeviceRegistrationResult.

Poniższy kod JSON przedstawia pomyślną odpowiedź rejestracji dla urządzenia TPM zawierającego właściwość ładunku:

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "assignedHub":"myIotHub",
      "createdDateTimeUtc" : "2022-08-01T22:57:47Z",
      "deviceId" : "myDeviceId",
      "etag" : "xxxx-etag-value-xxxxx",
      "lastUpdatedDateTimeUtc" : "2022-08-01T22:57:47Z",
      "payload": { "property1": "value1" },
      "registrationId": "mydevice", 
      "status": assigned,
      "substatus": initialAssignment,
      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"}
   }
}

Szczegóły implementacji

Niestandardowy webhook alokacji może być wywoływany dla urządzenia, które nie zostało wcześniej zarejestrowane przez DPS (przypisanie początkowe) lub dla urządzenia, które zostało wcześniej zarejestrowane przez DPS (ponowne aprowizowanie). System DPS obsługuje następujące polityki ponownego aprowizowania: Ponowne aprowizowanie i migrowanie danych, Ponowne aprowizowanie i resetowanie do początkowej konfiguracji oraz Nigdy nie ponawiać aprowizacji. Te zasady są stosowane za każdym razem, gdy wcześniej aprowizowane urządzenie zostanie przypisane do nowego centrum IoT. Aby uzyskać więcej informacji, zobacz IoT Hub Device reprovisioning concepts.

W poniższych punktach opisano wymagania, które musi spełniać Twój niestandardowy webhook alokacji oraz zachowania, o których należy pamiętać podczas projektowania webhooka.

• Urządzenie powinno być przypisane do jednego z centrów IoT w właściwości AllocationRequest.linkedHubs . Ta właściwość zawiera listę centrów IoT według nazwy hosta, do których można przypisać urządzenie. Zazwyczaj składa się to z centrów IoT wybranych dla wpisu rejestracji. Jeśli w wpisie rejestracji nie wybrano żadnych centrów IoT, zawiera on wszystkie centra IoT połączone z wystąpieniem usługi DPS. Na koniec, jeśli urządzenie jest ponownie aprowizowane, a polityka Nigdy nie ponownie aprowizuj jest ustawiona we wpisie rejestracji, zawiera tylko centrum IoT, do którego urządzenie jest obecnie przypisane.

• W przypadku przypisania początkowego, jeśli właściwość initialTwin jest zwracana przez element webhook, usługa DPS ustawia początkową reprezentację bliźniaczą dla urządzenia w przypisanym centrum IoT. Jeśli właściwość initialTwin zostanie pominięta lub ma wartość null, DPS ustawia początkową reprezentację bliźniaczą dla urządzenia zgodnie z ustawieniem określonym we wpisie rejestracji.

• Podczas ponownej aprowizacji usługa DPS jest zgodna z zasadami ponownego aprowizowania ustawionymi we wpisie rejestracji. Usługa DPS używa właściwości initialTwin w odpowiedzi tylko wtedy, gdy bieżący IoT hub zostanie zmieniony, a zasady ponownej aprowizacji ustawione we wpisie rejestracji to Ponowne aprowizowanie i resetowanie do początkowej konfiguracji. W takim przypadku usługa DPS ustawia początkowy twin dla urządzenia w nowym IoT hub dokładnie tak samo jak podczas przypisania początkowego w poprzednim punkcie. We wszystkich innych przypadkach DPS ignoruje właściwość initialTwin.

• Jeśli właściwość ładunku jest ustawiona w odpowiedzi, usługa DPS zawsze zwraca ją do urządzenia niezależnie od tego, czy żądanie dotyczy przypisania początkowego, czy ponownej aprowizacji.

• Jeśli urządzenie zostało wcześniej przydzielone do centrum IoT, AllocationRequest.deviceRuntimeContext zawiera currentIotHubHostName, ustawioną na nazwę hosta centrum IoT, do którego urządzenie jest obecnie przypisane.

• Możesz określić, która z zasad ponownej aprowizacji jest obecnie ustawiona we wpisie rejestracji, sprawdzając właściwość reprovisionPolicy w ramach AllocationRequest.individualEnrollment lub AllocationRequest.enrollmentGroup w żądaniu. Poniższy kod JSON przedstawia ustawienia polityki ponownego przygotowania i migracji danych:

         "reprovisionPolicy":{
            "updateHubAssignment":true,
            "migrateDeviceData":true
         }
  

Pomoc techniczna SDK

Zestawy SDK urządzeń DPS udostępniają interfejsy API w języku C, C#, Java i Node.js, aby ułatwić rejestrowanie urządzeń w usłudze DPS. Zestawy SDK usługi IoT Hub i zestawy SDK usługi DPS udostępniają klasy reprezentujące artefakty urządzeń i usług, takie jak bliźniacze reprezentacje urządzeń i wpisy rejestracji, które mogą być przydatne podczas tworzenia niestandardowych elementów webhook alokacji. Aby dowiedzieć się więcej o zestawach SDK usługi Azure IoT dostępnych dla usług IoT Hub i IoT Hub Device Provisioning, zobacz Zestawy SDK usługi Azure IoT Hub i zestawy MICROSOFT SDK dla usługi IoT Hub Device Provisioning.

Następne kroki

• Aby zapoznać się z kompleksowym przykładem z użyciem niestandardowej polityki alokacji, zobacz Samouczek: używanie niestandardowych zasad alokacji z usługą Device Provisioning Service (DPS)

• Aby dowiedzieć się więcej o usłudze Azure Functions, zobacz dokumentację usługi Azure Functions