Zarządzanie modelami usługi Azure Digital Twins

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, potrzebujesz instancji usługi Azure Digital Twins i wymaganych uprawnień do korzystania z niej. 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 dla języków 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:

• Eksplorator usługi Azure Digital Twins
• Wywołania interfejsu API REST
• Polecenia interfejsu wiersza polecenia platformy Azure

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:

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"
      }
    ]
  }

Model ten definiuje nazwę i unikatowy identyfikator pokoju pacjenta oraz właściwości reprezentujące liczbę odwiedzających i stan higieny rąk. Te liczniki są aktualizowane za pomocą czujników ruchu i inteligentnych dozowników mydła, i razem używane do obliczania handwash percentage właściwości. Model definiuje również związek hasDevices, który jest używany do łączenia dowolnych cyfrowych bliźniaków opartych na tym modelu Pomieszczenia z rzeczywistymi urządzeniami.

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 ontologie branżowe.

Użyj istniejących ontologii 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 Twoje rozwiązanie dotyczy określonej branży, która korzysta z dowolnego standardu modelowania, rozważ rozpoczęcie od istniejącego zestawu modeli zaprojektowanych dla twojej branży zamiast projektowania modeli od podstaw. Firma Microsoft nawiązała współpracę z ekspertami z dziedziny, aby tworzyć ontologie modeli DTDL oparte na standardach branżowych, pomagając zminimalizować powielanie oraz zachęcić do spójności i prostoty rozwiązań branżowych. Możesz dowiedzieć się więcej na temat tych ontologii, w tym jak ich używać i jakie ontologie są teraz dostępne, w temacie Co to jest ontologia?.

Weryfikowanie składni

Po utworzeniu modelu zalecamy 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.

Wczytaj modele

Po utworzeniu modeli można je przeładować do wystąpienia Azure Digital Twins.

Gdy jesteś gotowy do przesłania modelu, możesz użyć następującego fragmentu kodu dla pakietu .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 });

Po przekazaniu usługa weryfikuje pliki modelu.

Zazwyczaj musisz wgrać 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.

Wysyłanie 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, które można przesłać w pojedynczym wywołaniu interfejsu API, można sprawdzić w sekcji limity usługi Azure Digital Twins.

Jeśli używasz zestawu SDK, możesz przekazać wiele plików modelu za pomocą metody CreateModels 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 Azure CLI, możesz przesłać wiele modeli, umieszczając wiele definicji modeli w jednym pliku JSON do wspólnego przesłania. 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 Import Jobs

W przypadku dużych zestawów modeli można użyć interfejsu API Import Jobs, 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 i uprawnień do zapisu w wystąpieniu usługi Azure Digital Twins dla modeli i zadań zbiorczych.

Aby importować modele zbiorczo, należy ustrukturyzować modele (i inne zasoby uwzględnione w zadaniu importu zbiorczego) jako plik NDJSON. Sekcja Models jest natychmiast po Header sekcji, co czyni ją pierwszą sekcją danych grafu w pliku. Możesz zobaczyć przykładowy plik importu i przykładowy projekt we wprowadzeniu do interfejsu API importu zadań.

Następnie należy przekazać plik do obiektów blob typu append 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 blob. Używasz tej wartości później w treści wywołania interfejsu API importu zbiorczego.

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

Następnie plik można użyć w wywołaniu interfejsu API importu zadań. Podaj adres URL magazynu obiektów blob pliku wejściowego i nowy adres URL magazynu obiektów blob, aby wskazać, gdzie chcesz, aby usługa utworzyła i przechowywała dziennik danych wyjściowych.

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 });

SDK wykonuje wywołania, które zwracają obiekty DigitalTwinsModelData podczas pobierania modeli. 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.

Innymi słowy, można użyć wywołań zestawu SDK, aby pobrać tylko metadane dla modelu lub całego modelu, w zależności od określonych parametrów. Pobieranie tylko metadanych jest przydatne w scenariuszach, w których chcesz na przykład wyświetlić listę dostępnych narzędzi interfejsu użytkownika.

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ładnej postaci dokumentu, w której zostały przesłane. Usługa Azure Digital Twins gwarantuje tylko, że zwrotny formularz jest 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 zalecamy, aby całościowo myśleć o całym rozwiązaniu i wpływie 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 wpływa na bliźniaki, które korzystają z modeli, a także może mieć wpływ na ingres, kod przetwarzający, aplikacje klienckie i zautomatyzowane raporty.

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 ten sam rygor i uwagę do modeli i ich zmian, które stosujesz do kodu w swoim 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: Załaduj nową wersję modelu: załaduj model z nowym numerem wersji i zaktualizuj bliźniaki, aby korzystały z tego nowego modelu. Zarówno nowe, jak i stare wersje modelu istnieją w twojej instancji do momentu usunięcia jednej z nich.
  • Użyj tej strategii, jeśli chcesz zaktualizować tylko niektóre ze swoich cyfrowych bliźniaków korzystających z modelu, lub jeśli chcesz upewnić się, że cyfrowe bliźniaki pozostają zgodne z ich modelami i mogą być zapisywane podczas przejścia modelu.
• Strategia 2. Usuń stary model i wgraj ponownie: Usuń oryginalny model i przekaż nowy model o tej samej nazwie i identyfikatorze (wartość DTMI) na jego miejsce. Całkowicie zastępuje stary model nowym.
  • Użyj tej strategii, gdy chcesz zaktualizować wszystkie bliźniaki używające tego modelu jednocześnie z całym kodem reagującym na modele. Jeśli aktualizacja modelu zawiera zmianę powodującą niezgodność z aktualizacją modelu, bliźniacze reprezentacje są niezgodne z ich modelami przez krótki czas, gdy przenosisz je ze starego modelu do nowego, co oznacza, że nie są w stanie pobrać żadnych aktualizacji do momentu przekazania nowego modelu, a reprezentacje bliźniacze są zgodne z nim.

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 przesłanie jej do instancji.

Ta operacja nie zastępuje wcześniejszych wersji modelu, dlatego wiele wersji modelu współistnieje 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 pozostają 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 następujące 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 na swoją instancję.

Ta wersja modelu jest następnie dostępna w twoim wystąpieniu do użycia dla cyfrowych bliźniaków. Nie zastępuje wcześniejszych wersji modelu, więc wiele wersji modelu teraz współistnieje w Twojej instancji.

2. Zaktualizuj elementy grafu zgodnie z potrzebami

Następnie zaktualizuj bliźniaki i relacje w twojej instancji, aby zamiast starej wersji modelu używać nowej.

Możesz użyć poniższych instrukcji do aktualizowania bliźniaków oraz aktualizowania relacji. Operacja stosowania poprawek w celu zaktualizowania modelu bliźniaczej reprezentacji wygląda następująco:

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

Może być również konieczne zaktualizowanie relacji i innych modeli w Twojej instancji odwołujących się do tego modelu, aby odwoływały 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 należy zaktualizować.

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

Jeśli nie używasz już starej wersji modelu, możesz zlikwidować starszy model. Ta akcja pozwala modelowi nadal istnieć w instancji, ale nie można go używać do tworzenia nowych cyfrowych bliźniaków.

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

Poprzednie połączone 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 przypomina przekazanie zupełnie nowego modelu. Bliźniacze jednostki korzystające z modelu automatycznie przełączają się na nową definicję, gdy jest dostępna. 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 zgodne z usuniętą definicją i nie są prawidłowe dla nowej. W przypadku wystąpienia tej różnicy może być konieczne wprowadzenie poprawek, aby upewnić się, że pozostają prawidłowe.

Aby użyć tej strategii, wykonaj następujące 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.

Skorzystaj z poniższych instrukcji, aby usunąć oryginalny model. Ta akcja pozostawia bliźniaki, które używały tego modelu, tymczasowo osierocone, ponieważ obecnie używają modelu, który już nie istnieje. Ten stan jest naprawiany w następnym kroku podczas ponownego ładowania zaktualizowanego modelu.

2. Tworzenie i przekazywanie nowego modelu

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

Następnie przekaż model do wystąpienia, jakbyś przekazywał nowy model po raz pierwszy.

3. Zaktualizuj elementy grafu zgodnie z potrzebami

Teraz, gdy nowy model zostanie 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 są już dostępne.

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

Istnieją dwa sposoby aktualizowania bliźniaków i relacji w nowym modelu, aby można je było ponownie edytować:

• Dostosuj bliźniaki i relacje zgodnie z potrzebami, aby pasowały do nowego modelu. Możesz użyć poniższych instrukcji do aktualizowania bliźniaków i aktualizowania relacji.
  • Jeśli dodano właściwości: Aktualizowanie bliźniaków i relacji, aby mieć nowe wartości, nie jest wymagane, ponieważ bliźniaki, którym brakuje nowych wartości, są nadal prawidłowe. Możesz je modyfikować w dowolny sposób, aby dodać wartości dla nowych właściwości.
  • Jeśli usunięto właściwości: należy dostosować bliźniacze modele, aby usunąć właściwości, które są teraz nieprawidłowe w nowym modelu.
  • Jeśli zaktualizowano właściwości: należy zastosować poprawki w cyfrowych bliźniakach, aby zaktualizować wartości zmienionych właściwości, aby były prawidłowe dla nowego modelu.
• Usuń bliźniacze i relacje korzystające z modelu i utwórz je ponownie. Możesz użyć poniższych instrukcji do usuwania bliźniaków i ponownego tworzenia bliźniaków oraz usuwania relacji i ponownego tworzenia relacji.
  • Możesz wykonać tę operację, jeśli wprowadzasz wiele zmian w modelu i trudno jest zaktualizować istniejące reprezentacje bliźniacze, aby je dopasować. Jednak rekreacja może być skomplikowana, jeśli masz wiele bliźniąt połączonych przez wiele relacji.

Usuwanie modeli

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

• Po zlikwidowaniu modelu nie można go już używać do tworzenia nowych cyfrowych bliźniaków. 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 usuwa model z rozwiązania. Wszystkie bliźniaki, które korzystały z tego modelu, nie są już skojarzone z żadnym prawidłowym modelem, więc są traktowane tak, jakby nie miały modelu wcale. Możesz nadal odczytywać te bliźniaki, ale nie możesz wprowadzać żadnych aktualizacji do momentu przypisania ich do nowego modelu.

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

Wycofanie z eksploatacji

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 wygląda mniej więcej tak:

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

Status likwidacji modelu jest uwzględniany w ModelData rekordach zwracanych przez API do 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, poprzez relację extends lub jako komponent. Jeśli na przykład model ConferenceRoom rozszerza model Room i ma model ACUnit jako składnik, nie można usunąć Room ani modelu ACUnit, dopóki ConferenceRoom nie usunie odpowiednich referencji.

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, warto najpierw wykonać kilka kroków, aby uniknąć niezamierzonych konsekwencji dla bliźniaków. Poniżej przedstawiono kilka kroków, które mogą ułatwić zarządzanie procesem:

1. Najpierw zlikwiduj model
2. Aby upewnić się, że usługa przetwarza wszystkie ostatnio złożone żądania twina wysłane przed likwidacją, poczekaj kilka minut.
3. Zadać pytanie o bliźniacze reprezentacje według modelu, aby wyświetlić wszystkie te, które korzystają z obecnie zlikwidowanego modelu.
4. Usuń duplikaty, jeśli nie są już potrzebne, lub w razie potrzeby dostosuj je do nowego modelu. Możesz również je zostawić w spokoju, i w takim przypadku stają się bliźniakami bez modeli po usunięciu modelu. Zobacz następną sekcję, aby uzyskać implikacje tego stanu.
5. Poczekaj jeszcze kilka minut, aby upewnić się, że zmiany przenikną przez.
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źniaki bez modeli

Po usunięciu modelu wszystkie cyfrowe bliźniaki, które korzystały z modelu, są teraz traktowane jako pozbawione modelu. Nie ma zapytania, które może dać listę wszystkich bliźniaków w tym stanie — choć nadal można wykonywać zapytania dotyczące bliźniaków za pomocą usuniętego modelu, aby wiedzieć, na które ma to wpływ.

Oto omówienie tego, co można, a czego nie można zrobić z bliźniakami, które nie mają modelu.

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

• Zapytaj bliźniaka
• Odczytywanie właściwości
• Odczytywanie relacji wychodzących
• Dodawanie i usuwanie relacji przychodzących od innych bliźniaków (inny bliźniak nadal może tworzyć relacje z tym bliźniakiem)
  • Definicja relacji w target nadal może odzwierciedlać DTMI usuniętego modelu. Relacja bez zdefiniowanego obiektu docelowego może również działać tutaj.
• Usuń relacje
• Usuń bliźniaka

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

• Edytuj relacje wychodzące (czyli relacje tego bliźniaka z innymi bliźniakami)
• Edytuj właściwości

Po usunięciu: ponowne ładowanie modelu

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

• Z perspektywy repozytorium rozwiązań ta operacja jest taka sama jak wgrywanie całkowicie nowego modelu. Usługa nie pamięta, że stary plik był kiedykolwiek przesłany.
• Jeśli w grafie istnieją pozostałe bliźniaki odwołujące się do usuniętego modelu, nie są już osierocone; ten identyfikator modelu jest ponownie prawidłowy dzięki nowej definicji. Jeśli jednak nowa definicja modelu jest inna niż definicja 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 z nową.

Usługa Azure Digital Twins nie uniemożliwia tego stanu, dlatego należy zachować ostrożność, aby odpowiednio zastosować poprawki w Azure Digital Twins, aby upewnić się, że pozostają prawidłowe podczas zmiany 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 ta zmiana jest jedyną wymaganą.
   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. Aby dodać rozszerzenie funkcji, 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 trzeciej wersji: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
3. W razie potrzeby rozważ limity rozmiaru. W wersjach v2 i v3 obowiązują różne limity rozmiaru, więc jeśli Twój interfejs jest duży, warto przejrzeć limity przedstawione w sekcji różnice między DTDL v2 a v3.

Po tych zmianach były model DTDL w wersji 2 jest konwertowany 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 inne 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ć i zarządzać cyfrowymi bliźniakami na podstawie swoich modeli:

• Zarządzanie cyfrowymi bliźniakami