チュートリアル: Azure CLI を使用して Azure Digital Twins グラフを作成する
このチュートリアルでは、モデル、ツイン、およびリレーションシップを使用して、Azure Digital Twins でグラフを作成します。 このチュートリアルのツールは、Azure CLI 用の Azure Digital Twins コマンド セットです。
CLI コマンドを使用して、モデルのアップロード、ツインの作成と変更、リレーションシップの作成など、基本的な Azure Digital Twins の操作を実行できます。 また、az dt コマンド セットのリファレンス ドキュメントを参照して、CLI コマンドの完全なセットを確認することもできます。
このチュートリアルでは次のことを行います。
- 環境をモデル化する
- デジタル ツインの作成
- リレーションシップを追加して、グラフを形成する
- グラフのクエリを実行して、質問に回答する
前提条件
このチュートリアルの手順を実行するには、まず次の前提条件を満たしておく必要があります。
Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。
サンプル モデルをダウンロードする
このチュートリアルでは、Azure Digital Twins の C# エンドツーエンド サンプル プロジェクトの一部である事前に作成された 2 つのモデルを使用します。 モデル ファイルは以下にあります。
お使いのマシンにこれらのファイルを用意するには、上記のナビゲーション リンクを使用して、ファイル本文をマシン上の同じ名前 (Room.json と Floor.json) のローカル ファイルにコピーします。
Azure CLI の環境を準備する
Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。
初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。
CLI セッションを設定する
CLI で Azure Digital Twins の使用を開始するには、まずログインし、このセッションのサブスクリプションに CLI コンテキストを設定します。 CLI ウィンドウでこれらのコマンドを実行します。
az login
az account set --subscription "<your-Azure-subscription-ID>"
ヒント
上記のコマンドでは、ID の代わりにサブスクリプション名も使用できます。
このサブスクリプションを Azure Digital Twins で初めて使用する場合は、次のコマンドを実行して Azure Digital Twins の名前空間に登録します (それが不明な場合は、以前に実行していたとしても、もう一度実行して問題ありません)。
az provider register --namespace 'Microsoft.DigitalTwins'
次に、Azure CLI に Microsoft Azure IoT 拡張機能を追加して、Azure Digital Twins およびその他の IoT サービスと対話するためのコマンドを有効にします。 このコマンドを実行して、最新バージョンの拡張機能がインストールされていることを確認します。
az extension add --upgrade --name azure-iot
これで、Azure CLI で Azure Digital Twins を使用する準備が整いました。
このことは、az dt --help を実行し、使用できる最上位の Azure Digital Twins コマンドの一覧を表示することで、いつでも確認できます。
Azure Digital Twins インスタンスを準備する
この記事で Azure Digital Twins を操作するには、まず Azure Digital Twins インスタンスとそれを使用するために必要なアクセス許可を設定する必要があります。 以前の作業で Azure Digital Twins インスタンスが既に設定されている場合は、そのインスタンスを使用できます。
それ以外の場合は、「インスタンスと認証を設定する」の手順に従います。 説明には、各手順が正常に完了し、新しいインスタンスを使用する準備ができていることを確認するための手順も含まれています。
Azure Digital Twins インスタンスを設定したら、後でインスタンスに接続するために必要な次の値をメモしておきます。
- インスタンスの "ホスト名"。
- インスタンスの作成に使用した Azure サブスクリプション
ヒント
インスタンスのフレンドリ名がわかっている場合は、次の CLI コマンドを使用して、ホスト名とサブスクリプションの値を取得できます。
az dt show --dt-name <Azure-Digital-Twins-instance-name>
以下のような出力が表示されます。
DTDL を使用して物理環境をモデル化する
CLI と Azure Digital Twins インスタンスが設定されたので、シナリオのグラフの作成を開始できます。
Azure Digital Twins ソリューションを作成するにあたり最初にすべきことは、対象となる環境のツイン モデルの定義です。
モデルは、オブジェクト指向プログラミング言語におけるクラスに似ています。つまりモデルは、デジタル ツインのユーザー定義のテンプレートとなります。デジタル ツインは、そのテンプレートに従ってインスタンス化されることになります。 これらは、Digital Twins Definition Language (DTDL) と呼ばれる JSON に似た言語で記述され、ツインのプロパティ、リレーションシップ、およびコンポーネントを定義できます。
Note
デジタル ツインに対する "コマンド" も DTDL で定義できます。 ただし Azure Digital Twins サービスでは現在、コマンドがサポートされていません。
お使いのマシンで、「前提条件」セクションで作成した 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 サービス インスタンスが構成されます。 モデルをアップロードしたら、そのモデルを使用するツイン インスタンスを作成できます。
Azure CLI のローカル インストールを使用する場合は、この手順を省略できます。 Cloud Shell を使用する場合は、モデル ファイルを使用する Cloud Shell コマンドを実行したときに使用できるように、それらのファイルを Cloud Shell のストレージにアップロードする必要があります。 それを行うには、[ファイルのアップロード/ダウンロード] アイコンを選択し、[アップロード] を選択します。
マシン上の Room.json ファイルに移動し、[開く] を選択します。その後、Floor.json についてもこの手順を繰り返します。
次に、下に示す az dt model create コマンドを使用して、更新した Room モデルを Azure Digital Twins インスタンスにアップロードします。 2 番目のコマンドでは、別のモデルである Floor をアップロードします。これは、さまざまな種類のツインを作成するために次のセクションでも使用します。 インスタンスのホスト名にはプレースホルダーが 1 つ (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します) と、各モデル ファイルへのパスのプレースホルダーがあります。 Cloud Shell を使用する場合は、Room.json と Floor.json がメイン ストレージ ディレクトリにあるため、次のコマンドでファイル名を直接使用できます (パスが必要です)。
az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Room.json> az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Floor.json>各コマンドの出力には、正常にアップロードされたモデルに関する情報が表示されます。
ヒント
model create コマンドの
--from-directoryオプションを使用して、ディレクトリ内のすべてのモデルを同時にアップロードすることもできます。 詳細については、az dt model create のオプション パラメーターに関する記事を参照してください。下に示すように、az dt model list コマンドを使用して、モデルが作成されたことを確認します。 そうすると、Azure Digital Twins インスタンスにアップロードされたすべてのモデルの一覧が、その完全な情報と共に出力されます。 インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。
az dt model list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --definitionこの結果から、編集済みの Room モデルを探してみましょう。
エラー
CLI では、サービスからのエラーも処理されます。
az dt model create コマンドを再実行して、もう一度、アップロードしたものと同じモデルをどれか再アップロードしてみてください。
az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models Room.json
モデルは上書きできないので、このコマンドを同じモデルに対して実行すると、ModelIdAlreadyExists というエラー コードが返されます。
デジタル ツインを作成する
Azure Digital Twins インスタンスにいくつかのモデルをアップロードしたら、そのモデルの定義に基づいてデジタル ツインを作成できます。 デジタル ツインは、農場のセンサー、建物内の部屋、車内の照明など、対象となるビジネス環境内のエンティティを表します。
デジタル ツインを作成するには、az dt twin create コマンドを使用します。 ツインのベースとなるモデルを参照する必要があります。モデルのプロパティには、必要に応じて初期値を定義することができます。 この段階では、リレーションシップ情報を渡す必要はありません。
CLI でこのコードを実行して、先ほど更新した Room モデルと、もう 1 つのモデル (Floor) に基づいて、いくつかのツインを作成します。 Room には 3 つのプロパティがあったことを思い出してください。これらのプロパティの初期値を引数で指定することができます。 (プロパティ値の初期化は一般に省略可能ですが、このチュートリアルでは必要です。) インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room0 --properties '{"RoomName":"Room0", "Temperature":70, "HumidityLevel":30}' az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room1 --properties '{"RoomName":"Room1", "Temperature":80, "HumidityLevel":60}' az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor0 az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor1Note
Bash 環境で Cloud Shell 以外のものを使用している場合は、インライン JSON で特定の文字をエスケープして、正しく解析されるようにする必要があります。
詳細については、さまざまなシェルでの特殊文字の使用に関するページを参照してください。
各コマンドの出力には、正常に作成されたツインに関する情報 (部屋ツインと共に初期化されたそれらのプロパティを含みます) が表示されます。
下に示すように、az dt twin query コマンドを使用してツインが作成されたことを確認できます。 示されたクエリにより、Azure Digital Twins インスタンス内のすべてのデジタル ツインが検索されます。 インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"その結果から、room0、room1、floor0、floor1 のツインを探します。 以下は、このクエリの結果の一部を示す抜粋です。
Note
グラフのデータを変更してからそれがクエリに反映されるまで、最大 10 秒の待機時間が発生する場合があります。
DigitalTwins API を使用すると変更がすぐに反映されるため、即時の応答が必要な場合は、クエリの代わりに API 要求 (DigitalTwins GetById) または SDK 呼び出し (GetDigitalTwin) を使用してツイン データを取得します。
デジタル ツインに変更を加える
作成したツインのプロパティを変更することもできます。
次の az dt twin update コマンドを実行して、room0 の RoomName を Room0 から PresidentialSuite に変更します。 インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。
az dt twin update --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --json-patch '{"op":"add", "path":"/RoomName", "value": "PresidentialSuite"}'注意
このチュートリアルでは、Bash 環境で CLI を使用することをお勧めします。 PowerShell 環境を使用する場合は、
--json-patchJSON 値が正しく解析されるように、引用符文字のエスケープが必要になる場合があります。このコマンドの出力には、ツインの現在の情報が表示され、結果には
RoomNameの新しい値が表示されています。
az dt twin show コマンドを実行して room0 の情報を表示すると、更新が成功したことを確認できます。 インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。
az dt twin show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0更新後の名前が出力結果に反映されているはずです。
リレーションシップを追加してグラフを作成する
次に、ツイン間にいくつかのリレーションシップを作成することで、それらのツインを接続し、ツイン グラフを形成することができます。 ツイン グラフは、環境全体を表すために使用されます。
あるツインから別のものへと作成できるリレーションシップの種類は、前にアップロードしたモデル内に定義されています。 Floor のモデル定義では、フロアに contains という種類のリレーションシップを設定できることが指定されています。 このリレーションシップはモデル定義によって指定されているため、各 Floor ツインから、それに含まれる対応する部屋への contains の種類のリレーションシップを作成できます。
リレーションシップを追加するには、az dt twin relationship create コマンドを使用します。 リレーションシップの接続元となるツインと、リレーションシップの種類、リレーションシップの接続先のツインを指定します。 最後に、リレーションシップに一意の ID を指定します。 プロパティを持つようにリレーションシップが定義されていた場合は、このコマンドでリレーションシップのプロパティを初期化することもできます。
次のコードを実行すると、先ほど作成した各 Floor ツインから対応する Room ツインへの
containsの種類のリレーションシップが追加されます。 リレーションシップには、relationship0 と relationship1 という名前が付けられます。 インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship0 --relationship contains --twin-id floor0 --target room0 az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship1 --relationship contains --twin-id floor1 --target room1ヒント
また、Floor モデル内の
containsリレーションシップは、ownershipUserとownershipDepartmentの 2 つのプロパティを指定して定義されていたため、リレーションシップを作成するときに、これらの初期値を引数として指定することもできます。 これらのプロパティを初期化してリレーションシップを作成するには、このように、上記のいずれかのコマンドに--propertiesオプションを追加します。... --properties '{"ownershipUser":"MyUser", "ownershipDepartment":"MyDepartment"}'各コマンドの出力には、正常に作成されたリレーションシップに関する情報が表示されます。
リレーションシップは、ご自分の Azure Digital Twins インスタンスのリレーションシップを出力する、次の任意のコマンドを使用して確認できます。 各コマンドにはインスタンスのホスト名のプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。
- 各フロアを接続元とするすべてのリレーションシップを確認するには (一方の側からリレーションシップを表示):
az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0 az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1 - 各部屋を接続先とするすべてのリレーションシップを表示するには ("もう一方の" 側からリレーションシップを表示):
az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --incoming az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room1 --incoming - これらのリレーションシップを ID で個別に検索するには:
az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0 --relationship-id relationship0 az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1 --relationship-id relationship1
- 各フロアを接続元とするすべてのリレーションシップを確認するには (一方の側からリレーションシップを表示):
このチュートリアルで設定したツインとリレーションシップによって、次の概念グラフが形成されます。
環境についての質問をツイン グラフに照会する
Azure Digital Twins の主な機能は、環境についての質問に答えるクエリをツイン グラフに対して容易に、かつ効率よく実行できることです。 Azure CLI では、クエリの実行は、az dt twin query コマンドを使用して行います。
Note
グラフのデータを変更してからそれがクエリに反映されるまで、最大 10 秒の待機時間が発生する場合があります。
DigitalTwins API を使用すると変更がすぐに反映されるため、即時の応答が必要な場合は、クエリの代わりに API 要求 (DigitalTwins GetById) または SDK 呼び出し (GetDigitalTwin) を使用してツイン データを取得します。
サンプル環境に関するいくつかの質問に回答するには、CLI で次のクエリを実行します。 各コマンドにはインスタンスのホスト名のプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。
Azure Digital Twins で表されている自分の環境内のすべてのエンティティを知りたい (すべて照会)
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"このクエリによって、環境の概要を調べて、すべてのことが必要な形で Azure Digital Twins 内に表現されていることを確認できます。 このクエリの結果は、各デジタル ツインとそれらの詳細が含まれる出力です。 その一部を次に示します。
ヒント
お気づきかもしれませんが、これはインスタンス内のすべての Azure Digital Twins を検索するために前の「デジタル ツインを作成する」セクションで使用したのと同じコマンドです。
環境内に存在する部屋をすべて知りたい (モデルで照会)
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')"クエリを特定のタイプのツインに制限することで、表現されている内容についての、より具体的な情報を取得することができます。 このコマンドを実行すると、room0 と room1 は表示されますが、floor0 と floor1 は (room ではなく floor であるため) 表示されません。
floor0 に存在するすべての部屋を知りたい (リレーションシップで照会)
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.\$dtId = 'floor0'"グラフ内のリレーションシップに基づいてクエリを実行すると、ツインの関係性についての情報を入手したり、クエリを特定のエリアに制限したりすることができます。 このクエリは、メタデータ フィールド
$dtIdを使用してツインの ID (上記のクエリの floor0 など) のクエリが実行されることも示しています。 floor0 に存在するのは room0 のみであるため、このクエリの結果にはこの部屋のみが含まれています。
Note
Cloud Shell を使用して、このような
$で始まるメタデータ フィールドでクエリを実行する場合は、バックスラッシュで$をエスケープして、それを変数ではなくクエリ テキスト内のリテラルとして使用する必要があることを Cloud Shell に認識させる必要があります。 これは、上のスクリーンショットに反映されています。自分の環境に存在するツインのうち、温度が 75 度を超えるツインをすべて知りたい (プロパティで照会)
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DigitalTwins T WHERE T.Temperature > 75"プロパティに基づいてグラフを照会すると、環境内で注意すべき外れ値を見つけることなど、さまざまな種類の質問への答えを得られます。 その他の比較演算子 (<、>、=、または <) もサポートされます。 ここでは、温度が 80 である room1 が結果として表示されます。
floor0 上で温度が 75 度を超えるすべての部屋を知りたい (複合クエリ)
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "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 インスタンスを引き続き使用するが、そのモデル、ツイン、リレーションシップをすべてクリアする場合は、次の az dt job deletion CLI コマンドを実行してください:
az dt job deletion create -n <name-of-Azure-Digital-Twins-instance> -yこれらの要素の一部のみを削除する場合は、az dt twin relationship delete、az dt twin delete、az dt model delete コマンドを使用して、削除する要素のみを選択的に削除できます。
このチュートリアルで作成したリソースがすべて不要である場合、この記事で使用した Azure Digital Twins インスタンスとその他すべてのリソースを az group delete CLI コマンドで削除できます。 そのリソース グループとそこに含まれるすべての Azure リソースが削除されます。
重要
リソース グループを削除すると、元に戻すことができません。 リソース グループとそこに含まれるすべてのリソースは完全に削除されます。 間違ったリソース グループやリソースをうっかり削除しないようにしてください。
Azure Cloud Shell またはローカル CLI ウィンドウを開き、次のコマンドを実行すると、リソース グループとそこに含まれる内容がすべて削除されます。
az group delete --name <your-resource-group>
また、ローカル コンピューターに作成したモデル ファイルを削除することもできます。
次のステップ
このチュートリアルでは、Azure CLI を使用してインスタンスにグラフを作成することで、Azure Digital Twins の使用を開始しました。 モデル、デジタル ツイン、およびリレーションシップを作成して、グラフを形成しました。 また、Azure Digital Twins で回答できる環境についての質問の種類を理解するために、グラフに対していくつかのクエリを実行しました。
次のチュートリアルに進み、Azure Digital Twins を他の Azure サービスと組み合わせて、データ ドリブンのエンド ツー エンドのシナリオを完了してください。