イベント通知

[アーティクル]
08/01/2024

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

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

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

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

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

通知の構造

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

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

Azure Event Grid イベントスキーマ
CloudEvents の HTTP プロトコルバインド。

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

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

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

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

プロパティ

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

名前	値
`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>"
}

{
    "specversion": "1.0",
    "id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "type": "Microsoft.DigitalTwins.Twin.Update",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "data": {
      "modelId": "dtmi:examplecom:interfaceName;1",
      "patch": [
        {
          "value": "new name",
          "path": "/room",
          "op": "replace"
        }
      ]
    },
    "subject": "example-twin1",
    "time": "2021-12-09T20:28:52.9795363Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-590d733a1b798149-01"
}

AMQP の application-properties セクションのプロパティを示す例:

    "cloudEvents:id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Twin.Update",
    "cloudEvents:time": "2021-12-09T20:28:52.9795363Z",
    "cloudEvents:subject": "example-twin1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-e66f14eb07b50d40-01"

AMQP の data セクションに格納されたメッセージ本文の例:

{
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
      {
        "value": "new name",
        "path": "/room",
        "op": "replace"
      }
    ]
}

Note

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

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

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

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

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

プロパティ

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

名前	値
`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>"
}

{
    "specversion": "1.0",
    "id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "type": "Microsoft.DigitalTwins.Twin.Create",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "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"
        }
      }
    },
    "subject": "example-twin1",
    "time": "2021-12-09T20:28:52.6745538Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-96f834571bf4fe45-01"
}

AMQP の application-properties セクションのプロパティを示す例:

    "cloudEvents:id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Twin.Create",
    "cloudEvents:time": "2021-12-09T20:28:52.6745538Z",
    "cloudEvents:subject": "example-twin1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-a158c39c72ec1049-01"

AMQP の 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"
        }
    }
}

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

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

プロパティ

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

名前	値
`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>"
}

{
    "specversion": "1.0",
    "id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "type": "Microsoft.DigitalTwins.Relationship.Update",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "data": {
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
        {
        "value": "new value",
        "path": "/prop1",
        "op": "replace"
        }
    ]
    },
    "subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "time": "2021-12-09T20:28:53.2016395Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-723b3f49efd2e445-01"
}

AMQP の application-properties セクションのプロパティを示す例:

    "cloudEvents:id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Relationship.Update",
    "cloudEvents:time": "2021-12-09T20:28:53.2016395Z",
    "cloudEvents:subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-6f3805aab2b73e49-01"

AMQP の data セクションに格納されたメッセージ本文の例:

{
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
      {
        "value": "new value",
        "path": "/prop1",
        "op": "replace"
      }
    ]
}

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

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

プロパティ

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

名前	値
`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>"
}

{
    "specversion": "1.0",
    "id": "622e6818-f042-4be8-96df-1a77ee9caf9b",
    "type": "microsoft.iot.telemetry",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net/digitaltwins/RuntimeEventsScenario_componentTwin_6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "data": {
        "prop": "hello from telemetry"
    },
    "dataschema": "dtmi:examplecom:interfaceName;1",
    "subject": "component1",
    "datacontenttype": "application/json-patch+json; charset=utf-8",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-f58ef0c31162c548-01"
}

AMQP の application-properties セクションのプロパティを示す例:

    "cloudEvents:id": "6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net/digitaltwins/example-twin1",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "microsoft.iot.telemetry",
    "cloudEvents:dataschema": "dtmi:examplecom:interfaceName;1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-ce042d67cbbfd948-01"

AMQP の data セクションに格納されたメッセージ本文の例:

{
    "Temperature": 50
}

次のステップ

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

エンドポイントとイベントルート

次の方法で共有

イベント通知

通知の構造

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

プロパティ

本文の詳細

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

プロパティ

本文の詳細

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

プロパティ

本文の詳細

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

プロパティ

本文の詳細

次のステップ

フィードバック

その他のリソース

次の方法で共有

イベント通知

通知の構造

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

プロパティ

本文の詳細

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

プロパティ

本文の詳細

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

プロパティ

本文の詳細

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

プロパティ

本文の詳細

次のステップ

フィードバック

その他のリソース

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

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

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

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