Composer une requête à l’API d’Online ERP

Préface

Cet article est applicable seulement pour les requêtes GET sur les endpoints /Entity/MonEntité

Il est possible d’ajuster les requêtes d’extraction via des modificateurs pour :

• réduire le nombre de champs retournés
• filtré selon la valeur d’un champ
• trié selon un champ
• etc. ..

Query – $select

L’élément $select vous permet de limiter les champs que l’API va vous retourner. Il est possible de choisir plusieurs champs, ils doivent être séparés par un caractère virgule ( , ) 

Exemple :

/entity/Customer?$select=NoClient,NomClient

Ainsi, le payload va se limiter qu’à ces 2 champs, ce qui réduit considérablement les délais et coûts potentiels de votre requête!

Chaque champ sélectionné doit être séparé par une virgule.

Sous-entité: Il est possible aussi de faire le même concept avec un sous-champ.

Exemple :
Pour retourner que le champ MontantDu_Cycle1_Courant, nous pourrions donc écrire ceci :

/entity/Customer?$select=InfoAgeDesComptes.MontantDu_Cycle1_Courant

le client retournerait ceci: { Exemple JSON qui passe pas }

Il en va de même pour un tableau (par exemple, dans les comptes GL).

Query – $filter

L’élément $filter vous permet de limiter le nombre d’éléments retournés par l’API.

Exemple :

/entity/Customer?$filter=NomClient eq ‘Les entreprises de Jacques’.

L’exemple précédent vous retournera une liste de tous les clients où le nom est strictement égal à « Les entreprises de Jacques ». Si aucun client ne possède ce nom, alors une liste vide sera retournée.

Tout comme la sélection d’une sous-entitée, il est possible de filtrer pour un sous-champ.

Exemple :

/Entity/Product?$filter=GroupeProduit.CodeGroupe eq ‘vêtements’

Il est possible d’enchaîner plusieurs filtres de suite en utilisant le sous opérateur and :

Exemple :

/Entity/Product?$filter=GroupeProduit.CodeGroupe eq ‘vêtements’ and PrixFinal gt 5.75

Opérateurs disponibles

• EQUALS
  • correspond à « strictement égal »
  • alternativement : EQ
• NOTEQUALs
  • Correspond à « strictement inégal »
  • alternativement : NE
• GREATERTHAN
  • Correspond à « strictement supérieur »
  • alternativement : GT
• GREATERTHANEQUALS
  • Correspond à « supérieur ou égal »
  • alternativement : GE
• LESSTHAN
  • Correspond à « strictement inférieur »
  • alternativement : LT
• LESSTHANEQUALS
  • Correspond à « inférieur ou égal »
  • alternativement : LE
• CONTAINS
  • la valeur du champ doit contenir la séquence définie par l’utilisateur
  • Disponible uniquement pour les champs textes
• DOESNTCONTAINS
  • la valeur du champ doit exclure la séquence définie par l’utilisateur
  • Disponible uniquement pour les champs textes

Syntaxe des filtres

La valeur des champs numériques, aussi bien entiers que décimaux, doit contenir uniquement des chiffres et conditionnellement un point ( . ), qui sert ici de séparateur de la partie décimale.

Exemple :

/entity/Product?$filter=PrixFinal eq 12.75

Ici, on recevrait tous les produits dont le prix final doit être égal à 12.75.

La valeur des champs textes (string) et de type date doit être entourée d’une paire d’apostrophes ( ‘ ).

Le format des dates est le suivant : yyyy-MM-dd (année-mois-jour).

Exemple :
/entity/Customer?$filter=Fiche_DerniereModification gt ‘2024-02-10’

Ici, on recevrait tous les clients dont la date de dernière modification doit être supérieure au 10 février 2024.

On peut combiner plusieurs filtre en ajout des bloc séparateur and

Exemple :

/entity/Customer?$filter=Fiche_DerniereModification gt ‘2024-02-10’ and Pays eq ‘Canada’

Ici, on recevrait tous les clients dont leur date de dernière modification doit être supérieure au 10 février 2024 et dont leur pays est le Canada.

Query – $orderby

L’élément $orderby permet de définir par quel champ la liste de retour doit être triée de façon ascendante ou descendante.

Il est possible de définir l’ordre de tri en ajoutant un élément modificateur : ASC ou DESC, correspondant respectivement à un tri ascendant ou descendant. Si l’élément modificateur est omis, un tri ascendant sera appliqué par défaut par l’API.

Exemple :
/entity/Customer?$orderby=NoClient ASC

Ici, on obtiendrait une liste des clients triée par ordre alphabétique ascendant.

 

Query – $top et $skip

Les éléments $top et $skip définissent respectivement le nombre d’éléments maximal à retourner et le nombre d’éléments à sauter de la liste à retourner.

Vous pourriez obtenir plus de détails sur l’utilisation de ces opérateurs dans notre article sur la pagination

Query – $Expand

Cet élément est utilisé pour indiquer si un sous-champ de type tableau doit être inclus dans le résultat.

Exemple :
/Entity/GLProject?&$expand=Budget01

Ici, le retour des projets GL d’Acomba devra inclure le tableau Budget01 pour chaque élément de la liste de retours.

 

Composer une requête complexe

Il est possible de combiner plusieurs éléments en une seule requête pour obtenir un résultat plus précis pour votre extraction de données.

Syntaxe à respecter

Le premier élément de la requête doit être obligatoirement précédé d’un caractère point d’interrogation ( ? )

Exemple :
/entity/Customer?$orderby=NoClient ASC

Chaque élément supplémentaire doit être précédé par un caractère esperluette ( & ). À notez que les blocs d’éléments ne sont pas séparés par un caractère.

Exemple :

1. /entity/Customer?$orderby=NoClient ASC&$filter=NoClient eq ’01’
2. /entity/Customer?$orderby=NoClient ASC&$filter=NoClient eq ’01’&top=10