Cyfrowe reprezentacje bliźniacze i ich graf bliźniaczych reprezentacji

W tym artykule opisano, jakie cyfrowe reprezentacje bliźniacze znajdują się w kontekście usługi Azure Digital Twins i jak relacje między nimi mogą tworzyć graf bliźniaczych reprezentacji. W rozwiązaniu usługi Azure Digital Twins jednostki w twoim środowisku są reprezentowane przez cyfrowe reprezentacje bliźniacze. Cyfrowa reprezentacja bliźniacze jest wystąpieniem jednego z modeli zdefiniowanych niestandardowych. Może być połączony z innymi cyfrowymi reprezentacjami bliźniaczymi za pośrednictwem relacji w celu utworzenia grafu bliźniaczej reprezentacji: ten graf bliźniaczej reprezentacji całego środowiska.

Napiwek

"Azure Digital Twins" odnosi się do tej usługi platformy Azure jako całości. "Cyfrowe reprezentacje bliźniacze" lub tylko "bliźniacze" odnoszą się do poszczególnych węzłów bliźniaczych wewnątrz wystąpienia usługi.

Digital Twins

Przed utworzeniem cyfrowej reprezentacji bliźniaczej w wystąpieniu usługi Azure Digital Twins należy przekazać model do usługi. Model opisuje między innymi zestaw właściwości i relacji, które mogą mieć konkretna reprezentacja bliźniacze. Aby zapoznać się z typami informacji zdefiniowanych w modelu, zobacz Modele niestandardowe.

Po utworzeniu i przekazaniu modelu aplikacja kliencka może utworzyć wystąpienie typu. To wystąpienie jest cyfrową reprezentacją bliźniaczą. Na przykład po utworzeniu modelu Floor można utworzyć jedną lub kilka cyfrowych reprezentacji bliźniaczych, które używają tego typu (na przykład bliźniaczej reprezentacji typu floor o nazwie GroundFloor, innej o nazwie Floor2 itd.).

Uwaga

Cyfrowe reprezentacje bliźniacze w usłudze Azure Digital Twins różnią się od bliźniaczych reprezentacji urządzeń w usłudze IoT Hub. Bliźniacze reprezentacje urządzeń usługi IoT Hub często koncentrują się na opisywaniu aspektów i możliwości samego urządzenia, podczas gdy bliźniacze reprezentacje w usłudze Azure Digital Twins są bardziej koncepcyjnymi reprezentacjami, które mogą przechowywać zdefiniowane przez użytkownika szczegółowe informacje o urządzeniu lub wielu powiązanych urządzeniach.

Urządzenia w usłudze IoT Hub można połączyć z usługą Azure Digital Twins w ramach kompleksowego rozwiązania reprezentującego urządzenie między usługami.

Relacje: graf cyfrowych reprezentacji bliźniaczych

Bliźniacze reprezentacje są połączone z grafem bliźniaczych reprezentacji przez ich relacje. Relacje, które mogą mieć reprezentacja bliźniacze, są definiowane jako część modelu.

Na przykład model Floor może zdefiniować relację, która jest przeznaczona contains dla bliźniaczych reprezentacji typu Pokój. Dzięki tej definicji usługa Azure Digital Twins umożliwia tworzenie contains relacji z dowolnej reprezentacji bliźniaczej Floor do dowolnej reprezentacji bliźniaczej pokoju (w tym bliźniaczych reprezentacji, które są podtypami pokoju).

Wynikiem tego procesu jest zestaw węzłów (cyfrowych reprezentacji bliźniaczych) połączonych za pośrednictwem krawędzi (ich relacji) na grafie.

Wizualizacja

Azure Digital Twins Explorer to wizualne narzędzie do eksplorowania danych na grafie usługi Azure Digital Twins. Eksplorator umożliwia wyświetlanie, wykonywanie zapytań i edytowanie modeli, reprezentacji bliźniaczych i relacji.

Aby dowiedzieć się więcej o narzędziu Azure Digital Twins Explorer, zobacz Azure Digital Twins Explorer. Aby uzyskać szczegółowe instrukcje dotyczące korzystania z jej funkcji, zobacz Korzystanie z eksploratora usługi Azure Digital Twins.

Oto jak wygląda wizualizacja:

Tworzenie za pomocą interfejsów API

W tej sekcji pokazano, jak wygląda tworzenie cyfrowych reprezentacji bliźniaczych i relacji z aplikacji klienckiej. Zawiera on przykłady zestawu .NET SDK , które używają interfejsów API DigitalTwins, aby zapewnić więcej kontekstu na temat tego, co dzieje się wewnątrz każdej z tych pojęć.

Tworzenie cyfrowych reprezentacji bliźniaczych

Poniżej znajduje się fragment kodu klienta, który używa interfejsów API DigitalTwins do utworzenia wystąpienia bliźniaczej reprezentacji typu Room z elementem twinId zdefiniowanym podczas tworzenia wystąpienia.

Właściwości bliźniaczej reprezentacji bliźniaczej można zainicjować podczas jej tworzenia lub ustawiać później. Aby utworzyć bliźniacza reprezentację z zainicjowanymi właściwościami, utwórz dokument JSON zawierający niezbędne wartości inicjowania.

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

Możesz również użyć klasy pomocniczej wywoływanej BasicDigitalTwin do przechowywania pól właściwości w obiekcie "bliźniaczej reprezentacji" bardziej bezpośrednio, jako alternatywy dla używania słownika. Aby uzyskać więcej informacji na temat klasy pomocniczej i przykładów jej użycia, zobacz Tworzenie cyfrowej reprezentacji bliźniaczej.

Uwaga

Chociaż właściwości bliźniaczej reprezentacji są traktowane jako opcjonalne i dlatego nie muszą być inicjowane, podczas tworzenia bliźniaczej reprezentacji należy ustawić wszystkie składniki bliźniaczej reprezentacji. Mogą być pustymi obiektami, ale same składniki muszą istnieć.

Utwórz relacje

Oto przykładowy kod klienta, który używa interfejsów API Usługi DigitalTwins do tworzenia relacji z jednej reprezentacji cyfrowej (bliźniaczej reprezentacji źródłowej) do innej cyfrowej reprezentacji bliźniaczej (bliźniaczej reprezentacji docelowej).

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

Zbiorcze tworzenie reprezentacji bliźniaczych i relacji za pomocą interfejsu API importowania zadań

Wiele reprezentacji bliźniaczych i relacji można przekazać w jednym wywołaniu interfejsu API przy użyciu interfejsu API importu zadań. Bliźniacze i relacje utworzone za pomocą tego interfejsu API mogą opcjonalnie obejmować inicjowanie ich właściwości. Aby uzyskać szczegółowe instrukcje i przykłady korzystające z tego interfejsu API, zobacz instrukcje importowania zbiorczego dla reprezentacji bliźniaczych i relacji.

Usuwanie elementów grafu

Aby usunąć określone reprezentacje bliźniacze i relacje, użyj interfejsów API Delete i DigitalTwins DeleteTwins DeleteRelationship (dostępnych również w poleceniach interfejsu wiersza polecenia i wywołaniach zestawu SDK).

Aby usunąć wszystkie modele, reprezentacje bliźniacze i relacje w wystąpieniu jednocześnie, użyj interfejsu API usuwania zadań.

Reprezentacje JSON elementów grafu

Dane cyfrowej reprezentacji bliźniaczej i dane relacji są przechowywane w formacie JSON, co oznacza, że podczas wykonywania zapytań względem grafu bliźniaczej reprezentacji bliźniaczej w wystąpieniu usługi Azure Digital Twins wynik będzie reprezentacją JSON utworzonych cyfrowych reprezentacji bliźniaczych i relacji.

Format JSON cyfrowej reprezentacji bliźniaczej

Gdy jest reprezentowany jako obiekt JSON, cyfrowa reprezentacja bliźniacza wyświetli następujące pola:

Nazwa pola	opis
$dtId	Ciąg dostarczony przez użytkownika reprezentujący identyfikator cyfrowej reprezentacji bliźniaczej
$etag	Standardowe pole HTTP przypisane przez serwer internetowy
$metadata.$model	Identyfikator interfejsu modelu, który charakteryzuje tę cyfrową reprezentację bliźniaczą
$metadata.<property-name>	Inne informacje o metadanych dotyczących właściwości cyfrowej reprezentacji bliźniaczej
$metadata.<property-name>.lastUpdateTime	Data/godzina przetworzenia komunikatu o aktualizacji właściwości przez usługę Azure Digital Twins
$metadata.<property-name>.sourceTime	Opcjonalna, zapisywalna właściwość reprezentująca sygnaturę czasową obserwowanej aktualizacji właściwości w świecie rzeczywistym. Tę właściwość można napisać tylko przy użyciu wersji 2022-05-31 interfejsów API/zestawów SDK usługi Azure Digital Twins, a wartość musi być zgodna z formatem daty i godziny ISO 8601. Aby uzyskać więcej informacji na temat aktualizowania tej właściwości, zobacz Aktualizowanie właściwości sourceTime.
<property-name>	Wartość właściwości w formacie JSON (stringtyp liczbowy lub obiekt)
$relationships	Adres URL ścieżki do kolekcji relacji. To pole jest nieobecne, jeśli cyfrowa reprezentacja bliźniacze nie ma krawędzi relacji wychodzących.
<component-name>	Obiekt JSON zawierający wartości właściwości i metadane składnika, podobnie jak obiekt główny. Ten obiekt istnieje nawet wtedy, gdy składnik nie ma właściwości.
<component-name>.$metadata	Informacje o metadanych składnika, podobne do poziomu głównego $metadata
<component-name>.<property-name>	Wartość właściwości składnika w formacie JSON (string, typ liczby lub obiekt)

Oto przykład cyfrowej reprezentacji bliźniaczej sformatowanej jako obiekt JSON. Ta reprezentacja bliźniacze ma dwie właściwości, Wilgotność i Temperatura oraz składnik o nazwie Termostat.

{
    "$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": {}
    }

Format JSON relacji

W przypadku reprezentowania jako obiektu JSON relacja z cyfrowej reprezentacji bliźniaczej będzie wyświetlać następujące pola:

Nazwa pola	opis
$relationshipId	Ciąg podany przez użytkownika reprezentujący identyfikator tej relacji. Ten ciąg jest unikatowy w kontekście źródłowej cyfrowej reprezentacji bliźniaczej, co oznacza również, że sourceId + relationshipId jest ona unikatowa w kontekście wystąpienia usługi Azure Digital Twins.
$etag	Standardowe pole HTTP przypisane przez serwer internetowy
$sourceId	Identyfikator źródłowej cyfrowej reprezentacji bliźniaczej
$targetId	Identyfikator docelowej cyfrowej reprezentacji bliźniaczej
$relationshipName	Nazwa relacji
<property-name>	[Opcjonalnie] Wartość właściwości tej relacji w formacie JSON (stringtyp liczbowy lub obiekt)

Oto przykład relacji sformatowanej jako obiekt JSON:

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

Następne kroki

Zobacz, jak zarządzać elementami grafu za pomocą interfejsów API usługi Azure Digital Twin:

• Zarządzanie cyfrowymi reprezentacjami bliźniaczymi
• Zarządzanie grafem bliźniaczych reprezentacji i relacjami

Możesz też dowiedzieć się więcej na temat wykonywania zapytań względem grafu bliźniaczej reprezentacji bliźniaczej usługi Azure Digital Twins, aby uzyskać informacje:

• Język zapytań