Udostępnij za pośrednictwem

Egress i punkty końcowe w usłudze Azure Digital Twins

  • Artykuł

Ważne

Wydano nową wersję usługi Azure Digital Twins. W świetle rozszerzonych możliwości nowej usługi oryginalna usługa Azure Digital Twins (opisana w tym zestawie dokumentacji) została wycofana.

Aby wyświetlić dokumentację nowej usługi, odwiedź aktywną dokumentację usługi Azure Digital Twins.

Punkty końcowe usługi Azure Digital Twins reprezentują komunikat lub broker zdarzeń w ramach subskrypcji platformy Azure użytkownika. Zdarzenia i komunikaty można wysyłać do tematów Azure Event Hubs, Azure Event Grid i Azure Service Bus.

Zdarzenia są kierowane do punktów końcowych zgodnie ze wstępnie zdefiniowanymi preferencjami routingu. Użytkownicy określają typy zdarzeń , które mogą odbierać poszczególne punkty końcowe.

Aby dowiedzieć się więcej o zdarzeniach, routingu i typach zdarzeń, zobacz Routing zdarzeń i komunikatów w usłudze Azure Digital Twins.

Zdarzenia

Zdarzenia są wysyłane przez obiekty IoT (takie jak urządzenia i czujniki) do przetwarzania przez brokerów komunikatów i zdarzeń platformy Azure. Zdarzenia są definiowane przez następujące odwołanie do schematu zdarzeń 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"
}
Atrybut Typ Opis
identyfikator ciąg Unikatowy identyfikator zdarzenia.
subject ciąg Zdefiniowana przez wydawcę ścieżka do tematu zdarzenia.
dane object Dane zdarzenia specyficzne dla dostawcy zasobów.
eventType ciąg Jeden z zarejestrowanych typów zdarzeń dla tego źródła zdarzeń.
eventTime ciąg Czas generowania zdarzenia na podstawie czasu UTC dostawcy.
dataVersion ciąg Wersja schematu obiektu danych. Wydawca definiuje wersję schematu.
metadataVersion ciąg Wersja schematu metadanych zdarzenia. Usługa Event Grid definiuje schemat właściwości najwyższego poziomu. Ta wartość jest podawana przez usługę Event Grid.
temat ciąg Pełna ścieżka zasobu do źródła zdarzeń. To pole nie jest możliwe do zapisu. Ta wartość jest podawana przez usługę Event Grid.

Aby uzyskać więcej informacji na temat schematu zdarzeń usługi Event Grid:

Typy zdarzeń

Typy zdarzeń klasyfikują charakter zdarzenia i są ustawiane w polu eventType . Dostępne typy zdarzeń są podane na następującej liście:

  • TopologiaOperation
  • UdfCustom
  • SensorChange
  • SpaceChange
  • DeviceMessage

Formaty zdarzeń dla każdego typu zdarzenia są bardziej szczegółowo opisane w poniższych podsekcjach.

TopologiaOperation

TopologiaOperation ma zastosowanie do zmian grafu. Właściwość podmiotu określa typ obiektu, którego dotyczy problem. Następujące typy obiektów mogą wyzwalać to zdarzenie:

  • Urządzenie
  • DeviceBlobMetadata
  • DeviceExtendedProperty
  • ExtendedPropertyKey
  • ExtendedType
  • Keystore
  • Raport
  • Definicja roli
  • Czujnik
  • SensorBlobMetadata
  • SensorExtendedProperty
  • Miejsce
  • SpaceBlobMetadata
  • SpaceExtendedProperty
  • SpaceResource
  • SpaceRoleAssignment
  • System
  • Użytkownik
  • UserBlobMetadata
  • UserExtendedProperty

Przykład

{
  "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"
}
Wartość Zamień na
YOUR_TOPIC_NAME Nazwa dostosowanego tematu

UdfCustom

UdfCustom to zdarzenie wysyłane przez funkcję zdefiniowaną przez użytkownika (UDF).

Ważne

To zdarzenie musi być jawnie wysyłane z samej funkcji UDF.

Przykład

{
  "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"
}
Wartość Zamień na
YOUR_TOPIC_NAME Nazwa dostosowanego tematu

SensorChange

SensorChange to aktualizacja stanu czujnika na podstawie zmian telemetrycznych.

Przykład

{
  "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"
}
Wartość Zamień na
YOUR_TOPIC_NAME Nazwa dostosowanego tematu

SpaceChange

SpaceChange to aktualizacja stanu przestrzeni na podstawie zmian telemetrycznych.

Przykład

{
  "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"
}
Wartość Zamień na
YOUR_TOPIC_NAME Nazwa dostosowanego tematu

DeviceMessage

Za pomocą funkcji DeviceMessage można określić połączenie usługi EventHub , z którym mogą być kierowane nieprzetworzone zdarzenia telemetryczne, a także z usługi Azure Digital Twins.

Uwaga

  • DeviceMessage można połączyć tylko z usługą EventHub. Nie można połączyć funkcji DeviceMessage z żadnym z innych typów zdarzeń.
  • Można określić tylko jeden punkt końcowy kombinacji typu EventHub lub DeviceMessage.

Konfigurowanie punktów końcowych

Zarządzanie punktami końcowymi jest wykonywane za pośrednictwem interfejsu API punktów końcowych.

W poniższych YOUR_MANAGEMENT_API_URL przykładach odwołuje się do identyfikatora URI interfejsów API usługi Digital Twins:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Nazwa Zamień na
YOUR_INSTANCE_NAME Nazwa wystąpienia usługi Azure Digital Twins
YOUR_LOCATION Region, w którym jest hostowane twoje wystąpienie

W poniższych przykładach pokazano, jak skonfigurować obsługiwane punkty końcowe.

Ważne

Zwróć szczególną uwagę na atrybut eventTypes . Definiuje, które typy zdarzeń są obsługiwane przez punkt końcowy, a tym samym określają jego routing.

Uwierzytelnione żądanie HTTP POST dla:

YOUR_MANAGEMENT_API_URL/endpoints

  • Kierowanie do Service Bus typów zdarzeń SensorChange, SpaceChange i 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"
}
    Wartość Zamień na
    YOUR_NAMESPACE Przestrzeń nazw punktu końcowego
    YOUR_PRIMARY_KEY Podstawowe parametry połączenia używane do uwierzytelniania
    YOUR_SECONDARY_KEY Pomocnicze parametry połączenia używane do uwierzytelniania
    YOUR_TOPIC_NAME Nazwa dostosowanego tematu

  • Kierowanie do typów zdarzeń usługi Event Grid SensorChange, SpaceChange i TopologyOperation: 

    {
  "type": "EventGrid",
  "eventTypes": [
    "SensorChange",
    "SpaceChange",
    "TopologyOperation"
  ],
  "connectionString": "YOUR_PRIMARY_KEY",
  "secondaryConnectionString": "YOUR_SECONDARY_KEY",
  "path": "YOUR_TOPIC_NAME.westus-1.eventgrid.azure.net"
}
    Wartość Zamień na
    YOUR_PRIMARY_KEY Podstawowe parametry połączenia używane do uwierzytelniania
    YOUR_SECONDARY_KEY Pomocnicze parametry połączenia używane do uwierzytelniania
    YOUR_TOPIC_NAME Nazwa dostosowanego tematu

  • Kierowanie do typów zdarzeń usługi Event Hubs SensorChange, SpaceChange i 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"
}
    Wartość Zamień na
    YOUR_NAMESPACE Przestrzeń nazw punktu końcowego
    YOUR_PRIMARY_KEY Podstawowe parametry połączenia używane do uwierzytelniania
    YOUR_SECONDARY_KEY Pomocnicze parametry połączenia używane do uwierzytelniania
    YOUR_EVENT_HUB_NAME Nazwa centrum zdarzeń

  • Kierowanie do typu zdarzeń usługi Event Hubs DeviceMessage. Włączenie parametru EntityPathconnectionString jest obowiązkowe:

    {
  "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"
}
    Wartość Zamień na
    YOUR_NAMESPACE Przestrzeń nazw punktu końcowego
    YOUR_PRIMARY_KEY Podstawowe parametry połączenia używane do uwierzytelniania
    YOUR_SECONDARY_KEY Pomocnicze parametry połączenia używane do uwierzytelniania
    YOUR_EVENT_HUB_NAME Nazwa centrum zdarzeń

Uwaga

Po utworzeniu nowego punktu końcowego może upłynąć do 5 do 10 minut, aby rozpocząć odbieranie zdarzeń w punkcie końcowym.

Podstawowe i pomocnicze klucze połączenia

Gdy podstawowy klucz połączenia stanie się nieautoryzowany, system automatycznie podejmie próbę dodatkowego klucza połączenia. Zapewnia to kopię zapasową i umożliwia bezproblemowe uwierzytelnianie i aktualizowanie klucza podstawowego za pomocą interfejsu API punktów końcowych.

Jeśli zarówno podstawowe, jak i pomocnicze klucze połączenia są nieautoryzowane, system wprowadza wykładniczy czas oczekiwania do 30 minut. Zdarzenia są porzucane dla każdego wyzwalanego czasu oczekiwania.

Za każdym razem, gdy system znajduje się w stanie oczekiwania wycofywania, aktualizowanie kluczy połączeń za pośrednictwem interfejsu API punktów końcowych może potrwać do 30 minut.

Nieochwytne punkty końcowe

Gdy punkt końcowy stanie się nieosiągalny, system wprowadza wykładniczy czas oczekiwania do 30 minut. Zdarzenia są porzucane dla każdego wyzwalanego czasu oczekiwania.

Następne kroki