Eseményútvonalak és -szűrők létrehozása az Azure Digital Twinsben

Ez a cikk végigvezeti az eseményútvonalak létrehozásának folyamatán az Azure Portal, az Azure CLI az dt route parancsok, az Event Routes adatsík API-k és a .NET (C#) SDK használatával.

Az Eseményértesítések átirányítása az Azure Digital Twinsből az alsóbb rétegbeli szolgáltatásokhoz vagy a csatlakoztatott számítási erőforrásokhoz kétlépéses folyamat: végpontok létrehozása, majd eseményútvonalak létrehozása az adatoknak a végpontokra való küldéséhez. Ez a cikk a második lépést ismerteti, amely útvonalak beállításával szabályozza, hogy mely események érkeznek az Azure Digital Twin-végpontokra. A cikk folytatásához már létre kell hoznia végpontokat .

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éseivel. A cikk későbbi részében a következő értékeket használhatja a beállítástól kezdve:

    • Példány neve
    • Erőforráscsoport

    Ezeket a részleteket az Azure Portalon találja a példány beállítása után.

    Screenshot of the Overview page for an Azure Digital Twins instance in the Azure portal. The name and resource group are highlighted.

  • Hozzon létre egy végpontot a Végpontok létrehozása című témakörben található utasítások alapján. Ebben a cikkben létrehoz egy útvonalat, amellyel adatokat küldhet az adott végpontra.

Ezután kövesse az alábbi utasításokat, ha az Azure CLI-t szeretné használni az útmutató követésével.

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

Eseményútvonal létrehozása

A végpont létrehozása után meg kell határoznia egy eseményútvonalat, hogy ténylegesen adatokat küldjön a végpontnak. Ezek az útvonalak lehetővé teszik a fejlesztők számára az eseményfolyamatok továbbítását a teljes rendszerben és az alsóbb rétegbeli szolgáltatásokban. Egyetlen útvonal több értesítés és eseménytípus kijelölését is lehetővé teheti. További információ a végpontok és az eseményútvonalak eseményútvonalairól.

Megjegyzés:

Mielőtt továbblép az útvonal létrehozására, győződjön meg arról, hogy létrehozott legalább egy végpontot az előfeltételekben leírtak szerint.

Ha csak nemrég telepítette a végpontokat, ellenőrizze, hogy befejezték-e az üzembe helyezést, mielőtt megpróbálják használni őket egy új eseményútvonalhoz. 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 ezt a folyamatot szkripteli, érdemes lehet ezt figyelembe vennie úgy, hogy 2–3 perc várakozási idő alatt készíti el a végpontszolgáltatás üzembe helyezését, mielőtt továbblépne az útvonalbeállításra.

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
  • A végpontnak küldött eseményeket meghatározó szűrő
    • Ha le szeretné tiltani az útvonalat, hogy ne legyen eseményküldés, használja a következő szűrőértéket: false
    • Egy adott szűréssel nem rendelkező útvonal engedélyezéséhez használja a következő szűrőértéket: true
    • Bármilyen más típusú szűrővel kapcsolatos részletekért tekintse meg 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 egy ú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 szűrése a szűrő alapján történik.

Az eseményútvonalak az Azure Portalon, az EventRoutes adatsík API-kkal vagy az dt route CLI-parancsokkal hozhatók létre. A szakasz többi része végigvezeti a létrehozási folyamaton.

Eseményútvonal létrehozásához nyissa meg az Azure Digital Twins-példány részletes lapját az Azure Portalon (a példányt a portál keresősávjába való beírásával találhatja 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 a beállítás engedélyezéséhez, és írja be true a Szűrő mezőbe.

Screenshot of creating an event route for your instance in the 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.

Miután engedélyezte a minimális szűrőt true, 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-val
  • Ikertulajdonság-változási értesítések, aktiválva az Azure Digital Twins-példány bármely ikerpéldányának tulajdonságváltozásai miatt
  • Életciklus-események, amelyek ikerpéldányok vagy kapcsolatok létrehozásakor vagy törlésekor aktiválódnak

Az elküldött események típusait egy konkrétabb 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 casingnak meg kell egyeznie az eszköz által küldött telemetriai telemetria burkolatával.

Ha eseményszűrőt szeretne hozzáadni egy eseményútvonal létrehozásakor, 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 a speciális szűrőbeállításokat használva saját egyéni szűrőket írhat.

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.

Screenshot of creating an event route with a basic filter in the Azure portal, highlighting the checkboxes of the events.

Ezzel automatikusan feltölti a szűrő szövegdobozát a kijelölt szűrő szövegével:

Screenshot of creating an event route with a basic filter in the Azure portal, highlighting the autopopulated filter text after selecting the events.

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, kapcsolja be a Speciális szerkesztő kapcsolóját az engedélyezéséhez. Ezután saját eseményszűrőket írhat a Szűrő mezőbe:

Screenshot of creating an event route with an advanced filter in the 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 eseményküldés <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
Source 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>
Subject Az esemény leírása a fenti eseményforrás kontextusában subject = '<subject>' Íme a lehetséges tárgyértékek:

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

Telemetria esetén: A tárgy az összetevő elérési útja (ha a telemetriát ikerösszetevőből bocsátják ki), 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ő értesítési törzsben $body.$metadata.$modelé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
Spec verzió A használt eseményséma verziója specversion = '<version>' A verziónak meg 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és mezőjében található bármely tulajdonságra $body.<property> Az értesítési példákért tekintse meg az eseményértesítéseket . A mező bármely tulajdonságára hivatkozhat a data következő használatával: $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 egy digitális ikerpéldány változásértesítésének egy patch szakaszán belül.

Az alábbi adattípusok támogatottak a fenti adatokra mutató hivatkozások által visszaadott értékekként:

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
Bool $body.poweredOn = true
Null $body.prop != null

Az útvonalszűrők meghatározásakor a következő operátorok támogatottak:

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 meghatározásakor a következő függvények támogatottak:

Function 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ő implementálása vagy frissítése esetén a módosítás néhány percet is igénybe vehet, amíg megjelenik az adatfolyam.

Eseményútvonalak figyelése

Az útválasztási metrikákat, például a darabszámot, a késést és a hibaarányt az Azure Portalon tekintheti meg.

A metrikák Azure Monitorral való megtekintésével és kezelésével kapcsolatos információkért tekintse meg a Metrikák kezelő használatának első lépéseit. Az Azure Digital Twinshez elérhető útválasztási metrikák teljes listájáért tekintse meg az Azure Digital Twins útválasztási metrikáit.

További lépések

További információ a különböző típusú eseményüzenetekről: