イベント通知

  • [アーティクル]

この記事では、Azure Digital Twins によって生成されるイベント通知、その構造、および生成できるさまざまな種類の詳細を網羅します。

Azure Digital Twins のさまざまなイベントでは通知が生成されます。これにより、さまざまなアクションが発生したときにソリューション バックエンドが認識されるようになります。 これらの通知は、この情報を基に操作が実行される Azure Digital Twins 内外のさまざまな場所にルーティングされます。

生成される通知にはいくつかの種類があり、通知メッセージの表示は、その通知の生成元のイベントの種類によって異なる場合があります。 この記事では、さまざまな種類のメッセージについての詳細と、表示される内容について説明します。

この表は、さまざまな通知の種類を示しています。

通知の種類 ルーティング ソース名 生成元
デジタル ツインの変更通知 デジタル ツインの変更通知 任意のデジタル ツインのプロパティの変更
デジタル ツインのライフサイクル通知 デジタル ツインのライフサイクル通知 任意のデジタル ツインの作成または削除操作
デジタル ツインの関係の変更通知 デジタル ツインの関係の変更通知 任意のデジタル ツインの関係の変更
デジタル ツインのテレメトリ メッセージ テレメトリ メッセージ 任意のテレメトリ メッセージ

通知の構造

Azure Digital Twins からのイベント通知の構造は、通知の送信先によって異なります。

Event Grid に送信される通知は、次のいずれかの形式に準拠しています (Event Grid の設定によって異なります)。

Event Hubs と Service Bus に送信される通知は、CloudEvents の AMQP プロトコル バインドに準拠しています。

デジタル ツインの変更通知

デジタル ツインの変更通知は、次のようなデジタル ツインの更新時にトリガーされます。

  • プロパティ値またはメタデータが変更した場合。
  • デジタル ツインまたはコンポーネント メタデータが変更された場合。 このシナリオの例として、デジタル ツインのモデルの変更が挙げられます。

Properties

デジタル ツイン変更通知の本文に含まれるフィールドを次に示します。

名前 値
id サービスによって管理される UUID やカウンターなどの、通知の識別子。 source + id は個別のイベントごとに一意です
source IoT ハブや Azure Digital Twins インスタンスの名前 (myhub.azure-devices.net や mydigitaltwins.westus2.azuredigitaltwins.net など)
data ツインに対して行われた更新が記述されている JSON パッチ ドキュメント。 詳細については、下の本文の詳細を参照してください。
specversion 1.0
メッセージは、CloudEvents 標準のこのバージョンに準拠しています。
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject デジタル ツインの ID
time デジタル ツインで操作が発生したときのタイムスタンプ
traceparent イベントの W3C トレース コンテキスト

本文の詳細

メッセージ内の data フィールドには、デジタル ツインの更新情報を含む JSON パッチ ドキュメントが含まれています。

以下に、考えられる通知スキーマごとに、このメッセージの種類の例を示します。

{
    "id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "subject": "example-twin1",
    "data": {
      "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
          {
            "value": "new name",
            "path": "/room",
            "op": "replace"
          }
        ]
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-c28d665340fe5045-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.9795363Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Note

Azure Digital Twins では現在、配列内のフィールドに基づくイベントのフィルタリングはサポートされていません。 これには、デジタル ツインの変更通知の patch セクション内のプロパティを条件とするフィルタリングも含まれます。

デジタル ツインのライフサイクル通知

デジタル ツインは、Azure Digital Twins 内の IoT Hub デバイスを表すかどうかにかかわらず、すべて通知を出力します。 これは、デジタル ツイン自体に関するライフサイクル通知であるためです。

ライフサイクル通知は、次の場合にトリガーされます。

  • デジタル ツインの作成
  • デジタル ツインの削除

Properties

ライフサイクル通知の本文に含まれるフィールドを次に示します。

名前 値
id サービスによって管理される UUID やカウンターなどの、通知の識別子。 source + id は、個別のイベントごとに一意です。
source IoT ハブや Azure Digital Twins インスタンスの名前 (myhub.azure-devices.net や mydigitaltwins.westus2.azuredigitaltwins.net など)
data ライフサイクル イベントが発生しているツインのデータ。 詳細については、下の本文の詳細を参照してください。
specversion 1.0
メッセージは、CloudEvents 標準のこのバージョンに準拠しています。
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject デジタル ツインの ID
time ツインで操作が発生したときのタイムスタンプ
traceparent イベントの W3C トレース コンテキスト

本文の詳細

以下に、考えられる通知スキーマごとに、このメッセージの種類の例を示します。

{
    "id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "subject": "example-twin1",
    "data": {
      "data": {
        "$dtId": "example-twin1",
        "$etag": "W/\"ecf81d6c-8c1a-4a95-afd8-13bd4cea436f\"",
        "room": "room name",
        "$metadata": {
          "$model": "dtmi:examplecom:interfaceName;1",
          "room": {
            "lastUpdateTime": "2021-12-09T20:28:52.6651216Z"
          }
        }
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-51f716e7397ec64b-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Create",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.6745538Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

デジタル ツインのリレーションシップの変更通知

リレーションシップの変更通知は、デジタル ツインのリレーションシップが作成、更新、または削除されたときにトリガーされます。

Properties

リレーションシップ変更通知の本文に含まれるフィールドを次に示します。

Name 値
id サービスによって管理される UUID やカウンターなどの、通知の識別子。 source + id は個別のイベントごとに一意です
source Azure Digital Twins インスタンスの名前 (mydigitaltwins.westus2.azuredigitaltwins.net など)
data 変更されたリレーションシップのペイロード。 詳細については、下の本文の詳細を参照してください。
specversion 1.0
メッセージは、CloudEvents 標準のこのバージョンに準拠しています。
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject リレーションシップの ID (<twin-ID>/relationships/<relationshipID> など)
time リレーションシップで操作が発生したときのタイムスタンプ
traceparent イベントの W3C トレース コンテキスト

本文の詳細

メッセージ内の data フィールドには、リレーションシップのペイロードが JSON 形式で格納されます。 これは、DigitalTwins API を介して、リレーションシップの GET 要求と同じ形式を使用します。

以下に、考えられる通知スキーマごとに、このメッセージの種類の例を示します。

{
    "id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "data": {
    "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
        {
            "value": "new value",
            "path": "/prop1",
            "op": "replace"
        }
        ]
    },
    "contenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-c1fcf951f540ec44-01"
    },
    "eventType": "Microsoft.DigitalTwins.Relationship.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:53.2016395Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

デジタル ツインのテレメトリ メッセージ

デジタル ツインは、SendTelemetry API を使用して テレメトリ メッセージ を出力し、それらをエグレス エンドポイントに送信できます。

Properties

テレメトリ メッセージの本文に含まれるフィールドを次に示します。

Name 値
id テレメトリ API を呼び出す際にユーザーにより指定される、通知の識別子。
source テレメトリ イベントの送信元のツインの完全修飾名。 次の形式を使用します: <your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>。
specversion 1.0
メッセージは、CloudEvents 標準のこのバージョンに準拠しています。
type microsoft.iot.telemetry
data ツインから送信されるテレメトリ メッセージ。 ペイロードは、Azure Digital Twins インスタンスで定義されているスキーマに合わせる必要はありません。
dataschema データ スキーマは、テレメトリを生成するツインまたはコンポーネントのモデル ID です。 たとえば、「 dtmi:example:com:floor4;2 」のように入力します。
datacontenttype application/json
traceparent イベントの W3C トレース コンテキスト。

本文の詳細

本文には、ツインに関するいくつかのコンテキスト情報と共に、テレメトリの測定値が含まれています。 以下に、考えられる通知スキーマごとに、このメッセージの種類の例を示します。

{
    "id": "6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "subject": "example-twin1",
    "data": {
        "data": {
        "prop": "hello from telemetry"
        },
        "dataschema": "dtmi:examplecom:interfaceName;1",
        "contenttype": "application/json-patch+json; charset=utf-8",
        "traceparent": "00-2aa957558db348f387ef704b37631a1d-e894098b46243743-01"
    },
    "eventType": "microsoft.iot.telemetry",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "0001-01-01T00:00:00Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

次のステップ

エンドポイントとルートを使用して、さまざまな宛先にイベントを配信する方法について説明します。