Inviare eventi a un ambiente Time Series Insights tramite un hub eventiSend events to a Time Series Insights environment using event hub

Questo articolo illustra come creare e configurare un hub eventi ed eseguire un'applicazione di esempio per effettuare il push degli eventi.This article explains how to create and configure event hub and run a sample application to push events. Se è presente un hub eventi con eventi in formato JSON, saltare questa esercitazione e visualizzare l'ambiente in Time Series Insights.If you have an existing event hub with events in JSON format, skip this tutorial and view your environment in Time Series Insights.

Configurare un hub eventiConfigure an event hub

  1. Per creare un hub eventi, seguire le istruzioni contenute nella documentazione sugli hub eventi.To create an event hub, follow instructions from the Event Hub documentation.

  2. Cercare hub eventi nella barra di ricerca.Search for event hub in the search bar. Nell'elenco dei risultati fare clic su Hub eventi.Click Event Hubs in the returned list.

  3. Per selezionare l'hub eventi, fare clic sul relativo nome.Select your event hub by clicking on its name.

  4. In Entità nella finestra di configurazione centrale fare clic di nuovo su Hub eventi.Under Entities in the middle configuration window, click Event Hubs again.

  5. Selezionare il nome dell'hub eventi per configurarlo.Select the name of the event hub to configure it.

    Selezionare il gruppo di consumer dell'hub eventi

  6. In Entità selezionare Gruppi di consumer.Under Entities, select Consumer groups.

  7. Assicurarsi di creare un gruppo di consumer usato esclusivamente dall'origine evento di Time Series Insights.Make sure you create a consumer group that is used exclusively by your Time Series Insights event source.

    Importante

    Verificare che questo gruppo di consumer non venga usato da altri servizi, ad esempio un processo di Analisi di flusso o un altro ambiente Time Series Insights.Make sure this consumer group is not used by any other service (such as Stream Analytics job or another Time Series Insights environment). Se il gruppo di consumer viene usato da altri servizi, l'operazione di lettura viene compromessa per questo ambiente e per gli altri servizi.If the consumer group is used by other services, read operation is negatively affected for this environment and the other services. Se si usa "$Default" come gruppo di consumer, è probabile che venga usato anche da altri lettori.If you are using “$Default” as the consumer group, it could lead to potential reuse by other readers.

  8. Sotto l'intestazione Impostazioni selezionare Criteri di accesso condiviso.Under the Settings heading, select Share access policies.

  9. Nell'hub eventi creare MySendPolicy che viene usato per inviare eventi nell'esempio csharp.On the event hub, create MySendPolicy that is used to send events in the csharp sample.

    Selezionare Criteri di accesso condiviso e fare clic sul pulsante Aggiungi

    Aggiungere nuovi criteri di accesso condiviso

Aggiungere un set di dati di riferimento Time Series InsightsAdd Time Series Insights reference data set

L'uso di dati di riferimento in Time Series Insights consente di contestualizzare i dati di telemetria.Using reference data in TSI contextualizes your telemetry data. Tale contesto aggiunge significato ai dati e facilita le operazioni di filtro e aggregazione.That context adds meaning to your data and makes it easier to filter and aggregate. Time Series Insights esegue il join dei dati di riferimento in fase di ingresso e non può eseguire questa operazione retroattivamente.TSI joins reference data at ingress time and cannot retroactively join this data. È quindi fondamentale aggiungere i dati di riferimento prima di aggiungere un'origine eventi contenente dati.Therefore, it is critical to add reference data prior to adding an event source with data. I dati come il tipo di percorso o di sensore sono dimensioni utili da unire in join a un ID di dispositivo/tag/sensore per facilitare le operazioni di sezionamento e filtro.Data like location or sensor type are useful dimensions that you might want to join to a device/tag/sensor ID to make it easier to slice and filter.

Importante

La disponibilità di un set di dati di riferimento configurato è fondamentale quando si caricano dati cronologici.Having a reference data set configured is critical when you upload historical data.

Verificare che i dati di riferimento siano già disponibili quando si eseguono caricamenti in blocco di dati cronologici in Time Series Insights.Ensure that you have reference data in place when you bulk upload historical data to TSI. Tenere presente che Time Series Insights inizia immediatamente la lettura da un'origine eventi unita in join se tale origine eventi include dati.Keep in mind, TSI will immediately start reading from a joined event source if that event source has data. È utile aspettare a creare il join tra un'origine eventi e Time Series Insights fino a quando i dati di riferimento non sono a disposizione, in particolare se l'origine eventi include dati.It's useful to wait to join an event source to TSI until you have your reference data in place, especially if that event source has data in it. In alternativa, è possibile attendere a eseguire il push dei dati in tale origine eventi fino a quando non è disponibile il set di dati di riferimento.Alternatively, you can wait to push data to that event source until the reference data set is in place.

Per gestire i dati di riferimento, sono disponibili l'interfaccia utente basata sul Web in TSI Explorer e un'API C# programmatica.To manage reference data, there is the web-based user interface in the TSI Explorer, and there is a programmatic C# API. TSI Explorer include un'esperienza utente visiva per caricare i file o incollare set di dati di riferimento esistenti in formato JSON o CSV.TSI Explorer has a visual user experience to upload files or paste-in existing reference data sets as JSON or CSV format. Con l'API è possibile creare app personalizzate all'occorrenza.With the API, you can build a custom app when needed.

Per altre informazioni sulla gestione dei dati di riferimento in Time Series Insights, vedere l'articolo sui dati di riferimento.For more information on managing reference data in Time Series Insights, see the reference data article.

Creare un'origine evento di Time Series InsightsCreate Time Series Insights event source

  1. Se non è ancora stata creata un'origine evento, seguire queste istruzioni per crearne una.If you haven't created an event source, follow these instructions to create an event source.

  2. Specificare deviceTimestamp come nome della proprietà Timestamp. Questa proprietà viene usata come timestamp effettivo nell'esempio C#.Specify deviceTimestamp as the timestamp property name – this property is used as the actual timestamp in the C# sample. Il nome della proprietà timestamp applica la distinzione tra maiuscole e minuscole e i valori devono avere il formato aaaa-MM-ggTHH:mm:ss.FFFFFFFK quando viene inviato come file JSON all'hub eventi.The timestamp property name is case-sensitive and values must follow the format yyyy-MM-ddTHH:mm:ss.FFFFFFFK when sent as JSON to event hub. Se la proprietà non esiste nell'evento, verrà usata l'ora in cui l'evento è stato accodato nell'hub eventi.If the property does not exist in the event, then the event hub enqueued time is used.

    Creare un'origine evento

Codice di esempio per effettuare il push degli eventiSample code to push events

  1. Passare al criterio dell'hub eventi denominato MySendPolicy.Go to the event hub policy named MySendPolicy. Copiare la stringa di connessione con la chiave del criterio.Copy the connection string with the policy key.

    Copiare la stringa di connessione MySendPolicy

  2. Eseguire questo codice per inviare 600 eventi per ognuno dei tre dispositivi.Run the following code that to send 600 events per each of the three devices. Aggiornare eventHubConnectionString con la stringa di connessione.Update eventHubConnectionString with your connection string.

using System;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using Microsoft.ServiceBus.Messaging;

namespace Microsoft.Rdx.DataGenerator
{
    internal class Program
    {
        private static void Main(string[] args)
        {
            var from = new DateTime(2017, 4, 20, 15, 0, 0, DateTimeKind.Utc);
            Random r = new Random();
            const int numberOfEvents = 600;

            var deviceIds = new[] { "device1", "device2", "device3" };

            var events = new List<string>();
            for (int i = 0; i < numberOfEvents; ++i)
            {
                for (int device = 0; device < deviceIds.Length; ++device)
                {
                    // Generate event and serialize as JSON object:
                    // { "deviceTimestamp": "utc timestamp", "deviceId": "guid", "value": 123.456 }
                    events.Add(
                        String.Format(
                            CultureInfo.InvariantCulture,
                            @"{{ ""deviceTimestamp"": ""{0}"", ""deviceId"": ""{1}"", ""value"": {2} }}",
                            (from + TimeSpan.FromSeconds(i * 30)).ToString("o"),
                            deviceIds[device],
                            r.NextDouble()));
                }
            }

            // Create event hub connection.
            var eventHubConnectionString = @"Endpoint=sb://...";
            var eventHubClient = EventHubClient.CreateFromConnectionString(eventHubConnectionString);

            using (var ms = new MemoryStream())
            using (var sw = new StreamWriter(ms))
            {
                // Wrap events into JSON array:
                sw.Write("[");
                for (int i = 0; i < events.Count; ++i)
                {
                    if (i > 0)
                    {
                        sw.Write(',');
                    }
                    sw.Write(events[i]);
                }
                sw.Write("]");

                sw.Flush();
                ms.Position = 0;

                // Send JSON to event hub.
                EventData eventData = new EventData(ms);
                eventHubClient.Send(eventData);
            }
        }
    }
}

Forme JSON supportateSupported JSON shapes

Esempio 1Sample 1

InputInput

Un oggetto JSON semplice.A simple JSON object.

{
    "id":"device1",
    "timestamp":"2016-01-08T01:08:00Z"
}

Output - un eventoOutput - one event

idid timestamptimestamp
device1device1 2016-01-08T01:08:00Z2016-01-08T01:08:00Z

Esempio 2Sample 2

InputInput

Una matrice JSON con due oggetti JSON.A JSON array with two JSON objects. Ogni oggetto JSON verrà convertito in un evento.Each JSON object will be converted to an event.

[
    {
        "id":"device1",
        "timestamp":"2016-01-08T01:08:00Z"
    },
    {
        "id":"device2",
        "timestamp":"2016-01-17T01:17:00Z"
    }
]

Output - due eventiOutput - two events

idid timestamptimestamp
device1device1 2016-01-08T01:08:00Z2016-01-08T01:08:00Z
device2device2 2016-01-08T01:17:00Z2016-01-08T01:17:00Z

Esempio 3Sample 3

InputInput

Un oggetto JSON con una matrice JSON annidata che contiene due oggetti JSON:A JSON object with a nested JSON array that contains two JSON objects:

{
    "location":"WestUs",
    "events":[
        {
            "id":"device1",
            "timestamp":"2016-01-08T01:08:00Z"
        },
        {
            "id":"device2",
            "timestamp":"2016-01-17T01:17:00Z"
        }
    ]
}

Output - due eventiOutput - two events

Si noti che la proprietà "location" viene copiata in ogni evento.Notice the property "location" is copied over to each of the event.

locationlocation events.idevents.id events.timestampevents.timestamp
WestUsWestUs device1device1 2016-01-08T01:08:00Z2016-01-08T01:08:00Z
WestUsWestUs device2device2 2016-01-08T01:17:00Z2016-01-08T01:17:00Z

Esempio 4Sample 4

InputInput

Un oggetto JSON con una matrice JSON annidata che contiene due oggetti JSON.A JSON object with a nested JSON array containing two JSON objects. Questo input dimostra che le proprietà globali possono essere rappresentate dall'oggetto JSON complesso.This input demonstrates that the global properties may be represented by the complex JSON object.

{
    "location":"WestUs",
    "manufacturer":{
        "name":"manufacturer1",
        "location":"EastUs"
    },
    "events":[
        {
            "id":"device1",
            "timestamp":"2016-01-08T01:08:00Z",
            "data":{
                "type":"pressure",
                "units":"psi",
                "value":108.09
            }
        },
        {
            "id":"device2",
            "timestamp":"2016-01-17T01:17:00Z",
            "data":{
                "type":"vibration",
                "units":"abs G",
                "value":217.09
            }
        }
    ]
}

Output - due eventiOutput - two events

locationlocation manufacturer.namemanufacturer.name manufacturer.locationmanufacturer.location events.idevents.id events.timestampevents.timestamp events.data.typeevents.data.type events.data.unitsevents.data.units events.data.valueevents.data.value
WestUsWestUs manufacturer1manufacturer1 EastUsEastUs device1device1 2016-01-08T01:08:00Z2016-01-08T01:08:00Z pressurepressure psipsi 108.09108.09
WestUsWestUs manufacturer1manufacturer1 EastUsEastUs device2device2 2016-01-08T01:17:00Z2016-01-08T01:17:00Z vibrationvibration abs Gabs G 217.09217.09

Strategie per formare eventi JSONJSON shaping strategies

L'esempio di evento seguente verrà usato come punto di partenza per presentare i problemi correlati e le strategie per mitigare tali problemi.Let's use the following example of an event as a starting point, and then discuss issues related with it and strategies for mitigating those issues.

Payload 1:Payload 1:

[{
            "messageId": "LINE_DATA",
            "deviceId": "FXXX",
            "timestamp": 1522355650620,
            "series": [{
                        "chId": 3,
                        "value": -3750.0
                  }, {
                        "chId": 13,
                        "value": 0.58015072345733643
                  }, {
                        "chId": 11,
                        "value": 800.0
                  }, {
                        "chId": 21,
                        "value": 0.0
                  }, {
                        "chId": 14,
                        "value": -999.0
                  }, {
                        "chId": 37,
                        "value": 2.445906400680542
                  }, {
                        "chId": 39,
                        "value": 0.0
                  }, {
                        "chId": 40,
                        "value": 1.0
                  }, {
                        "chId": 1,
                        "value": 1.0172575712203979
                  }
            ],
            "EventProcessedUtcTime": "2018-03-29T20:36:21.3245900Z",
            "PartitionId": 2,
            "EventEnqueuedUtcTime": "2018-03-29T20:34:11.0830000Z",
            "IoTHub": {
                  "MessageId": "<17xxx2xx-36x0-4875-9x1x-x428x41x1x68>",
                  "CorrelationId": "<x253x5xx-7xxx-4xx3-91x4-xxx3bx2xx0x3>",
                  "ConnectionDeviceId": "AAAA-ZZ-001",
                  "ConnectionDeviceGenerationId": "<123456789012345678>",
                  "EnqueuedTime": "2018-03-29T20:34:10.7990000Z",
                  "StreamId": null
            }
      }
]

Se si esegue il push della matrice di eventi come payload in Time Series Insights, verrà archiviata come un evento per ogni valore di misura.If you push this array of events as a payload to TSI, it will be stored as one event per each measure value. In questo modo è possibile che si crei un numero eccessivo di eventi, che potrebbe non essere ideale.Doing so can create an excess of events, which may not be ideal. Si noti che è possibile usare dati di riferimento in Time Series Insights per aggiungere nomi significativi come proprietà.Notice that you can use reference data in TSI to add meaningful names as properties. Ad esempio, è possibile creare un set di dati di riferimento con la proprietà chiave = chId:For example, you can create reference data set with Key Property = chId:

chId Measure Unit 24 Engine Oil Pressure PSI 25 CALC Pump Rate bbl/minchId Measure Unit 24 Engine Oil Pressure PSI 25 CALC Pump Rate bbl/min

Per altre informazioni sulla gestione dei dati di riferimento in Time Series Insights, vedere l'articolo sui dati di riferimento.For more information on managing reference data in Time Series Insights, see the reference data article.

Un altro problema con il primo payload è che tale timestamp è espresso in millisecondi.Another problem with the first payload is that timestamp is in milliseconds. Time Series Insights accetta solo timestamp in formato ISO.TSI accepts only ISO formatted timestamps. Una soluzione consiste nel lasciare il comportamento predefinito per il timestamp in Time Series Insights, che prevede l'uso di timestamp accodati.One solution is to leave the default timestamp behavior in TSI, which is to use enqueued timestamp.

In alternativa al payload precedente, di seguito verrà esaminato un altro esempio.As an alternative to the payload above, let's look at another example.

Payload 2:Payload 2:

{
      "line": "Line01",
      "station": "Station 11",
      "gatewayid": "AAAA-ZZ-001",
      "deviceid": "F12XX",
      "timestamp": "2018-03-29T20:34:15.0000000Z",
      "STATE Engine State": 1,
      "unit": "NONE"
}, {
      "line": "Line01",
      "station": "Station 11",
      "gatewayid": "AAAA-ZZ-001",
      "deviceid": "MPC_AAAA-ZZ-001",
      "timestamp": "2018-03-29T20:34:15.0000000Z",
      "Well Head Px 1": -494162.8515625,
      "unit": "psi"
}, {
      "line": "Line01",
      "station": "Station 11",
      "gatewayid": "AAAA-ZZ-001",
      "deviceid": "F12XX",
      "timestamp": "2018-03-29T20:34:15.0000000Z",
      "CALC Pump Rate": 0,
      "unit": "bbl/min"
}, {
      "line": "Line01",
      "station": "Station 11",
      "gatewayid": "AAAA-ZZ-001",
      "deviceid": "F12XX",
      "timestamp": "2018-03-29T20:34:15.0000000Z",
      "Engine Fuel Pressure": 0,
      "unit": "psi"
}, {
      "line": "Line01",
      "station": "Station 11",
      "gatewayid": "AAAA-ZZ-001",
      "deviceid": "F12XX",
      "timestamp": "2018-03-29T20:34:15.0000000Z",
      "Engine Oil Pressure": 0.58015072345733643,
      "unit": "psi"
}

Come per il payload 1, Time Series Insights archivierà ogni valore misurato come un evento univoco.Like Payload 1, TSI will store each every measured value as a unique event. La differenza evidente è che Time Series Insights leggerà il timestamp come ISO, come è corretto in questo caso.The notable difference is that TSI will read the timestamp as correctly here, as ISO.

Se è necessario ridurre il numero di eventi inviati, è possibile inviare le informazioni come indicato di seguito.If you need to reduce the number of events sent, then you could send the information as the following.

Payload 3:Payload 3:

{
      "line": "Line01",
      "station": "Station 11",
      "gatewayid": "AAAA-ZZ-001",
      "deviceid": "F12XX",
      "timestamp": "2018-03-29T20:34:15.0000000Z",
      "CALC Pump Rate": 0,
      "CALC Pump Rate.unit": "bbl/min"
      "Engine Oil Pressure": 0.58015072345733643,
      "Engine Oil Pressure.unit": "psi"
      "Engine Fuel Pressure": 0,
      "Engine Fuel Pressure.unit": "psi"
}

Di seguito è riportato un suggerimento finale.One final suggestion is below.

Payload 4:Payload 4:

{
              "line": "Line01",
              "station": "Station 11",
              "gatewayid": "AAAA-ZZ-001",
              "deviceid": "F12XX",
              "timestamp": "2018-03-29T20:34:15.0000000Z",
              "CALC Pump Rate": {
                           "value": 0,
                           "unit": "bbl/min"
              },
              "Engine Oil Pressure": {
                           "value": 0.58015072345733643,
                           "unit": "psi"
              },
              "Engine Fuel Pressure": {
                           "value": 0,
                           "unit": "psi"
              }
}

Questo esempio mostra l'output dopo l'appiattimento del codice JSON:This example shows the output after flattening the JSON:

{
      "line": "Line01",
      "station": "Station 11",,
      "gatewayid": "AAAA-ZZ-001",
      "deviceid": "F12XX",
      "timestamp": "2018-03-29T20:34:15.0000000Z",
      "CALC Pump Rate.value": 0,
      "CALC Pump Rate.unit": "bbl/min"
      "Engine Oil Pressure.value": 0.58015072345733643,
      "Engine Oil Pressure.unit": "psi"
      "Engine Fuel Pressure.value": 0,
      "Engine Fuel Pressure.unit": "psi"
}

Si ha la possibilità di definire proprietà diverse per ognuno dei canali all'interno di un proprio oggetto JSON, mantenendo comunque basso il numero degli eventi.You have the freedom to define different properties for each of the channels inside its own json object, while still keeping the event count low. Questo approccio appiattito occupa più spazio e questo è un aspetto importante da considerare.This flattened approach does occupy more space, which is important to consider. La capacità di Time Series Insights si basa sia sugli eventi che sulle dimensioni, a seconda dell'aspetto prioritario.TSI capacity is based on both events and size, whichever comes first.

Passaggi successiviNext steps