Passa al contenuto principale

Paginazione, Filtri & Date

Questa sezione spiega come usare i parametri comuni di paginazione, ricerca, filtri e gestione delle date sugli endpoint Homsai.

Overview​

Molti endpoint Homsai condividono le stesse convenzioni per:

  • paginazione di liste (plants, devices, sensors, types, load signatures, ecc.);
  • filtri e ricerca testuale (search, UUID, modalità di visualizzazione);
  • intervalli temporali e granularità per storico e metriche energetiche.

Capire questi pattern ti permette di riutilizzare lo stesso approccio su gran parte delle API.

Paginazione​

Gli endpoint che restituiscono liste (es. GET /plants, GET /plants/{plantUuid}/devices, GET /sensor-types, GET /load-signatures) supportano normalmente la paginazione con questi parametri:

  • page: indice di pagina (zero-based, es. 0, 1, 2…).
  • size: numero di elementi per pagina.
  • sort: campo (o campi) su cui ordinare, opzionalmente con direzione (es. name,asc oppure createdAt,desc).

Esempio:

GET /plants?page=0&size=20&sort=name,asc
Authorization: Bearer <accessToken>

La risposta segue in genere il pattern tipico di Spring (o equivalente), con:

  • l’array di elementi (es. content o data);
  • informazioni sulla pagina corrente (numero, size);
  • conteggi totali (es. totalElements, totalPages).

Ricerca e filtri​

Molti endpoint espongono parametri di filtro per restringere i risultati.

Esempi comuni:

  • search: filtro testuale generico (per nome, descrizione o altri campi indicizzati).
  • plantUuids: elenco di UUID di plant da includere (su GET /plants).
  • externalIds: elenco di identificativi esterni (su GET /plants).
  • dataTypesCollectUuid: filtro per tipo di dato raccolto (su GET /plants/{plantUuid}/sensors).
  • mode: su alcuni endpoint, per cambiare “vista” logica, ad esempio:
    • GET /plants/{plantUuid}/vendors?mode=config (vendor configurati),
    • GET /plants/{plantUuid}/vendors?mode=not_config (vendor non ancora configurati).
  • includeRelationships: flag per includere informazioni relazionali aggiuntive (es. sensori collegati a un device).

Esempi:

GET /plants?search=rossi&size=10

GET /plants/{plantUuid}/devices?search=inverter&includeRelationships=true

GET /plants/{plantUuid}/sensors?dataTypesCollectUuid=<uuid>&page=0&size=50

GET /plants/{plantUuid}/vendors?mode=config

La combinazione di paginazione + filtri consente di interrogare in modo efficiente grandi impianti con molti dispositivi e sensori.

Date e intervalli​

Gli endpoint che lavorano con storico e metriche energetiche utilizzano formati data coerenti.

Formati più comuni:

  • Data semplice (giorno):

    • yyyy-MM-dd
    • Esempio: 2025-01-15
    • Usato ad esempio per:
      • GET /plants/{plantUuid}/daily-power-consumptions?date=2025-01-15
      • GET /plants/{plantUuid}/daily-power-productions?date=2025-01-15

  • Data e ora (timestamp):

    • yyyy-MM-dd'T'HH:mm
    • Esempio: 2025-01-15T13:30
    • Usato per definire intervalli in:
      • GET /plants/{plantUuid}/sensor-history-consumptions
      • GET /plants/{plantUuid}/sensor-history-productions
      • GET /plants/{plantUuid}/sensor-history-energy

Parametri tipici:

  • startDate: inizio intervallo (obbligatorio in diversi endpoint).
  • endDate: fine intervallo (spesso opzionale).
  • date: giorno di riferimento (per endpoint che lavorano su finestre relative, tipo “ultimi 7 giorni” o “ultime 24 ore”).

Esempi:

GET /plants/{plantUuid}/summary-daily-power-consumptions?startDate=2025-01-01&endDate=2025-01-31

GET /plants/{plantUuid}/sensor-history-consumptions?startDate=2025-01-01T00:00&endDate=2025-01-07T23:59&granularity=hours

Granularità dei dati​

Per alcune API di storico, puoi controllare la granularità dei dati restituiti:

  • parametro: granularity
  • valori supportati:
    • seconds
    • minutes
    • hours
    • days

Esempi:

  • granularity=seconds: restituisce punti quasi grezzi (massima risoluzione disponibile).
  • granularity=hours: aggrega i dati su base oraria.
  • granularity=days: aggrega su base giornaliera.

Questo parametro è usato ad esempio in:

  • GET /plants/{plantUuid}/sensor-history-consumptions
  • GET /plants/{plantUuid}/sensor-history-productions

Scegli la granularità in base allo use case:

  • dashboard in tempo reale → seconds o minutes;
  • grafici giornalieri/orari → hours;
  • report mensili o confronti su lungo periodo → days.