Korzystanie z modeli IoT Plug and Play w rozwiązaniu IoT

Artykuł
08/30/2024

W tym artykule opisano, jak w rozwiązaniu IoT można zidentyfikować identyfikator modelu urządzenia IoT Plug and Play, a następnie pobrać jego definicję modelu.

Istnieją dwie szerokie kategorie rozwiązań IoT:

Specjalnie utworzone rozwiązanie współpracuje ze znanym zestawem modeli dla urządzeń IoT Plug and Play, które łączą się z rozwiązaniem. Te modele są używane podczas tworzenia rozwiązania.
Rozwiązanie oparte na modelu współdziała z modelem dowolnego urządzenia IoT Plug and Play. Tworzenie rozwiązania opartego na modelu jest bardziej złożone, ale zaletą jest to, że rozwiązanie współpracuje z dowolnymi urządzeniami, które są dodawane w przyszłości. Rozwiązanie IoT oparte na modelu pobiera model i używa go do określania telemetrii, właściwości i poleceń implementowanych przez urządzenie.

Aby użyć modelu IoT Plug and Play, rozwiązanie IoT:

Identyfikuje identyfikator modelu implementowany przez urządzenie, moduł i moduł usługi IoT Plug and Play połączony z rozwiązaniem.
Używa identyfikatora modelu, aby pobrać definicję modelu połączonego urządzenia z repozytorium modelu lub magazynu niestandardowego.

Identyfikowanie identyfikatora modelu

Gdy urządzenie usługi IoT Plug and Play łączy się z usługą IoT Hub, rejestruje identyfikator modelu, który implementuje w usłudze IoT Hub.

Usługa IoT Hub powiadamia rozwiązanie o identyfikatorze modelu urządzenia w ramach przepływu połączenia urządzenia.

Rozwiązanie może uzyskać identyfikator modelu urządzenia IoT Plug and Play przy użyciu jednej z następujących trzech metod:

Uzyskiwanie interfejsu API bliźniaczej reprezentacji urządzenia

Rozwiązanie może użyć interfejsu API pobierania bliźniaczej reprezentacji urządzenia do pobierania identyfikatora modelu urządzenia IoT Plug and Play.

Napiwek

W przypadku modułów i modułów usługi IoT Edge użyj modułu ModuleClient.getTwin.

W poniższym fragmencie modelId odpowiedzi bliźniaczej reprezentacji urządzenia zawiera identyfikator modelu urządzenia IoT Plug and Play:

{
    "deviceId": "sample-device",
    "etag": "AAAAAAAAAAc=",
    "deviceEtag": "NTk0ODUyODgx",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00Z",
    "connectionState": "Disconnected",
    "lastActivityTime": "2020-07-17T06:12:26.8402249Z",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "modelId": "dtmi:com:example:TemperatureController;1",
    "version": 15,
    "properties": {...}
    }
}

Uzyskiwanie interfejsu API usługi Digital Twin

Rozwiązanie może użyć interfejsu API Get Digital Twin w celu pobrania identyfikatora modelu wdrożonego przez urządzenie IoT Plug and Play.

W poniższym fragmencie $metadata.$model odpowiedzi cyfrowej reprezentacji bliźniaczej zawiera identyfikator modelu urządzenia IoT Plug and Play:

{
    "$dtId": "sample-device",
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

Powiadomienie o zdarzeniu zmiany cyfrowej reprezentacji bliźniaczej

Połączenie urządzenia powoduje powiadomienie o zmianie usługi Digital Twin. Rozwiązanie musi subskrybować to powiadomienie o zdarzeniu. Aby dowiedzieć się, jak włączyć routing dla zdarzeń cyfrowej reprezentacji bliźniaczej, zobacz Używanie routingu komunikatów usługi IoT Hub w celu wysyłania komunikatów z urządzenia do chmury do różnych punktów końcowych.

Rozwiązanie może użyć zdarzenia pokazanego w poniższym fragmencie kodu, aby dowiedzieć się więcej o urządzeniu IoT Plug and Play, które łączy się i pobiera identyfikator modelu:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:com:example:TemperatureController;1"
  }
]

Pobieranie definicji modelu

Rozwiązanie używa wcześniej zidentyfikowanego identyfikatora modelu w celu pobrania odpowiedniej definicji modelu.

Rozwiązanie może uzyskać definicję modelu przy użyciu jednej z następujących opcji:

Repozytorium modeli

Rozwiązania mogą pobierać modele DTDL z repozytorium modelu urządzenia (DMR). DmR to repozytorium publiczne hostowane przez firmę Microsoft, które zawiera kolekcję wyselekcjonowanych modeli DTDL. Modele urządzeń publicznych przechowywanych w usłudze DMR są dostępne dla wszystkich użytkowników, którzy mogą korzystać z aplikacji i integrować je z publicznego punktu końcowego https://devicemodels.azure.com.

Po zidentyfikowaniu identyfikatora modelu dla nowego połączenia urządzenia wykonaj następujące kroki:

Pobierz definicję modelu przy użyciu identyfikatora modelu z repozytorium modelu. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z modelami.
Korzystając z definicji modelu połączonego urządzenia, można wyliczyć możliwości urządzenia.
Korzystając z wyliczonych możliwości urządzenia, można umożliwić użytkownikom interakcję z urządzeniem.

Rozwiązywanie problemów z modelami

Konwencje DMR zawierają inne artefakty upraszczające korzystanie z hostowanych modeli. Te funkcje są opcjonalne dla repozytoriów niestandardowych lub prywatnych.

Indeks. Wszystkie dostępne interfejsy DTMI są udostępniane za pośrednictwem indeksu składającego się z sekwencji plików json, na przykład:https://devicemodels.azure.com/index.page.2.json
Rozwinięte. Plik ze wszystkimi zależnościami jest dostępny dla każdego interfejsu, na przykład: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadane. Ten plik uwidacznia kluczowe atrybuty repozytorium i jest okresowo odświeżany przy użyciu najnowszej opublikowanej migawki modeli. Zawiera ona funkcje implementowane przez repozytorium, takie jak dostępność indeksu modelu lub rozszerzonych plików modelu. Dostęp do metadanych DMR można uzyskać pod adresem https://devicemodels.azure.com/metadata.json

Aby programowo uzyskać dostęp do publicznych modeli DTDL w usłudze DMR, możesz użyć ModelsRepositoryClient dostępnych w pakiecie NuGet Azure.IoT.ModelsRepository. Ten klient jest domyślnie skonfigurowany do wykonywania zapytań dotyczących publicznej pamięci DMR dostępnej w devicemodels.azure.com i można go skonfigurować do dowolnego repozytorium niestandardowego.

Klient akceptuje DTMI jako dane wejściowe i zwraca słownik ze wszystkimi wymaganymi interfejsami:

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

Oczekiwane dane wyjściowe wyświetlają DTMI trzy interfejsy znalezione w łańcuchu zależności:

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

Można ModelsRepositoryClient go skonfigurować tak, aby wykonywać zapytania dotyczące niestandardowego dmr dostępnego za pośrednictwem protokołu https-- i określić rozwiązanie zależności przy użyciu flagi ModelDependencyResolution :

Wyłączone. Zwraca tylko określony interfejs bez żadnej zależności.
Włączona. Zwraca wszystkie interfejsy w łańcuchu zależności

Napiwek

Repozytoria niestandardowe mogą nie uwidocznić .expanded.json pliku. Jeśli ten plik nie jest dostępny, klient wróci do przetwarzania każdej zależności lokalnie.

Poniższy przykładowy kod pokazuje, jak zainicjować ModelsRepositoryClient metodę przy użyciu niestandardowego podstawowego adresu URL repozytorium, w tym przypadku przy użyciu raw adresów URL z interfejsu API usługi GitHub bez użycia expanded formularza, ponieważ nie jest on dostępny w raw punkcie końcowym. Element AzureEventSourceListener jest inicjowany w celu sprawdzenia żądania HTTP wykonywanego przez klienta:

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

W repozytorium GitHub zestawu Azure SDK jest dostępnych więcej przykładów: Azure.Iot.ModelsRepository/samples.

Magazyn niestandardowy

Rozwiązania mogą przechowywać te definicje modelu w lokalnym systemie plików, w publicznym magazynie plików lub używać niestandardowej implementacji.

Po zidentyfikowaniu identyfikatora modelu dla nowego połączenia urządzenia wykonaj następujące kroki:

Pobierz definicję modelu przy użyciu identyfikatora modelu z magazynu niestandardowego.
Korzystając z definicji modelu połączonego urządzenia, można wyliczyć możliwości urządzenia.
Korzystając z wyliczonych możliwości urządzenia, można umożliwić użytkownikom interakcję z urządzeniem.

Następne kroki

Teraz, gdy wiesz już, jak zintegrować modele IoT Plug and Play w rozwiązaniu IoT, poniżej przedstawiono kilka sugerowanych następnych kroków:

Udostępnij za pośrednictwem