共用方式為

事件通知

  • 發行項

本文涵蓋 Azure Digital Twins 產生的事件通知、事件通知的結構，及可能產生的各種類型詳細資料。

Azure Digital Twins 中不同的事件會產生通知，讓解決方案後端能夠感知不同動作發生的時間。 接下來，這些通知會路由傳送至 Azure Digital Twins 內部和外部的不同位置，使用這些資訊採取動作。

可能產生的通知類型有數種，而通知訊息看起來可能因產生訊息的事件種類而有所不同。 本文提供不同類型的訊息和訊息外觀的詳細資料。

此圖表顯示不同的通知類型：

通知類型 路由來源名稱 產生自...
數位對應項變更通知 數位對應項變更通知 任何數位對應項屬性變更
數位對應項生命週期通知 數位對應項生命週期通知 任何數位對應項建立或刪除作業
數位對應項關聯性變更通知 數位對應項關聯性變更通知 任何數位對應項關聯性變更
數位對應項遙測訊息 遙測訊息 任何遙測訊息

通知結構

來自 Azure Digital Twins 的事件通知結構取決於通知的目的地。

傳送至事件方格通知符合下列其中一種格式 (取決於事件方格設定)：

傳送至事件中樞和服務匯流排的通知符合 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 數位對應項的識別碼
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>"
}

注意

Azure Digital Twins 目前不支援以陣列中欄位為基礎的篩選事件， 這包含在數位對應項變更通知的 patch 區段中篩選屬性。

數位對應項生命週期通知

無論數位對應項是否代表 Azure Digital Twins 中的 IoT 中樞裝置，這些數位對應項都會發出通知， 這是由於「生命週期通知」的緣故，這與數位對應項本身相關。

下列情況會觸發生命週期通知：

  • 建立數位對應項
  • 刪除數位對應項

屬性

以下是生命週期通知本文中的欄位。

名稱 值
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 數位對應項的識別碼
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>"
}

數位對應項關聯性變更通知

建立、更新或刪除數位對應項的任何關聯性時，即會觸發關聯性變更通知。

屬性

以下是關聯性變更通知本文中的欄位。

名稱 值
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 關聯性的識別碼，例如 <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 發出「遙測訊息」，並將其傳送至出口端點。

屬性

以下是遙測訊息本文中的欄位。

名稱 值
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 資料結構描述是對應項的模型識別碼，或發出遙測的元件。 例如： 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>"
}

下一步

了解如何使用端點和路由，傳遞事件至不同的目的地：