次の方法で共有

Azure Digital Twins 管理 API の使用方法

  • [アーティクル]

重要

Azure Digital Twins サービスの新しいバージョンがリリースされました。 新しいサービスの拡張された機能に照らして、元の Azure Digital Twins サービス (このドキュメント セットで説明) は廃止されました。

新しいサービスのドキュメントを表示するには、アクティブな Azure Digital Twins のドキュメントを参照してください。

Azure Digital Twins 管理 API は、IoT アプリのための強力な機能を提供します。 この記事では、API 構造内を移動する方法を示します。

API の概要

次の一覧は、Digital Twins API のコンポーネントを示しています。

  • /spaces: これらの API は、セットアップ内の物理的な場所とやり取りします。 これらは物理的な場所のデジタル マッピングを空間グラフの形式で作成、削除、および管理するのに役立ちます。

  • /devices: これらの API は、セットアップ内のデバイスとやり取りします。 これらのデバイスは、1 つまたは複数のセンサーを管理できます。 たとえば、電話機や Raspberry Pi センサー ポッド、あるいは LoRa ゲートウェイなどがデバイスに該当します。

  • /sensors: これらの API は、デバイスと物理的な場所に関連付けられているセンサーとの通信に役立ちます。 センサーは周辺環境の値を記録して送信し、この値は空間環境を操作するために後で使用できます。

  • /resources: これらの API は、Digital Twins インスタンス用に IoT ハブなどのリソースを設定するのに役立ちます。

  • /types: これらの API を使用すると、拡張型を Digital Twins オブジェクトに関連付けて、それらのオブジェクトに特定の特性を追加できます。 これらの型によって、UI 内のオブジェクトや、テレメトリ データを処理するカスタム関数のフィルター処理やグループ化を簡単に行うことができます。 拡張型の例として、DeviceType、SensorType、SensorDataType、SpaceType、SpaceSubType、SpaceBlobType、SpaceResourceType などがあります。

  • /オントロジ: これらの API は、拡張型のコレクションであるオントロジを管理するのに役立ちます。 オントロジでは、オブジェクトの種類が表す物理的スペースに従ってオブジェクトの種類の名前を指定します。 たとえば、BACnet オントロジは sensor types、datatypes、datasubtypes、dataunittypes に対して特定の名前を指定します。 オントロジはサービスによって管理および作成されます。 ユーザーはオントロジをロードおよびアンロードできます。 オントロジがロードされると、それに関連付けられているすべての種類の名前が有効になり、空間グラフにプロビジョニングできるようになります。

  • /propertyKeys: これらの API を使用して、 スペース、 デバイス、 ユーザー、 センサーのカスタム プロパティを作成できます。 これらのプロパティは、キー/値のペアとして作成されます。 これらのプロパティのデータ型は、PrimitiveDataType を設定して定義できます。 たとえば、センサーに対して種類が uint のBasicTemperatureDeltaProcessingRefreshTime という名前のプロパティを定義し、センサーごとにこのプロパティの値を割り当てることができます。 また、プロパティを作成するときに、これらの値の制約を追加することもでき、たとえば Min や Max の範囲や、許可される値として ValidationData を指定できます。

  • /マッチャー: これらの API を使用すると、受信デバイス データから評価する条件を指定できます。 詳細については、この記事を参照してください。

  • /userDefinedFunctions: これらの API を使用すると、 マッチャー によって定義された条件が発生したときに実行されるカスタム関数を作成、削除、または更新して、セットアップからのデータを処理できます。 ユーザー定義関数とも呼ばれるこれらのカスタム関数については、こちら記事を参照してください。

  • /endpoints: これらの API を使用すると、Digital Twins ソリューションが他の Azure サービスと通信してデータストレージと分析を行えるようにエンドポイントを作成できます。 詳細については、こちらの記事を参照してください。

  • /keyStores: これらの API を使用すると、スペースのセキュリティ キー ストアを管理できます。 これらのストアはセキュリティ キーのコレクションを保持できるため、ユーザーは最新の有効なキーを簡単に取得できます。

  • /users: これらの API を使用すると、ユーザーをスペースに関連付けて、必要に応じてこれらの個人を検索できます。

  • /system: これらの API を使用すると、既定の種類のスペースやセンサーなど、システム全体の設定を管理できます。

  • /roleAssignments: これらの API を使用すると、ユーザー ID、ユーザー定義関数 ID などのエンティティにロールを関連付けることができます。各ロールの割り当てには、関連付けるエンティティの ID、エンティティの種類、関連付けるロールの ID、テナント ID、およびエンティティがその関連付けでアクセスできるリソースの上限を定義するパスが含まれます。 詳細については、こちらの記事を参照してください。

API ナビゲーション

Digital Twins API では、以下のパラメーターを使用して、空間グラフ全体でのフィルター処理やおよびナビゲーションをサポートします。

  • spaceId: API は、指定されたスペース ID で結果をフィルター処理します。 さらに、ブール型フラグ useParentSpace を /spaces API に適用でき、このフラグは、指定したスペース ID が、現在のスペースではなく親のスペースを表すことを示します。

  • minLevel と maxLevel: ルートスペースはレベル 1 と見なされます。 親のスペースがレベル n であるスペースは、レベル n+1 です。 これらの値を設定して、特定のレベルで結果をフィルター処理できます。 これらの設定値は、その値を含みます。 デバイス、センサー、およびその他のオブジェクトは、それらの最も近いスペースと同じレベルであると見なされます。 特定のレベルのすべてのオブジェクトを取得するには、minLevel と maxLevel の両方を同じ値に設定します。

  • minRelative と maxRelative: これらのフィルターを指定すると、対応するレベルは指定されたスペース ID のレベルに対して相対的になります。

    • 相対レベル 0 は、特定のスペース ID と同じレベルになります。
    • 相対レベル 1 は、特定のスペース ID の子と同じレベルのスペースを表します。 相対レベル n は、指定されたスペースよりも n レベル低いスペースを表します。
    • 相対レベル -1 は、指定されたスペースの親のスペースと同じレベルのスペースを表します。

  • 走査: 次の値で指定されているように、特定の空間 ID から双方向に走査できます。

    • なし: この既定値は、指定された領域 ID にフィルター処理されます。
    • Down: 指定されたスペース ID とその子孫によってフィルター処理されます。
    • Up: 指定されたスペース ID とその先祖によってフィルター処理されます。
    • スパン: 空間グラフの水平方向の部分を、指定された空間 ID と同じレベルでフィルター処理します。 minRelative または maxRelative のいずれかを true に設定する必要があります。

例

次の一覧は、/devices API を使用した移動の例をいくつか示しています。 プレース ホルダー YOUR_MANAGEMENT_API_URL は、https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0/ 形式の Digital Twins API の URI を示すことに注意してください。ここで、YOUR_INSTANCE_NAME は Azure Digital Twins インスタンスの名前、YOUR_LOCATION はインスタンスをホストするリージョンです。

  • YOUR_MANAGEMENT_API_URL/devices?maxLevel=1 は、ルート スペースに接続されているすべてのデバイスを返します。
  • YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4 は、レベル 2、3、または 4 のスペースに接続されているすべてのデバイスを返します。
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId は、mySpaceId に直接接続されているすべてのデバイスを返します。
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down は、mySpaceId またはその子孫の 1 つに接続されているすべてのデバイスを返します。
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true は、mySpaceId の子孫 (mySpaceId を除く) に接続されているすべてのデバイスを返します。
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true は、mySpaceId の直下の子に接続されているすべてのデバイスを返します。
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Up&maxLevel=-1&maxRelative=true は、mySpaceId の先祖の 1 つに接続されているすべてのデバイスを返します。
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&maxLevel=5 は、mySpaceId の子孫のうち、レベル 5 またはそれより小さい子孫に接続されているすべてのデバイスを返します。
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true は、mySpaceId と同じレベルのスペースに接続されているすべてのデバイスを返します。

OData のサポート

/spaces の GET 呼び出しなど、コレクションを返す API のほとんどは、一般的な OData システム クエリ オプションの次のサブセットをサポートします。

  • $filter
  • $orderby
  • $top
  • $skip - コレクション全体を表示する場合、1 回の呼び出しで 1 つのセットとしてコレクションを要求し、その後アプリケーション内でページングを実行してください。

注意

一部の OData オプション (クエリ オプション $count、$expand、$search など) は、現在サポートされていません。

例

次の一覧は、有効な OData 構文を含むいくつかのクエリを示しています。

  • YOUR_MANAGEMENT_API_URL/devices?$top=3&$orderby=Name desc
  • YOUR_MANAGEMENT_API_URL/keystores?$filter=endswith(Description,'space')
  • YOUR_MANAGEMENT_API_URL/devices?$filter=TypeId eq 2
  • YOUR_MANAGEMENT_API_URL/resources?$filter=StatusId ne 1
  • YOUR_MANAGEMENT_API_URL/users?$top=4&$filter=endswith(LastName,'k')&$orderby=LastName
  • YOUR_MANAGEMENT_API_URL/spaces?$orderby=Name desc&$top=3&$filter=substringof('Floor',Name)

次の手順

API のいくつかの一般的なクエリ パターンについては、「一般的なタスクについて Azure Digital Twins API をクエリする方法」を参照してください。

API エンドポイントの詳細については、Digital Twins Swagger の使用方法に関するページをご覧ください。

Odata 構文と使用できる比較演算子を確認するには、Azure Cognitive Search の OData 比較演算子に関する記事をご覧ください。