Powiadomienia o zdarzeniach

Artykuł
06/01/2023

W tym artykule opisano powiadomienia o zdarzeniach generowane przez usługę Azure Digital Twins, ich strukturę i szczegóły dotyczące różnych typów, które można wygenerować.

Różne zdarzenia w usłudze Azure Digital Twins generują powiadomienia, które umożliwiają zapleczu rozwiązania świadomość, kiedy występują różne akcje. Te powiadomienia są następnie kierowane do różnych lokalizacji wewnątrz i poza usługą Azure Digital Twins, które mogą użyć tych informacji do podjęcia działań.

Istnieje kilka typów powiadomień, które można wygenerować, a komunikaty powiadomień mogą wyglądać inaczej w zależności od typu wygenerowanego zdarzenia. Ten artykuł zawiera szczegółowe informacje o różnych typach komunikatów i o tym, jak mogą wyglądać.

Ten wykres przedstawia różne typy powiadomień:

Typ powiadomienia	Nazwa źródła routingu	Generowane z...
Powiadomienie o zmianie cyfrowej reprezentacji bliźniaczej	Powiadomienie o zmianie cyfrowej reprezentacji bliźniaczej	dowolna zmiana właściwości cyfrowej reprezentacji bliźniaczej
Powiadomienie dotyczące cyklu życia cyfrowej reprezentacji bliźniaczej	Powiadomienie dotyczące cyklu życia cyfrowej reprezentacji bliźniaczej	dowolna operacja tworzenia lub usuwania cyfrowej reprezentacji bliźniaczej
Powiadomienie o zmianie relacji cyfrowej reprezentacji bliźniaczej	Powiadomienie o zmianie relacji cyfrowej reprezentacji bliźniaczej	dowolna zmiana relacji cyfrowej reprezentacji bliźniaczej
Komunikaty telemetryczne cyfrowej reprezentacji bliźniaczej	Komunikaty telemetryczne	dowolny komunikat telemetrii

Struktura powiadomień

Struktura powiadomienia o zdarzeniach z usługi Azure Digital Twins zależy od miejsca docelowego powiadomienia.

Powiadomienia wysyłane do usługi Event Grid są zgodne z jednym z następujących formatów (zależnych od ustawień usługi Event Grid):

schemat zdarzeń Azure Event Grid
Powiązanie protokołu HTTP dla rozwiązania CloudEvents.

Powiadomienia wysyłane do usługi Event Hubs i usługi Service Bus są zgodne z powiązaniem protokołu AMQP dla rozwiązania CloudEvents.

Powiadomienia o zmianie cyfrowej reprezentacji bliźniaczej

Powiadomienia o zmianie cyfrowej reprezentacji bliźniaczej są wyzwalane po zaktualizowaniu cyfrowej reprezentacji bliźniaczej, na przykład:

Gdy wartości właściwości lub metadane się zmieniają.
Gdy zmieniają się metadane cyfrowej reprezentacji bliźniaczej lub składnika. Przykładem tego scenariusza jest zmiana modelu cyfrowej reprezentacji bliźniaczej.

Właściwości

Poniżej przedstawiono pola w treści powiadomienia o zmianie cyfrowej reprezentacji bliźniaczej.

Nazwa	Wartość
`id`	Identyfikator powiadomienia, taki jak identyfikator UUID lub licznik obsługiwany przez usługę. `source` + `id` jest unikatowa dla każdego odrębnego zdarzenia
`source`	Nazwa centrum IoT lub wystąpienia usługi Azure Digital Twins, na przykład myhub.azure-devices.net lub mydigitaltwins.westus2.azuredigitaltwins.net
`data`	Dokument poprawki JSON opisujący aktualizację wprowadzoną do bliźniaczej reprezentacji. Aby uzyskać szczegółowe informacje, zobacz Szczegóły treści poniżej.
`specversion`	1.0 Komunikat jest zgodny z tą wersją specyfikacji CloudEvents.
`type`	`Microsoft.DigitalTwins.Twin.Update`
`datacontenttype`	`application/json`
`subject`	Identyfikator cyfrowej reprezentacji bliźniaczej
`time`	Sygnatura czasowa dla momentu wystąpienia operacji na cyfrowej reprezentacji bliźniaczej
`traceparent`	Kontekst śledzenia W3C dla zdarzenia

Szczegóły treści

Wewnątrz komunikatu data pole zawiera dokument poprawki JSON zawierający aktualizację cyfrowej reprezentacji bliźniaczej.

Poniżej przedstawiono przykłady tego typu komunikatu dla każdego możliwego schematu powiadomień.

{
    "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"
}

Przykład przedstawiający właściwości w sekcji właściwości aplikacji amQP :

    "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"

Przykładowa treść komunikatu wypełniona w sekcji danych amQP:

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

Uwaga

Usługa Azure Digital Twins obecnie nie obsługuje filtrowania zdarzeń na podstawie pól w tablicy. Obejmuje to filtrowanie właściwości w patch sekcji powiadomienia o zmianie cyfrowej reprezentacji bliźniaczej.

Powiadomienia dotyczące cyklu życia cyfrowej reprezentacji bliźniaczej

Niezależnie od tego, czy cyfrowe reprezentacje bliźniacze reprezentują urządzenia IoT Hub w usłudze Azure Digital Twins, czy nie, wszystkie będą emitować powiadomienia. Robią to ze względu na powiadomienia o cyklu życia, które dotyczą samej cyfrowej reprezentacji bliźniaczej.

Powiadomienia o cyklu życia są wyzwalane, gdy:

Tworzona jest cyfrowa reprezentacja bliźniacza
Usunięto cyfrową reprezentację bliźniaczą

Właściwości

Poniżej przedstawiono pola w treści powiadomienia o cyklu życia.

Nazwa	Wartość
`id`	Identyfikator powiadomienia, taki jak identyfikator UUID lub licznik obsługiwany przez usługę. `source` + `id` jest unikatowa dla każdego odrębnego zdarzenia.
`source`	Nazwa centrum IoT lub wystąpienia usługi Azure Digital Twins, na przykład myhub.azure-devices.net lub mydigitaltwins.westus2.azuredigitaltwins.net
`data`	Dane bliźniaczej reprezentacji, w której występuje zdarzenie cyklu życia. Aby uzyskać szczegółowe informacje, zobacz Szczegóły treści poniżej.
`specversion`	1.0 Komunikat jest zgodny z tą wersją specyfikacji CloudEvents.
`type`	`Microsoft.DigitalTwins.Twin.Create` `Microsoft.DigitalTwins.Twin.Delete`
`datacontenttype`	`application/json`
`subject`	Identyfikator cyfrowej reprezentacji bliźniaczej
`time`	Sygnatura czasowa dla momentu wystąpienia operacji na bliźniaczej reprezentacji
`traceparent`	Kontekst śledzenia W3C dla zdarzenia

Szczegóły treści

Poniżej przedstawiono przykłady tego typu komunikatu dla każdego możliwego schematu powiadomień.

{
    "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"
}

Przykład przedstawiający właściwości w sekcji właściwości aplikacji amQP :

    "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"

Przykładowa treść komunikatu wypełniona w sekcji danych amQP:

{
    "$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"
        }
    }
}

Powiadomienia o zmianie relacji cyfrowej reprezentacji bliźniaczej

Powiadomienia o zmianie relacji są wyzwalane po utworzeniu, zaktualizowaniu lub usunięciu dowolnej relacji cyfrowej reprezentacji bliźniaczej.

Właściwości

Poniżej przedstawiono pola w treści powiadomienia o zmianie relacji.

Nazwa	Wartość
`id`	Identyfikator powiadomienia, taki jak identyfikator UUID lub licznik obsługiwany przez usługę. `source` + `id` jest unikatowa dla każdego odrębnego zdarzenia
`source`	Nazwa wystąpienia usługi Azure Digital Twins, na przykład mydigitaltwins.westus2.azuredigitaltwins.net
`data`	Ładunek relacji, który został zmieniony. Aby uzyskać szczegółowe informacje, zobacz Szczegóły treści poniżej.
`specversion`	1.0 Komunikat jest zgodny z tą wersją specyfikacji CloudEvents.
`type`	`Microsoft.DigitalTwins.Relationship.Create` `Microsoft.DigitalTwins.Relationship.Update` `Microsoft.DigitalTwins.Relationship.Delete`
`datacontenttype`	`application/json`
`subject`	Identyfikator relacji, na przykład `<twin-ID>/relationships/<relationshipID>`
`time`	Sygnatura czasowa dla momentu wystąpienia operacji w relacji
`traceparent`	Kontekst śledzenia W3C dla zdarzenia

Szczegóły treści

Wewnątrz komunikatu data pole zawiera ładunek relacji w formacie JSON. Używa on tego samego formatu co GET żądanie relacji za pośrednictwem interfejsu API DigitalTwins.

Poniżej przedstawiono przykłady tego typu komunikatu dla każdego możliwego schematu powiadomień.

{
    "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"
}

Przykład przedstawiający właściwości w sekcji właściwości aplikacji amQP :

    "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"

Przykładowa treść komunikatu wypełniona w sekcji danych amQP:

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

Komunikaty telemetryczne cyfrowej reprezentacji bliźniaczej

Cyfrowe reprezentacje bliźniacze mogą używać interfejsu API SendTelemetry do emitowania komunikatów telemetrycznych i wysyłania ich do punktów końcowych ruchu wychodzącego.

Właściwości

Poniżej przedstawiono pola w treści komunikatu telemetrycznego.

Nazwa	Wartość
`id`	Identyfikator powiadomienia udostępnianego przez klienta podczas wywoływania interfejsu API telemetrii.
`source`	W pełni kwalifikowana nazwa bliźniaczej reprezentacji, z którą wysłano zdarzenie telemetrii. Używa następującego formatu: `<your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`.
`specversion`	1.0 Komunikat jest zgodny z tą wersją specyfikacji CloudEvents.
`type`	`microsoft.iot.telemetry`
`data`	Komunikat telemetrii wysyłany z bliźniaczej reprezentacji. Ładunek nie musi być zgodny z żadnym schematem zdefiniowanym w wystąpieniu usługi Azure Digital Twins.
`dataschema`	Schemat danych to identyfikator modelu bliźniaczej reprezentacji lub składnika, który emituje dane telemetryczne. Na przykład `dtmi:example:com:floor4;2`.
`datacontenttype`	`application/json`
`traceparent`	Kontekst śledzenia W3C dla zdarzenia.

Szczegóły treści

Treść zawiera pomiar telemetrii wraz z pewnymi informacjami kontekstowymi dotyczącymi bliźniaczej reprezentacji. Poniżej przedstawiono przykłady tego typu komunikatu dla każdego możliwego schematu powiadomień.

{
    "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"
}

Przykład przedstawiający właściwości w sekcji właściwości aplikacji amQP :

    "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"

Przykładowa treść komunikatu wypełniona w sekcji danych amQP:

{
    "Temperature": 50
}

Następne kroki

Dowiedz się więcej o dostarczaniu zdarzeń do różnych miejsc docelowych przy użyciu punktów końcowych i tras:

Punkty końcowe i trasy zdarzeń

Share via

Powiadomienia o zdarzeniach

Struktura powiadomień

Powiadomienia o zmianie cyfrowej reprezentacji bliźniaczej

Właściwości

Szczegóły treści

Powiadomienia dotyczące cyklu życia cyfrowej reprezentacji bliźniaczej

Właściwości

Szczegóły treści

Powiadomienia o zmianie relacji cyfrowej reprezentacji bliźniaczej

Właściwości

Szczegóły treści

Komunikaty telemetryczne cyfrowej reprezentacji bliźniaczej

Właściwości

Szczegóły treści

Następne kroki

Dodatkowe zasoby