Hoppa till huvudinnehåll

Tidsseriedata

Tidsseriedata finns tillgängliga för översatta iotnodes. När en översatt iotnode uppdateras sparar Yggio numerisk och sträng data i en tidsseriedatabas.

Med hjälp av REST API:et kan du hämta tidsseriedata för ett specifikt attribut från en iotnode.

Följande är formatet för tidsseriedata för ett attribut av en iotnode:

[
  {
    "time": String,
    "value": Number || String
  },
  ...
]

time är ett ISO 8601-tidsstämpel. T.ex.: 2019-08-07T12:30:00.00Z. value är det sparade värdet.

Ställ in tidsintervall​

Man kan välja att hämta data med ett fast tidsintervall mellan varje datapunkt. Detta kan vara önskvärt om en hög dataupplösning inte behövs. Det kan förbättra laddningstider och prestanda. Databasen använder då interpolation för att ställa in värdena för datapunkterna.

Om ett fast tidsintervall används kommer data att ha följande format:

[
  {
    "time": String,
    "value": Number,
    "min": Number,
    "max": Number,
    "stddev": Number
  },
  ...
]

time är ett ISO 8601-tidsstämpel. T.ex.: 2019-08-07T12:30:00.00Z. value är det interpolerade värdet. min är värdet av den minsta punkten i interpolationsområdet. max är värdet av den största punkten i interpolationsområdet. stddev är standardavvikelsen för punkterna i interpolationsområdet.

Sampla ner data med ValueFunction​

Funktionen valueFunction låter dig utföra operationer på data grupperade inom specifika tidsfönster. Detta kan vara användbart för att analysera datatrender över tid genom att sammanfatta datapunkterna inom varje fönster.

Stödda operationer​

Följande operationer kan utföras med valueFunction:

  • mean: Beräknar medelvärdet av alla värden inom fönstret.
  • timeWeightedMean: Beräknar det tidsviktade medelvärdet av alla värden inom fönstret.
  • max: Hittar det högsta värdet inom fönstret.
  • min: Hittar det lägsta värdet inom fönstret.
  • first: Använder det första värdet inom fönstret.
  • last: Använder det sista värdet inom fönstret.
  • sum: Beräknar summan av alla värden inom fönstret.
  • count: Räknar antalet värden inom fönstret.
  • difference: Beräknar skillnaden mellan det första värdet i efterföljande fönster.

Tidsvägt medelvärde​

Det tidsvägda medelvärdet beräknas genom att fastställa hur länge en mätning har befunnit sig i ett visst tillstånd inom ett givet intervall.

Exempel: En sensor mäter utnyttjandegraden av ett skrivbord:

[
    {time: "2025-03-18T13:00:00.000Z", value: 0},
    {time: "2025-03-18T13:30:00.000Z", value: 1},
    {time: "2025-03-18T13:45:00.000Z", value: 0},
    {time: "2025-03-18T14:15:00.000Z", value: 1},
    {time: "2025-03-18T14:30:00.000Z", value: 1},
    {time: "2025-03-18T14:45:00.000Z", value: 0},
    {time: "2025-03-18T15:00:00.000Z", value: 1},
    {time: "2025-03-18T15:45:00.000Z", value: 0}
]

Följande anrop beräknar det tidsvägda medelvärdet av beläggningen för varje timme:

$ curl -X 'GET' \
  'https://staging.yggio.net/api/iotnodes/<iotnode._id>/stats?measurement=occupancy&distance=3600&valueFunction=timeWeightedMean' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Svarsexempel:

[
    {"time": "2025-03-18T13:00:00.000Z", "value": 0.25},
    {"time": "2025-03-18T14:00:00.000Z", "value": 0.5},
    {"time": "2025-03-18T15:00:00.000Z", "value": 0.75}
]

Förklaring:

  • Timme 1 (13:00–14:00): Tre observationer registrerades. Skrivbordet var obelagt (värde 0) i totalt 45 minuter och belagt (värde 1) i 15 minuter. Det ger ett tidsvägt medelvärde på 0,25.
  • Timme 2 (14:00–15:00): Tre observationer registrerades. De första 15 minuterna använder föregående timmes tillstånd (0), följt av två observationer med värde 1. Det ger 30 minuter med värde 0 och 30 minuter med värde 1, vilket resulterar i ett medelvärde på 0,5.
  • Timme 3 (15:00–16:00): Två observationer registrerades. Skrivbordet var belagt (värde 1) i 45 minuter och obelagt (värde 0) i 15 minuter. Det ger ett tidsvägt medelvärde på 0,75.

Notera:

Om den första observationen inträffar efter intervallets starttid kommer resultatet för det intervallet att bli null. Detta beror på att vi inte känner till värdet innan den första observationen och därför inte kan fastställa tillståndet för hela intervallet.

Exempel:

Om det första intervallet startar kl. 13:00 men den första observationen görs kl. 13:15 saknas information om tillståndet mellan 13:00 och 13:15. Eftersom tillståndet före 13:00 är okänt kan systemet varken anta eller härleda ett värde, vilket leder till att resultatet för det första intervallet blir null. Alla efterföljande intervall påverkas inte av detta, eftersom de utgår från tidigare kända värden.

Definiera tidsfönstret​

Tidsfönstret för valueFunction bestäms av alternativet distance. Detta anger längden på varje fönster i antal sekunder. Svarformat

När du använder funktionen valueFunction kommer svaret att ha följande JSON-format:

[
  {
    "time": String,
    "value": Number
  },
  ...
]

time: En ISO 8601-tidsstämpel (t.ex. 2019-08-07T12:30:00.00Z) som anger början av tidsfönstret. value: Resultatet av den specificerade valueFunction-operationen för tidsfönstret.

Hantering av tomma fönster

Om det inte finns några datapunkter inom ett specificerat tidsfönster kommer det fönstret att hoppas över i svaret. Exempel

Här är ett exempel på svar för en API-förfrågan med valueFunction=mean och distance=3600 (1 timme):


[
  {
    "time": "2019-08-07T12:00:00.00Z",
    "value": 23.5
  },
  {
    "time": "2019-08-07T13:00:00.00Z",
    "value": 19.8
  },
  ...
]

I detta exempel är value vid varje tidsstämpel medelvärdet av alla värden inom det motsvarande en-timmes fönstret.