デジタルツインとツイングラフ

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

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

ヒント

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

Digital Twins

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

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

Note

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 Explorer は、Azure Digital Twins グラフ内のデータを探索するためのビジュアルツールです。エクスプローラーを使用して、モデル、ツイン、リレーションシップを表示、クエリ、編集できます。

Azure Digital Twins Explorer ツールについて詳しくは、Azure Digital Twins Explorer に関するページを参照してください。その機能を使用する方法の詳細な手順については、Azure Digital Twins Explorer を使用するに関するページを参照してください。

視覚化は次のように表示されます。

API を使用して作成する

このセクションでは、クライアントアプリケーションからデジタルツインとリレーションシップを作成する方法について説明します。これには、DigitalTwins API を使用する .NET SDK の例が含まれています。これらの各概念の内部で何が起きっているのかについて、より多くのコンテキストを提供します。

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

DigitalTwins API を使用して Room 型のツインをインスタンス化するクライアントコードのスニペットと、そのインスタンス化中に定義された twinId を次に示します。

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

// Define a custom model type for the twin to be created

internal class CustomDigitalTwin
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
    public string Id { get; set; }

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

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

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

// Initialize properties and create the twin
public class TwinOperationsCreateTwin
{
    public async Task CreateTwinAsync(DigitalTwinsClient client)
    {
        // Initialize the twin properties
        var myTwin = new CustomDigitalTwin
        {
            Temperature = 25.0,
            Humidity = 50.0,
        };

        // Create the twin
        const string twinId = "<twin-ID>";
        Response<CustomDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
        Console.WriteLine($"Temperature value: {response.Value.Temperature}");
    }
}

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

Note

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

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

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

public async Task CreateRelationship(DigitalTwinsClient client)
{
    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);
}

Import Jobs API を使用してツインとリレーションシップを一括で作成する

Import Jobs API を使用して、1 つの API 呼び出しで多数のツインとリレーションシップをアップロードできます。この API で作成されたツインとリレーションシップには、必要に応じてプロパティの初期化を含めることができます。この API を使用する詳細な手順と例については、ツインとリレーションシップの一括インポート手順を参照してください。

グラフ要素を削除する

特定のツインとリレーションシップを削除するには、DigitalTwins Delete API と DigitalTwins DeleteRelationship API (CLI コマンドおよび SDK 呼び出しとしても使用できます) を使用します。

インスタンス内のすべてのモデル、ツイン、リレーションシップを一度に削除するには、Delete Jobs API を使用します。

グラフ要素の JSON 表現

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

デジタルツインの JSON 形式

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

フィールド名	説明
`$dtId`	デジタルツインの ID を表すユーザー指定の文字列
`$etag`	Web サーバーによって割り当てられた標準 HTTP フィールド
`$metadata.$model`	このデジタルツインを特徴付けるモデルインターフェイスの ID
`$metadata.<property-name>`	デジタルツインのプロパティに関するその他のメタデータ情報
`$metadata.<property-name>.lastUpdateTime`	プロパティの更新メッセージが Azure Digital Twins によって処理された日時
`$metadata.<property-name>.sourceTime`	プロパティの更新が実際に観察されたタイムスタンプを表す、省略可能で書き込み可能なプロパティ。このプロパティは、Azure Digital Twins API/SDK の 2022-05-31 バージョンのみを使用して書き込むことができ、値は ISO 8601 の日付と時刻の形式に準拠している必要があります。このプロパティを更新する方法の詳細については、「プロパティの sourceTime を更新する」を参照してください。
`<property-name>`	JSON のプロパティ値 (`string`、数値型、またはオブジェクト)
`$relationships`	リレーションシップコレクションへのパスの URL。デジタルツインに発信リレーションシップエッジがない場合、このフィールドは存在しません。
`<component-name>`	コンポーネントのプロパティ値とメタデータを含む JSON オブジェクト。ルートオブジェクトの場合と似たものです。このオブジェクトは、コンポーネントにプロパティがない場合でも存在します。
`<component-name>.$metadata`	コンポーネントのメタデータ情報。ルートレベルの `$metadata` と似たものです。
`<component-name>.<property-name>`	コンポーネントの、JSON のプロパティ値 (`string`、数値型、またはオブジェクト)

JSON オブジェクトとして書式設定されたデジタルツインの例を次に示します。このツインには、Humidity (湿度) と Temperature (気温) の 2 つのプロパティと Thermostat (サーモスタット) というコンポーネントが 1 つあります。

{
    "$dtId": "myRoomID",
    "$etag": "W/\"8e6d3e89-1166-4a1d-9a99-8accd8fef43f\"",
    "$metadata": {
        "$model": "dtmi:example:Room23;1",
        "Humidity": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        },
        "Temperature": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        }
    },
    "Humidity": 55,
    "Temperature": 35,
    "Thermostat": {
        "$metadata": {}
    }

リレーションシップの 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 のツイングラフに対して情報のクエリを行う方法について学習します。

クエリ言語

デジタル ツインとツイン グラフ