Omówienie niestandardowych zasad alokacji za pomocą usługi Azure IoT Hub Device Provisioning

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.

Zasady alokacji niestandardowej można zaimplementować w elemecie webhook hostowanym w usłudze Azure Functions. Następnie można skonfigurować element webhook w co najmniej jednej indywidualnej rejestracji i grupach rejestracji. Gdy urządzenie rejestruje się za pomocą skonfigurowanego wpisu rejestracji, usługa DPS wywołuje element webhook, który zwraca centrum IoT w celu zarejestrowania urządzenia w usłudze i, opcjonalnie, początkowe ustawienia bliźniaczej reprezentacji urządzenia i wszelkie informacje, które mają zostać zwrócone bezpośrednio do urządzenia.

Omówienie

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

1. Niestandardowy deweloper alokacji opracowuje element webhook, który implementuje zamierzone zasady alokacji i wdraża go jako funkcję wyzwalacza HTTP w usłudze Azure Functions. Element webhook pobiera informacje o wpisie rejestracji usługi DPS oraz urządzeniu i zwraca centrum IoT Hub, do którego należy zarejestrować urządzenie, oraz, opcjonalnie, informacje o stanie początkowym urządzenia.

2. Operator IoT konfiguruje co najmniej jedną pojedynczą rejestrację i/lub grupy rejestracji na potrzeby alokacji niestandardowej i udostępnia szczegóły wywołania niestandardowego elementu webhook alokacji w usłudze Azure Functions.

3. Gdy urządzenie rejestruje się za pośrednictwem wpisu rejestracji skonfigurowanego dla niestandardowego elementu webhook alokacji, usługa DPS wysyła żądanie POST do elementu webhook z treścią żądania ustawioną na obiekt żą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ć opcjonalny niestandardowy ładunek wysyłany z urządzenia w żądaniu rejestracji. Aby uzyskać więcej informacji, zobacz Niestandardowe żądanie zasad alokacji.

4. Funkcja platformy Azure wykonuje i zwraca obiekt AllocationResponse w przypadku powodzenia. Obiekt AllocationResponse zawiera centrum IoT Hub, do których należy aprowizować urządzenie, początkowy stan bliźniaczej reprezentacji i opcjonalny niestandardowy ładunek, aby powrócić 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 początkowy stan bliźniaczej reprezentacji. Jeśli niestandardowy ładunek jest 00000000000000000000000000000000000000000000000000000000returned w odpowiedzi rejestracji, urządzenie używa go zgodnie z własną logiką po stronie klienta.

Poniższe sekcje zawierają więcej szczegółowych informacji na temat niestandardowego żądania alokacji i odpowiedzi, niestandardowych ładunków i implementacji zasad. Pełny przykład niestandardowych zasad alokacji można znaleźć w temacie Use custom allocation policies (Używanie niestandardowych zasad alokacji).

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 Functionwartość . 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 witrynie Azure Portal i określania niestandardowych zasad alokacji portal automatycznie obsługuje pobieranie i osadzanie klucza funkcji.

Po wybraniu funkcji dla niestandardowych zasad 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 elementu webhook używanego przez usługę DPS do wywoływania 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 .

Klucze funkcji 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 wyzwalacza > HTTP usługi Azure Functions.

Żądanie niestandardowych zasad alokacji

Usługa DPS wysyła żądanie POST do elementu webhook w następującym punkcie końcowym: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

Treść żądania jest obiektem AllocationRequest :

Nazwa właściwości	Opis
individualEnrollment	Indywidualny rekord rejestracji zawierający właściwości skojarzone z rejestracją indywidualną, z którego pochodzi żądanie alokacji. Przedstawia, czy urządzenie rejestruje się w ramach rejestracji indywidualnej.
enrollmentGroup	Rekord grupy rejestracji zawierający właściwości skojarzone z grupą rejestracji, z którą pochodzi żądanie alokacji. Przedstawia, czy urządzenie jest rejestrowane za pośrednictwem grupy rejestracji.
deviceRuntimeContext	Obiekt, który zawiera właściwości skojarzone z rejestrowanym urządzeniem. Zawsze obecne.
linkedHubs	Tablica zawierająca nazwy hostów centrów IoT, które są połączone z wpisem rejestracji, z którego pochodzi żądanie alokacji. Urządzenie może być przypisane do dowolnego z tych centrów IoT. Zawsze obecne.

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

Właściwość	Type	Opis
identyfikator rejestracji	string	Identyfikator rejestracji dostarczony przez urządzenie w czasie wykonywania. Zawsze obecne.
currentIotHubHostName	string	Nazwa hosta centrum IoT Hub, do którego urządzenie zostało wcześniej przypisane (jeśli istnieje). Nie ma, jeśli jest to początkowe przypisanie. Za pomocą tej właściwości można określić, czy jest to początkowe przypisanie urządzenia, czy też urządzenie zostało wcześniej przypisane.
currentDeviceId	string	Identyfikator urządzenia z poprzedniego przypisania urządzenia (jeśli istnieje). Nie ma, jeśli jest to początkowe przypisanie.
x509	X509DeviceAttestation	W przypadku zaświadczania X.509 zawiera szczegóły certyfikatu.
symmetricKey	SymmetricKeyAttestation	W przypadku zaświadczania klucza symetrycznego zawiera szczegóły klucza podstawowego i pomocniczego.
tpm	TpmAttestation	W przypadku zaświadczania modułu TPM zawiera szczegóły klucza poręczenia i klucza głównego magazynu.
payload	obiekt	Zawiera właściwości określone przez urządzenie we właściwości ładunku podczas rejestracji. Występuje, jeśli urządzenie wysyła niestandardowy ładunek w żądaniu rejestracji usługi DPS.

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 i identyfikator urządzenia usługi IoT Hub 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 .

Właściwości	opis
initialTwin	Opcjonalny. Obiekt zawierający żądane właściwości i tagi do ustawienia w początkowej reprezentacji bliźniaczej w przypisanym centrum IoT. Usługa DPS używa właściwości initialTwin, aby ustawić początkową reprezentację bliźniaczą w przypisanym centrum IoT w ramach przypisania początkowego lub podczas ponownej aprowizacji, jeśli zasady migracji wpisu rejestracji zostały ustawione na wartość Reprovision i resetuj do początkowej konfiguracji. W obu tych przypadkach, jeśli initialTwin nie jest zwracany lub jest ustawiony na wartość null, usługa DPS ustawia bliźniacze reprezentację w przypisanym centrum IoT do początkowych ustawień bliźniaczej reprezentacji w wpisie rejestracji. Usługa DPS ignoruje wartość initialTwin dla wszystkich innych ustawień ponownej aprowizacji we wpisie rejestracji. Aby dowiedzieć się więcej, zobacz Szczegóły implementacji.
iotHubHostName	Wymagany. Nazwa hosta centrum IoT Do przypisania urządzenia. Musi to być jedno z centrów IoT przekazanych we właściwości linkedHubs w żądaniu.
payload	Opcjonalny. Obiekt zawierający dane, które mają zostać przekazane z powrotem do urządzenia w odpowiedzi na rejestrację. Dokładne dane zależą od niejawnego kontraktu zdefiniowanego przez dewelopera między urządzeniem a niestandardową funkcją alokacji.

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

{
   "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, na przykład 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 przekaże ten ładunek do niestandardowego elementu webhook alokacji, który określi centrum IoT Hub, do którego będzie aprowizowane urządzenie na podstawie informacji o modelu urządzenia. W razie potrzeby element webhook może zwrócić dane z powrotem do usługi DPS jako obiekt JSON w odpowiedzi elementu webhook, a usługa DPS zwróci te dane do urządzenia w odpowiedzi rejestracji.

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

Urządzenie wywołuje interfejs API rejestracji w celu zarejestrowania się w usłudze DPS. Żądanie można ulepszyć za pomocą opcjonalnej właściwości ładunku . Ta właściwość może zawierać dowolny prawidłowy obiekt JSON. Dokładna zawartość będzie zależeć 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 ładunek danych do niestandardowego elementu webhook alokacji

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

W przypadku żądania rejestracji modułu TPM w poprzedniej sekcji kontekst środowiska uruchomieniowego urządzenia będzie 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 będzie również zawierać currentIoTHubHostname i właściwości currentDeviceId .

Niestandardowy element 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 elementu webhook, przekazuje te dane z powrotem do urządzenia w właściwości RegistrationOperationStatus.registrationState.payload w odpowiedzi na pomyślną rejestrację. 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 element webhook alokacji może być wywoływany dla urządzenia, które nie zostało wcześniej zarejestrowane za pośrednictwem usługi DPS (przypisania początkowego) lub dla urządzenia, które zostało wcześniej zarejestrowane za pośrednictwem usługi DPS (ponowne aprowizowanie). Usługa DPS obsługuje następujące zasady ponownego aprowizowania: Ponowne aprowizowanie i migrowanie danych, Ponowne aprowizowanie i resetowanie do początkowej konfiguracji i Nigdy nie należy ponownie 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 Ponowne aprowizowanie.

W poniższych punktach opisano wymagania dotyczące niestandardowego elementu webhook alokacji i zachowania, o których należy pamiętać podczas projektowania elementu webhook:

• 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, będą one zawierać wszystkie centra IoT połączone z wystąpieniem usługi DPS. Na koniec, jeśli urządzenie jest ponownie aprowizacji, a zasady Nigdy nie aprowizacji są ustawione we wpisie rejestracji, będzie zawierać tylko centrum IoT, do którego jest aktualnie przypisane urządzenie.

• W przypadku przypisania początkowego , jeśli właściwość initialTwin jest zwracana przez element webhook, usługa DPS ustawi 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, usługa DPS ustawia początkową reprezentację bliźniacze dla urządzenia na początkowe ustawienie bliźniaczej reprezentacji określonej 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żące centrum IoT zostanie zmienione, 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ątkową reprezentację bliźniacze dla urządzenia w nowym centrum IoT hub dokładnie tak samo jak podczas początkowego przypisania w poprzednim punkcie. We wszystkich innych przypadkach usługa DPS ignoruje właściwość initialTwin .

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

• Jeśli urządzenie zostało wcześniej aprowizowane w centrum IoT, właściwość AllocationRequest.deviceRuntimeContext będzie zawierać właściwość currentIotHubHostName , która zostanie ustawiona na nazwę hosta centrum IoT, w którym urządzenie jest aktualnie przypisane.

• Możesz określić, które z zasad ponownej aprowizacji jest obecnie ustawione we wpisie rejestracji, sprawdzając właściwość reprovisionPolicy właściwości AllocationRequest.individualEnrollment lub AllocationRequest.enrollmentGroup w żądaniu. Poniższy kod JSON przedstawia ustawienia zasad ponownej aprowizacji 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 na temat zestawów 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 SDK usługi Azure DPS.

Następne kroki

• Aby zapoznać się z kompleksowego przykładu przy użyciu niestandardowych zasad alokacji, zobacz Używanie niestandardowych zasad alokacji

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