Différences

Ci-dessous, les différences entre deux révisions de la page.

--- serveurscrutari:json:commun [2011/03/03 12:00] – créée vincent
+++ serveurscrutari:json:commun [2017/09/28 15:25] (Version actuelle) – [Paramètres communs] vincent
@@ Ligne 1: / Ligne 1: @@
 ====== Paramètres communs ======
-Les paramètres communs sont les paramètres utilisés par les différents types de requêtes JSON et dont la définition est identique quelque soit la requête. Tous les paramètres communs ne sont pas utilisés dans une même requête (par exemple, le paramètre //q// n'est pas utilisé dans la requête ////type=base//).
+Les paramètres communs sont les paramètres utilisés par les différents types de requêtes JSON et dont la définition est identique quelque soit la requête. Tous les paramètres communs ne sont pas utilisés dans une même requête (par exemple, le paramètre //q// n'est pas utilisé dans la requête //type=base//).
   * //q// : chaîne de caractères indiquant la séquence de recherche à effectuer
-  * //langui// : langue d'interface, c'est la langue à utiliser de préférence pour les contenus potentiellement multilingues, par exemple les intitulés des bases, des corpus, etc.
+  * //wildchar// : peut prendre les valeurs //end// (valeur par défaut), //start//, //both// ou //none// : indique qu'un astérisque (*) doit être rajouté automatiquement en fin, en début, aux deux bouts ou pas du tout pour les termes simples (qui ne sont pas entre guillemets et hors recherche avancée)
+  * //lang// : langue d'interface, c'est la langue à utiliser de préférence pour les contenus potentiellement multilingues, par exemple les intitulés des bases, des corpus, etc.
+  * //baselist// : une liste de bases (voir ci-dessous)
+  * //corpuslist// : une liste de corpus (voir ci-dessous)
+  * //start// : point de départ des résultats, à utiliser en conjonction avec //limit// pour définir une plage de résultats ; la valeur -1 indique l'absence de point de départ ; c'est la valeur par défaut si le paramètre est absent ; équivalent à la valeur 1 (point de départ à partir du premier résultat)
   * //limit// : limite donnée au nombre de résultats renvoyés (par exemple, le nombre de fiches trouvés par une recherche) ; la valeur -1 indique l'absence de limite ; c'est la valeur par défaut utilisée si ce paramètre est absent
+  * //fichefields// : définition des champs de données des fiches qui se retrouveront dans les objets décrivant ces fiches, ce paramètre est détaillé précisément dans [[serveurscrutari:json:fiche_fields|Champs des fiches]]
+  * //motclefields// : définition des champs de données des mots-clés qui se retrouveront dans les objets décrivant ces mots-clés, ce paramètre est détaillé précisément dans [[serveurscrutari:json:motcle_fields|Champs des mots-clés]]
+  * //warnings// : si la valeur est 1, les avertissements éventuels sont inclus à la fin du résultat de la requête (voir [[serveurscrutari:json:warnings|Messages d'avertissements]]), ce paramètre est optionnel et utilisable dans toutes les requêtes à des fins de débogage
+  * //version// : version de l'API à utiliser, l'API est la plus stable possible mais des modifications peuvent apparaitre ; l'API documentée est toujours la dernière ; il n'y a pas de numéro de version globale de l'API mais des différences pour chaque sortie JSON (pour des raisons de compatibilité, son absence est tolérée et correspond à la version 0)
+===== Syntaxe des listes de contenus ScrutariData =====
+Un certains nombres de paramètres communs ou spécifiques portent sur des listes de contenus ScrutariData : liste de corpus, de bases, de thésaurus, de mots-clés ou de mots-clés. Sauf cas particulier du filtre d'indexation, ces paramètres ont une syntaxe identique qui est la suivante :
+  * 1) quand une liste contient plusieurs éléments, le séparateur est la virgule
+  * 2) On peut désigner un contenu de trois formes différentes :
+    * par le code qui est un entier strictement positif : rappelons que le code n'est pas pérenne sauf dans le cas des [[serveurscrutari:config:uricodes|codes préétablis]], c'est donc une formulation très courte qui sera privilégiée pour les échanges avec le serveur au cours d'une session
+    * par l'URI du contenu, c'est la forme pérenne qui par exemple sera utilisée pour conserver le paramétrage d'une session à une autre de l'application cliente ; comme les listes concernent un type de contenu particulier (liste de corpus, liste de bases, etc.), on peut supprimer de l'URI la première partie qui identifie le type (par exemple, pour une liste de bases, on pourra écrire ///e17a05b0-c45e-11d8-9669-0800200c9a66/gouvafrique// plutôt que //base:/e17a05b0-c45e-11d8-9669-0800200c9a66/gouvafrique//
+    * par une forme mixte entre code et URI relatif à utiliser en particulier avec les codes préétablis (voir ci-dessous)
+  * 3) on peut dans une même liste mixer les trois formes du point 2)
+==== Forme mixte entre code et URI ====
+L'idée de cette forme mixte est de profiter des codes [[serveurscrutari:config:uricodes|codes préétablis]] utilisés pour des bases, des corpus et des thésaurus pour raccourcir les URI des « descendants » du contenu en question (corpus et thésaurus pour une base, fiches pour un corpus, mots-clés pour un thésaurus). Cette forme mixte commence par un code auquel est accolé l'URI relatif.
+Prenons un exemple : soit une base dont l'URI est //base:/e17a05b0-c45e-11d8-9669-0800200c9a66/gouvafrique// et dont le code est //3//, le corpus //organisme// dont l'URI est donc //corpus:/e17a05b0-c45e-11d8-9669-0800200c9a66/gouvafrique/organisme// pourra s'écrire //3/organisme//.
+On notera que cette forme mixte ne fonctionne que parce que les paramètres de liste sont toujours d'un type particulier. Dans l'absolu, on ne sait pas si //3/organisme// désigne un corpus ou un thésaurus.
+On voit également que cette forme mixte est à privilégier avec les codes préétablis car sur la durée un même code peut très bien se trouver à désigner un corpus, une fiche, un mot-clé, un thésaurus ou une base suivant l'ordre d'initialisation des fichiers ScrutariData.
+Ces précautions d'usage étant faites, cette forme mixte permet se simplifier grandement une application qui interrogerait une base bien précise. Il suffit de fixer une fois pour toute que le code //1// est attribué à la base en question pour ne plus avoir à se préoccuper de la forme avec nom de l'autorité et nom de la base.