Données de Télémétrie

Aggregated APIs

Les API agrégées sont principalement utilisées lorsque vous souhaitez obtenir, pour un certain type de données, une seule valeur en réponse, qui permet de résumer une certaine tendance et/ou résultat, pour une fenêtre temporelle personnalisée.

Ces types d’API sont toujours structurés comme suit:

Le path, qui permet de pointer vers les ressources souhaitées, nécessite toujours les paramètres suivants:

  • {power,frequency,wind,temperature,voltage,current,energy,kpis}: le type de ressource vers laquelle pointer. Ce paramètre ne précise pas les données réelles que vous souhaitez obtenir, mais la catégorie générale à laquelle appartiennent les données souhaitées (veuillez noter qu’un appel API n’accepte qu’une seule catégorie à la fois, il n’est actuellement pas possible de faire des appels BULK);
  • {entityID}: il peut s’agir d’un EID d’usine ou d’un appareil. Dans le premier cas, la valeur obtenue tient compte de l’agrégation de tous les appareils, pour lesquels cette valeur existe, au niveau de l’usine ; dans le second cas, la valeur obtenue fait référence à l’appareil unique d’intérêt;
  • {dataType}: représente les données réelles à obtenir. Les dataTypes disponibles varient selon les ressources pointées, une description détaillée est disponible directement dans la OpenAPIs Swagger;
  • {valuetype}: représente le type de critère d’agrégation avec lequel les données demandées sont à obtenir.

Les requêtes, qui permettent de filtrer les données demandées, nécessitent toujours les paramètres suivants:

  • {startDate}: la borne inférieure qui permet de définir le début de la fenêtre temporelle d’intérêt. Son format est YYYYMMGG (eg: 20220321);
  • {endDate}: la borne supérieure qui permet de définir la fin de la fenêtre temporelle d’intérêt. Son format est YYYYMMGG (eg: 20220322) et il doit être temporellement postérieur au {startDate};
  • {timezone}: permet de guider l’appel de l’API vers une récupération correcte des données en fonction du fuseau horaire demandé.

Un appel agrégé fournit toujours une seule valeur comme réponse, qui est manipulée en fonction de la fenêtre horaire et du fuseau horaire indiqués. Dans ce contexte, le paramètre {valuetype} a une grande importance car il varie selon la catégorie de ressources, donc de {dataType}, à obtenir.

Pour un {dataType} appartenant à la catégorie {power,frequency,wind,temperature,voltage,current,kpis}, le {valueType} peut prendre trois valeurs différentes:

  • Maximum: renvoie la valeur maximale trouvée parmi tous les échantillons présents dans le temps {startDate} et {endDate} défini fenêtre, pour le {dataType};
  • Minimum: renvoie la valeur minimale trouvée parmi tous les échantillons présents dans le temps {startDate} et {endDate} défini fenêtre, pour le {dataType};
  • Average: renvoie la valeur moyenne de tous les échantillons présents dans la fenêtre temporelle {startDate} et {endDate} défini fenêtre, pour le {dataType};

REMARQUE: pour la catégorie kpis , les considérations ci-dessus ne sont valables que si les Power-Based KPIs sont appelés. Pour plus de détails, veuillez consulter OpenAPIs Swagger.

Regardons quelques cas d’utilisation, où nous considérons une installation ( entityID: 12345678 ) avec un seul onduleur enregistré ( entityID : 87654321 ):

Use Case 1

Je veux obtenir la valeur maximale, trouvée le jour de l’équinoxe de printemps, de la puissance générée par l’usine.

Analyse des Problèmes

Considérant que le rapport entre l’usine et les appareils enregistrés est de 1:1, je peux indifféremment saisir l’ entityID de l’un des deux. Je veux la puissance produite, je vais donc pointer les ressources de la catégorie power et demander la GenerationPower.

Request

GET   https://api.auroravision.net/api/rest/v1/stats/power/aggregated/12345678/GenerationPower/maximum?startDate=20220321&endDate=20220322&timeZone=Europe/Rome

Response

Use Case 2

Je veux obtenir la valeur moyenne, le jour de l’équinoxe de printemps, de toute la tension mesurée par l’onduleur.

ProAnalyse des Problèmes

Considérant que le rapport entre l’usine et les appareils enregistrés est de 1:1, je peux indifféremment saisir l’ entityID de l’un des deux. Je veux la tension, je vais donc pointer les ressources de la catégorie voltage and et demander la Voltage.

Request

GET   https://api.auroravision.net/api/rest/v1/stats/voltage/aggregated/87654321/Voltage/average?startDate=20220321&endDate=20220322&timeZone=Europe/Rome

Response

Pour un {dataType} appartenant à la catégorie {energy,kpis}, le {valueType} peut prendre deux valeurs différentes:

  • Cumulative: renvoie la dernière valeur cumulée disponible dans la fenêtre temporelle {startDate} et {endDate} défini fenêtre, pour le {dataType};
  • Delta: renvoie la différence entre la dernière et la première valeur cumulée disponible dans le {startDate} et {endDate} défini fenêtre, pour le {dataType};

REMARQUE: pour la catégorie kpis , les considérations ci-dessus ne sont valables que si les Energy-Based KPIs sont appelés. Pour plus de détails, veuillez consulter OpenAPIs Swagger.

Regardons quelques cas d’utilisation, où nous considérons une installation ( entityID: 12345678 ) avec un seul onduleur enregistré ( entityID : 87654321 ):

Use Case 1

Je souhaite obtenir l’énergie générée par l’usine depuis le début de sa production jusqu’au jour de l’équinoxe de printemps..

Analyse des Problèmes

Considérant que le rapport entre l’usine et les appareils enregistrés est de 1:1, je peux indifféremment saisir l’ entityID de l’un des deux. Je veux l’énergie produite jusqu’à présent par la centrale, je vais donc pointer les ressources de la catégorie energy et demander le cumulative de la GenerationEnergy.

Request

GET   https://api.auroravision.net/api/rest/v1/stats/energy/aggregated/12345678/GenerationEnergy/cumulative?startDate=20220321&endDate=20220322&timeZone=Europe/Rome

Response

Use Case 2

I want to obtain the energy generated on the day of the spring equinox, by the inverter.

Analyse des Problèmes

Considérant que le rapport entre l’usine et les appareils enregistrés est de 1:1, je peux indifféremment saisir l’ entityID de l’un des deux. Je veux l’énergie générée le jour de l’équinoxe de printemps uniquement, je vais donc pointer les ressources de la catégorie energy et demander le delta de la GenerationEnergy.

Request

GET   https://api.auroravision.net/api/rest/v1/stats/energy/aggregated/87654321/GenerationEnergy/delta?startDate=20220321&endDate=20220322&timeZone=Europe/Rome

Response

Pages: 1 2 3 4