Creare route e filtri di eventi in Gemelli digitali di Azure

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.

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.

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

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.

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

Filtri di route supportati

Di seguito sono elencati i filtri di route supportati.

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

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

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

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