Creare route e filtri di eventi in Gemelli digitali di Azure

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

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, dovresti aver già creato gli endpoint.

Prerequisiti

• È necessario un account Azure, che può essere configurato gratuitamente

• Hai bisogno di un'istanza di Azure Digital Twins nella tua sottoscrizione 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 dell'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 viene creata una route per inviare dati a tale endpoint.

Seguire quindi le istruzioni seguenti 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 Introduzione ad 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 Eseguire l'autenticazione ad Azure con 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 e gestire 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.

Crea 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. Per altre informazioni sulle route di eventi, vedere Route di eventi di Gemelli digitali di Azure.

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

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 diverso, i messaggi vengono filtrati in base al filtro.

È possibile creare route di eventi con il portale di Azure, le API del piano dati Event Routes o i comandi della CLI 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 rotte hanno un campo filtro. Se il valore del filtro nella route è false, nessun evento viene inviato all'endpoint.

Dopo aver abilitato un filtro minimo di true, gli endpoint riceveranno diversi 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, la modifica potrebbe richiedere alcuni minuti per essere riflessa nella pipeline di dati.

Monitorare i percorsi 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 Analizzare le metriche con Esplora metriche di Monitoraggio di Azure. Per un elenco completo delle metriche di routing disponibili per Gemelli digitali di Azure, vedere Metriche di routing.

Passaggi successivi

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

• Notifiche degli eventi