Kurz: Kódování pomocí Azure Digital Twins API

Vývojáři pracující Azure Digital Twins často píšou klientské aplikace pro interakci s jejich instancí Azure Digital Twins službou. Tento kurz zaměřený na vývojáře představuje úvod do programování proti službě Azure Digital Twins pomocí sady SDK Azure Digital Twins pro .NET (C#). Provede vás podrobným psaním klientské klientské aplikace v jazyce C# a začíná od nuly.

Požadavky

Tento Azure Digital Twins kurzu používá příkazový řádek pro nastavení a práci na projektu. K procvičování cvičení můžete použít libovolný editor kódu.

Co potřebujete k zahájení:

• Libovolný editor kódu
• .NET Core 3.1 na vývojovém počítači. Tuto verzi nástroje pro různé .NET Core SDK si můžete stáhnout z .NET Core 3.1.

Příprava Azure Digital Twins instance

Pokud chcete s Azure Digital Twins v tomto článku pracovat, musíte nejprve nastavit instanci Azure Digital Twins . Potřebujete také požadovaná oprávnění k jeho použití. Pokud už máte instanci Azure Digital Twins, můžete ji použít.

Jinak postupujte podle pokynů v tématu Nastavení instance a ověřování. Pokyny obsahují informace, které vám pomůžou ověřit, že jste jednotlivé kroky úspěšně dokončili.

Po nastavení instance si poznamenejte následující hodnoty. Tyto hodnoty budete potřebovat pro připojení k instanci později:

• Název hostitele instance. Název hostitele najdete v části Azure Portal.
• Předplatné Azure, které jste použili k vytvoření instance. Bude fungovat jeho název nebo ID. Předplatné najdete na stránce Přehled vaší instance v Azure Portal .

Nastavení místních přihlašovacích údajů Azure

Tato ukázka používá DefaultAzureCredential (součást knihovny) k ověřování uživatelů pomocí Azure Digital Twins, když ji spustíte Azure.Identity na místním počítači. Další informace o různých způsobech ověřování klientských aplikací pomocí Azure Digital Twins najdete v tématu Psaní ověřovacího kódu aplikace.

V DefaultAzureCredential případě bude ukázka Hledat přihlašovací údaje v místním prostředí, jako je například přihlášení k Azure v místním rozhraní příkazového řádku Azure nebo v aplikaci Visual Studio nebo Visual Studio Code. Z tohoto důvodu byste se měli přihlásit k Azure místně prostřednictvím jednoho z těchto mechanismů a nastavit přihlašovací údaje pro ukázku.

Pokud používáte aplikaci Visual Studio nebo Visual Studio Code ke spuštění ukázky kódu, ujistěte se, že jste přihlášeni k tomuto editoru se stejnými přihlašovacími údaji Azure, které chcete použít pro přístup k instanci digitálních vláken Azure.

V opačném případě můžete nainstalovat místní rozhranípříkazového řádku Azure, spustit příkazový řádek na svém počítači a spustit az login příkaz pro přihlášení k účtu Azure. Po přihlášení si můžete při spuštění ukázky kódu automaticky přihlásit.

Nastavení projektu

Jakmile budete připraveni začít s vaší instancí Azure Digital Twins, začněte nastavovat projekt klientské aplikace.

Otevřete na svém počítači příkazový řádek nebo jiné okno konzoly a vytvořte prázdný adresář projektu, do kterého chcete během tohoto kurzu uložit svou práci. Pojmenuje adresář, který chcete (například DigitalTwinsCodeTutorial).

Přejděte do nového adresáře.

V adresáři projektu vytvořte prázdný projekt konzolové aplikace .NET. V příkazovém okně můžete spuštěním následujícího příkazu vytvořit minimální projekt C# pro konzolu:

dotnet new console

Tento příkaz vytvoří v adresáři několik souborů, včetně jednoho s názvem Program.cs, kde napíšete většinu kódu.

Nechte příkazové okno otevřené, protože ho budete dál používat v průběhu kurzu.

Dále do projektu přidejte dvě závislosti, které budou potřeba pro práci s Azure Digital Twins. První je balíček pro sadu AZURE DIGITAL TWINS SDK pro .NET, 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

Začínáme s kódem projektu

V této části začnete psát kód pro nový projekt aplikace pro práci s Azure Digital Twins. Mezi zahrnuté akce patří:

• Ověřování ve službě
• Nahrání modelu
• Zachytání chyb
• Vytváření digitálních dvojčat
• Vytváření relací
• Dotazování digitálních dvojčat

Na konci kurzu je také oddíl zobrazující kompletní kód. Tuto část můžete použít jako referenci k tomu, abyste mohli program zkontrolovat, jak budete používat.

Začněte tím, že otevřete soubor Program.cs v libovolném editoru kódu. Uvidíte minimální šablonu kódu, která vypadá nějak takhle:

Nejprve na začátek kódu přidejte několik řádků, které using načtou potřebné závislosti.

using Azure.DigitalTwins.Core;
using Azure.Identity;

Dále do tohoto souboru přidáte kód, který vyplní některé funkce.

Ověřování vůči službě

První věc, kterou vaše aplikace bude muset udělat, je ověření proti Azure Digital Twins službě. Pak můžete vytvořit třídu klienta služby pro přístup k funkcím sady SDK.

K ověření potřebujete název hostitele vaší Azure Digital Twins instance.

Do souboru Program.cs vložte následující kód pod text "Hello, World!" printout line in the Main method. Nastavte hodnotu adtInstanceUrl na název Azure Digital Twins instance.

string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-hostName>"; 

var credential = new DefaultAzureCredential();
var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
Console.WriteLine($"Service client created – ready to go");

Soubor uložte.

V příkazovém okně spusťte kód pomocí tohoto příkazu:

dotnet run

Tento příkaz obnoví závislosti při prvním spuštění a pak spustí program.

• Pokud dojde k žádné chybě, program vytiskne vytvořeného klienta služby – připraveno k provedení.
• Vzhledem k tomu, že v tomto projektu zatím není žádné zpracování chyb, v případě jakýchkoli problémů se zobrazí výjimka vyvolaná kódem.

Upload modelu

Azure Digital Twins nemá žádný vnitřní slovník domény. Typy elementů ve vašem prostředí, které můžete reprezentovat v Azure Digital Twins jsou definovány pomocí modelů. Modely jsou podobné třídám v objektově orientovaných programovacích jazycích. Poskytují uživatelem definované šablony pro digitální dvojčata, která se budou sledovat a později vytvořit instanci. Jsou napsané v jazyce ve formátu JSON s názvem Digital Twins Definition Language (DTDL).

Prvním krokem při vytváření Azure Digital Twins je definování alespoň jednoho modelu v souboru DTDL.

V adresáři, ve kterém jste vytvořili projekt, vytvořte nový soubor .json s názvem SampleModel.json. Vložte následující text souboru:

{
  "@id": "dtmi:example:SampleModel;1",
  "@type": "Interface",
  "displayName": "SampleModel",
  "contents": [
    {
      "@type": "Relationship",
      "name": "contains"
    },
    {
      "@type": "Property",
      "name": "data",
      "schema": "string"
    }
  ],
  "@context": "dtmi:dtdl:context;2"
}

Dále do souboru Program.cs přidejte další kód pro nahrání modelu, který jste vytvořili, do Azure Digital Twins instance.

Nejprve na začátek using souboru přidejte několik příkazů:

using System.Threading.Tasks;
using System.IO;
using System.Collections.Generic;
using Azure;

Dále se připravte na použití asynchronních metod v sadě SDK služby pro jazyk C#, a to změnou signatury metody tak, aby bylo Main možné asynchronní provádění.

static async Task Main(string[] args)
{

Dále přichází první část kódu, která komunikuje s Azure Digital Twins službou. Tento kód načte soubor DTDL, který jste vytvořili z disku, a pak ho nahraje do vaší Azure Digital Twins služby.

Pod autorizační kód, který jste přidali dříve, vložte následující kód.

Console.WriteLine();
Console.WriteLine($"Upload a model");
string dtdl = File.ReadAllText("SampleModel.json");
var models = new List<string> { dtdl };
// Upload the model to the service
await client.CreateModelsAsync(models);

V příkazovém okně spusťte program pomocí tohoto příkazu:

dotnet run

Ve Upload se zobrazí zpráva "Upload modelu", což značí, že tento kód byl dosažen, ale zatím není k dispozici žádný výstup, který by indikoval, jestli bylo nahrání úspěšné.

Pokud chcete přidat příkaz print zobrazující všechny modely úspěšně nahrané do instance, přidejte následující kód hned za předchozí část:

// Read a list of models back from the service
AsyncPageable<DigitalTwinsModelData> modelDataList = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in modelDataList)
{
    Console.WriteLine($"Model: {md.Id}");
}

Než program znovu spustíte a otestujte tento nový kód, vzpomeňte si, že při posledním spuštění programu jste model už nahráli. Azure Digital Twins vám nedovolí nahrát stejný model dvakrát, takže pokud se pokusíte stejný model nahrát znovu, měl by program vyvolat výjimku.

S vědomím těchto informací spusťte program znovu pomocí tohoto příkazu v příkazovém okně:

dotnet run

Program by měl vyvolat výjimku. Když se pokusíte nahrát model, který už je nahraný, služba vrátí chybu "chybný požadavek" prostřednictvím REST API. V důsledku toho klientská Azure Digital Twins SDK zase vyvolá výjimku pro každý návratový kód služby jiný než úspěšný.

V další části se budeme popovídat o výjimce, jako je tato, a o tom, jak je zpracovat v kódu.

Zachytání chyb

Pokud chcete zabránit selhání programu, můžete kolem kódu pro nahrání modelu přidat kód výjimky. Zabalte existující volání klienta await client.CreateModelsAsync(typeList) do obslužné rutiny try/catch, například:

try
{
    await client.CreateModelsAsync(models);
    Console.WriteLine("Models uploaded to the instance:");
}
catch (RequestFailedException e)
{
    Console.WriteLine($"Upload model error: {e.Status}: {e.Message}");
}

Když teď v příkazovém okně spustíte program pomocí příkazu , uvidíte, že se dotnet run vám vrátí kód chyby. Ve výstupu z kódu pro vytvoření modelu se zobrazí tato chyba:

Od této chvíli kurz zabalí všechna volání metod služby do obslužných rutin try/catch.

Vytvoření digitálních dvojčat

Teď, když jste nahráli model do Azure Digital Twins, můžete tuto definici modelu použít k vytvoření digitálních dvojčat. Digitální dvojčata jsou instancemi modelu a představují entity v rámci vašeho obchodního prostředí – například senzory na farmě, místnosti v budově nebo světla v automobilu. Tato část vytvoří několik digitálních dvojčat na základě modelu, který jste nahráli dříve.

Na konec metody přidejte následující kód pro vytvoření a inicializaci Main tří digitálních dvojčat založených na tomto modelu.

var twinData = new BasicDigitalTwin();
twinData.Metadata.ModelId = "dtmi:example:SampleModel;1";
twinData.Contents.Add("data", $"Hello World!");

string prefix = "sampleTwin-";
for (int i = 0; i < 3; i++)
{
    try
    {
        twinData.Id = $"{prefix}{i}";
        await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinData.Id, twinData);
        Console.WriteLine($"Created twin: {twinData.Id}");
    }
    catch(RequestFailedException e)
    {
        Console.WriteLine($"Create twin error: {e.Status}: {e.Message}");
    }
}

V příkazovém okně spusťte program pomocí dotnet run . Ve výstupu vyhledejte tiskové zprávy, které byly vytvořeny sampleTwin-0, sampleTwin-1 a sampleTwin-2.

Pak program znovu spusťte.

Všimněte si, že při druhém vytvoření dvojčat není vyvolána žádná chyba, i když dvojčata již existují po prvním spuštění. Na rozdíl od vytvoření modelu je vytvoření dvojčete na úrovni REST volání PUT s upsertovací sémantikou. Použití tohoto typu volání REST znamená, že pokud dvojče již existuje, pokus o vytvoření stejného dvojčete znovu nahradí původní dvojče. Není vyvolána žádná chyba.

Vytvoření relací

Dále můžete vytvořit relace mezi dvojčaty, která jste vytvořili, a připojit je k grafu dvojčat. Grafy dvojčat slouží k reprezentaci celého prostředí.

Pod metodu přidejte novou statickou metodu Program Main (kód teď má dvě metody):

public async static Task CreateRelationshipAsync(DigitalTwinsClient client, string srcId, string targetId)
{
    var relationship = new BasicRelationship
    {
        TargetId = targetId,
        Name = "contains"
    };

    try
    {
        string relId = $"{srcId}-contains->{targetId}";
        await client.CreateOrReplaceRelationshipAsync(srcId, relId, relationship);
        Console.WriteLine("Created relationship successfully");
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"Create relationship error: {e.Status}: {e.Message}");
    }
}

Dále přidejte na konec metody následující kód, který zavolá metodu a použije Main kód, CreateRelationship který jste právě napsali:

// Connect the twins with relationships
await CreateRelationshipAsync(client, "sampleTwin-0", "sampleTwin-1");
await CreateRelationshipAsync(client, "sampleTwin-0", "sampleTwin-2");

V příkazovém okně spusťte program pomocí dotnet run . Ve výstupu vyhledejte příkazy print, které říkají, že tyto dvě relace byly úspěšně vytvořeny.

Azure Digital Twins vám neumůžou vytvořit relaci, pokud už existuje jiná relace se stejným ID. Pokud tedy program spustíte vícekrát, uvidíte při vytváření relace výjimky. Tento kód zachycuje výjimky a ignoruje je.

Zobrazení seznamu relací

Další kód, který přidáte, vám umožní zobrazit seznam relací, které jste vytvořili.

Do třídy přidejte následující novou Program metodu:

public async static Task ListRelationshipsAsync(DigitalTwinsClient client, string srcId)
{
    try
    {
        AsyncPageable<BasicRelationship> results = client.GetRelationshipsAsync<BasicRelationship>(srcId);
        Console.WriteLine($"Twin {srcId} is connected to:");
        await foreach (BasicRelationship rel in results)
        {
            Console.WriteLine($" -{rel.Name}->{rel.TargetId}");
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"Relationship retrieval error: {e.Status}: {e.Message}");
    }
}

Pak na konec metody přidejte následující kód Main pro volání ListRelationships kódu:

//List the relationships
await ListRelationshipsAsync(client, "sampleTwin-0");

V příkazovém okně spusťte program pomocí dotnet run . Ve výstupním příkazu by se měl zobrazit seznam všech relací, které jste vytvořili:

Dotazování digitálních dvojčat

Hlavní funkcí tohoto Azure Digital Twins je schopnost snadno a efektivně dotazovat graf dvojčat, abyste mohli odpovídat na otázky týkající se vašeho prostředí.

Poslední část kódu, která se má přidat v tomto kurzu, spustí dotaz na Azure Digital Twins instanci. Dotaz použitý v tomto příkladu vrátí všechna digitální dvojčata v instanci .

Přidáním using tohoto příkazu povolíte použití třídy , která JsonSerializer pomůže prezentovat informace digitálního dvojčete:

using System.Text.Json;

Pak na konec metody přidejte následující Main kód:

// Run a query for all twins
string query = "SELECT * FROM digitaltwins";
AsyncPageable<BasicDigitalTwin> queryResult = client.QueryAsync<BasicDigitalTwin>(query);

await foreach (BasicDigitalTwin twin in queryResult)
{
    Console.WriteLine(JsonSerializer.Serialize(twin));
    Console.WriteLine("---------------");
}

V příkazovém okně spusťte program pomocí dotnet run . Ve výstupu by se měla zobrazit všechna digitální dvojčata v této instanci.

Kompletní příklad kódu

V tomto okamžiku kurzu máte kompletní klientskou aplikaci, která může provádět základní akce s Azure Digital Twins. Pro referenci je níže uvedený úplný kód programu v souboru Program.cs:

using System;
// <Azure_Digital_Twins_dependencies>
using Azure.DigitalTwins.Core;
using Azure.Identity;
// </Azure_Digital_Twins_dependencies>
// <Model_dependencies>
using System.Threading.Tasks;
using System.IO;
using System.Collections.Generic;
using Azure;
// </Model_dependencies>
// <Query_dependencies>
using System.Text.Json;
// </Query_dependencies>

namespace DigitalTwins_Samples
{
    class DigitalTwinsClientAppSample
    {
        // <Async_signature>
        static async Task Main(string[] args)
        {
        // </Async_signature>
            Console.WriteLine("Hello World!");
            // <Authentication_code>
            string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-hostName>"; 
            
            var credential = new DefaultAzureCredential();
            var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
            Console.WriteLine($"Service client created – ready to go");
            // </Authentication_code>

            // <Model_code>
            Console.WriteLine();
            Console.WriteLine("Upload a model");
            string dtdl = File.ReadAllText("SampleModel.json");
            var models = new List<string> { dtdl };

            // Upload the model to the service
            // <Model_try_catch>
            try
            {
                await client.CreateModelsAsync(models);
                Console.WriteLine("Models uploaded to the instance:");
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine($"Upload model error: {e.Status}: {e.Message}");
            }
            // </Model_try_catch>

            // <Print_model>
            // Read a list of models back from the service
            AsyncPageable<DigitalTwinsModelData> modelDataList = client.GetModelsAsync();
            await foreach (DigitalTwinsModelData md in modelDataList)
            {
                Console.WriteLine($"Model: {md.Id}");
            }
            // </Print_model>
            // </Model_code>

            // <Initialize_twins>
            var twinData = new BasicDigitalTwin();
            twinData.Metadata.ModelId = "dtmi:example:SampleModel;1";
            twinData.Contents.Add("data", $"Hello World!");
            
            string prefix = "sampleTwin-";
            for (int i = 0; i < 3; i++)
            {
                try
                {
                    twinData.Id = $"{prefix}{i}";
                    await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinData.Id, twinData);
                    Console.WriteLine($"Created twin: {twinData.Id}");
                }
                catch(RequestFailedException e)
                {
                    Console.WriteLine($"Create twin error: {e.Status}: {e.Message}");
                }
            }
            // </Initialize_twins>

            // <Use_create_relationship>
            // Connect the twins with relationships
            await CreateRelationshipAsync(client, "sampleTwin-0", "sampleTwin-1");
            await CreateRelationshipAsync(client, "sampleTwin-0", "sampleTwin-2");
            // </Use_create_relationship>

            // <Use_list_relationships>
            //List the relationships
            await ListRelationshipsAsync(client, "sampleTwin-0");
            // </Use_list_relationships>

            // <Query_twins>
            // Run a query for all twins
            string query = "SELECT * FROM digitaltwins";
            AsyncPageable<BasicDigitalTwin> queryResult = client.QueryAsync<BasicDigitalTwin>(query);
            
            await foreach (BasicDigitalTwin twin in queryResult)
            {
                Console.WriteLine(JsonSerializer.Serialize(twin));
                Console.WriteLine("---------------");
            }
            // </Query_twins>
        }

        // <Create_relationship>
        public async static Task CreateRelationshipAsync(DigitalTwinsClient client, string srcId, string targetId)
        {
            var relationship = new BasicRelationship
            {
                TargetId = targetId,
                Name = "contains"
            };
        
            try
            {
                string relId = $"{srcId}-contains->{targetId}";
                await client.CreateOrReplaceRelationshipAsync(srcId, relId, relationship);
                Console.WriteLine("Created relationship successfully");
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine($"Create relationship error: {e.Status}: {e.Message}");
            }
        }
        // </Create_relationship>
        
        // <List_relationships>
        public async static Task ListRelationshipsAsync(DigitalTwinsClient client, string srcId)
        {
            try
            {
                AsyncPageable<BasicRelationship> results = client.GetRelationshipsAsync<BasicRelationship>(srcId);
                Console.WriteLine($"Twin {srcId} is connected to:");
                await foreach (BasicRelationship rel in results)
                {
                    Console.WriteLine($" -{rel.Name}->{rel.TargetId}");
                }
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine($"Relationship retrieval error: {e.Status}: {e.Message}");
            }
        }
        // </List_relationships>
    }
}

Vyčištění prostředků

Po dokončení tohoto kurzu si můžete vybrat prostředky, které chcete odebrat, v závislosti na tom, co chcete udělat dále.

• Pokud chcete pokračovat k dalšímu kurzu, můžete instanci použitou v tomto kurzu znovu použít v dalším kurzu. Prostředky, které Azure Digital Twins tady nastavíte, můžete ponechat a zbytek této části přeskočit.

• Pokud chcete pokračovat v používání instance digitálních vazeb Azure, kterou jste nastavili v tomto článku, ale vymažete některé nebo všechny jeho modely, vlákna a relace, můžete k odstranění prvků, které chcete odebrat, použít příkazy AZ dt CLI v Azure Cloud Shellm okně.

• Pokud nepotřebujete žádné prostředky, které jste vytvořili v tomto kurzu, můžete odstranit instanci digitálních vláken Azure a všechny další prostředky z tohoto článku pomocí příkazu AZ Group Delete . Tím se odstraní všechny prostředky Azure ve skupině prostředků i v samotné skupině prostředků.

  Důležité

  Odstranění skupiny prostředků je nevratné. Skupina prostředků i všechny prostředky v ní obsažené se trvale odstraní. Ujistěte se, že nechtěně neodstraníte nesprávnou skupinu prostředků nebo prostředky.

  Otevřete Azure Cloud Shella spuštěním následujícího příkazu odstraňte skupinu prostředků a vše, co obsahuje.

  az group delete --name <your-resource-group>
  

Můžete také odstranit složku projektu z místního počítače.

Další kroky

V tomto kurzu jste vytvořili klientskou aplikaci konzoly .NET od začátku. Pro tuto klientskou aplikaci jste napsali kód pro provádění základních akcí na Azure Digital Twins instanci.

Pokračujte k dalšímu kurzu a prozkoumejte, co můžete s ukázkovou klientskou aplikací dělat: