Creare route e filtri di eventi in Gemelli digitali di Azure

Articolo
10/16/2024

Questo articolo illustra il processo di creazione di route eventi tramite il portale di Azure, i comandi az dt route dell'interfaccia della riga di comando di Azure, le API del piano dati Route eventi e .NET (C#) SDK.

Il routing di notifiche degli eventi da Gemelli digitali di Azure ai servizi downstream o alle risorse di calcolo connesse è un processo in due passaggi: creare endpoint, quindi creare route eventi per inviare dati a tali endpoint. Questo articolo illustra il secondo passaggio, configurando le route per controllare quali eventi vengono recapitati agli endpoint di Gemelli digitali di Azure. Per procedere con questo articolo, è necessario avere endpoint già creati.

Prerequisiti

È necessario un account Azure, che può essere configurato gratuitamente
È necessaria un'istanza di Gemelli digitali di Azure nella sottoscrizione di Azure. Se non si dispone già di un'istanza, è possibile crearne una seguendo la procedura descritta in Configurare un'istanza e l'autenticazione. Disporre a portata di mano dei seguenti valori di configurazione da utilizzare più avanti in questo articolo:
- Nome istanza
- Gruppo di risorse
Questi dettagli sono disponibili nel portale di Azure dopo aver configurato l'istanza.
Creare un endpoint usando le istruzioni riportate in Creare endpoint. In questo articolo si creerà una route per inviare dati a tale endpoint.

Quindi seguire le istruzioni riportate di seguito se si intende usare l'interfaccia della riga di comando di Azure seguendo questa guida.

Preparare l'ambiente per l'interfaccia della riga di comando di Azure

Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.
Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
- Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.
- Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.
- Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Creare una route eventi

Dopo aver creato un endpoint, è necessario definire una route eventi per inviare effettivamente dati all'endpoint. Queste route consentono agli sviluppatori di collegare il flusso di eventi, attraverso il sistema e fino ai servizi downstream. Una singola route può consentire la selezione di più notifiche e tipi di evento. Altre informazioni sulle route eventi in Endpoint e route eventi.

Nota

Assicurarsi di aver creato almeno un endpoint come descritto in Prerequisiti prima di passare alla creazione di una route.

Se gli endpoint sono stati distribuiti di recente, verificare che siano stati terminata la distribuzione prima di tentare di usarli per una nuova route eventi. Se la distribuzione della route non riesce perché gli endpoint non sono pronti, attendere alcuni minuti e riprovare.

Se si esegue lo script di questo flusso, è possibile tenere conto di questo aspetto creando in 2-3 minuti di tempo di attesa per il completamento della distribuzione del servizio endpoint prima di passare alla configurazione della route.

Una definizione di route può contenere questi elementi:

Nome della route da usare
Nome dell'endpoint da usare
Filtro che definisce gli eventi inviati all'endpoint
- Per disabilitare la route in modo che non vengano inviati eventi, usare un valore di filtro false
- Per abilitare una route senza filtri specifici, usare un valore di filtro true
- Per informazioni dettagliate su qualsiasi altro tipo di filtro, vedere la sezione Filtrare gli eventi di seguito

Se non è presente alcun nome di route, non viene instradato alcun messaggio all'esterno di Gemelli digitali di Azure. Se è presente un nome di route e il filtro è true, tutti i messaggi vengono indirizzati all'endpoint. Se è presente un nome di route e viene aggiunto un filtro differente, i messaggi verranno filtrati in base al filtro.

È possibile creare route eventi con il portale di Azure, le API del piano dati EventRoutes o i comandi dell'interfaccia della riga di comando di az dt route. La parte restante di questa sezione illustra il processo di creazione.

Per creare una route eventi, passare alla pagina dei dettagli per l'istanza di Gemelli digitali di Azure nel portale di Azure (è possibile trovare l'istanza immettendone il nome nella barra di ricerca del portale).

Nel menu dell'istanza selezionare Route eventi. Successivamente, nella paginaRoute eventi che segue selezionare + Crea una route eventi.

Nella pagina Crea una route eventi visualizzata scegliere almeno:

Nome della route nel campo Nome
L’endpoint da usare per creare la route

Affinché la route sia abilitata, è anche necessario aggiungere un filtro di route eventi di almeno true. (se si lascia il valore predefinito di false verrà creata la route, ma non verrà inviato alcun evento). A tale scopo, attivare o disattivare l'opzione per l'Editor avanzato per abilitarla e scrivere true nella casella Filtro.

Al termine, selezionare il pulsante Salva per creare la route eventi.

Questa sezione illustra come creare una route eventi usando .NET (C#) SDK.

CreateOrReplaceEventRouteAsync è la chiamata SDK usata per aggiungere una route eventi. Di seguito è riportato un esempio di utilizzo:

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

Suggerimento

Tutte le funzioni SDK sono disponibili in versioni sincrone e asincrone.

Codice DELL'SDK di esempio di route eventi

Il metodo di esempio seguente illustra come creare, elencare ed eliminare una route eventi con 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}");
    }
}

Filtrare gli eventi

Come descritto in precedenza, le route hanno un campo di filtro. Se il valore del filtro nella route è false, nessun evento verrà inviato all'endpoint.

Dopo aver abilitato un filtro minimo di true, gli endpoint riceveranno differenti tipi di eventi da Gemelli digitali di Azure:

Telemetria generata da gemelli digitali con l'API del servizio Gemelli digitali di Azure
Notifiche di modifica delle proprietà del dispositivo gemello, attivate in caso di modifiche alle proprietà per qualsiasi gemello nell'istanza di Gemelli digitali di Azure
Eventi del ciclo di vita, generati quando vengono creati o eliminati gemelli o relazioni

È possibile limitare i tipi di eventi inviati definendo un filtro più specifico.

Nota

I filtri fanno distinzione tra maiuscole e minuscole e devono corrispondere al caso del payload. Per i filtri di telemetria, ciò significa che la combinazione di maiuscole e minuscole deve corrispondere alla combinazione di maiuscole e minuscole nei dati di telemetria inviati dal dispositivo.

Portale
API

Per aggiungere un filtro eventi durante la creazione di una route eventi, usare la sezione Aggiungi un filtro di route eventi della pagina Crea route eventi.

È possibile selezionare alcune semplici opzioni di filtro di base comuni oppure usare opzioni di filtro avanzate per scrivere filtri personalizzati.

Usare i filtri di base

Per usare i filtri di base, espandere l'opzione Tipi di evento e selezionare le caselle di controllo corrispondenti agli eventi da inviare all'endpoint.

In questo modo, la casella di testo del filtro verrà popolata automaticamente con il testo del filtro selezionato:

Usare i filtri avanzati

È anche possibile usare l'opzione filtro avanzato per scrivere filtri personalizzati.

Per creare una route eventi con opzioni di filtro avanzate, attivare l'interruttore relativo a Editor avanzato per abilitare l'editor. Sarà quindi possibile scrivere filtri eventi personalizzati nella casella Filtro:

È possibile usare le API del piano dati Route eventi per scrivere filtri personalizzati. Per aggiungere un filtro, è possibile usare una richiesta PUT per https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 con il corpo seguente:

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

Filtri di route supportati

Di seguito sono elencati i filtri di route supportati.

Nome filtro	Descrizione	Schema di testo filtro	Valori supportati
True / False	Consente di creare una route senza filtri o disabilitare una route in modo che non vengano inviati eventi	`<true/false>`	`true` = la route è abilitata senza filtri `false` = la route è disabilitata
Type	Il tipo di evento che scorre nell'istanza di Gemelli digitali	`type = '<event-type>'`	Ecco i possibili valori del tipo di evento: `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`
Origine	Nome dell'istanza di Gemelli digitali di Azure	`source = '<host-name>'`	Ecco i possibili valori del nome host: Per le notifiche: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` Per i dati di telemetria: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
Oggetto	Descrizione dell'evento nel contesto dell'origine evento precedente	`subject = '<subject>'`	Ecco i possibili valori oggetto: Per le notifiche: l'oggetto è `<twin-ID>` o un formato URI per soggetti, identificati in modo univoco da più parti o ID: `<twin-ID>/relationships/<relationship-ID>` Per i dati di telemetria: l'oggetto è il percorso del componente (se i dati di telemetria vengono generati da un componente gemello), ad esempio `comp1.comp2`. Se i dati di telemetria non vengono generati da un componente, il relativo campo oggetto è vuoto.
Schema dati	ID modello DTDL	`dataschema = '<model-dtmi-ID>'`	Per i dati di telemetria: lo schema dei dati è l'ID modello del gemello o del componente che genera i dati di telemetria. Ad esempio, `dtmi:example:com:floor4;2` Per le notifiche (creazione/eliminazione): è possibile accedere allo schema dei dati nel corpo della notifica all'indirizzo `$body.$metadata.$model`. Per le notifiche (aggiornamento): è possibile accedere allo schema dei dati nel corpo della notifica all'indirizzo `$body.modelId`
Content type	Tipo di contenuto del valore di dati	`datacontenttype = '<content-type>'`	Il tipo di contenuto è `application/json`
Versione della specifica	Versione dello schema di eventi in uso	`specversion = '<version>'`	La versione deve essere `1.0`. Questo valore indica lo schema CloudEvents versione 1.0
Corpo della notifica	Fare riferimento a qualsiasi proprietà nel campo `data` di una notifica	`$body.<property>`	Per esempi di notifiche, vedere Notifiche degli eventi. È possibile fare riferimento a qualsiasi proprietà nel campo `data` tramite `$body`

Nota

Gemelli digitali di Azure attualmente non supporta il filtraggio degli eventi in base ai campi all'interno di un array. Sono inclusi i filtri sulle proprietà all'interno di una sezione patch di una notifica di modifica del gemello digitale.

I tipi di dati seguenti sono supportati come valori restituiti dai riferimenti ai dati precedenti:

Tipo di dati	Esempio
Stringa	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
Intero	`$body.errorCode > 200`
Double	`$body.temperature <= 5.5`
Bool	`$body.poweredOn = true`
Null	`$body.prop != null`

Per la definizione dei filtri di route sono supportati gli operatori seguenti:

Famiglia	Operatori	Esempio
Logico	AND, OR, ( )	`(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')`
Confronto	<, <=, >, >=, =, !=	`$body.temperature <= 5.5`

Per la definizione dei filtri di route sono supportate le funzioni seguenti:

Funzione	Descrizione	Esempio
STARTS_WITH(x,y)	Restituisce true se il valore `x` inizia con la stringa `y`.	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')`
ENDS_WITH(x, y)	Restituisce true se il valore `x` termina con la stringa `y`.	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
CONTAINS(x,y)	Restituisce true se il valore `x` contiene la stringa `y`.	`CONTAINS(subject, '<twin-ID>')`

Quando si implementa o si aggiorna un filtro, l'applicazione della modifica alla pipeline di dati può richiedere alcuni minuti.

Monitorare le route degli eventi

Le metriche di routing, ad esempio conteggio, latenza e frequenza degli errori, possono essere visualizzate nel portale di Azure.

Per informazioni sulla visualizzazione e la gestione delle metriche con Monitoraggio di Azure, vedere Introduzione a Esplora metriche. Per un elenco completo delle metriche di routing disponibili per Gemelli digitali di Azure, vedere Metriche di routing di Gemelli digitali di Azure.

Passaggi successivi

Leggere i differenti tipi di messaggi di evento che è possibile ricevere:

Notifiche degli eventi

Condividi tramite

Creare route e filtri di eventi in Gemelli digitali di Azure

Prerequisiti

Preparare l'ambiente per l'interfaccia della riga di comando di Azure

Creare una route eventi

Codice DELL'SDK di esempio di route eventi

Filtrare gli eventi

Usare i filtri di base

Usare i filtri avanzati

Filtri di route supportati

Monitorare le route degli eventi

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive