次の方法で共有


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

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

タグの概念を使用すると、デジタル ツインをさらに識別して分類することができます。 特に、ユーザーは、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 マップとしてモデル化されます。 mapKeymapValue の両方が意味を持ちます。

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

{
  "@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'

次のステップ

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

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