Digitale tweelingen beheren
Entiteiten in uw omgeving worden vertegenwoordigd door digitale dubbels. Het beheren van uw digitale dubbels kan bestaan uit het maken, wijzigen en verwijderen.
Dit artikel richt zich op het beheren van digitale dubbels; Als u wilt werken met relaties en de dubbelgrafiek als geheel, raadpleegt u De tweelinggrafiek en -relaties beheren.
Tip
Alle SDK-functies worden geleverd in synchrone en asynchrone versies.
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:
Een digitale dubbel maken
Als u een dubbel wilt maken, gebruikt u de CreateOrReplaceDigitalTwinAsync() methode op de serviceclient als volgt:
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
Als u een digitale dubbel wilt maken, moet u het volgende opgeven:
- Een id-waarde die u wilt toewijzen aan de digitale dubbel (u definieert die id wanneer de dubbel wordt gemaakt)
- Het model dat u wilt gebruiken
- Elke gewenste initialisatie van dubbelgegevens, waaronder...
- Eigenschappen (initialisatie optioneel): U kunt desgewenst initiële waarden instellen voor eigenschappen van de digitale dubbel. Eigenschappen worden behandeld als optioneel en kunnen later worden ingesteld, maar houd er rekening mee dat ze pas worden weergegeven als onderdeel van een dubbel als ze zijn ingesteld.
- Onderdelen (initialisatie vereist als ze aanwezig zijn op een dubbel): Als uw tweeling onderdelen bevat, moeten deze worden geïnitialiseerd wanneer de dubbel wordt gemaakt. Ze kunnen lege objecten zijn, maar de onderdelen zelf moeten bestaan.
Het model en eventuele initiële eigenschapswaarden worden verstrekt via de initData parameter. Dit is een JSON-tekenreeks die de relevante gegevens bevat. Ga verder naar de volgende sectie voor meer informatie over het structureren van dit object.
Tip
Nadat u een dubbel hebt gemaakt of bijgewerkt, kan er een latentie van maximaal 10 seconden zijn voordat de wijzigingen worden doorgevoerd in query's. De GetDigitalTwin API (die verderop in dit artikel wordt beschreven) ondervindt deze vertraging niet. Als u dus direct antwoord nodig hebt, gebruikt u de API-aanroep in plaats van query's uit te voeren om uw zojuist gemaakte tweelingen te zien.
Model en eigenschappen initialiseren
U kunt de eigenschappen van een dubbel initialiseren op het moment dat de dubbel wordt gemaakt.
De API voor het maken van dubbels accepteert een object dat wordt geserialiseerd in een geldige JSON-beschrijving van de eigenschappen van de dubbel. Zie Digitale dubbels en de tweelinggrafiek voor een beschrijving van de JSON-indeling voor een dubbel.
Eerst kunt u een gegevensobject maken om de tweeling en de bijbehorende eigenschapsgegevens weer te geven. U kunt handmatig een parameterobject maken of met behulp van een opgegeven helperklasse. Hier volgt een voorbeeld van elk.
Dubbels maken met handmatig gemaakte gegevens
Zonder het gebruik van aangepaste helperklassen kunt u de eigenschappen van een tweeling weergeven in een Dictionary<string, object>, waarbij de string naam van de eigenschap is en het een object is dat de eigenschap en de object bijbehorende waarde vertegenwoordigt.
// Define a custom model type for the twin to be created
internal class CustomDigitalTwin
{
[JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
public string Id { get; set; }
[JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinETag)]
public string ETag { get; set; }
[JsonPropertyName("temperature")]
public double Temperature { get; set; }
[JsonPropertyName("humidity")]
public double Humidity{ get; set; }
}
// Initialize properties and create the twin
public class TwinOperationsCreateTwin
{
public async Task CreateTwinAsync(DigitalTwinsClient client)
{
// Initialize the twin properties
var myTwin = new CustomDigitalTwin
{
Temperature = 25.0,
Humidity = 50.0,
};
// Create the twin
const string twinId = "<twin-ID>";
Response<CustomDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
Console.WriteLine($"Temperature value: {response.Value.Temperature}");
}
}
Dubbels maken met de helperklasse
Met de helperklasse kunt BasicDigitalTwin u eigenschapsvelden rechtstreeks opslaan in een dubbelobject. Mogelijk wilt u nog steeds de lijst met eigenschappen maken met behulp van een Dictionary<string, object>, die vervolgens rechtstreeks aan het dubbelobject CustomProperties kan worden toegevoegd.
string twinId = "myTwinID";
var initData = new BasicDigitalTwin
{
Id = twinId,
Metadata = { ModelId = "dtmi:example:Room;1" },
// Initialize properties
Contents =
{
{ "Temperature", 25.0 },
{ "Humidity", 50.0 },
},
};
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
Notitie
BasicDigitalTwin objecten worden geleverd met een Id veld. U kunt dit veld leeg laten, maar als u wel een id-waarde toevoegt, moet deze overeenkomen met de id-parameter die aan de CreateOrReplaceDigitalTwinAsync() aanroep is doorgegeven. Voorbeeld:
twin.Id = "myRoomId";
Dubbels bulksgewijs maken met de IMPORT Jobs-API
U kunt de IMPORT Jobs-API gebruiken om meerdere dubbels tegelijk te maken in één API-aanroep. Voor deze methode is het gebruik van Azure Blob Storage en schrijfmachtigingen in uw Azure Digital Twins-exemplaar vereist voor dubbels en bulktaken.
Tip
Met de IMPORT Jobs-API kunnen modellen en relaties ook 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 dubbels bulksgewijs wilt importeren, moet u uw tweelingen (en alle andere resources in de bulkimporttaak) structuren als een NDJSON-bestand . De Twins sectie komt na de Models sectie (en vóór de Relationships sectie). Twins die in het bestand zijn gedefinieerd, kunnen verwijzen naar modellen die zijn gedefinieerd in dit bestand of die al aanwezig zijn in het exemplaar, en ze kunnen eventueel initialisatie van de eigenschappen van de dubbel bevatten.
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:
Vervolgens kan het bestand worden gebruikt in een API-aanroep importtaken. U geeft de BLOB Storage-URL van het invoerbestand op en een nieuwe BLOB Storage-URL om aan te geven waar u het uitvoerlogboek wilt opslaan nadat de service het heeft gemaakt.
Gegevens ophalen voor een digitale dubbel
U hebt toegang tot de details van elke digitale dubbel door de GetDigitalTwin() methode als volgt aan te roepen:
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
Met deze aanroep worden dubbelgegevens geretourneerd als een sterk getypt objecttype, zoals BasicDigitalTwin. BasicDigitalTwin is een serialisatiehulpklasse die is opgenomen in de SDK, die de metagegevens en eigenschappen van de kerndubbel retourneert in vooraf geparseerde vorm. U kunt dubbelgegevens altijd deserialiseren met behulp van de JSON-bibliotheek van uw keuze, zoals System.Text.Json of Newtonsoft.Json. Voor eenvoudige toegang tot een tweeling kunnen de helperklassen dit echter handiger maken.
Notitie
BasicDigitalTwin maakt gebruik van System.Text.Json kenmerken. Als u wilt gebruiken BasicDigitalTwin met uw DigitalTwinsClient, moet u de client initialiseren met de standaardconstructor of, als u de serializer-optie wilt aanpassen, de JsonObjectSerializer gebruiken.
De BasicDigitalTwin helperklasse biedt u ook toegang tot eigenschappen die zijn gedefinieerd op de dubbel, via een Dictionary<string, object>. Als u eigenschappen van de dubbel wilt weergeven, kunt u het volgende gebruiken:
BasicDigitalTwin twin;
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
foreach (string prop in twin.Contents.Keys)
{
if (twin.Contents.TryGetValue(prop, out object value))
Console.WriteLine($"Property '{prop}': {value}");
}
Alleen eigenschappen die ten minste één keer zijn ingesteld, worden geretourneerd wanneer u een dubbel met de GetDigitalTwin() methode ophaalt.
Tip
Het displayName voor een dubbel maakt deel uit van de metagegevens van het model, dus deze wordt niet weergegeven wanneer er gegevens voor het dubbelexemplaren worden opgehaald. Als u deze waarde wilt zien, kunt u deze ophalen uit het model.
Als u meerdere dubbels wilt ophalen met behulp van één API-aanroep, raadpleegt u de query-API-voorbeelden in Query the twin graph.
Overweeg het volgende model (geschreven in Digital Twins Definition Language (DTDL)) dat een maan definieert:
{
"@id": "dtmi:example:Moon;1",
"@type": "Interface",
"@context": "dtmi:dtdl:context;3",
"contents": [
{
"@type": "Property",
"name": "radius",
"schema": "double",
"writable": true
},
{
"@type": "Property",
"name": "mass",
"schema": "double",
"writable": true
}
]
}
Het resultaat van het aanroepen object result = await client.GetDigitalTwinAsync("my-moon"); van een maantypedubbel kan er als volgt uitzien:
{
"$dtId": "myMoon-001",
"$etag": "W/\"e59ce8f5-03c0-4356-aea9-249ecbdc07f9\"",
"radius": 1737.1,
"mass": 0.0734,
"$metadata": {
"$model": "dtmi:example:Moon;1",
"radius": {
"lastUpdateTime": "2022-12-06T20:00:32.8209188Z"
},
"mass": {
"lastUpdateTime": "2022-12-04T12:04:43.3859361Z"
}
}
}
De gedefinieerde eigenschappen van de digitale dubbel worden geretourneerd als eigenschappen op het hoogste niveau van de digitale dubbel. Metagegevens of systeemgegevens die geen deel uitmaken van de DTDL-definitie, worden geretourneerd met een $ voorvoegsel. Metagegevenseigenschappen bevatten de volgende waarden:
$dtId: De id van de digitale dubbel in dit Azure Digital Twins-exemplaar$etag: Een standaard HTTP-veld dat is toegewezen door de webserver. Dit wordt bijgewerkt naar een nieuwe waarde telkens wanneer de tweeling wordt bijgewerkt. Dit kan handig zijn om te bepalen of de gegevens van de tweeling sinds een vorige controle op de server zijn bijgewerkt. U kunt updatesIf-Matchen verwijderingen uitvoeren die alleen zijn voltooid als de etag van de entiteit overeenkomt met de opgegeven etag. Zie de documentatie voor DigitalTwins Update en DigitalTwins Delete voor meer informatie over deze bewerkingen.$metadata: Een set metagegevenseigenschappen die het volgende kunnen bevatten:$model, de DTMI van het model van de digitale dubbel.lastUpdateTimevoor dubbeleigenschappen. Dit is een tijdstempel die de datum en tijd aangeeft waarop azure Digital Twins het bericht voor het bijwerken van de eigenschap heeft verwerktsourceTimevoor dubbeleigenschappen. Dit is een optionele, beschrijfbare eigenschap die de tijdstempel vertegenwoordigt toen de eigenschapsupdate werd waargenomen in de echte wereld.
Meer informatie over de velden in een digitale dubbel in JSON-indeling voor digitale dubbels. Meer informatie over de serialisatiehulpklassen, zoals BasicDigitalTwin in Azure Digital Twins-API's en SDK's.
Alle digitale dubbels weergeven
Als u alle digitale dubbels in uw exemplaar wilt weergeven, gebruikt u een query. U kunt een query uitvoeren met de query-API's of de CLI-opdrachten.
Hier volgt de hoofdtekst van de basisquery die een lijst met alle digitale dubbels in het exemplaar retourneert:
SELECT * FROM DIGITALTWINS
Een digital twin bijwerken
Als u eigenschappen van een digitale dubbel wilt bijwerken, schrijft u de informatie die u wilt vervangen in JSON Patch-indeling . Zie de bewerkingen voor JSON Patch voor een volledige lijst met JSON-patchbewerkingen die kunnen worden gebruikt, waaronder replaceen addremove.
Nadat u het JSON Patch-document met updategegevens hebt gemaakt, geeft u het document door aan de UpdateDigitalTwin() methode:
await client.UpdateDigitalTwinAsync(twinId, updateTwinData);
Eén patch-aanroep kan zoveel eigenschappen op één dubbel bijwerken als u wilt (zelfs allemaal). Als u eigenschappen voor meerdere dubbels moet bijwerken, hebt u een afzonderlijke aanroep voor elke tweeling nodig.
Tip
Nadat u een dubbel hebt gemaakt of bijgewerkt, kan er een latentie van maximaal 10 seconden zijn voordat de wijzigingen worden doorgevoerd in query's. De GetDigitalTwin API (eerder in dit artikel beschreven) ondervindt deze vertraging niet. Gebruik daarom de API-aanroep in plaats van query's uit te voeren om uw zojuist bijgewerkte tweelingen te zien als u een direct antwoord nodig hebt.
Hier volgt een voorbeeld van JSON Patch-code. In dit document worden de massa - en radius-eigenschapswaarden van de digitale dubbel waarop deze wordt toegepast, vervangen. In dit voorbeeld ziet u de JSON Patch-bewerking replace , die de waarde van een bestaande eigenschap vervangt.
[
{
"op": "replace",
"path": "/mass",
"value": 0.0799
},
{
"op": "replace",
"path": "/radius",
"value": 0.800
}
]
Wanneer u een dubbel bijwerkt vanuit een codeproject met behulp van de .NET SDK, kunt u JSON-patches maken met behulp van de JsonPatchDocument van de Azure .NET SDK. Hier volgt een voorbeeld van het maken van een JSON Patch-document en het gebruik UpdateDigitalTwin() in projectcode.
var updateTwinData = new JsonPatchDocument();
updateTwinData.AppendAdd("/Temperature", 25.0);
updateTwinData.AppendAdd("/myComponent/Property", "Hello");
// Un-set a property
updateTwinData.AppendRemove("/Humidity");
await client.UpdateDigitalTwinAsync("myTwin", updateTwinData).ConfigureAwait(false);
Tip
U kunt brontijdstempels op uw digitale dubbels onderhouden door het $metadata.<property-name>.sourceTime veld bij te werken met het proces dat in deze sectie wordt beschreven. Zie de JSON-indeling voor digitale dubbels voor meer informatie over dit veld en andere velden die beschrijfbaar zijn voor digitale dubbels.
Subeigenschappen in digitale dubbelonderdelen bijwerken
Denk eraan dat een model onderdelen kan bevatten, zodat het kan bestaan uit andere modellen.
Als u eigenschappen in de onderdelen van een digitale dubbel wilt patchen, kunt u de padsyntaxis in JSON Patch gebruiken:
[
{
"op": "replace",
"path": "/mycomponentname/mass",
"value": 0.0799
}
]
Subeigenschappen bijwerken in objecttype-eigenschappen
Modellen kunnen eigenschappen bevatten van een objecttype. Deze objecten hebben mogelijk hun eigen eigenschappen en mogelijk wilt u een van deze subeigenschappen bijwerken die behoren tot de eigenschap objecttype. Dit proces is vergelijkbaar met het proces voor het bijwerken van subeigenschappen in onderdelen, maar vereist mogelijk enkele extra stappen.
Overweeg een model met een objecttype-eigenschap, ObjectProperty. ObjectProperty heeft een tekenreekseigenschap met de naam StringSubProperty.
Wanneer een dubbel wordt gemaakt met behulp van dit model, is het niet nodig om op dat moment een ObjectProperty instantie te maken. Als de objecteigenschap niet wordt geïnstantieerd tijdens het maken van een dubbel, is er geen standaardpad gemaakt voor toegang ObjectProperty en het bijbehorende StringSubProperty pad voor een patchbewerking. U moet het pad aan ObjectProperty uzelf toevoegen voordat u de eigenschappen ervan kunt bijwerken.
Dit kan worden gedaan met een JSON Patch-bewerking add , zoals deze:
[
{
"op": "add",
"path": "/ObjectProperty",
"value": {"StringSubProperty":"<string-value>"}
}
]
Notitie
Als ObjectProperty er meer dan één eigenschap is, moet u deze allemaal opnemen in het value veld van deze bewerking, zelfs als u slechts één eigenschap bijwerkt:
... "value": {"StringSubProperty":"<string-value>", "Property2":"<property2-value>", ...}
Nadat dit eenmaal is gebeurd, bestaat er een pad dat StringSubProperty moet worden gemaakt en kan het rechtstreeks vanaf nu worden bijgewerkt met een typische replace bewerking:
[
{
"op": "replace",
"path": "/ObjectProperty/StringSubProperty",
"value": "<string-value>"
}
]
Hoewel de eerste stap niet nodig is in gevallen waarin ObjectProperty een exemplaar werd gemaakt toen de dubbel werd gemaakt, is het raadzaam deze telkens te gebruiken wanneer u een subeigenschap voor het eerst bijwerkt, omdat u mogelijk niet altijd zeker weet of de objecteigenschap in eerste instantie is geïnstantieerd of niet.
Het model van een digitale dubbel bijwerken
De UpdateDigitalTwin() functie kan ook worden gebruikt om een digitale dubbel naar een ander model te migreren.
Denk bijvoorbeeld aan het volgende JSON Patch-document dat het metagegevensveld $model van de digitale dubbel vervangt:
[
{
"op": "replace",
"path": "/$metadata/$model",
"value": "dtmi:example:foo;1"
}
]
Deze bewerking slaagt alleen als de digitale dubbel die door de patch wordt gewijzigd, voldoet aan het nieuwe model.
Kijk een naar het volgende voorbeeld:
- Stel je een digitale dubbel voor met een model van foo_old. foo_old definieert een vereiste eigenschapsmassa.
- Het nieuwe model foo_new definieert een eigenschapsmassa en voegt een nieuwe vereiste eigenschapstemperatuur toe.
- Na de patch moet de digitale dubbel zowel een massa- als temperatuureigenschap hebben.
De patch voor deze situatie moet zowel het model als de temperatuureigenschap van de dubbel bijwerken, zoals:
[
{
"op": "replace",
"path": "/$metadata/$model",
"value": "dtmi:example:foo_new;1"
},
{
"op": "add",
"path": "/temperature",
"value": 60
}
]
De sourceTime van een eigenschap bijwerken
U kunt eventueel besluiten om het sourceTime veld voor dubbeleigenschappen te gebruiken om tijdstempels vast te leggen voor wanneer eigenschapsupdates worden waargenomen in de echte wereld. Azure Digital Twins biedt systeemeigen ondersteuning sourceTime voor de metagegevens voor elke dubbeleigenschap. De sourceTime waarde moet voldoen aan de ISO 8601-datum- en tijdnotatie. Zie de JSON-indeling voor digitale dubbels voor meer informatie over dit veld en andere velden op digitale dubbels.
De minimaal stabiele REST API-versie ter ondersteuning van dit veld is de versie 2022-05-31 . Als u met dit veld wilt werken met behulp van de Azure Digital Twins SDK's, raden we u aan de nieuwste versie van de SDK te gebruiken om ervoor te zorgen dat dit veld is opgenomen.
Hier volgt een voorbeeld van een JSON Patch-document dat zowel de waarde als het sourceTime veld van een Temperature eigenschap bijwerkt:
[
{
"op": "replace",
"path": "/Temperature",
"value": "22.3"
},
{
"op": "replace",
"path": "/$metadata/Temperature/sourceTime",
"value": "2021-11-30T18:47:53.7648958Z"
}
]
Als u het sourceTime veld wilt bijwerken op een eigenschap die deel uitmaakt van een onderdeel, neemt u het onderdeel aan het begin van het pad op. In het bovenstaande voorbeeld doet u dit door de padwaarde te wijzigen van /$metadata/Temperature/sourceTime in myComponent/$metadata/Temperature/sourceTime.
Notitie
Als u zowel de als de sourceTime waarde voor een eigenschap bijwerkt en vervolgens alleen de waarde van de eigenschap later bijwerkt, blijft de sourceTime tijdstempel van de eerste update behouden.
Conflicterende update-aanroepen verwerken
Azure Digital Twins zorgt ervoor dat alle binnenkomende aanvragen na elkaar worden verwerkt. Dit betekent dat zelfs als meerdere functies tegelijkertijd dezelfde eigenschap op een dubbel proberen bij te werken, u geen expliciete vergrendelingscode hoeft te schrijven om het conflict af te handelen.
Dit gedrag is per dubbel.
Stel u een scenario voor waarin deze drie aanroepen tegelijkertijd binnenkomen:
- Eigenschap A schrijven op Twin1
- Eigenschap B schrijven op Twin1
- Eigenschap A schrijven op Twin2
De twee aanroepen die Twin1 wijzigen, worden één na elkaar uitgevoerd en er worden berichten gegenereerd voor elke wijziging. De aanroep voor het wijzigen van Twin2 kan gelijktijdig zonder conflict worden uitgevoerd zodra deze binnenkomt.
Een digitale dubbel verwijderen
U kunt dubbels verwijderen met behulp van de DeleteDigitalTwin() methode. U kunt echter alleen een dubbel verwijderen wanneer deze geen relaties meer heeft. Verwijder dus eerst de binnenkomende en uitgaande relaties van de dubbel.
Hier volgt een voorbeeld van de code om tweelingen en hun relaties te verwijderen. De DeleteDigitalTwin SDK-aanroep is gemarkeerd om te verduidelijken waar deze zich in de bredere voorbeeldcontext bevindt.
private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
{
await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
try
{
await client.DeleteDigitalTwinAsync(twinId);
Console.WriteLine("Twin deleted successfully");
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error:{ex.Message}");
}
}
private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
// Find the relationships for the twin
try
{
// GetRelationshipsAsync will throw an error if a problem occurs
AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);
await foreach (BasicRelationship rel in rels)
{
await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
}
}
private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
// Find the relationships for the twin
try
{
// GetRelationshipsAsync will throw an error if a problem occurs
AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);
await foreach (IncomingRelationship incomingRel in incomingRels)
{
await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
}
}
Alle digitale dubbels verwijderen
Voor een voorbeeld van hoe u alle dubbels tegelijk verwijdert, downloadt u de voorbeeld-app die wordt gebruikt in de basisbeginselen verkennen met een voorbeeldclient-app. Het bestand CommandLoop.cs doet dit in een CommandDeleteAllTwins() functie.
Notitie
Als u alle modellen, tweelingen en relaties in een exemplaar tegelijk wilt verwijderen, gebruikt u de API Taken verwijderen.
Voorbeeld van runnable digital twin-code
U kunt het uitvoerbare codevoorbeeld hieronder gebruiken om een dubbel te maken, de details ervan bij te werken en de tweeling te verwijderen.
Voorbeeldprojectbestanden instellen
Het codefragment maakt gebruik van een voorbeeldmodeldefinitie, Room.json. Als u het modelbestand wilt downloaden zodat u het in uw code kunt gebruiken, gebruikt u deze koppeling om rechtstreeks naar het bestand in GitHub te gaan. Klik vervolgens met de rechtermuisknop op een willekeurige plaats op het scherm, selecteer Opslaan als in het snelmenu van uw browser en gebruik het venster Opslaan als om het bestand op te slaan als Room.json.
Maak vervolgens een nieuw console-app-project in Visual Studio of uw gewenste editor.
Kopieer vervolgens de volgende code van het uitvoerbare voorbeeld naar uw project:
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Azure;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using System.IO;
namespace DigitalTwins_Samples
{
class TwinOperationsSample
{
public static async Task Main(string[] args)
{
Console.WriteLine("Hello World!");
// Create the Azure Digital Twins client for API calls
string adtInstanceUrl = "https://<your-instance-hostname>";
var credentials = new DefaultAzureCredential();
var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credentials);
Console.WriteLine($"Service client created – ready to go");
// Upload models
Console.WriteLine($"Upload a model");
string dtdl = File.ReadAllText("<path-to>/Room.json");
var models = new List<string> { dtdl };
// Upload the model to the service
await client.CreateModelsAsync(models);
// Create new digital twin
// <CreateTwin_withHelper>
string twinId = "myTwinID";
var initData = new BasicDigitalTwin
{
Id = twinId,
Metadata = { ModelId = "dtmi:example:Room;1" },
// Initialize properties
Contents =
{
{ "Temperature", 25.0 },
{ "Humidity", 50.0 },
},
};
// <CreateTwinCall>
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
// </CreateTwinCall>
// </CreateTwin_withHelper>
Console.WriteLine("Twin created successfully");
//Print twin
Console.WriteLine("--- Printing twin details:");
await CustomMethod_FetchAndPrintTwinAsync(twinId, client);
Console.WriteLine("--------");
//Update twin data
var updateTwinData = new JsonPatchDocument();
updateTwinData.AppendAdd("/Temperature", 30.0);
// <UpdateTwinCall>
await client.UpdateDigitalTwinAsync(twinId, updateTwinData);
// </UpdateTwinCall>
Console.WriteLine("Twin properties updated");
Console.WriteLine();
//Print twin again
Console.WriteLine("--- Printing twin details (after update):");
await CustomMethod_FetchAndPrintTwinAsync(twinId, client);
Console.WriteLine("--------");
Console.WriteLine();
//Delete twin
await CustomMethod_DeleteTwinAsync(client, twinId);
}
private static async Task<BasicDigitalTwin> CustomMethod_FetchAndPrintTwinAsync(string twinId, DigitalTwinsClient client)
{
// <GetTwin>
BasicDigitalTwin twin;
// <GetTwinCall>
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
// </GetTwinCall>
Console.WriteLine($"Model id: {twin.Metadata.ModelId}");
foreach (string prop in twin.Contents.Keys)
{
if (twin.Contents.TryGetValue(prop, out object value))
Console.WriteLine($"Property '{prop}': {value}");
}
// </GetTwin>
return twin;
}
// <DeleteTwin>
private static async Task CustomMethod_DeleteTwinAsync(DigitalTwinsClient client, string twinId)
{
await CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(client, twinId);
await CustomMethod_FindAndDeleteIncomingRelationshipsAsync(client, twinId);
try
{
await client.DeleteDigitalTwinAsync(twinId);
Console.WriteLine("Twin deleted successfully");
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error:{ex.Message}");
}
}
private static async Task CustomMethod_FindAndDeleteOutgoingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
// Find the relationships for the twin
try
{
// GetRelationshipsAsync will throw an error if a problem occurs
AsyncPageable<BasicRelationship> rels = client.GetRelationshipsAsync<BasicRelationship>(dtId);
await foreach (BasicRelationship rel in rels)
{
await client.DeleteRelationshipAsync(dtId, rel.Id).ConfigureAwait(false);
Console.WriteLine($"Deleted relationship {rel.Id} from {dtId}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting relationships for {dtId} due to {ex.Message}");
}
}
private static async Task CustomMethod_FindAndDeleteIncomingRelationshipsAsync(DigitalTwinsClient client, string dtId)
{
// Find the relationships for the twin
try
{
// GetRelationshipsAsync will throw an error if a problem occurs
AsyncPageable<IncomingRelationship> incomingRels = client.GetIncomingRelationshipsAsync(dtId);
await foreach (IncomingRelationship incomingRel in incomingRels)
{
await client.DeleteRelationshipAsync(incomingRel.SourceId, incomingRel.RelationshipId).ConfigureAwait(false);
Console.WriteLine($"Deleted incoming relationship {incomingRel.RelationshipId} from {dtId}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"*** Error {ex.Status}/{ex.ErrorCode} retrieving or deleting incoming relationships for {dtId} due to {ex.Message}");
}
}
// </DeleteTwin>
}
}
Notitie
Er is momenteel een bekend probleem dat van invloed is op de DefaultAzureCredential wrapper-klasse die kan leiden tot een fout tijdens het verifiëren. Als u dit probleem ondervindt, kunt u proberen te instantiëren DefaultAzureCredential met de volgende optionele parameter om dit op te lossen: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });
Zie bekende problemen met Azure Digital Twins voor meer informatie over dit probleem.
Project configureren
Voer vervolgens de volgende stappen uit om uw projectcode te configureren:
Voeg het Room.json-bestand toe dat u eerder hebt gedownload aan uw project en vervang de
<path-to>tijdelijke aanduiding in de code om uw programma te laten weten waar u het kunt vinden.Vervang de tijdelijke aanduiding
<your-instance-hostname>door de hostnaam van uw Azure Digital Twins-exemplaar.Voeg twee afhankelijkheden toe aan uw project die nodig zijn om met Azure Digital Twins te werken. Het eerste is het pakket voor de Azure Digital Twins SDK voor .NET en de tweede biedt hulpprogramma's voor verificatie met Azure.
dotnet add package Azure.DigitalTwins.Core dotnet add package Azure.Identity
U moet ook lokale referenties instellen als u het voorbeeld rechtstreeks wilt uitvoeren. In de volgende sectie wordt dit beschreven.
Lokale Azure-referenties instellen
In dit voorbeeld wordt gebruikgemaakt van DefaultAzureCredential (onderdeel van de Azure.Identity-bibliotheek) om gebruikers te verifiëren bij de Azure Digital Twins-instantie wanneer u deze uitvoert op uw lokale machine. Voor meer informatie over verschillende manieren waarop een client-app kan verifiëren met Azure Digital Twins, raadpleegt u Verificatiecode voor app schrijven.
Met DefaultAzureCredential zoekt het voorbeeld naar referenties in uw lokale omgeving, zoals een Azure-aanmelding in een lokale Azure-CLI of in Visual Studio of Visual Studio Code. Daarom moet u zich lokaal aanmelden bij Azure via een van deze mechanismen om referenties in te stellen voor het voorbeeld.
Als u Visual Studio of Visual Studio Code gebruikt om codevoorbeelden uit te voeren, moet u ervoor zorgen dat u bent aangemeld bij die editor met dezelfde Azure-referenties die u wilt gebruiken voor toegang tot uw Azure Digital Twins-exemplaar. Als u een lokaal CLI-venster gebruikt, voert u de az login opdracht uit om u aan te melden bij uw Azure-account. Daarna moet u, wanneer u het codevoorbeeld uitvoert, automatisch worden geverifieerd.
De voorbeeldtoepassing uitvoeren
Nu de installatie is voltooid, kunt u het voorbeeldcodeproject uitvoeren.
Dit is de console-uitvoer van het bovenstaande programma:
Volgende stappen
Lees hoe u relaties tussen uw digitale dubbels maakt en beheert: