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í webu Azure Portal, Azure CLI az dt route příkazů, rozhraní API roviny dat tras událostí a sady .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

• Budete potřebovat účet Azure, který si můžete zdarma nastavit.

• Ve svém předplatném Azure budete potřebovat 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 postupujte podle následujících pokynů, pokud chcete použít Azure CLI a postupujte podle této příručky.

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 Rychlý start pro Bash v Azure Cloud Shellu.

  

• 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 Přihlášení 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 Využití rozšíření v Azure CLI.

  • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte 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í. Přečtěte si další informace o trasách událostí v koncových bodech a trasách událostí.

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 to zohlednit tak, že sestavíte 2 až 3 minuty čekání, než služba koncového bodu dokončí nasazení, než přejdete na nastavení směrování.

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 Události filtru níže.

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 je název trasy a přidá se jiný filtr, zprávy se budou filtrovat podle filtru.

Trasy událostí je možné vytvořit pomocí webu Azure Portal, rozhraní API roviny dat EventRoutes nebo příkazu az dt route CLI. Zbývající část této části vás provede procesem vytváření.

Azure Portal

Pokud chcete vytvořit trasu události, přejděte na stránku podrobností vaší 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. (Pokud ponecháte výchozí hodnotu false , vytvoří se trasa, ale do ní nebudou odeslány žádné události.) Uděláte to tak, že přepínač pro rozšířený editor zapnete a zapíšete true do pole Filtr .

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

Rozhraní příkazového řádku

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

Tip

Všechny funkce sady SDK jsou synchronní a asynchronní verze.

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 C# 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 je popsáno výše, 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 truefiltru koncových bodů z Azure Digital Twins obdrží různé druhy událostí:

• Telemetrie aktivovaná digitálními dvojčaty pomocí rozhraní API služby Azure Digital Twins
• Oznámení o změně vlastností dvojčete, aktivované při změnách vlastností pro jakékoli dvojče v instanci Služby 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 případu datové části. U filtrů telemetrie to znamená, že velikost casingu se musí shodovat s velikostí v telemetrii odesílanou zařízením.

Azure Portal

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 trasuudá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 vyplní textové pole filtru textem filtru, který jste vybrali:

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

K zápisu vlastních filtrů můžete použít také možnost rozšířeného filtru.

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 roviny dat Trasy událostí . Pokud chcete přidat filtr, můžete použít požadavek PUT s https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 následujícím textem:

{
    "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í 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
Source	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 výše uvedeného zdroje událostí	subject = '<subject>'	Tady 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> Telemetrie: Předmět je cesta ke komponentě (pokud se telemetrie vygeneruje z komponenty dvojčete), například comp1.comp2. Pokud se telemetrie nevygeneruje ze 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): Schéma dat je možné získat přístup v textu oznámení na adrese . $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í	Odkazování na data libovolnou vlastnost v poli oznámení	$body.<property>	Příkladyoznámeních 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. To 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 výše uvedená data:

Datový typ	Příklad
String	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
Celé číslo	$body.errorCode > 200
Hodnota s dvojitou přesností	$body.temperature <= 5.5
Bool	$body.poweredOn = true
Null	$body.prop != null

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

Rodina	Operátory	Příklad
Logický	AND, OR, ( )	(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:

Function	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 Začínáme s průzkumníkem metrik. Úplný seznam metrik směrování dostupných pro Azure Digital Twins najdete v tématu Metriky směrování služby Azure Digital Twins.

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í