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

  • [アーティクル]

このチュートリアルでは、モデル、ツイン、およびリレーションシップを使用して、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 形式でこれをダウンロードできます。

Screenshot of the digital-twins-samples repo on GitHub, highlighting the steps to download it as a 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

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

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

Screenshot of the welcome message from the command-line app.

ヒント

このプロジェクトで使用できる全コマンドの一覧を確認するには、プロジェクト コンソールで「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 を編集用に開き、次の変更をコードに加えます。

  1. バージョン番号を更新する。このモデルのバージョンを更新することを示します。 そのためには、@id 値の末尾にある 1 を 2 に変更します。 現在のバージョン番号よりも大きい数値であれば、何でもかまいません。

  2. プロパティを編集する。 Humidity プロパティの名前を HumidityLevel に変更します (必要であれば、他の名前でもかまいません。HumidityLevel 以外の名前を使用した場合は、その名前を覚えておいて、このチュートリアル全体の HumidityLevel の代わりにそれを使用し続けてください)。

  3. プロパティを追加する。 HumidityLevel プロパティの最後 (15 行目) に続けて、次のコードを貼り付け、RoomName プロパティを room に追加します。

    ,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}

  4. リレーションシップを追加する。 先ほど追加した 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 サービス インスタンスが構成されます。 モデルをアップロードしたら、そのモデルを使用するツイン インスタンスを作成できます。

  1. digital-twins-samples-main\AdtSampleApp\SampleClientApp フォルダーが開いたコンソール ウィンドウに戻り、もう一度 dotnet run でコンソール アプリを実行します。

  2. プロジェクト コンソール ウィンドウで、次のコマンドを実行して、更新済みの Room モデルと、次のセクションで異なる種類のツインを作成するために使用する Floor モデルをアップロードします。

    CreateModels Room Floor

    出力結果を見ると、モデルが正常に作成されたことがわかります。

  3. GetModels true コマンドを実行して、モデルが作成されたことを確認します。 このコマンドによって、Azure Digital Twins インスタンスにアップロードされたすべてのモデルの完全な情報が出力されます。 この結果から、編集済みの Room モデルを探してみましょう。

    Screenshot of the result from GetModels, showing the updated Room model.

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

エラー

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

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

CreateModels Room

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

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

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

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

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

  1. 実行中のプロジェクト コンソールでこのコードを実行すると、いくつかのツインが作成されます。先ほど更新した 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

    コマンドから返される出力を見ると、ツインが正常に作成されたことがわかります。

    Screenshot showing an excerpt from the result of the CreateDigitalTwin commands, which includes floor0, floor1, room0, and room1.

  2. Query コマンドを実行すると、ツインが作成されたことを確認できます。 Azure Digital Twins インスタンスに対し、そこに含まれるすべてのデジタル ツインがこのコマンドによって照会されます。 その結果から、room0、room1、floor0、floor1 のツインを探します。

Note

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

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

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

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

Note

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

  1. このコマンドを実行して、room0 の RoomName を "Room0" から "PresidentialSuite" に変更します。

    UpdateDigitalTwin room0 add /RoomName string PresidentialSuite

    出力結果を見ると、ツインが正常に更新されたことがわかります。

  2. 次のコマンドを実行して room0 の情報を表示すると、更新が成功したことを確認できます。

    GetDigitalTwin room0

    更新後の名前が出力結果に反映されているはずです。

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

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

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

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

  1. 次のコマンドを実行すると、先ほど作成した各 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

    リレーションシップが正常に作成されたことが、コマンドから返される出力で確認できます。

    Screenshot of an excerpt from the result of the CreateRelationship commands, which includes relationship0 and relationship1.

  2. リレーションシップは、ご自分の Azure Digital Twins インスタンスのリレーションシップを出力する、次の任意のコマンドを使用して確認できます。

    • 各フロアを接続元とするすべてのリレーションシップを確認するには (一方の側からリレーションシップを表示): 
      GetRelationships floor0
GetRelationships floor1
    • 各部屋を接続先とするすべてのリレーションシップを表示するには ("もう一方の" 側からリレーションシップを表示): 
      GetIncomingRelationships room0
GetIncomingRelationships room1
    • これらのリレーションシップを ID で個別に検索するには: 
      GetRelationship floor0 relationship0
GetRelationship floor1 relationship1

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

A diagram showing a conceptual graph. floor0 is connected via relationship0 to room0, and floor1 is connected via relationship1 to room1.

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

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

Note

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

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

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

  1. Azure Digital Twins で表されている自分の環境内のすべてのエンティティを知りたい (すべて照会)

    Query

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

    Screenshot showing a partial result from the twin query, including room0 and floor1.

    ヒント

    サンプル プロジェクトでは、引数が追加されていない Query コマンドは、Query SELECT * FROM DIGITALTWINS に相当します。 クエリ API または CLI コマンドを使用して、インスタンス内のすべてのツインに対してクエリを実行するには、より長い (完全な) クエリを使用します。

  2. 環境内に存在する部屋をすべて知りたい (モデルで照会)

    Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')

    クエリを特定のタイプのツインに制限することで、表現されている内容についての、より具体的な情報を取得することができます。 このコマンドを実行すると、room0 と room1 は表示されますが、floor0 と floor1 は (room ではなく floor であるため) 表示されません。

    Screenshot of the result from the model query, showing only room0 and room1.

  3. floor0 に存在するすべての部屋を知りたい (リレーションシップで照会)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'

    グラフ内のリレーションシップに基づいてクエリを実行すると、ツインの関係性についての情報を入手したり、クエリを特定のエリアに制限したりすることができます。 floor0 に存在するのは room0 のみです。したがって、結果に含まれる部屋は room0 のみとなります。

    Screenshot of the result from the relationship query, showing room0.

  4. 自分の環境に存在するツインのうち、温度が 75 度を超えるツインをすべて知りたい (プロパティで照会)

    Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75

    プロパティに基づいてグラフを照会することにより、さまざまな質問への答えを得ることができます。たとえば、環境内で注意すべき外れ値を見つけることもできます。 その他の比較演算子 (<、>、=、<) もサポートされます。 ここでは、温度が 80 である room1 が結果として表示されます。

    Screenshot of the result from the property query, showing only room1.

  5. 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 度を超える部屋のみが表示されます。このケースでは、該当する部屋はありません。 結果セットは空になります。

    Screenshot of the result from the compound query, showing no results.

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

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

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

  • 次のチュートリアルに進む場合は、ここで設定したリソースを残しておいてください。この 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 サービスと組み合わせて、データ ドリブンのエンド ツー エンドのシナリオを完了してください。

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