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

Cikk
01/04/2024

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

Használja a Bash-környezetet az Azure Cloud Shellben. További információ: A Bash rövid útmutatója az Azure Cloud Shellben.
Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszert használ, fontolja meg az Azure CLI Docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.
- Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával. A hitelesítési folyamat befejezéséhez kövesse a terminálon megjelenő lépéseket. További bejelentkezési lehetőségekért lásd : Bejelentkezés az Azure CLI-vel.
- Amikor a rendszer kéri, először telepítse az Azure CLI-bővítményt. További információ a bővítményekről: Bővítmények használata az Azure CLI-vel.
- Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.

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.

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

Ez a szakasz bemutatja, hogyan hozhat létre eseményútvonalat a .NET (C#) SDK használatával.

CreateOrReplaceEventRouteAsync az eseményútvonal hozzáadásához használt SDK-hívás. Íme egy példa a használatára:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

Tipp.

Minden SDK-függvény szinkron és aszinkron verzióban jön létre.

Eseményútvonal-minta SDK-kód

Az alábbi mintametódus bemutatja, hogyan hozhat létre, listázhat és törölhet eseményútvonalat a C# SDK-val:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

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.

Portal
API

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.

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

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:

Az Event Routes adatsík API-kkal egyéni szűrőket írhat. Szűrő hozzáadásához put kérést https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 használhat a következő törzstel:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

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 `y`kezdő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 `y`vé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:

Eseményértesítések

Megosztás a következőn keresztül:

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

Előfeltételek

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

Eseményútvonal létrehozása

Eseményútvonal-minta SDK-kód

Események szűrése

Az alapszintű szűrők használata

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

Támogatott útvonalszűrők

Eseményútvonalak figyelése

További lépések

További források