Végpontok és útvonalak kezelése az Azure Digital Twinsben

Ez a cikk végigvezeti a végpontok és útvonalak létrehozásának folyamatán a Azure Portal, a REST API-k, a .NET (C#) SDK és az Azure Digital Twins parancssori felület használatával.

Az Azure Digital Twinsben az eseményértesítéseket alárendelt szolgáltatásokhoz vagy csatlakoztatott számítási erőforrásokhoz irányíthatja. Ez a folyamat az események fogadására képes végpontok beállításával végezhető el. Ezután létrehozhat eseményútvonalakat, amelyek megszabják, hogy az Azure Digital Twins által létrehozott események közül melyek melyik végponthoz kerülnek.

Előfeltételek

  • Szüksége lesz egy Azure-fiókra, amely ingyenesen beállítható
  • Szüksége lesz egy Azure Digital Twins-példányra az Azure-előfizetésében. Ha még nincs példánya, létrehozhat egyet a példány és a hitelesítés beállításának lépéseit követve. A cikk későbbi részében az alábbi értékeket használhatja a beállításból:
    • Példány neve
    • Erőforráscsoport

Ezeket az adatokat a példány beállítása után a Azure Portal találja. Jelentkezzen be a portálra, és keresse meg a példány nevét a portál keresősávján.

Képernyőkép Azure Portal keresősávról.

Válassza ki a példányt az eredmények közül, és tekintse meg ezeket a részleteket a példány áttekintésében:

Képernyőkép az Azure Digital Twins-példány áttekintési oldaláról a Azure Portal. A név és az erőforráscsoport ki van emelve.

Kövesse az alábbi utasításokat, ha az útmutatót követve szeretné használni az Azure CLI-t.

A környezet előkészítése az Azure CLI-hez

Végpont létrehozása az Azure Digital Twinshez

Ezek a szolgáltatások a példányhoz létrehozható végpontok támogatott típusai:

Megjegyzés

Az Event Grid-végpontok esetében csak az Event Grid-témakörök támogatottak. Az Event Grid-tartományok nem támogatottak végpontként.

A különböző végponttípusokkal kapcsolatos további információkért tekintse meg az Azure üzenetkezelési szolgáltatások közötti választást ismertető cikket.

Ez a szakasz azt ismerteti, hogyan hozhat létre végpontot a Azure Portal vagy az Azure CLI használatával. A végpontokat a DigitalTwinsEndpoint vezérlősík API-jaival is kezelheti.

Előfeltétel: Végponterőforrások létrehozása

Ahhoz, hogy egy végpontot az Azure Digital Twinshez csatoljon, a végponthoz használt Event Grid-témakörnek, eseményközpontnak vagy Service Bus-témakörnek már léteznie kell.

Az alábbi diagramon megtekintheti, hogy milyen erőforrásokat kell beállítani a végpont létrehozása előtt.

Végpont típusa Szükséges erőforrások (létrehozási utasításokhoz csatolva)
Event Grid-végpont Event Grid-témakör
*az eseménysémának Event Grid-sémának vagy felhőbeli eseményséma 1.0-s verziójának kell lennie
Event Hubs-végpont Event Hubs-névtér

eseményközpont

(Nem kötelező) hitelesítési szabály kulcsalapú hitelesítéshez
Service Bus-végpont Service Bus-névtér

Service Bus-témakör

(Nem kötelező) hitelesítési szabály kulcsalapú hitelesítéshez

A végpont létrehozása

Miután létrehozta a végpont erőforrásait, használhatja őket egy Azure Digital Twins-végponthoz.

Új végpont létrehozásához lépjen a példány lapjára a Azure Portal (a példányt a portál keresősávjába beírt névvel találhatja meg).

  1. A példány menüjében válassza a Végpontok lehetőséget. Ezután a következő Végpontok lapon válassza a + Végpont létrehozása lehetőséget. Ezzel megnyitja a Végpont létrehozása lapot, ahol az alábbi lépésekben kitöltheti a mezőket.

    Képernyőkép egy Event Grid típusú végpont létrehozásáról a Azure Portal.

  2. Adja meg a végpont nevét , és válassza ki a végpont típusát.

  3. Töltse ki a végponttípushoz szükséges egyéb részleteket, beleértve az előfizetést és a fent leírt végponterőforrásokat.

    1. Csak Event Hubs- és Service Bus-végpontok esetén ki kell választania egy hitelesítési típust. Kulcsalapú hitelesítést használhat egy előre létrehozott engedélyezési szabománnyal, vagy identitásalapú hitelesítést, ha a végpontot felügyelt identitással fogja használni az Azure Digital Twins-példányhoz.

    Képernyőkép egy Event Hubs típusú végpont létrehozásáról a Azure Portal.

  4. Fejezze be a végpont létrehozását a Mentés gombra kattintva.

Fontos

Ahhoz, hogy sikeresen használhassa az identitásalapú hitelesítést a végponthoz, létre kell hoznia egy felügyelt identitást a példányhoz az Események átirányítása felügyelt identitással című szakasz lépéseit követve.

A végpont létrehozása után a felső Azure Portal sáv értesítési ikonjának ellenőrzésével ellenőrizheti, hogy a végpont sikeresen létrejött-e:

Képernyőkép az értesítésről a végpont létrehozásának ellenőrzéséhez a Azure Portal.

Ha a végpont létrehozása sikertelen, figyelje meg a hibaüzenetet, és próbálkozzon újra néhány perc múlva.

Az Azure Digital Twins-példány Végpontok lapján létrehozott végpontot is megtekintheti.

Az Event Grid, az Event Hub vagy a Service Bus-témakör mostantól végpontként érhető el az Azure Digital Twinsben a végponthoz választott név alatt. Ezt a nevet általában egy eseményútvonal céljaként fogja használni, amelyet a cikk későbbi részében fog létrehozni.

Végpont létrehozása kézbesíthetetlen levelek használatával

Ha egy végpont nem tud eseményt kézbesíteni egy adott időtartamon belül, vagy ha bizonyos számú alkalommal próbálja kézbesíteni az eseményt, a kézbesítetlen eseményt elküldheti egy tárfiókba. Ezt a folyamatot kézbesíthetetlen leveleknek nevezzük.

A szükséges tárolási erőforrásokat a Azure Portal vagy az Azure Digital Twins parancssori felületével állíthatja be. Ha azonban engedélyezni szeretné a kézbesíthetetlen levelek használatát, az Azure Digital Twins parancssori felületét vagy a vezérlősík API-jait kell használnia.

További információ a kézbesíthetetlen levelekről: Végpontok és eseményútvonalak. A végpontok kézbesíthetetlen levelek használatával történő beállításával kapcsolatos útmutatásért tekintse meg a szakasz további részeit.

Tárolási erőforrások beállítása

A kézbesíthetetlen levelek helyének beállítása előtt rendelkeznie kell egy tárfiókkal , amelyben be van állítva egy tároló az Azure-fiókjában.

A végpont későbbi létrehozásakor meg kell adnia a tároló URI-ját. A kézbesíthetetlen levelek helyét a rendszer sas-jogkivonattal rendelkező tároló URI-ként adja meg a végpontnak. A jogkivonatnak engedélyre van szüksége write a tárfiókon belüli céltárolóhoz. A teljesen formázott SAS URI a következő formátumban lesz: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Az alábbi lépéseket követve állítsa be ezeket a tárolási erőforrásokat az Azure-fiókjában, hogy felkészüljön a végpontkapcsolat beállítására a következő szakaszban.

  1. A tárfiók azure-előfizetésben való létrehozásához kövesse a Tárfiók létrehozása című témakör lépéseit. Jegyezze fel a tárfiók nevét, hogy később használhassa.
  2. Az új tárfiókon belüli tároló létrehozásához kövesse a Tároló létrehozása című témakör lépéseit. Jegyezze fel a tároló nevét, hogy később használhassa.
SAS-jogkivonat létrehozása

Ezután hozzon létre egy SAS-jogkivonatot a tárfiókhoz, amelyet a végpont használhat a hozzáféréshez.

  1. Első lépésként navigáljon a tárfiókhoz a Azure Portal (a portál keresősávján név szerint megtalálhatja).

  2. A tárfiók oldalán válassza a közös hozzáférésű jogosultságkód hivatkozását a bal oldali navigációs sávon az SAS-jogkivonat beállításának megkezdéséhez.

    Képernyőkép a tárfiók oldaláról a Azure Portal.

  3. A Közös hozzáférésű jogosultságkód lapEngedélyezett szolgáltatások és Engedélyezett erőforrástípusok területén válassza ki a kívánt beállításokat. Minden kategóriában legalább egy mezőt ki kell jelölnie. Az Engedélyezett engedélyek területen válassza az Írás lehetőséget (igény szerint más engedélyeket is kiválaszthat).

  4. Adja meg, hogy milyen értékeket szeretne megadni a többi beállításhoz.

  5. Ha végzett, válassza az SAS létrehozása és kapcsolati sztring gombot az SAS-jogkivonat létrehozásához.

    Képernyőkép a tárfiók oldaláról a Azure Portal, amelyen az SAS-jogkivonat létrehozásához kiválasztott összes beállítás látható.

  6. Ezzel több SAS-értéket hoz létre, és kapcsolati sztring értékeket az oldal alján, a beállításkijelölések alatt. Görgessen le az értékek megtekintéséhez, és a Másolás a vágólapra ikonnal másolja ki az SAS-jogkivonat értékét. Mentse későbbi használatra.

    Képernyőkép a tárfiók oldaláról a Azure Portal, amely bemutatja, hogyan másolhatja át az SAS-jogkivonatot a kézbesíthetetlen levelek titkos kódjában való használatra.

A kézbesíthetetlen levelek végpontjának létrehozása

Ha engedélyezni szeretné a kézbesíthetetlen levelek használatát, a végpont létrehozásához a parancssori felület parancsait vagy vezérlősík API-jait kell használnia a végpont létrehozásához a Azure Portal helyett.

Az ilyen típusú végpontok Azure CLI-vel való létrehozásával kapcsolatos utasításokért váltson a jelen szakasz PARANCSSORI lapjára.

Üzenettárolási séma

Miután beállította a kézbesítetlen levelek végpontját, a kézbesítetlen levelek a következő formátumban lesznek tárolva a tárfiókban:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

A kézbesítetlen levelek megegyeznek az eredeti esemény sémájának, amelyet az eredeti végpontnak szántak.

Íme egy példa az ikerpéldány-létrehozási értesítés kézbesíthetetlen levelekre vonatkozó üzenetére:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Eseményútvonal létrehozása

Ahhoz, hogy ténylegesen adatokat küldjön az Azure Digital Twinsből egy végpontra, meg kell határoznia egy eseményútvonalat. Ezek az útvonalak lehetővé teszik a fejlesztők számára az eseményfolyamok átvitelét a teljes rendszerben és a lefelé irányuló szolgáltatásokban. Egyetlen útvonal több értesítés és eseménytípus kiválasztását is lehetővé teszi. További információ a végpontok és az eseményútvonalak eseményútvonalairól.

Előfeltétel: Hozzon létre végpontokat a cikk korábbi részében leírtak szerint, mielőtt továbblép az útvonal létrehozására. Ha a végpontok beállítása befejeződött, folytathatja az eseményútvonal létrehozását.

Megjegyzés

Ha nemrég telepítette a végpontokat, ellenőrizze, hogy befejezték-e az üzembe helyezést, mielőtt új eseményútvonalhoz próbálnák használni őket. Ha az útvonal üzembe helyezése meghiúsul, mert a végpontok nem állnak készen, várjon néhány percet, és próbálkozzon újra.

Ha szkripteli ezt a folyamatot, érdemes lehet figyelembe vennie ezt úgy, hogy 2–3 perc várakozási idő alatt felépíti a végpontszolgáltatás üzembe helyezését, mielőtt továbblépne az útvonal beállítására.

Az útvonaldefiníciók a következő elemeket tartalmazhatják:

  • A használni kívánt útvonalnév
  • A használni kívánt végpont neve
  • Egy szűrő, amely meghatározza, hogy mely események kerülnek a végponthoz
    • Ha le szeretné tiltani az útvonalat, hogy ne legyen elküldve esemény, használja a következő szűrőértéket: false
    • Ha olyan útvonalat szeretne engedélyezni, amelynek nincs konkrét szűrése, használja a következő szűrőértéket: true
    • A többi szűrőtípussal kapcsolatos részletekért lásd az alábbi Szűrési események szakaszt

Ha nincs útvonalnév, a rendszer nem irányít át üzeneteket az Azure Digital Twinsen kívül. Ha van útvonalnév, és a szűrő az true, az összes üzenet a végpontra lesz irányítva. Ha van egy útvonalnév, és egy másik szűrőt ad hozzá, az üzenetek a szűrő alapján lesznek szűrve.

Eseményútvonalak a Azure Portal, az EventRoutes adatsík API-jaival vagy az dt route CLI-parancsokkal hozhatók létre. A szakasz további része végigvezeti a létrehozási folyamaton.

Eseményútvonal létrehozásához lépjen az Azure Digital Twins-példány részletek lapjára a Azure Portal (a példányt a portál keresősávjába beírt névvel találja meg).

A példány menüjében válassza az Eseményútvonalak lehetőséget. Ezután a következő Eseményútvonalak lapon válassza a + Eseményútvonal létrehozása lehetőséget.

A megnyíló eseményútvonal létrehozása lapon válasszon legalább:

  • Az útvonal neve a Név mezőben
  • Az útvonal létrehozásához használni kívánt végpont

Ahhoz, hogy az útvonal engedélyezve legyen, legalább egy eseményútvonal-szűrőttrueis hozzá kell adnia. (Az alapértelmezett érték elhagyásával false létrejön az útvonal, de a rendszer nem küld neki eseményeket.) Ehhez kapcsolja be a Speciális szerkesztő kapcsolót, és írja be true a Szűrő mezőbe.

Képernyőkép a példány eseményútvonalának létrehozásáról a Azure Portal.

Ha végzett, válassza a Mentés gombot az eseményútvonal létrehozásához.

Események szűrése

A fentiekben leírtak szerint az útvonalak szűrőmezővel rendelkeznek. Ha az útvonal szűrőértéke az false, a rendszer nem küld eseményeket a végpontnak.

A minimális szűrő trueengedélyezése után a végpontok különböző típusú eseményeket kapnak az Azure Digital Twinstől:

  • Digitális ikerpéldányok által aktivált telemetriai adatok az Azure Digital Twins szolgáltatás API-jának használatával
  • Ikertulajdonság-változási értesítések, aktiválva az Azure Digital Twins-példány bármelyik ikerpéldányának tulajdonságváltozásai miatt
  • Életciklus-események, ikerpéldányok vagy kapcsolatok létrehozásakor vagy törlésekor aktiválódnak

Az elküldött események típusait egy pontosabb szűrő definiálásával korlátozhatja.

Megjegyzés

A szűrők megkülönböztetik a kis- és nagybetűket, és meg kell egyezniük a hasznos adatokkal.

A telemetriai szűrők esetében ez azt jelenti, hogy a burkolatnak meg kell egyeznie az eszköz által küldött telemetriában szereplő burkolattal, nem feltétlenül az ikerpéldány modelljében definiált burkolattal.

Eseményútvonal létrehozásakor eseményszűrő hozzáadásához használja az Eseményútvonal létrehozása lap Eseményútvonal-szűrő hozzáadása szakaszát.

Választhat néhány alapvető gyakori szűrőbeállítás közül, vagy használhatja a speciális szűrőbeállításokat saját egyéni szűrők írásához.

Az alapszintű szűrők használata

Az alapvető szűrők használatához bontsa ki az Eseménytípusok lehetőséget, és jelölje be a végpontnak elküldeni kívánt eseményeknek megfelelő jelölőnégyzeteket.

Képernyőkép egy eseményútvonal létrehozásáról egy alapszintű szűrővel a Azure Portal, kiemelve az események jelölőnégyzeteit.

Ezzel automatikusan kitölti a szűrő szövegmezőt a kijelölt szűrő szövegével:

Képernyőkép egy eseményútvonal létrehozásáról egy alapszintű szűrővel a Azure Portal, kiemelve az automatikusan kitöltött szűrőszöveget az események kiválasztása után.

A speciális szűrők használata

A speciális szűrőbeállítással saját egyéni szűrőket is írhat.

Ha speciális szűrőbeállításokat tartalmazó eseményútvonalat szeretne létrehozni, állítsa be a Speciális szerkesztő kapcsolóját annak engedélyezéséhez. Ezután megírhatja a saját eseményszűrőit a Szűrő mezőbe:

Képernyőkép egy eseményútvonal létrehozásáról egy speciális szűrővel a Azure Portal.

Támogatott útvonalszűrők

Íme a támogatott útvonalszűrők.

Szűrő neve Leírás Szövegséma szűrése Támogatott értékek
Igaz /Hamis Lehetővé teszi az útvonalak szűrés nélküli létrehozását vagy az útvonal letiltását, hogy ne legyen elküldve esemény <true/false> true = az útvonal szűrés nélkül engedélyezve van
false = az útvonal le van tiltva
Típus A digitális ikerpéldányon áthaladó esemény típusa type = '<event-type>' Az alábbi lehetséges eseménytípus-értékek:
Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
Microsoft.DigitalTwins.Twin.Update
Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
microsoft.iot.telemetry
Forrás Az Azure Digital Twins-példány neve source = '<host-name>' Íme a lehetséges állomásnévértékek:

Értesítések esetén: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net

Telemetria esetén: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Tárgy Az esemény leírása a fenti eseményforrás kontextusában subject = '<subject>' A lehetséges tárgyértékek a következők:

Értesítések esetén: A tárgy a következő: <twin-ID>
vagy a témák URI-formátuma, amelyet több rész vagy azonosító egyedileg azonosít:
<twin-ID>/relationships/<relationship-ID>

Telemetria esetén: A tárgy az összetevő elérési útja (ha a telemetria egy ikerösszetevőből származik), például comp1.comp2. Ha a telemetria nem egy összetevőből van kibocsátva, akkor a tárgymező üres.
Adatséma DTDL-modell azonosítója dataschema = '<model-dtmi-ID>' Telemetria esetén: Az adatséma az ikerpéldány vagy a telemetriát kibocsátó összetevő modellazonosítója. Például: dtmi:example:com:floor4;2

Értesítések esetén (létrehozás/törlés): Az adatséma a következő $body.$metadata.$modelértesítési törzsben érhető el: .

Értesítések (frissítés): Az adatséma a következő címen érhető el az értesítési törzsben: $body.modelId
Tartalomtípus Adatérték tartalomtípusa datacontenttype = '<content-type>' A tartalomtípus a következő: application/json
Specifikáció verziója A használt eseményséma verziója specversion = '<version>' A verziónak a következőnek kell lennie 1.0: . Ez az érték a CloudEvents séma 1.0-s verzióját jelzi
Értesítés törzse Hivatkozás az data értesítési mező bármely tulajdonságára $body.<property> Az eseményértesítések között találhat példákat az értesítésekre. A mező bármely tulajdonságára hivatkozhat a data következővel: $body

Megjegyzés

Az Azure Digital Twins jelenleg nem támogatja a tömbök mezői alapján történő szűrést. Ez magában foglalja a tulajdonságok szűrését a digitális ikerpéldány változásáról szóló értesítés egy patch szakaszán belül.

A fenti adatokra mutató hivatkozások által visszaadott értékek a következő adattípusokat támogatják:

Adattípus Példa
Sztring STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
CONTAINS(subject, '<twin-ID>')
Egész szám $body.errorCode > 200
Dupla $body.temperature <= 5.5
Logikai $body.poweredOn = true
Null $body.prop != null

Útvonalszűrők definiálásakor a következő operátorok támogatottak:

Family (Család) Operátorok Példa
Logikai AND, OR, ( ) (type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Összehasonlítás <, <=, >, >=, =, != $body.temperature <= 5.5

Az útvonalszűrők definiálásakor a következő függvények támogatottak:

Függvény Leírás Példa
STARTS_WITH(x;y) Igaz értéket ad vissza, ha az érték x a sztringgel ykezdődik. STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x;y) Igaz értéket ad vissza, ha az érték x a sztringgel yvégződik. ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x;y) Igaz értéket ad vissza, ha az érték x tartalmazza a sztringet y. CONTAINS(subject, '<twin-ID>')

Szűrő megvalósításakor vagy frissítésekor eltarthat néhány percig, amíg a módosítás megjelenik az adatfolyamban.

Eseményútvonalak monitorozása

Az útválasztási metrikák, például a szám, a késés és a hibaarány megtekinthetők a Azure Portal.

A portál kezdőlapján keresse meg az Azure Digital Twins-példányt a részleteinek lekéréséhez. Válassza a Metrikák lehetőséget a bal oldali Azure Digital Twins-példány navigációs menüjében a Metrikák lap megjelenítéséhez.

Képernyőkép az Azure Digital Twins metrikaoldalával.

Itt megtekintheti a példány metrikáit, és egyéni nézeteket hozhat létre.

Az Azure Digital Twins-metrikák megtekintéséről további információt a Monitor with metrics (Monitorozás metrikákkal) című témakörben talál.

Következő lépések

Olvassa el a különböző típusú eseményüzeneteket, amelyek fogadhatók: