Gebeurtenisroutes en -filters maken in Azure Digital Twins

In dit artikel wordt u begeleid bij het maken van gebeurtenisroutes met behulp van Azure Portal, Azure CLI az dt route commands, Event Routes data plane API's en de .NET (C#) SDK.

Het routeren van gebeurtenismeldingen van Azure Digital Twins naar downstreamservices of verbonden rekenresources is een proces in twee stappen: eindpunten maken en vervolgens gebeurtenisroutes maken om gegevens naar deze eindpunten te verzenden. Dit artikel gaat over de tweede stap, het instellen van routes om te bepalen welke gebeurtenissen worden geleverd aan welke Azure Digital Twin-eindpunten worden geleverd. Als u verder wilt gaan met dit artikel, moet er al eindpunten zijn gemaakt.

Vereisten

• U hebt een Azure-account nodig dat gratis kan worden ingesteld

• U hebt een Azure Digital Twins-exemplaar nodig in uw Azure-abonnement. Als u nog geen exemplaar hebt, kunt u er een maken met behulp van de stappen in Een exemplaar en verificatie instellen. Laat de volgende waarden van de installatie handig zijn om verderop in dit artikel te gebruiken:

  • Exemplaarnaam
  • Resourcegroep

  U vindt deze details in Azure Portal nadat u uw exemplaar hebt ingesteld.

  

• Maak een eindpunt met behulp van de instructies in Eindpunten maken. In dit artikel maakt u een route om gegevens naar dat eindpunt te verzenden.

Volg vervolgens de onderstaande instructies als u de Azure CLI wilt gebruiken tijdens het volgen van deze handleiding.

De omgeving voorbereiden op de Azure CLI

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.

  

• Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

  • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

  • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

Een gebeurtenisroute maken

Nadat u een eindpunt hebt gemaakt, moet u een gebeurtenisroute definiëren om gegevens daadwerkelijk naar het eindpunt te verzenden. Met deze routes kunnen ontwikkelaars gebeurtenisstromen, in het hele systeem en naar downstreamservices, verbinden. Met één route kunnen meerdere meldingen en gebeurtenistypen worden geselecteerd. Lees meer over gebeurtenisroutes in Eindpunten en gebeurtenisroutes.

Notitie

Zorg ervoor dat u ten minste één eindpunt hebt gemaakt, zoals beschreven in de vereisten voordat u verdergaat met het maken van een route.

Als u uw eindpunten pas onlangs hebt geïmplementeerd, controleert u of ze zijn geïmplementeerd voordat u ze probeert te gebruiken voor een nieuwe gebeurtenisroute. Als de implementatie van de route mislukt omdat de eindpunten niet gereed zijn, wacht u enkele minuten en probeert u het opnieuw.

Als u deze stroom scriptt, kunt u hiervoor rekening houden door de eindpuntservice binnen 2-3 minuten te laten wachten totdat de implementatie van de eindpuntservice is voltooid voordat u verdergaat met het instellen van de route.

Een routedefinitie kan deze elementen bevatten:

• De routenaam die u wilt gebruiken
• De naam van het eindpunt dat u wilt gebruiken
• Een filter waarmee wordt gedefinieerd welke gebeurtenissen naar het eindpunt worden verzonden
  • Als u de route wilt uitschakelen zodat er geen gebeurtenissen worden verzonden, gebruikt u een filterwaarde van false
  • Als u een route wilt inschakelen die geen specifiek filter heeft, gebruikt u een filterwaarde van true
  • Zie de sectie Filter-gebeurtenissen hieronder voor meer informatie over elk ander type filter

Als er geen routenaam is, worden er geen berichten gerouteerd buiten Azure Digital Twins. Als er een routenaam is en het filter is true, worden alle berichten doorgestuurd naar het eindpunt. Als er een routenaam is en er een ander filter wordt toegevoegd, worden berichten gefilterd op basis van het filter.

Gebeurtenisroutes kunnen worden gemaakt met de Azure-portal, EventRoutes-gegevensvlak-API's of az dt route CLI-opdrachten. In de rest van deze sectie wordt het proces voor het maken beschreven.

Portal

Als u een gebeurtenisroute wilt maken, gaat u naar de detailpagina voor uw Azure Digital Twins-exemplaar in Azure Portal (u kunt het exemplaar vinden door de naam in te voeren in de zoekbalk van de portal).

Selecteer gebeurtenisroutes in het exemplaarmenu. Selecteer vervolgens op de pagina Gebeurtenisroutes die volgt de optie + Een gebeurtenisroute maken.

Kies op de pagina Een gebeurtenisroute maken die wordt geopend minimaal:

• Een naam voor uw route in het veld Naam
• Het eindpunt dat u wilt gebruiken om de route te maken

Als u de route wilt inschakelen, moet u ook een gebeurtenisroutefilter van ten minste truetoevoegen. (Als u de standaardwaarde van false de route verlaat, wordt de route gemaakt, maar er worden geen gebeurtenissen naar deze route verzonden.) U doet dit door de schakeloptie voor de geavanceerde editor in te schakelen om deze in te schakelen en in het filtervak te schrijventrue.

Wanneer u klaar bent, selecteert u de knop Opslaan om uw gebeurtenisroute te maken.

CLI

Routes kunnen worden beheerd met behulp van de az dt route-opdrachten voor de Azure Digital Twins CLI.

Zie de Azure Digital Twins CLI-opdrachtenset voor meer informatie over het gebruik van de CLI en welke opdrachten beschikbaar zijn.

.NET SDK

In deze sectie wordt beschreven hoe u een gebeurtenisroute maakt met behulp van de .NET -SDK (C#).

CreateOrReplaceEventRouteAsync is de SDK-aanroep die wordt gebruikt om een gebeurtenisroute toe te voegen. Hier volgt een voorbeeld van het gebruik:

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

Tip

Alle SDK-functies worden geleverd in synchrone en asynchrone versies.

Voorbeeld-SDK-code voor gebeurtenisroute

In de volgende voorbeeldmethode ziet u hoe u een gebeurtenisroute maakt, weergeeft en verwijdert met de 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}");
    }
}

Gebeurtenissen filteren

Zoals hierboven beschreven, hebben routes een filterveld. Als de filterwaarde op uw route is false, worden er geen gebeurtenissen naar uw eindpunt verzonden.

Nadat u een minimaal filter truehebt ingeschakeld, ontvangen eindpunten verschillende soorten gebeurtenissen van Azure Digital Twins:

• Telemetrie geactiveerd door digitale dubbels met behulp van de Azure Digital Twins-service-API
• Meldingen over wijziging van eigenschappen van dubbels, geactiveerd op eigenschapswijzigingen voor elke tweeling in het Azure Digital Twins-exemplaar
• Levenscyclusgebeurtenissen, geactiveerd wanneer tweelingen of relaties worden gemaakt of verwijderd

U kunt de typen gebeurtenissen beperken die worden verzonden door een specifieker filter te definiëren.

Notitie

Filters zijn hoofdlettergevoelig en moeten overeenkomen met de nettoladingscase. Voor telemetriefilters betekent dit dat de behuizing moet overeenkomen met de behuizing in de telemetrie die door het apparaat wordt verzonden.

Portal

Als u een gebeurtenisfilter wilt toevoegen terwijl u een gebeurtenisroute maakt, gebruikt u de sectie Een gebeurtenisroutefilter toevoegen van de pagina Een gebeurtenisroute maken.

U kunt kiezen uit een aantal algemene filteropties of de geavanceerde filteropties gebruiken om uw eigen aangepaste filters te schrijven.

De basisfilters gebruiken

Als u de basisfilters wilt gebruiken, vouwt u de optie Gebeurtenistypen uit en schakelt u de selectievakjes in die overeenkomen met de gebeurtenissen die u naar uw eindpunt wilt verzenden.

Als u dit doet, wordt het filtertekstvak automatisch ingevuld met de tekst van het filter dat u hebt geselecteerd:

De geavanceerde filters gebruiken

U kunt ook de geavanceerde filteroptie gebruiken om uw eigen aangepaste filters te schrijven.

Als u een gebeurtenisroute met geavanceerde filteropties wilt maken, schakelt u de schakeloptie voor de geavanceerde editor in om deze in te schakelen. U kunt vervolgens uw eigen gebeurtenisfilters schrijven in het vak Filter :

API

U kunt de gegevensvlak-API's voor gebeurtenisroutes gebruiken om aangepaste filters te schrijven. Als u een filter wilt toevoegen, kunt u een PUT-aanvraag gebruiken voor https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 de volgende hoofdtekst:

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

Ondersteunde routefilters

Dit zijn de ondersteunde routefilters.

Filternaam	Beschrijving	Tekstschema filteren	Ondersteunde waarden
Waar/niet waar	Hiermee kunt u een route zonder filteren maken of een route uitschakelen, zodat er geen gebeurtenissen worden verzonden	<true/false>	true = route is ingeschakeld zonder filteren false = route is uitgeschakeld
Type	Het type gebeurtenis dat door uw digital twin-exemplaar stroomt	type = '<event-type>'	Dit zijn de mogelijke waarden voor gebeurtenistypen: 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
Bron	Naam van Azure Digital Twins-exemplaar	source = '<host-name>'	Dit zijn de mogelijke hostnaamwaarden: Voor meldingen: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net Voor telemetrie: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Onderwerp	Een beschrijving van de gebeurtenis in de context van de bovenstaande gebeurtenisbron	subject = '<subject>'	Dit zijn de mogelijke onderwerpwaarden: Voor meldingen: het onderwerp is <twin-ID> of een URI-indeling voor onderwerpen, die uniek worden geïdentificeerd door meerdere onderdelen of id's: <twin-ID>/relationships/<relationship-ID> Voor telemetrie: Het onderwerp is het onderdeelpad (als de telemetrie wordt verzonden vanuit een dubbelonderdeel), zoals comp1.comp2. Als de telemetrie niet wordt verzonden vanuit een onderdeel, is het onderwerpveld leeg.
Gegevensschema	DTDL-model-id	dataschema = '<model-dtmi-ID>'	Voor telemetrie: Het gegevensschema is de model-id van de tweeling of het onderdeel dat de telemetrie verzendt. Bijvoorbeeld dtmi:example:com:floor4;2 Voor meldingen (maken/verwijderen): gegevensschema kan worden geopend in de hoofdtekst van de melding op $body.$metadata.$model. Voor meldingen (update): Gegevensschema kan worden geopend in de hoofdtekst van de melding op $body.modelId
Inhoudstype	Inhoudstype van gegevenswaarde	datacontenttype = '<content-type>'	Het inhoudstype is application/json
Specificatieversie	De versie van het gebeurtenisschema dat u gebruikt	specversion = '<version>'	De versie moet zijn 1.0. Deze waarde geeft het Schema van CloudEvents versie 1.0 aan
Hoofdtekst van melding	Verwijzen naar een eigenschap in het data veld van een melding	$body.<property>	Zie Gebeurtenismeldingen voor voorbeelden van meldingen. Naar elke eigenschap in het data veld kan worden verwezen met behulp van $body

Notitie

Azure Digital Twins biedt momenteel geen ondersteuning voor het filteren van gebeurtenissen op basis van velden in een matrix. Dit omvat filteren op eigenschappen in een patch sectie van een melding voor wijziging van digitale dubbels.

De volgende gegevenstypen worden ondersteund als waarden die worden geretourneerd door verwijzingen naar de bovenstaande gegevens:

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

De volgende operators worden ondersteund bij het definiëren van routefilters:

Gezin	Operators	Opmerking
Logisch	AND, OR, ( )	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Vergelijking	<, <=, >=, >=, =, !=	$body.temperature <= 5.5

De volgende functies worden ondersteund bij het definiëren van routefilters:

Functie	Description	Voorbeeld
STARTS_WITH(x,y)	Retourneert waar als de waarde x begint met de tekenreeks y.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y)	Retourneert waar als de waarde x eindigt op de tekenreeks y.	ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y)	Retourneert waar als de waarde x de tekenreeks ybevat.	CONTAINS(subject, '<twin-ID>')

Wanneer u een filter implementeert of bijwerkt, kan het enkele minuten duren voordat de wijziging wordt doorgevoerd in de gegevenspijplijn.

Gebeurtenisroutes bewaken

Metrische gegevens voor routering, zoals count, latency en failure rate, kunnen worden weergegeven in Azure Portal.

Zie Aan de slag met Metrics Explorer voor informatie over het weergeven en beheren van metrische gegevens met Azure Monitor. Zie de metrische gegevens voor routering van Azure Digital Twins voor een volledige lijst met metrische routeringsgegevens die beschikbaar zijn voor Azure Digital Twins.

Volgende stappen

Lees meer over de verschillende typen gebeurtenisberichten die u kunt ontvangen:

• Gebeurtenismeldingen