Azure Digital Twins-modellen beheren

  • Artikel

In dit artikel wordt beschreven hoe u de modellen in uw Azure Digital Twins-exemplaar beheert. Beheerbewerkingen omvatten het uploaden, valideren, ophalen en verwijderen van modellen.

Vereisten

Als u met Azure Digital Twins in dit artikel wilt werken, hebt u een Azure Digital Twins-exemplaar en de vereiste machtigingen nodig om deze te gebruiken. Als u al een Azure Digital Twins-exemplaar hebt ingesteld, kunt u dat exemplaar gebruiken en doorgaan naar de volgende sectie. Volg anders de instructies in Een instantie en verificatie instellen. De instructies bevatten informatie om te controleren of u elke stap hebt voltooid.

Nadat u uw exemplaar hebt ingesteld, noteert u de hostnaam van het exemplaar. U vindt de hostnaam in Azure Portal.

Ontwikkelaarsinterfaces

In dit artikel wordt uitgelegd hoe u verschillende beheerbewerkingen kunt uitvoeren met behulp van de .NET-SDK (C#). U kunt dezelfde beheeroproepen ook maken met behulp van de andere taal-SDK's die worden beschreven in Azure Digital Twins-API's en SDK's.

Andere ontwikkelaarsinterfaces die kunnen worden gebruikt om deze bewerkingen te voltooien, zijn onder andere:

Visualisatie

Azure Digital Twins Explorer is een visueel hulpmiddel voor het verkennen van de gegevens in uw Azure Digital Twins-grafiek. U kunt de verkenner gebruiken om uw modellen, tweelingen en relaties weer te geven, op te vragen en te bewerken.

Zie Azure Digital Twins Explorer voor meer informatie over het hulpprogramma Azure Digital Twins Explorer. Zie Azure Digital Twins Explorer gebruiken voor gedetailleerde stappen voor het gebruik van de functies.

De visualisatie ziet er als volgt uit:

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

Modellen maken

U kunt uw eigen modellen helemaal zelf maken of bestaande ontologieën gebruiken die beschikbaar zijn voor uw branche.

Modellen ontwerpen

Modellen voor Azure Digital Twins worden geschreven in DTDL en opgeslagen als JSON-bestanden. Er is ook een DTDL-extensie beschikbaar voor Visual Studio Code, die syntaxisvalidatie en andere functies biedt om het gemakkelijker te maken DTDL-documenten te schrijven.

Bekijk een voorbeeld waarin een ziekenhuis hun kamers digitaal wil vertegenwoordigen. Elke kamer bevat een slimme zeepdispenser voor het bewaken van handwas en sensoren om het verkeer door de ruimte te bewaken.

De eerste stap in de richting van de oplossing is het maken van modellen die aspecten van het ziekenhuis vertegenwoordigen. Een patiëntenkamer in dit scenario kan als volgt worden beschreven:

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

Notitie

Dit is een voorbeeldtekst voor een JSON-bestand waarin een model wordt gedefinieerd en opgeslagen, dat moet worden geüpload als onderdeel van een clientproject. De REST API-aanroep neemt daarentegen een matrix van modeldefinities zoals hierboven (die is toegewezen aan een IEnumerable<string> in de .NET SDK). Als u dit model dus rechtstreeks in de REST API wilt gebruiken, plaatst u het tussen vierkante haken.

Dit model definieert een naam en een unieke id voor de patiëntenkamer en eigenschappen die het aantal bezoekers en de status van de handwas vertegenwoordigen. Deze tellers worden bijgewerkt van bewegingssensoren en slimme zeepdispensers en worden samen gebruikt om een handwash percentage eigenschap te berekenen. Het model definieert ook een relatie hasDevices, die wordt gebruikt om digitale dubbels te verbinden op basis van dit ruimtemodel met de werkelijke apparaten.

Notitie

Er zijn enkele DTDL-functies die momenteel niet door Azure Digital Twins worden ondersteund, waaronder het writable kenmerk voor eigenschappen en relaties, en minMultiplicitymaxMultiplicity voor relaties. Zie Servicespecifieke DTDL-notities voor meer informatie.

Met deze methode kunt u modellen definiëren voor de ziekenhuisafdelingen, zones of het ziekenhuis zelf.

Als u een uitgebreide modelset wilt bouwen die uw branchedomein beschrijft, kunt u overwegen of er een bestaande brancheonologie is die u kunt gebruiken om het ontwerpen van modellen eenvoudiger te maken. In de volgende sectie worden brancheonologieën in meer detail beschreven.

Bestaande industriestandaard ontologieën gebruiken

Een ontologie is een reeks modellen die een bepaald domein uitgebreid beschrijven, zoals productie, bouwstructuren, IoT-systemen, slimme steden, energienetten, webinhoud en meer.

Als uw oplossing voor een bepaalde branche is die gebruikmaakt van een soort modelleringsstandaard, kunt u overwegen om te beginnen met een bestaande set modellen die zijn ontworpen voor uw branche in plaats van uw modellen helemaal zelf te ontwerpen. Microsoft werkt samen met domeinexperts om DTDL-modelonologieën te maken op basis van industriestandaarden, om te helpen bij het minimaliseren van heruitvinding en het stimuleren van consistentie en eenvoud in alle brancheoplossingen. U kunt meer lezen over deze ontologieën, waaronder hoe u deze kunt gebruiken en welke ontologieën er nu beschikbaar zijn, in Wat is een ontologie?.

Syntaxis valideren

Nadat u een model hebt gemaakt, is het raadzaam om uw modellen offline te valideren voordat u ze uploadt naar uw Azure Digital Twins-exemplaar.

Om u te helpen uw modellen te valideren, wordt er een DTDL-parseringsbibliotheek aan de clientzijde van .NET aangeboden in NuGet: DTDLParser. U kunt de parserbibliotheek rechtstreeks in uw C#-code gebruiken. U kunt ook het voorbeeldgebruik van de parser bekijken in de DTDLParserResolveSample in GitHub.

Modellen uploaden

Zodra modellen zijn gemaakt, kunt u ze uploaden naar het Azure Digital Twins-exemplaar.

Wanneer u klaar bent om een model te uploaden, kunt u het volgende codefragment gebruiken voor de .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 });

Bij het uploaden worden modelbestanden gevalideerd door de service.

Meestal moet u meer dan één model uploaden naar de service. Er zijn verschillende manieren waarop u veel modellen tegelijk kunt uploaden in één transactie. Houd rekening met de grootte van uw modelset terwijl u doorloopt in de rest van deze sectie om u te helpen bij het kiezen van een strategie.

Kleine modelsets uploaden

Voor kleinere modelsets kunt u meerdere modellen tegelijk uploaden met behulp van afzonderlijke API-aanroepen. U kunt de huidige limiet controleren voor het aantal modellen dat kan worden geüpload in één API-aanroep in de limieten van Azure Digital Twins.

Als u de SDK gebruikt, kunt u meerdere modelbestanden uploaden met de CreateModels methode als volgt:

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

Als u de REST API's of Azure CLI gebruikt, kunt u meerdere modellen uploaden door meerdere modeldefinities in één JSON-bestand te plaatsen dat samen moet worden geüpload. In dit geval moeten de modellen in een JSON-matrix in het bestand worden geplaatst, zoals in het volgende voorbeeld:

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

Grote modelsets uploaden met de IMPORT Jobs-API

Voor grote modelsets kunt u de API Import Jobs gebruiken om veel modellen tegelijk te uploaden in één API-aanroep. De API kan tegelijkertijd de limiet voor Azure Digital Twins accepteren voor het aantal modellen in een exemplaar en de volgorde van modellen wordt automatisch opnieuw gerangschikt als dat nodig is om afhankelijkheden tussen deze modellen op te lossen. Deze methode vereist het gebruik van Azure Blob Storage, evenals schrijfmachtigingen in uw Azure Digital Twins-exemplaar voor modellen en bulktaken.

Tip

Met de IMPORT Jobs-API kunnen ook dubbels en relaties in dezelfde aanroep worden geïmporteerd om alle onderdelen van een grafiek tegelijk te maken. Zie Modellen, tweelingen en relaties bulksgewijs uploaden met de Import Jobs-API voor meer informatie over dit proces.

Als u modellen bulksgewijs wilt importeren, moet u uw modellen (en alle andere resources in de bulkimporttaak) structuren als een NDJSON-bestand . De Models sectie wordt direct na Header de sectie geleverd, waardoor deze de eerste grafiekgegevenssectie in het bestand is. U kunt een voorbeeld van een importbestand en een voorbeeldproject bekijken voor het maken van deze bestanden in de inleiding tot de importtaken-API.

Vervolgens moet het bestand worden geüpload naar een toevoeg-blob in Azure Blob Storage. Zie Een container maken voor instructies over het maken van een Azure-opslagcontainer. Upload vervolgens het bestand met behulp van de uploadmethode van uw voorkeur (sommige opties zijn de AzCopy-opdracht, de Azure CLI of de Azure-portal).

Zodra het NDJSON-bestand is geüpload naar de container, haalt u de URL op in de blobcontainer. U gebruikt deze waarde verderop in de hoofdtekst van de API-aanroep voor bulkimport.

Hier volgt een schermopname van de URL-waarde van een blobbestand in Azure Portal:

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

Vervolgens kan het bestand worden gebruikt in een API-aanroep importtaken. U geeft de BLOB Storage-URL van het invoerbestand op, evenals een nieuwe BLOB Storage-URL om aan te geven waar u het uitvoerlogboek wilt opslaan wanneer het door de service wordt gemaakt.

Modellen ophalen

U kunt modellen weergeven en ophalen die zijn opgeslagen op uw Azure Digital Twins-exemplaar.

Uw opties zijn onder andere:

  • Eén model ophalen
  • Alle modellen ophalen
  • Metagegevens en afhankelijkheden voor modellen ophalen

Hier volgen enkele voorbeelden van aanroepen:

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

De SDK-aanroepen om alle retourobjecten op DigitalTwinsModelData te halen. DigitalTwinsModelData bevat metagegevens over het model dat is opgeslagen in het Azure Digital Twins-exemplaar, zoals de naam, de DTMI en de aanmaakdatum van het model. Het DigitalTwinsModelData object bevat eventueel ook het model zelf. Dit betekent dat u, afhankelijk van parameters, de aanroepen voor ophalen kunt gebruiken om alleen metagegevens op te halen (wat handig is in scenario's waarin u bijvoorbeeld een gebruikersinterfacelijst met beschikbare hulpprogramma's wilt weergeven) of het hele model.

De RetrieveModelWithDependencies aanroep retourneert niet alleen het aangevraagde model, maar ook alle modellen waarop het aangevraagde model afhankelijk is.

Modellen worden niet noodzakelijkerwijs geretourneerd in het documentformulier waarin ze zijn geüpload. Azure Digital Twins garandeert alleen dat het retourformulier semantisch gelijkwaardig is.

Modellen bijwerken

In deze sectie worden overwegingen en strategieën beschreven voor het bijwerken van uw modellen.

Voordat u bijwerkt: Denk na in de context van uw hele oplossing

Voordat u updates aanbrengt aan uw modellen, is het raadzaam om holistisch na te denken over uw hele oplossing en de impact van de modelwijzigingen die u gaat aanbrengen. Modellen in een Azure Digital Twins-oplossing zijn vaak onderling verbonden, dus het is belangrijk dat u rekening moet houden met trapsgewijze wijzigingen waarbij het bijwerken van een model verschillende andere moet bijwerken. Het bijwerken van modellen heeft invloed op de tweelingen die gebruikmaken van de modellen en kan ook van invloed zijn op de inkomende en verwerkingscode, clienttoepassingen en geautomatiseerde rapporten.

Hier volgen enkele aanbevelingen om u te helpen uw modelovergangen soepel te beheren:

  • In plaats van modellen als afzonderlijke entiteiten te beschouwen, kunt u overwegen om uw hele modelset te ontwikkelen wanneer dit van toepassing is om modellen en hun relaties up-to-date te houden.
  • Behandel modellen zoals broncode en beheer ze in broncodebeheer. Pas dezelfde kracht en aandacht toe op modellen en modelwijzigingen die u toepast op andere code in uw oplossing.

Wanneer u klaar bent om door te gaan met het bijwerken van uw modellen, beschrijft de rest van deze sectie de strategieën die u kunt gebruiken om de updates te implementeren.

Strategieën voor het bijwerken van modellen

Zodra een model is geüpload naar uw Azure Digital Twins-exemplaar, is de modelinterface onveranderbaar, wat betekent dat er geen traditionele 'bewerking' van modellen is. Azure Digital Twins staat ook niet toe dat hetzelfde exacte model opnieuw wordt geladen, terwijl er al een overeenkomend model aanwezig is in het exemplaar.

Als u in plaats daarvan wijzigingen wilt aanbrengen in een model, zoals bijwerken displayName of descriptiontoevoegen en verwijderen van eigenschappen, moet u het oorspronkelijke model vervangen.

Er zijn twee strategieën waaruit u kunt kiezen bij het vervangen van een model:

  • Strategie 1: Upload de nieuwe modelversie: Upload het model, met een nieuw versienummer en werk uw tweelingen bij om dat nieuwe model te gebruiken. Zowel de nieuwe als de oude versies van het model bestaan in uw exemplaar totdat u er een verwijdert.
    • Gebruik deze strategie als u slechts enkele van uw tweelingen wilt bijwerken die gebruikmaken van het model, of wanneer u ervoor wilt zorgen dat tweelingen voldoen aan hun modellen en schrijfbaar blijven via de modelovergang.
  • Strategie 2: Oud model verwijderen en opnieuw laden: verwijder het oorspronkelijke model en upload het nieuwe model met dezelfde naam en id (DTMI-waarde) op de plaats. Vervangt het oude model volledig door het nieuwe model.
    • Gebruik deze strategie als u alle dubbels wilt bijwerken die dit model tegelijk gebruiken, naast alle code die op de modellen reageert. Als uw modelupdate een belangrijke wijziging bevat met de modelupdate, zijn tweelingen gedurende korte tijd niet-conform met hun modellen terwijl u ze van het oude model naar het nieuwe model overbrengt, wat betekent dat ze geen updates kunnen uitvoeren totdat het nieuwe model is geüpload en de tweelingen eraan voldoen.

Notitie

Het aanbrengen van belangrijke wijzigingen in uw modellen wordt afgeraden buiten de ontwikkeling.

Ga verder met de volgende secties voor meer informatie over elke strategieoptie in detail.

Strategie 1: Nieuwe modelversie uploaden

Deze optie omvat het maken van een nieuwe versie van het model en het uploaden ervan naar uw exemplaar.

Met deze bewerking worden eerdere versies van het model niet overschreven, dus meerdere versies van het model bestaan in uw exemplaar totdat u ze verwijdert. Omdat de nieuwe modelversie en de oude modelversie naast elkaar bestaan, kunnen tweelingen de nieuwe versie van het model of de oudere versie gebruiken, wat betekent dat het uploaden van een nieuwe versie van een model niet automatisch van invloed is op bestaande tweelingen. De bestaande tweelingen blijven behouden als exemplaren van de oude modelversie en u kunt deze tweelingen bijwerken naar de nieuwe modelversie door ze te patchen.

Volg de onderstaande stappen om deze strategie te gebruiken.

1. Nieuwe modelversie maken en uploaden

Als u een nieuwe versie van een bestaand model wilt maken, begint u met de DTDL van het oorspronkelijke model. Werk de velden die u wilt wijzigen bij, voeg deze toe of verwijder deze.

Markeer dit model vervolgens als een nieuwere versie van het model door het id veld van het model bij te werken. De laatste sectie van de model-id, na de ;, vertegenwoordigt het modelnummer. Als u wilt aangeven dat dit model nu een meer bijgewerkte versie is, moet u het getal aan het einde van de id waarde verhogen tot een getal dat groter is dan het huidige versienummer.

Als uw vorige model-id er bijvoorbeeld als volgt uitziet:

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

Versie 2 van dit model kan er als volgt uitzien:

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

Upload vervolgens de nieuwe versie van het model naar uw exemplaar.

Deze versie van het model is vervolgens beschikbaar in uw exemplaar om te gebruiken voor digitale dubbels. Eerdere versies van het model worden niet overschreven, dus meerdere versies van het model worden nu naast elkaar gebruikt in uw exemplaar.

2. Grafiekelementen indien nodig bijwerken

Werk vervolgens de tweelingen en relaties in uw exemplaar bij om de nieuwe modelversie te gebruiken in plaats van de oude.

U kunt de volgende instructies gebruiken om tweelingen bij te werken en relaties bij te werken. De patchbewerking voor het bijwerken van een dubbelmodel ziet er ongeveer als volgt uit:

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

Belangrijk

Wanneer u dubbels bijwerkt, gebruikt u dezelfde patch om zowel de model-id (naar de nieuwe modelversie) als alle velden die op de dubbel moeten worden gewijzigd, bij te werken zodat deze voldoen aan het nieuwe model.

Mogelijk moet u ook relaties en andere modellen in uw exemplaar bijwerken die verwijzen naar dit model, zodat ze verwijzen naar de nieuwe modelversie. U moet een andere modelupdatebewerking uitvoeren om dit doel te bereiken. Ga daarom terug naar het begin van deze sectie en herhaal het proces voor alle modellen die moeten worden bijgewerkt.

3. (Optioneel) Oude modelversie uit bedrijf nemen of verwijderen

Als u de oude modelversie niet meer gebruikt, kunt u het oudere model buiten gebruik stellen . Met deze actie kan het model bestaande blijven in het exemplaar, maar kan het niet worden gebruikt om nieuwe digitale dubbels te maken.

U kunt het oude model ook volledig verwijderen als u het niet meer in het exemplaar wilt hebben.

De bovenstaande secties bevatten voorbeeldcode en overwegingen voor het buiten gebruik stellen en verwijderen van modellen.

Strategie 2: Oud model verwijderen en opnieuw laden

In plaats van de versie van een model te verhogen, kunt u een model volledig verwijderen en een bewerkt model opnieuw uploaden naar het exemplaar.

Azure Digital Twins herinnert zich niet dat het oude model ooit is geüpload, dus deze actie lijkt op het uploaden van een volledig nieuw model. Tweelingen die gebruikmaken van het model schakelen automatisch over naar de nieuwe definitie zodra het beschikbaar is. Afhankelijk van hoe de nieuwe definitie verschilt van de oude, kunnen deze tweelingen eigenschappen en relaties hebben die overeenkomen met de verwijderde definitie en die niet geldig zijn met de nieuwe definitie, dus u moet ze mogelijk patchen om ervoor te zorgen dat ze geldig blijven.

Volg de onderstaande stappen om deze strategie te gebruiken.

1. Oud model verwijderen

Omdat Azure Digital Twins geen twee modellen met dezelfde id toestaat, begint u met het verwijderen van het oorspronkelijke model uit uw exemplaar.

Notitie

Als u andere modellen hebt die afhankelijk zijn van dit model (via overname of onderdelen), moet u deze verwijzingen verwijderen voordat u het model kunt verwijderen. U kunt deze afhankelijke modellen eerst bijwerken om de verwijzingen tijdelijk te verwijderen, of de afhankelijke modellen verwijderen en deze in een latere stap opnieuw laden.

Gebruik de volgende instructies om het oorspronkelijke model te verwijderen. Met deze actie blijven uw tweelingen die dat model gebruikten tijdelijk 'zwevend' achter, omdat ze nu een model gebruiken dat niet meer bestaat. Deze status wordt hersteld in de volgende stap wanneer u het bijgewerkte model opnieuw laadt.

2. Nieuw model maken en uploaden

Begin met de DTDL van het oorspronkelijke model. Werk de velden die u wilt wijzigen bij, voeg deze toe of verwijder deze.

Upload vervolgens het model naar het exemplaar, alsof het een nieuw model was dat voor het eerst werd geüpload.

3. Grafiekelementen zo nodig bijwerken

Nu uw nieuwe model is geüpload in plaats van het oude model, beginnen de tweelingen in uw grafiek automatisch met het gebruik van de nieuwe modeldefinitie zodra de caching in uw exemplaar verloopt en opnieuw wordt ingesteld. Dit proces kan 10-15 minuten of langer duren, afhankelijk van de grootte van uw grafiek. Daarna moeten nieuwe en gewijzigde eigenschappen in uw model toegankelijk zijn en zijn verwijderde eigenschappen niet meer toegankelijk.

Notitie

Als u eerder andere afhankelijke modellen hebt verwijderd om het oorspronkelijke model te verwijderen, laadt u deze opnieuw nadat de cache opnieuw is ingesteld. Als u de afhankelijke modellen hebt bijgewerkt om verwijzingen naar het oorspronkelijke model tijdelijk te verwijderen, kunt u ze opnieuw bijwerken om de verwijzing terug te zetten.

Werk vervolgens de tweelingen en relaties in uw exemplaar bij zodat hun eigenschappen overeenkomen met de eigenschappen die zijn gedefinieerd door het nieuwe model. Voordat deze stap is voltooid, kunnen de tweelingen die niet overeenkomen met hun model nog steeds worden gelezen, maar kunnen ze niet naar worden geschreven. Zie Twins zonder modellen voor meer informatie over de status van tweelingen zonder geldig model.

Er zijn twee manieren om tweelingen en relaties voor het nieuwe model bij te werken, zodat ze opnieuw beschrijfbaar zijn:

  • Patch de tweelingen en relaties indien nodig, zodat ze passen bij het nieuwe model. U kunt de volgende instructies gebruiken om tweelingen bij te werken en relaties bij te werken.
    • Als u eigenschappen hebt toegevoegd: dubbels en relaties bijwerken zodat de nieuwe waarden niet vereist zijn, omdat tweelingen die de nieuwe waarden missen, nog steeds geldige dubbels zijn. U kunt ze patchen, maar u wilt waarden toevoegen voor de nieuwe eigenschappen.
    • Als u eigenschappen hebt verwijderd: u moet dubbels patchen om de eigenschappen te verwijderen die nu ongeldig zijn met het nieuwe model.
    • Als u eigenschappen hebt bijgewerkt: u moet dubbels patchen om de waarden van gewijzigde eigenschappen bij te werken zodat deze geldig zijn met het nieuwe model.
  • Verwijder tweelingen en relaties die gebruikmaken van het model en maak ze opnieuw. U kunt de volgende instructies gebruiken om tweelingen te verwijderen en dubbels opnieuw te maken, en relaties te verwijderen en relaties opnieuw te maken.
    • Mogelijk wilt u deze bewerking uitvoeren als u veel wijzigingen aanbrengt in het model en het is moeilijk om de bestaande tweelingen bij te werken zodat deze overeenkomen. Recreatie kan echter ingewikkeld zijn als u veel tweelingen hebt die zijn verbonden door veel relaties.

Modellen verwijderen

Modellen kunnen op twee manieren uit de service worden verwijderd:

  • Buiten gebruik stellen: zodra een model buiten gebruik is gesteld, kunt u het niet meer gebruiken om nieuwe digitale dubbels te maken. Bestaande digitale dubbels die dit model al gebruiken, worden niet beïnvloed, dus u kunt ze nog steeds bijwerken met zaken als eigenschapswijzigingen en het toevoegen of verwijderen van relaties.
  • Verwijderen: Met deze bewerking wordt het model volledig uit de oplossing verwijderd. Tweelingen die dit model gebruikten, zijn niet meer gekoppeld aan een geldig model, dus ze worden behandeld alsof ze helemaal geen model hebben. U kunt deze tweelingen nog steeds lezen, maar u kunt er geen updates op aanbrengen totdat ze opnieuw zijn toegewezen aan een ander model.

Deze bewerkingen zijn afzonderlijke functies en hebben geen invloed op elkaar, hoewel ze mogelijk samen worden gebruikt om een model geleidelijk te verwijderen.

Notitie

Als u alle modellen, tweelingen en relaties in een exemplaar tegelijk wilt verwijderen, gebruikt u de API Taken verwijderen.

Ontmanteling

Als u een model buiten gebruik wilt stellen, kunt u de methode DecommissionModel van de SDK gebruiken:

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

U kunt een model ook buiten gebruik stellen met behulp van de REST API-aanroep DigitalTwinModels Update. De decommissioned eigenschap is de enige eigenschap die kan worden vervangen door deze API-aanroep. Het JSON Patch-document ziet er ongeveer als volgt uit:

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

De buitengebruikstellingsstatus van een model wordt opgenomen in de ModelData records die worden geretourneerd door de API's voor het ophalen van het model.

Verwijdering

U kunt alle modellen in uw exemplaar tegelijk verwijderen of u kunt dit op individuele basis doen.

Zie de end-to-end voorbeelden voor de Azure Digital Twins-opslagplaats in GitHub voor een voorbeeld van het verwijderen van alle modellen tegelijk. Het bestand CommandLoop.cs bevat een CommandDeleteAllModels functie met code om alle modellen in het exemplaar te verwijderen.

Als u een afzonderlijk model wilt verwijderen, volgt u de instructies en overwegingen uit de rest van deze sectie.

Vóór verwijdering: verwijderingsvereisten

Over het algemeen kunnen modellen op elk gewenst moment worden verwijderd.

De uitzondering hierop zijn modellen waarvan andere modellen afhankelijk zijn, hetzij met een extends relatie of als onderdeel. Als een ConferenceRoom-model bijvoorbeeld een ruimtemodel uitbreidt en een ACUnit-model als onderdeel heeft, kunt u Room of ACUnit pas verwijderen als conferenceroom deze respectieve verwijzingen verwijdert.

U kunt dit doen door het afhankelijke model bij te werken om de afhankelijke afhankelijkheden te verwijderen of het afhankelijke model volledig te verwijderen.

Tijdens het verwijderen: verwijderingsproces

Zelfs als een model voldoet aan de vereisten om het onmiddellijk te verwijderen, kunt u eerst een paar stappen doorlopen om onbedoelde gevolgen te voorkomen voor de tweelingen die achterblijven. Hier volgen enkele stappen waarmee u het proces kunt beheren:

  1. Eerst moet u het model buiten gebruik stellen
  2. Wacht enkele minuten om ervoor te zorgen dat de service eventuele aanvragen voor het maken van dubbels van laatste minuten heeft verwerkt voordat de buitengebruikstelling
  3. Query's uitvoeren op model om alle dubbels te zien die gebruikmaken van het nu buiten gebruik gestelde model
  4. Verwijder de tweelingen als u ze niet meer nodig hebt of patch ze indien nodig naar een nieuw model. U kunt er ook voor kiezen om ze alleen te laten. In dat geval worden ze dubbels zonder modellen zodra het model is verwijderd. Zie de volgende sectie voor de gevolgen van deze status.
  5. Wacht nog een paar minuten om ervoor te zorgen dat de wijzigingen zijn geïsoleerd door
  6. Het model verwijderen

Als u een model wilt verwijderen, kunt u de DeleteModel SDK-aanroep gebruiken:

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

U kunt ook een model verwijderen met de REST API-aanroep DigitalTwinModels Delete .

Na verwijdering: Twins zonder modellen

Zodra een model is verwijderd, worden digitale dubbels die het model gebruiken, beschouwd als een model zonder model. Er is geen query die u een lijst met alle tweelingen in deze status kan geven, hoewel u nog steeds query's kunt uitvoeren op de tweelingen door het verwijderde model om te weten welke tweelingen worden beïnvloed.

Hier volgt een overzicht van wat u wel en niet kunt doen met tweelingen die geen model hebben.

U kunt het volgende doen:

  • Query's uitvoeren op de dubbel
  • Leeseigenschappen
  • Uitgaande relaties lezen
  • Binnenkomende relaties toevoegen en verwijderen (net als in andere tweelingen kunnen nog steeds relaties met deze dubbel vormen)
    • De target definitie van de relatie kan nog steeds de DTMI van het verwijderde model weerspiegelen. Een relatie zonder gedefinieerd doel kan hier ook werken.
  • Relaties verwijderen
  • De dubbel verwijderen

Dingen die u niet kunt doen:

  • Uitgaande relaties bewerken (zoals in, relaties van deze dubbel naar andere tweelingen)
  • Eigenschappen bewerken

Na verwijdering: Een model opnieuw laden

Nadat een model is verwijderd, kunt u later besluiten een nieuw model te uploaden met dezelfde id als het model dat u hebt verwijderd. In dat geval gebeurt het volgende.

  • Vanuit het perspectief van het oplossingsarchief is deze bewerking hetzelfde als het uploaden van een volledig nieuw model. De service herinnert zich niet dat de oude ooit is geüpload.
  • Als er nog tweelingen in de grafiek zijn die naar het verwijderde model verwijzen, zijn ze niet meer zwevend; deze model-id is opnieuw geldig met de nieuwe definitie. Als de nieuwe definitie voor het model echter anders is dan de modeldefinitie die is verwijderd, hebben deze tweelingen mogelijk eigenschappen en relaties die overeenkomen met de verwijderde definitie en die niet geldig zijn met de nieuwe definitie.

Azure Digital Twins voorkomt deze status niet. Zorg er dus voor dat u dubbels op de juiste manier patcht om ervoor te zorgen dat ze geldig blijven via de switch voor modeldefinities.

V2-modellen converteren naar v3

Azure Digital Twins ondersteunt respectievelijk DTDL-versies 2 en 3 (ingekort in de documentatie naar respectievelijk v2 en v3). V3 is de aanbevolen keuze op basis van de uitgebreide mogelijkheden. In deze sectie wordt uitgelegd hoe u een bestaand DTDL v2-model bijwerkt naar DTDL v3.

  1. Werk de context bij. De belangrijkste functie die een model identificeert als v2 of v3, is het @context veld op de interface. Als u een model wilt converteren van v2 naar v3, wijzigt u de dtmi:dtdl:context;2 contextwaarde in dtmi:dtdl:context;3. Voor veel modellen is dit de enige vereiste wijziging.
    1. Waarde in v2: "@context": "dtmi:dtdl:context;2"
    2. Waarde in v3: "@context": "dtmi:dtdl:context;3".
  2. Werk indien nodig semantische typen bij. In DTDL v2 worden semantische typen systeemeigen ondersteund. In DTDL v3 zijn ze opgenomen in de functie-extensie QuantitativeTypes. Dus als uw v2-model semantische typen heeft gebruikt, moet u de functie-extensie toevoegen bij het converteren van het model naar v3. Hiervoor wijzigt u eerst het @context veld op de interface van één waarde in een matrix met waarden en voegt u vervolgens de waarde dtmi:dtdl:extension:quantitativeTypes;1toe.
    1. Waarde in v2: "@context": "dtmi:dtdl:context;2"
    2. Waarde in v3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
  3. Overweeg indien nodig de groottelimieten. V2 en v3 hebben verschillende groottelimieten, dus als uw interface erg groot is, kunt u de limieten controleren in de verschillen tussen DTDL v2 en v3.

Na deze wijzigingen is een voormalig DTDL v2-model geconverteerd naar een DTDL v3-model.

Mogelijk wilt u ook rekening houden met nieuwe mogelijkheden van DTDL v3, zoals eigenschappen van het matrixtype, versieversoepeling en aanvullende functie-extensies, om te zien of een van deze voordelen voordelen zou opleveren. Zie Wijzigingen van versie 2 in de DTDL v3-taalbeschrijving voor een volledige lijst met verschillen tussen DTDL v2 en v3.

Volgende stappen

Lees hoe u digitale dubbels maakt en beheert op basis van uw modellen: