ツインモデルについて、および Azure Digital Twins で定義する方法について説明します。

[アーティクル]
01/04/2024

Azure Digital Twins の重要な特性は、独自のボキャブラリを定義し、ビジネスの自己定義用語でツイングラフを構築できることです。この機能は、ユーザー提供のモデルを通じて提供されます。モデルは、世界を説明するための名詞と考えることができます。 Azure Digital Twins のモデルは、JSON-LD ベースの Digital Twin Definition language (DTDL) で表現されます。

モデルは、オブジェクト指向プログラミング言語のクラスに似ており、実際の作業環境における 1 つの特定の概念のデータシェイプを定義します。モデルには名前 (Room や TemperatureSensor など) があり、プロパティ、コンポネント、環境内でこの型のエンティティに何ができるかを説明するリレーションシップなどの要素が含まれています。後で、これらのモデルを使用して、この型の説明と一致する特定のエンティティを表すデジタルツインを作成します。

モデル用の Digital Twin Definition Language (DTDL)

Azure Digital Twins のモデルは、Digital Twins Definition language (DTDL) を使用して定義されます。

DTDL v3 の完全な言語の説明は、GitHub で確認できます: DTDL バージョン 3 言語の説明。このページには、独自の DTDL モデルを作成し始める際に役立つ詳細な DTDL リファレンスと例が含まれています。

DTDL は JSON-LD に基づいており、プログラミング言語に依存しません。 DTDL は Azure Digital Twins 専用ではありません。 IoT プラグアンドプレイなどの他の IoT サービスのデバイスデータを表すためにも使用されます。

この記事の残りの部分では、Azure Digital Twins で言語を使用する方法について説明します。

サポートされている DTDL バージョン

Azure Digital Twins では DTDL バージョン 2 および 3 がサポートされています (このドキュメントではそれぞれ v2 および v3 と短縮して表記されています)。 V3 は、次のような拡張された機能に基づいて、Azure Digital Twins でのモデリングに推奨される選択肢です:

DTMI バージョンリラクゼーション
プロパティの配列サポート
モデルの継承の制限の増加
機能拡張
- セマンティック型でカスタムインターフェイススキーマを装飾する機能 (QuantitativeTypes 拡張機能で提供)

これらの機能についてはドキュメントで説明しますが、DTDL v3 でのみ利用可能な点に注意してください。 DTDL v2 と v3 の違いの完全なリストについては、「DTDL v3 言語の説明: バージョン 2 からの変更」を参照してください。

Azure Digital Twins では、同じインスタンス内での v2 モデルと v3 モデルの組み合わせの使用もサポートされています。両方のバージョンのモデルを一緒に使用する場合は、次の制限事項に注意してください:

v2 インターフェイスは、v3 インターフェイスを拡張、または v3 インターフェイスをスキーマとしてのコンポーネントを持つことはできません。
逆に、v3 インターフェイスは v2 インターフェイスを拡張でき、v3 インターフェイスは v2 インターフェイスをスキーマとしてのコンポーネントを持つことができます。
リレーションシップは、v2 モデルソースから v3 モデルターゲット、またはその逆の方向、または v3 モデルソースから v2 モデルターゲットを指すことができます。

既存の v2 モデルを v3 に移行することもできます。これを行う方法については、「v2 モデルを v3 に変換する」を参照してください。

Note

現在、Azure Digital Twins Explorer は DTDL v2 モデルを完全にサポートしており、DTDL v3 モデルの制限された機能をサポートしています。

[モデル] パネルで DTDL v3 モデルを表示でき、DTDL v3 モデルで作成されたツインを表示および編集できます (配列プロパティを持つものを含む)。ただし、DTDL v3 モデルは [モデルグラフ] パネルに表示されず、Azure Digital Twins Explorer を使用してこれらをインポートすることはできません。 DTDL v3 モデルをインスタンスにインポートするには、API と SDK や Azure CLI などの別の開発者インターフェイスを使用します。

モデルの概要

ツインの型モデルは、任意のテキストエディターで記述できます。 DTDL 言語は、JSON 構文に従います。そのため、モデルは json という拡張子で保存する必要があります。 JSON 拡張子を使用すると、多くのプログラミングテキストエディターで、DTDL ドキュメントの基本的な構文チェックと強調表示ができるようになります。また、Visual Studio Code では、DTDL 拡張子も使用できます。

モデルインターフェイス内のフィールドを次に示します。

フィールド	説明
`@id`	モデルのデジタルツインモデル識別子 (DTMI)、`dtmi:<domain>:<unique-model-identifier>;<model-version-number>` 形式。 DTDL v3 では、バージョン番号を省略することも、2 部構成の (`<major>.<minor>`) バージョン番号として構造化することもできます。
`@type`	記述されている情報の種類を識別します。インターフェイスの場合、型は `Interface` です。
`@context`	JSON ドキュメントのコンテキストを設定します。モデルでは、DTDL v2 には `dtmi:dtdl:context;2` を使用し、DTDL v3 には `dtmi:dtdl:context;3` を使用する必要があります。 DTDL v3 モデルでは、このフィールドに追加の機能拡張に名前を付けることもできます。
`displayName`	[省略可能] モデルのわかりやすい名前を定義するオプションを提供します。このフィールドを使用しない場合、モデルはそれの完全な DTMI 値を使用します。
`contents`	残りのすべてのインターフェイスデータは、属性定義の配列としてここに配置されます。各属性には、それが表現するインターフェイス情報の種類を識別するための `@type` (`Property`、`Relationship`、または `Component`) と、実際の属性を定義する一連のプロパティを指定する必要があります。次のセクションでは、モデル属性について詳しく説明します。

基本的な DTDL モデルの例を次に示します。このモデルでは、ID に 1 つのプロパティを持つ Home が記述されています。また、Home モデルは、Floor モデルとのリレーションシップも定義します。これは、Home ツインが特定の 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"
    }
  ]
}

モデル属性

モデルに関する主な情報は、モデルインターフェイスの contents セクション内で定義する属性によって提供されます。

Azure Digital Twins でサポートされている DTDL で使用できる属性を次に示します。 Azure Digital Twins で使用される DTDL モデルのインターフェイスには、以下の各フィールドをゼロ個、1 個、または複数個、含めることができます:

Property - プロパティは、エンティティの状態を表すデータフィールドです (多くのオブジェクト指向プログラミング言語のプロパティと同様)。プロパティはバッキングストレージを備えていて、いつでも読み取ることができます。詳細については、以下の「プロパティ」を参照してください。
Relationship - リレーションシップを使用すると、あるデジタルツインと他のデジタルツインの関係性を表すことができます。リレーションシップは、さまざまなセマンティックな意味を表す可能性があります。たとえば、contains ("フロアに部屋が含まれる")、cools ("hvac によって部屋が冷やされる")、isBilledTo ("コンプレッサーがユーザーに請求される") などです。リレーションシップにより、ソリューションは相互に関連するエンティティのグラフを提供できます。リレーションシップには、独自のプロパティを含めることもできます。詳細については、以下の「リレーションシップ」を参照してください。
Component - コンポーネントを使用すると、必要に応じてモデルインターフェイスを他のインターフェイスの組み合わせとして構築できます。コンポーネントの例として、"電話" のモデルの定義に使用される frontCamera インターフェイス (およびもう 1 つのコンポーネントインターフェイスである backCamera) があります。まず、frontCamera のインターフェイスを独自のモデルであるかのように定義します。その後、Phone を定義するときに、それを参照します。

コンポーネントを使用するのは、ソリューションの不可欠な要素でありながら、個別の ID を必要とせず、ツイングラフで独立して作成、削除、および再配置する必要がないものを記述する場合です。エンティティがツイングラフ内で独立した存在になるようにするには、それらを異なるモデルの個別のデジタルツインとして表現し、「リレーションシップ」で接続します。

ヒント

コンポーネントは、モデルインターフェイス内の関連するプロパティをグループ化するために、組織に使用することもできます。この状況では、各コンポーネントをインターフェイス内の名前空間または "フォルダー" と考えることができます。

詳細については、以下の「コンポーネント」を参照してください。

DTDL v3 言語の説明では、コマンド と テレメトリ も定義されていますが、これらはどちらも Azure Digital Twins では使用されていません。コマンドはサポートされておらず、テレメトリはモデル定義で許可されていますが、Azure Digital Twins モデリングでは一意のユースケースはありません。 DTDL テレメトリを使用する代わりに、ツインの状態情報を格納するために DTDL プロパティを使用する必要があります。

Note

受信デバイスデータを格納するために DTDL モデルでテレメトリフィールドを定義する必要はありませんが、Azure Digital Twins では、SendTelemetry API を使用してテレメトリとしてイベントを出力できます。これにより、 Digital Twin テレメトリメッセージイベントがトリガーされます。イベントハンドラーは、他のツインに対してアクションを実行したり、ダウンストリームサービスをトリガーしたりできます。

プロパティ

このセクションでは、DTDL モデルのプロパティについて詳しく説明します。

プロパティの一部として表示される可能性のあるフィールドに関する包括的な情報については、「DTDL v3 言語の説明」を参照してください。

Note

プロパティの writable DTDL 属性は、Azure Digital Twins で現在サポートされていません。これはモデルに追加できますが、Azure Digital Twins によって適用されることはありません。詳細については、「サービス固有の DTDL に関する注意事項」を参照してください。

[スキーマ]

DTDL に従って、プロパティ属性のスキーマには、標準のプリミティブ型 (integer、double、string、および boolean) およびその他の型 (dateTime、duration など) を指定できます。。

プリミティブ型のほか、プロパティフィールドには、これらの複合型を含むことができます:

Object
Map
Enum
Array、DTDL v3 のみ。プロパティの Array 型は、DTDL v2 ではサポートされていません。

また、セマンティック型にすることもできます。この型を使用すると、値に単位の注釈を付けることができます。 DTDL v2 では、セマンティック型がネイティブにサポートされています。DTDL v3 では、機能拡張機能に含めることができます。

基本プロパティの例

DTDL モデルのプロパティの基本的な例を次に示します。この例では、Home の ID プロパティを示しています。

{
  "@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"
    }
  ]
}

複合オブジェクト型の例

プロパティは、Object 型などの複合型にすることができます。

次の例は、アドレスのプロパティを持つ Home モデルの別のバージョンを示しています。 address はオブジェクトであり、番地、市区町村、都道府県、および郵便番号の独自のフィールドを持っています。

{
  "@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"
        }
      ]
    }
  ]
}

DTDL v2 セマンティック型の例

セマンティック型は、単位で値を表します。 Azure Digital Twins のプロパティでは、DTDL でサポートされている任意のセマンティック型を使用できます。

DTDL v2 では、セマンティック型はネイティブでサポートされています。 DTDL v2 のセマンティック型の詳細については、「DTDL v2 言語の説明のセマンティック型」を参照してください。 DTDL v3 のセマンティック型の詳細については、「QuantitativeTypes DTDL v3 機能拡張」を参照してください。

次の例は、湿度と温度のセマンティック型プロパティを持つ DTDL v2 センサーモデルを示しています。

{
  "@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" 
    }
  ]
}

重要

"Property" は、@type 配列の最初の要素の後にセマンティック型が続く必要があります。そうしないと、Azure Digital Twins Explorer にフィールドが表示されない可能性があります。

リレーションシップ

このセクションでは、DTDL モデルのリレーションシップについて詳しく説明します。

リレーションシップの一部として表示される可能性があるフィールドの包括的な一覧については、「DTDL v3 言語の説明のリレーションシップ」を参照してください。

Note

リレーションシップの writable、minMultiplicity、および maxMultiplicity DTDL 属性は、Azure Digital Twins で現時点ではサポートされていません。これらはモデルに追加できますが、Azure Digital Twins によって適用されません。詳細については、「サービス固有の DTDL に関する注意事項」を参照してください。

基本的なリレーションシップの例

DTDL モデルのリレーションシップの基本的な例を次に示します。この例では、Floor モデルへの接続を可能にする Home モデルのリレーションシップを示します。

{
  "@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"
    }
  ]
}

Note

リレーションシップについては、@id はオプションのフィールドです。 @id が指定されていない場合、デジタルツインインターフェイスプロセッサは 1 を割り当てます。

対象および対象外のリレーションシップ

リレーションシップは、ターゲットを指定するか、指定せずに定義することができます。ターゲットは、リレーションシップが到達できるツインの種類を指定します。たとえば、Home モデルが Floor ツインであるツインとのみ rel_has_floors リレーションシップを持つことができるように指定するターゲットを含めることができます。

場合によっては、特定のターゲットなしでリレーションシップを定義して、リレーションシップがさまざまな種類のツインに接続できるようにする必要がある場合があります。

ターゲットを持たない DTDL モデルのリレーションシップの例を次に示します。この例では、リレーションシップは Room に含まれる可能性があるセンサーを定義するためのものであり、リレーションシップは任意の種類に接続できます。

{
  "@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"

リレーションシップのプロパティ

DTDL を使用すると、リレーションシップに独自のプロパティを含めることもできます。 DTDL モデル内でリレーションシップを定義する際に、リレーションシップに独自の properties フィールドを含めることができます。このフィールドで、リレーションシップ固有の状態を記述するカスタムプロパティを定義できます。

次の例は、別のバージョンの Home モデルを示しています。rel_has_floors リレーションシップには、関連する Floor が最後に占有された時間を表すプロパティがあります。

{
  "@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"
        }
      ]
    }
  ]
}

コンポーネント

このセクションでは、DTDL モデルのコンポーネントについて詳しく説明します。

コンポーネントの一部として表示される可能性のあるフィールドの包括的な一覧については、「DTDL v3 言語の説明」を参照してください。

基本的なコンポーネントの例

DTDL モデルのコンポーネントの基本的な例を次に示します。この例では、コンポーネントとしてサーモスタットモデルを使用する Room モデルを示します。

[
  {
    "@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"
      }
    ]
  }
]

このソリューション内の他のモデルにもサーモスタットが含まれている必要がある場合は、Room の場合と同様に、独自の定義でコンポーネントと同じサーモスタットモデルを参照することができます。

重要

コンポーネントの参照が見つかるようにするには、コンポーネントインターフェイス (上記の例ではサーモスタット) を、それを使用するすべてのインターフェイス (上の例では Room) と同じ配列で定義する必要があります。

モデルの継承

場合によっては、モデルをさらに特殊化したい場合があります。たとえば、汎用的なモデル Room と、特殊化したバリアント ConferenceRoom および Gym を作成すると便利な場合があります。特殊化を表現するため、DTDL では "継承" がサポートされています。インターフェイスは、1 つ以上の他のインターフェイスから継承できます。これを行うには、モデルに extends フィールドを追加します。

extends セクションは、インターフェイス名、またはインターフェイス名の配列です (拡張インターフェイスで複数の親モデルを継承できます)。 1 つの親は、複数の拡張インターフェイスの基本モデルとして機能できます。

Note

DTDL v2 では、各 extends には最大 2 つのインターフェイスを一覧表示できます。 DTDL v3 では、extends の即時値の数に制限はありません。

DTDL v2 と v3 の両方で、extends 階層の合計深度制限は 10 です。

次の例では、Home モデルを前の DTDL 例からより大きな「コア」モデルのサブタイプとして再イメージ化しています。親モデル (Core) が先に定義され、次に extends を使用してその上に子モデル (Home) が構築されます。

{
    "@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": [
    {

この場合、Core は ID と名前を Home に提供します。他のモデルでは、Core モデルを拡張してこれらのプロパティを取得することもできます。同じ親インターフェイスを拡張する Room モデルを次に示します。

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

継承が適用されると、拡張インターフェイスは継承チェーン全体のすべてのプロパティを公開します。

拡張インターフェイスでは、親インターフェイスの定義は変更できません。定義の追加のみ行うことができます。また、いずれかの親インターフェイスで既に定義されている機能を再定義することもできません (機能が同じになるように定義される場合でも)。たとえば、親インターフェイスで double のプロパティ mass が定義されている場合、拡張インターフェイスに mass の宣言を含めることはできません (それが同様に double である場合でも)。

DTDL v3 機能拡張

DTDL v3 では追加のメタモデルクラスを定義する言語拡張機能を使用できます。このクラスを使用すると、より豊富なモデルを記述できます。このセクションでは、DTDL v3 モデルに非コア機能を追加するために使用できる機能拡張クラスについて説明します。

各機能拡張は、コンテキスト指定子によって識別されます。これは、一意の Digital Twin Model Identifier (DTMI) 値です。モデルで機能拡張を有効にするには、拡張機能のコンテキスト指定子をモデルの @context フィールドに追加します (dtmi:dtdl:context;3 の一般的な DTDL コンテキスト指定子と共に)。同じモデルに複数の機能拡張を追加できます。

機能拡張の @context フィールドの例を次に示します。次は、QuantitativeTypes 拡張機能と注釈拡張機能の両方を使用するモデルからの抜粋です。

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

モデルに機能拡張機能を追加すると、その拡張機能のモデル内の補助型にアクセスできるようになります。 DTDL 要素の @type フィールドに補助型を追加して、要素に追加の機能を提供できます。補助型は、要素に追加のプロパティを追加できます。

たとえば、注釈拡張機能を使用しているモデルからの抜粋を次に示します。この拡張機能には、次の例でプロパティ要素に追加される ValueAnnotationという補助型があります。この補助型を property 要素に追加すると、要素に追加の annotates フィールドを設定できます。このフィールドは、この要素によって注釈が付けられた別のプロパティを示すために使用されます。

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

このセクションの残りの部分では、注釈拡張機能とその他の DTDL v3 機能拡張機能について詳しく説明します。

注釈拡張機能

注釈拡張機能 は、DTDL v3 モデルのプロパティ要素にカスタムメタデータを追加するために使用されます。そのコンテキスト指定子は dtmi:dtdl:extension:annotation;1。

この拡張機能には、DTDL プロパティ要素に追加できる ValueAnnotation の補助型が含まれています。 ValueAnnotation 型は、annotates要素に 1 つのフィールドを追加します。現在の要素によって注釈が付けられた別のプロパティに名前を付けることができます。

この拡張機能の詳細と例については、「DTDL v3 言語の説明の注釈拡張機能」を参照してください。

Historization 拡張機能

Historization 拡張機能 は、DTDL v3 モデルのプロパティを履歴に記録する必要があるものとして指定するために使用されます (値の履歴シーケンスと値が変更された時刻を記録する必要があります)。そのコンテキスト指定子は dtmi:dtdl:extension:historization;1 です。

この拡張機能には、Historized 補助型が含まれています。これは、DTDL プロパティ要素に共同型として追加して、サービスが要素の履歴値を保持し、クエリと分析に使用できるようにする必要があることを示します。 Historized 補助型では、要素にフィールドは追加されません。

この拡張機能の詳細と例については、「DTDL v3 言語の説明の Historization 拡張機能」を参照してください。

オーバーライド拡張機能

オーバーライド拡張機能は、DTDL V3 モデルのプロパティをインスタンス値でオーバーライドするために使用されます。これは、注釈拡張機能と組み合わせて使用され、そのコンテキスト指定子が dtmi:dtdl:extension:overriding;1 です。

この拡張機能には、Override の補助型が含まれます。これは、(注釈拡張からの) ValueAnnotation と共に型指定し、DTDL プロパティに追加できます。 Override 型では、要素 overrides に 1 つのフィールドを追加します。これにより、注釈付き要素のフィールドに現在の要素の値によってオーバーライドされる名前を付けることができます。

この拡張機能の詳細と例については、「DTDL v3 言語の説明のオーバーライド拡張機能」を参照してください。

QuantitativeTypes 拡張機能

QuantitativeTypes 拡張機能 は、DTDL v3 モデルでセマンティック型、単位型、および単位を有効にするために使用されます。そのコンテキスト指定子は dtmi:dtdl:extension:quantitativeTypes;1 です。

この拡張機能を使用すると、多くのセマンティック型を補助型として使用できます。これは、CommandRequest、Field、MapValue、または DTDL v3 のプロパティに追加できます。セマンティック型は、unit 要素に 1 つのフィールドを追加します。このフィールドは、セマンティック型に対応する有効な単位を受け入れます。

サポートされているセマンティック型と単位の例や完全な一覧など、拡張機能の詳細については、「DTDL v3 言語の説明のQuantitativeTypes 拡張機能」を参照してください。

サービス固有の DTDL に関する注意事項

DTDL を使用するすべてのサービスで、DTDL の機能がまったく同じに実装されるわけではありません。いくつかの DTDL 機能は Azure Digital Twins で現在サポートされていません。次に例を示します。

DTDL コマンド
プロパティまたはリレーションシップの writable 属性。この属性は DTDL 仕様に従って設定できますが、Azure Digital Twins では使用しません。代わりに、これらの属性は常に、Azure Digital Twins サービスに対する一般的な書き込みアクセス許可を持つ外部クライアントによって書き込み可能として扱われます。
リレーションシップの minMultiplicity と maxMultiplicity プロパティ。これらの属性は DTDL 仕様に従って設定できますが、値は Azure Digital Twins によって適用されません。

DTDL モデルに Azure Digital Twins との互換性を与えるには、これらの要件も満たす必要があります。

モデルの最上位レベルの DTDL 要素は、すべて Interface 型である必要があります。この要件の理由は、Azure Digital Twins モデル API で、インターフェイスまたはインターフェイスの配列のいずれかを表す、JSON オブジェクトを受け取ることができるためです。その結果、最上位レベルでは他の DTDL 要素型を使用できません。
Azure Digital Twins の DTDL では、"コマンド" を定義しないでください。
Azure Digital Twins では、単一レベルのコンポーネントの入れ子のみを許可します。これは、コンポーネントとして使用されているインターフェイス自体にはコンポーネントを含められないことを意味します。
インターフェイスは、他の DTDL インターフェイスの内部にインラインで定義することはできません。それらは、独自の ID を備えた個別の最上位レベルのエンティティとして定義する必要があります。その後、別のインターフェイスがそのインターフェイスをコンポーネントとして含めるか、継承を通じて含めようとする場合は、その ID を参照できます。

モデリングツールとベストプラクティス

このセクションでは、モデリングに関するその他の考慮事項と推奨事項について説明します。

既存の業界標準のオントロジの使用

オントロジとは、製造、ビルの構造、IoT システム、スマートシティ、エネルギーグリッド、Web コンテンツなど、特定のドメインを包括的に記述したモデルのセットです。

ソリューションが、いずれかの種類のモデリング標準を使用する特定の業界に対するものである場合、モデルをゼロから設計するのではなく、業界向けに設計された既存のモデルセットから始めることを検討してください。 Microsoft は、各分野の専門家と提携して業界標準に基づく DTDL モデルオントロジを作成することで、再発明を最小限に抑え、業界ソリューション全体で一貫性とシンプルさが促進されるようにしました。これらのオントロジの詳細 (使用方法や現在提供されているオントロジなど) については、「オントロジとは」を参照してください。

クエリの影響を考慮する

環境内のエンティティを反映するようにモデルを設計するときには、先を考えること、および設計に対するクエリの影響を考慮することが有益です。グラフのトラバーサルから大きな結果セットが生成されない方法で、プロパティを設計することができます。また、1 つのクエリで回答される必要があるリレーションシップを、単一レベルのリレーションシップとしてモデル化することもできます。

モデルを検証する

モデルの作成後、モデルは、Azure Digital Twins インスタンスにアップロードする前に、オフラインで検証することが推奨されます。

モデルを検証するために、.NET クライアント側 DTDL 解析ライブラリが NuGet: DTDLParser に用意されています。 C# コードのパーサーライブラリを直接使用できます。 GitHub の DTDLParserResolveSample でパーサーの使用例を参照することもできます。

モデルを一括でアップロードおよび削除する

モデルの作成、拡張、または選択が完了したら、それらをお使いのソリューションで使用できるように、Azure Digital Twins インスタンスにアップロードする必要があります。

Import Jobs API を使用して、1 つの API 呼び出しで多数のモデルをアップロードできます。この API は、1 つのインスタンス内のモデルの数に関する Azure Digital Twins の制限の限度まで同時に受け入れることができ、それらのモデル間の依存関係を解決する必要がある場合は自動的に並べ替えます。この API を使用する詳細な手順と例については、「モデルの一括インポート手順」を参照してください。

Import Jobs API の代わりに、モデルアップローダーサンプルがあります。このサンプルでは、個々のモデル API を使用して複数のモデルファイルを一度にアップロードします。このサンプルでは、モデルの依存関係を解決するための自動並べ替えも実装されています。現在、DTDL のバージョン 2 でのみ動作します。

Azure Digital Twins インスタンス内のすべてのモデルを一度に削除する必要がある場合は、Model デリーターサンプルを使用できます。これは、削除プロセスを通じてモデルの依存関係を処理する再帰ロジックを含むプロジェクトです。現在、DTDL のバージョン 2 でのみ動作します。

または、すべてのツインとリレーションシップと共にすべてのモデルを削除してインスタンス内のデータを消去する場合は、Delete Jobs API を使用できます。

モデルの視覚化

Azure Digital Twins インスタンスにモデルをアップロードすると、 Azure Digital Twins Explorer を使用してモデルを表示できるようになります。エクスプローラーには、インスタンス内のすべてのモデルの一覧と、継承やモデルのリレーションシップなど、相互の関係を示す モデルグラフ が含まれています。

Note

現在、Azure Digital Twins Explorer は DTDL v2 モデルを完全にサポートしており、DTDL v3 モデルの制限された機能をサポートしています。

モデルグラフがどのように見えるかの例を次に示します。

Azure Digital Twins Explorer でのモデルエクスペリエンスの詳細については、「モデルとモデルグラフの参照」を参照してください。

次のステップ

業界標準のオントロジに基づいてモデルを作成する方法について学習してください。オントロジとは?
API 操作によるモデルの管理について詳しく学習してください。DTDL モデルを管理する
「デジタルツインとツイングラフ」でモデルを使用してデジタルツインを作成する方法について確認する

次の方法で共有

ツインモデルについて、および Azure Digital Twins で定義する方法について説明します。

モデル用の Digital Twin Definition Language (DTDL)

サポートされている DTDL バージョン

モデルの概要

モデル属性

プロパティ

[スキーマ]

基本プロパティの例

複合オブジェクト型の例

DTDL v2 セマンティック型の例

リレーションシップ

基本的なリレーションシップの例

対象および対象外のリレーションシップ

リレーションシップのプロパティ

コンポーネント

基本的なコンポーネントの例

モデルの継承

DTDL v3 機能拡張

注釈拡張機能

Historization 拡張機能

オーバーライド拡張機能

QuantitativeTypes 拡張機能

サービス固有の DTDL に関する注意事項

モデリングツールとベストプラクティス

既存の業界標準のオントロジの使用

クエリの影響を考慮する

モデルを検証する

モデルを一括でアップロードおよび削除する

モデルの視覚化

次のステップ

フィードバック

フィードバック

その他のリソース

次の方法で共有

ツイン モデルについて、および Azure Digital Twins で定義する方法について説明します。

モデル用の Digital Twin Definition Language (DTDL)

サポートされている DTDL バージョン

モデルの概要

モデル属性

プロパティ

[スキーマ]

基本プロパティの例

複合オブジェクト型の例

DTDL v2 セマンティック型の例

リレーションシップ

基本的なリレーションシップの例

対象および対象外のリレーションシップ

リレーションシップのプロパティ

コンポーネント

基本的なコンポーネントの例

モデルの継承

DTDL v3 機能拡張

注釈拡張機能

Historization 拡張機能

オーバーライド拡張機能

QuantitativeTypes 拡張機能

サービス固有の DTDL に関する注意事項

モデリング ツールとベスト プラクティス

既存の業界標準のオントロジの使用

クエリの影響を考慮する

モデルを検証する

モデルを一括でアップロードおよび削除する

モデルの視覚化

次のステップ

フィードバック

フィードバック

その他のリソース

ツインモデルについて、および Azure Digital Twins で定義する方法について説明します。

モデリングツールとベストプラクティス