Správa digitálních dvojčat
Entity ve vašem prostředí jsou reprezentovány digitálními dvojčaty. Správa digitálních dvojčat může zahrnovat vytváření, úpravy a odebrání.
Tento článek se zaměřuje na správu digitálních dvojčat; pokud chcete pracovat s relacemi a grafem dvojčete jako celku, přečtěte si téma Správa grafu dvojčete a relací.
Tip
Všechny funkce sady SDK jsou synchronní a asynchronní verze.
Požadavky
Pokud chcete pracovat se službou Azure Digital Twins v tomto článku, budete potřebovat instanci služby Azure Digital Twins a požadovaná oprávnění k jeho použití. Pokud už máte nastavenou instanci Služby Azure Digital Twins, můžete tuto instanci použít a přeskočit k další části. V opačném případě postupujte podle pokynů v části Nastavení instance a ověřování. Pokyny obsahují informace, které vám pomůžou ověřit, že jste každý krok úspěšně dokončili.
Po nastavení instance si poznamenejte název hostitele instance. Název hostitele najdete na webu Azure Portal.
Vývojářská rozhraní
Tento článek popisuje, jak provádět různé operace správy pomocí sady .NET (C#) SDK. Stejná volání správy můžete také vytvořit pomocí jiných jazykových sad SDK popsaných v rozhraních API a sadách SDK služby Azure Digital Twins.
Mezi další vývojářská rozhraní, která lze použít k dokončení těchto operací, patří:
Vizualizace
Azure Digital Twins Explorer je vizuální nástroj pro zkoumání dat v grafu Služby Azure Digital Twins. Průzkumníka můžete použít k zobrazení, dotazování a úpravám modelů, dvojčat a relací.
Další informace o nástroji Azure Digital Twins Explorer najdete v Průzkumníku služby Azure Digital Twins. Podrobný postup použití jeho funkcí najdete v tématu Použití Průzkumníka služby Azure Digital Twins.
Vizualizace vypadá takto:
Vytvoření digitálního dvojčete
K vytvoření dvojčete použijete metodu CreateOrReplaceDigitalTwinAsync() na klientovi služby takto:
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinId, initData);
Pokud chcete vytvořit digitální dvojče, musíte zadat:
- Hodnota ID, kterou chcete přiřadit k digitálnímu dvojčeti (definujete toto ID při vytvoření dvojčete)
- Model, který chcete použít
- Jakákoli požadovaná inicializace dat dvojčat, včetně...
- Vlastnosti (inicializace volitelné): Pokud chcete, můžete nastavit počáteční hodnoty pro vlastnosti digitálního dvojčete. Vlastnosti jsou považovány za volitelné a je možné je nastavit později, ale všimněte si, že se nezobrazí jako součást dvojčete, dokud nebudou nastaveny.
- Komponenty (inicializace nutná, pokud jsou přítomné na dvojčeti): Pokud dvojče obsahuje nějaké komponenty, musí se inicializovat při vytvoření dvojčete. Mohou být prázdné objekty, ale samotné komponenty musí existovat.
Model a všechny počáteční hodnoty vlastností jsou poskytovány prostřednictvím parametru initData , což je řetězec JSON obsahující relevantní data. Další informace o strukturování tohoto objektu najdete v další části.
Tip
Po vytvoření nebo aktualizaci dvojčete může docházet k latenci až 10 sekund, než se změny projeví v dotazech. Rozhraní GetDigitalTwin API (popsané dále v tomto článku) toto zpoždění neprovádí, takže pokud potřebujete okamžitou odpověď, použijte místo dotazování volání rozhraní API k zobrazení nově vytvořených dvojčat.
Inicializace modelu a vlastností
Vlastnosti dvojčete můžete inicializovat v okamžiku vytvoření dvojčete.
Rozhraní API pro vytvoření dvojčete přijímá objekt serializovaný do platného popisu JSON vlastností dvojčete. Popis formátu JSON pro dvojčete najdete v tématu Digitální dvojčata a graf dvojčat.
Nejprve můžete vytvořit datový objekt představující dvojče a jeho data vlastností. Objekt parametru můžete vytvořit buď ručně, nebo pomocí poskytnuté pomocné třídy. Tady je příklad každého.
Vytvoření dvojčat pomocí ručně vytvořených dat
Bez použití jakýchkoli vlastních pomocných tříd můžete reprezentovat vlastnosti dvojčete v objektu Dictionary<string, object>, kde string je název vlastnosti a object je objekt představující vlastnost a její hodnota.
// 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}");
}
}
Vytvoření dvojčat pomocí pomocné třídy
Pomocná třída BasicDigitalTwin umožňuje ukládat pole vlastností přímo do objektu dvojčete. Přesto můžete chtít vytvořit seznam vlastností pomocí Dictionary<string, object>objektu dvojčete, který pak můžete přidat přímo do objektu CustomProperties dvojčete.
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);
Poznámka:
BasicDigitalTwin objekty jsou součástí Id pole. Toto pole můžete ponechat prázdné, ale pokud přidáte hodnotu ID, musí odpovídat parametru ID předaným volání CreateOrReplaceDigitalTwinAsync() . Příklad:
twin.Id = "myRoomId";
Hromadné vytváření dvojčat pomocí rozhraní API pro import úloh
Rozhraní API pro import úloh můžete použít k vytvoření mnoha dvojčat najednou v jednom volání rozhraní API. Tato metoda vyžaduje použití služby Azure Blob Storage a oprávnění k zápisu v instanci služby Azure Digital Twins pro dvojčata a hromadné úlohy.
Tip
Rozhraní API pro úlohy importu také umožňuje importovat modely a relace ve stejném volání, aby se vytvořily všechny části grafu najednou. Další informace o tomto procesu najdete v tématu Hromadné nahrávání modelů, dvojčat a relací pomocí rozhraní API importu úloh.
Pokud chcete dvojčata importovat hromadně, musíte dvojčata strukturovat (a všechny další prostředky zahrnuté v úloze hromadného importu) jako soubor NDJSON . Oddíl Twins následuje za Models oddílem (a před oddílem Relationships ). Dvojčata definovaná v souboru mohou odkazovat na modely, které jsou definovány buď v tomto souboru, nebo již existují v instanci, a mohou volitelně zahrnovat inicializaci vlastností dvojčete.
Ukázkový soubor importu a ukázkový projekt pro vytvoření těchto souborů si můžete prohlédnout v úvodu k rozhraní API importu úloh.
Dále je potřeba soubor nahrát do doplňovacího objektu blob ve službě Azure Blob Storage. Pokyny k vytvoření kontejneru úložiště Azure najdete v tématu Vytvoření kontejneru. Pak soubor nahrajte pomocí preferované metody nahrání (některé možnosti jsou příkaz AzCopy, Azure CLI nebo Azure Portal).
Jakmile se soubor NDJSON nahraje do kontejneru, získejte jeho adresu URL v kontejneru objektů blob. Tuto hodnotu použijete později v textu volání rozhraní API hromadného importu.
Tady je snímek obrazovky znázorňující hodnotu adresy URL souboru objektu blob na webu Azure Portal:
Pak se soubor dá použít ve volání rozhraní API importu úloh. Zadáte adresu URL úložiště objektů blob vstupního souboru a novou adresu URL úložiště objektů blob, která bude indikovat, kam má být výstupní protokol uložen po vytvoření služby.
Získání dat pro digitální dvojče
K podrobnostem jakéhokoli digitálního dvojčete se dostanete voláním GetDigitalTwin() metody takto:
Response<BasicDigitalTwin> twinResponse = await client.GetDigitalTwinAsync<BasicDigitalTwin>(twinId);
twin = twinResponse.Value;
Toto volání vrátí data dvojčete jako typ objektu silného typu, například BasicDigitalTwin. BasicDigitalTwin je pomocná třída serializace zahrnutá v sadě SDK, která vrací základní metadata a vlastnosti dvojčete v předem oddělené podobě. Data dvojčete můžete vždy deserializovat pomocí knihovny JSON podle vašeho výběru, například System.Text.Json nebo Newtonsoft.Json. Pro základní přístup k dvojčeti však pomocné třídy mohou usnadnit tuto možnost.
Poznámka:
BasicDigitalTwin používá System.Text.Json atributy. Chcete-li použít BasicDigitalTwin s digitalTwinsClient, musíte buď inicializovat klienta s výchozím konstruktorem, nebo pokud chcete přizpůsobit možnost serializátoru , použijte JsonObjectSerializer.
Pomocná BasicDigitalTwin třída také poskytuje přístup k vlastnostem definovaným ve dvojčeti prostřednictvím Dictionary<string, object>. Pokud chcete zobrazit seznam vlastností dvojčete, můžete použít:
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}");
}
Při načtení dvojčete pomocí GetDigitalTwin() metody se vrátí pouze vlastnosti, které byly nastaveny alespoň jednou.
Tip
Dvojče displayName je součástí jeho metadat modelu, takže se při získávání dat pro instanci dvojčete nezobrazí. Pokud chcete zobrazit tuto hodnotu, můžete ji načíst z modelu.
Pokud chcete načíst více dvojčat pomocí jednoho volání rozhraní API, podívejte se na příklady rozhraní API pro dotazy v grafu dvojčete.
Představte si následující model (napsaný v jazyce DTDL (Digital Twins Definition Language), který definuje Měsíc:
{
"@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
}
]
}
Výsledek volání object result = await client.GetDigitalTwinAsync("my-moon"); dvojčete typu Měsíc může vypadat takto:
{
"$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"
}
}
}
Definované vlastnosti digitálního dvojčete se vrátí jako vlastnosti nejvyšší úrovně digitálního dvojčete. Metadata nebo systémové informace, které nejsou součástí definice DTDL, se vrátí s předponou $ . Vlastnosti metadat zahrnují následující hodnoty:
$dtId: ID digitálního dvojčete v této instanci Služby Azure Digital Twins$etag: Standardní pole HTTP přiřazené webovým serverem. Aktualizuje se na novou hodnotu při každé aktualizaci dvojčete, což může být užitečné k určení, jestli se data dvojčete aktualizovala na serveru od předchozí kontroly. Můžete použítIf-Matchk provádění aktualizací a odstraňování, které se dokončí pouze v případě, že etag entity odpovídá zadané etag. Další informace o těchto operacích najdete v dokumentaci k řešení DigitalTwins Update a DigitalTwins Delete.$metadata: Sada vlastností metadat, které můžou zahrnovat následující:$model, DTMI modelu digitálního dvojčete.lastUpdateTimepro vlastnosti dvojčete. Toto je časové razítko označující datum a čas, kdy služba Azure Digital Twins zpracovala zprávu o aktualizaci vlastnosti.sourceTimepro vlastnosti dvojčete. Jedná se o volitelnou zapisovatelnou vlastnost představující časové razítko při aktualizaci vlastnosti v reálném světě.
Další informace o polích obsažených ve formátu JSON digitálního dvojčete si můžete přečíst. Další informace o pomocných třídách serializace, jako jsou BasicDigitalTwin v rozhraních API a sadách SDK služby Azure Digital Twins.
Zobrazit všechna digitální dvojčata
Pokud chcete zobrazit všechna digitální dvojčata ve vaší instanci, použijte dotaz. Dotaz můžete spustit pomocí rozhraní API dotazů nebo příkazů rozhraní příkazového řádku.
Tady je text základního dotazu, který vrátí seznam všech digitálních dvojčat v instanci:
SELECT * FROM DIGITALTWINS
Aktualizace digitálního dvojčete
Pokud chcete aktualizovat vlastnosti digitálního dvojčete, napište informace, které chcete nahradit ve formátu opravy JSON. Úplný seznam operací oprav JSON, které lze použít, včetně replaceadd a remove, naleznete v operacích pro opravu JSON.
Po vytvoření dokumentu JSON Patch obsahujícího informace o aktualizaci předejte dokument do UpdateDigitalTwin() metody:
await client.UpdateDigitalTwinAsync(twinId, updateTwinData);
Jedno volání opravy může aktualizovat tolik vlastností na jednom dvojčeti, kolik potřebujete (dokonce i všechny). Pokud potřebujete aktualizovat vlastnosti napříč více dvojčaty, potřebujete samostatné volání aktualizace pro každé dvojče.
Tip
Po vytvoření nebo aktualizaci dvojčete může docházet k latenci až 10 sekund, než se změny projeví v dotazech. Rozhraní GetDigitalTwin API (popsané výše v tomto článku) nemá toto zpoždění, takže pokud potřebujete okamžitou odpověď, použijte volání rozhraní API místo dotazování na nově aktualizovaná dvojčata.
Tady je příklad kódu opravy JSON. Tento dokument nahrazuje hodnoty vlastností hmotnosti a poloměru digitálního dvojčete, na které se vztahuje. Tento příklad ukazuje operaci OPRAVA replace JSON, která nahrazuje hodnotu existující vlastnosti.
[
{
"op": "replace",
"path": "/mass",
"value": 0.0799
},
{
"op": "replace",
"path": "/radius",
"value": 0.800
}
]
Při aktualizaci dvojčete z projektu kódu pomocí sady .NET SDK můžete vytvořit opravy JSON pomocí souboru JsonPatchDocument sady Azure .NET SDK. Tady je příklad vytvoření dokumentu opravy JSON a použití UpdateDigitalTwin() v kódu projektu.
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
Časové razítka zdroje můžete udržovat ve svých digitálních dvojčatech tak, že pole aktualizujete $metadata.<property-name>.sourceTime procesem popsaným v této části. Další informace o tomto poli a dalších polích, která lze zapisovat na digitální dvojčata, najdete v tématu Formát JSON digitálního dvojčete.
Aktualizace dílčích vlastností v součástech digitálního dvojčete
Vzpomeňte si, že model může obsahovat komponenty, což umožňuje jeho vytvoření z jiných modelů.
Pokud chcete opravit vlastnosti součástí digitálního dvojčete, můžete použít syntaxi cesty v opravě JSON:
[
{
"op": "replace",
"path": "/mycomponentname/mass",
"value": 0.0799
}
]
Aktualizace dílčích vlastností ve vlastnostech typu objektu
Modely můžou obsahovat vlastnosti typu objektu. Tyto objekty můžou mít vlastní vlastnosti a můžete chtít aktualizovat jednu z těchto dílčích vlastností patřících do vlastnosti typu objektu. Tento proces se podobá procesu aktualizace dílčích vlastností v součástech, ale může vyžadovat několik dalších kroků.
Zvažte model s vlastností typu objektu , ObjectProperty. ObjectProperty má řetězcovou vlastnost s názvem StringSubProperty.
Když se pomocí tohoto modelu vytvoří dvojče, není nutné vytvořit instanci v daném okamžiku ObjectProperty . Pokud během vytváření dvojčete není vytvořena instance vlastnosti objektu, neexistuje žádná výchozí cesta pro přístup ObjectProperty a její StringSubProperty operace opravy. Než budete moct aktualizovat jeho vlastnosti, musíte tuto cestu přidat sami sobě ObjectProperty .
Můžete to provést pomocí operace opravy add JSON, například takto:
[
{
"op": "add",
"path": "/ObjectProperty",
"value": {"StringSubProperty":"<string-value>"}
}
]
Poznámka:
Pokud ObjectProperty má více než jednu vlastnost, měli byste je zahrnout do value pole této operace, i když aktualizujete jenom jednu:
... "value": {"StringSubProperty":"<string-value>", "Property2":"<property2-value>", ...}
Po provedení této akce jednou existuje cesta StringSubProperty , která se dá aktualizovat přímo od této chvíle pomocí typické replace operace:
[
{
"op": "replace",
"path": "/ObjectProperty/StringSubProperty",
"value": "<string-value>"
}
]
I když první krok není nezbytný v případech, kdy ObjectProperty byla vytvořena instance dvojčete, doporučujeme ho použít při každé aktualizaci dílčí vlastnosti poprvé, protože nemusíte vždy vědět s jistotou, zda byla vlastnost objektu původně vytvořena nebo ne.
Aktualizace modelu digitálního dvojčete
Funkci UpdateDigitalTwin() lze také použít k migraci digitálního dvojčete do jiného modelu.
Představte si například následující dokument opravy JSON, který nahrazuje pole metadat $model digitálního dvojčete:
[
{
"op": "replace",
"path": "/$metadata/$model",
"value": "dtmi:example:foo;1"
}
]
Tato operace bude úspěšná pouze v případě, že digitální dvojče změněné opravou odpovídá novému modelu.
Představte si následující příklad:
- Představte si digitální dvojče s modelem foo_old. foo_old definuje požadovanou hmotnost vlastnosti.
- Nový model foo_new definuje hmotnost vlastnosti a přidá novou požadovanou teplotu vlastnosti.
- Po opravě musí digitální dvojče mít vlastnost hmotnosti i teploty.
Oprava pro tuto situaci musí aktualizovat model i vlastnost teploty dvojčete, například takto:
[
{
"op": "replace",
"path": "/$metadata/$model",
"value": "dtmi:example:foo_new;1"
},
{
"op": "add",
"path": "/temperature",
"value": 60
}
]
Aktualizace zdrojového času vlastnosti
Volitelně se můžete rozhodnout použít sourceTime pole vlastností dvojčete k zaznamenávání časových razítek, kdy se v reálném světě zaznamenávají aktualizace vlastností. Azure Digital Twins nativně podporuje sourceTime metadata pro každou vlastnost dvojčete. Hodnota sourceTime musí být v souladu s formátem data a času ISO 8601. Další informace o tomto poli a dalších polích digitálních dvojčat najdete ve formátu JSON digitálního dvojčete.
Minimální stabilní verze rozhraní REST API pro podporu tohoto pole je verze 2022-05-31 . Pokud chcete s tímto polem pracovat pomocí sad SDK služby Azure Digital Twins, doporučujeme použít nejnovější verzi sady SDK, abyste měli jistotu, že je toto pole součástí.
Tady je příklad dokumentu Opravy JSON, který aktualizuje hodnotu i sourceTime pole Temperature vlastnosti:
[
{
"op": "replace",
"path": "/Temperature",
"value": "22.3"
},
{
"op": "replace",
"path": "/$metadata/Temperature/sourceTime",
"value": "2021-11-30T18:47:53.7648958Z"
}
]
Chcete-li aktualizovat sourceTime pole u vlastnosti, která je součástí komponenty, zahrňte komponentu na začátku cesty. V předchozím příkladu byste to udělali změnou hodnoty cesty z /$metadata/Temperature/sourceTime na myComponent/$metadata/Temperature/sourceTime.
Poznámka:
Pokud aktualizujete vlastnost sourceTime i hodnotu a později aktualizujete pouze hodnotu vlastnosti, sourceTime časové razítko z první aktualizace zůstane.
Zpracování konfliktních volání aktualizací
Azure Digital Twins zajišťuje, aby se všechny příchozí požadavky zpracovávaly po druhé. To znamená, že i když se několik funkcí pokusí aktualizovat stejnou vlastnost dvojčete současně, není nutné psát explicitní zamykání kódu pro zpracování konfliktu.
Toto chování je založené na jednotlivých dvojčatech.
Představte si například scénář, ve kterém tyto tři volání přicházejí současně:
- Write property A on Twin1
- Write property B on Twin1
- Write property A on Twin2
Dvě volání, která upravují Twin1 , se spustí jedna za druhou a pro každou změnu se vygenerují zprávy o změnách. Volání pro úpravu twin2 se dá spustit souběžně bez konfliktu, jakmile dorazí.
Odstranění digitálního dvojčete
Pomocí této metody můžete odstranit dvojčata DeleteDigitalTwin() . Dvojče však můžete odstranit pouze v případě, že už nemá žádné další relace. Proto nejprve odstraňte příchozí a odchozí relace dvojčete.
Tady je příklad kódu pro odstranění dvojčat a jejich relací. Volání DeleteDigitalTwin sady SDK je zvýrazněné, aby bylo jasné, kde spadá do širšího ukázkového kontextu.
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}");
}
}
Odstranit všechna digitální dvojčata
Příklad, jak odstranit všechna dvojčata najednou, stáhněte si ukázkovou aplikaci použitou v části Prozkoumání základů pomocí ukázkové klientské aplikace. Soubor CommandLoop.cs to dělá ve CommandDeleteAllTwins() funkci.
Poznámka:
Pokud chcete odstranit všechny modely, dvojčata a relace v instanci najednou, použijte rozhraní API pro odstranění úloh.
Ukázka kódu spustitelného digitálního dvojčete
Následující ukázku spustitelného kódu můžete použít k vytvoření dvojčete, aktualizaci jeho podrobností a odstranění dvojčete.
Nastavení ukázkových souborů projektu
Fragment kódu používá ukázkovou definici modelu Room.json. Pokud chcete stáhnout soubor modelu, abyste ho mohli použít ve svém kódu, použijte tento odkaz a přejděte přímo k souboru na GitHubu. Potom klikněte pravým tlačítkem na libovolné místo na obrazovce, v nabídce pravého kliknutí v prohlížeči vyberte Uložit jako a pomocí okna Uložit jako soubor uložte soubor jako Room.json.
Dále vytvořte nový projekt konzolové aplikace v sadě Visual Studio nebo v libovolném editoru.
Pak do projektu zkopírujte následující kód spustitelné ukázky:
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>
}
}
Poznámka:
V současné době existuje známý problém ovlivňující DefaultAzureCredential třídu obálky, která může způsobit chybu při ověřování. Pokud narazíte na tento problém, můžete zkusit vytvořit instanci DefaultAzureCredential s následujícím volitelným parametrem a vyřešit ho: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });
Další informace o tomto problému najdete v tématu Známé problémy služby Azure Digital Twins.
Konfigurace projektu
Dále proveďte následující kroky a nakonfigurujte kód projektu:
Přidejte do projektu soubor Room.json, který jste si stáhli dříve, a nahraďte
<path-to>zástupný symbol v kódu, aby program řekl, kde ho najdete.Zástupný symbol
<your-instance-hostname>nahraďte názvem hostitele instance Azure Digital Twins.Přidejte do projektu dvě závislosti, které jsou potřeba pro práci s Azure Digital Twins. První je balíček sady Azure Digital Twins SDK pro .NET a druhý poskytuje nástroje, které vám pomůžou s ověřováním v Azure.
dotnet add package Azure.DigitalTwins.Core dotnet add package Azure.Identity
Pokud chcete ukázku spustit přímo, musíte také nastavit místní přihlašovací údaje. Tato část vás provede v další části.
Nastavení místních přihlašovacích údajů Azure
Tato ukázka používá defaultAzureCredential (součást Azure.Identity knihovny) k ověřování uživatelů s instancí Služby Azure Digital Twins, když ji spustíte na místním počítači. Další informace o různých způsobech ověřování klientské aplikace pomocí služby Azure Digital Twins najdete v tématu Psaní ověřovacího kódu aplikace.
Pomocí DefaultAzureCredentialtéto ukázky vyhledáte přihlašovací údaje ve vašem místním prostředí, jako je přihlášení k Azure v místním Azure CLI nebo v sadě Visual Studio nebo Visual Studio Code. Z tohoto důvodu byste se měli k Azure přihlásit místně prostřednictvím jednoho z těchto mechanismů, abyste pro ukázku nastavili přihlašovací údaje.
Pokud ke spouštění ukázek kódu používáte Visual Studio nebo Visual Studio Code, ujistěte se, že jste k ho editoru přihlášeni pomocí stejných přihlašovacích údajů Azure, které chcete použít pro přístup k vaší instanci Azure Digital Twins. Pokud používáte místní okno rozhraní příkazového řádku, spusťte az login příkaz pro přihlášení ke svému účtu Azure. Potom byste při spuštění ukázky kódu měli být automaticky ověřeni.
Spuštění ukázky
Po dokončení instalace můžete spustit ukázkový projekt kódu.
Tady je výstup konzoly výše uvedeného programu:
Další kroky
Podívejte se, jak vytvářet a spravovat vztahy mezi digitálními dvojčaty: