API des cubes

Préambule et démo

Dans l’objectif d’offrir un moyen plus adapté d’accéder aux données, nous avons implémenté une API permettant de requêter les données sous la représentation du cube.

Définition d’un cube

Un cube est un représentation tridimensionnelle des données tel que :

• Axe des dimensions : Identifiant d’une donnée.

• Axe des valeurs bruts : Projection plate de la donnée.

• Axe des mesures : Une projection d’une donnée par rapport à un sous ensemble exprimé selon un agrégateur.

Un Cube est identifié via son Id, exemple : Analysis.Users prenant pour point de départ les utilisateurs et permettrai de déterminer l’établissement d’un utilisateur via une dimension Establishment.Id. Un autre Cube Analysis.Establishments aura pour point de départ un établissement, et permettrai de lister ses utilisateurs avec la dimension Member.Name et permettrai d’en déterminer le nombre via la mesure Member.Id avec l’agrégateur Count.

Définition d’un Criteria

Afin de réduire le volume de données, il convient d’utiliser des filtres, que nous appelons Criteria. Un Criteria se compose de 3 éléments :

• Field : une dimension à cibler.

• Comparator : Déterminer la comparaison à appliquer à la Valeur.

• Value : la valeur de comparaison.

Exemple : un Criteria { Field : « User.FirstName », Coperator : Equal, Value : “Paul” } restreindra les résultats aux utilisateurs nommés Paul. Ces Criteria peuvent être regroupés dans un objet Operator définissant l’opération AND ou OR à appliquer sur ses children.

Note : l’élément racine opère un AND sur ses enfants.

Exploiter l’existant

Au sein de Xperience, vous pouvez interroger ces cubes au moyen des rapports dans le module Analyse. Pour créer un rapport, vous devez commencer par sélectionner un cube avant de définir les Dimensions et Mesures (les dénommés Valeurs).

Sur la page de ce dernier, sous l’onglet Rapport, récupérer la requête vous permettant d’obtenir le même résultat via notre API :

Note : Cette fonctionnalité est également accessible via les requêtes d’API

GET /api/cubes/customreports

et

GET /api/cubes/customreports/{REPORT_ID}

Pourquoi utiliser l’API des Cubes ?

L’utilisation via les rapports induit une pagination courte systématique ; cependant dans la mesure ou l’API Cube est implémenté dans un besoin Backend-to-Backend, la pagination n’est appliquée qu’à la demande et selon la volumétrie des données requêtées. De ce fait, le délais de traitement peut se voir lourdement allongé.

Afin de passer outre la limitation de temps de réponse du protocole http, nous avons décorrélé la requête de sa réponse.

En effet, là où une API standard comme celle de oData retourne les données en tant que contenue de la réponse, l’API Cube vous retournera un identifiant de traitement GenerationID.

Ce GénérationID vous servira, une fois la génération terminée, à récupérer le résultat. Les avantages de cette procédure sont multiples. Le plus pertinent est que, une fois le résultat disponible, il peut être rapatrié plusieurs fois sans coût relatif à la BDD.  

Il est alors possible de planifier une tache qui lancera la génération sur une plage horaire de faible affluence et de consommer le résultat au moment voulu.

Une documentation technique en ligne

L’API Cube expose un certain nombre de requêtes. Elles sont décrites dans la documentation en ligne accessible sous l’url :

https://serveur-xperience.syfadis.com/swagger/ui/index

Vous devez être connecté au serveur Xperience pour accéder à cette page.

L’utilisation de ‘API des cubes se fait de manière authentifiée (Basic-Auth) via un utilisateur OData sur lequel on peut définir une langue. Les données sont alors remontées dans la langue de cet utilisateur.

Construire sa requête

La première étape sera de définir le Cube qui servira de point de départ. Pour cela, vous utiliserez la requête :

GET /api/cubes

Une fois le Cube déterminé, il convient de définir les dimensions et mesures que vous souhaitez remonter.

Utilisez pour cela les requêtes :

GET /api/cubes/{CUBE_ID}/dimensions

et

GET /api/cubes/{CUBE_ID}/measures

Dans notre exemple, on constate une complexité de 1, signifiant que la donnée se trouve dans le cube racine, si cette valeur augmente, cela signifie que la donnée se trouve dans des cubes imbriqués.

Nous constatons également que le type de la dimensions Gender est Enumeration. Cela implique que la valeur retourné sera un entier correspondante a une énumération.

Vous trouverez les valeurs correspondante en faisant appel à la requête :

GET /api/cubes/{CUBE_ID}/criteria/{field}

Nous allons pour l’exemple créer une requête simple mais exhaustive :

Ces deux écrans représentent le même rapport conçu depuis l’outil de reporting d’où l’on a récupéré la requête API. Cette requête API peut être récupérée à partir d’un bouton Copier la requête API à retrouver dans le premier onglet Rapport. La présence de ce bouton est soumise à l’activation d’un privilège.

Nous prenons pour point de départ le Cube Analysis.Users, en ciblant 2 dimensions et une valeur en Count et en appliquant un filtre composé. Nous n’appliquons pas de pagination.

Lancer le génération

Lorsque vous avez rassemblé tous les éléments, nous pouvons passer à la seconde étape : demander une génération.

Cela s’opère via la requête POST /api/cubes. Voici un exemple simple mais complet :

Suivre la progression

L’API retourne alors le GenerationID avec le quel l’on peut suivre l’état d’avancement de la génération avec la requête GET /api/cubes/status

Note : il est possible d’appeler cette requête en cours de génération, le Status Code sera alors adapté à l’état d’avancement.

Si le résultat de cet exemple est très léger, selon la volumétrie des données demandé, il peut constituer un JSON bien plus conséquent qui est pour rappel stocké sous la forme d’un fichier sur le disque dur du serveur.

Aussi, il convient de purger régulièrement ces données de rapports temporaires, un délai de rétention de 14 jours est applique.

Les données peuvent être aussi supprimées manuellement (avant ce délai de rétention) au moyen de la requête DELETE /api/cubes/{GENERATION_ID}

Scope et langue appliqués lors de l’utilisation de l’API

Contrairement aux rapports dans les analyses, aucun filtre de visibilité par défaut n’est appliqué lors de l’utilisation de l’API des cubes.

Pour les propriétés multilingues, les données remontent dans la langue de l’utilisateur OData connecté.

Synthèse

Trois endpoints principaux peuvent être facilement testés avec un client Postman :

• POST : https://{serveur-xperience}/api/cubes

  • Où est précisé dans le body, le cube utilisé, les dimensions projetées, les éventuelles mesures et critères.  

  • Pour constituer ce body, s’aider du bouton Copier la requête API

  • En retour est fourni un id de traitement.  

• GET : https://{serveur-xperience}/api/cubes/status

  • Permet de connaître l’état de génération des rapports (id traitements): date de début/fin de traitement, taille du fichier généré, statuts…

  • Les rapports sont générés dans un répertoire temporaire qui est nettoyé de manière automatique tous les 15 jours pour éviter toute surcharge inutile d’espace disque.

• GET : https://{serveur-xperience}/api/cubes/result/{idTraitement}

  • Fournit les données JSON associées à l’id de traitement.

Des endpoints complémentaires existent et permettent de lister par exemple la liste des cubes disponibles, leurs dimensions, leur mesures.

• GET : https://{serveur-xperience}/api/cubes/customReports

• GET : https://{serveur-xperience}/api/cubes/customReports/{reportId}

  • Permet de récupérer la structure JSON (pour construire votre body) de tous vos rapports ou d’un rapport en particulier.

• GET : https://{serveur-xperience}/api/cubes

  • Permet de lister tous les cubes utilisables : nom + description.

• GET : https://{serveur-xperience}/api/cubes/{cubeId}/dimensions

  • Permet de lister toutes les dimensions d’un cube, c’est-à-dire toutes ses propriétés récupérables.

• GET : https://{serveur-xperience}/api/cubes/Analysis.userSkills/dimensions

  • Permet de récupérer toutes les dimensions récupérables à partir du cube Compétences utilisateurs.

• GET : https://{serveur-xperience}/api/cubes/{cubeId}/measures

  • Permet de réaliser la même chose sur les measures (valeurs).