デジタルツインにタグを追加する

[アーティクル]
06/29/2023

この記事では、さまざまな種類のタグをモデルとデジタルツインに追加する方法と、タグを使用してクエリを実行する方法について説明します。

タグの概念を使用すると、デジタルツインをさらに識別して分類することができます。特に、ユーザーは、Azure Digital Twins インスタンス内の既存のシステム (Haystack タグなど) からタグをレプリケートすることができます。

このドキュメントでは、デジタルツインにタグを実装するために使用できるパターンについて説明します。

タグは、デジタルツインを記述するモデル内のプロパティとして最初に追加されます。その後、モデルに基づいてツインが作成されるときに、そのプロパティがツインに設定されます。設定後は、クエリでタグを使用して、ツインを特定したり、フィルター処理したりできます。

マーカータグ

マーカータグは、デジタルツインをマークまたは分類するために使用される単純な文字列です ("blue"、"red" など)。この文字列はタグの名前であり、マーカータグには意味のある値がありません。タグは存在すること (または存在しないこと) によってのみ意味を持ちます。

モデルにマーカータグを追加する

マーカータグは、string から boolean への DTDL マップとしてモデル化されます。タグが存在することのみが重要であるため、ブール mapValue は無視されます。

マーカータグをプロパティとして実装するツインモデルの抜粋を次に示します。

{
      "@type": "Property",
      "name": "tags",
      "schema": {
        "@type": "Map",
        "mapKey": {
          "name": "tagName",
          "schema": "string"
        },
        "mapValue": {
          "name": "tagValue",
          "schema": "boolean"
        }
      }
    },

デジタルツインにマーカータグを追加する

tags プロパティがデジタルツインのモデルの一部となったら、このプロパティの値を設定することによって、デジタルツインにマーカータグを設定できます。

以下に、.NET SDK を使用してツインにマーカー tags を設定する方法のコード例を示します。

IDictionary<string, bool> tags = new Dictionary<string, bool>
{
    { "oceanview", true },
    { "VIP", true }
};
var twin = new BasicDigitalTwin
{
    Metadata = { ModelId = "dtmi:example:Room;1" },
    Contents =
    {
        { "Temperature", 75 },
        { "tags", tags },
    },
};
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>("myTwinID", twin);

上記の例に従ってタグプロパティを持つツインを作成すると、ツインは次のようになります。

{
  "$dtId": "myTwinID",
  "$etag": "W/\"e7429259-6833-46b4-b443-200a77a468c2\"",
  "$metadata": {
    "$model": "dtmi:example:Room;1",
    "Temperature": {
      "lastUpdateTime": "2021-08-03T14:24:42.0850614Z"
    },
    "tags": {
      "lastUpdateTime": "2021-08-03T14:24:42.0850614Z"
    }
  },
  "Temperature": 75,
  "tags": {
    "VIP": true,
    "oceanview": true
  }
}

ヒント

ツインの JSON 表現を参照するには、CLI または API で、それに対するクエリを実行します。

マーカータグを使用したクエリ

デジタルツインにタグを追加したら、タグを使用してクエリでツインをフィルター処理できます。

"red" とタグ付けされているすべてのツインを取得するクエリを次に示します。

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

さらに複雑なクエリの場合は、タグを組み合わせることもできます。 red ではなく、round であるすべてのツインを取得するクエリを次に示します。

SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND IS_DEFINED(tags.round)

値タグ

値タグは、各タグに値を設定するために使用されるキーと値のペアです ("color": "blue"、"color": "red" など)。値タグが作成されたら、タグの値を無視することによって、マーカータグとして使用することもできます。

モデルに値タグを追加する

値タグは、string から string への DTDL マップとしてモデル化されます。 mapKey と mapValue の両方が意味を持ちます。

値タグをプロパティとして実装するツインモデルの抜粋を次に示します。

{
  "@type": "Property",
  "name": "tags",
  "schema": {
    "@type": "Map",
    "mapKey": {
      "name": "tagName",
      "schema": "string"
    },
    "mapValue": {
      "name": "tagValue",
      "schema": "string"
    }
  }
}

デジタルツインに値タグを追加する

マーカータグの場合と同様に、デジタルツインに値タグを設定するには、モデルからこの tags プロパティの値を設定します。値タグをマーカータグとして使用するには、tagValue フィールドを空の文字列値 ("") に設定します。

下に示したのは、サイズを表す値タグを持つ 2 つのツインの JSON 本文です。この例のツインには、マーカータグとして使用されている "red" や "purple" の値タグもあります。

Twin1 の例には、大きなサイズの値タグと、"red" のマーカータグがあります。

{
  "$dtId": "Twin1",
  "$etag": "W/\"d3997593-cc5f-4d8a-8683-957becc2bcdd\"",
  "$metadata": {
    "$model": "dtmi:example:ValueTags;1",
    "tags": {
      "lastUpdateTime": "2021-08-03T14:43:02.3150852Z"
    }
  },
  "tags": {
    "red": "",
    "size": "large"
  }
}

Twin2 の例には、小さなサイズの値タグと、"purple" のマーカータグがあります。

{
  "$dtId": "Twin2",
  "$etag": "W/\"e215e586-b14a-4234-8ddb-be69ebfef878\"",
  "$metadata": {
    "$model": "dtmi:example:ValueTags;1",
    "tags": {
      "lastUpdateTime": "2021-08-03T14:43:53.1517123Z"
    }
  },
  "tags": {
    "purple": "",
    "size": "small"
  }
}

値タグを使用したクエリ

マーカータグの場合と同様に、値タグを使用してクエリでツインをフィルター処理できます。値タグとマーカータグを一緒に使用することもできます。

上記の例では、red がマーカータグとして使用されています。これは、"red" とタグ付けされているすべてのツインを取得するクエリであることに注意してください。

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

red ではなく、small (値タグ) であるすべてのエンティティを取得するクエリを次に示します。

SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND tags.size = 'small'

次のステップ

デジタルツインモデルの設計と管理の詳細については、次の記事を参照してください。

DTDL モデルを管理する

ツイングラフに対するクエリ実行の詳細については、次の記事を参照してください。

ツイングラフにクエリを実行する

デジタル ツインにタグを追加する

マーカー タグ

モデルにマーカー タグを追加する

デジタルツインにマーカー タグを追加する

マーカー タグを使用したクエリ

値タグ