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

Artykuł
01/04/2024

Kluczową cechą usługi Azure Digital Twins jest możliwość definiowania własnego słownictwa i tworzenia grafu bliźniaczej reprezentacji w zdefiniowanych samodzielnie terminach 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:

Złagodzenie wersji DTMI
Obsługa tablicy dla właściwości
Zwiększone limity dziedziczenia modelu
Rozszerzenia funkcji
- Możliwość dekorowania niestandardowych schematów interfejsu za pomocą typów semantycznych (dostarczanych z rozszerzeniem QuantitativeTypes)

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 różnych modeli w wersji 2 i 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 rozszerzyć interfejsu w wersji 3 lub mieć składnika z interfejsem w wersji 3 jako jego schematu.
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 te z właściwościami tablicy). Jednak modele DTDL w wersji 3 nie będą wyświetlane w panelu Model Graph i nie można ich zaimportować przy użyciu eksploratora usługi Azure Digital Twins. Aby zaimportować modele DTDL w wersji 3 do wystąpienia, użyj innego interfejsu deweloperskiego, takiego jak interfejsy API i zestawy SDK lub interfejs wiersza polecenia platformy Azure.

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 cyfrowej reprezentacji bliźniaczej (DTMI) dla modelu 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 być używane `dtmi:dtdl:context;2` w przypadku języka DTDL w wersji 2 lub `dtmi:dtdl:context;3` 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 podać `@type` element (`Property`, `Relationship`, lub `Component`), aby zidentyfikować opis rodzaju informacji o interfejsie, 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 domowy definiuje również relację z modelem Floor, który może służyć do wskazania, że bliźniacze reprezentacje główne są połączone z niektórymi bliźniaczymi reprezentacjami podłogowymi.

{
  "@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 reprezentacja cyfrowej reprezentacji bliźniaczej może być zaangażowana w inne cyfrowe reprezentacje bliźniacze. Relacje mogą reprezentować różne znaczenia semantyczne, takie jak contains ("piętro zawiera pomieszczenie"), ("pomieszczenie chłodne hvac"), cools ("kompresor jest rozliczany dla użytkownika"), isBilledTo 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 zmieniane niezależnie w grafie bliźniaczej reprezentacji. Jeśli chcesz, aby jednostki miały niezależne istnienia na grafie reprezentacji bliźniaczej, reprezentują je jako oddzielne cyfrowe reprezentacje bliźniacze 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źniaczej reprezentacji.

Uwaga

Chociaż nie ma potrzeby definiowania pól telemetrycznych 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 komunikatu telemetrii usługi Digital Twin, które może zostać odebrane przez program obsługi zdarzeń w celu wykonania akcji w innych bliźniaczych reprezentacjach lub wyzwalania 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, stringi — i innymi typami, takimi jak dateTime i booleanduration.

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 języku DTDL w wersji 2.

Mogą być również typami semantycznymi, które umożliwiają dodawanie adnotacji do wartości z 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 strony głównej.

{
  "@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 typem Object .

W poniższym przykładzie pokazano inną wersję modelu Home z właściwością dla jej adresu. 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, po którym następuje typ semantyczny. W przeciwnym razie pole może nie być widoczne 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

writableAtrybuty , minMultiplicityi 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 macierzysym, który umożliwia mu nawiązanie połączenia z modelem Floor.

{
  "@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 nie @id zostanie podany, procesor interfejsu cyfrowej reprezentacji bliźniaczej przypisze jeden.

Relacje docelowe i nienależące do celu

Relacje można definiować z elementem docelowym lub bez. Element docelowy określa typy bliźniaczych reprezentacji, z którymi może się połączyć relacja. Możesz na przykład uwzględnić element docelowy, aby określić, że model domowy może mieć relację rel_has_floors tylko z bliźniaczymi reprezentacjami bliźniaczymi.

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

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 Temat Składnik w opisie języka DTDL w wersji 3.

Przykład podstawowego składnika

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

[
  {
    "@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 co składnik we własnych definicjach, podobnie jak w przypadku pokoju.

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 pokoju modelu i 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 element nadrzędny może służyć jako model podstawowy dla wielu rozszerzeń 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 języków DTDL w wersji 2 i 3 łączny limit głębokości dla extends hierarchii wynosi 10.

Poniższy przykład ponownie wyobraża sobie model macierzystym 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 współtworzy identyfikator i nazwę strony głównej. 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 dziedziczenia rozszerzenie interfejsu 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, rozszerzenie interfejsu 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 cyfrowej reprezentacji bliźniaczej (DTMI). Aby włączyć rozszerzenie funkcji w modelu, dodaj specyfikator kontekstu rozszerzenia do pola modelu @context (wraz z ogólnym specyfikatorem kontekstu DTDL ).dtmi: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 rozszerzenia adnotacji.

  "@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 adjunct tego rozszerzenia w modelu. Możesz dodać typy adjunct do @type pola elementu DTDL, aby nadać elementowi dodatkowe możliwości. Typ adjunct może dodać dodatkowe właściwości do elementu.

Na przykład poniżej przedstawiono fragment modelu używającego rozszerzenia adnotacji. 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 ValueAnnotation typ adjunct, który można dodać do elementu właściwości DTDL. Typ ValueAnnotation dodaje jedno pole do elementu , annotatesco umożliwia nadenie innej właściwości adnotacji bieżącego elementu.

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 Historized typ adjunct, 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ępnić je do wykonywania zapytań i analizy. 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).

Zastępowanie rozszerzenia

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

To rozszerzenie zawiera Override typ adjunct, który można dodać do właściwości DTDL, która jest również współpisana ValueAnnotation z (z rozszerzenia adnotacji). Typ Override dodaje jedno pole do elementu , overridesco umożliwia nadsyłanie nazwy pola w elemencie z adnotacjami 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 i 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 adjunct, które można dodać do elementu CommandRequest, Field, MapValue lub właściwości w języku DTDL w wersji 3. Typy semantyczne dodaj jedno pole do elementu , unitktóry 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 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.

Korzystanie z istniejących nałogów standardowych 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ć dzienniki modelu DTDL oparte na standardach branżowych, aby pomóc zminimalizować ponowne tworzenie pomysłów i zachęcić do spójności i prostoty w różnych rozwiązaniach branżowych. Możesz dowiedzieć się więcej na temat tych nalogów, w tym jak ich używać i jakie dzienniki 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 zaleca się 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 udostępnić je do użycia w rozwiązaniu.

Wiele modeli można przekazać w jednym wywołaniu interfejsu API przy użyciu interfejsu API importu zadań. 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ładu 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 też chcesz wyczyścić dane w wystąpieniu, usuwając wszystkie modele wraz ze wszystkimi reprezentacjami bliźniaczymi 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 modelu, który ilustruje, jak są ze sobą powiązane, w tym wszelkie relacje dziedziczenia i 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.

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

Aby uzyskać więcej informacji na temat środowiska modelu w Eksploratorze usługi Azure Digital Twins, zobacz Eksplorowanie modeli i wykres modelu.

Następne kroki

Dowiedz się więcej o tworzeniu modeli na podstawie standardowych w branży nalogów: Co to jest ontologia?
Dowiedz się więcej na temat zarządzania modelami za pomocą operacji interfejsu API: Zarządzanie modelami DTDL
Dowiedz się, jak modele są używane do tworzenia cyfrowych reprezentacji bliźniaczych: cyfrowe reprezentacje bliźniacze i graf bliźniaczych reprezentacji bliźniaczych

Udostępnij za pośrednictwem

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

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

Obsługiwane wersje języka DTDL

Omówienie modelu

Atrybuty modelu

Właściwości

Schemat

Podstawowy przykład właściwości

Przykład typu obiektu złożonego

Przykład semantycznego typu DTDL w wersji 2

Relacje

Podstawowy przykład relacji

Relacje docelowe i nienależące do celu

Właściwości relacji

Składniki

Przykład podstawowego składnika

Dziedziczenie modelu

Rozszerzenia funkcji DTDL w wersji 3

Rozszerzenie adnotacji

Rozszerzenie historyzacji

Zastępowanie rozszerzenia

Rozszerzenie QuantitativeTypes

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

Narzędzia do modelowania i najlepsze rozwiązania

Korzystanie z istniejących nałogów standardowych w branży

Rozważ implikacje dotyczące zapytań

Weryfikowanie modeli

Zbiorcze przekazywanie i usuwanie modeli

Wizualizowanie modeli

Następne kroki

Opinia

Dodatkowe zasoby