Digitális ikerpéldányok és ikergráfjuk

Ez a cikk bemutatja, hogy milyen digitális ikerpéldányok vannak az Azure Digital Twins kontextusában, és hogy a köztük lévő kapcsolatok hogyan hozhatnak létre ikergráfot. Egy Azure Digital Twins-megoldásban a környezet entitásait digitális ikerpéldányok képviselik. A digitális ikerpéldány az egyik egyénileg definiált modell példánya. Kapcsolaton keresztül más digitális ikerpéldányokhoz is csatlakoztatható, így ikergráfot alkothat: ez az ikergráf a teljes környezet ábrázolása.

Tipp.

Az "Azure Digital Twins" az Azure-szolgáltatás egészére utal. A "Digitális ikerpéldány(ok)" vagy a "twin(s)" a szolgáltatás példányán belüli egyedi ikercsomópontokra utal.

Digital Twins

Ahhoz, hogy létre tud hozni egy digitális ikerpéldányt az Azure Digital Twins-példányban, fel kell töltenie egy modellt a szolgáltatásba. A modell többek között azokat a tulajdonságokat és kapcsolatokat írja le, amelyekkel egy adott ikerpéldány rendelkezhet. A modellben definiált információtípusokért lásd az Egyéni modellek című témakört.

A modell létrehozása és feltöltése után az ügyfélalkalmazás létrehozhat egy ilyen típusú példányt. Ez a példány egy digitális ikerpéldány. A Floor-modell létrehozása után például létrehozhat egy vagy több ilyen típusú digitális ikerpéldányt (például egy FloorFloor nevű ikerpéldányt, egy másikat Floor2-nek stb.).

Megjegyzés:

Az Azure Digital Twins digitális ikerpéldányai eltérnek az IoT Hubban található ikereszközöktől. Az IoT Hub-ikereszközök gyakran maguk az eszközök jellemzőinek és képességeinek leírására összpontosítanak, míg az Azure Digital Twins ikerpéldányai fogalmibb reprezentációk, amelyek képesek a felhasználó által meghatározott elemzéseket tárolni egy eszközről vagy számos kapcsolódó eszközről.

Az IoT Hub eszközei egy olyan teljes körű megoldás részeként csatlakoztathatók az Azure Digital Twinshez, amely az eszközt a szolgáltatások között képviseli.

Kapcsolatok: digitális ikerpéldányok grafikonja

Az ikerpéldányokat a kapcsolatuk köti össze egy ikergráfban. Az ikerpéldányok kapcsolatai a modell részeként definiálhatók.

A modell padlója például meghatározhat egy contains olyan kapcsolatot, amely a Room típusú ikerpéldányokat célozza meg. Ezzel a definícióval az Azure Digital Twins lehetővé teszi, hogy kapcsolatokat hozzon létre contains bármely emeleti ikerpéldány és bármely szobai ikerpéldány között (beleértve a Szoba altípusú ikerpéldányokat is).

Ennek a folyamatnak az eredménye a csomópontok (a digitális ikerpéldányok) halmaza, amely éleken (kapcsolataikon) keresztül csatlakozik egy gráfhoz.

Visualization

Az Azure Digital Twins Explorer egy vizuális eszköz az Azure Digital Twins-gráf adatainak feltárására. Az Explorerrel megtekintheti, lekérdezheti és szerkesztheti modelljeit, ikerpéldányait és kapcsolatait.

Az Azure Digital Twins Explorer eszközről az Azure Digital Twins Explorerben olvashat. A funkciók használatának részletes lépéseit az Azure Digital Twins Explorer használata című témakörben találja.

Így néz ki a vizualizáció:

Létrehozás az API-kkal

Ez a szakasz bemutatja, hogyan lehet digitális ikerpéldányokat és kapcsolatokat létrehozni egy ügyfélalkalmazásból. .NET SDK-példákat tartalmaz, amelyek a DigitalTwins API-kat használják, hogy több kontextust biztosítsanak az egyes fogalmakon belül.

Digitális ikerpéldányok létrehozása

Az alábbiakban egy kódrészlet látható, amely a DigitalTwins API-kat használja egy Szoba típusú ikerpéldány példányosításához a példányosítás során definiált kódrészlettel twinId .

Az ikerpéldányok tulajdonságait inicializálhatja a létrehozáskor, vagy később is beállíthatja őket. Inicializált tulajdonságokkal rendelkező ikerpéldány létrehozásához hozzon létre egy JSON-dokumentumot, amely biztosítja a szükséges inicializálási értékeket.

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

Használhat egy segédosztályt is, amely a tulajdonságmezők közvetlenebb tárolására szolgál BasicDigitalTwin egy "iker" objektumban, a szótár használata helyett. A segédosztályról és a használatára vonatkozó példákról további információt a Digitális ikerpéldány létrehozása című témakörben talál.

Megjegyzés:

Bár az ikertulajdonságok nem kötelezőek, ezért nem kell inicializálni őket, az ikerpéldány összes összetevőjét be kell állítani az ikerpéldány létrehozásakor. Lehetnek üres objektumok, de maguknak az összetevőknek is létezniük kell.

Kapcsolatok létrehozása

Íme néhány példa ügyfélkód, amely a DigitalTwins API-kkal hoz létre kapcsolatot egy digitális ikerpéldányról (a "forrás" ikerpéldányról) egy másik digitális ikerpéldányra (a "cél" ikerpéldányra).

public async Task CreateRelationship(DigitalTwinsClient client)
{
    var rel = new BasicRelationship
    {
        TargetId = "myTargetTwin",
        Name = "contains", // a relationship with this name must be defined in the model
        // Initialize properties
        Properties =
        {
            { "active", true },
        },
    };
    await client.CreateOrReplaceRelationshipAsync("mySourceTwin", "rel001", rel);
}

Ikerpéldányok és kapcsolatok tömeges létrehozása az Import Jobs API-val

Több ikerpéldányt és kapcsolatot is feltölthet egyetlen API-hívásba az Import Jobs API használatával. Az API-val létrehozott ikerpéldányok és kapcsolatok opcionálisan magukban foglalhatják a tulajdonságaik inicializálását. Az API-t használó részletes utasításokért és példákért tekintse meg az ikerpéldányok és kapcsolatok tömeges importálására vonatkozó utasításokat.

Gráfelemek törlése

Adott ikerpéldányok és kapcsolatok törléséhez használja a DigitalTwins Delete és a DigitalTwins DeleteRelationship API-kat (parancssori felületi parancsok és SDK-hívások esetén is).

Az összes modell, ikerpéldány és kapcsolat egyszerre történő törléséhez használja a Feladatok törlése API-t.

Gráfelemek JSON-ábrázolásai

A digitális ikeradatok és a kapcsolatadatok egyaránt JSON formátumban vannak tárolva, ami azt jelenti, hogy amikor lekérdezi az ikergráfot az Azure Digital Twins-példányban, az eredmény a létrehozott digitális ikerpéldányok és kapcsolatok JSON-ábrázolása lesz.

Digitális iker JSON formátum

JSON-objektumként ábrázolva egy digitális ikerpéldány a következő mezőket jeleníti meg:

Mező neve	Leírás
$dtId	A digitális ikerpéldány azonosítóját képviselő, felhasználó által megadott sztring
$etag	A webkiszolgáló által hozzárendelt szabványos HTTP-mező
$metadata.$model	A digitális ikerpéldányt jellemző modellfelület azonosítója
$metadata.<property-name>	A digitális ikerpéldány tulajdonságaival kapcsolatos egyéb metaadat-információk
$metadata.<property-name>.lastUpdateTime	A tulajdonságfrissítési üzenet Azure Digital Twins általi feldolgozásának dátuma/időpontja
$metadata.<property-name>.sourceTime	Nem kötelező, írható tulajdonság, amely azt az időbélyeget jelöli, amikor a tulajdonságfrissítést a valós világban figyelték meg. Ez a tulajdonság csak az Azure Digital Twins API-k/SDK-k 2022-05-31-es verziójával írható, és az értéknek meg kell felelnie az ISO 8601 dátum- és időformátumának. A tulajdonság frissítéséről további információt a tulajdonság sourceTime-jának frissítése című témakörben talál.
<property-name>	Egy tulajdonság értéke a JSON-ban (stringszámtípus vagy objektum)
$relationships	A kapcsolatgyűjtemény elérési útjának URL-címe. Ez a mező hiányzik, ha a digitális ikerpéldány nem rendelkezik kimenő kapcsolati élekkel.
<component-name>	Az összetevő tulajdonságértékeit és metaadatait tartalmazó JSON-objektum, a gyökérobjektuméhoz hasonlóan. Ez az objektum akkor is létezik, ha az összetevőnek nincsenek tulajdonságai.
<component-name>.$metadata	Az összetevő metaadatai a gyökérszinthez hasonlóan $metadata
<component-name>.<property-name>	Az összetevő tulajdonságának értéke a JSON-ban (stringszámtípus vagy objektum)

Íme egy példa egy JSON-objektumként formázott digitális ikerpéldányra. Ennek az ikernek két tulajdonsága van, a páratartalom és a hőmérséklet, valamint egy termosztát nevű összetevő.

{
    "$dtId": "myRoomID",
    "$etag": "W/\"8e6d3e89-1166-4a1d-9a99-8accd8fef43f\"",
    "$metadata": {
        "$model": "dtmi:example:Room23;1",
        "Humidity": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        },
        "Temperature": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        }
    },
    "Humidity": 55,
    "Temperature": 35,
    "Thermostat": {
        "$metadata": {}
    }

Kapcsolat JSON formátuma

JSON-objektumként ábrázolva a digitális ikerpéldányból származó kapcsolat a következő mezőket jeleníti meg:

Mező neve	Leírás
$relationshipId	A kapcsolat azonosítóját képviselő, felhasználó által megadott sztring. Ez a sztring a forrás digitális ikerpéldány kontextusában egyedi, ami azt is jelenti, hogy sourceId + relationshipId az Azure Digital Twins-példány kontextusában is egyedi.
$etag	A webkiszolgáló által hozzárendelt szabványos HTTP-mező
$sourceId	A forrás digitális ikerpéldány azonosítója
$targetId	A cél digitális ikerpéldány azonosítója
$relationshipName	A kapcsolat neve
<property-name>	[Nem kötelező] A kapcsolat egy tulajdonságának értéke JSON-ban (stringszámtípus vagy objektum)

Íme egy példa egy JSON-objektumként formázott kapcsolatra:

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

További lépések

Megtudhatja, hogyan kezelheti a gráfelemeket az Azure Digital Twin API-kkal:

• Digitális ikerpéldányok kezelése
• Az ikergráf és a kapcsolatok kezelése

További információ az Azure Digital Twins ikergráfjának lekérdezéséről:

• Lekérdezés nyelve