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

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 でのモデリングに推奨される選択肢です。

これらの機能についてはドキュメントで説明しますが、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 エクスプローラーは DTDL v2 モデルを完全にサポートし、DTDL v3 モデルの限られた機能をサポートしています。 Azure Digital Twins エクスプローラーでは、[モデル] パネルで DTDL v3 モデルを表示でき、DTDL v3 モデルで作成されたツイン (配列プロパティを含む) を表示および編集できます。 ただし、DTDL v3 モデルは [モデル グラフ] パネルに表示されません。また、Azure Digital Twins エクスプローラーを使用してインポートすることはできません。 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;3 DTDL v3 に使用dtmi:dtdl:context;2する必要があります。 DTDL v3 モデルでは、このフィールドに追加 の機能拡張 の名前を付けることもできます。
displayName [省略可能] モデルのわかりやすい名前を定義するオプションを提供します。 このフィールドを使用しない場合、モデルはそれの完全な DTMI 値を使用します。
contents 残りのすべてのインターフェイス データは、属性定義の配列としてここに配置されます。 各属性には、記述する@typeインターフェイス情報の種類を識別するための (PropertyまたはRelationshipComponent) と、実際の属性を定義する一連のプロパティを指定する必要があります。 次のセクションでは、モデル属性 について詳しく説明します。

基本的な 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 モデル インターフェイスには、次の各フィールドの 0、1、または多くを含む場合があります。

  • Property - プロパティは、エンティティの状態を表すデータ フィールドです (多くのオブジェクト指向プログラミング言語のプロパティと同様)。 プロパティはバッキング ストレージを備えていて、いつでも読み取ることができます。 詳細については、以下の「プロパティ」を参照してください

  • Relationship - リレーションシップを使用すると、あるデジタル ツインと他のデジタル ツインの関係性を表すことができます。 リレーションシップは、("floor contains room")、("hvac cools room") cools 、("compressor is billed to user") isBilledTo 、などのcontainsさまざまなセマンティックの意味を表すことができます。 リレーションシップにより、ソリューションは相互に関連するエンティティのグラフを提供できます。 リレーションシップには、独自のプロパティを含めることもできます。 詳細については、以下の「リレーションシップ」を参照してください。

  • Component - コンポーネントを使用すると、必要に応じてモデル インターフェイスを他のインターフェイスの組み合わせとして構築できます。 コンポーネントの例として、電話のモデルの定義に使用されるフロントカメラ インターフェイス (および別のコンポーネント インターフェイスバックカメラ) があります。 まず、frontCamera のインターフェイスを独自のモデルであるかのように定義します。その後、Phone を定義するときに、それを参照します。

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

    ヒント

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

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

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

Note

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

プロパティ

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

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

Note

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

[スキーマ]

DTDL に従って、プロパティ属性のスキーマは、標準のプリミティブ型 (integer標準のプリミティブ型)、doubleおよびbooleanstring他の型 (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

リレーションシップの writableminMultiplicity、および 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 モデルに非コア機能を追加するために使用できる機能拡張 クラスについて説明します。

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

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

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

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

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

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

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

注釈の拡張子

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

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

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

ヒストライゼーション拡張機能

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

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

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

拡張機能のオーバーライド

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

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

この拡張機能の詳細と例については、「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 サービスに対する一般的な書き込みアクセス許可を持つ外部クライアントによって書き込み可能として扱われます。
  • リレーションシップの minMultiplicitymaxMultiplicity プロパティ。 これらの属性は 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 Deleter サンプル使用できます。 これは、削除プロセスを通じてモデルの依存関係を処理する再帰ロジックを含むプロジェクトです。 現在、DTDL のバージョン 2 でのみ機能します

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

モデルの視覚化

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

Note

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

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

Screenshot of Azure Digital Twins Explorer. The Model Graph panel is highlighted.

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

次のステップ