Udostępnij za pośrednictwem

Dowiedz się więcej o modelach bliźniaczych i sposobach ich definiowania w usłudze Azure Digital Twins

Kluczową cechą usługi Azure Digital Twins jest możliwość definiowania własnego słownictwa i budowania grafu bliźniaczego, używając terminów zdefiniowanych samodzielnie w kontekście działalności firmy. Ta funkcja jest udostępniana za pośrednictwem modeli udostępnianych przez użytkownika. Modele można traktować jako nicowniki w opisie świata. Modele usługi Azure Digital Twins są reprezentowane w języku JSON-LD Digital Twin Definition Language (DTDL).

Model jest podobny do klasy w języku programowania obiektowym, definiując kształt danych dla jednej konkretnej koncepcji w rzeczywistym środowisku pracy. Modele mają nazwy (takie jak Room lub TemperatureSensor) i zawierają elementy, takie jak właściwości, składniki i relacje opisujące działanie tej jednostki w danym środowisku. Później użyjesz tych modeli do utworzenia cyfrowych reprezentacji bliźniaczych reprezentujących określone jednostki spełniające ten typ opisu.

Język DTDL (Digital Twin Definition Language) dla modeli

Modele usługi Azure Digital Twins są definiowane przy użyciu języka Digital Twins Definition Language (DTDL).

Pełny opis języka dla języka DTDL w wersji 3 można wyświetlić w witrynie GitHub: OPIS języka DTDL w wersji 3. Ta strona zawiera szczegółowe informacje o dokumentacji języka DTDL i przykłady ułatwiające rozpoczęcie pisania własnych modeli DTDL.

Język DTDL jest oparty na formacie JSON-LD i nie jest zależny od języka programowania. Język DTDL nie jest wyłączny dla usługi Azure Digital Twins. Służy również do reprezentowania danych urządzenia w innych usługach IoT, takich jak IoT Plug and Play.

W pozostałej części tego artykułu podsumowano sposób użycia języka w usłudze Azure Digital Twins.

Obsługiwane wersje języka DTDL

Usługa Azure Digital Twins obsługuje języki DTDL w wersji 2 i 3 (odpowiednio skrócone w dokumentacji do wersji 2 i 3). Wersja 3 jest zalecanym wyborem do modelowania w usłudze Azure Digital Twins na podstawie rozszerzonych możliwości, w tym:

W przypadku omawiania tych funkcji w dokumentacji towarzyszy im uwaga, że są one dostępne tylko w języku DTDL w wersji 3. Aby uzyskać pełną listę różnic między językiem DTDL w wersji 2 i 3, zobacz Opis języka DTDL w wersji 3: zmiany z wersji 2.

Usługa Azure Digital Twins obsługuje również używanie mieszanki modeli w wersji 2 i wersji 3 w tym samym wystąpieniu. W przypadku używania modeli obu wersji należy pamiętać o następujących ograniczeniach:

  • Interfejs w wersji 2 nie może rozszerzać interfejsu w wersji 3 ani posiadać składnika z interfejsem w wersji 3 jako swój schemat.
  • Z drugiej strony interfejs w wersji 3 może rozszerzyć interfejs v2, a interfejs w wersji 3 może mieć składnik z interfejsem w wersji 2 jako jego schematu.
  • Relacje mogą wskazywać w obu kierunkach od źródła modelu w wersji 2 do docelowego modelu w wersji 3 lub odwrotnie od źródła modelu w wersji 3 do celu modelu w wersji 2.

Istniejące modele w wersji 2 można również migrować do wersji 3. Aby uzyskać instrukcje dotyczące tego, jak to zrobić, zobacz Konwertowanie modeli w wersji 2 na 3.

Uwaga

Obecnie usługa Azure Digital Twins Explorer w pełni obsługuje modele DTDL w wersji 2 i obsługuje ograniczone funkcje modeli DTDL w wersji 3.

Modele DTDL w wersji 3 można wyświetlić na panelu Modele, a bliźniacze reprezentacje utworzone za pomocą modeli DTDL w wersji 3 można wyświetlać i edytować (w tym bliźniacze reprezentacje z właściwościami tablicy). Jednak modele DTDL w wersji 3 nie są wyświetlane na panelu Model Graph i nie można ich zaimportować przy użyciu narzędzia Azure Digital Twins Explorer. Aby zaimportować modele DTDL w wersji 3 do wystąpienia, użyj innego interfejsu deweloperskiego, takiego jak interfejsy API i zestawy SDK lub Azure CLI.

Omówienie modelu

Modele typów reprezentacji bliźniaczych można pisać w dowolnym edytorze tekstów. Język DTDL jest zgodny ze składnią JSON, dlatego należy przechowywać modele z rozszerzeniem .json. Użycie rozszerzenia JSON umożliwi wielu edytorom programowania tekstu zapewnienie podstawowego sprawdzania składni i wyróżniania dokumentów DTDL. Istnieje również rozszerzenie DTDL dostępne dla programu Visual Studio Code.

Poniżej przedstawiono pola w interfejsie modelu:

Pole opis
@id Identyfikator modelu bliźniaka cyfrowego (DTMI) w formacie dtmi:<domain>:<unique-model-identifier>;<model-version-number>. W języku DTDL w wersji 3 numer wersji może zostać pominięty lub ustrukturyzowany jako dwuczęściowy (<major>.<minor>) numer wersji.
@type Określa rodzaj opisywanych informacji. W przypadku interfejsu typ to Interface.
@context Ustawia kontekst dokumentu JSON. Modele powinny używać dtmi:dtdl:context;2 dla DTDL w wersji 2 lub dtmi:dtdl:context;3 dla DTDL w wersji 3. Modele DTDL w wersji 3 mogą również nazywać dodatkowe rozszerzenia funkcji w tym polu.
displayName [opcjonalnie] Umożliwia zdefiniowanie przyjaznej nazwy modelu. Jeśli nie używasz tego pola, model użyje pełnej wartości DTMI.
contents Wszystkie pozostałe dane interfejsu są umieszczane tutaj jako tablica definicji atrybutów. Każdy atrybut musi zapewniać @type (Property, Relationship lub Component), aby zidentyfikować rodzaj interfejsu informacji, które opisuje, a następnie zestaw właściwości definiujących rzeczywisty atrybut. W następnej sekcji opisano szczegółowo atrybuty modelu.

Oto przykład podstawowego modelu DTDL. W tym modelu opisano element Home z jedną właściwością identyfikatora. Model domu definiuje również relację z modelem piętra, która może służyć do wskazania, że bliźniaki związane z domem są połączone z pewnymi bliźniakami związanymi z piętrem.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Atrybuty modelu

Główne informacje o modelu są podane przez jego atrybuty, które są zdefiniowane w contents sekcji interfejsu modelu.

Poniżej przedstawiono atrybuty dostępne w języku DTDL, które są obsługiwane w usłudze Azure Digital Twins. Interfejs modelu DTDL używany w usłudze Azure Digital Twins może zawierać zero, jeden lub wiele z następujących pól:

  • Właściwość — właściwości to pola danych reprezentujące stan jednostki (na przykład właściwości w wielu językach programowania obiektowych). Właściwości mają magazyn zapasowy i można je odczytywać w dowolnym momencie. Aby uzyskać więcej informacji, zobacz Właściwości poniżej.

  • Relacja — relacje umożliwiają przedstawienie sposobu, w jaki cyfrowy bliźniak może być zaangażowany w inne cyfrowe bliźniaki. Relacje mogą reprezentować różne znaczenia semantyczne, takie jak contains ("piętro zawiera pomieszczenie"), cools ("hvac chłodzi pomieszczenie"), isBilledTo ("kompresor jest rozliczany na użytkownika"), itd. Relacje umożliwiają rozwiązaniu udostępnianie grafu powiązanych jednostek. Relacje mogą również mieć własne właściwości. Aby uzyskać więcej informacji, zobacz Relacje poniżej.

  • Component — składniki umożliwiają tworzenie interfejsu modelu jako zestawu innych interfejsów, jeśli chcesz. Przykładem składnika jest interfejs frontCamera (i inny interfejs składnika backCamera), który jest używany do definiowania modelu dla telefonu. Najpierw zdefiniuj interfejs dla frontCamera tak, jakby był jego własnym modelem, a następnie odwoływał się do niego podczas definiowania telefonu.

    Użyj składnika, aby opisać coś, co jest integralną częścią rozwiązania, ale nie wymaga oddzielnej tożsamości i nie musi być tworzone, usuwane ani reorganizowane niezależnie w grafie podwójnym. Jeśli chcesz, aby jednostki miały niezależne istnienia w bliźniaczym grafie, przedstaw je jako oddzielne cyfrowe bliźniaki różnych modeli, połączone relacjami.

    Napiwek

    Składniki mogą być również używane w organizacji do grupowania zestawów powiązanych właściwości w interfejsie modelu. W takiej sytuacji każdy składnik można traktować jako przestrzeń nazw lub "folder" wewnątrz interfejsu.

    Aby uzyskać więcej informacji, zobacz Składniki poniżej.

Opis języka DTDL w wersji 3 definiuje również polecenia i dane telemetryczne, ale żadna z nich nie jest używana w usłudze Azure Digital Twins. Polecenia nie są obsługiwane, a dane telemetryczne — chociaż są dozwolone w definicjach modelu — nie mają unikatowego przypadku użycia w modelowaniu usługi Azure Digital Twins. Zamiast używać telemetrii DTDL, należy użyć właściwości DTDL do przechowywania informacji o stanie bliźniaka.

Uwaga

Chociaż nie ma potrzeby definiowania pól telemetrii w modelach DTDL do przechowywania danych przychodzących urządzeń, usługa Azure Digital Twins może emitować zdarzenia jako dane telemetryczne przy użyciu interfejsu API SendTelemetry. Spowoduje to wyzwolenie zdarzenia wiadomości telemetrycznej Digital Twin, które może zostać odebrane przez program obsługi zdarzeń w celu podjęcia akcji na innych bliźniaczych obiektach lub wyzwolenia usług podrzędnych.

Właściwości

Ta sekcja zawiera bardziej szczegółowe informacje o właściwościach modeli DTDL.

Aby uzyskać kompleksowe informacje o polach, które mogą być wyświetlane jako część właściwości, zobacz Właściwość w opisie języka DTDL w wersji 3.

Uwaga

Atrybut writable DTDL dla właściwości nie jest obecnie obsługiwany w usłudze Azure Digital Twins. Można go dodać do modelu, ale usługa Azure Digital Twins nie będzie jej wymuszać. Aby uzyskać więcej informacji, zobacz Uwagi dotyczące języka DTDL specyficzne dla usługi.

Schemat

Zgodnie z DTDL schemat atrybutów właściwości może być standardowym typem pierwotnym — integer, double, string, boolean — oraz innymi typami, takimi jak dateTime i duration.

Oprócz typów pierwotnych pola właściwości mogą mieć następujące typy złożone:

  • Object
  • Map
  • Enum
  • Array, tylko w języku DTDL w wersji 3. Array Typ właściwości nie jest obsługiwany w DTDL v2.

Mogą być również typami semantycznymi, które umożliwiają adnotowanie wartości jednostkami. W kodzie DTDL w wersji 2 typy semantyczne są natywnie obsługiwane. W języku DTDL w wersji 3 można uwzględnić je z rozszerzeniem funkcji.

Podstawowy przykład właściwości

Oto podstawowy przykład właściwości w modelu DTDL. W tym przykładzie pokazano właściwość ID domu.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Przykład typu obiektu złożonego

Właściwości mogą być typami złożonymi, w tym zawierać typ Object.

W poniższym przykładzie pokazano inną wersję modelu Home, z właściwością określającą jego adres. address jest obiektem, z własnymi polami dla ulicy, miasta, stanu i zip.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Przykład semantycznego typu DTDL w wersji 2

Typy semantyczne służą do wyrażania wartości za pomocą jednostki. Właściwości usługi Azure Digital Twins mogą używać dowolnego typu semantycznego obsługiwanego przez język DTDL.

W kodzie DTDL w wersji 2 typy semantyczne są natywnie obsługiwane. Aby uzyskać więcej informacji na temat typów semantycznych w języku DTDL w wersji 2, zobacz Semantyczne typy w opisie języka DTDL w wersji 2. Aby dowiedzieć się więcej o typach semantycznych w języku DTDL w wersji 3, zobacz rozszerzenie funkcji QuantitativeTypes DTDL v3.

W poniższym przykładzie przedstawiono model czujnika DTDL w wersji 2 z właściwościami typu semantycznego dla wilgotności i temperatury.

{
  "@id": "dtmi:com:adt:dtsample:v2sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Sensor (v2 model)",
  "contents": [
    {
      "@type": ["Property", "Temperature"],
      "name": "Temperature",
      "schema": "double",
      "unit": "degreeFahrenheit"    
    },
    {
      "@type": ["Property", "Humidity"],
      "name": "Humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre" 
    }
  ]
}

Ważne

"Właściwość" musi być pierwszym elementem @type tablicy, a za nim powinien znajdować się typ semantyczny. W przeciwnym razie pole może być niewidoczne w Eksploratorze usługi Azure Digital Twins.

Relacje

Ta sekcja zawiera bardziej szczegółowe informacje na temat relacji w modelach DTDL.

Aby uzyskać pełną listę pól, które mogą być wyświetlane jako część relacji, zobacz Relacja w opisie języka DTDL w wersji 3.

Uwaga

Atrybuty writable, minMultiplicity i maxMultiplicity DTDL dla relacji nie są obecnie obsługiwane w usłudze Azure Digital Twins. Można je dodać do modelu, ale usługa Azure Digital Twins nie będzie ich wymuszać. Aby uzyskać więcej informacji, zobacz Uwagi dotyczące języka DTDL specyficzne dla usługi.

Podstawowy przykład relacji

Oto podstawowy przykład relacji w modelu DTDL. W tym przykładzie pokazano relację w modelu domu, który umożliwia połączenie z modelem podłogi.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Uwaga

W przypadku relacji @id jest polem opcjonalnym. Jeśli @id nie zostanie dostarczony, procesor interfejsu cyfrowego bliźniaka przypisze jeden.

Relacje docelowe i nienależące do celu

Relacje można definiować z elementem docelowym lub bez. Element docelowy określa, do jakich typów bliźniaków relacja może dotrzeć. Na przykład możesz uwzględnić element docelowy, aby określić, że model Dom może mieć relację rel_has_floors tylko z bliźniakami typu Podłoga.

Czasami możesz chcieć zdefiniować relację bez określonego celu, aby relacja mogła łączyć się z wieloma różnymi typami bliźniaków.

Oto przykład relacji w modelu DTDL, który nie ma elementu docelowego. W tym przykładzie relacja służy do definiowania czujników, które może mieć pokój, a relacja może łączyć się z dowolnym typem.

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre"
    },
    {
      "@type": "Component",
      "name": "thermostat",
      "schema": "dtmi:com:adt:dtsample:thermostat;1"
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
      "name": "rel_has_sensors",
      "displayName": "Room has sensors"
    }
  ]
},

Właściwości relacji

Język DTDL umożliwia również relacjom posiadanie własnych właściwości. Podczas definiowania relacji w modelu DTDL relacja może mieć własne properties pole, w którym można zdefiniować właściwości niestandardowe do opisania stanu specyficznego dla relacji.

W poniższym przykładzie pokazano inną wersję modelu Home, w której rel_has_floors relacja ma właściwość reprezentującą, gdy powiązane piętro zostało ostatnio zajęte.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Składniki

Ta sekcja zawiera bardziej szczegółowe informacje na temat składników w modelach DTDL.

Aby uzyskać pełną listę pól, które mogą być wyświetlane jako część składnika, zobacz Składnik w opisie języka DTDL v3.

Przykład podstawowego składnika

Oto podstawowy przykład składnika w modelu DTDL. W tym przykładzie pokazano model pokoju, który korzysta z modelu termostatu jako elementu.

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "schema": "double",
        "unit": "gramPerCubicMetre"
      },
      {
        "@type": "Component",
        "name": "thermostat",
        "schema": "dtmi:com:adt:dtsample:thermostat;1"
      },
      {
        "@type": "Relationship",
        "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
        "name": "rel_has_sensors",
        "displayName": "Room has sensors"
      }
    ]
  },
  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "schema": "double",
        "unit": "degreeFahrenheit"
      }
    ]
  }
]

Jeśli inne modele w tym rozwiązaniu powinny również zawierać termostat, mogą odwoływać się do tego samego modelu termostatu jako składnika we własnych definicjach, tak jak robi to Pokój.

Ważne

Interfejs składnika (termostat w powyższym przykładzie) musi być zdefiniowany w tej samej tablicy, co wszystkie interfejsy, które go używają (pokój w powyższym przykładzie) w celu znalezienia odwołania do składnika.

Dziedziczenie modelu

Czasami warto jeszcze bardziej specjalizować model. Na przykład, może być przydatne posiadanie ogólnego modelu Pokój oraz wyspecjalizowanych wariantów Sala Konferencyjna i Siłownia. Aby wyrazić specjalizację, język DTDL obsługuje dziedziczenie. Interfejsy mogą dziedziczyć z co najmniej jednego innego interfejsu. Możesz to zrobić, dodając extends pole do modelu.

Sekcja extends jest nazwą interfejsu lub tablicą nazw interfejsów (co umożliwia dziedziczenie interfejsu z wielu modeli nadrzędnych). Pojedynczy rodzic może służyć jako model podstawowy dla wielu rozszerzających interfejsów.

Uwaga

W języku DTDL w wersji 2 każdy extends może mieć co najwyżej dwa interfejsy wymienione dla niego. W języku DTDL w wersji 3 nie ma limitu liczby wartości natychmiastowych dla elementu extends.

W przypadku wersji 2 i 3 języka DTDL łączny limit głębokości hierarchii dla extends wynosi 10.

Poniższy przykład przekształca model Domu z wcześniejszego przykładu DTDL jako podtyp większego modelu „podstawowego”. Model nadrzędny (Core) jest definiowany najpierw, a następnie model podrzędny (Strona główna) kompiluje go przy użyciu polecenia extends.

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Core",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "schema": "string"
        },
        {
            "@type": "Property",
            "name": "name",
            "schema": "string"
        }
    ]
}

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

W takim przypadku Core przyczynia się do identyfikatora i nazwy do Home. Inne modele mogą również rozszerzyć model Core, aby uzyskać te właściwości. Oto model pokoju rozszerzający ten sam interfejs nadrzędny:

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",

Po zastosowaniu zasady dziedziczenia, rozszerzający interfejs uwidacznia wszystkie właściwości z całego łańcucha dziedziczenia.

Interfejs rozszerzający nie może zmienić żadnej z definicji interfejsów nadrzędnych; może je dodawać tylko do nich. Nie może również ponownie zdefiniować możliwości zdefiniowanej już w żadnym z jego interfejsów nadrzędnych (nawet jeśli możliwości są zdefiniowane tak samo). Jeśli na przykład interfejs nadrzędny definiuje double właściwość mass, interfejs rozszerzający nie może zawierać deklaracji mass, nawet jeśli jest to również double.

Rozszerzenia funkcji DTDL w wersji 3

Język DTDL w wersji 3 umożliwia rozszerzenia języka definiujące dodatkowe klasy metamodelek, których można użyć do pisania bogatszych modeli. W tej sekcji opisano klasy rozszerzeń funkcji, których można użyć do dodawania funkcji innych niż podstawowe do modeli DTDL w wersji 3.

Każde rozszerzenie funkcji jest identyfikowane przez specyfikator kontekstu, który jest unikatową wartością identyfikatora modelu cyfrowego bliźniaka (DTMI). Aby włączyć rozszerzenie funkcji w modelu, dodaj specyfikator kontekstu tego rozszerzenia do pola modelu @context (wraz z ogólnym specyfikatorem kontekstu DTDLdtmi:dtdl:context;3). Do tego samego modelu można dodać wiele rozszerzeń funkcji.

Oto przykład tego, jak to @context pole może wyglądać z rozszerzeniami funkcji. Poniższy fragment pochodzi z modelu, który korzysta zarówno z rozszerzenia QuantitativeTypes, jak i z rozszerzenia Annotation.

  "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1",
      "dtmi:dtdl:extension:annotation;1"
  ]

Po dodaniu rozszerzenia funkcji do modelu będziesz mieć dostęp do typów uzupełniających tego rozszerzenia w modelu. Możesz dodać typy dodatków do pola @type elementu DTDL, aby element zyskał dodatkowe możliwości. Typ adjunct może dodać dodatkowe właściwości do elementu.

Na przykład, oto fragment modelu, który używa rozszerzenia adnotacji Annotation extension. To rozszerzenie ma typ adjunct o nazwie ValueAnnotation, który jest dodawany w poniższym przykładzie do elementu właściwości. Dodanie tego typu adjunct do elementu właściwości umożliwia elementowi posiadanie dodatkowego annotates pola, które służy do wskazywania innej właściwości, która jest oznaczona adnotacjami tego elementu.

{
  "@type": [ "Property", "ValueAnnotation" ],
  "name": "currentTempAccuracy",
  "annotates": "currentTemp",
  "schema": "double"
  },

W pozostałej części tej sekcji bardziej szczegółowo opisano rozszerzenie adnotacji i inne rozszerzenia funkcji DTDL w wersji 3.

Rozszerzenie adnotacji

Rozszerzenie adnotacji służy do dodawania niestandardowych metadanych do elementu właściwości w modelu DTDL w wersji 3. Jego specyfikator kontekstu to dtmi:dtdl:extension:annotation;1.

To rozszerzenie zawiera typ dodatkowy ValueAnnotation, który można dodać do elementu właściwości DTDL. Typ ValueAnnotation dodaje jedno pole do elementu annotates, co umożliwia nadanie nazwy innej właściwości, adnotowanej przez bieżący element.

Aby uzyskać więcej szczegółów i przykładów tego rozszerzenia, zobacz Rozszerzenie adnotacji w opisie języka DTDL w wersji 3.

Rozszerzenie historyzacji

Rozszerzenie Historization służy do wyznaczania właściwości w modelu DTDL w wersji 3 jako elementu, który powinien być historizowany (co oznacza, że należy zarejestrować sekwencję historyczną jej wartości wraz z czasami, w których zmieniają się wartości). Jego specyfikator kontekstu to dtmi:dtdl:extension:historization;1.

To rozszerzenie zawiera typ pomocniczy Historized, który można dodać jako współtyp do elementu właściwości DTDL, aby wskazać, że usługa powinna utrwalać wartości historyczne elementu i udostępniać je do zapytań i analiz. Typ Historized adjunct nie dodaje żadnych pól do elementu.

Aby uzyskać więcej szczegółów i przykładów tego rozszerzenia, zobacz Historization extension in the DTDL v3 Language Description (Opis języka DTDL w wersji 3).

Nadpisywanie rozszerzenia

Rozszerzenie zastępujące służy do zastępowania właściwości w modelu DTDL w wersji 3 wartością wystąpienia. Jest używany w połączeniu z rozszerzeniem adnotacji, a jego specyfikator kontekstu to dtmi:dtdl:extension:overriding;1.

To rozszerzenie zawiera Override typ dołączony, który można dodać do właściwości DTDL, która jest również współtypowana z ValueAnnotation (pochodzący z rozszerzenia adnotacji). Typ Override dodaje jedno pole do elementu overrides, co umożliwia określenie pola w elemencie z adnotacjami, które ma zostać nadpisane przez wartość bieżącego elementu.

Aby uzyskać więcej szczegółów i przykładów tego rozszerzenia, zobacz Zastępowanie rozszerzenia w opisie języka DTDL w wersji 3.

Rozszerzenie QuantitativeTypes

Rozszerzenie QuantitativeTypes służy do włączania typów semantycznych, typów jednostek oraz jednostek w modelu DTDL w wersji 3. Jego specyfikator kontekstu to dtmi:dtdl:extension:quantitativeTypes;1.

To rozszerzenie umożliwia używanie wielu typów semantycznych jako typów pomocniczych, które można dodać do CommandRequest, Field, MapValue lub właściwości w języku DTDL w wersji 3. Typy semantyczne dodają jedno pole do elementu unit, które akceptuje prawidłową jednostkę odpowiadającą typowi semantycznemu.

Aby uzyskać więcej informacji na temat rozszerzenia, w tym przykłady i pełną listę obsługiwanych typów i jednostek semantycznych, zobacz Rozszerzenie QuantitativeTypes w opisie języka DTDL w wersji 3.

Uwagi dotyczące języka DTDL specyficzne dla usługi

Nie wszystkie usługi korzystające z języka DTDL implementują dokładnie te same funkcje języka DTDL. Istnieją pewne funkcje dtDL, których usługa Azure Digital Twins obecnie nie obsługuje, w tym:

  • Polecenia DTDL
  • Atrybut writable stosowany do właściwości lub relacji. Mimo że ten atrybut można ustawić zgodnie ze specyfikacjami DTDL, wartość nie jest używana przez usługę Azure Digital Twins. Zamiast tego te atrybuty są zawsze traktowane jako zapisywalne przez klientów zewnętrznych, którzy mają ogólne uprawnienia do zapisu w usłudze Azure Digital Twins.
  • Właściwości minMultiplicity i maxMultiplicity w relacjach. Chociaż te atrybuty można ustawić zgodnie ze specyfikacjami DTDL, wartości nie są wymuszane przez usługę Azure Digital Twins.

Aby model DTDL był zgodny z usługą Azure Digital Twins, musi również spełniać następujące wymagania:

  • Wszystkie elementy DTDL najwyższego poziomu w modelu muszą mieć typ Interface. Powodem tego wymagania jest to, że interfejsy API modelu usługi Azure Digital Twins mogą odbierać obiekty JSON reprezentujące interfejs lub tablicę interfejsów. W związku z tym żadne inne typy elementów DTDL nie są dozwolone na najwyższym poziomie.
  • Język DTDL dla usługi Azure Digital Twins nie może definiować żadnych poleceń.
  • Usługa Azure Digital Twins zezwala tylko na pojedynczy poziom zagnieżdżania składników, co oznacza, że interfejs używany jako składnik nie może mieć żadnych składników.
  • Interfejsy nie mogą być zdefiniowane śródwierszowo w innych interfejsach DTDL; muszą być zdefiniowane jako oddzielne jednostki najwyższego poziomu z własnymi identyfikatorami. Następnie, gdy inny interfejs chce uwzględnić ten interfejs jako składnik lub przez dziedziczenie, może odwoływać się do jego identyfikatora.

Narzędzia do modelowania i najlepsze rozwiązania

W tej sekcji opisano dodatkowe zagadnienia i zalecenia dotyczące modelowania.

Używać istniejących standardowych ontologii w branży

Ontologia to zestaw modeli, które kompleksowo opisują daną domenę, takie jak produkcja, struktury budowlane, systemy IoT, inteligentne miasta, sieci energetyczne, zawartość internetowa i inne.

Jeśli Rozwiązanie jest przeznaczone dla określonej branży, która korzysta z dowolnego rodzaju standardu modelowania, rozważ rozpoczęcie od istniejącego zestawu modeli zaprojektowanych dla twojej branży zamiast projektowania modeli od podstaw. Firma Microsoft współpracuje z ekspertami z dziedziny, aby tworzyć ontologie modelu DTDL oparte na standardach branżowych, aby pomóc zminimalizować ponowne wynajdywanie i zachęcić do spójności i prostoty w rozwiązaniach branżowych. Możesz dowiedzieć się więcej na temat tych ontologii, w tym jak ich używać i jakie ontologie są teraz dostępne, w temacie Co to jest ontologia?.

Rozważ implikacje dotyczące zapytań

Podczas projektowania modeli w celu odzwierciedlenia jednostek w danym środowisku warto przyjrzeć się przyszłości i rozważyć implikacje zapytania dotyczące projektu. Możesz zaprojektować właściwości w sposób, który pozwoli uniknąć dużych zestawów wyników z przechodzenia grafu. Możesz również modelować relacje, na które należy odpowiedzieć w jednym zapytaniu jako relacje jednopoziomowe.

Weryfikowanie modeli

Po utworzeniu modelu zalecamy zweryfikowanie modeli w trybie offline przed przekazaniem ich do wystąpienia usługi Azure Digital Twins.

Aby ułatwić weryfikowanie modeli, biblioteka analizy DTDL po stronie klienta platformy .NET jest udostępniana w usłudze NuGet: DTDLParser. Bibliotekę analizatora można używać bezpośrednio w kodzie języka C#. Przykładowe użycie analizatora można również wyświetlić w pliku DTDLParserResolveSample w usłudze GitHub.

Zbiorcze przekazywanie i usuwanie modeli

Po zakończeniu tworzenia, rozszerzania lub wybierania modeli należy przekazać je do wystąpienia usługi Azure Digital Twins, aby były dostępne do użycia w Twoim rozwiązaniu.

Wiele modeli można przesłać w jednym wywołaniu interfejsu API przy użyciu API Import Jobs. Interfejs API może jednocześnie zaakceptować limit usługi Azure Digital Twins dla liczby modeli w wystąpieniu i automatycznie zmienić kolejność modeli w razie potrzeby w celu rozwiązania zależności między nimi. Aby uzyskać szczegółowe instrukcje i przykłady korzystające z tego interfejsu API, zobacz instrukcje importowania zbiorczego dla modeli.

Alternatywą dla interfejsu API zadań importu jest przykład moduł przekazujący model, który używa poszczególnych interfejsów API modelu do przekazywania wielu plików modelu jednocześnie. Przykład implementuje również automatyczne zmienianie kolejności w celu rozpoznawania zależności modelu. Obecnie działa tylko w wersji 2 języka DTDL.

Jeśli musisz usunąć wszystkie modele w wystąpieniu usługi Azure Digital Twins jednocześnie, możesz użyć przykładowego narzędzia Model Deleter. Jest to projekt, który zawiera logikę rekursywną do obsługi zależności modelu za pośrednictwem procesu usuwania. Obecnie działa tylko w wersji 2 języka DTDL.

Jeśli chcesz wyczyścić dane w wystąpieniu, usuwając wszystkie modele wraz ze wszystkimi bliźniakami i relacjami, możesz użyć interfejsu API Usuwania Zadań.

Wizualizowanie modeli

Po przekazaniu modeli do wystąpienia usługi Azure Digital Twins możesz je wyświetlić za pomocą eksploratora usługi Azure Digital Twins . Eksplorator zawiera listę wszystkich modeli w wystąpieniu, a także wykres zależności między modelami, który ilustruje, jak są one ze sobą powiązane, w tym wszelkie dziedziczenie i relacje modelu.

Uwaga

Obecnie usługa Azure Digital Twins Explorer w pełni obsługuje modele DTDL w wersji 2 i obsługuje ograniczone funkcje modeli DTDL w wersji 3.

Modele DTDL w wersji 3 można wyświetlić na panelu Modele, a bliźniacze reprezentacje utworzone za pomocą modeli DTDL w wersji 3 można wyświetlać i edytować (w tym bliźniacze reprezentacje z właściwościami tablicy). Jednak modele DTDL w wersji 3 nie są wyświetlane na panelu Model Graph i nie można ich zaimportować przy użyciu narzędzia Azure Digital Twins Explorer. Aby zaimportować modele DTDL w wersji 3 do wystąpienia, użyj innego interfejsu deweloperskiego, takiego jak interfejsy API i zestawy SDK lub Azure CLI.

Oto przykład tego, jak może wyglądać wykres modelu:

Zrzut ekranu przedstawiający eksploratora usługi Azure Digital Twins. Panel Model Graph został wyróżniony.

Aby uzyskać więcej informacji na temat doświadczenia z modelami w Eksploratorze Azure Digital Twins, zobacz Eksplorowanie modeli i Wykres Modelu.

Następne kroki