Introduction
Ce document décrit le fonctionnement de l’API « data-search » permettant de rechercher et de récupérer les aggregates d’une base de données DAZZM.
Note sur les exemples
Les exemples dans ce document utilisent le modèle d’un CRM. Ce CRM permet la gestion d’achat/vente de produits électroniques, et comporte les agrégats suivants :
Compte : représentant les clients et contacts
Produit : représentant les produits offerts à l’achat/vente
Opportunité : représentant les différentes interactions entres les clients et les produits
Requêtes et réponses
Structure d’une requête avec fetch
Voici un exemple de requête simple qui montre la liste de produits (Produit) ou le nom est égal à “Lenovo756” :
fetch('https://votre_environement.api.octopus-esm.com/prod/data-search', {
method: 'POST',
headers: {
'Content-Type': 'application/json;charset=UTF-8',
'api-key': 'votre_token'
},
body: JSON.stringify({
query: {
typename: 'Produit',
criteria: [
{
nom: {
equal: 'Lenovo756'
}
}
]
}
})
})
.then(response => response.json())
.then(body => console.log(body))
.catch(error => console.error(error));
.png)
Une query nécessite 2 éléments, un ‘typename’, qui représente le nom de l`agrégat et un ‘criteria’ qui représente le critère de recherche.
Note 1 : Utiliser un critère vide retournera tous les résultats possibles pour cette requête.
Note 2 : Afin de pouvoir faire un appel d'API externe, vous devez obtenir un jeton d'API, configuré dans votre application.
Structure de la réponse du serveur
Remarquez que la valeur de retour est au format JSON et est toujours une collection d'éléments (data) ainsi que le nombre total d'éléments (totalCount).
{
"data": [
{
"prixAchat": 449.99,
"_version": 1,
"prixUnitaire": 599.99,
"_typename": "Produit",
"nom": "Lenovo756",
"fournisseur": {
"id": "58d8d274-0df2-4466-84aa-b3d4b730bdd8"
},
"id": "b816b7b3-490f-4ca3-b7b2-87327d925b52"
}
],
"totalCount": 1
}Opérateurs de comparaison
Nous nous appuyons sur MongoDb pour élaborer nos opérateurs. La section suivante, qui spécifie les opérateurs utilisés, comportera une indication de la relation avec MongoDb dans la colonne (Conforme à MongoDB).
equal [Conforme à MongoDB ($eq)]
Spécifie une condition d'égalité. L'opérateur equal correspond aux documents dans lesquels la valeur d'un champ est égale à la valeur spécifiée.
Exemple 1 : Trouver le produit ayant le nom “Lenovo756”.
{
"nom": {
"equal": "Lenovo756"
}
}Exemple 2 : Trouver les produits sans prix unitaire.
{
"prixUnitaire": {
"equal": null
}
} Exemple 3 : Trouver les produits d’un fournisseur spécifique (le fournisseur avec l’id 58d8d274-0df2-4466-84aa-b3d4b730bdd8).
{
"fournisseur": {
"equal": {
"id": "58d8d274-0df2-4466-84aa-b3d4b730bdd8"
}
}
} notEqual : [Conforme à MongoDB ($ne)]
L’opérateur notEqual sélectionne les documents dans lesquels la valeur du champ spécifié n'est pas égale à la valeur spécifiée. Cela inclut les documents qui ne contiennent pas le champ spécifié.
Exemple : Trouver les produits qui ne sont pas fournis par Sony dont l’id est 58d8d274-0df2-4466-84aa-b3d4b730bdd8.
{
"fournisseur": {
"notEqual": {
"id": "58d8d274-0df2-4466-84aa-b3d4b730bdd8"
}
}
} Exemple 2 : Trouver les produits ayant un prix unitaire.
{
"prixUnitaire": {
"notEqual": null
}
} insensitiveEqual : [Critère natif à DAZZM]
L'opérateur insensitiveEqual correspond aux documents dans lesquels la valeur d'un champ est égale à la valeur spécifiée, sans importance donnée aux lettres accentuées.
Exemple : Trouver le produit ayant le nom “lenovo”.
{
"nom": {
"insensitiveEqual": "lenovo756"
}
} Note : Nous avons un produit “Lenovo756” dans la base de données, avec cet opérateur, ce produit apparaitra dans les résultats.
in : [Conforme à MongoDB ($in)]
L'opérateur in sélectionne les documents dans lesquels la valeur d'un champ est égale à l'une quelconque des valeurs spécifiées dans le tableau.
Exemple : Trouver les produits fournis par Sony (fournisseur dont le id est : 58d8d274-0df2-4466-84aa-b3d4b730bdd8), ainsi que les produits fournis par Microsoft (fournisseur dont le id est : 038c6b5f-3b4a-412d-a693-4424540d3e95).
{
"fournisseur": {
"in": [
{
"id": "58d8d274-0df2-4466-84aa-b3d4b730bdd8"
},
{
"id": "038c6b5f-3b4a-412d-a693-4424540d3e95"
}
]
}
} notIn : [Conforme à MongoDB ($nin)]
notIn sélectionne les documents dans lesquels la valeur du champ spécifié n'est pas dans le tableau spécifié, ou le champ spécifié n'existe pas.
Exemple : Trouver les produits qui ne sont fournis ni par Sony (fournisseur dont le id est : 58d8d274-0df2-4466-84aa-b3d4b730bdd8), ni par Microsoft (fournisseur dont le id est : 038c6b5f-3b4a-412d-a693-4424540d3e95).
{
"fournisseur": {
"notIn": [
{
"id": "58d8d274-0df2-4466-84aa-b3d4b730bdd8"
},
{
"id": "038c6b5f-3b4a-412d-a693-4424540d3e95"
}
]
}
} beginsWith : [Critère natif à DAZZM]
L’opérateur beginsWith correspond aux documents dont la valeur du champ spécifié commence par une chaîne de caractères spécifiés.
Exemple : Nos produits contiennent plusieurs versions de Lenovo, si on veut trouver tous les produits Lenovo peu importe leurs versions, on peut utiliser Begins with Lenovo:
{
"nom": {
"beginsWith": "Lenovo"
}
} contains : [Critère natif à DAZZM]
L’opérateur contains correspond aux documents qui contiennent le mot spécifié dans un champ donné.
Exemple 1 : Trouver l’ensemble des produits de la gamme 5000 parmi la liste des produits.
{
"nom": {
"contains": "5000"
}
} Exemple 2 : Trouver l’ensemble des Téléphones parmi la liste des produits (en cherchant phone).
{
"nom": {
"contains": "phone"
}
} containsWords : [Critère natif à DAZZM]
L’opérateur containsWords correspond aux documents qui ont un champ spécifié contenant plusieurs mots (séparés par des espaces).
Exemple : Trouver la liste des fournisseurs se situant sur la rue pont.
{
"typename": "Compte",
"criteria": [
{
"adresse": {
"containsWords": "pont"
}
}
]
}
Cet opérateur offre également la possibilité de rechercher sur plusieurs champs contenant un mot spécifique.
Exemple : On souhaite trouver tous les utilisateurs portant le nom John comme prénom ou nom de famille.
{
"firstName, lastName": {
"containsWords": "John"
}
} lessThan : [Conforme à MongoDB ($lt)]
lessThan sélectionne les documents dans lesquels la valeur du champ est inférieure à (c'est-à-dire <) la valeur spécifiée.
Exemple : Trouver tous les produits qui ont un prix unitaire inférieur à 500$.
{
"prixUnitaire": {
"lessThan": 500
}
} lessOrEqualThan : [Conforme à MongoDB ($lte)]
lessOrEqualThan sélectionne les documents dans lesquels la valeur du champ est inférieure ou égale à (c'est-à-dire <=) la valeur spécifiée.
Exemple : Trouver tous les produits qui ont un prix unitaire inférieur ou égal à 500$.
{
"prixUnitaire": {
"lessOrEqualThan": 500
}
} greaterThan : [Conforme à MongoDB ($gt)]
greaterThan sélectionne les documents dans lesquels la valeur du champ spécifié est supérieure à (c'est-à-dire >) la valeur spécifiée.
Exemple : Trouver tous les produits qui ont un prix unitaire supérieur à 500$.
{
"prixUnitaire": {
"greaterThan": 500
}
} greaterOrEqualThan : [Conforme à MongoDB ($gte)]
greaterOrEqualThan sélectionne les documents dans lesquels la valeur du champ spécifié est supérieure ou égale à (c'est-à-dire >=) une valeur spécifiée (par exemple, une valeur).
Exemple : Trouver tous les produits qui ont un prix unitaire supérieur ou égal à 500$.
{
"prixUnitaire": {
"greaterOrEqualThan": 500
}
} dateRangeExpression : [Critère natif à DAZZM]
Sélectionne les documents dans lesquels la valeur du champ de type UTCDate se trouve dans la plage de temps spécifié à l'aide des opérateurs suivants :
UTCDateRange.Yesterday
UTCDateRange.Tomorrow
UTCDateRange.ThisWeek
UTCDateRange.LastWeek
UTCDateRange.NextWeek
UTCDateRange.ThisMonth
UTCDateRange.LastMonth
UTCDateRange.NextMonth
UTCDateRange.ThisYear
UTCDateRange.LastYear
UTCDateRange.NextYear
UTCDateRange.between(from, to)
UTCDateRange.notBetween(from, to)
UTCDateRange.range(from, 'day'|'week'|'month'|'year')
UTCDateRange.last(number, 'day'|'week'|'month'|'year')
UTCDateRange.next(number, 'day'|'week'|'month'|'year')
UTCDateRange.earlierThan(number, 'day'|'week'|'month'|'year')
UTCDateRange.laterThan(number, 'day'|'week'|'month'|'year')Exemple (between) : Trouver la liste des opportunités que leur date de fermeture estimée est entre le 01/12/2023 et le 31/12/2023.
{
"dateDeFermetureEstimée": {
"dateRangeExpression": "UTCDateRange.between('2023-12-01T00:00:00.000Z', '2023-12-31T00:00:00.000Z')"
}
} Exemple (yesterday) : Trouver la liste des opportunités que leur date de fermeture estimée est hier.
{
"dateDeFermetureEstimée": {
"dateRangeExpression": "UTCDateRange.Yesterday"
}
} Exemple (laterThan) : Trouver la liste des opportunités que leur date de fermeture estimée est dans une semaine de la date d’aujourd’hui.
{
"dateDeFermetureEstimée": {
"dateRangeExpression": "UTCDateRange.laterThan(1, 'week')"
}
} dateTimeRangeExpression : [Critère natif à DAZZM]
Sélectionne les documents dans lesquels la valeur du champ de type DateTime se trouve dans la plage de temps spécifié à l'aide des opérateurs suivants :
DateTimeRange.ThisMinute
DateTimeRange.LastMinute
DateTimeRange.NextMinute
DateTimeRange.ThisHour
DateTimeRange.LastHour
DateTimeRange.NextHour
DateTimeRange.Today
DateTimeRange.Yesterday
DateTimeRange.Tomorrow
DateTimeRange.ThisWeek
DateTimeRange.LastWeek
DateTimeRange.NextWeek
DateTimeRange.ThisMonth
DateTimeRange.LastMonth
DateTimeRange.NextMonth
DateTimeRange.ThisYear
DateTimeRange.LastYear
DateTimeRange.NextYear
DateTimeRange.between(from, to)
DateTimeRange.notBetween(from, to)
DateTimeRange.range(from, 'day'|'week'|'month'|'year')
DateTimeRange.last(number, 'day'|'week'|'month'|'year')
DateTimeRange.next(number, 'day'|'week'|'month'|'year')
DateTimeRange.earlierThan(number, 'day'|'week'|'month'|'year')
DateTimeRange.laterThan(number, 'day'|'week'|'month'|'year')
Exemple (between) : Trouver la liste des opportunités que leur date de fermeture est entre le 01/12/2023 et le 31/12/2023.
{
"dateDeFermeture": {
"dateTimeRangeExpression": "DateTimeRange.between('2023-12-01T00:00:00.000-05:00', '2023-12-31T00:00:00.000-05:00')"
}
} Exemple (yesterday) : Trouver la liste des opportunités que leur date de fermeture est hier.
{
"dateDeFermeture": {
"dateTimeRangeExpression": "DateTimeRange.Yesterday"
}
} Exemple (laterThan) : Trouver la liste des opportunités que leur date de fermeture dans une semaine de la date d’aujourd’hui.
{
"dateDeFermeture": {
"dateTimeRangeExpression": "DateTimeRange.laterThan(1, 'week')"
}
} itemMatch : [Conforme à MongoDB ($elementMatch)]
L'opérateur itemMatch correspond aux documents qui contiennent un champ tableau avec au moins un élément qui satisfait tous les critères de requête spécifiés.
Exemple
En se référant au schéma exemple mentionné dans ce document, il est indiqué qu'un Compte (agrégat) peut avoir plusieurs contacts (collections d'entités). Si l'on souhaite trouver le compte ayant un contact répondant à deux critères :
le contact a le genre "MASCULIN"
le titre du contact est égal à 'Vendeur'.
Attention : L'utilisation de l'opérateur AND dans la requête ne donnera pas le résultat souhaité.
En effet, la requête suivante :
{
"contacts": {
"genre": "MASCULIN",
"titre": "Vendeur"
}
} sera convertie comme suit :
{
"$and": [
{
"contacts.genre": {"$eq": "MASCULIN"}
},
{
"contacts.titre": {"$eq": "Vendeur"}
}
]
}Cela peut être interprété verbalement comme suit : "Trouve le compte qui a un contact de genre MASCULIN et n'importe quel autre contact qui a le titre 'Vendeur'", ce qui ne répond pas à notre besoin.
C'est ici qu'il devient important, voire obligatoire, d'utiliser itemMatch. Cet opérateur garantit la validation des critères définis par les requêtes sur le même élément, c'est-à-dire le même contact. Ainsi, notre requête devient :
{
"contacts":{
"itemMatch": {
"genre": {"equal": "MASCULIN"},
"titre": {"equal": "Vendeur"}
}
}
}Par conséquent, cette requête permet d'obtenir le compte qui a un contact de genre MASCULIN et pour lequel ce même contact a le titre 'Vendeur'.
Opérateurs logiques
Opérateur AND
AND effectue une opération logique ET sur un tableau d'une ou plusieurs expressions (<expression1>, <expression2>, et ainsi de suite) et sélectionne les documents qui satisfont toutes les expressions.
Afin de faire une opération de type AND, les expressions doivent se trouver dans le même Objet, séparés par des virgules.
Exemple : Trouver les produits fournis par Sony dont le ID est 58d8d274-0df2-4466-84aa-b3d4b730bdd8 et qui ont un prix unitaire inférieur à 500$.
{
"typename": "Produit",
"criteria": [
{
"fournisseur": {
"equal": {
"id": "58d8d274-0df2-4466-84aa-b3d4b730bdd8"
}
},
"prixUnitaire": {
"lessThan": 500
}
}
]
}Operateur OR
L'opérateur OR effectue une opération logique OU sur un tableau d'une ou plusieurs <expressions> et sélectionne les documents qui satisfont au moins l'une des <expressions>.
Afin de faire une opération de type OR, les expressions doivent se trouver dans des Objets séparés.
Exemple : Trouver les produits fournis par Sony dont le id est 58d8d274-0df2-4466-84aa-b3d4b730bdd8 OU qui ont un prix unitaire supérieur à 500$.
{
"typename": "Produit",
"criteria": [
{
"fournisseur": {
"equal": {
"id": "58d8d274-0df2-4466-84aa-b3d4b730bdd8"
}
}
},
{
"prixUnitaire": {
"greaterThan": 500
}
}
]
} Tri, limites et pagination
Trier sur un ou plusieurs champs
Il est possible de faire un tri sur un ou plusieurs champs en utilisant l’opérateur orderBy.
Exemple 1 : Trier la liste des produits par ordre ascendant des noms des produits.
{
"typename": "Produit",
"criteria": [],
"orderBy": {
"nom": "asc"
}
} Exemple 2 : Trier la liste des produits par ordre ascendant des noms des produits et par ordre descendant des prix unitaire.
{
"typename": "Produit",
"criteria": [],
"orderBy": {
"nom": "asc",
"prixUnitaire": "desc"
}
} Remarque : Les produits vont être d’abord trier par nom (ascendant) ensuite par prix unitaire (descendant), c’est à dire que l’ordre des champs spécifié est important.
Changer la limite des éléments obtenus
Si on veut obtenir seulement 10 produits de la liste, on peut le faire en ajoutant first à la requête comme suit :
Exemple : obtenir les 10 premiers produits de la liste.
{
"typename": "Produit",
"criteria": [],
"first": 10
} Exemple : Obtenir les 10 prochains produits en utilisant « offset »:
{
"typename": "Produit",
"criteria": [],
"offset": 10,
"first": 10,
} Éléments imbriqués
On peut faire des requêtes sur des entités imbriqués à l’intérieur de nos agrégats.
Example : Trouver les listes des Compte (Agreggate) qui ont des contacts (entité) de genre masculin.
{
"typename": "Compte",
"criteria": [
{
"contacts": {
"genre": {
"equal": "MASCULIN"
}
}
}
]
}Utilisation des requêtes au travers la plateforme DAZZM
Cette section démontre brièvement comment la même api « data-search » peut être exploité lors de la création d’applications avec la plateforme DAZZM.
Utilisation avec le SDK
Le SDK intégré dans l’outil low code donne accès à un objet « db ». La méthode « search » de cette méthode utilise une syntaxe identique à celle décrite dans ce document.
Exemple : recherche avec « db.search » :
db.search({
typename: 'Produit',
criteria: [
{
nom: {
equal: 'Lenovo756'
}
}
]
});Utilisation avec les outils visuels
L’expérience sans code DAZZM permet de créer de requêtes avec un outil visuel. Cet outil visuel utilise lui aussi le même API sous-jacent et agit comme une simple interface graphique de conception de requêtes.
Exemple : Utilisation avec les outils visuels