Skapa händelsevägar och filter i Azure Digital Twins

Den här artikeln beskriver hur du skapar händelsevägar med hjälp av Azure-portalen, Azure CLI az dt route-kommandon, Event Routes dataplan-API:er och .NET (C#) SDK.

Routning av händelsemeddelanden från Azure Digital Twins till underordnade tjänster eller anslutna beräkningsresurser är en tvåstegsprocess: skapa slutpunkter och skapa sedan händelsevägar för att skicka data till dessa slutpunkter. Den här artikeln beskriver det andra steget och konfigurerar vägar för att styra vilka händelser som levereras till vilka Azure Digital Twin-slutpunkter. Om du vill fortsätta med den här artikeln bör du redan ha skapat slutpunkter .

Förutsättningar

• Du behöver ett Azure-konto som kan konfigureras kostnadsfritt

• Du behöver en Azure Digital Twins-instans i din Azure-prenumeration. Om du inte redan har en instans kan du skapa en med hjälp av stegen i Konfigurera en instans och autentisering. Ha följande värden från installationen till hands för senare användning i den här artikeln:

  • Instansnamn
  • Resursgrupp

  Du hittar den här informationen i Azure-portalen när du har konfigurerat din instans.

  

• Skapa en slutpunkt med hjälp av anvisningarna i Skapa slutpunkter. I den här artikeln skapar du en väg för att skicka data till slutpunkten.

Följ sedan anvisningarna nedan om du tänker använda Azure CLI när du följer den här guiden.

Förbereda din miljö för Azure CLI

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

  • När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.

  • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Skapa en händelseväg

När du har skapat en slutpunkt måste du definiera en händelseväg för att faktiskt skicka data till slutpunkten. Med de här vägarna kan utvecklare koppla upp händelseflödet, i hela systemet och till underordnade tjänster. En enda väg kan tillåta att flera meddelanden och händelsetyper väljs. Läs mer om händelsevägar i Slutpunkter och händelsevägar.

Kommentar

Kontrollera att du har skapat minst en slutpunkt enligt beskrivningen i Förutsättningar innan du går vidare till att skapa en väg.

Om du nyligen har distribuerat dina slutpunkter kontrollerar du att de har distribuerats klart innan du försöker använda dem för en ny händelseväg. Om routningsdistributionen misslyckas på grund av att slutpunkterna inte är klara väntar du några minuter och försöker igen.

Om du skriptar det här flödet kanske du vill ta hänsyn till detta genom att skapa inom 2–3 minuters väntetid för att slutpunktstjänsten ska slutföra distributionen innan du går vidare till routningskonfigurationen.

En vägdefinition kan innehålla följande element:

• Det routningsnamn som du vill använda
• Namnet på den slutpunkt som du vill använda
• Ett filter som definierar vilka händelser som skickas till slutpunkten
  • Om du vill inaktivera vägen så att inga händelser skickas använder du ett filtervärde på false
  • Om du vill aktivera en väg som inte har någon specifik filtrering använder du ett filtervärde på true
  • Mer information om andra typer av filter finns i avsnittet Filterhändelser nedan

Om det inte finns något vägnamn dirigeras inga meddelanden utanför Azure Digital Twins. Om det finns ett vägnamn och filtret är truedirigeras alla meddelanden till slutpunkten. Om det finns ett vägnamn och ett annat filter läggs till filtreras meddelanden baserat på filtret.

Händelsevägar kan skapas med Azure-portalen, EventRoutes-API:er för dataplan eller az dt route CLI-kommandon. Resten av det här avsnittet går igenom skapandeprocessen.

Portal

Om du vill skapa en händelseväg går du till informationssidan för din Azure Digital Twins-instans i Azure-portalen (du hittar instansen genom att ange dess namn i portalens sökfält).

På instansmenyn väljer du Händelsevägar. På sidan Händelsevägar som följer väljer du sedan + Skapa en händelseväg.

På sidan Skapa en händelseväg som öppnas väljer du minst:

• Ett namn på din väg i fältet Namn
• Slutpunkten som du vill använda för att skapa vägen

För att vägen ska vara aktiverad måste du också lägga till ett händelsevägsfilter på minst true. (Om du lämnar standardvärdet false för skapas vägen, men inga händelser skickas till den.) Det gör du genom att växla växeln för avancerad redigerare för att aktivera den och skriva true i rutan Filter .

När du är klar väljer du knappen Spara för att skapa händelsevägen.

CLI

Vägar kan hanteras med hjälp av az dt route-kommandona för Azure Digital Twins CLI.

Mer information om hur du använder CLI och vilka kommandon som är tillgängliga finns i Azure Digital Twins CLI-kommandouppsättning.

.NET SDK

Det här avsnittet visar hur du skapar en händelseväg med hjälp av .NET (C#) SDK.

CreateOrReplaceEventRouteAsync är det SDK-anrop som används för att lägga till en händelseväg. Här är ett exempel på dess användning:

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

Dricks

Alla SDK-funktioner finns i synkrona och asynkrona versioner.

SDK-kod för exempel på händelseväg

Följande exempelmetod visar hur du skapar, listar och tar bort en händelseväg med 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}");
    }
}

Filtrera händelser

Som beskrivs ovan har vägar ett filterfält. Om filtervärdet på din väg är falseskickas inga händelser till slutpunkten.

När du har aktiverat ett minimalt filter av truefår slutpunkter olika typer av händelser från Azure Digital Twins:

• Telemetri som utlöses av digitala tvillingar med hjälp av Azure Digital Twins-tjänst-API:et
• Meddelanden om ändring av tvillingegenskap, utlösta på egenskapsändringar för alla tvillingar i Azure Digital Twins-instansen
• Livscykelhändelser som utlöses när tvillingar eller relationer skapas eller tas bort

Du kan begränsa vilka typer av händelser som skickas genom att definiera ett mer specifikt filter.

Kommentar

Filter är skiftlägeskänsliga och måste matcha nyttolastfallet. För telemetrifilter innebär det att höljet måste matcha höljet i telemetrin som skickas av enheten.

Portal

Om du vill lägga till ett händelsefilter när du skapar en händelseväg använder du avsnittet Lägg till ett händelsevägsfilter på sidan Skapa en händelseväg .

Du kan antingen välja bland några grundläggande vanliga filteralternativ eller använda avancerade filteralternativ för att skriva egna anpassade filter.

Använda de grundläggande filtren

Om du vill använda de grundläggande filtren expanderar du alternativet Händelsetyper och markerar kryssrutorna som motsvarar de händelser som du vill skicka till slutpunkten.

Om du gör det fylls filtertextrutan automatiskt i med texten i det filter som du har valt:

Använda de avancerade filtren

Du kan också använda alternativet avancerat filter för att skriva egna anpassade filter.

Om du vill skapa en händelseväg med avancerade filteralternativ växlar du växeln för avancerad redigerare för att aktivera den. Du kan sedan skriva egna händelsefilter i rutan Filter :

API

Du kan använda API:erna för händelsevägar för dataplanet för att skriva anpassade filter. Om du vill lägga till ett filter kan du använda en PUT-begäran till https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 med följande brödtext:

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

Vägfilter som stöds

Här är de vägfilter som stöds.

Filternamn	beskrivning	Filtrera textschema	Värden som stöds
Sant/falskt	Tillåter att du skapar en väg utan filtrering eller inaktiverar en väg så att inga händelser skickas	<true/false>	true = vägen är aktiverad utan filtrering false = vägen är inaktiverad
Typ	Typen av händelse som flödar genom din digitala tvillinginstans	type = '<event-type>'	Här är de möjliga händelsetypsvärdena: 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
Källa	Namnet på Azure Digital Twins-instansen	source = '<host-name>'	Här är de möjliga värdnamnsvärdena: För meddelanden: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net För telemetri: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Subject	En beskrivning av händelsen i kontexten för händelsekällan ovan	subject = '<subject>'	Här är de möjliga ämnesvärdena: För meddelanden: Ämnet är <twin-ID> eller ett URI-format för ämnen som unikt identifieras av flera delar eller ID:n: <twin-ID>/relationships/<relationship-ID> För telemetri: Ämnet är komponentsökvägen (om telemetrin genereras från en tvillingkomponent), till exempel comp1.comp2. Om telemetrin inte genereras från en komponent är ämnesfältet tomt.
Dataschema	DTDL-modell-ID	dataschema = '<model-dtmi-ID>'	För telemetri: Dataschemat är modell-ID för tvillingen eller komponenten som genererar telemetrin. Till exempel: dtmi:example:com:floor4;2 För meddelanden (skapa/ta bort): Dataschema kan nås i meddelandetexten på $body.$metadata.$model. För meddelanden (uppdatering): Dataschema kan nås i meddelandetexten på $body.modelId
Content type	Innehållstyp för datavärde	datacontenttype = '<content-type>'	Innehållstypen är application/json
Specifikationsversion	Den version av händelseschemat som du använder	specversion = '<version>'	Versionen måste vara 1.0. Det här värdet anger CloudEvents schemaversion 1.0
Meddelandetext	Referera till en egenskap i fältet data för ett meddelande	$body.<property>	Se Händelsemeddelanden för exempel på meddelanden. Alla egenskaper i fältet data kan refereras med hjälp av $body

Kommentar

Azure Digital Twins stöder för närvarande inte filtreringshändelser baserat på fält i en matris. Detta inkluderar filtrering av egenskaper i ett patch avsnitt i ett meddelande om ändring av digital tvilling.

Följande datatyper stöds som värden som returneras av referenser till ovanstående data:

Datatyp	Exempel
String	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
Integer	$body.errorCode > 200
Dubbel	$body.temperature <= 5.5
Bool	$body.poweredOn = true
Null	$body.prop != null

Följande operatorer stöds när du definierar vägfilter:

Familj	Operatorer	Exempel
Logiskt	AND, OR, ( )	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Jämförelse	<, <=, >, >=, =, !=	$body.temperature <= 5.5

Följande funktioner stöds när du definierar vägfilter:

Function	beskrivning	Exempel
STARTS_WITH(x,y)	Returnerar true om värdet x börjar med strängen y.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y)	Returnerar true om värdet x slutar med strängen y.	ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y)	Returnerar true om värdet x innehåller strängen y.	CONTAINS(subject, '<twin-ID>')

När du implementerar eller uppdaterar ett filter kan det ta några minuter innan ändringen återspeglas i datapipelinen.

Övervaka händelsevägar

Routningsmått som antal, svarstid och felfrekvens kan visas i Azure-portalen.

Information om hur du visar och hanterar mått med Azure Monitor finns i Komma igång med Metrics Explorer. En fullständig lista över tillgängliga routningsmått för Azure Digital Twins finns i Routningsmått för Azure Digital Twins.

Nästa steg

Läs om de olika typerna av händelsemeddelanden som du kan ta emot:

• Händelsemeddelanden