チュートリアル: サンプルクライアントアプリを使用して Azure Digital Twins グラフを作成する

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

このチュートリアルでは、モデル、ツイン、およびリレーションシップを使用して、Azure Digital Twins でグラフを作成します。このチュートリアルのツールは、Azure Digital Twins インスタンスを操作するためのサンプルコマンドラインクライアントアプリケーションです。このクライアントアプリは、クライアントアプリのコーディングに関する記事で作成したアプリに似ています。

このサンプルを使用して、モデルのアップロード、ツインの作成と変更、リレーションシップの作成など、基本的な Azure Digital Twins アクションを実行することができます。サンプルのコードを見て、Azure Digital Twins の API について学んだり、サンプルプロジェクトに自由に変更を加えながら、独自のコマンドを実装する練習をしたりすることもできます。

このチュートリアルでは次のことを行います。

環境をモデル化する
デジタルツインの作成
リレーションシップを追加して、グラフを形成する
グラフのクエリを実行して、質問に回答する

前提条件

このチュートリアルを開始する前に、次の前提条件から始めてください。

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
このチュートリアルでは、.NET を使用します。「.NET のダウンロード」から、複数のプラットフォームに対応する最新バージョンの .NET SDK をダウンロードできます。

次に、このセクションの残りの部分を続行して、残りの前提条件を設定します。

サンプルリソースを入手する

このチュートリアルは、C# で記述された Azure Digital Twins のエンドツーエンドのサンプルプロジェクトを使用して進められます。サンプルのリンクに移動し、タイトルの下にある " [Browse Code](コードの参照) " ボタンを選択して、お使いのマシン上でサンプルプロジェクトを取得します。

これにより、サンプル用の GitHub リポジトリに移動します。[Code](コード) ボタンと、[Download ZIP](ZIP のダウンロード) を選択することによって、.zip 形式でこれをダウンロードできます。

これにより、.zip フォルダーが digital-twins-samples-main.zip としてお使いのマシンにダウンロードされます。フォルダーを解凍し、ファイルを抽出します。

Azure Digital Twins インスタンスを準備する

この記事で Azure Digital Twins を操作するには、まず Azure Digital Twins インスタンスとそれを使用するために必要なアクセス許可が必要です。 Azure Digital Twins インスタンスが既に設定されている場合は、そのインスタンスを使用し、次のセクションに進むことができます。それ以外の場合は、「インスタンスと認証を設定する」の手順に従います。手順には、各ステップを正常に完了したことを確認するために役立つ情報が含まれています。

インスタンスの設定後、インスタンスのホスト名を書き留めておきます。ホスト名は Azure portal で確認できます。

サンプルプロジェクトを構成する

次に、Azure Digital Twins インスタンスとやり取りするサンプルクライアントアプリケーションを設定します。

マシン上で、以前に Azure Digital Twins のエンドツーエンドサンプルからダウンロードしたフォルダーに移動します (まだの場合は解凍します)。

そのフォルダー内の digital-twins-samples-main\AdtSampleApp\SampleClientApp に移動し、appsettings.json ファイルを開きます。この JSON ファイルには、プロジェクトを実行するために必要な構成変数が含まれています。

ファイルの本体で、instanceUrl を Azure Digital Twins インスタンスのホスト名 URL に変更します (以下に示すように、ホスト名の前に https:// を追加します)。

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

ファイルを保存して閉じます。

ローカルの Azure 資格情報を設定する

このサンプルでは、ローカルコンピューターで実行された Azure Digital Twins インスタンスに対し、(Azure.Identity ライブラリの) DefaultAzureCredential を使用してユーザーを認証します。 Azure Digital Twins に対してクライアントアプリの認証を行う各種の方法について詳しくは、「アプリ認証コードを作成する」を参照してください。

このサンプルでは、DefaultAzureCredential を使用して、ローカル環境から資格情報が検索されます。たとえば、ローカルの DefaultAzureCredential や Visual Studio または Visual Studio Code での Azure サインインなどです。このため、サンプルの資格情報を設定するために、これらのメカニズムのいずれかを使用して、Azure にローカルでサインインする必要があります。

Visual Studio または Visual Studio Code を使用してコードサンプルを実行する場合は、Azure Digital Twins インスタンスへのアクセスに使用する Azure 資格情報でそのエディターにサインインしていることを確認してください。ローカル CLI ウィンドウを使用している場合は、az login コマンドを実行して Azure アカウントにサインインします。その後、コードサンプルを実行すれば、自動的に認証処理が行われます。

サンプルプロジェクトを実行する

アプリと認証の設定が済んだら、プロジェクトの実行に使用するローカル コンソールウィンドウを開きます。コンソールで digital-twins-samples-main\AdtSampleApp\SampleClientApp フォルダーに移動し、この dotnet コマンドを使用してプロジェクトを実行します。

dotnet run

プロジェクトが開始されて認証が実行され、コマンドの待機状態となります。

次に示したのは、プロジェクトコンソールの画面例を示すスクリーンショットです。

ヒント

このプロジェクトで使用できる全コマンドの一覧を確認するには、プロジェクトコンソールで「help」と入力し、Return キーを押します。

アプリが正常に実行されていることを確認したら、プロジェクトを停止できます。後でこのチュートリアルの中で、再び実行します。

DTDL を使用して物理環境をモデル化する

Azure Digital Twins インスタンスとサンプルアプリが設定されたので、シナリオのグラフの作成を開始できます。

Azure Digital Twins ソリューションを作成するにあたり最初にすべきことは、対象となる環境のツインモデルの定義です。

モデルは、オブジェクト指向プログラミング言語におけるクラスに似ています。つまりモデルはユーザー定義のテンプレートであり、それをインスタンス化することによってデジタルツインを作成することができます。 Azure Digital Twins のモデルは、Digital Twins Definition Language (DTDL) という JSON に似た言語で記述され、ツインのタイプをそのプロパティ、リレーションシップ、コンポーネントの観点から定義します。

Note

デジタルツインに対する "コマンド" も DTDL で定義できます。ただし Azure Digital Twins サービスでは現在、コマンドがサポートされていません。

先ほどダウンロードしたサンプルプロジェクトフォルダーの digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models フォルダーに移動します。このフォルダーにサンプルモデルが格納されています。

Room.json を編集用に開き、次の変更をコードに加えます。

バージョン番号を更新する。このモデルのバージョンを更新することを示します。そのためには、@id 値の末尾にある 1 を 2 に変更します。現在のバージョン番号よりも大きい数値であれば、何でもかまいません。
プロパティを編集する。 Humidity プロパティの名前を HumidityLevel に変更します (必要であれば、他の名前でもかまいません。HumidityLevel 以外の名前を使用した場合は、その名前を覚えておいて、このチュートリアル全体の HumidityLevel の代わりにそれを使用し続けてください)。
プロパティを追加する。 HumidityLevel プロパティの最後 (15 行目) に続けて、次のコードを貼り付け、RoomName プロパティを room に追加します。
```
,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}
```
リレーションシップを追加する。先ほど追加した RoomName プロパティの下に次のコードを貼り付けて、このタイプのツインが他のツインとの間で contains のリレーションシップを形成できるようにします。
```
,{
  "@type": "Relationship",
  "name": "contains"
}
```

作業が終わったら、更新後のモデルは次と一致します。

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

次に進む前に、必ずファイルを保存してください。

Azure Digital Twins にモデルをアップロードする

モデルを設計したら、Azure Digital Twins インスタンスにアップロードする必要があります。そうすることで、カスタムドメインの独自のボキャブラリを使用して、Azure Digital Twins サービスインスタンスが構成されます。モデルをアップロードしたら、そのモデルを使用するツインインスタンスを作成できます。

digital-twins-samples-main\AdtSampleApp\SampleClientApp フォルダーが開いたコンソールウィンドウに戻り、もう一度 dotnet run でコンソールアプリを実行します。
プロジェクトコンソールウィンドウで、次のコマンドを実行して、更新済みの Room モデルと、次のセクションで異なる種類のツインを作成するために使用する Floor モデルをアップロードします。
```
CreateModels Room Floor
```
出力結果を見ると、モデルが正常に作成されたことがわかります。
GetModels true コマンドを実行して、モデルが作成されたことを確認します。このコマンドによって、Azure Digital Twins インスタンスにアップロードされたすべてのモデルの完全な情報が出力されます。この結果から、編集済みの Room モデルを探してみましょう。

次の手順のために、コンソールアプリは実行したままにしておいてください。

エラー

このサンプルアプリケーションは、サービスからのエラーも処理します。

これをテストするために、CreateModels コマンドを再実行して、既にアップロードした Room モデルを再アップロードしてみましょう。

CreateModels Room

モデルは上書きできないので、このコマンドから、作成しようとしているモデル ID の一部が既に存在していることを示すサービスエラーが返されます。

既存のモデルを削除する方法について詳しくは、DTDL モデルの管理に関する記事を参照してください。

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

Azure Digital Twins インスタンスにいくつかのモデルをアップロードしたら、そのモデルの定義に基づいてデジタルツインを作成できます。デジタルツインは、農場のセンサー、建物内の部屋、車内の照明など、対象となるビジネス環境内のエンティティを表します。

デジタルツインを作成するには、CreateDigitalTwin コマンドを使用します。ツインのベースとなるモデルを参照する必要があります。モデルのプロパティには、必要に応じて初期値を定義することができます。この段階では、リレーションシップ情報を渡す必要はありません。

実行中のプロジェクトコンソールでこのコードを実行すると、いくつかのツインが作成されます。先ほど更新した Room モデルに基づくツインと、もう 1 つのモデル (Floor) に基づくツインです。 Room には 3 つのプロパティがあったことを思い出してください。これらのプロパティの初期値を引数で指定することができます。 (プロパティ値の初期化は一般に省略可能ですが、このチュートリアルでは必要です。)
```
CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1
```
コマンドから返される出力を見ると、ツインが正常に作成されたことがわかります。
Query コマンドを実行すると、ツインが作成されたことを確認できます。 Azure Digital Twins インスタンスに対し、そこに含まれるすべてのデジタルツインがこのコマンドによって照会されます。その結果から、room0、room1、floor0、floor1 のツインを探します。

Note

グラフのデータを変更してからそれがクエリに反映されるまで、最大 10 秒の待機時間が発生する場合があります。

DigitalTwins API を使用すると変更がすぐに反映されるため、即時の応答が必要な場合は、クエリの代わりに API 要求 (DigitalTwins GetById) または SDK 呼び出し (GetDigitalTwin) を使用してツインデータを取得します。

デジタルツインに変更を加える

作成したツインのプロパティを変更することもできます。

Note

基になる REST API では、ツインに対する更新を定義するために、JSON Patch 形式が使用されます。また、コマンドラインアプリでは、この形式を使用して、基になる API が予期する内容を含む真のエクスペリエンスを提供します。

このコマンドを実行して、room0 の RoomName を "Room0" から "PresidentialSuite" に変更します。
```
UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
```
出力結果を見ると、ツインが正常に更新されたことがわかります。
次のコマンドを実行して room0 の情報を表示すると、更新が成功したことを確認できます。
```
GetDigitalTwin room0
```
更新後の名前が出力結果に反映されているはずです。

リレーションシップを追加してグラフを作成する

次に、ツイン間にいくつかのリレーションシップを作成することで、それらのツインを接続し、ツイングラフを形成することができます。ツイングラフは、環境全体を表すために使用されます。

あるツインから別のものへと作成できるリレーションシップの種類は、前にアップロードしたモデル内に定義されています。 Floor のモデル定義には、フロアが contains という型のリレーションシップを持てることが指定されています。そのため、各 Floor ツインから、それに含まれる対応する部屋に対して contains 型のリレーションシップを作成できます。

リレーションシップを追加するには、CreateRelationship コマンドを使用します。リレーションシップの接続元となるツインと、リレーションシップの種類、リレーションシップの接続先のツインを指定します。最後に、リレーションシップに一意の ID を指定します。

次のコマンドを実行すると、先ほど作成した各 Floor ツインから対応する Room ツインへの contains リレーションシップが追加されます。リレーションシップには、relationship0 と relationship1 という名前が付けられます。
```
CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1
```
ヒント

また、Floor モデル内の contains リレーションシップは、ownershipUser と ownershipDepartment の 2 つの文字列プロパティを指定して定義されていたため、リレーションシップを作成するときに、これらの初期値を引数として指定することもできます。 relationship0 を作成する上記のコマンドの代替バージョンを次に示します。これは、これらのプロパティの初期値も指定しています。
```
CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
```
リレーションシップが正常に作成されたことが、コマンドから返される出力で確認できます。
リレーションシップは、ご自分の Azure Digital Twins インスタンスのリレーションシップを出力する、次の任意のコマンドを使用して確認できます。
- 各フロアを接続元とするすべてのリレーションシップを確認するには (一方の側からリレーションシップを表示):
```
GetRelationships floor0
GetRelationships floor1
```
- 各部屋を接続先とするすべてのリレーションシップを表示するには ("もう一方の" 側からリレーションシップを表示):
```
GetIncomingRelationships room0
GetIncomingRelationships room1
```
- これらのリレーションシップを ID で個別に検索するには:
```
GetRelationship floor0 relationship0
GetRelationship floor1 relationship1
```

このチュートリアルで設定したツインとリレーションシップによって、次の概念グラフが形成されます。

環境についての質問をツイングラフに照会する

Azure Digital Twins の主な機能は、環境についての質問に答えるクエリをツイングラフに対して容易に、かつ効率よく実行できることです。

Note

グラフのデータを変更してからそれがクエリに反映されるまで、最大 10 秒の待機時間が発生する場合があります。

サンプル環境に関するいくつかの質問に回答するには、実行中のプロジェクトコンソールで次のコマンドを実行します。

Azure Digital Twins で表されている自分の環境内のすべてのエンティティを知りたい (すべて照会)
```
Query
```
このコマンドを使用すると、環境の概要を調べ、必要な事柄がすべて Azure Digital Twins 内で表現されていることを確認できます。このコマンドの結果は、個々のデジタルツインとその詳細を含んだ出力です。その一部を次に示します。

ヒント

サンプルプロジェクトでは、引数が追加されていない Query コマンドは、Query SELECT * FROM DIGITALTWINS に相当します。クエリ API または CLI コマンドを使用して、インスタンス内のすべてのツインに対してクエリを実行するには、より長い (完全な) クエリを使用します。
環境内に存在する部屋をすべて知りたい (モデルで照会)
```
Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
```
クエリを特定のタイプのツインに制限することで、表現されている内容についての、より具体的な情報を取得することができます。このコマンドを実行すると、room0 と room1 は表示されますが、floor0 と floor1 は (room ではなく floor であるため) 表示されません。
floor0 に存在するすべての部屋を知りたい (リレーションシップで照会)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
```
グラフ内のリレーションシップに基づいてクエリを実行すると、ツインの関係性についての情報を入手したり、クエリを特定のエリアに制限したりすることができます。 floor0 に存在するのは room0 のみです。したがって、結果に含まれる部屋は room0 のみとなります。
自分の環境に存在するツインのうち、温度が 75 度を超えるツインをすべて知りたい (プロパティで照会)
```
Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
```
プロパティに基づいてグラフを照会することにより、さまざまな質問への答えを得ることができます。たとえば、環境内で注意すべき外れ値を見つけることもできます。その他の比較演算子 (<、>、=、<) もサポートされます。ここでは、温度が 80 である room1 が結果として表示されます。
floor0 上で温度が 75 度を超えるすべての部屋を知りたい (複合クエリ)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75
```
SQL と同様、結合演算子 (AND、OR、NOT など) を使用して、先行するクエリを結合することもできます。このクエリは、AND を使用して、ツインの温度に関する先行するクエリを絞り込んでいます。結果には、floor0 上の部屋のうち、温度が 75 度を超える部屋のみが表示されます。このケースでは、該当する部屋はありません。結果セットは空になります。

以上、設定したシナリオでいくつかのクエリを実行しました。これでチュートリアルは完了です。プロジェクトを停止し、コンソールウィンドウを閉じます。

リソースをクリーンアップする

このチュートリアルを終えたら、次に行う作業に応じて、削除するリソースを選択できます。

次のチュートリアルに進む場合は、ここで設定したリソースを残しておいてください。この Azure Digital Twins インスタンスと構成済みのサンプルアプリを引き続き次のチュートリアルで使用します。
Azure Digital Twins インスタンスは引き続き使用するものの、そのモデル、ツイン、関係をすべてクリアする場合は、サンプルアプリの DeleteAllTwins コマンドと DeleteAllModels コマンドをそれぞれ使用して、インスタンスからツインとモデルをクリアすることができます。

このチュートリアルで作成したリソースがすべて不要である場合、この記事で使用した Azure Digital Twins インスタンスとその他すべてのリソースを az group delete CLI コマンドで削除できます。そのリソースグループとそこに含まれるすべての Azure リソースが削除されます。

重要

リソースグループを削除すると、元に戻すことができません。リソースグループとそこに含まれるすべてのリソースは完全に削除されます。間違ったリソースグループやリソースをうっかり削除しないようにしてください。

Azure Cloud Shell またはローカル CLI ウィンドウを開き、次のコマンドを実行すると、リソースグループとそこに含まれる内容がすべて削除されます。
```
az group delete --name <your-resource-group>
```

さらに、ダウンロードしたプロジェクトフォルダーもローカルコンピューターから削除できます。

次のステップ

このチュートリアルでは、サンプルクライアントアプリケーションを使用してインスタンスにグラフを作成することで、Azure Digital Twins の使用を開始しました。モデル、デジタルツイン、およびリレーションシップを作成して、グラフを形成しました。また、Azure Digital Twins で回答できる環境についての質問の種類を理解するために、グラフに対していくつかのクエリを実行しました。

次のチュートリアルに進み、Azure Digital Twins を他の Azure サービスと組み合わせて、データドリブンのエンドツーエンドのシナリオを完了してください。

エンドツーエンドのソリューションを接続する

次の方法で共有

チュートリアル: サンプルクライアントアプリを使用して Azure Digital Twins グラフを作成する

前提条件

サンプルリソースを入手する

Azure Digital Twins インスタンスを準備する

サンプルプロジェクトを構成する

ローカルの Azure 資格情報を設定する

サンプルプロジェクトを実行する

DTDL を使用して物理環境をモデル化する

Azure Digital Twins にモデルをアップロードする

エラー

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

デジタルツインに変更を加える

リレーションシップを追加してグラフを作成する

環境についての質問をツイングラフに照会する

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

次の方法で共有

チュートリアル: サンプル クライアント アプリを使用して Azure Digital Twins グラフを作成する

前提条件

サンプル リソースを入手する

Azure Digital Twins インスタンスを準備する

サンプル プロジェクトを構成する

ローカルの Azure 資格情報を設定する

サンプル プロジェクトを実行する

DTDL を使用して物理環境をモデル化する

Azure Digital Twins にモデルをアップロードする

エラー

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

デジタル ツインに変更を加える

リレーションシップを追加してグラフを作成する

環境についての質問をツイン グラフに照会する

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

チュートリアル: サンプルクライアントアプリを使用して Azure Digital Twins グラフを作成する

サンプルリソースを入手する

サンプルプロジェクトを構成する

サンプルプロジェクトを実行する

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

デジタルツインに変更を加える

環境についての質問をツイングラフに照会する