チュートリアル: Azure Digital Twins プレビューをデプロイし、空間グラフを構成する
重要
Azure Digital Twins サービスの新しいバージョンがリリースされました。 新しいサービスの拡張された機能に照らして、元の Azure Digital Twins サービス (このドキュメント セットで説明) は廃止されました。
新しいサービスのドキュメントを表示するには、アクティブな Azure Digital Twins のドキュメントを参照してください。
Azure Digital Twins プレビューサービスを使用すると、人、場所、デバイスを一貫した空間システムにまとめることができます。 この一連のチュートリアルでは、Azure Digital Twins を使用して、温度と空気の質が最適な状態の部屋の使用を検出する方法を示します。
これらのチュートリアルでは、.NET コンソール アプリケーションを使用して、オフィス ビルのシナリオを構築する手順を説明します。 このビルには、複数のフロアがあり各フロアに部屋があります。 それぞれの部屋には、モーション、周囲温度、空気の質を検出するセンサーを備えたデバイスがあります。
Azure Digital Twins サービスを使用して、建物内の物理的なエリアとエンティティをデジタル オブジェクトとして複製する方法を学習します。 別のコンソール アプリケーションを使用して、デバイス イベントをシミュレートします。 次に、これらの物理的なエリアとエンティティで発生するイベントをほぼリアルタイムで監視する方法を学習します。
オフィス管理者は、この情報を使用して、この建物内で働く従業員が最適な条件の会議室を予約するのを支援することができます。 オフィス施設管理者は、お客様の設定を使用して、部屋の使用傾向を調べたり、メンテナンスのために作業環境を監視したりすることができます。
このシリーズの最初のチュートリアルで学習する内容は次のとおりです。
- Digital Twins をデプロイする。
- アプリにアクセス許可を付与する。
- Digital Twins サンプル アプリを変更する。
- 建物をプロビジョニングする。
これらのチュートリアルで使用および変更するサンプルは、概念についてさらに詳しく説明されている、空き部屋を見つけるためのクイック スタートのサンプルと同じです。
前提条件
Azure サブスクリプション。 Azure アカウントがない場合は、無料アカウントを作成します。
.NET Core SDK。 これらのチュートリアルで使用される Azure Digital Twins サンプルは、C# で記述されています。 サンプルをビルドして実行する開発マシンには、必ず .NET Core SDK バージョン 2.1.403 以上をインストールしておいてください。 コマンド ウィンドウで
dotnet --versionを実行して、適切なバージョンがマシンにインストールされていることを確認してください。Visual Studio Code。サンプル コードを確認するために使用します。
Digital Twins をデプロイする
このセクションの手順を使用して、Azure Digital Twins サービスの新しいインスタンスを作成します。 作成できるインスタンスは、サブスクリプションごとに 1 つだけです。 実行中のインスタンスが既にある場合は、スキップして次のセクションに進んでください。
Azure portal にサインインします。
ホームのサイドバーを選択してから、[+ リソースの作成] を選択します。
![ホーム サイド バーを展開し、[+ リソースの作成] を選択します](../includes/media/create-digital-twins-portal/azure-portal-create-a-resource.png)
[Digital Twins] を検索し、[Digital Twins]\(デジタル ツイン\) を選択します。
あるいは、[モノのインターネット] を選択してから、[Digital Twins (プレビュー)] を選択します。
[作成] を選択してデプロイ プロセスを開始します。
[Digital Twins] ウィンドウで、次の情報を入力します。
[リソース名]: Digital Twins インスタンスの一意の名前を作成します。
[サブスクリプション]: この Digital Twins インスタンスを作成するために使用するサブスクリプションを選択します。
[リソース グループ]: Digital Twins インスタンスのリソース グループを選択または作成します。
場所: デバイスに最も近い場所を選択します。
![情報が入力された [Digital Twins] ペイン](../includes/media/create-digital-twins-portal/create-digital-twins-param.png)
Digital Twins の情報を確認してから、[作成] を選択します。 Digital Twins インスタンスが作成されるまでに数分かかる場合があります。 [通知] ウィンドウで進行状況を監視できます。
Digital Twins インスタンスの [概要] ウィンドウを開きます。 [管理 API] の下のリンクに注目します。 [管理 API] の URL の形式は次のとおりです。
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerこの URL では、インスタンスに適用される Azure Digital Twins REST API のドキュメントが表示されます。 この API ドキュメントを読んで使用する方法については、「How to use Azure Digital Twins Swagger (Azure Digital Twins Swagger の使用方法)」を参照してください。 [管理 API] の URL をコピーし、次の形式に変更します。
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/アプリケーションは、変更された URL をベース URL として使用してインスタンスにアクセスします。 この変更した URL を一時ファイルにコピーします。 これは次のセクションで必要になります。
![ホーム サイド バーを展開し、[+ リソースの作成] を選択します](../includes/media/create-digital-twins-portal/azure-portal-create-a-resource.png#lightbox)
![情報が入力された [Digital Twins] ペイン](../includes/media/create-digital-twins-portal/create-digital-twins-param.png#lightbox)
アプリにアクセス許可を付与する
Digital Twins では、Azure Active Directory (Azure AD) を使用してサービスに対する読み取り/書き込みアクセスを制御します。 お客様の Digital Twins インスタンスに接続する必要のあるアプリケーションは、Azure AD に登録しなければなりません。 このセクションの手順では、サンプル アプリを登録する方法を示します。
既にアプリの登録がある場合は、それをサンプルに再利用することができます。 ただし、このセクションを参照して、アプリの登録が適切に構成されていることを確認してください。
注意
このセクションでは、Azure AD アプリの登録手順について説明します。
Azure portal で、展開可能な左側のメニューの [Azure Active Directory] を開き、[アプリの登録] ペインを開きます。
![[Azure Active Directory] ペインを選択する](../includes/media/digital-twins-permissions/azure-portal-select-aad-pane.png)
[+ 新規登録] ボタンを選択します。
![[新しい登録] ボタンを選択します](../includes/media/digital-twins-permissions/aad-app-register.png)
[名前] ボックスに、このアプリ登録の表示名を入力します。
[リダイレクト URI (省略可能)] セクションのテキスト ボックスに「
https://microsoft.com」と入力します。Azure Active Directory アプリでどのアカウントとテナントがサポートされるかを確認します。
[登録] を選択します。
![[作成] ウィンドウ](../includes/media/digital-twins-permissions/aad-app-reg-create.png)
[認証] ブレードで、重要な認証構成設定を指定します。
[+ プラットフォームを追加] を選択して、 [リダイレクト URI] を追加し、 [アクセス トークン] を構成します。
アプリがパブリック クライアントであることを指定するには、[はい] を選択します。
Azure Active Directory アプリでどのアカウントとテナントがサポートされるかを確認します。
適切なプラットフォームを選択したら、ユーザー インターフェイスの右側のサイド パネルで [リダイレクト URI] と [アクセス トークン] を構成します。
[リダイレクト URI] は、認証要求で指定されたアドレスと一致する必要があります。
- ローカル開発環境でホストされているアプリでは、 [パブリック クライアント (モバイルとデスクトップ)] を選択します。 [パブリック クライアント] は必ず [はい] に設定してください。
- Azure App Service でホストされているシングルページ アプリでは、 [Web] を選択します。
[ログアウト URL] が適切かどうかを確認します。
[アクセス トークン] または [ID トークン] をオンにすることによって、暗黙的な許可のフローを有効にします。
[構成] 、 [保存] の順にクリックします。
登録済みアプリの [概要] ペインを開き、次のエンティティの値を一時ファイルにコピーします。 これらの値は、以下のセクションでサンプル アプリケーションを構成する際に使用します。
- アプリケーション (クライアント) ID
- ディレクトリ (テナント) ID
アプリの登録の [API アクセス許可] ウィンドウを開きます。 [+ アクセス許可の追加] ボタンを選択します。 [API アクセス許可の要求] ペインで、[所属する組織で使用している API] タブを選択し、次のいずれかを選択します。
Azure Digital Twins. Azure Digital Twins API を選択します。
または、
Azure Smart Spaces Serviceを検索します。 Azure Smart Spaces Service API を選択します。
重要
表示される Azure AD API の名前と ID は、テナントによって異なります。
- テスト テナントと顧客アカウントでは、
Azure Digital Twinsを検索する必要があります。 - 他の Microsoft アカウントでは、
Azure Smart Spaces Serviceを検索する必要があります。
選択すると、いずれかの API が同じ [API アクセス許可の要求] ペインに Azure Digital Twins として表示されます。 [Read]\(読み取り\) ドロップ ダウンを選択し、[Read.Write] チェック ボックスをオンにします。 [アクセス許可の追加] ボタンを選択します
組織の設定によっては、この API への管理者アクセスを許可するために追加の手順を実行する必要があります。 詳細については、管理者にお問い合わせください。 管理者アクセスが承認されると、[API アクセス許可] ペインの [管理者の同意が必要] 列にアクセス許可が表示されます。
Azure Digital Twins が表示されていることを確認します。
![[Azure Active Directory] ペインを選択する](../includes/media/digital-twins-permissions/azure-portal-select-aad-pane.png#lightbox)
![[新しい登録] ボタンを選択します](../includes/media/digital-twins-permissions/aad-app-register.png#lightbox)
![[作成] ウィンドウ](../includes/media/digital-twins-permissions/aad-app-reg-create.png#lightbox)
Digital Twins サンプルを構成する
このセクションでは、Digital Twins REST API と通信する Azure Digital Twins アプリケーションについて説明します。
サンプルのダウンロード
空き部屋を見つけるためのクイック スタート用に既にサンプルをダウンロードしている場合は、これらの手順をスキップできます。
- Digital Twins .NET サンプルをダウンロードします。
- お客様のマシン上に zip フォルダーの内容を展開します。
サンプルの確認
Visual Studio Code で、展開されたサンプル フォルダー内の digital-twins-samples-csharp\digital-twins-samples.code-workspace ファイルを開きます。 ここには次の 2 つのプロジェクトが含まれています。
プロビジョニング サンプル occupancy-quickstart を使用すると、空間インテリジェンス グラフを構成およびプロビジョニングできます。 このグラフは、物理空間とそこに含まれるリソースのデジタル化画像です。 これには、スマート ビルのためのオブジェクトを定義するオブジェクト モデルが使用されています。 Digital Twins オブジェクトと REST API の完全な一覧については、この REST API ドキュメントまたはお客様のインスタンス用に作成された Management API URL を参照してください。
サンプルを確認し、サンプルと Digital Twins インスタンスの通信のしくみを理解するには、src\actions フォルダーから開始できます。 このフォルダー内のファイルによって、これらのチュートリアルで使用するコマンドが実装されます。
- provisionSample.cs ファイルでは、空間グラフのプロビジョニング方法が示されます。
- getSpaces.cs ファイルでは、プロビジョニングされた空間に関する情報が取得されます。
- getAvailableAndFreshSpaces.cs ファイルでは、ユーザー定義関数と呼ばれるカスタム関数の結果が取得されます。
- createEndpoints.cs ファイルでは、他のサービスと対話するためのエンドポイントが作成されます。
device-connectivity シミュレーション サンプルを使用すると、センサー データがシミュレートされ、お客様の Digital Twins インスタンス用にプロビジョニングされた IoT ハブにそのデータが送信されます。 このサンプルは、空間グラフをプロビジョニングした後の次のチュートリアルで使用します。 このサンプルを構成するために使用されるセンサーとデバイスの識別子は、グラフのプロビジョニングに使用するものと同じである必要があります。
プロビジョニング サンプルの構成
コマンド ウィンドウを開き、ダウンロードしたサンプルに移動します。 次のコマンドを実行します。
cd occupancy-quickstart/src次のコマンドを実行して、依存関係をサンプル プロジェクトに復元します。
dotnet restoreVisual Studio Code で occupancy-quickstart プロジェクトの appSettings.json ファイルを開きます。 次の値を更新します。
- ClientId: Azure AD アプリ登録のアプリケーション ID を入力します。 この ID は、アプリのアクセス許可の設定に関するセクションでメモしたものです。
- Tenant: Azure AD テナントのディレクトリ ID を入力します。 この ID も、アプリのアクセス許可の設定に関するセクションでメモしたものです。
- BaseUrl: Digital Twins インスタンスの URL を入力します。 この URL を取得するには、URL
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/内のプレースホルダーをお客様のインスタンスの値に置き換えます。 また、デプロイに関するセクションに示されている Management API URL を変更することによってもこの URL を取得できます。 swagger/ は api/v1.0/ に置き換えてください。
サンプルを使用して確認できる Digital Twins の機能の一覧を確認します。 次のコマンドを実行します。
dotnet run
プロビジョニング プロセスを理解する
このセクションでは、サンプルで建物の空間グラフがどのようにプロビジョニングされるかを説明します。
Visual Studio Code で、occupancy-quickstart\src\actions フォルダーに移動し、provisionSample.cs ファイルを開きます。 次の関数に注目してください。
public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
IEnumerable<SpaceDescription> spaceCreateDescriptions;
using (var r = new StreamReader("actions/provisionSample.yaml"))
{
spaceCreateDescriptions = await GetProvisionSampleTopology(r);
}
var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);
Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");
return results;
}
この関数では、同じフォルダー内の provisionSample.yaml が使用されています。 このファイルを開き、オフィス ビルの階層が Venue、Floor、Area、Rooms となっている点に注目してください。 これらの物理空間のいずれにも、devices と sensors を含めることができます。 各エントリには、Floor、Room などの定義済み typeがあります。
サンプルの yaml ファイルでは、Default Digital Twins オブジェクト モデルを使用して空間グラフが表示されます。 このモデルでは、ほとんどの型に汎用的な名前が与えられています。 建物であれば、汎用的な名前で十分です。 たとえば、SensorDataType の Temperature、SpaceBlobType の Mapがあります。 空間型の例としては、FocusRoom、ConferenceRoom などのサブタイプを備えた Room があります。
異なるタイプの現場 (工場など) の空間グラフを作成する必要がある場合は、別のオブジェクト モデルが必要になることがあります。 プロビジョニング サンプルに対してコマンド ラインでコマンド dotnet run GetOntologies を実行すると、使用可能なモデルを見つけることができます。
空間グラフとオブジェクト モデルの詳細については、Digital Twins オブジェクト モデルと空間インテリジェンス グラフに関するページを参照してください。
サンプル空間グラフの変更
provisionSample.yaml ファイルには、次のノードが含まれています。
resources:
resourcesノードでは、お客様の設定内のデバイスと通信するための Azure IoT Hub リソースが作成されます。 グラフのルート ノードにある IoT ハブは、グラフ内のすべてのデバイスおよびセンサーと通信できます。spaces: Digital Twins オブジェクト モデルでは、
spacesは物理的な場所を表します。 各スペースにはType、リージョン、会場、顧客など、 とわかりやすいNameがあります。 空間は他の空間に属することができ、これによって階層構造が作られます。 provisionSample.yaml ファイルには、架空の建物の空間グラフが含まれています。 入れ子になった論理的な空間、つまりVenue内の型Floor、フロア内のArea、エリア内のRoomノードに注目してください。devices: 空間には
devicesを含めることができます。これは、複数のセンサーを管理する物理エンティティまたは仮想エンティティです。 たとえば、デバイスは、ユーザーの電話、Raspberry Pi センサー ポッド、ゲートウェイなどです。 サンプルにある架空の建物の Focus Room という名前の部屋に Raspberry Pi 3 A1 デバイスがどのように含まれているかに注目してください。 それぞれのデバイス ノードは一意のhardwareIdで識別されます。これは、サンプルではハードコーディングされています。 このサンプルを実際の運用環境用に構成する場合は、これらの値をお客様の設定の値に置き換えてください。sensors: デバイスは、複数の
sensorsを含むことができます。 これらは、温度、モーション、バッテリー レベルなどの物理的な変化を検出して記録することができます。 それぞれのセンサー ノードはhardwareIdで一意に識別されます。これは、ここではハードコーディングされています。 実際のアプリケーションではこれらを、お客様の設定に含まれているセンサーの一意の識別子に置き換えてください。 provisionSample.yaml ファイルには、Motion と CarbonDioxide を記録する 2 つのセンサーがあります。 CarbonDioxide センサーの行の下に次の行を追加して、Temperature を記録する別のセンサーを追加します。 これらは、provisionSample.yaml 内でコメントアウトされた行として提供されます。 各行の先頭にある#文字を削除するだけでコメント解除することができます。- dataType: Temperature hardwareId: SAMPLE_SENSOR_TEMPERATURE注意
dataTypeキーとhardwareIdキーがこのスニペットの上のステートメントに揃っていることを確認します。 また、エディターで空白がタブに置き換えられないことを確認します。
provisionSample.yaml ファイルを保存して閉じます。 次のチュートリアルでは、このファイルに情報をさらに追加したうえで、Azure Digital Twins のサンプルの建物をプロビジョニングします。
ヒント
Azure Digital Twins グラフ ビューアーを使って、空間グラフを表示および変更できます。
リソースをクリーンアップする
この時点で Azure Digital Twins の探索を中止する場合は、このチュートリアルで作成されたリソースを削除してかまいません。
Azure portal の左側のメニューにある [すべてのリソース] をクリックし、目的の Digital Twins リソース グループを選択して [削除] を選択します。
ヒント
ご自分の Digital Twins インスタンスの削除で問題が発生していた場合は、サービス更新が修正と共にロールアウトされています。 ご自分のインスタンスの削除を再試行してください。
必要に応じて、作業マシン上のサンプル アプリケーションを削除します。
次の手順
サンプルの建物の状態を監視するためのカスタム ロジックを実装する方法について学習するために、シリーズの次のチュートリアルに進んでください。