Udostępnij za pośrednictwem

Cyfrowe bliźniaki i ich graf bliźniaków

W tym artykule opisano, czym są cyfrowe bliźniaki w kontekście usługi Azure Digital Twins, oraz jak relacje między nimi mogą tworzyć graf bliźniaczych. W rozwiązaniu usługi Azure Digital Twins jednostki w twoim środowisku są reprezentowane przez cyfrowe reprezentacje bliźniacze. Cyfrowy bliźniak jest wystąpieniem jednego z niestandardowych zdefiniowanych modeli. Może być połączony z innymi cyfrowymi bliźniakami za pośrednictwem relacji w celu utworzenia grafu bliźniaków: ten graf jest reprezentacją całego twojego środowiska.

Wskazówka

"Azure Digital Twins" odnosi się do tej usługi platformy Azure jako całości. "Cyfrowe bliźniaki" lub po prostu "bliźniaki" odnoszą się do poszczególnych węzłów bliźniaczych w ramach wystąpienia usługi.

Bliźniaki cyfrowe

Przed utworzeniem cyfrowego bliźniaka w wystąpieniu usługi Azure Digital Twins należy przesłać model do usługi. Model opisuje zestaw właściwości i relacji, które może mieć między innymi konkretny bliźniak. Aby uzyskać więcej informacji na temat modeli, zobacz Modele DTDL.

Po utworzeniu i przesłaniu modelu aplikacja kliencka może utworzyć wystąpienie typu. To wystąpienie jest cyfrowym bliźniakiem. 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 / Notatka

Bliźniaki cyfrowe w Azure Digital Twins różnią się od bliźniaków urządzeń w 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 bliźniaków

Bliźniaki są połączone w graf bliźniaczych przez ich relacje. Relacje, które może mieć bliźniak, są definiowane jako część jego modelu.

Na przykład model Floor może zdefiniować relację, która jest przeznaczona contains dla bliźniaczych jednostek typu Pokój. Dzięki tej definicji usługa Azure Digital Twins umożliwia tworzenie relacji z dowolnego bliźniaka piętra do dowolnego bliźniaka pokoju (w tym bliźniaków, 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:

Zrzut ekranu Azure Digital Twins Explorer przedstawiający przykładowe modele i bliźniaki.

Reprezentacje JSON elementów grafu

Dane cyfrowego bliźniaka i dane relacji są przechowywane w formacie JSON, co oznacza, że kiedy zapytujesz graf cyfrowego bliźniaka w wystąpieniu usługi Azure Digital Twins, wynik będzie reprezentacją JSON utworzonych cyfrowych bliźniaków i relacji.

Format JSON cyfrowego bliźniaka

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 cyfrowego bliźniaka
$etag Standardowe pole HTTP przypisane przez serwer internetowy
$metadata.$model Identyfikator interfejsu modelu, który charakteryzuje tego cyfrowego bliźniaka
$metadata.<property-name> Inne informacje o metadanych dotyczące właściwości cyfrowego bliźniaka
$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 zdefiniować tylko w wersji Azure Digital Twins APIs/SDKs z 31 maja 2022 r., 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 cyfrowy bliźniak nie ma żadnych wychodzących krawędzi relacji.
<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 cyfrowego bliźniaka sformatowanego jako obiekt JSON. Ten bliźniak ma dwie właściwości: wilgotność i temperaturę oraz komponent 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 unikatowe w kontekście wystąpienia usługi Azure Digital Twins.
$etag Standardowe pole HTTP przypisane przez serwer internetowy
$sourceId Identyfikator cyfrowego bliźniaka źródłowego
$targetId Identyfikator docelowego cyfrowego bliźniaka
$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"
}

Tworzenie za pomocą interfejsów API

W tej sekcji pokazano, jak wygląda tworzenie cyfrowych bliźniaków i relacji za pomocą aplikacji klienckiej. Zawiera przykłady użycia zestawu .NET SDK, które wykorzystują interfejsy API DigitalTwins, aby zapewnić więcej kontekstu na temat tego, co dzieje się w ramach każdego z tych pojęć.

Tworzenie cyfrowych bliźniaków

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

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

// 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 nazywanej BasicDigitalTwin do przechowywania pól właściwości w bliźniaczym obiekcie 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 artykuł Tworzenie cyfrowego bliźniaka.

Uwaga / Notatka

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 API DigitalTwins do tworzenia relacji z jednego bliźniaka cyfrowego (bliźniaka źródłowego) do innego bliźniaka cyfrowego (bliźniaka docelowego).

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

Twórz bliźniaki oraz relacje zbiorczo za pomocą API do importowania zadań

Można przesłać wiele obiektów bliźniaczych i relacji w jednym wywołaniu interfejsu API przy użyciu Import Jobs API. 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 zbiorczego importu bliźniaków i relacji.

Usuwanie elementów grafu

Aby usunąć określone bliźniaki cyfrowe i relacje, użyj interfejsów API DigitalTwins Delete i DigitalTwins DeleteRelationship (dostępnych również jako polecenia CLI i wywołania zestawu SDK).

Aby usunąć wszystkie modele, bliźniaki i relacje w wystąpieniu jednocześnie, użyj interfejsu API Delete Jobs.

Dalsze kroki

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

Możesz też dowiedzieć się więcej na temat wykonywania zapytań do grafu bliźniaczego usługi Azure Digital Twins, aby uzyskać informacje.