Vytváření tras a filtrů událostí ve službě Azure Digital Twins

Tento článek vás provede procesem vytváření tras událostí pomocí Azure portalu, příkazů Azure CLI az dt route, rozhraní API pro datovou rovinu tras událostí a sady SDK .NET (C#).

Směrování oznámení událostí z Azure Digital Twins do podřízených služeb nebo připojených výpočetních prostředků je dvoustupňový proces: vytvoření koncových bodů a následné vytvoření tras událostí pro odesílání dat do těchto koncových bodů. Tento článek popisuje druhý krok, který nastavuje trasy pro řízení, které události se doručují do koncových bodů služby Azure Digital Twin. Pokud chcete pokračovat v tomto článku, měli byste mít už vytvořené koncové body .

Požadavky

• Potřebujete účet Azure, který si můžete zdarma nastavit.

• Ve svém předplatném Azure potřebujete instanci Azure Digital Twins. Pokud ještě instanci nemáte, můžete ji vytvořit pomocí kroků v části Nastavení instance a ověřování. Můžete použít následující hodnoty z nastavení, které můžete použít dále v tomto článku:

  • Název instance
  • Skupina prostředků

  Tyto podrobnosti najdete na webu Azure Portal po nastavení instance.

  

• Vytvořte koncový bod podle pokynů v části Vytvoření koncových bodů. V tomto článku vytvoříte trasu pro odesílání dat do tohoto koncového bodu.

V dalším kroku proveďte následující pokyny, pokud máte v úmyslu používat Azure CLI a postupujte podle tohoto průvodce.

Příprava prostředí pro rozhraní příkazového řádku Azure

• Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Začínáme s Azure Cloud Shellem.

  

• Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

  • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login . Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Ověřování v Azure pomocí Azure CLI.

  • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Použití a správa rozšíření pomocí Azure CLI.

  • Spuštěním příkazu az version vyhledejte nainstalovanou verzi a závislé knihovny. Pokud chcete upgradovat na nejnovější verzi, spusťte příkaz az upgrade.

Vytvoření trasy události

Po vytvoření koncového bodu budete muset definovat trasu události , která skutečně odesílá data do koncového bodu. Tyto trasy umožňují vývojářům připojit tok událostí v celém systému a do podřízených služeb. Jedna trasa může povolit výběr více oznámení a typů událostí. Další informace o trasách událostí najdete v tématu Směrování událostí Azure Digital Twins.

Poznámka:

Než přejdete na vytvoření trasy, ujistěte se, že jste vytvořili aspoň jeden koncový bod, jak je popsáno v části Požadavky .

Pokud jste koncové body nasadili teprve nedávno, ověřte, že se dokončily, a teprve potom je zkuste použít pro novou trasu událostí. Pokud nasazení trasy selže, protože koncové body nejsou připravené, počkejte několik minut a zkuste to znovu.

Pokud tento tok skriptujete, můžete chtít zohlednit nasazení vytvořením 2 až 3 minuty čekání, než služba koncového bodu dokončí nasazení, než přejdete na nastavení trasy.

Definice trasy může obsahovat tyto prvky:

• Název trasy, kterou chcete použít
• Název koncového bodu, který chcete použít
• Filtr, který definuje, které události se posílají do koncového bodu
  • Pokud chcete trasu zakázat, aby se neposílaly žádné události, použijte hodnotu filtru false
  • Pokud chcete povolit trasu, která nemá žádné konkrétní filtrování, použijte hodnotu filtru true
  • Podrobnosti o jakémkoli jiném typu filtru najdete v části Filtrování událostí .

Pokud název trasy neexistuje, žádné zprávy se nesměrují mimo Službu Azure Digital Twins. Pokud existuje název trasy a filtr je true, všechny zprávy se směrují do koncového bodu. Pokud existuje název trasy a přidá se jiný filtr, zprávy se filtrují podle filtru.

Trasy událostí je možné vytvořit pomocí Azure portálu, API datové roviny tras událostí nebo CLI příkazů az dt route. Zbývající část této části vás provede procesem vytváření.

Portál

Pokud chcete vytvořit trasu události, přejděte na stránku podrobností instance služby Azure Digital Twins na webu Azure Portal. Instanci najdete zadáním jejího názvu do panelu hledání na portálu.

V nabídce instance vyberte Trasy událostí. Potom na následující stránce Trasy událostí vyberte + Vytvořit trasu události.

Na stránce Vytvořit trasu události , která se otevře, zvolte minimálně:

• Název trasy v poli Název
• Koncový bod, který chcete použít k vytvoření trasy

Chcete-li povolit trasu, musíte také přidat filtr tras událostí alespoň true. (Ponechání výchozí hodnoty false vytváří trasu, ale neodesílají se na ni žádné události.) Chcete-li to provést, přepněte přepínač pro Rozšířený editor a zapište true do pole Filtr.

Až budete hotovi, vyberte tlačítko Uložit a vytvořte trasu události.

CLI

Trasy je možné spravovat pomocí příkazů az dt route pro Azure Digital Twins CLI.

Další informace o používání rozhraní příkazového řádku a dostupných příkazech najdete v sadě příkazů Azure Digital Twins CLI.

.NET SDK

Tato část ukazuje, jak vytvořit trasu událostí pomocí sady .NET (C#) SDK.

CreateOrReplaceEventRouteAsync je volání sady SDK, které se používá k přidání trasy události. Tady je příklad použití:

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

Návod

Všechny funkce sady SDK přicházejí ve verzích synchronních a asynchronních.

Ukázkový kód sady SDK pro trasu událostí

Následující ukázková metoda ukazuje, jak vytvořit, vypsat a odstranit trasu události pomocí sady .NET SDK:

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}");
    }
}

Události filtru

Jak jsme popsali dříve, trasy mají pole filtru. Pokud je falsehodnota filtru ve vaší trase , do koncového bodu se neposílají žádné události.

Po povolení minimálního filtru true budou koncové body z Azure Digital Twins přijímat různé druhy událostí:

• Telemetrie generovaná digitálními dvojčaty pomocí rozhraní API služby Azure Digital Twins
• Notifikace o změně vlastností dvojčete, spuštěné při změnách vlastností pro jakékoli dvojče v instanci Azure Digital Twins
• Události životního cyklu, aktivované při vytváření nebo odstranění dvojčat nebo relací

Typy událostí, které se odesílají, můžete omezit definováním konkrétnějšího filtru.

Poznámka:

Filtry rozlišují malá a velká písmena a musí odpovídat velikosti písmen v datové části. cs-CZ: U filtrů telemetrie se musí pouzdro filtru shodovat s pouzdrem v telemetrii odesílané zařízením.

Portál

Pokud chcete přidat filtr událostí při vytváření trasy události, použijte oddíl Přidat filtr tras událostí na stránce Vytvořit trasu události .

Můžete si buď vybrat některé základní běžné možnosti filtru, nebo použít pokročilé možnosti filtru k zápisu vlastních filtrů.

Použití základních filtrů

Pokud chcete použít základní filtry, rozbalte možnost Typy událostí a zaškrtněte políčka odpovídající událostem, které chcete odeslat do koncového bodu.

Tím se automaticky naplní textové pole filtru textem filtru, který jste vybrali:

Použití rozšířených filtrů

Rovněž můžete použít možnost pokročilého filtru k vytvoření vlastních filtrů.

Pokud chcete vytvořit trasu událostí s rozšířenými možnostmi filtru, přepněte přepínač rozšířeného editoru a povolte ho. Potom můžete do pole Filtr napsat vlastní filtry událostí:

Rozhraní api

K zápisu vlastních filtrů můžete použít rozhraní API datové roviny tras událostí. Pokud chcete přidat filtr, můžete použít požadavek PUT na https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 s následujícím tělem:

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

Podporované filtry tras

Tady jsou podporované filtry tras.

Název filtru	Popis	Filtrování textového schématu	Podporované hodnoty
Pravda / Nepravda	Umožňuje vytvořit trasu bez filtrování nebo zakázání trasy, aby se neposílaly žádné události.	<true/false>	true = trasa je povolená bez filtrování. false = trasa je zakázaná.
Typ	Typ události procházející vaší instancí digitálního dvojčete	type = '<event-type>'	Tady jsou možné hodnoty typu události: 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
Zdroj	Název instance Služby Azure Digital Twins	source = '<host-name>'	Tady jsou možné hodnoty názvu hostitele: Oznámení: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net Telemetrie: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Předmět	Popis události v kontextu zdroje událostí	subject = '<subject>'	Zde jsou možné hodnoty předmětu: Pro oznámení: Předmět je <twin-ID> nebo formát identifikátoru URI pro předměty, které jsou jednoznačně identifikovány více částmi nebo ID: <twin-ID>/relationships/<relationship-ID> Pro telemetrii: Předmět je cesta ke komponentě (pokud je telemetrie odesílána z komponenty dvojčete), například comp1.comp2. Pokud telemetrie není vysílena z komponenty, pole předmětu je prázdné.
Datové schéma	ID modelu DTDL	dataschema = '<model-dtmi-ID>'	Telemetrie: Schéma dat je ID modelu dvojčete nebo komponenty, která generuje telemetrii. Například dtmi:example:com:floor4;2 Pro oznámení (vytvoření nebo odstranění): K datovému schématu lze přistupovat v textu oznámení na adrese $body.$metadata.$model. Pro oznámení (aktualizace): Ke schématu dat lze přistupovat v textu oznámení na $body.modelId.
Typ obsahu	Typ obsahu datové hodnoty	datacontenttype = '<content-type>'	Typ obsahu je application/json
Specifikace verze	Verze schématu událostí, které používáte	specversion = '<version>'	Verze musí být 1.0. Tato hodnota označuje schéma CloudEvents verze 1.0.
Text oznámení	Odkazujte na libovolnou vlastnost v poli data oznámení.	$body.<property>	Podívejte se na Oznámení událostí pro příklady oznámení. Na libovolnou data vlastnost v poli lze odkazovat pomocí $body

Poznámka:

Azure Digital Twins v současné době nepodporuje filtrování událostí na základě polí v rámci pole. Toto omezení zahrnuje filtrování vlastností v patch části oznámení o změně digitálního dvojčete.

Následující datové typy jsou podporovány jako hodnoty vrácené odkazy na předchozí data:

Datový typ	Příklad
Řetězec	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
Celé číslo	$body.errorCode > 200
Dvojitá	$body.temperature <= 5.5
Booleovská hodnota	$body.poweredOn = true
Nula	$body.prop != null

Při definování filtrů tras se podporují následující operátory:

Rodina	Operátory	Příklad
Logický	A, NEBO, ( )	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Porovnání	<, <=, >>, =, =, !=	$body.temperature <= 5.5

Při definování filtrů tras se podporují následující funkce:

Funkce	Popis	Příklad
STARTS_WITH(x;y)	Vrátí hodnotu true, pokud hodnota x začíná řetězcem y.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x;y)	Vrátí hodnotu true, pokud hodnota x končí řetězcem y.	ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x;y)	Vrátí hodnotu true, pokud hodnota x obsahuje řetězec y.	CONTAINS(subject, '<twin-ID>')

Když implementujete nebo aktualizujete filtr, může trvat několik minut, než se změna projeví v datovém kanálu.

Monitorování tras událostí

Metriky směrování, jako je počet, latence a míra selhání, se dají zobrazit na webu Azure Portal.

Informace o zobrazení a správě metrik pomocí služby Azure Monitor najdete v tématu Analýza metrik pomocí Průzkumníka metrik služby Azure Monitor. Úplný seznam metrik směrování dostupných pro Azure Digital Twins najdete v tématu Metriky směrování.

Další kroky

Přečtěte si o různých typech zpráv událostí, které můžete přijímat:

• Oznámení událostí