Dela via

Hantera Azure Digital Twins-modeller

  • Artikel

Den här artikeln beskriver hur du hanterar modellerna i din Azure Digital Twins-instans. Hanteringsåtgärder omfattar uppladdning, validering, hämtning och borttagning av modeller.

Förutsättningar

För att arbeta med Azure Digital Twins i den här artikeln behöver du en Azure Digital Twins-instans och de behörigheter som krävs för att använda den. Om du redan har konfigurerat en Azure Digital Twins-instans kan du använda den instansen och gå vidare till nästa avsnitt. Annars följer du anvisningarna i Konfigurera en instans och autentisering. Anvisningarna innehåller information som hjälper dig att kontrollera att du har slutfört varje steg.

När du har konfigurerat instansen antecknar du instansens värdnamn. Du hittar värdnamnet i Azure-portalen.

Utvecklargränssnitt

Den här artikeln beskriver hur du slutför olika hanteringsåtgärder med hjälp av .NET (C#) SDK. Du kan också skapa samma hanteringsanrop med de andra språk-SDK:erna som beskrivs i Azure Digital Twins-API:er och SDK:er.

Andra utvecklargränssnitt som kan användas för att slutföra dessa åtgärder är:

Kommentar

För närvarande har Azure Digital Twins Explorer fullt stöd för DTDL v2-modeller och har stöd för begränsade funktioner för DTDL v3-modeller.

DTDL v3-modeller kan visas i panelen Modeller och tvillingar som skapats med DTDL v3-modeller kan visas och redigeras (inklusive de med matrisegenskaper). DTDL v3-modeller visas dock inte i panelen Modelldiagram och de kan inte importeras med Azure Digital Twins Explorer. Om du vill importera DTDL v3-modeller till din instans använder du ett annat utvecklargränssnitt som API:er och SDK:er eller Azure CLI.

Visualisering

Azure Digital Twins Explorer är ett visuellt verktyg för att utforska data i ditt Azure Digital Twins-diagram. Du kan använda utforskaren för att visa, fråga och redigera dina modeller, tvillingar och relationer.

Mer information om Azure Digital Twins Explorer-verktyget finns i Azure Digital Twins Explorer. Detaljerade anvisningar om hur du använder dess funktioner finns i Använda Azure Digital Twins Explorer.

Så här ser visualiseringen ut:

Skärmbild av Azure Digital Twins Explorer som visar ett exempelmodelldiagram.

Skapa modeller

Du kan skapa egna modeller från grunden eller använda befintliga ontologier som är tillgängliga för din bransch.

Skapa modeller

Modeller för Azure Digital Twins skrivs i DTDL och sparas som JSON-filer. Det finns också ett DTDL-tillägg tillgängligt för Visual Studio Code, som tillhandahåller syntaxverifiering och andra funktioner för att göra det enklare att skriva DTDL-dokument.

Tänk dig ett exempel där ett sjukhus vill representera sina rum digitalt. Varje rum innehåller en smart tvålautomat för övervakning av handtvätt och sensorer för att övervaka trafiken genom rummet.

Det första steget mot lösningen är att skapa modeller som representerar aspekter av sjukhuset. Ett patientrum i det här scenariot kan beskrivas så här:

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

Kommentar

Det här är en exempeltext för en JSON-fil där en modell definieras och sparas, som ska laddas upp som en del av ett klientprojekt. REST API-anropet tar å andra sidan en matris med modelldefinitioner som den ovan (som mappas till en IEnumerable<string> i .NET SDK). Om du vill använda den här modellen direkt i REST-API:et omger du den med hakparenteser.

Den här modellen definierar ett namn och ett unikt ID för patientrummet och egenskaper som representerar antalet besökare och handtvättsstatus. Dessa räknare uppdateras från rörelsesensorer och smarta tvålautomater och används tillsammans för att beräkna en handwash percentage egenskap. Modellen definierar också en relation hasDevices, som kommer att användas för att ansluta alla digitala tvillingar baserat på den här rumsmodellen till de faktiska enheterna.

Kommentar

Det finns vissa DTDL-funktioner som Azure Digital Twins för närvarande inte stöder, inklusive writable attributet för egenskaper och relationer och minMultiplicity maxMultiplicity för relationer. Mer information finns i Tjänstspecifika DTDL-anteckningar.

Med den här metoden kan du definiera modeller för sjukhusets avdelningar, zoner eller själva sjukhuset.

Om målet är att skapa en omfattande modelluppsättning som beskriver din branschdomän bör du överväga om det finns en befintlig branschontologi som du kan använda för att göra modellredigering enklare. I nästa avsnitt beskrivs bransch ontologier i detalj.

Använda befintliga ontologier av branschstandard

En ontologi är en uppsättning modeller som på ett omfattande sätt beskriver en viss domän, till exempel tillverkning, byggnadsstrukturer, IoT-system, smarta städer, energinät, webbinnehåll med mera.

Om din lösning är för en viss bransch som använder någon form av modelleringsstandard kan du börja med en befintlig uppsättning modeller som är utformade för din bransch i stället för att designa dina modeller från grunden. Microsoft har samarbetat med domänexperter för att skapa DTDL-modell ontologier baserade på branschstandarder, för att minimera förnyelse och uppmuntra konsekvens och enkelhet i branschlösningar. Du kan läsa mer om dessa ontologier, inklusive hur du använder dem och vilka ontologier som är tillgängliga nu, i Vad är en ontologi?.

Verifiera syntax

När du har skapat en modell rekommenderar vi att du verifierar dina modeller offline innan du laddar upp dem till din Azure Digital Twins-instans.

För att hjälpa dig att verifiera dina modeller finns ett DTDL-parsningsbibliotek på .NET-klientsidan på NuGet: DTDLParser. Du kan använda parsningsbiblioteket direkt i C#-koden. Du kan också visa exempelanvändningen av parsern i DTDLParserResolveSample i GitHub.

Ladda upp modeller

När modeller har skapats kan du ladda upp dem till Azure Digital Twins-instansen.

När du är redo att ladda upp en modell kan du använda följande kodfragment för .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 });

Vid uppladdning verifieras modellfiler av tjänsten.

Du behöver vanligtvis ladda upp mer än en modell till tjänsten. Det finns flera sätt att ladda upp många modeller samtidigt i en enda transaktion. För att hjälpa dig att välja en strategi bör du överväga storleken på din modelluppsättning när du fortsätter med resten av det här avsnittet.

Ladda upp små modelluppsättningar

För mindre modelluppsättningar kan du ladda upp flera modeller samtidigt med hjälp av enskilda API-anrop. Du kan kontrollera den aktuella gränsen för hur många modeller som kan laddas upp i ett enda API-anrop i Azure Digital Twins-gränserna.

Om du använder SDK:et kan du ladda upp flera modellfiler med metoden CreateModels så här:

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

Om du använder REST-API:er eller Azure CLI kan du ladda upp flera modeller genom att placera flera modelldefinitioner i en enda JSON-fil som ska laddas upp tillsammans. I det här fallet ska modellerna placeras i en JSON-matris i filen, som i följande exempel:

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

Ladda upp stora modelluppsättningar med API:et Importera jobb

För stora modelluppsättningar kan du använda API:et Importera jobb för att ladda upp många modeller samtidigt i ett enda API-anrop. API:et kan samtidigt acceptera upp till Gränsen för Azure Digital Twins för antalet modeller i en instans, och det ordnar automatiskt om modeller om det behövs för att lösa beroenden mellan dem. Den här metoden kräver användning av Azure Blob Storage, samt skrivbehörigheter i din Azure Digital Twins-instans för modeller och massjobb.

Dricks

MED API:et Importera jobb kan även tvillingar och relationer importeras i samma anrop för att skapa alla delar av ett diagram samtidigt. Mer information om den här processen finns i Ladda upp modeller, tvillingar och relationer i bulk med API:et Importera jobb.

Om du vill importera modeller i bulk måste du strukturera dina modeller (och andra resurser som ingår i massimportjobbet) som en NDJSON-fil . Avsnittet Models kommer direkt efter Header avsnittet, vilket gör det till det första grafdataavsnittet i filen. Du kan visa en exempelimportfil och ett exempelprojekt för att skapa dessa filer i introduktionen för API:et Importera jobb.

Därefter måste filen laddas upp till en tilläggsblob i Azure Blob Storage. Anvisningar om hur du skapar en Azure Storage-container finns i Skapa en container. Ladda sedan upp filen med den uppladdningsmetod du föredrar (vissa alternativ är Kommandot AzCopy, Azure CLI eller Azure-portalen).

När NDJSON-filen har laddats upp till containern hämtar du dess URL i blobcontainern. Du använder det här värdet senare i brödtexten i API-anropet för massimport.

Här är en skärmbild som visar URL-värdet för en blobfil i Azure-portalen:

Skärmbild av Azure-portalen som visar URL:en för en fil i en lagringscontainer.

Sedan kan filen användas i ett API-anrop för importjobb. Du anger bloblagrings-URL:en för indatafilen samt en ny bloblagrings-URL för att ange var du vill att utdataloggen ska lagras när den skapas av tjänsten.

Hämta modeller

Du kan lista och hämta modeller som lagras på din Azure Digital Twins-instans.

Alternativen är:

  • Hämta en enskild modell
  • Hämta alla modeller
  • Hämta metadata och beroenden för modeller

Här är några exempelanrop:

// '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 anropar för att hämta modeller alla returnerade DigitalTwinsModelData objekt. DigitalTwinsModelData innehåller metadata om modellen som lagras i Azure Digital Twins-instansen, till exempel namn, DTMI och skapandedatum för modellen. Objektet DigitalTwinsModelData kan också innehålla själva modellen. Det innebär att du, beroende på parametrar, kan använda hämtningsanropen för att antingen hämta bara metadata (vilket är användbart i scenarier där du till exempel vill visa en användargränssnittslista med tillgängliga verktyg) eller hela modellen.

Anropet RetrieveModelWithDependencies returnerar inte bara den begärda modellen, utan även alla modeller som den begärda modellen är beroende av.

Modeller returneras inte nödvändigtvis i exakt det dokumentformulär som de laddades upp i. Azure Digital Twins garanterar endast att returformuläret är semantiskt likvärdigt.

Uppdatera modeller

I det här avsnittet beskrivs överväganden och strategier för att uppdatera dina modeller.

Innan du uppdaterar: Tänk i kontexten för hela lösningen

Innan du gör uppdateringar av dina modeller rekommenderar vi att du tänker holistiskt på hela lösningen och effekten av de modelländringar som du håller på att göra. Modeller i en Azure Digital Twins-lösning är ofta sammankopplade, så det är viktigt att vara medveten om sammanhängande ändringar där uppdatering av en modell kräver uppdatering av flera andra. Uppdatering av modeller påverkar tvillingarna som använder modellerna och kan även påverka ingress- och bearbetningskod, klientprogram och automatiserade rapporter.

Här följer några rekommendationer som hjälper dig att hantera dina modellövergångar smidigt:

  • I stället för att tänka på modeller som separata entiteter bör du överväga att utveckla hela din modelluppsättning när det är lämpligt för att hålla modeller och deras relationer uppdaterade tillsammans.
  • Behandla modeller som källkod och hantera dem i källkontrollen. Tillämpa samma stränghet och uppmärksamhet på modeller och modelländringar som du tillämpar på annan kod i din lösning.

När du är redo att fortsätta med processen med att uppdatera dina modeller beskriver resten av det här avsnittet de strategier som du kan använda för att implementera uppdateringarna.

Strategier för att uppdatera modeller

När en modell har laddats upp till din Azure Digital Twins-instans är modellgränssnittet oföränderligt, vilket innebär att det inte finns någon traditionell "redigering" av modeller. Azure Digital Twins tillåter inte heller återuppladdning av samma exakta modell medan en matchande modell redan finns i instansen.

Om du i stället vill göra ändringar i en modell, till exempel uppdatera displayName eller description, eller lägga till och ta bort egenskaper, måste du ersätta den ursprungliga modellen.

Det finns två strategier att välja mellan när du ersätter en modell:

  • Strategi 1: Ladda upp en ny modellversion: Ladda upp modellen med ett nytt versionsnummer och uppdatera tvillingarna så att de använder den nya modellen. Både de nya och gamla versionerna av modellen finns i din instans tills du tar bort en.
    • Använd den här strategin om du bara vill uppdatera några av dina tvillingar som använder modellen, eller när du vill se till att tvillingarna håller sig överensstämmande med sina modeller och skrivbara genom modellövergången.
  • Strategi 2: Ta bort gammal modell och ladda om: Ta bort den ursprungliga modellen och ladda upp den nya modellen med samma namn och ID (DTMI-värde) i stället. Ersätter helt den gamla modellen med den nya.
    • Använd den här strategin när du vill uppdatera alla tvillingar som använder den här modellen samtidigt, förutom all kod som reagerar på modellerna. Om modelluppdateringen innehåller en icke-bakåtkompatibel ändring med modelluppdateringen kommer tvillingarna att vara icke-konforma med sina modeller under en kort tid medan du övergår dem från den gamla modellen till den nya, vilket innebär att de inte kan ta några uppdateringar förrän den nya modellen har laddats upp och tvillingarna överensstämmer med den.

Kommentar

Att göra icke-bakåtkompatibla ändringar i dina modeller rekommenderas inte utanför utvecklingen.

Fortsätt till nästa avsnitt om du vill läsa mer om varje strategialternativ i detalj.

Strategi 1: Ladda upp ny modellversion

Det här alternativet innebär att skapa en ny version av modellen och ladda upp den till din instans.

Den här åtgärden skriver inte över tidigare versioner av modellen, så flera versioner av modellen samexisterar i din instans tills du tar bort dem. Eftersom den nya modellversionen och den gamla modellversionen samexisterar kan tvillingar använda antingen den nya versionen av modellen eller den äldre versionen, vilket innebär att uppladdning av en ny version av en modell inte automatiskt påverkar befintliga tvillingar. De befintliga tvillingarna förblir som instanser av den gamla modellversionen och du kan uppdatera dessa tvillingar till den nya modellversionen genom att korrigera dem.

Följ stegen nedan om du vill använda den här strategin.

1. Skapa och ladda upp en ny modellversion

Om du vill skapa en ny version av en befintlig modell börjar du med DTDL för den ursprungliga modellen. Uppdatera, lägga till eller ta bort de fält som du vill ändra.

Markera sedan den här modellen som en nyare version av modellen genom att uppdatera id modellens fält. Det sista avsnittet i modell-ID:t, efter ;, representerar modellnumret. Om du vill ange att den här modellen nu är en mer uppdaterad version ökar du talet i slutet av id värdet till ett tal som är större än det aktuella versionsnumret.

Om ditt tidigare modell-ID till exempel såg ut så här:

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

Version 2 av den här modellen kan se ut så här:

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

Ladda sedan upp den nya versionen av modellen till din instans.

Den här versionen av modellen kommer sedan att vara tillgänglig i din instans för användning för digitala tvillingar. Den skriver inte över tidigare versioner av modellen, så flera versioner av modellen samexisterar nu i din instans.

2. Uppdatera diagramelement efter behov

Uppdatera sedan tvillingarna och relationerna i din instans för att använda den nya modellversionen i stället för den gamla.

Du kan använda följande instruktioner för att uppdatera tvillingar och uppdatera relationer. Korrigeringsåtgärden för att uppdatera en tvillings modell ser ut ungefär så här:

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

Viktigt!

När du uppdaterar tvillingar använder du samma korrigering för att uppdatera både modell-ID :t (till den nya modellversionen) och alla fält som måste ändras på tvillingen för att den ska överensstämma med den nya modellen.

Du kan också behöva uppdatera relationer och andra modeller i din instans som refererar till den här modellen för att få dem att referera till den nya modellversionen. Du måste utföra en annan modelluppdateringsåtgärd för att uppnå detta syfte, så gå tillbaka till början av det här avsnittet och upprepa processen för alla fler modeller som behöver uppdateras.

3. (Valfritt) Inaktivera eller ta bort gammal modellversion

Om du inte längre använder den gamla modellversionen kan du inaktivera den äldre modellen. Med den här åtgärden kan modellen behålla befintlig i instansen, men den kan inte användas för att skapa nya digitala tvillingar.

Du kan också ta bort den gamla modellen helt om du inte vill ha den i instansen längre.

Avsnitten som är länkade ovan innehåller exempelkod och överväganden för att inaktivera och ta bort modeller.

Strategi 2: Ta bort gammal modell och ladda om

I stället för att öka versionen av en modell kan du ta bort en modell helt och ladda upp en redigerad modell på nytt till instansen.

Azure Digital Twins minns inte att den gamla modellen någonsin laddades upp, så den här åtgärden blir som att ladda upp en helt ny modell. Tvillingar som använder modellen växlar automatiskt över till den nya definitionen när den är tillgänglig. Beroende på hur den nya definitionen skiljer sig från den gamla, kan dessa tvillingar ha egenskaper och relationer som matchar den borttagna definitionen och inte är giltiga med den nya, så du kan behöva korrigera dem för att se till att de förblir giltiga.

Följ stegen nedan om du vill använda den här strategin.

1. Ta bort gammal modell

Eftersom Azure Digital Twins inte tillåter två modeller med samma ID börjar du med att ta bort den ursprungliga modellen från din instans.

Kommentar

Om du har andra modeller som är beroende av den här modellen (via arv eller komponenter) måste du ta bort dessa referenser innan du kan ta bort modellen. Du kan uppdatera de beroende modellerna först för att tillfälligt ta bort referenserna eller ta bort de beroende modellerna och ladda upp dem igen i ett senare steg.

Använd följande instruktioner för att ta bort den ursprungliga modellen. Den här åtgärden lämnar dina tvillingar som använde modellen tillfälligt "överblivna", eftersom de nu använder en modell som inte längre finns. Det här tillståndet repareras i nästa steg när du laddar om den uppdaterade modellen.

2. Skapa och ladda upp en ny modell

Börja med DTDL för den ursprungliga modellen. Uppdatera, lägga till eller ta bort de fält som du vill ändra.

Ladda sedan upp modellen till instansen, som om det vore en ny modell som laddades upp för första gången.

3. Uppdatera diagramelement efter behov

Nu när den nya modellen har laddats upp i stället för den gamla börjar tvillingarna i diagrammet automatiskt använda den nya modelldefinitionen när cachelagringen i din instans upphör att gälla och återställs. Den här processen kan ta 10–15 minuter eller längre, beroende på grafens storlek. Efter det bör nya och ändrade egenskaper i din modell vara tillgängliga och borttagna egenskaper kommer inte längre att vara tillgängliga.

Kommentar

Om du tog bort andra beroende modeller tidigare för att ta bort den ursprungliga modellen laddar du upp dem igen nu när cacheminnet har återställts. Om du har uppdaterat de beroende modellerna för att tillfälligt ta bort referenser till den ursprungliga modellen kan du uppdatera dem igen för att återställa referensen.

Uppdatera sedan tvillingarna och relationerna i din instans så att deras egenskaper matchar egenskaperna som definieras av den nya modellen. Innan det här steget har slutförts kan tvillingarna som inte matchar modellen fortfarande läsas, men kan inte skrivas till. Mer information om tillståndet för tvillingar utan en giltig modell finns i Tvillingar utan modeller.

Det finns två sätt att uppdatera tvillingar och relationer för den nya modellen så att de kan skrivas igen:

  • Korrigera tvillingarna och relationerna efter behov så att de passar den nya modellen. Du kan använda följande instruktioner för att uppdatera tvillingar och uppdatera relationer.
    • Om du har lagt till egenskaper: Uppdatering av tvillingar och relationer för att ha de nya värdena krävs inte, eftersom tvillingar som saknar de nya värdena fortfarande är giltiga tvillingar. Du kan korrigera dem men du vill lägga till värden för de nya egenskaperna.
    • Om du har tagit bort egenskaper: Det är nödvändigt att korrigera tvillingar för att ta bort de egenskaper som nu är ogiltiga med den nya modellen.
    • Om du har uppdaterat egenskaper: Du måste korrigera tvillingar för att uppdatera värdena för ändrade egenskaper så att de är giltiga med den nya modellen.
  • Ta bort tvillingar och relationer som använder modellen och återskapa dem. Du kan använda följande instruktioner för att ta bort tvillingar och återskapa tvillingar och ta bort relationer och återskapa relationer.
    • Du kanske vill göra den här åtgärden om du gör många ändringar i modellen och det blir svårt att uppdatera de befintliga tvillingarna så att de matchar den. Rekreation kan dock vara komplicerat om du har många tvillingar som är sammankopplade av många relationer.

Ta bort modeller

Modeller kan tas bort från tjänsten på något av två sätt:

  • Avaktivering: När en modell har inaktiverats kan du inte längre använda den för att skapa nya digitala tvillingar. Befintliga digitala tvillingar som redan använder den här modellen påverkas inte, så du kan fortfarande uppdatera dem med saker som egenskapsändringar och lägga till eller ta bort relationer.
  • Borttagning: Den här åtgärden tar bort modellen helt från lösningen. Tvillingar som använder den här modellen är inte längre associerade med någon giltig modell, så de behandlas som om de inte har någon modell alls. Du kan fortfarande läsa dessa tvillingar, men du kan inte göra några uppdateringar på dem förrän de har omtilldelats till en annan modell.

Dessa åtgärder är separata funktioner och påverkar inte varandra, även om de kan användas tillsammans för att ta bort en modell gradvis.

Kommentar

Om du vill ta bort alla modeller, tvillingar och relationer i en instans samtidigt använder du API:et Ta bort jobb.

Avveckling

Om du vill inaktivera en modell kan du använda metoden DecommissionModel från SDK:

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

Du kan också inaktivera en modell med hjälp av REST API-anropet DigitalTwinModels Update. Egenskapen decommissioned är den enda egenskapen som kan ersättas med det här API-anropet. JSON Patch-dokumentet ser ut ungefär så här:

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

En modells inaktiveringsstatus ingår i de ModelData poster som returneras av API:erna för modellhämtning.

Borttagning

Du kan ta bort alla modeller i din instans samtidigt, eller så kan du göra det individuellt.

Ett exempel på hur du tar bort alla modeller samtidigt finns i slutpunkt till slutpunkt-exempel för Azure Digital Twins-lagringsplatsen i GitHub. Filen CommandLoop.cs innehåller en CommandDeleteAllModels funktion med kod för att ta bort alla modeller i instansen.

Om du vill ta bort en enskild modell följer du anvisningarna och övervägandena från resten av det här avsnittet.

Före borttagning: Borttagningskrav

I allmänhet kan modeller tas bort när som helst.

Undantaget är modeller som andra modeller är beroende av, antingen med en extends relation eller som en komponent. Om en ConferenceRoom-modell till exempel utökar en rumsmodell och har en ACUnit-modell som en komponent, kan du inte ta bort Rum eller ACUnit förrän ConferenceRoom tar bort dessa referenser.

Du kan göra det genom att uppdatera den beroende modellen för att ta bort beroendena eller ta bort den beroende modellen helt.

Under borttagning: Borttagningsprocess

Även om en modell uppfyller kraven för att ta bort den omedelbart, kanske du vill gå igenom några steg först för att undvika oavsiktliga konsekvenser för tvillingarna som lämnas kvar. Här följer några steg som kan hjälpa dig att hantera processen:

  1. Först inaktiverar du modellen
  2. Vänta några minuter för att se till att tjänsten har bearbetat alla begäranden om tvillingskapande i sista minuten som skickats före avaktivering
  3. Fråga tvillingar efter modell för att se alla tvillingar som använder den nu inaktiverade modellen
  4. Ta bort tvillingarna om du inte längre behöver dem eller korrigera dem till en ny modell om det behövs. Du kan också välja att låta dem vara, i så fall blir de tvillingar utan modeller när modellen har tagits bort. Se nästa avsnitt för konsekvenserna av det här tillståndet.
  5. Vänta några minuter till för att se till att ändringarna har percolated genom
  6. Ta bort modellen

Om du vill ta bort en modell kan du använda anropet DeleteModel SDK:

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

Du kan också ta bort en modell med anropet DigitalTwinModels Delete REST API.

Efter borttagning: Tvillingar utan modeller

När en modell har tagits bort anses alla digitala tvillingar som använde modellen nu vara utan modell. Det finns ingen fråga som kan ge dig en lista över alla tvillingar i det här tillståndet, även om du fortfarande kan fråga tvillingarna efter den borttagna modellen för att veta vilka tvillingar som påverkas.

Här är en översikt över vad du kan och inte kan göra med tvillingar som inte har en modell.

Saker du kan göra:

  • Fråga tvillingen
  • Läsegenskaper
  • Läsa utgående relationer
  • Lägga till och ta bort inkommande relationer (som i kan andra tvillingar fortfarande bilda relationer till den här tvillingen)
    • I target relationsdefinitionen kan fortfarande återspegla DTMI för den borttagna modellen. En relation utan definierat mål kan också fungera här.
  • Ta bort relationer
  • Ta bort tvillingen

Saker du inte kan göra:

  • Redigera utgående relationer (som i relationer från den här tvillingen till andra tvillingar)
  • Redigera egenskaper

Efter borttagning: Ladda om en modell

När en modell har tagits bort kan du senare bestämma dig för att ladda upp en ny modell med samma ID som den du tog bort. Det här är vad som händer i det fallet.

  • Ur lösningsarkivets perspektiv är den här åtgärden densamma som att ladda upp en helt ny modell. Tjänsten minns inte att den gamla någonsin laddades upp.
  • Om det finns några återstående tvillingar i diagrammet som refererar till den borttagna modellen är de inte längre överblivna. det här modell-ID:t är giltigt igen med den nya definitionen. Men om den nya definitionen för modellen skiljer sig från den modelldefinition som togs bort kan dessa tvillingar ha egenskaper och relationer som matchar den borttagna definitionen och som inte är giltiga med den nya.

Azure Digital Twins förhindrar inte det här tillståndet, så var noga med att korrigera tvillingar på rätt sätt för att se till att de förblir giltiga via modelldefinitionsväxeln.

Konvertera v2-modeller till v3

Azure Digital Twins stöder DTDL-versionerna 2 och 3 (förkortas i dokumentationen till v2 respektive v3). V3 är det rekommenderade valet baserat på dess utökade funktioner. I det här avsnittet beskrivs hur du uppdaterar en befintlig DTDL v2-modell till DTDL v3.

  1. Uppdatera kontexten. Huvudfunktionen som identifierar en modell som v2 eller v3 är fältet @context i gränssnittet. Om du vill konvertera en modell från v2 till v3 ändrar du dtmi:dtdl:context;2 kontextvärdet till dtmi:dtdl:context;3. För många modeller är detta den enda nödvändiga ändringen.
    1. Värde i v2: "@context": "dtmi:dtdl:context;2"
    2. Värde i v3: "@context": "dtmi:dtdl:context;3".
  2. Uppdatera semantiska typer om det behövs. I DTDL v2 stöds semantiska typer internt. I DTDL v3 ingår de i funktionstillägget QuantitativeTypes. Så om din v2-modell använde semantiska typer måste du lägga till funktionstillägget när du konverterar modellen till v3. Det gör du genom att först ändra @context fältet i gränssnittet från ett enda värde till en matris med värden och sedan lägga till värdet dtmi:dtdl:extension:quantitativeTypes;1.
    1. Värde i v2: "@context": "dtmi:dtdl:context;2"
    2. Värde i v3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
  3. Om det behövs bör du överväga storleksgränser. V2 och v3 har olika storleksgränser, så om gränssnittet är mycket stort kanske du vill granska gränserna för skillnaderna mellan DTDL v2 och v3.

Efter dessa ändringar har en tidigare DTDL v2-modell konverterats till en DTDL v3-modell.

Du kanske också vill överväga nya funktioner i DTDL v3, till exempel egenskaper av matristyp, versionsavslappning och ytterligare funktionstillägg, för att se om någon av dem skulle vara fördelaktiga tillägg. En fullständig lista över skillnader mellan DTDL v2 och v3 finns i Ändringar från version 2 i språkbeskrivningen för DTDL v3.

Kommentar

För närvarande har Azure Digital Twins Explorer fullt stöd för DTDL v2-modeller och har stöd för begränsade funktioner för DTDL v3-modeller.

DTDL v3-modeller kan visas i panelen Modeller och tvillingar som skapats med DTDL v3-modeller kan visas och redigeras (inklusive de med matrisegenskaper). DTDL v3-modeller visas dock inte i panelen Modelldiagram och de kan inte importeras med Azure Digital Twins Explorer. Om du vill importera DTDL v3-modeller till din instans använder du ett annat utvecklargränssnitt som API:er och SDK:er eller Azure CLI.

Nästa steg

Se hur du skapar och hanterar digitala tvillingar baserat på dina modeller: