Zarządzanie modelami usługi Azure Digital Twins

  • Artykuł

W tym artykule opisano sposób zarządzania modelami w wystąpieniu usługi Azure Digital Twins. Operacje zarządzania obejmują przekazywanie, walidację, pobieranie i usuwanie modeli.

Wymagania wstępne

Aby pracować z usługą Azure Digital Twins w tym artykule, musisz mieć wystąpienie usługi Azure Digital Twins i wymagane uprawnienia do korzystania z niego. Jeśli masz już skonfigurowane wystąpienie usługi Azure Digital Twins, możesz użyć tego wystąpienia i przejść do następnej sekcji. W przeciwnym razie postępuj zgodnie z instrukcjami w temacie Konfigurowanie wystąpienia i uwierzytelniania. Instrukcje zawierają informacje ułatwiające sprawdzenie, czy każdy krok został ukończony pomyślnie.

Po skonfigurowaniu wystąpienia zanotuj nazwę hosta wystąpienia. Nazwę hosta można znaleźć w witrynie Azure Portal.

Interfejsy deweloperskie

W tym artykule opisano sposób wykonywania różnych operacji zarządzania przy użyciu zestawu SDK platformy .NET (C#). Możesz również utworzyć te same wywołania zarządzania przy użyciu innych zestawów SDK języka opisanych w interfejsach API i zestawach SDK usługi Azure Digital Twins.

Inne interfejsy deweloperskie, których można użyć do wykonania tych operacji, to:

Wizualizacja

Azure Digital Twins Explorer to wizualne narzędzie do eksplorowania danych na grafie usługi Azure Digital Twins. Eksplorator umożliwia wyświetlanie, wykonywanie zapytań i edytowanie modeli, reprezentacji bliźniaczych i relacji.

Aby dowiedzieć się więcej o narzędziu Azure Digital Twins Explorer, zobacz Azure Digital Twins Explorer. Aby uzyskać szczegółowe instrukcje dotyczące korzystania z jej funkcji, zobacz Korzystanie z eksploratora usługi Azure Digital Twins.

Oto jak wygląda wizualizacja:

Screenshot of Azure Digital Twins Explorer showing a sample model graph.

Tworzenie modeli

Możesz tworzyć własne modele od podstaw lub używać istniejących nalogowań, które są dostępne dla Twojej branży.

Tworzenie modeli

Modele usługi Azure Digital Twins są zapisywane w języku DTDL i zapisywane jako pliki JSON. Istnieje również rozszerzenie DTDL dostępne dla programu Visual Studio Code, które zapewnia walidację składni i inne funkcje, aby ułatwić pisanie dokumentów DTDL.

Rozważmy przykład, w którym szpital chce cyfrowo reprezentować swoje pokoje. Każdy pokój zawiera inteligentny dozownik mydła do monitorowania mycia rąk i czujników do monitorowania ruchu przez pomieszczenie.

Pierwszym krokiem w kierunku rozwiązania jest utworzenie modeli reprezentujących aspekty szpitala. W tym scenariuszu można opisać salę pacjentów w następujący sposób:

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Uwaga

Jest to przykładowa treść pliku JSON, w którym model jest definiowany i zapisywany do przekazania w ramach projektu klienta. Z drugiej strony wywołanie interfejsu API REST przyjmuje tablicę definicji modelu, takich jak powyższy (który jest mapowany na element IEnumerable<string> w zestawie SDK platformy .NET). Dlatego aby użyć tego modelu bezpośrednio w interfejsie API REST, umieść go w nawiasach kwadratowych.

Ten model definiuje nazwę i unikatowy identyfikator pokoju pacjentów oraz właściwości reprezentujące liczbę odwiedzających i stan mycia ręcznego. Te liczniki zostaną zaktualizowane z czujników ruchu i inteligentnych dozowników mydła i będą używane razem do obliczania handwash percentage właściwości. Model definiuje również relację hasDevices, która będzie używana do łączenia wszystkich cyfrowych reprezentacji bliźniaczych na podstawie tego modelu Pokój z rzeczywistymi urządzeniami.

Uwaga

Istnieją pewne funkcje języka DTDL, których usługa Azure Digital Twins obecnie nie obsługuje, w tym writable atrybut właściwości i relacji oraz minMultiplicitymaxMultiplicity dla relacji. Aby uzyskać więcej informacji, zobacz Uwagi dotyczące języka DTDL specyficzne dla usługi.

Zgodnie z tą metodą można zdefiniować modele dla oddziałów, stref lub samego szpitala.

Jeśli Twoim celem jest utworzenie kompleksowego zestawu modeli opisującego domenę branżową, rozważ, czy istnieje istniejąca ontologia branżowa, której można użyć, aby ułatwić tworzenie modeli. W następnej sekcji opisano bardziej szczegółowo wdrożenia branżowe.

Korzystanie z istniejących nałogów standardowych w branży

Ontologia to zestaw modeli, które kompleksowo opisują daną domenę, takie jak produkcja, struktury budowlane, systemy IoT, inteligentne miasta, sieci energetyczne, zawartość internetowa i inne.

Jeśli Rozwiązanie jest przeznaczone dla określonej branży, która korzysta z dowolnego rodzaju standardu modelowania, rozważ rozpoczęcie od istniejącego zestawu modeli zaprojektowanych dla twojej branży zamiast projektowania modeli od podstaw. Firma Microsoft współpracuje z ekspertami z dziedziny, aby tworzyć dzienniki modelu DTDL oparte na standardach branżowych, aby pomóc zminimalizować ponowne tworzenie pomysłów i zachęcić do spójności i prostoty w różnych rozwiązaniach branżowych. Możesz dowiedzieć się więcej na temat tych nalogów, w tym jak ich używać i jakie dzienniki są teraz dostępne w temacie Co to jest ontologia?.

Weryfikowanie składni

Po utworzeniu modelu zaleca się zweryfikowanie modeli w trybie offline przed przekazaniem ich do wystąpienia usługi Azure Digital Twins.

Aby ułatwić weryfikowanie modeli, biblioteka analizy DTDL po stronie klienta platformy .NET jest udostępniana w usłudze NuGet: DTDLParser. Bibliotekę analizatora można używać bezpośrednio w kodzie języka C#. Przykładowe użycie analizatora można również wyświetlić w pliku DTDLParserResolveSample w usłudze GitHub.

Przekazywanie modeli

Po utworzeniu modeli można przekazać je do wystąpienia usługi Azure Digital Twins.

Gdy wszystko będzie gotowe do przekazania modelu, możesz użyć następującego fragmentu kodu dla zestawu .NET SDK:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

Podczas przekazywania pliki modelu są weryfikowane przez usługę.

Zazwyczaj musisz przekazać więcej niż jeden model do usługi. Istnieje kilka sposobów przekazywania wielu modeli jednocześnie w ramach jednej transakcji. Aby ułatwić wybór strategii, należy wziąć pod uwagę rozmiar zestawu modeli w pozostałej części tej sekcji.

Przekazywanie małych zestawów modeli

W przypadku mniejszych zestawów modeli można przekazać wiele modeli jednocześnie przy użyciu poszczególnych wywołań interfejsu API. Bieżący limit liczby modeli można przekazać w ramach pojedynczego wywołania interfejsu API w limitach usługi Azure Digital Twins.

Jeśli używasz zestawu SDK, możesz przekazać wiele plików modelu za CreateModels pomocą metody w następujący sposób:

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

Jeśli używasz interfejsów API REST lub interfejsu wiersza polecenia platformy Azure, możesz przekazać wiele modeli, umieszczając wiele definicji modelu w jednym pliku JSON do przekazania razem. W takim przypadku modele powinny zostać umieszczone w tablicy JSON w pliku, tak jak w poniższym przykładzie:

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Przekazywanie dużych zestawów modeli za pomocą interfejsu API importowania zadań

W przypadku dużych zestawów modeli można użyć interfejsu API importu zadań, aby przekazać wiele modeli jednocześnie w jednym wywołaniu interfejsu API. Interfejs API może jednocześnie zaakceptować limit usługi Azure Digital Twins dla liczby modeli w wystąpieniu i automatycznie zmienić kolejność modeli w razie potrzeby w celu rozwiązania zależności między nimi. Ta metoda wymaga użycia usługi Azure Blob Storage, a także uprawnień do zapisu w wystąpieniu usługi Azure Digital Twins dla modeli i zadań zbiorczych.

Napiwek

Interfejs API zadań importu umożliwia również importowanie bliźniaczych reprezentacji i relacji w tym samym wywołaniu w celu utworzenia wszystkich części grafu jednocześnie. Aby uzyskać więcej informacji na temat tego procesu, zobacz Przekazywanie modeli, reprezentacji bliźniaczych i relacji zbiorczo za pomocą interfejsu API importowania zadań.

Aby importować modele zbiorczo, należy utworzyć strukturę modeli (i innych zasobów uwzględnionych w zadaniu importu zbiorczego ) jako pliku NDJSON . Sekcja Models jest natychmiast po Header sekcji, co czyni ją pierwszą sekcją danych grafu w pliku. Przykładowy plik importu i przykładowy projekt służą do tworzenia tych plików w temacie Wprowadzenie do interfejsu API importu zadań.

Następnie należy przekazać plik do uzupełnialnych obiektów blob w usłudze Azure Blob Storage. Aby uzyskać instrukcje dotyczące tworzenia kontenera usługi Azure Storage, zobacz Tworzenie kontenera. Następnie przekaż plik przy użyciu preferowanej metody przekazywania (niektóre opcje to polecenie AzCopy, interfejs wiersza polecenia platformy Azure lub witryna Azure Portal).

Po przekazaniu pliku NDJSON do kontenera pobierz jego adres URL w kontenerze obiektów blob. Użyjesz tej wartości w dalszej części treści wywołania interfejsu API importu zbiorczego.

Oto zrzut ekranu przedstawiający wartość adresu URL pliku obiektu blob w witrynie Azure Portal:

Screenshot of the Azure portal showing the URL of a file in a storage container.

Następnie plik można użyć w wywołaniu interfejsu API importu zadań. Podasz adres URL magazynu obiektów blob pliku wejściowego, a także nowy adres URL magazynu obiektów blob, aby wskazać, gdzie ma być przechowywany dziennik wyjściowy podczas jego tworzenia przez usługę.

Pobieranie modeli

Możesz wyświetlić listę i pobrać modele przechowywane w wystąpieniu usługi Azure Digital Twins.

Dostępne są następujące opcje:

  • Pobieranie pojedynczego modelu
  • Pobieranie wszystkich modeli
  • Pobieranie metadanych i zależności dla modeli

Oto kilka przykładowych wywołań:

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

Zestaw SDK wywołuje metodę pobierania modeli wszystkich obiektów zwracanych DigitalTwinsModelData . DigitalTwinsModelData Zawiera metadane dotyczące modelu przechowywanego w wystąpieniu usługi Azure Digital Twins, takie jak nazwa, dtMI i data utworzenia modelu. Obiekt DigitalTwinsModelData również opcjonalnie zawiera sam model. Oznacza to, że w zależności od parametrów można użyć wywołań pobierania, aby pobrać tylko metadane (co jest przydatne w scenariuszach, w których chcesz wyświetlić listę dostępnych narzędzi, na przykład) lub cały model.

Wywołanie RetrieveModelWithDependencies zwraca nie tylko żądany model, ale także wszystkie modele, od których zależy żądany model.

Modele nie muszą być zwracane w dokładnie postaci dokumentu, w której zostały przekazane. Usługa Azure Digital Twins gwarantuje tylko, że formularz powrotu będzie semantycznie równoważny.

Aktualizowanie modeli

W tej sekcji opisano zagadnienia i strategie aktualizowania modeli.

Przed aktualizacją: pomyśl w kontekście całego rozwiązania

Przed wprowadzeniem aktualizacji modeli zaleca się całościowe przemyślenie całego rozwiązania i wpływu zmian modelu, które wkrótce wprowadzisz. Modele w rozwiązaniu usługi Azure Digital Twins są często połączone, dlatego ważne jest, aby pamiętać o kaskadowych zmianach, w których aktualizacja jednego modelu wymaga zaktualizowania kilku innych. Aktualizowanie modeli będzie miało wpływ na bliźniacze reprezentacje korzystające z modeli, a także może mieć wpływ na ruch przychodzący i przetwarzanie kodu, aplikacji klienckich i zautomatyzowanych raportów.

Poniżej przedstawiono kilka zaleceń, które ułatwiają bezproblemowe zarządzanie przejściami modelu:

  • Zamiast myśleć o modelach jako oddzielne jednostki, rozważ zmianę całego zestawu modeli, jeśli jest to konieczne, aby zachować aktualność modeli i ich relacji razem.
  • Traktuj modele, takie jak kod źródłowy i zarządzaj nimi w kontroli źródła. Zastosuj tę samą rigor i uwagę na modele i zmiany modelu, które mają zastosowanie do innego kodu w rozwiązaniu.

Gdy wszystko będzie gotowe do kontynuowania procesu aktualizowania modeli, w pozostałej części tej sekcji opisano strategie, których można użyć do zaimplementowania aktualizacji.

Strategie aktualizowania modeli

Po przekazaniu modelu do wystąpienia usługi Azure Digital Twins interfejs modelu jest niezmienny, co oznacza, że nie ma tradycyjnej "edycji" modeli. Usługa Azure Digital Twins również nie zezwala na ponowne ładowanie tego samego dokładnego modelu, gdy pasujący model jest już obecny w wystąpieniu.

Zamiast tego, jeśli chcesz wprowadzić zmiany w modelu , takie jak aktualizowanie displayName lub descriptiondodawanie i usuwanie właściwości, musisz zastąpić oryginalny model.

Podczas zastępowania modelu należy wybrać dwie strategie:

  • Strategia 1: Przekaż nową wersję modelu: przekaż model z nowym numerem wersji i zaktualizuj bliźniacze reprezentacje, aby korzystały z tego nowego modelu. Zarówno nowe, jak i stare wersje modelu będą istnieć w twoim wystąpieniu do momentu ich usunięcia.
    • Użyj tej strategii, jeśli chcesz zaktualizować tylko niektóre reprezentacje bliźniacze korzystające z modelu lub upewnić się, że bliźniacze reprezentacje pozostają zgodne z ich modelami i zapisywalne za pośrednictwem przejścia modelu.
  • Strategia 2. Usuwanie starego modelu i ponowne ładowanie: Usuń oryginalny model i przekaż nowy model o tej samej nazwie i identyfikatorze (wartość DTMI) w swoim miejscu. Całkowicie zastępuje stary model nowym.
    • Użyj tej strategii, jeśli chcesz zaktualizować wszystkie bliźniacze reprezentacje, które używają tego modelu jednocześnie, oprócz całego kodu reagującego na modele. Jeśli aktualizacja modelu zawiera zmianę powodującą niezgodność z aktualizacją modelu, bliźniacze reprezentacje będą niekonformantowane z ich modelami przez krótki czas podczas przechodzenia ich ze starego modelu do nowego, co oznacza, że nie będą mogły pobrać żadnych aktualizacji, dopóki nowy model nie zostanie przekazany, a reprezentacje bliźniacze będą zgodne z nim.

Uwaga

Wprowadzanie zmian powodujących niezgodność w modelach jest zniechęcane poza programowaniem.

Przejdź do następnych sekcji, aby dowiedzieć się więcej na temat każdej opcji strategii szczegółowo.

Strategia 1. Przekazywanie nowej wersji modelu

Ta opcja obejmuje utworzenie nowej wersji modelu i przekazanie jej do wystąpienia.

Ta operacja nie zastępuje wcześniejszych wersji modelu, więc wiele wersji modelu będzie współistnieć w twoim wystąpieniu do momentu ich usunięcia. Ponieważ nowa wersja modelu i stara wersja modelu współistnieją, bliźniacze reprezentacje mogą używać nowej wersji modelu lub starszej wersji, co oznacza, że przekazywanie nowej wersji modelu nie wpływa automatycznie na istniejące reprezentacje bliźniacze. Istniejące reprezentacje bliźniacze pozostaną wystąpieniami starej wersji modelu i można zaktualizować te reprezentacje bliźniacze do nowej wersji modelu, stosując ich poprawki.

Aby użyć tej strategii, wykonaj poniższe kroki.

1. Tworzenie i przekazywanie nowej wersji modelu

Aby utworzyć nową wersję istniejącego modelu, zacznij od języka DTDL oryginalnego modelu. Zaktualizuj, dodaj lub usuń pola, które chcesz zmienić.

Następnie oznacz ten model jako nowszą wersję modelu, aktualizując id pole modelu. Ostatnia sekcja identyfikatora modelu po ;, reprezentuje numer modelu. Aby wskazać, że ten model jest teraz bardziej zaktualizowaną wersją, zwiększ liczbę na końcu id wartości do dowolnej liczby większej niż numer bieżącej wersji.

Jeśli na przykład poprzedni identyfikator modelu wyglądał następująco:

"@id": "dtmi:com:contoso:PatientRoom;1",

Wersja 2 tego modelu może wyglądać następująco:

"@id": "dtmi:com:contoso:PatientRoom;2",

Następnie przekaż nową wersję modelu do wystąpienia.

Ta wersja modelu będzie następnie dostępna w twoim wystąpieniu do użycia w przypadku cyfrowych reprezentacji bliźniaczych. Nie zastępuje wcześniejszych wersji modelu, więc wiele wersji modelu jest teraz współistnienych w twoim wystąpieniu.

2. Zaktualizuj elementy grafu zgodnie z potrzebami

Następnie zaktualizuj reprezentacje bliźniacze i relacje w twoim wystąpieniu, aby zamiast starej wersji modelu używać nowej wersji modelu.

Poniższe instrukcje umożliwiają aktualizowanie bliźniaczych reprezentacji bliźniaczych i aktualizowanie relacji. Operacja stosowania poprawek w celu zaktualizowania modelu bliźniaczej reprezentacji będzie wyglądać mniej więcej tak:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

Ważne

Podczas aktualizowania bliźniaczych reprezentacji bliźniaczych użyj tej samej poprawki, aby zaktualizować zarówno identyfikator modelu (do nowej wersji modelu), jak i wszystkie pola, które muszą zostać zmienione na bliźniaczej reprezentacji, aby były zgodne z nowym modelem.

Może być również konieczne zaktualizowanie relacji i innych modeli w wystąpieniu odwołujących się do tego modelu, aby odwoływać się do nowej wersji modelu. Aby osiągnąć ten cel, należy wykonać inną operację aktualizacji modelu, dlatego wróć do początku tej sekcji i powtórz proces dla kolejnych modeli, które wymagają aktualizacji.

3. (Opcjonalnie) Likwiduj lub usuń starą wersję modelu

Jeśli nie będziesz już używać starej wersji modelu, możesz zlikwidować starszy model. Ta akcja umożliwia modelowi zachowanie istniejącej w wystąpieniu, ale nie można jej użyć do tworzenia nowych cyfrowych reprezentacji bliźniaczych.

Możesz również całkowicie usunąć stary model, jeśli nie chcesz go już w wystąpieniu.

Powyższe sekcje zawierają przykładowy kod i zagadnienia dotyczące likwidowania i usuwania modeli.

Strategia 2. Usuwanie starego modelu i ponowne ładowanie

Zamiast zwiększać wersję modelu, możesz całkowicie usunąć model i ponownie załadować edytowany model do wystąpienia.

Usługa Azure Digital Twins nie pamięta, że stary model został kiedykolwiek przekazany, więc ta akcja będzie wyglądać jak przekazanie zupełnie nowego modelu. Reprezentacje bliźniacze korzystające z modelu automatycznie przełączyć się na nową definicję po udostępnieniu. W zależności od tego, jak nowa definicja różni się od starej, te reprezentacje bliźniacze mogą mieć właściwości i relacje pasujące do usuniętej definicji i nie są prawidłowe z nową definicją, więc może być konieczne ich stosowanie poprawek, aby upewnić się, że pozostają prawidłowe.

Aby użyć tej strategii, wykonaj poniższe kroki.

1. Usuwanie starego modelu

Ponieważ usługa Azure Digital Twins nie zezwala na dwa modele o tym samym identyfikatorze, zacznij od usunięcia oryginalnego modelu z wystąpienia.

Uwaga

Jeśli masz inne modele, które zależą od tego modelu (za pośrednictwem dziedziczenia lub składników), musisz usunąć te odwołania przed usunięciem modelu. Te modele zależne można najpierw zaktualizować w celu tymczasowego usunięcia odwołań lub usunięcia modeli zależnych i ponownego załadowania ich w późniejszym kroku.

Skorzystaj z poniższych instrukcji, aby usunąć oryginalny model. Ta akcja spowoduje pozostawienie bliźniaczych reprezentacji, które używały tego modelu tymczasowo "oddzielone", ponieważ teraz używają modelu, który już nie istnieje. Ten stan zostanie naprawiony w następnym kroku po ponownym załadowaniu zaktualizowanego modelu.

2. Tworzenie i przekazywanie nowego modelu

Zacznij od języka DTDL oryginalnego modelu. Zaktualizuj, dodaj lub usuń pola, które chcesz zmienić.

Następnie przekaż model do wystąpienia, tak jakby był to nowy model przekazywany po raz pierwszy.

3. Zaktualizuj elementy grafu zgodnie z potrzebami

Teraz, gdy nowy model został przekazany zamiast starego, reprezentacje bliźniacze na grafie automatycznie zaczną używać nowej definicji modelu po wygaśnięciu i zresetowaniu buforowania w wystąpieniu. Ten proces może potrwać od 10 do 15 minut lub dłużej, w zależności od rozmiaru grafu. Następnie nowe i zmienione właściwości modelu powinny być dostępne, a usunięte właściwości nie będą już dostępne.

Uwaga

Jeśli wcześniej usunięto inne modele zależne w celu usunięcia oryginalnego modelu, załaduj je ponownie po zresetowaniu pamięci podręcznej. Jeśli zaktualizowano modele zależne w celu tymczasowego usunięcia odwołań do oryginalnego modelu, można je ponownie zaktualizować, aby przywrócić odwołanie.

Następnie zaktualizuj reprezentacje bliźniacze i relacje w wystąpieniu, aby ich właściwości odpowiadały właściwościom zdefiniowanym przez nowy model. Przed ukończeniem tego kroku bliźniacze reprezentacje bliźniacze, które nie pasują do ich modelu, nadal mogą być odczytywane, ale nie można ich zapisywać. Aby uzyskać więcej informacji na temat stanu bliźniaczych reprezentacji bez prawidłowego modelu, zobacz Bliźniacze reprezentacje bez modeli.

Istnieją dwa sposoby aktualizowania bliźniaczych reprezentacji bliźniaczych i relacji dla nowego modelu, aby można je było zapisywać ponownie:

  • Popraw reprezentacje bliźniacze i relacje zgodnie z potrzebami, aby pasowały do nowego modelu. Poniższe instrukcje umożliwiają aktualizowanie bliźniaczych reprezentacji bliźniaczych i aktualizowanie relacji.
    • Jeśli dodano właściwości: Aktualizowanie bliźniaczych reprezentacji bliźniaczych i relacji w celu utworzenia nowych wartości nie jest wymagane, ponieważ brak nowych wartości bliźniaczych będzie nadal prawidłowymi reprezentacjami bliźniaczymi. Można je zastosować, jednak chcesz dodać wartości dla nowych właściwości.
    • Jeśli usunięto właściwości: wymagane jest stosowanie poprawek bliźniaczych reprezentacji w celu usunięcia właściwości, które są teraz nieprawidłowe w nowym modelu.
    • Jeśli zaktualizowano właściwości: wymagane jest stosowanie poprawek bliźniaczych reprezentacji w celu zaktualizowania wartości zmienionych właściwości tak, aby były prawidłowe dla nowego modelu.
  • Usuń bliźniacze i relacje korzystające z modelu i utwórz je ponownie. Poniższe instrukcje umożliwiają usuwanie bliźniaczych reprezentacji bliźniaczych i ponowne tworzenie reprezentacji bliźniaczych oraz usuwanie relacji i ponowne tworzenie relacji.
    • Możesz wykonać tę operację, jeśli wprowadzasz wiele zmian w modelu i będzie trudno zaktualizować istniejące reprezentacje bliźniacze, aby je dopasować. Jednak rekreacja może być skomplikowana, jeśli masz wiele bliźniąt, które są połączone przez wiele relacji.

Usuwanie modeli

Modele można usunąć z usługi na jeden z dwóch sposobów:

  • Likwidowanie: po zlikwidowaniu modelu nie można go już używać do tworzenia nowych cyfrowych reprezentacji bliźniaczych. Nie ma to wpływu na istniejące cyfrowe reprezentacje bliźniacze, które już używają tego modelu, więc nadal można je aktualizować za pomocą takich elementów, jak zmiany właściwości i dodawanie lub usuwanie relacji.
  • Usunięcie: ta operacja całkowicie usunie model z rozwiązania. Wszystkie bliźniacze reprezentacje, które korzystały z tego modelu, nie są już skojarzone z żadnym prawidłowym modelem, więc są traktowane tak, jakby w ogóle nie miały modelu. Możesz nadal odczytywać te reprezentacje bliźniacze, ale nie możesz wprowadzać żadnych aktualizacji do momentu ponownego przypisania ich do innego modelu.

Te operacje są oddzielnymi funkcjami i nie wpływają na siebie, chociaż mogą być używane razem do stopniowego usuwania modelu.

Uwaga

Jeśli chcesz usunąć wszystkie modele, reprezentacje bliźniacze i relacje w wystąpieniu jednocześnie, użyj interfejsu API usuwania zadań.

Likwidacji

Aby zlikwidować model, możesz użyć metody DecommissionModel z zestawu SDK:

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

Możesz również zlikwidować model przy użyciu wywołania interfejsu API REST DigitalTwinModels Update. Właściwość decommissioned jest jedyną właściwością, którą można zastąpić tym wywołaniem interfejsu API. Dokument poprawki JSON będzie wyglądać mniej więcej tak:

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

Stan likwidowania modelu jest uwzględniany w ModelData rekordach zwracanych przez interfejsy API pobierania modelu.

Usunięcie

Możesz usunąć wszystkie modele w wystąpieniu jednocześnie lub wykonać je pojedynczo.

Aby zapoznać się z przykładem usuwania wszystkich modeli w tym samym czasie, zobacz kompleksowe przykłady dla repozytorium usługi Azure Digital Twins w usłudze GitHub. Plik CommandLoop.cs zawiera CommandDeleteAllModels funkcję z kodem umożliwiającym usunięcie wszystkich modeli w wystąpieniu.

Aby usunąć pojedynczy model, postępuj zgodnie z instrukcjami i zagadnieniami z pozostałej części tej sekcji.

Przed usunięciem: wymagania dotyczące usuwania

Ogólnie rzecz biorąc, modele można usuwać w dowolnym momencie.

Wyjątkiem są modele, od których zależą inne modele, z relacją extends lub jako składnikiem. Jeśli na przykład model ConferenceRoom rozszerza model Room i ma model ACUnit jako składnik, nie można usunąć pokoju ani modułu ACUnit, dopóki sala konferencyjna nie usunie odpowiednich odwołań.

Można to zrobić, aktualizując model zależny w celu usunięcia zależności lub całkowicie usuwając model zależny.

Podczas usuwania: proces usuwania

Nawet jeśli model spełnia wymagania dotyczące jego natychmiastowego usunięcia, możesz najpierw wykonać kilka kroków, aby uniknąć niezamierzonych konsekwencji dla bliźniaczych reprezentacji. Poniżej przedstawiono kilka kroków, które mogą ułatwić zarządzanie procesem:

  1. Najpierw zlikwiduj model
  2. Poczekaj kilka minut, aby upewnić się, że usługa przetworzyła wszystkie żądania utworzenia bliźniaczej reprezentacji ostatniej minuty wysłane przed likwidacją
  3. Wykonywanie zapytań o bliźniacze reprezentacje bliźniacze według modelu, aby wyświetlić wszystkie reprezentacje bliźniacze używające teraz zlikwidowanego modelu
  4. Usuń bliźniacze reprezentacje bliźniacze, jeśli nie są już potrzebne, lub w razie potrzeby popraw je do nowego modelu. Możesz również pozostawić je w spokoju, w tym przypadku staną się bliźniaczymi reprezentacjami bez modeli po usunięciu modelu. Zobacz następną sekcję, aby uzyskać implikacje tego stanu.
  5. Poczekaj kolejne kilka minut, aby upewnić się, że zmiany zostały przesłonięte
  6. Usuwanie modelu

Aby usunąć model, możesz użyć wywołania zestawu SDK DeleteModel :

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

Możesz również usunąć model za pomocą wywołania interfejsu API REST DigitalTwinModels Delete .

Po usunięciu: Bliźniacze reprezentacje bez modeli

Po usunięciu modelu wszystkie cyfrowe reprezentacje bliźniacze, które korzystały z modelu, są teraz uważane za bez modelu. Nie ma zapytania, które może dać listę wszystkich bliźniaczych reprezentacji w tym stanie — chociaż nadal można wykonywać zapytania dotyczące bliźniaczych reprezentacji przez usunięty model, aby wiedzieć, na jakie reprezentacje bliźniacze mają wpływ.

Oto omówienie tego, co można zrobić i nie można zrobić z bliźniaczymi reprezentacjami, które nie mają modelu.

Czynności, które można wykonać:

  • Wykonywanie zapytań względem bliźniaczej reprezentacji
  • Odczytywanie właściwości
  • Odczytywanie relacji wychodzących
  • Dodawanie i usuwanie relacji przychodzących (podobnie jak w przypadku innych reprezentacji bliźniaczych nadal mogą tworzyć relacje z tą reprezentacją bliźniaczą)
    • Definicja target w relacji nadal może odzwierciedlać jednostki DTMI usuniętego modelu. Relacja bez zdefiniowanego obiektu docelowego może również działać tutaj.
  • Usuń relacje
  • Usuwanie bliźniaczej reprezentacji

Nie można wykonywać następujących czynności:

  • Edytuj relacje wychodzące (podobnie jak w przypadku relacji z tej reprezentacji bliźniaczej do innych reprezentacji bliźniaczych)
  • Edytuj właściwości

Po usunięciu: ponowne ładowanie modelu

Po usunięciu modelu możesz zdecydować się później na przekazanie nowego modelu o tym samym identyfikatorze, który został usunięty. Oto, co się dzieje w tym przypadku.

  • Z perspektywy magazynu rozwiązań ta operacja jest taka sama jak przekazywanie całkowicie nowego modelu. Usługa nie pamięta, że stary został kiedykolwiek przekazany.
  • Jeśli na grafie istnieją pozostałe bliźniacze reprezentacje odwołujące się do usuniętego modelu, nie są już oddzielone; ten identyfikator modelu jest prawidłowy ponownie przy użyciu nowej definicji. Jeśli jednak nowa definicja modelu różni się od definicji modelu, która została usunięta, te reprezentacje bliźniacze mogą mieć właściwości i relacje zgodne z usuniętą definicją i nie są prawidłowe w przypadku nowej.

Usługa Azure Digital Twins nie uniemożliwia tego stanu, dlatego należy zachować ostrożność, aby odpowiednio zastosować poprawki bliźniaczych reprezentacji, aby upewnić się, że pozostają prawidłowe za pomocą przełącznika definicji modelu.

Konwertowanie modeli w wersji 2 na 3

Usługa Azure Digital Twins obsługuje języki DTDL w wersji 2 i 3 (odpowiednio skrócone w dokumentacji do wersji 2 i 3). Wersja 3 jest zalecanym wyborem na podstawie rozszerzonych możliwości. W tej sekcji wyjaśniono, jak zaktualizować istniejący model DTDL w wersji 2 do języka DTDL w wersji 3.

  1. Zaktualizuj kontekst. Główną funkcją identyfikującą model w wersji 2 lub 3 jest @context pole w interfejsie. Aby przekonwertować model z wersji 2 na 3, zmień dtmi:dtdl:context;2 wartość kontekstu na dtmi:dtdl:context;3. W przypadku wielu modeli będzie to jedyna wymagana zmiana.
    1. Wartość w wersji 2: "@context": "dtmi:dtdl:context;2"
    2. Wartość w wersji 3: "@context": "dtmi:dtdl:context;3".
  2. W razie potrzeby zaktualizuj typy semantyczne. W kodzie DTDL w wersji 2 typy semantyczne są natywnie obsługiwane. W języku DTDL w wersji 3 są one dołączone do rozszerzenia funkcji QuantitativeTypes. Dlatego jeśli model w wersji 2 używał typów semantycznych, należy dodać rozszerzenie funkcji podczas konwertowania modelu na 3. W tym celu najpierw zmień @context pole w interfejsie z jednej wartości na tablicę wartości, a następnie dodaj wartość dtmi:dtdl:extension:quantitativeTypes;1.
    1. Wartość w wersji 2: "@context": "dtmi:dtdl:context;2"
    2. Wartość w wersji 3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
  3. W razie potrzeby rozważ limity rozmiaru. W wersji 2 i 3 istnieją różne limity rozmiaru, więc jeśli interfejs jest bardzo duży, warto przejrzeć limity różnic między językiem DTDL w wersji 2 i 3.

Po tych zmianach poprzedni model DTDL w wersji 2 został przekonwertowany na model DTDL w wersji 3.

Warto również rozważyć nowe możliwości języka DTDL w wersji 3, takie jak właściwości typu tablicy, relaks wersji i dodatkowe rozszerzenia funkcji, aby sprawdzić, czy którykolwiek z nich byłby korzystnym dodatkiem. Aby uzyskać pełną listę różnic między językiem DTDL w wersji 2 i 3, zobacz Zmiany z wersji 2 w opisie języka DTDL w wersji 3.

Następne kroki

Zobacz, jak tworzyć cyfrowe reprezentacje bliźniacze i zarządzać nimi na podstawie modeli: