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

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

Digital Twins

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

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

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

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

たとえば、モデル 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 という名称のヘルパー クラスを使用し、"ツイン" オブジェクトにプロパティ フィールドをもっと直接的に格納することもできます。 ヘルパー クラスとその使用例について詳しくは、「デジタル ツインを作成する」をご覧ください。

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

ここでは、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 オブジェクトとして表された場合、デジタル ツインには次のフィールドが表示されます。

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

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

• クエリ言語