Sdílet prostřednictvím

Správa modelů Azure Digital Twins

  • Článek

Tento článek popisuje, jak spravovat modely v instanci služby Azure Digital Twins. Mezi operace správy patří nahrávání, ověřování, načítání a odstraňování modelů.

Požadavky

Pokud chcete pracovat se službou Azure Digital Twins v tomto článku, budete potřebovat instanci služby Azure Digital Twins a požadovaná oprávnění k jeho použití. Pokud už máte nastavenou instanci Služby Azure Digital Twins, můžete tuto instanci použít a přeskočit k další části. V opačném případě postupujte podle pokynů v části Nastavení instance a ověřování. Pokyny obsahují informace, které vám pomůžou ověřit, že jste každý krok úspěšně dokončili.

Po nastavení instance si poznamenejte název hostitele instance. Název hostitele najdete na webu Azure Portal.

Vývojářská rozhraní

Tento článek popisuje, jak provádět různé operace správy pomocí sady .NET (C#) SDK. Stejná volání správy můžete také vytvořit pomocí jiných jazykových sad SDK popsaných v rozhraních API a sadách SDK služby Azure Digital Twins.

Mezi další vývojářská rozhraní, která lze použít k dokončení těchto operací, patří:

Poznámka:

Azure Digital Twins Explorer v současné době plně podporuje modely DTDL v2 a podporuje omezené funkce pro modely DTDL v3.

Modely DTDL v3 lze zobrazit na panelu Modely a dvojčata vytvořená pomocí modelů DTDL v3 je možné zobrazit a upravit (včetně modelů s vlastnostmi pole). Modely DTDL v3 se ale nezobrazí na panelu Graf modelů a nedají se importovat pomocí Průzkumníka služby Azure Digital Twins. K importu modelů DTDL v3 do vaší instance použijte jiné vývojářské rozhraní, jako jsou rozhraní API a sady SDK nebo Azure CLI.

Vizualizace

Azure Digital Twins Explorer je vizuální nástroj pro zkoumání dat v grafu Služby Azure Digital Twins. Průzkumníka můžete použít k zobrazení, dotazování a úpravám modelů, dvojčat a relací.

Další informace o nástroji Azure Digital Twins Explorer najdete v Průzkumníku služby Azure Digital Twins. Podrobný postup použití jeho funkcí najdete v tématu Použití Průzkumníka služby Azure Digital Twins.

Vizualizace vypadá takto:

Snímek obrazovky s Průzkumníkem služby Azure Digital Twins zobrazující ukázkový graf modelu

Vytváření modelů

Můžete vytvořit vlastní modely od začátku nebo použít existující ontologie, které jsou dostupné pro vaše odvětví.

Vytváření modelů

Modely pro Azure Digital Twins jsou napsané v DTDL a ukládají se jako soubory JSON. Pro Visual Studio Code je k dispozici také rozšíření DTDL, které poskytuje ověřování syntaxe a další funkce, které usnadňují psaní dokumentů DTDL.

Představte si příklad, ve kterém nemocnice chce digitálně reprezentovat své místnosti. Každá místnost obsahuje inteligentní dávkovač mýdla pro monitorování ručního praní a senzorů pro monitorování provozu přes místnost.

Prvním krokem k řešení je vytvoření modelů představujících aspekty nemocnice. Pacientská místnost v tomto scénáři může být popsaná takto:

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

Poznámka:

Toto je vzorové tělo pro soubor JSON, ve kterém je model definovaný a uložený, který se má nahrát jako součást klientského projektu. Volání rozhraní REST API na druhou stranu přebírá pole definic modelů, jako je ta výše (která je namapovaná na sadu IEnumerable<string> .NET SDK). Pokud tedy chcete tento model použít přímo v rozhraní REST API, obklopte ho hranatými závorkami.

Tento model definuje název a jedinečné ID pro místnost pacienta a vlastnosti, které představují počet návštěvníků a stav ručního mytí. Tyto čítače budou aktualizovány ze snímačů pohybu a inteligentních dávkovačů mýdla a budou použity společně k výpočtu handwash percentage vlastnosti. Model také definuje relaci hasDevices, která se použije k propojení digitálních dvojčat založených na tomto modelu místnosti se skutečnými zařízeními.

Poznámka:

Služba Azure Digital Twins v současné době nepodporuje některé funkce DTDL, včetně atributu writable vlastností a relací a minMultiplicitymaxMultiplicity relací. Další informace najdete v poznámkách DTDL specifických pro službu.

Pomocí této metody můžete definovat modely pro nemocnice oddělení, zóny nebo samotnou nemocnici.

Pokud vaším cílem je vytvořit komplexní sadu modelů, která popisuje vaši oborovou doménu, zvažte, jestli existuje stávající oborová ontologie, kterou můžete použít k usnadnění vytváření modelů. Další část popisuje oborové ontologie podrobněji.

Použití stávajících standardních ontologií

Ontologie je sada modelů, které komplexně popisují danou doménu, jako je výroba, stavební struktury, systémy IoT, inteligentní města, energetické sítě, webový obsah a další.

Pokud je vaše řešení pro určité odvětví, které používá jakýkoli druh standardu modelování, zvažte, že začnete s předem existující sadou modelů navržených pro vaše odvětví, a nemusíte navrhovat modely úplně od začátku. Microsoft spolupracuje s odborníky na domény a vytvořil model DTDL založený na oborových standardech, aby pomohl minimalizovat nové vynalézavost a podpořit konzistenci a jednoduchost napříč oborovými řešeními. Další informace o těchto ontologiích, včetně toho, jak je používat a jaké ontologie jsou nyní k dispozici, si můžete přečíst v tématu Co je ontologie?.

Ověření syntaxe

Po vytvoření modelu se doporučuje před jejich nahráním do instance Služby Azure Digital Twins ověřit modely offline.

Pro účely ověření modelů se na NuGetu poskytuje knihovna analyzátoru DTDL na straně klienta .NET: DTDLParser. Knihovnu analyzátoru můžete použít přímo v kódu jazyka C#. Ukázkové použití analyzátoru můžete zobrazit také v souboru DTDLParserResolveSample na GitHubu.

Nahrání modelů

Po vytvoření modelů je můžete nahrát do instance Azure Digital Twins.

Až budete připraveni nahrát model, můžete pro sadu .NET SDK použít následující fragment kódu:

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

Při nahrání služba ověří soubory modelu.

Obvykle budete muset do služby nahrát více než jeden model. Existuje několik způsobů, jak v jedné transakci nahrát mnoho modelů najednou. Pokud chcete vybrat strategii, zvažte velikost sady modelů při pokračování ve zbývající části této části.

Nahrání malých sad modelů

U menších sad modelů můžete nahrát více modelů najednou pomocí jednotlivých volání rozhraní API. Aktuální limit počtu modelů můžete zkontrolovat v rámci jednoho volání rozhraní API v limitech služby Azure Digital Twins.

Pokud používáte sadu SDK, můžete pomocí CreateModels této metody nahrát několik souborů modelu:

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

Pokud používáte rozhraní REST API nebo Azure CLI, můžete nahrát několik modelů umístěním více definic modelů do jednoho souboru JSON, který se má nahrát dohromady. V tomto případě by se modely měly umístit do pole JSON v souboru, například v následujícím příkladu:

[
    {
      "@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"
    }
]

Nahrání velkých sad modelů pomocí rozhraní API pro import úloh

U velkých sad modelů můžete pomocí rozhraní API importu úloh nahrát mnoho modelů najednou v jednom volání rozhraní API. Rozhraní API může současně přijímat až limit služby Azure Digital Twins pro počet modelů v instanci a v případě potřeby automaticky změní pořadí modelů, aby bylo možné přeložit závislosti mezi nimi. Tato metoda vyžaduje použití služby Azure Blob Storage a také oprávnění k zápisu v instanci služby Azure Digital Twins pro modely a hromadné úlohy.

Tip

Rozhraní API pro úlohy importu také umožňuje importovat dvojčata a relace ve stejném volání, aby se vytvořily všechny části grafu najednou. Další informace o tomto procesu najdete v tématu Hromadné nahrávání modelů, dvojčat a relací pomocí rozhraní API importu úloh.

Pokud chcete modely importovat hromadně, budete muset modely strukturovat (a všechny další prostředky zahrnuté v úloze hromadného importu) jako soubor NDJSON . Oddíl Models je hned za Header oddílem, takže se jedná o první datový oddíl grafu v souboru. Ukázkový soubor importu a ukázkový projekt pro vytvoření těchto souborů si můžete prohlédnout v úvodu k rozhraní API importu úloh.

Dále je potřeba soubor nahrát do doplňovacího objektu blob ve službě Azure Blob Storage. Pokyny k vytvoření kontejneru úložiště Azure najdete v tématu Vytvoření kontejneru. Pak soubor nahrajte pomocí preferované metody nahrání (některé možnosti jsou příkaz AzCopy, Azure CLI nebo Azure Portal).

Jakmile se soubor NDJSON nahraje do kontejneru, získejte jeho adresu URL v kontejneru objektů blob. Tuto hodnotu použijete později v textu volání rozhraní API hromadného importu.

Tady je snímek obrazovky znázorňující hodnotu adresy URL souboru objektu blob na webu Azure Portal:

Snímek obrazovky webu Azure Portal zobrazující adresu URL souboru v kontejneru úložiště

Pak se soubor dá použít ve volání rozhraní API importu úloh. Zadáte adresu URL úložiště objektů blob vstupního souboru a také novou adresu URL úložiště objektů blob, která bude indikovat, kam se má výstupní protokol uložit, když služba vytvoří.

Načtení modelů

Můžete vypsat a načíst modely uložené v instanci služby Azure Digital Twins.

Mezi vaše možnosti patří:

  • Načtení jednoho modelu
  • Načtení všech modelů
  • Načtení metadat a závislostí pro modely

Tady je několik ukázkových volání:

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

Volání sady SDK pro načtení modelů všechny návratové DigitalTwinsModelData objekty. DigitalTwinsModelData obsahuje metadata o modelu uloženém v instanci Služby Azure Digital Twins, jako je název, DTMI a datum vytvoření modelu. Objekt DigitalTwinsModelData také volitelně zahrnuje samotný model. To znamená, že v závislosti na parametrech můžete pomocí volání načíst pouze metadata (což je užitečné ve scénářích, kdy chcete zobrazit seznam dostupných nástrojů, například uživatelského rozhraní), nebo celý model.

Volání RetrieveModelWithDependencies vrátí nejen požadovaný model, ale také všechny modely, na které požadovaný model závisí.

Modely nemusí být nutně vráceny přesně ve formuláři dokumentu, do které byly nahrány. Azure Digital Twins zaručuje, že návratový formulář bude sémanticky ekvivalentní.

Aktualizace modelů

Tato část popisuje aspekty a strategie aktualizace modelů.

Před aktualizací: Zamyslete se v kontextu celého řešení

Než začnete s modely aktualizovat, doporučujeme se zamyslet nad celým řešením a dopadem změn modelu, které se chystáte provést. Modely v řešení Azure Digital Twins jsou často vzájemně propojené, takže je důležité vědět o kaskádových změnách, kdy aktualizace jednoho modelu vyžaduje aktualizaci několika dalších. Aktualizace modelů ovlivní dvojčata, která modely používají, a mohou také ovlivnit příchozí přenos dat a zpracování kódu, klientských aplikací a automatizovaných sestav.

Tady je několik doporučení, která vám pomůžou hladce spravovat přechody modelu:

  • Místo myšlení modelů jako samostatných entit zvažte vývoj celé sady modelů, pokud je to vhodné, aby byly modely a jejich vztahy aktuální.
  • Nakládat s modely jako se zdrojovým kódem a spravovat je ve správě zdrojového kódu Použijte stejnou rigorii a pozornost na modely a změny modelu, které použijete u jiného kódu ve vašem řešení.

Až budete připraveni pokračovat v procesu aktualizace modelů, zbytek této části popisuje strategie, které můžete použít k implementaci aktualizací.

Strategie aktualizace modelů

Po nahrání modelu do instance Služby Azure Digital Twins je rozhraní modelu neměnné, což znamená, že neexistuje tradiční "úpravy" modelů. Azure Digital Twins také neumožňuje opětovné načtení stejného přesného modelu, zatímco v instanci už existuje odpovídající model.

Místo toho, pokud chcete v modelu udělat změny, jako je aktualizace displayName nebo descriptionnebo přidání a odebrání vlastností, budete muset nahradit původní model.

Při nahrazování modelu si můžete vybrat ze dvou strategií:

  • Strategie 1: Nahrání nové verze modelu: Nahrajte model s novým číslem verze a aktualizujte dvojčata tak, aby používala tento nový model. Nové i staré verze modelu budou existovat ve vaší instanci, dokud ho neodstraníte.
    • Tuto strategii použijte, když chcete aktualizovat pouze některá dvojčata, která model používají, nebo pokud chcete zajistit, aby dvojčata zůstala v souladu s jejich modely a zapisovatelná prostřednictvím přechodu modelu.
  • Strategie 2: Odstraňte starý model a znovu načtěte: Odstraňte původní model a nahrajte nový model se stejným názvem a ID (hodnota DTMI) na svém místě. Úplně nahradí starý model novým modelem.
    • Tuto strategii použijte, pokud chcete aktualizovat všechna dvojčata, která tento model používají najednou, a navíc ke všemu kódu, který na modely reaguje. Pokud vaše aktualizace modelu obsahuje zásadní změnu v aktualizaci modelu, dvojčata nebudou s jejich modely po krátkou dobu v době, kdy je přecházíte ze starého modelu na nový, což znamená, že nebudou moct provádět žádné aktualizace, dokud se nový model nenahraje a dvojčata budou odpovídat.

Poznámka:

Provádění zásadníchzměnch

Pokračujte k dalším oddílům a podrobně si přečtěte o jednotlivých možnostech strategie.

Strategie 1: Nahrání nové verze modelu

Tato možnost zahrnuje vytvoření nové verze modelu a její nahrání do vaší instance.

Tato operace nepřepíše starší verze modelu, takže v instanci bude existovat více verzí modelu, dokud je neodeberete. Vzhledem k tomu, že nová verze modelu a stará verze modelu existují společně, můžou dvojčata používat buď novou verzi modelu, nebo starší verzi, což znamená, že nahrání nové verze modelu automaticky neovlivní stávající dvojčata. Stávající dvojčata zůstanou jako instance staré verze modelu a můžete je aktualizovat na novou verzi modelu tím, že je opravíte.

Pokud chcete tuto strategii použít, postupujte podle následujících kroků.

1. Vytvoření a nahrání nové verze modelu

Pokud chcete vytvořit novou verzi existujícího modelu, začněte s DTDL původního modelu. Aktualizujte, přidejte nebo odeberte pole, která chcete změnit.

V dalším kroku označte tento model jako novější verzi modelu aktualizací id pole modelu. Poslední část ID modelu za číslem ;modelu představuje číslo modelu. Chcete-li označit, že tento model je nyní aktualizovanou verzí, zvýší číslo na konci id hodnoty na libovolné číslo větší než číslo aktuální verze.

Pokud například id předchozího modelu vypadalo takto:

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

Verze 2 tohoto modelu může vypadat takto:

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

Pak nahrajte novou verzi modelu do vaší instance.

Tato verze modelu bude pak dostupná ve vaší instanci pro použití pro digitální dvojčata. Nepřepíše starší verze modelu, takže ve vaší instanci teď existuje více verzí modelu.

2. Podle potřeby aktualizujte prvky grafu.

V dalším kroku aktualizujte dvojčata a relace ve vaší instanci tak, aby používaly novou verzi modelu místo staré verze.

K aktualizaci dvojčat a relací aktualizací můžete použít následující pokyny. Operace opravy pro aktualizaci modelu dvojčete bude vypadat přibližně takto:

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

Důležité

Při aktualizaci dvojčat použijte stejnou opravu k aktualizaci ID modelu (na novou verzi modelu) i všechna pole, která musí být ve dvojčeti změněna, aby odpovídala novému modelu.

Možná budete muset aktualizovat relace a další modely ve vaší instanci, které na tento model odkazují, aby se odkazovaly na novou verzi modelu. K dosažení tohoto účelu budete muset provést další operaci aktualizace modelu, takže se vraťte na začátek této části a opakujte proces pro všechny další modely, které potřebují aktualizaci.

3. (Volitelné) Vyřazení nebo odstranění staré verze modelu

Pokud už starší verzi modelu nebudete používat, můžete starší model vyřadit z provozu . Tato akce umožňuje modelu zachovat existující v instanci, ale nedá se použít k vytvoření nových digitálních dvojčat.

Starý model můžete také úplně odstranit , pokud ho už nechcete v instanci vůbec.

Oddíly propojené výše obsahují ukázkový kód a důležité informace o vyřazení a odstranění modelů z provozu.

Strategie 2: Odstranění starého modelu a opětovné načtení

Místo zvýšení verze modelu můžete model zcela odstranit a znovu načíst upravený model do instance.

Azure Digital Twins si nepamatuje, že se starý model nahrál, takže tato akce bude vypadat jako nahrání zcela nového modelu. Dvojčata, která model používají, se po zpřístupnění automaticky přepne na novou definici. V závislosti na tom, jak se nová definice liší od staré, můžou mít tato dvojčata vlastnosti a relace, které odpovídají odstraněné definici a nejsou platné s novou definicí, takže je budete muset opravit, abyste měli jistotu, že zůstanou platné.

Pokud chcete tuto strategii použít, postupujte podle následujících kroků.

1. Odstranění starého modelu

Vzhledem k tomu, že Azure Digital Twins neumožňuje dva modely se stejným ID, začněte odstraněním původního modelu z vaší instance.

Poznámka:

Pokud máte jiné modely, které závisí na tomto modelu (prostřednictvím dědičnosti nebo komponent), musíte tyto odkazy před odstraněním modelu odebrat. Tyto závislé modely můžete nejprve aktualizovat tak, aby odkazy dočasně odebraly, nebo závislé modely odstraňte a znovu je načtěte v pozdějším kroku.

Pomocí následujících pokynů odstraňte původní model. Tato akce opustí dvojčata, která používala tento model dočasně osamocené, protože teď používají model, který už neexistuje. Tento stav se opraví v dalším kroku při opětovném načtení aktualizovaného modelu.

2. Vytvoření a nahrání nového modelu

Začněte s DTDL původního modelu. Aktualizujte, přidejte nebo odeberte pole, která chcete změnit.

Pak model nahrajte do instance, jako by to byl nový model, který se nahrává poprvé.

3. Podle potřeby aktualizujte prvky grafu.

Teď, když byl nový model nahraný místo starého modelu, dvojčata v grafu začnou automaticky používat novou definici modelu, jakmile vyprší platnost mezipaměti ve vaší instanci a resetuje se. V závislosti na velikosti grafu může tento proces trvat 10 až 15 minut nebo déle. Potom by měly být nové a změněné vlastnosti modelu přístupné a odebrané vlastnosti už nebudou přístupné.

Poznámka:

Pokud jste odebrali jiné závislé modely dříve, abyste původní model odstranili, znovu je načtěte po resetování mezipaměti. Pokud jste aktualizovali závislé modely tak, aby dočasně odebraly odkazy na původní model, můžete je znovu aktualizovat a vrátit odkaz zpět.

Dále aktualizujte dvojčata a relace ve vaší instanci tak, aby jejich vlastnosti odpovídaly vlastnostem definovaným novým modelem. Před dokončením tohoto kroku se dvojčata, která neodpovídají modelu, stále můžou číst, ale nelze je zapsat do. Další informace o stavu dvojčat bez platného modelu najdete v tématu Dvojčata bez modelů.

Existují dva způsoby, jak aktualizovat dvojčata a relace pro nový model, aby byly znovu zapisovatelné:

  • Podle potřeby opravte dvojčata a relace tak, aby odpovídaly novému modelu. K aktualizaci dvojčat a relací aktualizací můžete použít následující pokyny.
    • Pokud jste přidali vlastnosti: Aktualizace dvojčat a relací tak, aby nové hodnoty byly povinné, protože dvojčata, u kterých chybí nové hodnoty, budou stále platná dvojčata. Můžete je opravit, ale chcete přidat hodnoty pro nové vlastnosti.
    • Pokud jste odebrali vlastnosti: Je nutné opravit dvojčata, aby se odebraly vlastnosti, které jsou teď u nového modelu neplatné.
    • Pokud jste aktualizovali vlastnosti: Je nutné opravit dvojčata, aby se aktualizovaly hodnoty změněných vlastností, které mají být platné pro nový model.
  • Odstraňte dvojčata a relace, které model používají, a vytvořte je znovu. Následující pokyny můžete použít k odstranění dvojčat a opětovnému vytvoření dvojčat a odstranění relací a opětovnému vytvoření relací.
    • Tuto operaci můžete chtít provést, pokud v modelu provádíte mnoho změn a bude obtížné aktualizovat stávající dvojčata tak, aby odpovídala tomuto modelu. Rekreační ale může být složité, pokud máte mnoho dvojčat, která jsou propojena mnoha relacemi.

Odebrání modelů

Modely lze ze služby odebrat jedním ze dvou způsobů:

  • Vyřazení z provozu: Jakmile se model vyřadí z provozu, už ho nemůžete použít k vytvoření nových digitálních dvojčat. Stávající digitální dvojčata, která už tento model používají, nejsou ovlivněná, takže je můžete aktualizovat pomocí věcí, jako jsou změny vlastností a přidání nebo odstranění relací.
  • Odstranění: Tato operace zcela odebere model z řešení. Všechna dvojčata, která používala tento model, už nejsou přidružená k žádnému platnému modelu, takže se považují za to, že model vůbec nemají. Tato dvojčata si stále můžete přečíst, ale nemůžete v nich provádět žádné aktualizace, dokud se znovu nepřiřadí k jinému modelu.

Tyto operace jsou samostatné funkce a nemají na sebe vliv, i když se můžou používat společně k postupnému odebrání modelu.

Poznámka:

Pokud chcete odstranit všechny modely, dvojčata a relace v instanci najednou, použijte rozhraní API pro odstranění úloh.

Vyřazení

Pokud chcete model vyřadit z provozu, můžete použít metodu DecommissionModel ze sady SDK:

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

Model můžete také vyřadit z provozu pomocí volání rozhraní REST API DigitalTwinModels Update. Vlastnost decommissioned je jedinou vlastností, kterou lze nahradit tímto voláním rozhraní API. Dokument opravy JSON bude vypadat přibližně takto:

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

Stav vyřazení modelu z ModelData provozu je součástí záznamů vrácených rozhraními API pro načítání modelu.

Odstranění

Všechny modely ve vaší instanci můžete odstranit najednou nebo to můžete udělat jednotlivě.

Příklad odstranění všech modelů najednou najdete v kompletních ukázkách pro úložiště Azure Digital Twins na GitHubu. Soubor CommandLoop.cs obsahuje funkci s kódem CommandDeleteAllModels pro odstranění všech modelů v instanci.

Pokud chcete odstranit jednotlivé modely, postupujte podle pokynů a důležitých aspektů ze zbytku této části.

Před odstraněním: Požadavky na odstranění

Obecně platí, že modely je možné kdykoli odstranit.

Výjimkou jsou modely, na které závisejí jiné modely, a to buď s extends relací, nebo jako komponentou. Pokud například model ConferenceRoom rozšiřuje model místnosti a má model ACUnit jako součást, nemůžete odstranit místnost nebo ACUnit, dokud konferenční místnost neodebere tyto příslušné odkazy.

Můžete to udělat tak, že aktualizujete závislý model tak, aby odebral závislosti, nebo úplně odstranil závislý model.

Během odstraňování: Proces odstranění

I když model splňuje požadavky na jeho okamžité odstranění, můžete nejprve projít několika kroky, abyste se vyhnuli nezamýšleným důsledkům pro dvojčata, která zůstala za sebou. Tady je několik kroků, které vám můžou pomoct se správou tohoto procesu:

  1. Nejprve vyřadíte model z provozu.
  2. Počkejte několik minut, abyste se ujistili, že služba zpracovala všechny žádosti o vytvoření dvojčete za poslední minutu odeslané před vyřazením z provozu.
  3. Dotazování dvojčat podle modelu a zobrazení všech dvojčat, která používají model vyřazený z provozu
  4. Pokud je už nepotřebujete, odstraňte dvojčata nebo je v případě potřeby opravte na nový model. Můžete se také rozhodnout, že je necháte samostatně, v takovém případě se stanou dvojčaty bez modelů, jakmile se model odstraní. Důsledky tohoto stavu najdete v další části.
  5. Počkejte několik minut, abyste se ujistili, že se změny změnily.
  6. Odstranění modelu

K odstranění modelu můžete použít volání sady DeleteModel SDK:

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

Model můžete také odstranit pomocí volání rozhraní REST API Pro odstranění modelu DigitalTwinModels.

Po odstranění: Dvojčata bez modelů

Po odstranění modelu se teď všechny digitální dvojčata, která používala tento model, považují za bez modelu. Neexistuje žádný dotaz, který by vám mohl poskytnout seznam všech dvojčat v tomto stavu– i když můžete dvojčata dotazovat odstraněným modelem, abyste věděli, jaká dvojčata jsou ovlivněná.

Tady je přehled toho, co můžete a nemůžete dělat s dvojčaty, která nemají model.

Co můžete udělat:

  • Dotazování dvojčete
  • Čtení vlastností
  • Čtení odchozích relací
  • Přidání a odstranění příchozích relací (stejně jako v případě ostatních dvojčat může stále tvořit relace s tímto dvojčetem)
    • Definice target relace může stále odrážet DTMI odstraněného modelu. Tady také může fungovat vztah bez definovaného cíle.
  • Odstranění vztahů
  • Odstranění dvojčete

Co nemůžete udělat:

  • Úprava odchozích relací (stejně jako u relací z tohoto dvojčete do jiných dvojčat)
  • Upravit vlastnosti

Po odstranění: Opětovné načtení modelu

Po odstranění modelu se můžete později rozhodnout nahrát nový model se stejným ID jako ten, který jste odstranili. Tady je to, co se v takovém případě stane.

  • Z pohledu úložiště řešení je tato operace stejná jako nahrávání zcela nového modelu. Služba si nepamatuje, že se ta stará nahrála.
  • Pokud v grafu odkazující na odstraněný model existují nějaká zbývající dvojčata, už nejsou osamocené; toto ID modelu je znovu platné s novou definicí. Pokud se ale nová definice modelu liší od definice modelu, která byla odstraněna, můžou mít tato dvojčata vlastnosti a relace, které odpovídají odstraněné definici a nejsou platné s novou definicí.

Azure Digital Twins nezabrání tomuto stavu, proto dávejte pozor na správné opravy dvojčat, abyste měli jistotu, že zůstanou platné prostřednictvím přepínače definice modelu.

Převod modelů v2 na v3

Azure Digital Twins podporuje DTDL verze 2 a 3 (zkrácené v dokumentaci na verzi 2 a v3). V3 je doporučená volba na základě svých rozšířených možností. Tato část vysvětluje, jak aktualizovat existující model DTDL v2 na DTDL v3.

  1. Aktualizujte kontext. Hlavní funkcí, která identifikuje model jako v2 nebo v3, je @context pole v rozhraní. Pokud chcete převést model z v2 na v3, změňte kontextovou dtmi:dtdl:context;2 hodnotu na dtmi:dtdl:context;3. U mnoha modelů to bude jediná požadovaná změna.
    1. Hodnota ve verzi 2: "@context": "dtmi:dtdl:context;2"
    2. Hodnota v 3: "@context": "dtmi:dtdl:context;3".
  2. V případě potřeby aktualizujte sémantické typy. V DTDL v2 se nativně podporují sémantické typy . V DTDL v3 jsou součástí rozšíření funkcí QuantitativeTypes. Pokud tedy model v2 používal sémantické typy, budete muset při převodu modelu na v3 přidat rozšíření funkcí. Chcete-li to provést, nejprve změňte @context pole v rozhraní z jedné hodnoty na matici hodnot a pak přidejte hodnotu dtmi:dtdl:extension:quantitativeTypes;1.
    1. Hodnota ve verzi 2: "@context": "dtmi:dtdl:context;2"
    2. Hodnota v 3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
  3. V případě potřeby zvažte omezení velikosti. V2 a v3 mají různá omezení velikosti, takže pokud je vaše rozhraní velmi velké, můžete zkontrolovat limity v rozdílech mezi DTDL v2 a v3.

Po těchto změnách byl bývalý model DTDL v2 převeden na model DTDL v3.

Můžete také zvážit nové funkce DTDL v3, jako jsou vlastnosti typu pole, uvolnění verzí a další rozšíření funkcí, abyste zjistili, jestli některé z nich by byly přínosné. Úplný seznam rozdílů mezi DTDL v2 a v3 najdete v popisu jazyka DTDL verze 2 ve verzi 2.

Poznámka:

Azure Digital Twins Explorer v současné době plně podporuje modely DTDL v2 a podporuje omezené funkce pro modely DTDL v3.

Modely DTDL v3 lze zobrazit na panelu Modely a dvojčata vytvořená pomocí modelů DTDL v3 je možné zobrazit a upravit (včetně modelů s vlastnostmi pole). Modely DTDL v3 se ale nezobrazí na panelu Graf modelů a nedají se importovat pomocí Průzkumníka služby Azure Digital Twins. K importu modelů DTDL v3 do vaší instance použijte jiné vývojářské rozhraní, jako jsou rozhraní API a sady SDK nebo Azure CLI.

Další kroky

Podívejte se, jak vytvářet a spravovat digitální dvojčata na základě vašich modelů: