デジタル ツインとツイン グラフについて理解する

Azure Digital Twins ソリューションでは、環境内のエンティティは デジタル ツイン で表されます。 デジタル ツインは、カスタム定義モデルのいずれかのインスタンスです。 それを リレーションシップ によって他のデジタル ツインに接続して、ツイン グラフ を形成できます。このツイン グラフは、環境全体を表しています。

ヒント

"Azure Digital Twins" は、この Azure サービス全体を指します。 "デジタル ツイン" または単に "ツイン" は、サービスのインスタンス内の個々のツイン ノードを指します。

Digital Twins

Azure Digital Twins インスタンスでデジタル ツインを作成するには、"モデル" をサービスにアップロードしておく必要があります。 モデルは、特に、プロパティ、テレメトリ メッセージ、特定のツインが持つことのできるリレーションシップのセットを記述したものです。 モデルで定義される情報の種類については、カスタム モデルに関するページを参照してください。

モデルを作成してアップロードしたら、クライアント アプリはその型のインスタンスを作成できます。これがデジタル ツインです。 たとえば、モデル Floor を作成したら、この型を使用する 1 つまたは複数のデジタル ツイン (GroundFloor という Floor 型ツイン、Floor2 という別のツインなど) を作成できます。

注意

Azure Digital Twins のデジタル ツインは、IoT Hub のデバイス ツインとは異なります。 IoT Hub デバイス ツインは、デバイス自体の側面や機能を記述することに焦点を当てることが多いのに対し、Azure Digital Twins のツインは、デバイスまたは多くの関連するデバイスに関するユーザー定義の分析情報を格納できる、より概念的な表現です。

IoT Hub デバイス ツインは、サービス間のデバイスを表すエンドツーエンド ソリューションの一部として Azure Digital Twins に接続できます。

リレーションシップ: デジタル ツインのグラフ

ツインは、そのリレーションシップによってツイン グラフに接続されます。 ツインが持つことのできるリレーションシップは、そのモデルの一部として定義されます。

たとえば、モデル Floor で、Room 型のツインをターゲットとする contains リレーションシップが定義されているとします。 この定義により、Azure Digital Twins では、任意の Floor ツインから任意の Room ツイン (Room サブタイプのツインを含む) への contains リレーションシップを作成できます。

このプロセスにより、グラフ内にエッジ (リレーションシップ) によって接続された一連のノード (デジタル ツイン) が作成されます。

グラフ

自分の Azure Digital Twins インスタンスは主に、API と SDK を使用して操作しますが、自分のインスタンスで作成しているツインとグラフの視覚化を確認できると便利な場合があります。

Azure Digital Twins エクスプローラーは、Azure Digital Twins を視覚化して操作するためのサンプル アプリケーションです。 サンプルにある手順に従って、アプリケーション コードをダウンロードして実行します。

このサンプルでは、他に作成および管理アクティビティがある中、ご自分のデジタル ツインとそれによって作成されるグラフを視覚的に表示できます。

次に、視覚化の例を示します。

デジタル ツインを表すノードのグラフを示す Azure Digital Twins エクスプローラーのサンプル アプリケーションのスクリーンショット

サンプルは次に使用できます。

  • モデルのアップロードおよび確認
  • ツイン グラフのアップロードと編集
  • さまざまなレイアウト手法を使用したツイン グラフの視覚化
  • ツインのプロパティの編集
  • ツイン グラフに対するクエリの実行

API を使用して作成する

このセクションでは、クライアント アプリケーションからデジタル ツインとリレーションシップを作成する方法について説明します。 これらの各概念の内部で何が行われるかについて追加のコンテキストを提供するため、Digital Twins API を利用する .NET コードの例が含まれています。

デジタル ツインを作成する

DigitalTwins API を使用して、Room 型のツインをインスタンス化するクライアント コードのスニペットを次に示します。

ツインは作成時にそのプロパティを初期化できます。あるいは後で設定できます。 プロパティを初期化してツインを作成するには、必要な初期化値を与える JSON ドキュメントを作成します。

// Define a custom model type for the twin to be created
class CustomDigitalTwin
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
    public string Id { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinETag)]
    public string ETag { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinMetadata)]
    public MyCustomDigitalTwinMetadata Metadata { get; set; } = new MyCustomDigitalTwinMetadata();

    [JsonPropertyName("temperature")]
    public double Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public double Humidity{ get; set; }
}

class MyCustomDigitalTwinMetadata
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.MetadataModel)]
    public string ModelId { get; set; }

    [JsonPropertyName("temperature")]
    public DigitalTwinPropertyMetadata Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public DigitalTwinPropertyMetadata Humidity { get; set; }
}

// Initialize the twin properties
var myTwin = new MyCustomDigitalTwin
{
    Metadata = { ModelId = "dtmi:example:Room;1" },
    Temperature = 25.0,
    Humidity = 50.0,
};
// Create the twin
Response<BasicDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
Console.WriteLine($"Temperature last updated on {response.Value.Metadata.Temperature.LastUpdatedOn}")

ディクショナリを使用する代わりに、BasicDigitalTwin という名称のヘルパー クラスを使用し、"ツイン" オブジェクトにプロパティ フィールドをもっと直接的に格納することもできます。 ヘルパー クラスとその使用例の詳細については、「デジタル ツインを作成するセクション」を参照してください。このセクションは 「デジタル ツインを管理する」方法 を参照してください。

注意

ツイン プロパティはオプションとして扱われ、初期化する必要がありませんが、ツインの作成時にそのあらゆる コンポーネントを設定する 必要があります。 空のオブジェクトにすることができますが、コンポーネント自体は存在する必要があります。

リレーションシップの作成

ここでは、DigitalTwins API を使用して、あるデジタル ツイン ("ソース" ツイン) から別のデジタル ツイン ("ターゲット" ツイン) への関係を構築するクライアント コードの例を示します。

var rel = new BasicRelationship
{
    TargetId = "myTargetTwin",
    Name = "contains", // a relationship with this name must be defined in the model
    // Initialize properties
    Properties =
    {
        { "active", true },
    },
};
await client.CreateOrReplaceRelationshipAsync("mySourceTwin", "rel001", rel);

グラフ要素の JSON 表現

デジタル ツイン データとリレーションシップ データは、どちらも JSON 形式で保存されます。 つまり、Azure Digital Twins インスタンスでツイン グラフのクエリを実行すると、結果は作成済みのデジタル ツインとリレーションシップの JSON 表現になります。

デジタル ツインの JSON 形式

JSON オブジェクトとして表された場合、デジタル ツインには次のフィールドが表示されます。

フィールド名 説明
$dtId デジタル ツインの ID を表すユーザー指定の文字列
$etag Web サーバーによって割り当てられた標準 HTTP フィールド
$conformance このデジタル ツインの適合性状態 (conformantnon-conformantunknown) を含む列挙型
<property-name> JSON のプロパティ値 (string、数値型、またはオブジェクト)
$relationships リレーションシップ コレクションへのパスの URL。 デジタル ツインに発信リレーションシップ エッジがない場合、このフィールドは存在しません。
$metadata.$model [省略可能] このデジタル ツインを特徴付けるモデル インターフェイスの ID
$metadata.<property-name>.desiredValue [書き込み可能なプロパティ専用] 指定されたプロパティの目的の値
$metadata.<property-name>.desiredVersion [書き込み可能なプロパティ専用] 目的の値のバージョン
$metadata.<property-name>.ackVersion デジタル ツインを実装するデバイス アプリによって確認されたバージョン
$metadata.<property-name>.ackCode [書き込み可能なプロパティ専用] デジタル ツインを実装するデバイス アプリによって返される ack コード
$metadata.<property-name>.ackDescription [書き込み可能なプロパティ専用] デジタル ツインを実装するデバイス アプリによって返される ack の説明
<component-name> コンポーネントのプロパティ値とメタデータを含む JSON オブジェクト。ルート オブジェクトの場合と似たものです。 このオブジェクトは、コンポーネントにプロパティがない場合でも存在します。
<component-name>.<property-name> コンポーネントの、JSON のプロパティ値 (string、数値型、またはオブジェクト)
<component-name>.$metadata コンポーネントのメタデータ情報。ルートレベルの $metadata と似たものです。

JSON オブジェクトとして書式設定されたデジタル ツインの例を次に示します。

{
  "$dtId": "Cafe",
  "$etag": "W/\"e59ce8f5-03c0-4356-aea9-249ecbdc07f9\"",
  "Temperature": 72,
  "Location": {
    "x": 101,
    "y": 33
  },
  "component": {
    "TableOccupancy": 1,
    "$metadata": {
      "TableOccupancy": {
        "desiredValue": 1,
        "desiredVersion": 3,
        "ackVersion": 2,
        "ackCode": 200,
        "ackDescription": "OK"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:contoso:Room;1",
    "Temperature": {
      "desiredValue": 72,
      "desiredVersion": 5,
      "ackVersion": 4,
      "ackCode": 200,
      "ackDescription": "OK"
    },
    "Location": {
      "desiredValue": {
        "x": 101,
        "y": 33,
      },
      "desiredVersion": 8,
      "ackVersion": 8,
      "ackCode": 200,
      "ackDescription": "OK"
    }
  }
}

リレーションシップの JSON 形式

JSON オブジェクトとして表された場合、デジタル ツインのリレーションシップには次のフィールドが表示されます。

フィールド名 説明
$relationshipId このリレーションシップの ID を表すユーザー指定の文字列。 この文字列は、ソース デジタル ツインのコンテキストで一意です。つまり、sourceId + relationshipId は、Azure Digital Twins インスタンスのコンテキストで一意になるということでもあります。
$etag Web サーバーによって割り当てられた標準 HTTP フィールド
$sourceId ソース デジタル ツインの ID
$targetId ターゲット デジタル ツインの ID
$relationshipName リレーションシップの名前
<property-name> [省略可能] このリレーションシップの、JSON のプロパティ値 (string、数値型、またはオブジェクト)

JSON オブジェクトとして書式設定されたリレーションシップの例を次に示します。

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

次のステップ

Azure Digital Twins の API を使用してグラフ要素を管理する方法を確認します。

または、Azure Digital Twins のツイン グラフに対して情報のクエリを行う方法について学習します。