Azure Digital Twins でのエグレスとエンドポイント

[アーティクル]
01/21/2020

重要

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

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

Azure Digital Twins のエンドポイントは、ユーザーの Azure サブスクリプション内のメッセージブローカーまたはイベントブローカーを表します。イベントとメッセージは、Azure Event Hubs、Azure Event Grid、および Azure Service Bus のトピックに送信できます。

イベントは、ルーティングの定義済み優先設定に従ってエンドポイントにルーティングされます。ユーザーは、各エンドポイントが受け取る可能性があるイベントの種類を指定します。

イベント、ルーティング、イベントタイプについて詳しくは、「Azure Digital Twins でのルーティングイベントおよびメッセージ」をご覧ください。

イベント

イベントは、Azure のメッセージブローカーおよびイベントブローカーで処理するために IoT オブジェクト (デバイス、センサーなど) によって送信されます。イベントは、次の Azure Event Grid イベントスキーマリファレンスによって定義されます。

{
  "id": "00000000-0000-0000-0000-000000000000",
  "subject": "ExtendedPropertyKey",
  "data": {
    "SpacesToNotify": [
      "3a16d146-ca39-49ee-b803-17a18a12ba36"
    ],
    "Id": "00000000-0000-0000-0000-000000000000",
      "Type": "ExtendedPropertyKey",
    "AccessType": "Create"
  },
  "eventType": "TopologyOperation",
  "eventTime": "2018-04-17T17:41:54.9400177Z",
  "dataVersion": "1",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

属性	Type	説明
id	string	イベントの一意識別子。
subject	string	発行元が定義したイベントの対象のパス。
data	object	リソースプロバイダーに固有のイベントデータ。
eventType	string	このイベントソース用に登録されたイベントの種類のいずれか。
eventTime	string	プロバイダーの UTC 時刻に基づくイベントの生成時刻。
dataVersion	string	データオブジェクトのスキーマバージョン。スキーマバージョンは発行元によって定義されます。
metadataVersion	string	イベントメタデータのスキーマバージョン。最上位プロパティのスキーマは Event Grid によって定義されます。この値は Event Grid によって指定されます。
topic	string	イベントソースの完全なリソースパス。このフィールドは書き込み可能ではありません。この値は Event Grid によって指定されます。

Event Grid イベントスキーマの詳細については、

Azure Event Grid イベントスキーマリファレンスに関するページを参照してください。
Azure EventGrid Node.js SDK EventGridEvent リファレンスに関するページをお読みください。

イベントの種類

イベントの種類はイベントの性質を分類し、 eventType フィールドに設定されます。使用可能なイベントの種類の一覧を、次に示します。

TopologyOperation
UdfCustom
SensorChange
SpaceChange
DeviceMessage

それぞれのイベントの種類のイベント形式については、以下のサブセクションで詳しく説明します。

TopologyOperation

TopologyOperation は、グラフの変更に適用されます。 subject プロパティは、影響を受けるオブジェクトの種類を指定します。次のオブジェクトの種類によって、このイベントがトリガーされる可能性があります。

Device
DeviceBlobMetadata
DeviceExtendedProperty
ExtendedPropertyKey
ExtendedType
KeyStore
レポート
RoleDefinition
Sensor
SensorBlobMetadata
SensorExtendedProperty
Space
SpaceBlobMetadata
SpaceExtendedProperty
SpaceResource
SpaceRoleAssignment
システム
User
UserBlobMetadata
UserExtendedProperty

例

{
  "id": "00000000-0000-0000-0000-000000000000",
  "subject": "ExtendedPropertyKey",
  "data": {
    "SpacesToNotify": [
      "3a16d146-ca39-49ee-b803-17a18a12ba36"
    ],
    "Id": "00000000-0000-0000-0000-000000000000",
      "Type": "ExtendedPropertyKey",
    "AccessType": "Create"
  },
  "eventType": "TopologyOperation",
  "eventTime": "2018-04-17T17:41:54.9400177Z",
  "dataVersion": "1",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

値	置換後の文字列
YOUR_TOPIC_NAME	カスタマイズしたトピックの名前

UdfCustom

UdfCustom は、ユーザー定義関数 (UDF) によって送信されるイベントです。

重要

このイベントは、UDF 自体から明示的に送信する必要があります。

例

{
  "id": "568fd394-380b-46fa-925a-ebb96f658cce",
  "subject": "UdfCustom",
  "data": {
    "TopologyObjectId": "7c799bfc-1bff-4b9e-b15a-669933969d20",
    "ResourceType": "Space",
    "Payload": "\"Room is not available or air quality is poor\"",
    "CorrelationId": "568fd394-380b-46fa-925a-ebb96f658cce"
  },
  "eventType": "UdfCustom",
  "eventTime": "2018-10-02T06:50:15.198Z",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

値	置換後の文字列
YOUR_TOPIC_NAME	カスタマイズしたトピックの名前

SensorChange

SensorChange は、テレメトリの変化に基づく、センサーの状態に対する更新です。

例

{
  "id": "60bf5336-2929-45b4-bb4c-b45699dfe95f",
  "subject": "SensorChange",
  "data": {
    "Type": "Classic",
    "DataType": "Motion",
    "Id": "60bf5336-2929-45b4-bb4c-b45699dfe95f",
    "Value": "False",
    "PreviousValue": "True",
    "EventTimestamp": "2018-04-17T17:46:15.4964262Z",
    "MessageType": "sensor",
    "Properties": {
      "ms-client-request-id": "c9e576b7-5eea-4f61-8617-92a57add5179",
      "ms-activity-id": "ct22YwXEGJ5u.605.0"
    }
  },
  "eventType": "SensorChange",
  "eventTime": "2018-04-17T17:46:18.5452993Z",
  "dataVersion": "1",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

値	置換後の文字列
YOUR_TOPIC_NAME	カスタマイズしたトピックの名前

SpaceChange

SpaceChange は、テレメトリの変化に基づく、スペースの状態に対する更新です。

例

{
  "id": "42522e10-b1aa-42ff-a5e7-7181788ffc4b",
  "subject": "SpaceChange",
  "data": {
    "Type": null,
    "DataType": "AvailableAndFresh",
    "Id": "7c799bfc-1bff-4b9e-b15a-669933969d20",
    "Value": "Room is not available or air quality is poor",
    "PreviousValue": null,
    "RawData": null,
    "transactionId": null,
    "EventTimestamp": null,
    "MessageType": null,
    "Properties": null,
    "CorrelationId": "42522e10-b1aa-42ff-a5e7-7181788ffc4b"
  },
  "eventType": "SpaceChange",
  "eventTime": "2018-10-02T06:50:20.128Z",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "topic": "/subscriptions/YOUR_TOPIC_NAME"
}

値	置換後の文字列
YOUR_TOPIC_NAME	カスタマイズしたトピックの名前

DeviceMessage

DeviceMessage を使用すると、Azure Digital Twins からも生テレメトリイベントをルーティングできる EventHub 接続を指定できます。

注意

DeviceMessage は、EventHub とのみ組み合わせることができます。 DeviceMessage はその他のいずれのイベントの種類とも組み合わせることができません。
種類 EventHub または DeviceMessage の組み合わせのエンドポイントは、1 つだけ指定できます。

エンドポイントを構成する

エンドポイントの管理は、Endpoints API を使用して行います。

次の例では、YOUR_MANAGEMENT_API_URL は Digital Twins API の URI を参照しています。

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

名前	置換後の文字列
YOUR_INSTANCE_NAME	Azure Digital Twins インスタンスの名前
YOUR_LOCATION	インスタンスをホストするリージョン

次の例は、サポートされているエンドポイントの構成方法を示しています。

重要

eventTypes 属性に注意してください。これはエンドポイントによって処理されるイベントの種類を定義するため、ルーティングを決定します。

認証済みの HTTP POST 要求:

YOUR_MANAGEMENT_API_URL/endpoints

Service Bus イベントの種類へのルート SensorChange、SpaceChange、TopologyOperation:

{
  "type": "ServiceBus",
  "eventTypes": [
    "SensorChange",
    "SpaceChange",
    "TopologyOperation"
  ],
  "connectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_PRIMARY_KEY",
  "secondaryConnectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_SECONDARY_KEY",
  "path": "YOUR_TOPIC_NAME"
}

値	置換後の文字列
YOUR_NAMESPACE	エンドポイントの名前空間
YOUR_PRIMARY_KEY	認証に使用されるプライマリ接続文字列
YOUR_SECONDARY_KEY	認証に使用されるセカンダリ接続文字列
YOUR_TOPIC_NAME	カスタマイズしたトピックの名前

Event Grid イベントの種類へのルート SensorChange、SpaceChange、TopologyOperation:

{
  "type": "EventGrid",
  "eventTypes": [
    "SensorChange",
    "SpaceChange",
    "TopologyOperation"
  ],
  "connectionString": "YOUR_PRIMARY_KEY",
  "secondaryConnectionString": "YOUR_SECONDARY_KEY",
  "path": "YOUR_TOPIC_NAME.westus-1.eventgrid.azure.net"
}

値	置換後の文字列
YOUR_PRIMARY_KEY	認証に使用されるプライマリ接続文字列
YOUR_SECONDARY_KEY	認証に使用されるセカンダリ接続文字列
YOUR_TOPIC_NAME	カスタマイズしたトピックの名前

Event Hubs イベントの種類へのルート SensorChange、SpaceChange、TopologyOperation:

{
  "type": "EventHub",
  "eventTypes": [
    "SensorChange",
    "SpaceChange",
    "TopologyOperation"
  ],
  "connectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_PRIMARY_KEY",
  "secondaryConnectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_SECONDARY_KEY",
  "path": "YOUR_EVENT_HUB_NAME"
}

値	置換後の文字列
YOUR_NAMESPACE	エンドポイントの名前空間
YOUR_PRIMARY_KEY	認証に使用されるプライマリ接続文字列
YOUR_SECONDARY_KEY	認証に使用されるセカンダリ接続文字列
YOUR_EVENT_HUB_NAME	イベントハブの名前

Event Hubs イベントの種類へのルート DeviceMessage。 connectionString に含めるEntityPathのは必須です。

{
  "type": "EventHub",
  "eventTypes": [
    "DeviceMessage"
  ],
  "connectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_PRIMARY_KEY;EntityPath=YOUR_EVENT_HUB_NAME",
  "secondaryConnectionString": "Endpoint=sb://YOUR_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_SECONDARY_KEY;EntityPath=YOUR_EVENT_HUB_NAME",
  "path": "YOUR_EVENT_HUB_NAME"
}

値	置換後の文字列
YOUR_NAMESPACE	エンドポイントの名前空間
YOUR_PRIMARY_KEY	認証に使用されるプライマリ接続文字列
YOUR_SECONDARY_KEY	認証に使用されるセカンダリ接続文字列
YOUR_EVENT_HUB_NAME	イベントハブの名前

注意

新しいエンドポイントを作成するとき、そのエンドポイントでイベントの受信が始まるまで最大 5 ～ 10 分かかる場合があります。

プライマリ接続キーとセカンダリ接続キー

プライマリ接続キーが承認されなくなると、システムは自動的にセカンダリ接続キーを試みます。これによってバックアップが提供され、Endpoints API を使用してプライマリキーを正常に認証および更新できる可能性があります。

プライマリとセカンダリ両方の接続キーが承認されなくなると、システムは最大 30 分の指数バックオフ待機時間に入ります。トリガーされた各バックオフ待機時間では、イベントは削除されます。

システムがバックオフ待機状態のときは常に、Endpoints API による接続キーの更新が有効になるまでに最大で 30 分かかる場合があります。

到達できないエンドポイント

エンドポイントが到達不能になると、システムは最大 30 分の指数バックオフ待機時間に入ります。トリガーされた各バックオフ待機時間では、イベントは削除されます。

次の手順

Azure Digital Twins Swagger の使用方法を確認します。
Azure Digital Twins 内でのイベントとメッセージのルーティングの詳細を確認します。

次の方法で共有