OData pagination avec l'API

La notion de pagination est fondamentale, il est important de savoir que l’API Sage 100 renvoie à chaque demande un maximum de 100 enregistrements.

Pourquoi limiter à 100 enregistrements ?

Les données requêtées par l’API Sage 100 vont transiter entre le serveur local Sage 100 et Microsoft 365. Si une table de votre base de données contient des milliers d’enregistrements, vous ne pouvez pas les envoyer en une seule demande à la fois pour des raisons de volumétrie et de sécurité.
Pour éviter ce problème, le serveur peut limiter le nombre d’enregistrements qu’il envoie à chaque demande.
Pour l’API Sage 100 cette limite a été fixée à 100.

Notion de pagination

Utilisation de $count et $skip

Pour gérer la pagination vous devez connaître le nombre total d’enregistrements répondant aux critères de filtre de votre requête et le nombre d’enregistrements renvoyés à chaque appel afin de définir le nombre d’enregistrements à sauter en utilisant $skip.

• Le paramètre $count doit être affecté à true pour pouvoir récupérer le nombre d’enregistrements répondant aux critères de filtre.
  Il faudra alors récupérer la valeur via '@odata.count'.
  
• Le paramètre $skip permet de mentionner le nombre d’enregistrements à sauter qui ne seront par conséquent pas inclus dans le résultat.

Set(currentCompanyId;"{datasetId}");;
 Sage100cloud.ComptesGetByDatasetid(
      currentCompanyId;
      {
        '$filter': "startswith(numero,'6') and type eq 'Detail'";
        '$top': 0;
        '$count': true
      }   
  ).'@odata.count';;

Maintenant que nous connaissons le total d’enregistrements ('@odata.count') et le nombre d’enregistrements (par défaut 100), nous pouvons gérer la pagination.
Il suffira d’incrémenter à chaque appel $skip avec le nombre total d’enregistrements déjà lus.

Recommandations

Dossier de tests avec suffisamment de données

Nous vous recommandons d’utiliser un dossier avec suffisamment de données pour ne pas être piégés si pour certaines requêtes le seuil des 100 enregistrements n’est pas atteint.
Par exemple, si vous testez avec la société BIJOU de démonstration Sage 100, comme ce dossier a un nombre de clients, de devis, de factures inférieur à 100, vous pourriez croire, si vous avez omis de gérer la pagination, que votre développement est correct.
Mais une fois mise en production, votre application utilisée avec un dossier contenant des données réelles avec plus de 100 clients, ou devis ou factures, empêcherait l’utilisateur d’accéder aux données au delà des 100 premiers enregistrements.

Ou simuler la limite à moins de 100 enregistrements

Une astuce consiste aussi à définir un paramètre global nommé par exemple maxPaginate avec une valeur inférieure au nombre d’enregistrements moyens de votre dossier de tests.
Par exemple vous pouvez affecter maxPaginate avec la valeur 10. Puis lors de vos requêtes, affectez toujours le paramètre $top avec maxPaginate, ainsi vos requêtes ne renverront que le nombre maximal mentionné dans maxPaginate.
Vous serez alors plus rapidement alertés lors de la conception de votre application que vous devez gérer la pagination pour permettre à l’utilisateur d’accéder à l’ensemble des données et non à une vue tronquée des données.
Une fois la pagination testée et votre développement opérationnel, vous pourrez affecter maxPaginate avec la valeur 100 et votre développement continuera à fonctionner.

Set (maxPaginate;10);;  // Valeur max du $top pour les tests
Set (cptPage;0);;       // Compteur de pages pour affecter $skip

...

Set(currentCompanyId;"{datasetId}");;
 Sage100cloud.ComptesGetByDatasetid(
      currentCompanyId;
      {
        '$expand': Blank();
        '$select': "intitule,numero";
        '$filter': Blank();
        '$orderby':"numero";
        '$top': maxPaginate;
        '$skip': cptPage*maxPaginate;
        '$count': Blank()
      }   
  ).value;;

Boucler sur la pagination pour récupérer tous les enregistrements

Pour certains usages, il peut être nécessaire de récupérer la totalité des enregistrements.
Ce peut être le cas lorsque l’on sait que le nombre total d’enregistrements restera faible mais néanmoins risque de dépasser 100.
A l’exemple des familles de produits que l’on souhaiterait choisir dans une liste déroulante, s’il y a 130 familles il faut que ces 130 familles apparaissent dans la liste de choix.

En appliquant la logique de pagination, il est possible de boucler pour récupérer la totalité des enregistrements.

L’exemple Power Apps ci-dessous montre :

• comment récupérer la totalité des familles de produit dans une collection familles,
• la collection contiendra aussi en premier une valeur <Tous> pour permettre ce choix lors de l’utilisation dans une liste déroulante.
• comme il n’existe pas de for i dans Power Apps mais un ForAll qui boucle sur les enregistrements d’une collection, on simule une collection où chaque enregistrement est un | avec un nombre de | égal au nombre de pages à récupérer,
• on fait un premier appel à la requête des familles avec $count à true afin de récupérer le nombre d’enregistrements via @odata.count, dans cet appel on a forcé $top à 0 puisqu’on ne souhaite pas récupérer les enregistrements mais juste le total, inutile donc que le serveur renvoie des données autre que ce total,
• bien sûr pour récupérer ce nombre d’enregistrements, on applique via $filter le même filtre que celui qui sera mentionné pour récupérer les lignes, ici le filtre sur les familles dont la valeur de la propriété type est égale à Detail.
• dans la boucle ForAll, on incrémente $skip avec le nombre de familles déjà récupérées dans la collection : 0 puis 100 puis 200, etc,
• à noter qu’on ne tient pas compte de l’enregistrement <Tous> dans le calcul de la pagination, d’où la variable RowsInit qui contient le nombre initial d’enregistrements de la collection familles, ici 1 pour l’enregistrement <Tous> , et le calcul de $skip qui déduit cet enregistrement : CountRows(familles) - RowsInit,
• dans l’exemple on utilise un AddColumns pour ajouter une nouvelle colonne dans la collection Familles qui n’existe pas en tant que propriété dans la ressource Familles de l’API. Ici la colonne intituleComplet est créée à partir de la valeur de la propriété intitulé suivie de la valeur de la propriété code entre parenthèses.

//utilisé itérer au prorata du nombre de pages de familles
Set(colIterate;"||||||||||||||||||||||||||||||||||||");;  
 //Nombre maxi d'enregistrements renvoyés par l'API
Set(apiPagesize;100);;

//Initialisation collection familles
ClearCollect(familles;{code:"";intitule:""});;Clear(familles);;
 // Ajout en premier du choix <Tous>  
ClearCollect(familles;{code:"<Tous>";intitule:"<Tous>"});;      
With (
  {
    // Nb de pages = @odata.count / apiPagesize
    MaxIterate:RoundUp(
         Sage100cloud.FamillesGetByDatasetid(currentCompanyId;{'$top':0;'$count':true;'$filter':"type eq 'Detail'"}).'@odata.count'/apiPagesize
         ;0);
    // Nb enregistrements collection famille avant ajout des données famille     
    RowsInit:CountRows(familles)
   };
   //On utilise les MaxIterate car. de la chaîne colIterate pour provoquer une boucle car pas de for i dans Power Apps.
   ForAll(
       Split(Left(colIterate;MaxIterate);"|");
       Collect(familles;AddColumns(Sage100cloud.FamillesGetByDatasetid(currentCompanyId;
               {
                 '$select':"intitule,code";
                 '$top':apiPagesize;
                 '$skip':CountRows(familles)-RowsInit;
                 '$filter':"type eq 'Detail'"
               }).value;
               "intituleComplet";intitule&" ("&code&")")
       )
   )
);;